@vibe-agent-toolkit/utils 0.1.0-rc.7

package/dist/path-utils.js

@@ -0,0 +1,112 @@
+import path from 'node:path';
+/**
+ * Normalize a path for cross-platform comparison
+ *
+ * - Converts to absolute path (if baseDir provided)
+ * - Normalizes separators (/ vs \)
+ * - Resolves . and ..
+ * - Removes trailing slashes
+ *
+ * @param p - Path to normalize
+ * @param baseDir - Optional base directory for relative path resolution
+ * @returns Normalized absolute path
+ *
+ * @example
+ * normalizePath('./docs/../README.md', '/project')
+ * // Returns: '/project/README.md'
+ */
+export function normalizePath(p, baseDir) {
+    // Resolve to absolute if baseDir provided, otherwise just normalize
+    const resolved = baseDir ? path.resolve(baseDir, p) : path.normalize(p);
+    // Normalize path separators and remove trailing slashes
+    // Use simple non-backtracking pattern
+    let normalized = resolved;
+    while (normalized.endsWith('/') || normalized.endsWith('\\')) {
+        normalized = normalized.slice(0, -1);
+    }
+    return normalized;
+}
+/**
+ * Check if a path is absolute
+ *
+ * Cross-platform detection of absolute paths:
+ * - Unix: /path/to/file
+ * - Windows: C:\path\to\file or C:/path/to/file
+ *
+ * @param p - Path to check
+ * @returns True if path is absolute
+ *
+ * @example
+ * isAbsolutePath('/path/to/file')  // true
+ * isAbsolutePath('./relative')      // false
+ * isAbsolutePath('C:/Windows')      // true (Windows)
+ */
+export function isAbsolutePath(p) {
+    return path.isAbsolute(p);
+}
+/**
+ * Convert a relative path to absolute
+ *
+ * If path is already absolute, returns it normalized.
+ * Otherwise resolves relative to baseDir.
+ *
+ * @param p - Path to convert
+ * @param baseDir - Base directory for resolution
+ * @returns Absolute path
+ *
+ * @example
+ * toAbsolutePath('./docs/README.md', '/project')
+ * // Returns: '/project/docs/README.md'
+ *
+ * toAbsolutePath('/absolute/path.md', '/project')
+ * // Returns: '/absolute/path.md'
+ */
+export function toAbsolutePath(p, baseDir) {
+    if (path.isAbsolute(p)) {
+        return path.normalize(p);
+    }
+    return path.resolve(baseDir, p);
+}
+/**
+ * Get the relative path from one file to another
+ *
+ * Useful for generating relative links between markdown files.
+ *
+ * @param from - Source file path (absolute)
+ * @param to - Target file path (absolute)
+ * @returns Relative path from source to target
+ *
+ * @example
+ * getRelativePath('/project/docs/guide.md', '/project/README.md')
+ * // Returns: '../README.md'
+ *
+ * getRelativePath('/project/README.md', '/project/docs/api.md')
+ * // Returns: 'docs/api.md'
+ */
+export function getRelativePath(from, to) {
+    // Get directory of source file (not the file itself)
+    const fromDir = path.dirname(from);
+    // Calculate relative path from source directory to target file
+    return path.relative(fromDir, to);
+}
+/**
+ * Convert a path to Unix-style forward slashes
+ *
+ * Useful for glob pattern matching, which expects forward slashes.
+ * On Windows, path.resolve() and path.normalize() return backslashes,
+ * but glob matchers like picomatch expect forward slashes by default.
+ *
+ * @param p - Path to convert
+ * @returns Path with forward slashes
+ *
+ * @example
+ * toUnixPath('C:\\Users\\docs\\README.md')
+ * // Returns: 'C:/Users/docs/README.md'
+ *
+ * toUnixPath('/project/docs/README.md')
+ * // Returns: '/project/docs/README.md' (unchanged on Unix)
+ */
+export function toUnixPath(p) {
+    return p.replaceAll('\\', '/');
+}
+//# sourceMappingURL=path-utils.js.map

package/dist/path-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-utils.js","sourceRoot":"","sources":["../src/path-utils.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,aAAa,CAAC,CAAS,EAAE,OAAgB;IACvD,oEAAoE;IACpE,MAAM,QAAQ,GAAG,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IAExE,wDAAwD;IACxD,sCAAsC;IACtC,IAAI,UAAU,GAAG,QAAQ,CAAC;IAC1B,OAAO,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7D,UAAU,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACvC,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,cAAc,CAAC,CAAS;IACtC,OAAO,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;AAC5B,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,cAAc,CAAC,CAAS,EAAE,OAAe;IACvD,IAAI,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;QACvB,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IAC3B,CAAC;IACD,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;AAClC,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY,EAAE,EAAU;IACtD,qDAAqD;IACrD,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnC,+DAA+D;IAC/D,OAAO,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AACpC,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,UAAU,CAAC,CAAS;IAClC,OAAO,CAAC,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;AACjC,CAAC"}

package/dist/safe-exec.d.ts

@@ -0,0 +1,206 @@
+/**
+ * Options for safe command execution
+ */
+export interface SafeExecOptions {
+    /** Character encoding for output (default: undefined = Buffer) */
+    encoding?: BufferEncoding;
+    /** Standard I/O configuration */
+    stdio?: 'pipe' | 'ignore' | Array<'pipe' | 'ignore' | 'inherit'>;
+    /** Environment variables (merged with process.env if not fully specified) */
+    env?: NodeJS.ProcessEnv;
+    /** Working directory */
+    cwd?: string;
+    /** Maximum output buffer size in bytes */
+    maxBuffer?: number;
+    /** Timeout in milliseconds */
+    timeout?: number;
+}
+/**
+ * Result of a safe command execution
+ */
+export interface SafeExecResult {
+    /** Exit code (0 = success) */
+    status: number;
+    /** Standard output */
+    stdout: Buffer | string;
+    /** Standard error */
+    stderr: Buffer | string;
+    /** Error object if command failed to spawn */
+    error?: Error;
+}
+/**
+ * Error thrown when command execution fails
+ */
+export declare class CommandExecutionError extends Error {
+    readonly status: number;
+    readonly stdout: Buffer | string;
+    readonly stderr: Buffer | string;
+    constructor(message: string, status: number, stdout: Buffer | string, stderr: Buffer | string);
+}
+/**
+ * Safe command execution using spawnSync + which pattern
+ *
+ * More secure than execSync:
+ * - Resolves PATH once using pure Node.js (which package)
+ * - Executes with absolute path and shell: false
+ * - No shell interpreter = no command injection risk
+ * - Supports custom env vars (e.g., GIT_INDEX_FILE)
+ *
+ * @param command - Command name (e.g., 'git', 'gitleaks', 'node')
+ * @param args - Array of arguments
+ * @param options - Execution options
+ * @returns Buffer or string output
+ * @throws Error if command not found or execution fails
+ *
+ * @example
+ * // Tool detection
+ * safeExecSync('gitleaks', ['--version'], { stdio: 'ignore' });
+ *
+ * @example
+ * // Git with custom env
+ * safeExecSync('git', ['add', '--all'], {
+ *   env: { ...process.env, GIT_INDEX_FILE: tempFile }
+ * });
+ *
+ * @example
+ * // Get output as string
+ * const version = safeExecSync('node', ['--version'], { encoding: 'utf8' });
+ */
+export declare function safeExecSync(command: string, args?: string[], options?: SafeExecOptions): Buffer | string;
+/**
+ * Safe command execution that returns detailed result (doesn't throw)
+ *
+ * Use this when you need to handle errors programmatically
+ * instead of catching exceptions.
+ *
+ * @param command - Command name (e.g., 'git', 'node')
+ * @param args - Array of arguments
+ * @param options - Execution options
+ * @returns Detailed execution result
+ *
+ * @example
+ * const result = safeExecResult('git', ['status']);
+ * if (result.status === 0) {
+ *   console.log(result.stdout.toString());
+ * } else {
+ *   console.error(`Failed: ${result.stderr.toString()}`);
+ * }
+ */
+export declare function safeExecResult(command: string, args?: string[], options?: SafeExecOptions): SafeExecResult;
+/**
+ * Check if a command-line tool is available
+ *
+ * @param toolName - Name of tool to check (e.g., 'gh', 'gitleaks', 'node')
+ * @returns true if tool is available, false otherwise
+ *
+ * @example
+ * if (isToolAvailable('gh')) {
+ *   console.log('GitHub CLI is installed');
+ * }
+ */
+export declare function isToolAvailable(toolName: string): boolean;
+/**
+ * Get tool version if available
+ *
+ * @param toolName - Name of tool (e.g., 'node', 'pnpm')
+ * @param versionArg - Argument to get version (default: '--version')
+ * @returns Version string or null if not available
+ *
+ * @example
+ * const nodeVersion = getToolVersion('node');
+ * console.log(nodeVersion); // "v20.11.0"
+ *
+ * @example
+ * const gitVersion = getToolVersion('git', 'version');
+ * console.log(gitVersion); // "git version 2.39.2"
+ */
+export declare function getToolVersion(toolName: string, versionArg?: string): string | null;
+/**
+ * Check if a command string contains shell-specific syntax
+ *
+ * Detects patterns that require shell interpretation:
+ * - Quotes (", ', `)
+ * - Glob patterns (*, ?, [])
+ * - Variable expansion ($)
+ * - Pipes/redirects/operators (|, >, <, &, ;, &&, ||)
+ *
+ * Performance: Single-pass O(n) algorithm with O(1) Set lookups.
+ * Short-circuits on first match (no backtracking, no regex overhead).
+ *
+ * @param commandString - Command string to check
+ * @returns Object with detection result and details
+ *
+ * @example
+ * ```typescript
+ * const check1 = hasShellSyntax('npm test');
+ * console.log(check1); // { hasShellSyntax: false }
+ *
+ * const check2 = hasShellSyntax('npm test && npm run build');
+ * console.log(check2);
+ * // {
+ * //   hasShellSyntax: true,
+ * //   pattern: 'pipes/redirects/operators',
+ * //   example: 'cat file | grep text'
+ * // }
+ * ```
+ */
+export declare function hasShellSyntax(commandString: string): {
+    hasShellSyntax: boolean;
+    pattern?: string;
+    example?: string;
+};
+/**
+ * Execute a command from a simple command string (convenience wrapper)
+ *
+ * **IMPORTANT: Shift-Left Validation** - This function actively rejects shell syntax
+ * to prevent subtle bugs where shell features are expected but not executed.
+ *
+ * **Supported:**
+ * - Simple commands: `git status`, `pnpm test`, `node --version`
+ * - Commands with flags: `git log --oneline --max-count 10`
+ * - Multiple unquoted arguments: `gh pr view 123`
+ *
+ * **NOT Supported (will throw error):**
+ * - Quotes: `echo "hello world"` ❌
+ * - Glob patterns: `ls *.txt` ❌
+ * - Variable expansion: `echo $HOME` ❌
+ * - Pipes/redirects: `cat file | grep text` ❌
+ * - Command chaining: `build && test` ❌
+ *
+ * **Why these restrictions?**
+ * We don't use a shell interpreter (for security), so shell features like
+ * glob expansion, variable substitution, and pipes don't work. By detecting
+ * and rejecting these patterns, we force you to use the safer `safeExecSync()`
+ * API with explicit argument arrays.
+ *
+ * @param commandString - Simple command string (no shell syntax)
+ * @param options - Execution options
+ * @returns Command output (Buffer or string depending on encoding option)
+ * @throws Error if command contains shell-specific syntax
+ *
+ * @example
+ * ```typescript
+ * // ✅ Simple commands (these work)
+ * safeExecFromString('git status');
+ * safeExecFromString('pnpm test --watch');
+ * safeExecFromString('gh pr view 123');
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // ❌ Shell syntax (these throw errors)
+ * safeExecFromString('echo "hello"');         // Quotes
+ * safeExecFromString('ls *.txt');             // Glob pattern
+ * safeExecFromString('cat file | grep text'); // Pipe
+ * safeExecFromString('echo $HOME');           // Variable expansion
+ *
+ * // ✅ Use safeExecSync() instead with explicit arguments
+ * safeExecSync('echo', ['hello']);
+ * safeExecSync('ls', ['file1.txt', 'file2.txt']); // Or use glob library
+ * safeExecSync('grep', ['text', 'file']);
+ * safeExecSync('echo', [process.env.HOME || '']);
+ * ```
+ *
+ */
+export declare function safeExecFromString(commandString: string, options?: SafeExecOptions): Buffer | string;
+//# sourceMappingURL=safe-exec.d.ts.map

package/dist/safe-exec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-exec.d.ts","sourceRoot":"","sources":["../src/safe-exec.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,kEAAkE;IAClE,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,iCAAiC;IACjC,KAAK,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC,CAAC;IACjE,6EAA6E;IAC7E,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,wBAAwB;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8BAA8B;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,sBAAsB;IACtB,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,qBAAqB;IACrB,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,8CAA8C;IAC9C,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,SAAgB,MAAM,EAAE,MAAM,CAAC;IAC/B,SAAgB,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IACxC,SAAgB,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;gBAGtC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GAAG,MAAM,EACvB,MAAM,EAAE,MAAM,GAAG,MAAM;CAQ1B;AA4DD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,MAAM,EAAO,EACnB,OAAO,GAAE,eAAoB,GAC5B,MAAM,GAAG,MAAM,CAsCjB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,MAAM,EAAO,EACnB,OAAO,GAAE,eAAoB,GAC5B,cAAc,CA0ChB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAOzD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,UAAU,GAAE,MAAoB,GAC/B,MAAM,GAAG,IAAI,CAUf;AAuBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,cAAc,CAAC,aAAa,EAAE,MAAM,GAAG;IACrD,cAAc,EAAE,OAAO,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CA0CA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,wBAAgB,kBAAkB,CAChC,aAAa,EAAE,MAAM,EACrB,OAAO,GAAE,eAAoB,GAC5B,MAAM,GAAG,MAAM,CAyBjB"}