aiwcli 0.9.0

package/dist/lib/tty-detection.js

@@ -0,0 +1,83 @@
+/**
+ * TTY Detection Utilities
+ *
+ * Provides cross-platform TTY detection for controlling color output and spinners.
+ * Respects NO_COLOR and FORCE_COLOR environment variables per standard conventions.
+ */
+import { isQuietMode as getQuietMode } from './quiet.js';
+/**
+ * Check if stdout is a TTY (terminal).
+ * Returns true for interactive terminal, false for piped/redirected output.
+ * @param proc - Optional process-like object for testing (defaults to global process)
+ */
+export function isTTY(proc = process) {
+    return proc.stdout.isTTY === true;
+}
+/**
+ * Check if stderr is a TTY (terminal).
+ * Useful for determining if error output should use colors.
+ * @param proc - Optional process-like object for testing (defaults to global process)
+ */
+export function isStderrTTY(proc = process) {
+    return proc.stderr?.isTTY === true;
+}
+/**
+ * Determine if colors should be used in output.
+ * Respects NO_COLOR and FORCE_COLOR environment variables.
+ *
+ * Priority:
+ * 1. NO_COLOR (if set, always disable)
+ * 2. FORCE_COLOR (if set, use level 0-3)
+ * 3. TTY detection (colors only in TTY)
+ *
+ * @param proc - Optional process-like object for testing (defaults to global process)
+ */
+export function shouldUseColors(proc = process) {
+    const env = proc.env ?? process.env;
+    const noColor = env.NO_COLOR;
+    const forceColor = env.FORCE_COLOR;
+    // NO_COLOR takes precedence (any value disables colors)
+    if (noColor !== undefined) {
+        return false;
+    }
+    // FORCE_COLOR overrides TTY detection
+    if (forceColor !== undefined) {
+        const level = Number.parseInt(forceColor, 10);
+        return level > 0;
+    }
+    // Default: colors only in TTY
+    return isTTY(proc);
+}
+/**
+ * Check if quiet mode is enabled from flags.
+ * Quiet mode suppresses informational output (errors still shown).
+ * @param flags - Optional flags object
+ * @param flags.quiet - Quiet mode flag
+ */
+export function isQuietMode(flags) {
+    // If flags provided, use them directly (for testing)
+    if (flags !== undefined) {
+        return flags?.quiet === true;
+    }
+    // Otherwise use module-level state
+    return getQuietMode();
+}
+/**
+ * Determine if progress spinners should be shown.
+ * Spinners only make sense in interactive terminals.
+ * Automatically disabled in CI environments and quiet mode.
+ * @param flags - Optional flags object with quiet mode
+ * @param proc - Optional process-like object for testing (defaults to global process)
+ */
+export function shouldShowSpinners(flags, proc = process) {
+    const env = proc.env ?? process.env;
+    // Spinners disabled in CI environments
+    if (env.CI) {
+        return false;
+    }
+    // Spinners disabled in quiet mode
+    if (isQuietMode(flags)) {
+        return false;
+    }
+    return isTTY(proc);
+}

package/dist/lib/user-utils.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Detect username from git config or environment variables.
+ * Priority: git config user.name > USER env > USERNAME env > fallback to "User"
+ */
+export declare function detectUsername(): Promise<string>;

package/dist/lib/user-utils.js

@@ -0,0 +1,23 @@
+import { execSync } from 'node:child_process';
+/**
+ * Detect username from git config or environment variables.
+ * Priority: git config user.name > USER env > USERNAME env > fallback to "User"
+ */
+export async function detectUsername() {
+    // Try git config first
+    try {
+        const gitUser = execSync('git config user.name', { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
+        const username = gitUser.trim();
+        if (username)
+            return username;
+    }
+    catch {
+        // Git command failed or not configured, continue to env vars
+    }
+    // Try environment variables
+    const envUser = process.env['USER'] ?? process.env['USERNAME'];
+    if (envUser)
+        return envUser;
+    // Fallback
+    return 'User';
+}

package/dist/lib/version.d.ts

@@ -0,0 +1,99 @@
+/**
+ * @file Version detection and compatibility checking for Claude Code CLI.
+ *
+ * This module provides:
+ * - Claude Code version detection via `claude --version`
+ * - Semantic version compatibility checking
+ * - Graceful degradation when version unavailable
+ *
+ * ## Usage Pattern
+ *
+ * ```typescript
+ * import {getClaudeCodeVersion, checkVersionCompatibility} from '../lib/version.js'
+ *
+ * const version = await getClaudeCodeVersion()
+ * const versionCheck = checkVersionCompatibility(version)
+ *
+ * if (versionCheck.warning) {
+ *   this.warn(versionCheck.warning)
+ * }
+ *
+ * if (this.debugEnabled) {
+ *   this.debug(`Claude Code version: ${versionCheck.version || 'unknown'}`)
+ * }
+ * ```
+ *
+ * @module lib/version
+ */
+/**
+ * Minimum supported Claude Code version.
+ * Versions below this will trigger a compatibility warning.
+ */
+export declare const MIN_CLAUDE_CODE_VERSION = "0.1.0";
+/**
+ * Known incompatible Claude Code versions.
+ * These versions have confirmed issues with AI Workflow CLI.
+ */
+export declare const INCOMPATIBLE_VERSIONS: string[];
+/**
+ * Result of version compatibility check.
+ */
+export interface VersionCheckResult {
+    /**
+     * Whether the version is compatible with AI Workflow CLI.
+     * If version is unknown, assumes compatible (graceful degradation).
+     */
+    compatible: boolean;
+    /**
+     * Detected version string (e.g., "0.1.0") or null if unavailable.
+     */
+    version: null | string;
+    /**
+     * Warning message if incompatible or version unavailable.
+     * Undefined if version is compatible.
+     */
+    warning?: string;
+}
+/**
+ * Detects Claude Code version by executing `claude --version`.
+ *
+ * Parses version output formats:
+ * - "claude 0.1.0"
+ * - "claude version 0.1.0"
+ *
+ * Returns null on any failure (command not found, invalid output, etc.)
+ * to support graceful degradation.
+ *
+ * @returns Version string (e.g., "0.1.0") or null if unavailable
+ *
+ * @example
+ * ```typescript
+ * const version = await getClaudeCodeVersion()
+ * if (version) {
+ *   console.log(`Claude Code version: ${version}`)
+ * } else {
+ *   console.log('Claude Code version unavailable')
+ * }
+ * ```
+ */
+export declare function getClaudeCodeVersion(): Promise<null | string>;
+/**
+ * Checks if a Claude Code version is compatible with AI Workflow CLI.
+ *
+ * Compatibility rules:
+ * 1. Version must be >= MIN_CLAUDE_CODE_VERSION
+ * 2. Version must not be in INCOMPATIBLE_VERSIONS list
+ * 3. If version is null/unknown, assumes compatible (graceful degradation)
+ *
+ * @param version - Version string (e.g., "0.1.0") or null if unavailable
+ * @returns Compatibility check result with version, compatible flag, and optional warning
+ *
+ * @example
+ * ```typescript
+ * const result = checkVersionCompatibility('0.1.0')
+ * if (result.warning) {
+ *   this.warn(result.warning)
+ * }
+ * ```
+ */
+export declare function checkVersionCompatibility(version: null | string | undefined): VersionCheckResult;

package/dist/lib/version.js

@@ -0,0 +1,144 @@
+/**
+ * @file Version detection and compatibility checking for Claude Code CLI.
+ *
+ * This module provides:
+ * - Claude Code version detection via `claude --version`
+ * - Semantic version compatibility checking
+ * - Graceful degradation when version unavailable
+ *
+ * ## Usage Pattern
+ *
+ * ```typescript
+ * import {getClaudeCodeVersion, checkVersionCompatibility} from '../lib/version.js'
+ *
+ * const version = await getClaudeCodeVersion()
+ * const versionCheck = checkVersionCompatibility(version)
+ *
+ * if (versionCheck.warning) {
+ *   this.warn(versionCheck.warning)
+ * }
+ *
+ * if (this.debugEnabled) {
+ *   this.debug(`Claude Code version: ${versionCheck.version || 'unknown'}`)
+ * }
+ * ```
+ *
+ * @module lib/version
+ */
+import { exec } from 'node:child_process';
+import { promisify } from 'node:util';
+const execAsync = promisify(exec);
+/**
+ * Minimum supported Claude Code version.
+ * Versions below this will trigger a compatibility warning.
+ */
+export const MIN_CLAUDE_CODE_VERSION = '0.1.0';
+/**
+ * Known incompatible Claude Code versions.
+ * These versions have confirmed issues with AI Workflow CLI.
+ */
+export const INCOMPATIBLE_VERSIONS = ['0.0.9'];
+/**
+ * Detects Claude Code version by executing `claude --version`.
+ *
+ * Parses version output formats:
+ * - "claude 0.1.0"
+ * - "claude version 0.1.0"
+ *
+ * Returns null on any failure (command not found, invalid output, etc.)
+ * to support graceful degradation.
+ *
+ * @returns Version string (e.g., "0.1.0") or null if unavailable
+ *
+ * @example
+ * ```typescript
+ * const version = await getClaudeCodeVersion()
+ * if (version) {
+ *   console.log(`Claude Code version: ${version}`)
+ * } else {
+ *   console.log('Claude Code version unavailable')
+ * }
+ * ```
+ */
+export async function getClaudeCodeVersion() {
+    try {
+        // Set 5 second timeout to prevent hanging
+        const { stdout } = await execAsync('claude --version', { timeout: 5000 });
+        // Parse version from output formats:
+        // - New format: "2.1.3 (Claude Code)"
+        // - Old format: "claude 0.1.0" or "claude version 0.1.0"
+        const newFormatMatch = stdout.match(/^(\d+\.\d+\.\d+)\s+\(Claude Code\)/i);
+        if (newFormatMatch?.[1]) {
+            return newFormatMatch[1];
+        }
+        const oldFormatMatch = stdout.match(/claude\s+(?:version\s+)?(\d+\.\d+\.\d+)/i);
+        return oldFormatMatch?.[1] ?? null;
+    }
+    catch {
+        // Command not found, execution failed, timeout, or other error
+        // Gracefully return null to allow launch to continue
+        return null;
+    }
+}
+/**
+ * Checks if a Claude Code version is compatible with AI Workflow CLI.
+ *
+ * Compatibility rules:
+ * 1. Version must be >= MIN_CLAUDE_CODE_VERSION
+ * 2. Version must not be in INCOMPATIBLE_VERSIONS list
+ * 3. If version is null/unknown, assumes compatible (graceful degradation)
+ *
+ * @param version - Version string (e.g., "0.1.0") or null if unavailable
+ * @returns Compatibility check result with version, compatible flag, and optional warning
+ *
+ * @example
+ * ```typescript
+ * const result = checkVersionCompatibility('0.1.0')
+ * if (result.warning) {
+ *   this.warn(result.warning)
+ * }
+ * ```
+ */
+export function checkVersionCompatibility(version) {
+    // Handle null/undefined version (graceful degradation)
+    if (!version) {
+        return {
+            compatible: true, // Assume compatible if unknown
+            version: null,
+            warning: 'Claude Code version could not be determined. Proceeding with caution.',
+        };
+    }
+    // Check known incompatible versions first
+    if (INCOMPATIBLE_VERSIONS.includes(version)) {
+        return {
+            compatible: false,
+            version,
+            warning: `Claude Code version ${version} has known issues with AI Workflow CLI. Please upgrade to ${MIN_CLAUDE_CODE_VERSION} or later.`,
+        };
+    }
+    // Parse version numbers for semantic comparison
+    const versionParts = version.split('.').map(Number);
+    const minVersionParts = MIN_CLAUDE_CODE_VERSION.split('.').map(Number);
+    const major = versionParts[0] ?? 0;
+    const minor = versionParts[1] ?? 0;
+    const patch = versionParts[2] ?? 0;
+    const minMajor = minVersionParts[0] ?? 0;
+    const minMinor = minVersionParts[1] ?? 0;
+    const minPatch = minVersionParts[2] ?? 0;
+    // Check if version meets minimum requirement
+    const isBelowMinimum = major < minMajor ||
+        (major === minMajor && minor < minMinor) ||
+        (major === minMajor && minor === minMinor && patch < minPatch);
+    if (isBelowMinimum) {
+        return {
+            compatible: false,
+            version,
+            warning: `Claude Code version ${version} is below minimum ${MIN_CLAUDE_CODE_VERSION}. Some features may not work correctly. Please upgrade Claude Code.`,
+        };
+    }
+    // Version is compatible
+    return {
+        compatible: true,
+        version,
+    };
+}

package/dist/lib/watch-templates.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * Watch templates directory and copy changes to dist.
+ * Used for development workflow to auto-sync template changes.
+ */
+export {};

package/dist/lib/watch-templates.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+/**
+ * Watch templates directory and copy changes to dist.
+ * Used for development workflow to auto-sync template changes.
+ */
+import { copyFile, mkdir } from 'node:fs/promises';
+import { dirname, join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { watch } from 'chokidar';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SRC_TEMPLATES = join(__dirname, '..', 'templates');
+const DIST_TEMPLATES = join(__dirname, '..', '..', 'dist', 'templates');
+/**
+ * Copy a file from src/templates to dist/templates preserving structure.
+ */
+async function copyTemplate(filePath) {
+    const relativePath = relative(SRC_TEMPLATES, filePath);
+    const destPath = join(DIST_TEMPLATES, relativePath);
+    try {
+        await mkdir(dirname(destPath), { recursive: true });
+        await copyFile(filePath, destPath);
+        logChange('copied', relativePath);
+    }
+    catch (error) {
+        logError(`Failed to copy ${relativePath}`, error);
+    }
+}
+/**
+ * Log a change with timestamp.
+ */
+function logChange(action, path) {
+    const timestamp = new Date().toLocaleTimeString();
+    const supportsColor = process.stdout.isTTY;
+    if (supportsColor) {
+        console.log(`\u001B[2m[${timestamp}]\u001B[0m \u001B[32m${action}\u001B[0m ${path}`);
+    }
+    else {
+        console.log(`[${timestamp}] ${action} ${path}`);
+    }
+}
+/**
+ * Log an error.
+ */
+function logError(message, error) {
+    const timestamp = new Date().toLocaleTimeString();
+    console.error(`[${timestamp}] \u001B[31merror\u001B[0m ${message}:`, error);
+}
+/**
+ * Start watching templates directory.
+ */
+function startWatching() {
+    console.log('Watching templates for changes...');
+    console.log(`  Source: ${SRC_TEMPLATES}`);
+    console.log(`  Dest:   ${DIST_TEMPLATES}`);
+    console.log('');
+    const watcher = watch(SRC_TEMPLATES, {
+        ignoreInitial: true,
+        persistent: true,
+    });
+    watcher.on('add', copyTemplate);
+    watcher.on('change', copyTemplate);
+    watcher.on('error', (error) => logError('Watcher error', error));
+    // Handle graceful shutdown
+    process.on('SIGINT', () => {
+        console.log('\nStopping template watcher...');
+        watcher.close().catch(() => { });
+    });
+    process.on('SIGTERM', () => {
+        watcher.close().catch(() => { });
+    });
+}
+// Run if executed directly
+startWatching();

package/dist/lib/windsurf-hooks-hierarchy.d.ts

@@ -0,0 +1,30 @@
+import type { WindsurfHooks } from './windsurf-hooks-types.js';
+/**
+ * Read Windsurf hooks from file
+ *
+ * @param path - Path to hooks.json file
+ * @returns Parsed hooks or undefined if file doesn't exist or is invalid
+ */
+export declare function readWindsurfHooks(path: string): Promise<undefined | WindsurfHooks>;
+/**
+ * Write Windsurf hooks to file
+ *
+ * Creates parent directories if they don't exist
+ * Backs up existing file before writing
+ *
+ * @param path - Path to hooks.json file
+ * @param hooks - Hooks to write
+ * @throws Error if write fails
+ */
+export declare function writeWindsurfHooks(path: string, hooks: WindsurfHooks): Promise<void>;
+/**
+ * Get the target hooks file for template hook merging
+ *
+ * Strategy:
+ * - If project hooks exist, merge into that file
+ * - Otherwise, create project hooks with template hooks
+ *
+ * @param projectDir - Project directory path
+ * @returns Path to target hooks file
+ */
+export declare function getTargetHooksFile(projectDir: string): string;

package/dist/lib/windsurf-hooks-hierarchy.js

@@ -0,0 +1,66 @@
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Check if file exists
+ */
+async function fileExists(path) {
+    try {
+        await fs.access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Read Windsurf hooks from file
+ *
+ * @param path - Path to hooks.json file
+ * @returns Parsed hooks or undefined if file doesn't exist or is invalid
+ */
+export async function readWindsurfHooks(path) {
+    try {
+        const content = await fs.readFile(path, 'utf8');
+        return JSON.parse(content);
+    }
+    catch {
+        // File doesn't exist or invalid JSON
+        return undefined;
+    }
+}
+/**
+ * Write Windsurf hooks to file
+ *
+ * Creates parent directories if they don't exist
+ * Backs up existing file before writing
+ *
+ * @param path - Path to hooks.json file
+ * @param hooks - Hooks to write
+ * @throws Error if write fails
+ */
+export async function writeWindsurfHooks(path, hooks) {
+    // 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 hooks with pretty formatting
+    const content = JSON.stringify(hooks, null, 2);
+    await fs.writeFile(path, content, 'utf8');
+}
+/**
+ * Get the target hooks file for template hook merging
+ *
+ * Strategy:
+ * - If project hooks exist, merge into that file
+ * - Otherwise, create project hooks with template hooks
+ *
+ * @param projectDir - Project directory path
+ * @returns Path to target hooks file
+ */
+export function getTargetHooksFile(projectDir) {
+    return join(projectDir, '.windsurf', 'hooks.json');
+}

package/dist/lib/windsurf-hooks-merger.d.ts

@@ -0,0 +1,26 @@
+import type { WindsurfHooks, WindsurfHooksConfig } from './windsurf-hooks-types.js';
+/**
+ * Merge hooks configurations from template into existing
+ *
+ * Strategy:
+ * - For each event type in template hooks
+ * - Concatenate with existing hooks for that event
+ * - Deduplicate based on command configuration
+ * - Maintain order: existing hooks first, then template hooks
+ *
+ * @param existing - Existing hooks configuration (will not be modified)
+ * @param template - Template hooks configuration to merge
+ * @returns New merged hooks configuration
+ */
+export declare function mergeWindsurfHooksConfig(existing: undefined | WindsurfHooksConfig, template: undefined | WindsurfHooksConfig): WindsurfHooksConfig;
+/**
+ * Merge complete Windsurf hooks configurations
+ *
+ * Strategy:
+ * - Deep merge hooks using mergeWindsurfHooksConfig function
+ *
+ * @param existing - Existing hooks (will not be modified)
+ * @param template - Template hooks to merge
+ * @returns New merged hooks configuration
+ */
+export declare function mergeWindsurfHooks(existing: undefined | WindsurfHooks, template: undefined | WindsurfHooks): WindsurfHooks;

package/dist/lib/windsurf-hooks-merger.js

@@ -0,0 +1,53 @@
+import { mergeArraysWithDedup, mergeConfigByEventType } from './generic-merge.js';
+/**
+ * Check if two hook commands are equivalent
+ */
+function areHookCommandsEqual(a, b) {
+    return (a.command === b.command &&
+        a.timeout === b.timeout &&
+        a.show_output === b.show_output &&
+        a.once === b.once);
+}
+/**
+ * Merge hooks configurations from template into existing
+ *
+ * Strategy:
+ * - For each event type in template hooks
+ * - Concatenate with existing hooks for that event
+ * - Deduplicate based on command configuration
+ * - Maintain order: existing hooks first, then template hooks
+ *
+ * @param existing - Existing hooks configuration (will not be modified)
+ * @param template - Template hooks configuration to merge
+ * @returns New merged hooks configuration
+ */
+export function mergeWindsurfHooksConfig(existing, template) {
+    return mergeConfigByEventType(existing, template, (existingCommands, templateCommands) => mergeArraysWithDedup(existingCommands, templateCommands, areHookCommandsEqual));
+}
+/**
+ * Merge complete Windsurf hooks configurations
+ *
+ * Strategy:
+ * - Deep merge hooks using mergeWindsurfHooksConfig function
+ *
+ * @param existing - Existing hooks (will not be modified)
+ * @param template - Template hooks to merge
+ * @returns New merged hooks configuration
+ */
+export function mergeWindsurfHooks(existing, template) {
+    // If no template hooks, return existing (or empty hooks)
+    if (!template || !template.hooks || Object.keys(template.hooks).length === 0) {
+        return existing || { hooks: {} };
+    }
+    // If no existing hooks, return template
+    if (!existing || !existing.hooks || Object.keys(existing.hooks).length === 0) {
+        return template;
+    }
+    // Merge hooks using dedicated function
+    const mergedHooksConfig = mergeWindsurfHooksConfig(existing.hooks, template.hooks);
+    // Create merged hooks
+    const merged = {
+        hooks: mergedHooksConfig,
+    };
+    return merged;
+}

package/dist/lib/windsurf-hooks-types.d.ts

@@ -0,0 +1,33 @@
+/**
+ * TypeScript interfaces for Windsurf Cascade hooks.json structure
+ * Based on Windsurf Cascade Hooks documentation
+ */
+/**
+ * Hook command configuration
+ */
+export interface WindsurfHookCommand {
+    /** Command to execute (bash, python, node, etc.) */
+    command: string;
+    /** Execute only once (for session-level hooks) */
+    once?: boolean;
+    /** Show output in Cascade UI */
+    show_output?: boolean;
+    /** Optional timeout in milliseconds */
+    timeout?: number;
+}
+/**
+ * Hook event types supported by Windsurf Cascade
+ */
+export type WindsurfHookEventType = 'post_execute_command' | 'post_model_response' | 'post_read_code' | 'post_user_prompt' | 'post_write_code' | 'pre_execute_command' | 'pre_model_response' | 'pre_read_code' | 'pre_user_prompt' | 'pre_write_code';
+/**
+ * Hooks configuration
+ * Maps event types to arrays of hook commands
+ */
+export type WindsurfHooksConfig = Partial<Record<WindsurfHookEventType, WindsurfHookCommand[]>>;
+/**
+ * Complete Windsurf hooks.json structure
+ */
+export interface WindsurfHooks {
+    /** Hook configurations */
+    hooks: WindsurfHooksConfig;
+}

package/dist/lib/windsurf-hooks-types.js

@@ -0,0 +1,5 @@
+/**
+ * TypeScript interfaces for Windsurf Cascade hooks.json structure
+ * Based on Windsurf Cascade Hooks documentation
+ */
+export {};