aiwcli 0.9.0

package/dist/lib/claude-settings-types.js

@@ -0,0 +1,5 @@
+/**
+ * TypeScript interfaces for Claude Code settings.json structure
+ * Based on Claude Code documentation and research
+ */
+export {};

package/dist/lib/config.d.ts

@@ -0,0 +1,25 @@
+/**
+ * AI Workflow CLI configuration interface.
+ * Contains all resolved paths for CLI operation.
+ */
+export interface AiwcliConfig {
+    aiwDir: string;
+    claudeConfigPath: string;
+    settingsPath: string;
+}
+/**
+ * Resolve AI Workflow CLI home directory.
+ * Priority: AIW_DIR env var > ~/.aiw default
+ */
+export declare function getAiwDir(): string;
+/**
+ * Validate that AIW home directory exists.
+ * @throws {ConfigNotFoundError} When directory does not exist
+ */
+export declare function validateAiwDir(aiwDir: string): void;
+/**
+ * Load and validate AIW configuration.
+ * @returns Fully resolved AiwcliConfig with all paths
+ * @throws {ConfigNotFoundError} When AIW_DIR does not exist
+ */
+export declare function loadConfig(): AiwcliConfig;

package/dist/lib/config.js

@@ -0,0 +1,46 @@
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { debug } from './debug.js';
+import { getAiwDir as getAiwDirFromEnv } from './env-compat.js';
+import { ConfigNotFoundError } from './errors.js';
+/**
+ * Resolve AI Workflow CLI home directory.
+ * Priority: AIW_DIR env var > ~/.aiw default
+ */
+export function getAiwDir() {
+    // Try env var first, then default
+    const envHome = getAiwDirFromEnv();
+    if (envHome) {
+        return envHome;
+    }
+    // Default to ~/.aiw
+    return join(homedir(), '.aiw');
+}
+/**
+ * Validate that AIW home directory exists.
+ * @throws {ConfigNotFoundError} When directory does not exist
+ */
+export function validateAiwDir(aiwDir) {
+    if (!existsSync(aiwDir)) {
+        throw new ConfigNotFoundError(`AIW_DIR not found at ${aiwDir}. Run 'aiw setup' or set AIW_DIR env var.`);
+    }
+}
+/**
+ * Load and validate AIW configuration.
+ * @returns Fully resolved AiwcliConfig with all paths
+ * @throws {ConfigNotFoundError} When AIW_DIR does not exist
+ */
+export function loadConfig() {
+    const aiwDir = getAiwDir();
+    debug(`Resolved AIW_DIR: ${aiwDir}`);
+    validateAiwDir(aiwDir);
+    const config = {
+        aiwDir,
+        claudeConfigPath: join(homedir(), '.claude'),
+        settingsPath: join(aiwDir, '.claude', 'settings.json'),
+    };
+    debug(`claudeConfigPath: ${config.claudeConfigPath}`);
+    debug(`settingsPath: ${config.settingsPath}`);
+    return config;
+}

package/dist/lib/debug.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Debug logging utilities for AI Workflow CLI.
+ * Provides conditional debug output with [debug] prefix.
+ */
+/**
+ * Check if debug mode is enabled.
+ */
+export declare function isDebugEnabled(): boolean;
+/**
+ * Enable or disable debug mode.
+ */
+export declare function setDebugEnabled(enabled: boolean): void;
+/**
+ * Log a debug message if debug mode is enabled.
+ * Messages are prefixed with [debug] and output to stderr.
+ * @param message - The message to log
+ */
+export declare function debug(message: string): void;
+/**
+ * Log configuration details in debug mode.
+ * Only logs AIW_DIR path to avoid accidentally logging sensitive data.
+ * @param config - Configuration object
+ * @param config.aiwDir - AIW_DIR path
+ */
+export declare function debugConfig(config: {
+    [key: string]: unknown;
+    aiwDir: string;
+}): void;
+/**
+ * Log process spawn details in debug mode.
+ * @param command - Command being spawned
+ * @param args - Arguments passed to command
+ */
+export declare function debugSpawn(command: string, args: string[]): void;
+/**
+ * Log version information in debug mode.
+ * Displays AI Workflow CLI version and Node.js version.
+ */
+export declare function debugVersion(): void;

package/dist/lib/debug.js

@@ -0,0 +1,74 @@
+/**
+ * Debug logging utilities for AI Workflow CLI.
+ * Provides conditional debug output with [debug] prefix.
+ */
+let debugEnabled = false;
+/**
+ * Check if debug mode is enabled.
+ */
+export function isDebugEnabled() {
+    return debugEnabled;
+}
+/**
+ * Enable or disable debug mode.
+ */
+export function setDebugEnabled(enabled) {
+    debugEnabled = enabled;
+}
+/**
+ * Log a debug message if debug mode is enabled.
+ * Messages are prefixed with [debug] and output to stderr.
+ * @param message - The message to log
+ */
+export function debug(message) {
+    if (debugEnabled) {
+        // Use dim color if terminal supports it, otherwise plain text
+        const supportsColor = process.stderr.isTTY;
+        if (supportsColor) {
+            // ANSI dim: \u001B[2m, reset: \u001B[0m
+            process.stderr.write(`\u001B[2m[debug] ${message}\u001B[0m\n`);
+        }
+        else {
+            process.stderr.write(`[debug] ${message}\n`);
+        }
+    }
+}
+/**
+ * Log configuration details in debug mode.
+ * Only logs AIW_DIR path to avoid accidentally logging sensitive data.
+ * @param config - Configuration object
+ * @param config.aiwDir - AIW_DIR path
+ */
+export function debugConfig(config) {
+    debug(`AIW_DIR resolved to ${config.aiwDir}`);
+    // NOTE: Do NOT log full config - may contain API keys/tokens in future
+}
+/**
+ * Log process spawn details in debug mode.
+ * @param command - Command being spawned
+ * @param args - Arguments passed to command
+ */
+export function debugSpawn(command, args) {
+    debug(`Spawning: ${command} ${args.join(' ')}`);
+}
+/**
+ * Log version information in debug mode.
+ * Displays AI Workflow CLI version and Node.js version.
+ */
+export function debugVersion() {
+    // Read version from package.json
+    // Note: process.env.npm_package_version only works during npm scripts
+    // For production, we need to read package.json directly
+    let version = 'unknown';
+    try {
+        // In ESM, we can use import.meta.url to resolve relative to this file
+        // For now, use env var with fallback (will be 'unknown' in production until fixed properly)
+        version = process.env.npm_package_version || '0.1.0';
+    }
+    catch {
+        version = '0.1.0';
+    }
+    debug(`AI Workflow CLI v${version}`);
+    debug(`Node.js ${process.version}`);
+    debug(`Platform: ${process.platform} ${process.arch}`);
+}

package/dist/lib/env-compat.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Environment Variable Layer
+ *
+ * Provides environment variable resolution for AIW CLI.
+ *
+ * Environment variables:
+ * - AIW_DIR: Main installation directory
+ * - AIW_CONFIG: Configuration file path
+ */
+/**
+ * Load environment variables.
+ * Call this early in application bootstrap.
+ */
+export declare function loadEnvWithCompatibility(): void;
+/**
+ * Get AIW_DIR environment variable
+ */
+export declare function getAiwDir(): string | undefined;
+/**
+ * Get AIW_CONFIG environment variable
+ */
+export declare function getAiwConfig(): string | undefined;
+/**
+ * Check if using legacy environment variables
+ */
+export declare function isUsingLegacyEnvVars(): boolean;

package/dist/lib/env-compat.js

@@ -0,0 +1,35 @@
+/**
+ * Environment Variable Layer
+ *
+ * Provides environment variable resolution for AIW CLI.
+ *
+ * Environment variables:
+ * - AIW_DIR: Main installation directory
+ * - AIW_CONFIG: Configuration file path
+ */
+/**
+ * Load environment variables.
+ * Call this early in application bootstrap.
+ */
+export function loadEnvWithCompatibility() {
+    // DA (Assistant name) - Keep for backward compatibility, no warning
+    // This is commonly used and doesn't need migration
+}
+/**
+ * Get AIW_DIR environment variable
+ */
+export function getAiwDir() {
+    return process.env['AIW_DIR'];
+}
+/**
+ * Get AIW_CONFIG environment variable
+ */
+export function getAiwConfig() {
+    return process.env['AIW_CONFIG'];
+}
+/**
+ * Check if using legacy environment variables
+ */
+export function isUsingLegacyEnvVars() {
+    return false;
+}

package/dist/lib/errors.d.ts

@@ -0,0 +1,126 @@
+/**
+ * @file Error handling classes and utilities for AI Workflow CLI.
+ *
+ * This module provides:
+ * - Custom error classes with exit codes
+ * - Error message formatting utilities
+ * - Error handling patterns for commands
+ *
+ * ## Error Handling Patterns for Commands
+ *
+ * ### Basic Pattern (Recommended)
+ * ```typescript
+ * import {Command} from '@oclif/core'
+ * import {ConfigNotFoundError, InvalidUsageError} from '../lib/errors.js'
+ *
+ * export default class LaunchCommand extends Command {
+ *   async run() {
+ *     try {
+ *       const config = await loadConfig()
+ *       await launchClaude(config)
+ *     } catch (error) {
+ *       if (error instanceof ConfigNotFoundError) {
+ *         this.error(error.message, {exit: error.exitCode})
+ *       }
+ *       if (error instanceof InvalidUsageError) {
+ *         this.error(error.message, {exit: error.exitCode})
+ *       }
+ *       this.error(`Unexpected error: ${error.message}`, {exit: EXIT_CODES.GENERAL_ERROR})
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * ### Using this.error() vs throwing custom errors
+ * - **Throw custom errors** in library code (src/lib/) for business logic failures
+ * - **Catch and translate** in commands using this.error() for user-facing output
+ * - **this.error()** automatically outputs to stderr and exits with specified code
+ *
+ * ### Exit Code Guidelines
+ * - **EXIT_CODES.SUCCESS (0)**: Command completed successfully
+ * - **EXIT_CODES.GENERAL_ERROR (1)**: Unexpected errors, system failures, unhandled exceptions
+ * - **EXIT_CODES.INVALID_USAGE (2)**: User provided invalid arguments, flags, or usage patterns
+ * - **EXIT_CODES.ENVIRONMENT_ERROR (3)**: Missing prerequisites, config not found, environment setup issues
+ *
+ * @module lib/errors
+ */
+import { type ExitCode } from '../types/index.js';
+/**
+ * Base error class for AI Workflow CLI.
+ * All custom errors extend this class and include an exit code.
+ *
+ * @example
+ * ```typescript
+ * throw new AiwError('Unexpected system error occurred. Check logs for details.', EXIT_CODES.GENERAL_ERROR)
+ * ```
+ */
+export declare class AiwError extends Error {
+    readonly exitCode: ExitCode;
+    constructor(message: string, exitCode?: ExitCode);
+}
+/**
+ * Error thrown when AIW configuration cannot be found.
+ * Indicates AIW_DIR is not set or points to a non-existent directory.
+ * Exit code: 3 (ENVIRONMENT_ERROR)
+ *
+ * @example
+ * ```typescript
+ * throw new ConfigNotFoundError('AIW_DIR not found. Set AIW_DIR env var or run \'aiw setup\'.')
+ * ```
+ */
+export declare class ConfigNotFoundError extends AiwError {
+    constructor(message: string);
+}
+/**
+ * Error thrown when environment prerequisites are missing.
+ * Used for missing dependencies, required tools not in PATH, or system requirements not met.
+ * Exit code: 3 (ENVIRONMENT_ERROR)
+ *
+ * @example
+ * ```typescript
+ * throw new EnvironmentError('Claude Code CLI not found in PATH. Install from https://claude.ai.')
+ * ```
+ */
+export declare class EnvironmentError extends AiwError {
+    constructor(message: string);
+}
+/**
+ * Error thrown when user provides invalid arguments or usage.
+ * Used for user-fixable errors like invalid flags or missing required arguments.
+ * Exit code: 2 (INVALID_USAGE)
+ *
+ * @example
+ * ```typescript
+ * throw new InvalidUsageError('Invalid --format value \'xyz\'. Use \'json\' or \'text\'.')
+ * ```
+ */
+export declare class InvalidUsageError extends AiwError {
+    constructor(message: string);
+}
+/**
+ * Error thrown when process spawning fails.
+ * Used for spawn errors like ENOENT (command not found) or EACCES (permission denied).
+ * Exit code: 3 (ENVIRONMENT_ERROR)
+ *
+ * @example
+ * ```typescript
+ * throw new ProcessSpawnError('Command not found: claude. Install Claude Code from https://claude.ai/download.')
+ * ```
+ */
+export declare class ProcessSpawnError extends AiwError {
+    readonly code?: string | undefined;
+    constructor(message: string, code?: string | undefined);
+}
+/**
+ * Format error message following AI Workflow CLI convention.
+ * @param what - Description of what went wrong
+ * @param howToFix - Actionable steps to fix the problem
+ * @returns Formatted error message in format: "{what}. {howToFix}."
+ * @example
+ * formatErrorMessage(
+ *   'AIW_DIR directory not found',
+ *   'Set AIW_DIR env var or run "aiw setup"'
+ * )
+ * // Returns: "AIW_DIR directory not found. Set AIW_DIR env var or run \"aiw setup\"."
+ */
+export declare function formatErrorMessage(what: string, howToFix: string): string;

package/dist/lib/errors.js

@@ -0,0 +1,145 @@
+/**
+ * @file Error handling classes and utilities for AI Workflow CLI.
+ *
+ * This module provides:
+ * - Custom error classes with exit codes
+ * - Error message formatting utilities
+ * - Error handling patterns for commands
+ *
+ * ## Error Handling Patterns for Commands
+ *
+ * ### Basic Pattern (Recommended)
+ * ```typescript
+ * import {Command} from '@oclif/core'
+ * import {ConfigNotFoundError, InvalidUsageError} from '../lib/errors.js'
+ *
+ * export default class LaunchCommand extends Command {
+ *   async run() {
+ *     try {
+ *       const config = await loadConfig()
+ *       await launchClaude(config)
+ *     } catch (error) {
+ *       if (error instanceof ConfigNotFoundError) {
+ *         this.error(error.message, {exit: error.exitCode})
+ *       }
+ *       if (error instanceof InvalidUsageError) {
+ *         this.error(error.message, {exit: error.exitCode})
+ *       }
+ *       this.error(`Unexpected error: ${error.message}`, {exit: EXIT_CODES.GENERAL_ERROR})
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * ### Using this.error() vs throwing custom errors
+ * - **Throw custom errors** in library code (src/lib/) for business logic failures
+ * - **Catch and translate** in commands using this.error() for user-facing output
+ * - **this.error()** automatically outputs to stderr and exits with specified code
+ *
+ * ### Exit Code Guidelines
+ * - **EXIT_CODES.SUCCESS (0)**: Command completed successfully
+ * - **EXIT_CODES.GENERAL_ERROR (1)**: Unexpected errors, system failures, unhandled exceptions
+ * - **EXIT_CODES.INVALID_USAGE (2)**: User provided invalid arguments, flags, or usage patterns
+ * - **EXIT_CODES.ENVIRONMENT_ERROR (3)**: Missing prerequisites, config not found, environment setup issues
+ *
+ * @module lib/errors
+ */
+import { EXIT_CODES } from '../types/index.js';
+/**
+ * Base error class for AI Workflow CLI.
+ * All custom errors extend this class and include an exit code.
+ *
+ * @example
+ * ```typescript
+ * throw new AiwError('Unexpected system error occurred. Check logs for details.', EXIT_CODES.GENERAL_ERROR)
+ * ```
+ */
+export class AiwError extends Error {
+    exitCode;
+    constructor(message, exitCode = EXIT_CODES.GENERAL_ERROR) {
+        super(message);
+        this.exitCode = exitCode;
+        this.name = 'AiwError';
+    }
+}
+/**
+ * Error thrown when AIW configuration cannot be found.
+ * Indicates AIW_DIR is not set or points to a non-existent directory.
+ * Exit code: 3 (ENVIRONMENT_ERROR)
+ *
+ * @example
+ * ```typescript
+ * throw new ConfigNotFoundError('AIW_DIR not found. Set AIW_DIR env var or run \'aiw setup\'.')
+ * ```
+ */
+export class ConfigNotFoundError extends AiwError {
+    constructor(message) {
+        super(message, EXIT_CODES.ENVIRONMENT_ERROR);
+        this.name = 'ConfigNotFoundError';
+    }
+}
+/**
+ * Error thrown when environment prerequisites are missing.
+ * Used for missing dependencies, required tools not in PATH, or system requirements not met.
+ * Exit code: 3 (ENVIRONMENT_ERROR)
+ *
+ * @example
+ * ```typescript
+ * throw new EnvironmentError('Claude Code CLI not found in PATH. Install from https://claude.ai.')
+ * ```
+ */
+export class EnvironmentError extends AiwError {
+    constructor(message) {
+        super(message, EXIT_CODES.ENVIRONMENT_ERROR);
+        this.name = 'EnvironmentError';
+    }
+}
+/**
+ * Error thrown when user provides invalid arguments or usage.
+ * Used for user-fixable errors like invalid flags or missing required arguments.
+ * Exit code: 2 (INVALID_USAGE)
+ *
+ * @example
+ * ```typescript
+ * throw new InvalidUsageError('Invalid --format value \'xyz\'. Use \'json\' or \'text\'.')
+ * ```
+ */
+export class InvalidUsageError extends AiwError {
+    constructor(message) {
+        super(message, EXIT_CODES.INVALID_USAGE);
+        this.name = 'InvalidUsageError';
+    }
+}
+/**
+ * Error thrown when process spawning fails.
+ * Used for spawn errors like ENOENT (command not found) or EACCES (permission denied).
+ * Exit code: 3 (ENVIRONMENT_ERROR)
+ *
+ * @example
+ * ```typescript
+ * throw new ProcessSpawnError('Command not found: claude. Install Claude Code from https://claude.ai/download.')
+ * ```
+ */
+export class ProcessSpawnError extends AiwError {
+    code;
+    constructor(message, code) {
+        super(message, EXIT_CODES.ENVIRONMENT_ERROR);
+        this.code = code;
+        this.name = 'ProcessSpawnError';
+    }
+}
+/**
+ * Format error message following AI Workflow CLI convention.
+ * @param what - Description of what went wrong
+ * @param howToFix - Actionable steps to fix the problem
+ * @returns Formatted error message in format: "{what}. {howToFix}."
+ * @example
+ * formatErrorMessage(
+ *   'AIW_DIR directory not found',
+ *   'Set AIW_DIR env var or run "aiw setup"'
+ * )
+ * // Returns: "AIW_DIR directory not found. Set AIW_DIR env var or run \"aiw setup\"."
+ */
+export function formatErrorMessage(what, howToFix) {
+    return `${what}. ${howToFix}.`;
+}

package/dist/lib/generic-merge.d.ts

@@ -0,0 +1,74 @@
+/**
+ * @file Generic merge utilities for configuration merging.
+ *
+ * This module provides reusable utilities for merging arrays with deduplication
+ * and merging configuration objects by event type. Used by hook merger modules
+ * to eliminate code duplication.
+ *
+ * ## Usage
+ * ```typescript
+ * import { mergeArraysWithDedup, mergeConfigByEventType } from '../lib/generic-merge.js'
+ *
+ * // Merge arrays with custom equality
+ * const merged = mergeArraysWithDedup(existing, template, (a, b) => a.id === b.id)
+ *
+ * // Merge config objects by event type
+ * const mergedConfig = mergeConfigByEventType(
+ *   existingConfig,
+ *   templateConfig,
+ *   (existing, template) => mergeArraysWithDedup(existing, template, areEqual)
+ * )
+ * ```
+ *
+ * @module lib/generic-merge
+ */
+/**
+ * Merge two arrays with deduplication based on custom equality function.
+ *
+ * Items from the template array are appended to the existing array only if
+ * no equivalent item exists. Order is preserved: existing items first.
+ *
+ * @template T - Type of array elements
+ * @param existing - Existing array (preserved in order)
+ * @param template - Template array to merge (items appended if not duplicate)
+ * @param areEqual - Function to check if two items are equivalent
+ * @returns New merged array with duplicates removed
+ *
+ * @example
+ * ```typescript
+ * const merged = mergeArraysWithDedup(
+ *   [{id: 1, name: 'a'}],
+ *   [{id: 1, name: 'b'}, {id: 2, name: 'c'}],
+ *   (a, b) => a.id === b.id
+ * )
+ * // Result: [{id: 1, name: 'a'}, {id: 2, name: 'c'}]
+ * ```
+ */
+export declare function mergeArraysWithDedup<T>(existing: T[], template: T[], areEqual: (a: T, b: T) => boolean): T[];
+/**
+ * Merge configuration objects organized by event type.
+ *
+ * Each configuration maps event types to arrays of items. This function
+ * merges configurations by:
+ * 1. Collecting all event types from both configurations
+ * 2. For each event type, merging the arrays using the provided merge function
+ *
+ * @template TEventType - Type of event type keys (typically string union)
+ * @template TItem - Type of items in the arrays
+ * @template TConfig - Type of the configuration object
+ * @param existing - Existing configuration (may be undefined)
+ * @param template - Template configuration to merge (may be undefined)
+ * @param mergeArrays - Function to merge arrays for a single event type
+ * @returns New merged configuration
+ *
+ * @example
+ * ```typescript
+ * const mergedConfig = mergeConfigByEventType(
+ *   {click: [handler1], hover: [handler2]},
+ *   {click: [handler3], focus: [handler4]},
+ *   (existing, template) => mergeArraysWithDedup(existing, template, areEqual)
+ * )
+ * // Result: {click: [handler1, handler3], hover: [handler2], focus: [handler4]}
+ * ```
+ */
+export declare function mergeConfigByEventType<TEventType extends string, TItem, TConfig extends Partial<Record<TEventType, TItem[]>>>(existing: TConfig | undefined, template: TConfig | undefined, mergeArrays: (existing: TItem[], template: TItem[]) => TItem[]): TConfig;