aiwcli 0.9.0

package/dist/lib/output.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Output Utilities
+ *
+ * Provides TTY-aware output functions with automatic color support.
+ * Colors automatically disabled when output is piped or redirected.
+ * Respects NO_COLOR and FORCE_COLOR environment variables.
+ */
+import { type ProcessLike } from './tty-detection.js';
+/**
+ * Dependencies for output functions.
+ * Allows tests to inject mock values without mutating global state.
+ */
+export interface OutputDependencies {
+    proc?: ProcessLike;
+}
+/**
+ * Log informational message (stdout, no color).
+ * Suppressed in quiet mode.
+ * @param message - Message to log
+ * @param quiet - If true, suppress output
+ */
+export declare function logInfo(message: string, quiet?: boolean): void;
+/**
+ * Log success message (stdout, green in TTY).
+ * Suppressed in quiet mode.
+ * @param message - Message to log
+ * @param quiet - If true, suppress output
+ * @param deps - Optional dependencies for testing
+ */
+export declare function logSuccess(message: string, quiet?: boolean, deps?: OutputDependencies): void;
+/**
+ * Log error message (stderr, red in TTY).
+ * NEVER suppressed - errors always output even in quiet mode.
+ * @param message - Message to log
+ * @param deps - Optional dependencies for testing
+ */
+export declare function logError(message: string, deps?: OutputDependencies): void;
+/**
+ * Log warning message (stdout, yellow in TTY).
+ * Suppressed in quiet mode.
+ * @param message - Message to log
+ * @param quiet - If true, suppress output
+ * @param deps - Optional dependencies for testing
+ */
+export declare function logWarning(message: string, quiet?: boolean, deps?: OutputDependencies): void;
+/**
+ * Log debug message (stdout, dim in TTY).
+ * @param message - Message to log
+ * @param deps - Optional dependencies for testing
+ */
+export declare function logDebug(message: string, deps?: OutputDependencies): void;

package/dist/lib/output.js

@@ -0,0 +1,76 @@
+/**
+ * Output Utilities
+ *
+ * Provides TTY-aware output functions with automatic color support.
+ * Colors automatically disabled when output is piped or redirected.
+ * Respects NO_COLOR and FORCE_COLOR environment variables.
+ */
+import chalk from 'chalk';
+import { shouldUseColors } from './tty-detection.js';
+/**
+ * Get whether colors should be used, evaluating lazily.
+ * Internal helper that checks TTY state at call time.
+ */
+function getUseColors(deps) {
+    return shouldUseColors(deps?.proc);
+}
+/**
+ * Log informational message (stdout, no color).
+ * Suppressed in quiet mode.
+ * @param message - Message to log
+ * @param quiet - If true, suppress output
+ */
+export function logInfo(message, quiet = false) {
+    if (quiet)
+        return;
+    console.log(message);
+}
+/**
+ * Log success message (stdout, green in TTY).
+ * Suppressed in quiet mode.
+ * @param message - Message to log
+ * @param quiet - If true, suppress output
+ * @param deps - Optional dependencies for testing
+ */
+export function logSuccess(message, quiet = false, deps) {
+    if (quiet)
+        return;
+    const useColors = getUseColors(deps);
+    const formatted = useColors ? chalk.green(message) : message;
+    console.log(formatted);
+}
+/**
+ * Log error message (stderr, red in TTY).
+ * NEVER suppressed - errors always output even in quiet mode.
+ * @param message - Message to log
+ * @param deps - Optional dependencies for testing
+ */
+export function logError(message, deps) {
+    const useColors = getUseColors(deps);
+    const formatted = useColors ? chalk.red(message) : message;
+    console.error(formatted);
+}
+/**
+ * Log warning message (stdout, yellow in TTY).
+ * Suppressed in quiet mode.
+ * @param message - Message to log
+ * @param quiet - If true, suppress output
+ * @param deps - Optional dependencies for testing
+ */
+export function logWarning(message, quiet = false, deps) {
+    if (quiet)
+        return;
+    const useColors = getUseColors(deps);
+    const formatted = useColors ? chalk.yellow(message) : message;
+    console.log(formatted);
+}
+/**
+ * Log debug message (stdout, dim in TTY).
+ * @param message - Message to log
+ * @param deps - Optional dependencies for testing
+ */
+export function logDebug(message, deps) {
+    const useColors = getUseColors(deps);
+    const formatted = useColors ? chalk.dim(message) : message;
+    console.log(formatted);
+}

package/dist/lib/paths.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Get the user's home directory path.
+ * Wrapper around os.homedir() for consistency.
+ * @returns Absolute path to user's home directory
+ */
+export declare function getHomePath(): string;
+/**
+ * Expand a path that may contain ~ (tilde) home directory shorthand.
+ * @param inputPath - Path that may start with ~
+ * @returns Path with ~ expanded to home directory, or original path
+ */
+export declare function expandPath(inputPath: string): string;
+/**
+ * Convert a path to Unix-style forward slashes.
+ * Useful for cross-platform logging or display.
+ * @param inputPath - Path with any separator style
+ * @returns Path with forward slashes only
+ */
+export declare function toUnixPath(inputPath: string): string;
+/**
+ * Convert a path to Windows-style backslashes.
+ * Useful for cross-platform logging or display.
+ * @param inputPath - Path with any separator style
+ * @returns Path with backslashes only
+ */
+export declare function toWindowsPath(inputPath: string): string;
+/**
+ * Normalize a path to use platform-native separators.
+ * Handles mixed forward/back slashes and removes redundant separators.
+ * @param inputPath - Path with potentially mixed separators
+ * @returns Path with platform-native separators
+ */
+export declare function normalizePath(inputPath: string): string;
+/**
+ * Check if a path exists asynchronously.
+ *
+ * WARNING: Subject to Time-of-Check-Time-of-Use (TOCTOU) race condition.
+ * The path may be created/deleted between checking and using it.
+ * For critical operations, use try/catch around the actual file operation instead.
+ *
+ * @param pathToCheck - Path to check for existence
+ * @returns Promise resolving to true if path exists, false otherwise
+ */
+export declare function pathExists(pathToCheck: string): Promise<boolean>;
+/**
+ * Join path segments using platform-appropriate separator.
+ */
+export declare function resolvePath(...segments: string[]): string;
+/**
+ * Check if directory is an AI Workflow workspace (contains .aiw directory marker).
+ * Per AC3: The marker must be a directory, not a file.
+ */
+export declare function isWorkspace(dir: string): boolean;
+/**
+ * Search up the directory tree for a .aiw workspace marker.
+ * @param startDir - Directory to start searching from
+ * @returns Path to workspace root, or null if not found
+ */
+export declare function findWorkspaceRoot(startDir: string): null | string;
+/**
+ * Get the workspace path if in an AI Workflow workspace, or null otherwise.
+ * Alias for findWorkspaceRoot with current directory as default.
+ * @param startDir - Directory to start searching from (defaults to cwd)
+ * @returns Path to workspace root, or null if not in a workspace or cwd unavailable
+ */
+export declare function getWorkspacePath(startDir?: string): null | string;

package/dist/lib/paths.js

@@ -0,0 +1,136 @@
+import { existsSync, statSync } from 'node:fs';
+import { access } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join, normalize } from 'node:path';
+/**
+ * Get the user's home directory path.
+ * Wrapper around os.homedir() for consistency.
+ * @returns Absolute path to user's home directory
+ */
+export function getHomePath() {
+    return homedir();
+}
+/**
+ * Expand a path that may contain ~ (tilde) home directory shorthand.
+ * @param inputPath - Path that may start with ~
+ * @returns Path with ~ expanded to home directory, or original path
+ */
+export function expandPath(inputPath) {
+    if (!inputPath) {
+        return inputPath;
+    }
+    // Only expand ~ at the start of the path
+    if (inputPath === '~') {
+        return homedir();
+    }
+    if (inputPath.startsWith('~/') || inputPath.startsWith('~\\')) {
+        return join(homedir(), inputPath.slice(2));
+    }
+    return inputPath;
+}
+/**
+ * Convert a path to Unix-style forward slashes.
+ * Useful for cross-platform logging or display.
+ * @param inputPath - Path with any separator style
+ * @returns Path with forward slashes only
+ */
+export function toUnixPath(inputPath) {
+    return inputPath.replaceAll('\\', '/');
+}
+/**
+ * Convert a path to Windows-style backslashes.
+ * Useful for cross-platform logging or display.
+ * @param inputPath - Path with any separator style
+ * @returns Path with backslashes only
+ */
+export function toWindowsPath(inputPath) {
+    return inputPath.replaceAll('/', '\\');
+}
+/**
+ * Normalize a path to use platform-native separators.
+ * Handles mixed forward/back slashes and removes redundant separators.
+ * @param inputPath - Path with potentially mixed separators
+ * @returns Path with platform-native separators
+ */
+export function normalizePath(inputPath) {
+    if (!inputPath) {
+        return '.';
+    }
+    // Replace all forward and back slashes with forward slashes first,
+    // then let normalize() handle the platform conversion
+    const unified = inputPath.replaceAll(/[\\/]+/g, '/');
+    return normalize(unified);
+}
+/**
+ * Check if a path exists asynchronously.
+ *
+ * WARNING: Subject to Time-of-Check-Time-of-Use (TOCTOU) race condition.
+ * The path may be created/deleted between checking and using it.
+ * For critical operations, use try/catch around the actual file operation instead.
+ *
+ * @param pathToCheck - Path to check for existence
+ * @returns Promise resolving to true if path exists, false otherwise
+ */
+export async function pathExists(pathToCheck) {
+    try {
+        await access(pathToCheck);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Join path segments using platform-appropriate separator.
+ */
+export function resolvePath(...segments) {
+    return join(...segments);
+}
+/**
+ * Check if directory is an AI Workflow workspace (contains .aiw directory marker).
+ * Per AC3: The marker must be a directory, not a file.
+ */
+export function isWorkspace(dir) {
+    const aiwPath = join(dir, '.aiw');
+    try {
+        return existsSync(aiwPath) && statSync(aiwPath).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Search up the directory tree for a .aiw workspace marker.
+ * @param startDir - Directory to start searching from
+ * @returns Path to workspace root, or null if not found
+ */
+export function findWorkspaceRoot(startDir) {
+    let currentDir = normalize(startDir);
+    while (true) {
+        if (isWorkspace(currentDir)) {
+            return currentDir;
+        }
+        const parentDir = dirname(currentDir);
+        // Reached filesystem root
+        if (parentDir === currentDir) {
+            return null;
+        }
+        currentDir = parentDir;
+    }
+}
+/**
+ * Get the workspace path if in an AI Workflow workspace, or null otherwise.
+ * Alias for findWorkspaceRoot with current directory as default.
+ * @param startDir - Directory to start searching from (defaults to cwd)
+ * @returns Path to workspace root, or null if not in a workspace or cwd unavailable
+ */
+export function getWorkspacePath(startDir) {
+    try {
+        const dir = startDir ?? process.cwd();
+        return findWorkspaceRoot(dir);
+    }
+    catch {
+        // process.cwd() can throw ENOENT if current directory was deleted
+        return null;
+    }
+}

package/dist/lib/quiet.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Quiet mode state management for AI Workflow CLI.
+ * Provides global quiet mode state for suppressing informational output.
+ */
+/**
+ * Check if quiet mode is enabled.
+ */
+export declare function isQuietMode(): boolean;
+/**
+ * Enable or disable quiet mode.
+ */
+export declare function setQuietMode(enabled: boolean): void;

package/dist/lib/quiet.js

@@ -0,0 +1,17 @@
+/**
+ * Quiet mode state management for AI Workflow CLI.
+ * Provides global quiet mode state for suppressing informational output.
+ */
+let quietMode = false;
+/**
+ * Check if quiet mode is enabled.
+ */
+export function isQuietMode() {
+    return quietMode;
+}
+/**
+ * Enable or disable quiet mode.
+ */
+export function setQuietMode(enabled) {
+    quietMode = enabled;
+}

package/dist/lib/settings-hierarchy.d.ts

@@ -0,0 +1,42 @@
+import type { ClaudeSettings, SettingsLocation } from './claude-settings-types.js';
+/**
+ * Discover Claude settings files in the hierarchy
+ *
+ * Settings hierarchy (in order of precedence):
+ * 1. Local Project Settings: `.claude/settings.local.json` (gitignored)
+ * 2. Project Settings: `.claude/settings.json` (shared with team)
+ * 3. User Settings: `~/.claude/settings.json` (global)
+ *
+ * @param projectDir - Project directory path
+ * @returns Array of settings locations in order of precedence
+ */
+export declare function discoverSettingsFiles(projectDir: string): Promise<SettingsLocation[]>;
+/**
+ * Read Claude settings from file
+ *
+ * @param path - Path to settings.json file
+ * @returns Parsed settings or undefined if file doesn't exist or is invalid
+ */
+export declare function readClaudeSettings(path: string): Promise<ClaudeSettings | undefined>;
+/**
+ * Write Claude settings to file
+ *
+ * Creates parent directories if they don't exist
+ * Backs up existing file before writing
+ *
+ * @param path - Path to settings.json file
+ * @param settings - Settings to write
+ * @throws Error if write fails
+ */
+export declare function writeClaudeSettings(path: string, settings: ClaudeSettings): Promise<void>;
+/**
+ * Get the target settings file for template hook merging
+ *
+ * Strategy:
+ * - If project settings exist, merge into that file
+ * - Otherwise, create project settings with template hooks
+ *
+ * @param projectDir - Project directory path
+ * @returns Path to target settings file
+ */
+export declare function getTargetSettingsFile(projectDir: string): string;

package/dist/lib/settings-hierarchy.js

@@ -0,0 +1,105 @@
+import { promises as fs } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { IdePathResolver } from './ide-path-resolver.js';
+/**
+ * Discover Claude settings files in the hierarchy
+ *
+ * Settings hierarchy (in order of precedence):
+ * 1. Local Project Settings: `.claude/settings.local.json` (gitignored)
+ * 2. Project Settings: `.claude/settings.json` (shared with team)
+ * 3. User Settings: `~/.claude/settings.json` (global)
+ *
+ * @param projectDir - Project directory path
+ * @returns Array of settings locations in order of precedence
+ */
+export async function discoverSettingsFiles(projectDir) {
+    const locations = [];
+    // User settings (global)
+    const userSettingsPath = join(homedir(), '.claude', 'settings.json');
+    locations.push({
+        type: 'user',
+        path: userSettingsPath,
+        exists: await fileExists(userSettingsPath),
+    });
+    // Project settings (shared)
+    const projectSettingsPath = join(projectDir, '.claude', 'settings.json');
+    locations.push({
+        type: 'project',
+        path: projectSettingsPath,
+        exists: await fileExists(projectSettingsPath),
+    });
+    // Local project settings (gitignored)
+    const localSettingsPath = join(projectDir, '.claude', 'settings.local.json');
+    locations.push({
+        type: 'local',
+        path: localSettingsPath,
+        exists: await fileExists(localSettingsPath),
+    });
+    return locations;
+}
+/**
+ * Check if file exists
+ */
+async function fileExists(path) {
+    try {
+        await fs.access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Read Claude settings from file
+ *
+ * @param path - Path to settings.json file
+ * @returns Parsed settings or undefined if file doesn't exist or is invalid
+ */
+export async function readClaudeSettings(path) {
+    try {
+        const content = await fs.readFile(path, 'utf8');
+        return JSON.parse(content);
+    }
+    catch {
+        // File doesn't exist or invalid JSON
+        return undefined;
+    }
+}
+/**
+ * Write Claude settings to file
+ *
+ * Creates parent directories if they don't exist
+ * Backs up existing file before writing
+ *
+ * @param path - Path to settings.json file
+ * @param settings - Settings to write
+ * @throws Error if write fails
+ */
+export async function writeClaudeSettings(path, settings) {
+    // Create parent directory if it doesn't exist
+    const dir = join(path, '..');
+    await fs.mkdir(dir, { recursive: true });
+    // Backup existing file if it exists
+    if (await fileExists(path)) {
+        const backupPath = `${path}.backup`;
+        await fs.copyFile(path, backupPath);
+    }
+    // Write settings with pretty formatting
+    const content = JSON.stringify(settings, null, 2);
+    await fs.writeFile(path, content, 'utf8');
+}
+/**
+ * Get the target settings file for template hook merging
+ *
+ * Strategy:
+ * - If project settings exist, merge into that file
+ * - Otherwise, create project settings with template hooks
+ *
+ * @param projectDir - Project directory path
+ * @returns Path to target settings file
+ */
+export function getTargetSettingsFile(projectDir) {
+    const resolver = new IdePathResolver(projectDir);
+    return resolver.getClaudeSettings();
+}

package/dist/lib/spawn.d.ts

@@ -0,0 +1,105 @@
+/**
+ * @file Process spawning utilities for AI Workflow CLI.
+ *
+ * This module provides utilities for spawning external processes (e.g., Claude Code)
+ * with proper error handling, stdio configuration, and debug logging.
+ *
+ * ## Key Features
+ * - Spawn external processes with configurable stdio (inherit, pipe)
+ * - Exit code capture and error handling
+ * - Detached mode for parallel sessions
+ * - Debug logging integration
+ * - Cross-platform compatibility
+ *
+ * ## Usage Examples
+ *
+ * ### Basic Spawn (Interactive)
+ * ```typescript
+ * import {spawnProcess} from '../lib/spawn.js'
+ *
+ * const exitCode = await spawnProcess('claude', ['--dangerously-skip-permissions'])
+ * if (exitCode !== 0) {
+ *   console.error('Claude Code exited with error')
+ * }
+ * ```
+ *
+ * ### Parallel Sessions (Detached Mode)
+ * ```typescript
+ * // Launch multiple Claude Code sessions concurrently
+ * const session1 = spawnProcess('claude', ['--dangerously-skip-permissions'], {detached: true})
+ * const session2 = spawnProcess('claude', ['--dangerously-skip-permissions'], {detached: true})
+ * await Promise.all([session1, session2])
+ * ```
+ *
+ * ### Custom Working Directory
+ * ```typescript
+ * await spawnProcess('npm', ['install'], {cwd: '/path/to/project'})
+ * ```
+ *
+ * @module lib/spawn
+ */
+/**
+ * Spawn options for process execution.
+ */
+export interface SpawnProcessOptions {
+    /**
+     * Working directory for spawned process.
+     * Defaults to current working directory if not specified.
+     */
+    cwd?: string;
+    /**
+     * Spawn detached process for parallel sessions.
+     * When true, process runs independently and parent can exit without waiting.
+     * Useful for launching multiple Claude Code sessions concurrently.
+     *
+     * @default false
+     */
+    detached?: boolean;
+    /**
+     * Stdio configuration.
+     * - 'inherit': Connect child stdio to parent (default, for interactive sessions)
+     * - 'pipe': Capture child stdio for programmatic access
+     */
+    stdio?: 'inherit' | 'pipe';
+}
+/**
+ * Spawn an external process and return its exit code.
+ *
+ * This function wraps Node.js child_process.spawn with AIW-specific
+ * error handling, debug logging, and parallel session support.
+ *
+ * ## Exit Code Mapping
+ * - 0: Success
+ * - Non-zero: Error (actual code from child process)
+ * - null code: Defaults to 1
+ *
+ * ## Error Handling
+ * - ENOENT: Command not found → ProcessSpawnError with install instructions
+ * - EACCES: Permission denied → ProcessSpawnError with permission fix
+ * - Other errors: ProcessSpawnError with error details
+ *
+ * ## Parallel Sessions
+ * Use `detached: true` to spawn independent processes that don't block parent.
+ * Multiple calls can run concurrently without conflicts.
+ *
+ * @param command - Command to execute (e.g., 'claude', 'npm', 'git')
+ * @param args - Arguments array (e.g., ['--dangerously-skip-permissions'])
+ * @param options - Spawn configuration options
+ * @returns Promise<number> - Exit code (0 = success, non-zero = error)
+ * @throws ProcessSpawnError - When spawn fails (command not found, permissions, etc.)
+ *
+ * @example
+ * // Launch Claude Code with sandbox disabled
+ * const exitCode = await spawnProcess('claude', ['--dangerously-skip-permissions'])
+ *
+ * @example
+ * // Parallel session with detached mode
+ * const session1 = spawnProcess('claude', ['--dangerously-skip-permissions'], {detached: true})
+ * const session2 = spawnProcess('claude', ['--dangerously-skip-permissions'], {detached: true})
+ * await Promise.all([session1, session2])
+ *
+ * @example
+ * // Custom working directory
+ * await spawnProcess('npm', ['test'], {cwd: '/path/to/project'})
+ */
+export declare function spawnProcess(command: string, args?: string[], options?: SpawnProcessOptions): Promise<number>;