refactor: extract CLI utilities (parseCliFlags, createLogger) to paths.mjs

Signed-off-by: leocavalcante <leo@cavalcante.dev>

Author: leocavalcante

postinstall.mjs

@@ -12,31 +12,26 @@ import { join } from "node:path"
 
 import {
 	AGENTS_TARGET_DIR,
+	createLogger,
 	getAgentsSourceDir,
 	getErrorMessage,
 	getPackageRoot,
+	parseCliFlags,
 	retryOnTransientError,
 	validateAgentContent,
 } from "./src/paths.mjs"
 
 const packageRoot = getPackageRoot(import.meta.url)
 const AGENTS_SOURCE_DIR = getAgentsSourceDir(packageRoot)
 
-/** Check for --dry-run flag in command line arguments */
-const DRY_RUN = process.argv.includes("--dry-run")
+/** Parse command line flags */
+const flags = parseCliFlags(process.argv)
+const DRY_RUN = flags.dryRun
+const VERBOSE = flags.verbose
 
-/** Check for --verbose flag in command line arguments */
-const VERBOSE = process.argv.includes("--verbose")
-
-/**
- * Logs verbose output if --verbose flag is set.
- * @param {string} message - The message to log
- */
-function verbose(message) {
-	if (VERBOSE) {
-		console.log(`[VERBOSE] ${message}`)
-	}
-}
+/** Create logger with verbose flag */
+const logger = createLogger(VERBOSE)
+const verbose = logger.verbose
 
 /**
  * Validates an agent file by reading and validating its content.

preuninstall.mjs

@@ -12,30 +12,25 @@ import { join } from "node:path"
 
 import {
 	AGENTS_TARGET_DIR,
+	createLogger,
 	getAgentsSourceDir,
 	getErrorMessage,
 	getPackageRoot,
+	parseCliFlags,
 	retryOnTransientError,
 } from "./src/paths.mjs"
 
 const packageRoot = getPackageRoot(import.meta.url)
 const AGENTS_SOURCE_DIR = getAgentsSourceDir(packageRoot)
 
-/** Check for --dry-run flag in command line arguments */
-const DRY_RUN = process.argv.includes("--dry-run")
+/** Parse command line flags */
+const flags = parseCliFlags(process.argv)
+const DRY_RUN = flags.dryRun
+const VERBOSE = flags.verbose
 
-/** Check for --verbose flag in command line arguments */
-const VERBOSE = process.argv.includes("--verbose")
-
-/**
- * Logs verbose output if --verbose flag is set.
- * @param {string} message - The message to log
- */
-function verbose(message) {
-	if (VERBOSE) {
-		console.log(`[VERBOSE] ${message}`)
-	}
-}
+/** Create logger with verbose flag */
+const logger = createLogger(VERBOSE)
+const verbose = logger.verbose
 
 /**
  * Main entry point for the preuninstall script.

src/paths.d.mts

@@ -116,3 +116,50 @@ export function validateAgentContent(content: string): ValidateAgentContentResul
  * @returns True if current version satisfies the required range
  */
 export function checkVersionCompatibility(required: string, current: string): boolean
+
+/**
+ * Parsed command line flags for install/uninstall scripts.
+ */
+export interface CliFlags {
+	/** Simulate the operation without making changes */
+	dryRun: boolean
+	/** Enable verbose logging output */
+	verbose: boolean
+	/** Display help information */
+	help: boolean
+}
+
+/**
+ * Parses command line flags for install/uninstall scripts.
+ *
+ * Recognizes the following flags:
+ * - `--dry-run`: Simulate the operation without making changes
+ * - `--verbose`: Enable verbose logging output
+ * - `--help`: Display help information
+ *
+ * @param argv - The command line arguments array (typically process.argv)
+ * @returns Parsed flags object
+ */
+export function parseCliFlags(argv: string[]): CliFlags
+
+/**
+ * Logger object with standard and verbose logging methods.
+ */
+export interface Logger {
+	/** Log a message to console */
+	log: (message: string) => void
+	/** Log a verbose message (only when verbose mode is enabled) */
+	verbose: (message: string) => void
+}
+
+/**
+ * Creates a logger object with standard and verbose logging methods.
+ *
+ * The logger provides two methods:
+ * - `log(message)`: Always logs to console.log
+ * - `verbose(message)`: Only logs when verbose mode is enabled, prefixed with [VERBOSE]
+ *
+ * @param verbose - Whether verbose logging is enabled
+ * @returns Logger object
+ */
+export function createLogger(verbose: boolean): Logger

src/paths.mjs

@@ -405,3 +405,66 @@ export function checkVersionCompatibility(required, current) {
 	if (!rangeVersion) return false
 	return compareVersions(currentVersion, rangeVersion) === 0
 }
+
+/**
+ * Parses command line flags for install/uninstall scripts.
+ *
+ * Recognizes the following flags:
+ * - `--dry-run`: Simulate the operation without making changes
+ * - `--verbose`: Enable verbose logging output
+ * - `--help`: Display help information
+ *
+ * @param {string[]} argv - The command line arguments array (typically process.argv)
+ * @returns {{ dryRun: boolean, verbose: boolean, help: boolean }} Parsed flags
+ *
+ * @example
+ * // Parse process.argv
+ * const flags = parseCliFlags(process.argv)
+ * if (flags.help) {
+ *   console.log("Usage: ...")
+ *   process.exit(0)
+ * }
+ *
+ * @example
+ * // Parse custom arguments
+ * const flags = parseCliFlags(["node", "script.js", "--verbose", "--dry-run"])
+ * // flags = { dryRun: true, verbose: true, help: false }
+ */
+export function parseCliFlags(argv) {
+	return {
+		dryRun: argv.includes("--dry-run"),
+		verbose: argv.includes("--verbose"),
+		help: argv.includes("--help"),
+	}
+}
+
+/**
+ * Creates a logger object with standard and verbose logging methods.
+ *
+ * The logger provides two methods:
+ * - `log(message)`: Always logs to console.log
+ * - `verbose(message)`: Only logs when verbose mode is enabled, prefixed with [VERBOSE]
+ *
+ * @param {boolean} verbose - Whether verbose logging is enabled
+ * @returns {{ log: (message: string) => void, verbose: (message: string) => void }} Logger object
+ *
+ * @example
+ * const logger = createLogger(true)
+ * logger.log("Installing agents...")     // Always prints
+ * logger.verbose("Source: /path/to/src") // Prints: [VERBOSE] Source: /path/to/src
+ *
+ * @example
+ * const logger = createLogger(false)
+ * logger.log("Installing agents...")     // Prints
+ * logger.verbose("Source: /path/to/src") // Does nothing (verbose disabled)
+ */
+export function createLogger(verbose) {
+	return {
+		log: (message) => console.log(message),
+		verbose: (message) => {
+			if (verbose) {
+				console.log(`[VERBOSE] ${message}`)
+			}
+		},
+	}
+}

tests/paths.test.ts

@@ -4,11 +4,13 @@ import { join } from "node:path"
 import {
 	AGENTS_TARGET_DIR,
 	checkVersionCompatibility,
+	createLogger,
 	getAgentsSourceDir,
 	getErrorMessage,
 	getPackageRoot,
 	isTransientError,
 	MIN_CONTENT_LENGTH,
+	parseCliFlags,
 	parseFrontmatter,
 	REQUIRED_FRONTMATTER_FIELDS,
 	REQUIRED_KEYWORDS,
@@ -760,4 +762,123 @@ This is a test agent that handles various tasks.
 			})
 		})
 	})
+
+	describe("parseCliFlags", () => {
+		it("should return all false flags for empty argv", () => {
+			const result = parseCliFlags([])
+			expect(result).toEqual({ dryRun: false, verbose: false, help: false })
+		})
+
+		it("should return all false flags for argv without flags", () => {
+			const result = parseCliFlags(["node", "script.js"])
+			expect(result).toEqual({ dryRun: false, verbose: false, help: false })
+		})
+
+		it("should detect --dry-run flag", () => {
+			const result = parseCliFlags(["node", "script.js", "--dry-run"])
+			expect(result.dryRun).toBe(true)
+			expect(result.verbose).toBe(false)
+			expect(result.help).toBe(false)
+		})
+
+		it("should detect --verbose flag", () => {
+			const result = parseCliFlags(["node", "script.js", "--verbose"])
+			expect(result.dryRun).toBe(false)
+			expect(result.verbose).toBe(true)
+			expect(result.help).toBe(false)
+		})
+
+		it("should detect --help flag", () => {
+			const result = parseCliFlags(["node", "script.js", "--help"])
+			expect(result.dryRun).toBe(false)
+			expect(result.verbose).toBe(false)
+			expect(result.help).toBe(true)
+		})
+
+		it("should detect multiple flags", () => {
+			const result = parseCliFlags(["node", "script.js", "--dry-run", "--verbose"])
+			expect(result.dryRun).toBe(true)
+			expect(result.verbose).toBe(true)
+			expect(result.help).toBe(false)
+		})
+
+		it("should detect all flags", () => {
+			const result = parseCliFlags(["node", "script.js", "--dry-run", "--verbose", "--help"])
+			expect(result).toEqual({ dryRun: true, verbose: true, help: true })
+		})
+
+		it("should ignore unknown flags", () => {
+			const result = parseCliFlags(["node", "script.js", "--unknown", "--other"])
+			expect(result).toEqual({ dryRun: false, verbose: false, help: false })
+		})
+
+		it("should handle flags in any position", () => {
+			const result = parseCliFlags(["--verbose", "node", "--dry-run", "script.js", "--help"])
+			expect(result).toEqual({ dryRun: true, verbose: true, help: true })
+		})
+
+		it("should not match partial flag names", () => {
+			const result = parseCliFlags(["node", "script.js", "--dry-run-test", "--verbosity"])
+			expect(result.dryRun).toBe(false)
+			expect(result.verbose).toBe(false)
+		})
+	})
+
+	describe("createLogger", () => {
+		it("should return an object with log and verbose methods", () => {
+			const logger = createLogger(false)
+			expect(typeof logger.log).toBe("function")
+			expect(typeof logger.verbose).toBe("function")
+		})
+
+		it("should log messages with log() method", () => {
+			const originalLog = console.log
+			const messages: string[] = []
+			console.log = (msg: string) => messages.push(msg)
+
+			const logger = createLogger(false)
+			logger.log("test message")
+
+			console.log = originalLog
+			expect(messages).toContain("test message")
+		})
+
+		it("should not log verbose messages when verbose is false", () => {
+			const originalLog = console.log
+			const messages: string[] = []
+			console.log = (msg: string) => messages.push(msg)
+
+			const logger = createLogger(false)
+			logger.verbose("verbose message")
+
+			console.log = originalLog
+			expect(messages).toHaveLength(0)
+		})
+
+		it("should log verbose messages with [VERBOSE] prefix when verbose is true", () => {
+			const originalLog = console.log
+			const messages: string[] = []
+			console.log = (msg: string) => messages.push(msg)
+
+			const logger = createLogger(true)
+			logger.verbose("verbose message")
+
+			console.log = originalLog
+			expect(messages).toContain("[VERBOSE] verbose message")
+		})
+
+		it("should log both normal and verbose messages when verbose is true", () => {
+			const originalLog = console.log
+			const messages: string[] = []
+			console.log = (msg: string) => messages.push(msg)
+
+			const logger = createLogger(true)
+			logger.log("normal message")
+			logger.verbose("verbose message")
+
+			console.log = originalLog
+			expect(messages).toContain("normal message")
+			expect(messages).toContain("[VERBOSE] verbose message")
+		})
+	})
 })