@aiwg/cli 0.0.0-bootstrap.0 → 2026.7.18

package/dist/src/cli/config-loader.js

@@ -0,0 +1,232 @@
+/**
+ * Configuration Loader
+ *
+ * Manages loading, validating, and merging AIWG CLI configurations from multiple sources.
+ * Supports .aiwgrc.json, package.json, and command-line overrides.
+ */
+import { readFile, access } from 'fs/promises';
+import { existsSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { constants } from 'fs';
+/**
+ * Configuration Loader class
+ */
+export class ConfigLoader {
+    configCache = null;
+    /**
+     * Load configuration from file or defaults
+     */
+    async load(configPath) {
+        // If cached, return it
+        if (this.configCache) {
+            return this.configCache;
+        }
+        // Start with defaults
+        let config = this.getDefaults();
+        // Try to load from .aiwgrc.json
+        if (configPath) {
+            const fileConfig = await this.loadFromFile(configPath);
+            if (fileConfig) {
+                config = this.merge([config, fileConfig]);
+            }
+        }
+        else {
+            // Look for .aiwgrc.json in current directory and parent directories
+            const foundConfig = await this.findConfigFile(process.cwd());
+            if (foundConfig) {
+                config = this.merge([config, foundConfig]);
+            }
+        }
+        // Try to load from package.json
+        const pkgPath = resolve(process.cwd(), 'package.json');
+        if (existsSync(pkgPath)) {
+            const pkgConfig = await this.loadFromPackageJson(pkgPath);
+            if (pkgConfig) {
+                config = this.merge([config, pkgConfig]);
+            }
+        }
+        // Validate merged config
+        const validation = this.validate(config);
+        if (!validation.valid) {
+            throw new Error(`Invalid configuration: ${validation.errors.join(', ')}`);
+        }
+        // Cache it
+        this.configCache = config;
+        return config;
+    }
+    /**
+     * Load configuration from .aiwgrc.json file
+     */
+    async loadFromFile(filePath) {
+        try {
+            await access(filePath, constants.R_OK);
+            const content = await readFile(filePath, 'utf-8');
+            const config = JSON.parse(content);
+            return config;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                return null;
+            }
+            throw new Error(`Failed to load config from ${filePath}: ${error}`);
+        }
+    }
+    /**
+     * Load configuration from package.json "aiwg" field
+     */
+    async loadFromPackageJson(pkgPath) {
+        try {
+            const content = await readFile(pkgPath, 'utf-8');
+            const pkg = JSON.parse(content);
+            return pkg.aiwg || null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Find config file by walking up directory tree
+     */
+    async findConfigFile(startDir) {
+        let currentDir = startDir;
+        const root = resolve('/');
+        while (currentDir !== root) {
+            const configPath = resolve(currentDir, '.aiwgrc.json');
+            if (existsSync(configPath)) {
+                return await this.loadFromFile(configPath);
+            }
+            const parentDir = dirname(currentDir);
+            if (parentDir === currentDir) {
+                break; // Reached root
+            }
+            currentDir = parentDir;
+        }
+        return null;
+    }
+    /**
+     * Merge multiple partial configs into one complete config
+     */
+    merge(configs) {
+        const result = this.getDefaults();
+        for (const config of configs) {
+            if (config.version)
+                result.version = config.version;
+            if (config.validation) {
+                result.validation = { ...result.validation, ...config.validation };
+            }
+            if (config.optimization) {
+                result.optimization = { ...result.optimization, ...config.optimization };
+            }
+            if (config.output) {
+                result.output = { ...result.output, ...config.output };
+            }
+            if (config.watch) {
+                result.watch = { ...result.watch, ...config.watch };
+            }
+            if (config.hooks) {
+                result.hooks = { ...result.hooks, ...config.hooks };
+            }
+        }
+        return result;
+    }
+    /**
+     * Validate configuration object
+     */
+    validate(config) {
+        const errors = [];
+        const warnings = [];
+        // Validate version
+        if (!config.version || !config.version.match(/^\d+\.\d+$/)) {
+            errors.push('Invalid version format (expected "1.0")');
+        }
+        // Validate validation config
+        if (config.validation.threshold < 0 || config.validation.threshold > 100) {
+            errors.push('Validation threshold must be between 0 and 100');
+        }
+        if (config.validation.context &&
+            !['academic', 'technical', 'executive', 'casual'].includes(config.validation.context)) {
+            errors.push('Invalid validation context');
+        }
+        // Validate optimization config
+        const validStrategies = ['specificity', 'examples', 'constraints', 'voice', 'anti_pattern'];
+        for (const strategy of config.optimization.strategies) {
+            if (!validStrategies.includes(strategy)) {
+                warnings.push(`Unknown optimization strategy: ${strategy}`);
+            }
+        }
+        // Validate output config
+        if (!['text', 'json', 'html', 'junit'].includes(config.output.format)) {
+            errors.push('Invalid output format (must be: text, json, html, or junit)');
+        }
+        // Validate watch config
+        if (config.watch.debounce < 0) {
+            errors.push('Watch debounce must be >= 0');
+        }
+        if (config.watch.patterns.length === 0) {
+            warnings.push('No watch patterns specified');
+        }
+        return {
+            valid: errors.length === 0,
+            errors,
+            warnings
+        };
+    }
+    /**
+     * Get default configuration
+     */
+    getDefaults() {
+        return {
+            version: '1.0',
+            validation: {
+                enabled: true,
+                threshold: 70,
+                context: undefined,
+                failOnCritical: true,
+                rules: []
+            },
+            optimization: {
+                enabled: true,
+                autoApply: false,
+                strategies: ['specificity', 'examples', 'constraints', 'anti_pattern'],
+                createBackup: true
+            },
+            output: {
+                format: 'text',
+                destination: undefined,
+                verbose: false,
+                colors: true
+            },
+            watch: {
+                enabled: false,
+                patterns: ['**/*.md', '**/*.txt'],
+                debounce: 500,
+                ignorePatterns: ['**/node_modules/**', '**/.git/**', '**/dist/**']
+            },
+            hooks: {
+                preCommit: false,
+                prePush: false,
+                hookPath: '.git/hooks'
+            }
+        };
+    }
+    /**
+     * Generate example config file content
+     */
+    generateExample() {
+        const example = this.getDefaults();
+        return JSON.stringify(example, null, 2);
+    }
+    /**
+     * Clear cached configuration
+     */
+    clearCache() {
+        this.configCache = null;
+    }
+    /**
+     * Override specific config values
+     */
+    override(config, overrides) {
+        return this.merge([config, overrides]);
+    }
+}
+//# sourceMappingURL=config-loader.js.map

package/dist/src/cli/env.js

@@ -0,0 +1,82 @@
+/**
+ * AIWG CLI Environment Detection
+ *
+ * Centralized helpers for detecting the runtime environment so handlers
+ * can make consistent interactive / non-interactive decisions.
+ *
+ * Phase 3 of the CLI Stabilization Epic (#920).
+ */
+/**
+ * Return true iff the CLI is running attached to an interactive terminal
+ * where it is safe to prompt the user.
+ *
+ * Conditions (all must hold):
+ *   - stdin  is a TTY
+ *   - stdout is a TTY
+ *   - TERM is not 'dumb'
+ *   - CI env var is not truthy (matches GitHub Actions, GitLab, CircleCI,
+ *     Travis, Buildkite, Jenkins, and most other CI systems)
+ *   - DEBIAN_FRONTEND is not 'noninteractive' (common in Docker images)
+ *
+ * Respects common CI convention: any of
+ *   CI, CONTINUOUS_INTEGRATION, BUILD_NUMBER, RUN_ID, GITHUB_ACTIONS,
+ *   GITLAB_CI, CIRCLECI, TRAVIS, BUILDKITE, JENKINS_URL
+ * set (to any truthy value) indicates a CI environment.
+ *
+ * Handlers MUST call this helper instead of re-deriving the check locally.
+ * Divergent isTTY checks scattered across handlers have caused bugs in the
+ * past (#918 audit findings).
+ */
+export function isInteractive() {
+    if (!process.stdin.isTTY)
+        return false;
+    if (!process.stdout.isTTY)
+        return false;
+    if (process.env['TERM'] === 'dumb')
+        return false;
+    if (process.env['DEBIAN_FRONTEND'] === 'noninteractive')
+        return false;
+    if (isCI())
+        return false;
+    return true;
+}
+/**
+ * Return true iff we're running in a continuous-integration environment.
+ * Checks the common CI env vars set by major CI systems.
+ */
+export function isCI() {
+    const ciVars = [
+        'CI',
+        'CONTINUOUS_INTEGRATION',
+        'BUILD_NUMBER',
+        'RUN_ID',
+        'GITHUB_ACTIONS',
+        'GITLAB_CI',
+        'CIRCLECI',
+        'TRAVIS',
+        'BUILDKITE',
+        'JENKINS_URL',
+        'TF_BUILD', // Azure DevOps
+        'TEAMCITY_VERSION',
+    ];
+    for (const v of ciVars) {
+        const val = process.env[v];
+        if (val && val !== '0' && val.toLowerCase() !== 'false')
+            return true;
+    }
+    return false;
+}
+/**
+ * Return true iff colored output should be emitted.
+ *
+ * Honors NO_COLOR (per https://no-color.org) and FORCE_COLOR.
+ * Requires stdout (or the passed stream) to be a TTY.
+ */
+export function shouldUseColor(stream = process.stdout) {
+    if (process.env['NO_COLOR'])
+        return false;
+    if (process.env['FORCE_COLOR'] && process.env['FORCE_COLOR'] !== '0')
+        return true;
+    return !!stream.isTTY;
+}
+//# sourceMappingURL=env.js.map

package/dist/src/cli/errors.js

@@ -0,0 +1,150 @@
+/**
+ * AIWG Structured Errors
+ *
+ * Every intentional error thrown by CLI code should be an `AiwgError` with:
+ *   - `code`   — stable UPPER_SNAKE_CASE identifier (ERR_CATEGORY_REASON)
+ *   - `exitCode` — process exit code (see EXIT_CODES table below)
+ *   - `hint`   — optional one-line user-facing hint with a suggested next action
+ *   - `cause`  — optional underlying error for chain preservation (ES2022)
+ *
+ * The top-level formatter in `bin/aiwg.mjs` prints a single-line message and
+ * only reveals stack traces when `AIWG_DEBUG=1` or `--verbose` is set.
+ *
+ * Code naming: category-prefixed uppercase snake_case.
+ *   ERR_CONFIG_*     — problems reading/writing .aiwg/aiwg.config
+ *   ERR_NETWORK_*    — timeouts, unreachable services, HTTP errors
+ *   ERR_USAGE_*      — bad flags, unknown commands, missing required args
+ *   ERR_FS_*         — filesystem errors (permission, ENOENT outside config)
+ *   ERR_SANDBOX_*    — sandbox-specific failures
+ *   ERR_INTERNAL     — unexpected bugs (last resort; prefer a specific code)
+ *
+ * Phase 4 of the CLI Stabilization Epic (#921).
+ */
+/**
+ * Process exit codes used by the CLI. Pragmatic subset of sysexits.h —
+ * enough categorization for scripts to branch on without full sysexits
+ * ceremony.
+ */
+export const EXIT_CODES = {
+    /** Command completed successfully. */
+    OK: 0,
+    /** General / uncategorized failure. */
+    GENERAL: 1,
+    /** User error: unknown command, bad flag, missing required argument. */
+    USAGE: 2,
+    /** Filesystem write failure: permission denied, disk full, read-only. */
+    CANT_CREATE: 73,
+    /** Config file missing, malformed, or otherwise unusable. */
+    CONFIG: 78,
+    /** Interrupted by SIGINT (Ctrl-C). 128 + 2. */
+    INTERRUPTED: 130,
+    /** Terminated by SIGTERM. 128 + 15. */
+    TERMINATED: 143,
+};
+/**
+ * Structured CLI error with a stable code and a prescribed exit code.
+ *
+ * Always throw these from handler code instead of bare `Error` so the
+ * top-level formatter can render consistent output and so tests can assert
+ * on the error code rather than brittle message strings.
+ */
+export class AiwgError extends Error {
+    code;
+    exitCode;
+    hint;
+    constructor(init) {
+        super(init.message, init.cause !== undefined ? { cause: init.cause } : undefined);
+        this.name = 'AiwgError';
+        this.code = init.code;
+        this.exitCode = init.exitCode ?? EXIT_CODES.GENERAL;
+        if (init.hint !== undefined)
+            this.hint = init.hint;
+        // Stabilize stack trace capture across engines.
+        if (typeof Error.captureStackTrace === 'function') {
+            Error.captureStackTrace(this, AiwgError);
+        }
+    }
+}
+/**
+ * Convenience checker — ts-narrows an unknown to AiwgError. Avoids importing
+ * the class just for a typeof-like check at catch sites.
+ */
+export function isAiwgError(err) {
+    return err instanceof AiwgError;
+}
+/**
+ * Format an error for terminal output. Always returns a single-line primary
+ * message; `hint` (if present) is returned as a second line; `stack` and the
+ * `cause` chain are included only when verbose is true.
+ *
+ * Does NOT color the output — caller chooses whether to apply ui.red() etc.
+ * so non-TTY stderr paths stay ANSI-clean.
+ */
+export function formatError(err, opts = {}) {
+    const lines = [];
+    if (isAiwgError(err)) {
+        lines.push(`aiwg: error: ${err.message} (code: ${err.code})`);
+        if (err.hint)
+            lines.push(`  hint: ${err.hint}`);
+        if (opts.verbose) {
+            if (err.stack)
+                lines.push(err.stack);
+            if (err.cause) {
+                lines.push('  cause:');
+                lines.push(formatError(err.cause, { verbose: true }));
+            }
+        }
+    }
+    else if (err instanceof Error) {
+        lines.push(`aiwg: error: ${err.message}`);
+        if (opts.verbose && err.stack)
+            lines.push(err.stack);
+    }
+    else {
+        lines.push(`aiwg: error: ${String(err)}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Resolve the exit code to use for an error. Non-AiwgError throws and plain
+ * strings map to EXIT_CODES.GENERAL.
+ */
+export function exitCodeFor(err) {
+    if (isAiwgError(err))
+        return err.exitCode;
+    return EXIT_CODES.GENERAL;
+}
+/**
+ * Convert any thrown value into a uniform HandlerResult shape, preserving
+ * AiwgError's semantic fields (code, exitCode, hint) where present.
+ *
+ * This is the bridge between the in-handler `try { ... } catch (err) { ... }`
+ * pattern and the HandlerResult contract the router expects. Use it in every
+ * handler's top-level catch:
+ *
+ *   try {
+ *     await doWork(ctx);
+ *     return { exitCode: 0 };
+ *   } catch (err) {
+ *     return handlerResultFromError(err);
+ *   }
+ *
+ * Non-AiwgError throws map to `{ exitCode: 1, message, error }`. AiwgError
+ * throws carry their `exitCode` (USAGE=2, CONFIG=78, CANT_CREATE=73, etc.)
+ * plus the `hint` merged into the message for single-line output.
+ *
+ * Phase 5 of the CLI Stabilization Epic (#922) — unblocks the exit-code
+ * propagation from Phase 4 (#921) that was previously flattened to 1.
+ */
+export function handlerResultFromError(err) {
+    if (isAiwgError(err)) {
+        const message = err.hint ? `${err.message} — hint: ${err.hint}` : err.message;
+        return { exitCode: err.exitCode, message, error: err };
+    }
+    if (err instanceof Error) {
+        return { exitCode: EXIT_CODES.GENERAL, message: err.message, error: err };
+    }
+    const message = String(err);
+    return { exitCode: EXIT_CODES.GENERAL, message, error: new Error(message) };
+}
+//# sourceMappingURL=errors.js.map

package/dist/src/cli/find-package-root.js

@@ -0,0 +1,40 @@
+/**
+ * Shared helper: walk up from a starting directory to find AIWG's package root
+ * (the directory containing the full or lightweight AIWG package.json).
+ *
+ * Required because the compiled layout (dist/src/<area>/<file>.js) and the
+ * source layout (src/<area>/<file>.ts) are different depths from the package
+ * root, so fixed `../../` walks break in one of the two modes. Walking up to
+ * the package manifest works in source, full-package, and `@aiwg/cli` modes.
+ *
+ * @issue #1261
+ */
+import { existsSync, readFileSync } from 'fs';
+import { dirname, join } from 'path';
+/**
+ * Walk up from `startDir` looking for an AIWG package manifest.
+ * Returns the directory containing that package.json, or `null` if not found
+ * within `maxDepth` levels.
+ */
+export function findPackageRoot(startDir, maxDepth = 10) {
+    let dir = startDir;
+    for (let i = 0; i < maxDepth; i++) {
+        const pkgPath = join(dir, 'package.json');
+        if (existsSync(pkgPath)) {
+            try {
+                const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+                if (pkg.name === 'aiwg' || pkg.name === '@aiwg/cli')
+                    return dir;
+            }
+            catch {
+                /* malformed package.json — keep walking */
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+//# sourceMappingURL=find-package-root.js.map