@mycodemap/mycodemap 1.9.0 → 2.7.0

package/dist/cli/output/apply-suggestion.js

@@ -0,0 +1,29 @@
+// [META] since:2026-05-01 | owner:cli-team | stable:false
+// [WHY] Safety-gated auto-remediation engine — executes nextCommand only when confidence >= threshold and --apply-suggestion flag set
+import { exec } from 'node:child_process';
+import { promisify } from 'node:util';
+import { APPLY_SUGGESTION_CONFIDENCE_THRESHOLD } from './types.js';
+const execAsync = promisify(exec);
+export async function tryApplySuggestion(error, options, _mode) {
+    if (!options.applySuggestion) {
+        return { type: 'result', success: false, data: { reason: 'apply-suggestion flag not set' } };
+    }
+    if (error.confidence < APPLY_SUGGESTION_CONFIDENCE_THRESHOLD) {
+        return { type: 'result', success: false, data: { reason: `confidence ${error.confidence} below threshold ${APPLY_SUGGESTION_CONFIDENCE_THRESHOLD}` } };
+    }
+    if (!error.nextCommand) {
+        return { type: 'result', success: false, data: { reason: 'no nextCommand available' } };
+    }
+    process.stderr.write(JSON.stringify({ type: 'apply-suggestion', action: 'attempt', command: error.nextCommand, confidence: error.confidence }) + '\n');
+    try {
+        const { stdout } = await execAsync(error.nextCommand, { timeout: 30000 });
+        process.stderr.write(JSON.stringify({ type: 'apply-suggestion', action: 'success', command: error.nextCommand }) + '\n');
+        return { type: 'result', success: true, data: { stdout: stdout.trim() }, attemptedCommand: error.nextCommand };
+    }
+    catch (execError) {
+        const msg = execError instanceof Error ? execError.message : String(execError);
+        process.stderr.write(JSON.stringify({ type: 'apply-suggestion', action: 'failed', command: error.nextCommand, error: msg }) + '\n');
+        return { type: 'result', success: false, data: { error: msg }, attemptedCommand: error.nextCommand };
+    }
+}
+//# sourceMappingURL=apply-suggestion.js.map

package/dist/cli/output/apply-suggestion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-suggestion.js","sourceRoot":"","sources":["../../../src/cli/output/apply-suggestion.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAC1D,sIAAsI;AAEtI,OAAO,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,OAAO,EAAE,qCAAqC,EAAE,MAAM,YAAY,CAAC;AAEnE,MAAM,SAAS,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;AASlC,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,KAAsB,EACtB,OAA8D,EAC9D,KAAiB;IAEjB,IAAI,CAAC,OAAO,CAAC,eAAe,EAAE,CAAC;QAC7B,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,+BAA+B,EAAE,EAAE,CAAC;IAC/F,CAAC;IAED,IAAI,KAAK,CAAC,UAAU,GAAG,qCAAqC,EAAE,CAAC;QAC7D,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,cAAc,KAAK,CAAC,UAAU,oBAAoB,qCAAqC,EAAE,EAAE,EAAE,CAAC;IACzJ,CAAC;IAED,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC;QACvB,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,0BAA0B,EAAE,EAAE,CAAC;IAC1F,CAAC;IAED,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,kBAAkB,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,CAAC,WAAW,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;IAEvJ,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,SAAS,CAAC,KAAK,CAAC,WAAW,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;QAC1E,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,kBAAkB,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;QACzH,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,EAAE,EAAE,gBAAgB,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC;IACjH,CAAC;IAAC,OAAO,SAAS,EAAE,CAAC;QACnB,MAAM,GAAG,GAAG,SAAS,YAAY,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAC/E,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,kBAAkB,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,CAAC,WAAW,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;QACpI,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,gBAAgB,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC;IACvG,CAAC;AACH,CAAC"}

package/dist/cli/output/error-codes.d.ts

@@ -0,0 +1,24 @@
+export declare const ErrorCodes: {
+    readonly DEP_NATIVE_MISSING: "DEP_NATIVE_MISSING";
+    readonly DEP_WASM_FALLBACK_AVAILABLE: "DEP_WASM_FALLBACK_AVAILABLE";
+    readonly DEP_MODULE_NOT_FOUND: "DEP_MODULE_NOT_FOUND";
+    readonly DEP_REBUILD_REQUIRED: "DEP_REBUILD_REQUIRED";
+    readonly CFG_INVALID_CONFIG: "CFG_INVALID_CONFIG";
+    readonly CFG_WORKSPACE_NOT_INITIALIZED: "CFG_WORKSPACE_NOT_INITIALIZED";
+    readonly CFG_WORKSPACE_DRIFT: "CFG_WORKSPACE_DRIFT";
+    readonly DEPRECATED_PARSER_MODE: "DEPRECATED_PARSER_MODE";
+    readonly UNSUPPORTED_STORAGE_TYPE: "UNSUPPORTED_STORAGE_TYPE";
+    readonly RUN_COMMAND_FAILED: "RUN_COMMAND_FAILED";
+    readonly RUN_PARSE_ERROR: "RUN_PARSE_ERROR";
+    readonly RUN_TIMEOUT: "RUN_TIMEOUT";
+    readonly FS_FILE_NOT_FOUND: "FS_FILE_NOT_FOUND";
+    readonly FS_PERMISSION_DENIED: "FS_PERMISSION_DENIED";
+    readonly FS_WORKING_DIR_INVALID: "FS_WORKING_DIR_INVALID";
+};
+export type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+export declare const ErrorRemediation: Record<ErrorCode, {
+    message: string;
+    nextCommand?: string;
+    confidence: number;
+}>;
+//# sourceMappingURL=error-codes.d.ts.map

package/dist/cli/output/error-codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-codes.d.ts","sourceRoot":"","sources":["../../../src/cli/output/error-codes.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;CAuBb,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,OAAO,UAAU,CAAC,CAAC;AAErE,eAAO,MAAM,gBAAgB,EAAE,MAAM,CACnC,SAAS,EACT;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CA6E9D,CAAC"}

package/dist/cli/output/error-codes.js

@@ -0,0 +1,94 @@
+// [META] since:2026-05-01 | owner:cli-team | stable:false
+// [WHY] Canonical error code registry with prefix classification and remediation map
+export const ErrorCodes = {
+    // Dependency errors
+    DEP_NATIVE_MISSING: 'DEP_NATIVE_MISSING',
+    DEP_WASM_FALLBACK_AVAILABLE: 'DEP_WASM_FALLBACK_AVAILABLE',
+    DEP_MODULE_NOT_FOUND: 'DEP_MODULE_NOT_FOUND',
+    DEP_REBUILD_REQUIRED: 'DEP_REBUILD_REQUIRED',
+    // Configuration errors
+    CFG_INVALID_CONFIG: 'CFG_INVALID_CONFIG',
+    CFG_WORKSPACE_NOT_INITIALIZED: 'CFG_WORKSPACE_NOT_INITIALIZED',
+    CFG_WORKSPACE_DRIFT: 'CFG_WORKSPACE_DRIFT',
+    // Runtime errors
+    DEPRECATED_PARSER_MODE: 'DEPRECATED_PARSER_MODE',
+    UNSUPPORTED_STORAGE_TYPE: 'UNSUPPORTED_STORAGE_TYPE',
+    RUN_COMMAND_FAILED: 'RUN_COMMAND_FAILED',
+    RUN_PARSE_ERROR: 'RUN_PARSE_ERROR',
+    RUN_TIMEOUT: 'RUN_TIMEOUT',
+    // Filesystem errors
+    FS_FILE_NOT_FOUND: 'FS_FILE_NOT_FOUND',
+    FS_PERMISSION_DENIED: 'FS_PERMISSION_DENIED',
+    FS_WORKING_DIR_INVALID: 'FS_WORKING_DIR_INVALID',
+};
+export const ErrorRemediation = {
+    DEP_NATIVE_MISSING: {
+        message: 'Native dependency cannot be loaded. Try: --wasm-fallback, npm rebuild, or install prebuilt binaries',
+        nextCommand: 'codemap --wasm-fallback',
+        confidence: 0.9,
+    },
+    DEP_WASM_FALLBACK_AVAILABLE: {
+        message: 'Native dependency unavailable but WASM fallback is available',
+        nextCommand: 'codemap --wasm-fallback',
+        confidence: 0.95,
+    },
+    DEP_MODULE_NOT_FOUND: {
+        message: 'Required module not found. Run npm install to install dependencies',
+        nextCommand: 'npm install',
+        confidence: 0.85,
+    },
+    DEP_REBUILD_REQUIRED: {
+        message: 'Native modules need rebuilding. Run npm rebuild',
+        nextCommand: 'npm rebuild',
+        confidence: 0.85,
+    },
+    CFG_INVALID_CONFIG: {
+        message: 'Configuration file is invalid. Check .mycodemap/config.json syntax',
+        confidence: 0.7,
+    },
+    CFG_WORKSPACE_NOT_INITIALIZED: {
+        message: 'Workspace not initialized. Run codemap init first',
+        nextCommand: 'codemap init',
+        confidence: 0.9,
+    },
+    CFG_WORKSPACE_DRIFT: {
+        message: 'Workspace has drifted from receipt state. Run codemap doctor for details',
+        nextCommand: 'codemap doctor',
+        confidence: 0.8,
+    },
+    DEPRECATED_PARSER_MODE: {
+        message: 'Parser mode inputs fast/smart/hybrid are deprecated. Remove the mode flag or config value and use the default registry-backed parser flow',
+        nextCommand: 'mycodemap doctor',
+        confidence: 0.98,
+    },
+    UNSUPPORTED_STORAGE_TYPE: {
+        message: 'Persistent storage has converged to SQLite-only. Change storage.type to "sqlite" (recommended) or "auto"; use "memory" only for tests, and migrate legacy filesystem/Kuzu data into the SQLite database path before rerunning',
+        nextCommand: 'mycodemap doctor',
+        confidence: 0.97,
+    },
+    RUN_COMMAND_FAILED: {
+        message: 'Command execution failed. Check the error details above',
+        confidence: 0.3,
+    },
+    RUN_PARSE_ERROR: {
+        message: 'Parse error in source file. Verify the file syntax',
+        confidence: 0.5,
+    },
+    RUN_TIMEOUT: {
+        message: 'Operation timed out. Try with a smaller scope or increase timeout',
+        confidence: 0.6,
+    },
+    FS_FILE_NOT_FOUND: {
+        message: 'Required file not found. Verify the path is correct',
+        confidence: 0.7,
+    },
+    FS_PERMISSION_DENIED: {
+        message: 'Permission denied. Check file/directory permissions',
+        confidence: 0.6,
+    },
+    FS_WORKING_DIR_INVALID: {
+        message: 'Working directory is invalid or does not exist',
+        confidence: 0.8,
+    },
+};
+//# sourceMappingURL=error-codes.js.map

package/dist/cli/output/error-codes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-codes.js","sourceRoot":"","sources":["../../../src/cli/output/error-codes.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAC1D,qFAAqF;AAErF,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,oBAAoB;IACpB,kBAAkB,EAAE,oBAAoB;IACxC,2BAA2B,EAAE,6BAA6B;IAC1D,oBAAoB,EAAE,sBAAsB;IAC5C,oBAAoB,EAAE,sBAAsB;IAE5C,uBAAuB;IACvB,kBAAkB,EAAE,oBAAoB;IACxC,6BAA6B,EAAE,+BAA+B;IAC9D,mBAAmB,EAAE,qBAAqB;IAE1C,iBAAiB;IACjB,sBAAsB,EAAE,wBAAwB;IAChD,wBAAwB,EAAE,0BAA0B;IACpD,kBAAkB,EAAE,oBAAoB;IACxC,eAAe,EAAE,iBAAiB;IAClC,WAAW,EAAE,aAAa;IAE1B,oBAAoB;IACpB,iBAAiB,EAAE,mBAAmB;IACtC,oBAAoB,EAAE,sBAAsB;IAC5C,sBAAsB,EAAE,wBAAwB;CACxC,CAAC;AAIX,MAAM,CAAC,MAAM,gBAAgB,GAGzB;IACF,kBAAkB,EAAE;QAClB,OAAO,EACL,qGAAqG;QACvG,WAAW,EAAE,yBAAyB;QACtC,UAAU,EAAE,GAAG;KAChB;IACD,2BAA2B,EAAE;QAC3B,OAAO,EAAE,8DAA8D;QACvE,WAAW,EAAE,yBAAyB;QACtC,UAAU,EAAE,IAAI;KACjB;IACD,oBAAoB,EAAE;QACpB,OAAO,EACL,oEAAoE;QACtE,WAAW,EAAE,aAAa;QAC1B,UAAU,EAAE,IAAI;KACjB;IACD,oBAAoB,EAAE;QACpB,OAAO,EAAE,iDAAiD;QAC1D,WAAW,EAAE,aAAa;QAC1B,UAAU,EAAE,IAAI;KACjB;IACD,kBAAkB,EAAE;QAClB,OAAO,EACL,oEAAoE;QACtE,UAAU,EAAE,GAAG;KAChB;IACD,6BAA6B,EAAE;QAC7B,OAAO,EAAE,mDAAmD;QAC5D,WAAW,EAAE,cAAc;QAC3B,UAAU,EAAE,GAAG;KAChB;IACD,mBAAmB,EAAE;QACnB,OAAO,EACL,0EAA0E;QAC5E,WAAW,EAAE,gBAAgB;QAC7B,UAAU,EAAE,GAAG;KAChB;IACD,sBAAsB,EAAE;QACtB,OAAO,EACL,2IAA2I;QAC7I,WAAW,EAAE,kBAAkB;QAC/B,UAAU,EAAE,IAAI;KACjB;IACD,wBAAwB,EAAE;QACxB,OAAO,EACL,+NAA+N;QACjO,WAAW,EAAE,kBAAkB;QAC/B,UAAU,EAAE,IAAI;KACjB;IACD,kBAAkB,EAAE;QAClB,OAAO,EAAE,yDAAyD;QAClE,UAAU,EAAE,GAAG;KAChB;IACD,eAAe,EAAE;QACf,OAAO,EAAE,oDAAoD;QAC7D,UAAU,EAAE,GAAG;KAChB;IACD,WAAW,EAAE;QACX,OAAO,EACL,mEAAmE;QACrE,UAAU,EAAE,GAAG;KAChB;IACD,iBAAiB,EAAE;QACjB,OAAO,EAAE,qDAAqD;QAC9D,UAAU,EAAE,GAAG;KAChB;IACD,oBAAoB,EAAE;QACpB,OAAO,EAAE,qDAAqD;QAC9D,UAAU,EAAE,GAAG;KAChB;IACD,sBAAsB,EAAE;QACtB,OAAO,EAAE,gDAAgD;QACzD,UAAU,EAAE,GAAG;KAChB;CACF,CAAC"}

package/dist/cli/output/errors.d.ts

@@ -0,0 +1,14 @@
+import type { OutputMode, ActionableError } from './types.js';
+import { type ErrorCode } from './error-codes.js';
+/**
+ * Format an error based on output mode.
+ *
+ * - JSON mode: returns JSON string of {type:"error", code, message, ...actionableFields}
+ * - Human mode: returns chalk-colored readable string
+ */
+export declare function formatError(error: unknown, mode: OutputMode, attempted?: string): string;
+/**
+ * Programmatically create an ActionableError with sensible defaults.
+ */
+export declare function createActionableError(code: ErrorCode | string, message: string, attempted: string, overrides?: Partial<Pick<ActionableError, 'confidence' | 'nextCommand' | 'causes' | 'rootCause' | 'remediationPlan'>>): ActionableError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/cli/output/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/cli/output/errors.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAmB,MAAM,YAAY,CAAC;AAE/E,OAAO,EAAgC,KAAK,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAYhF;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAwCxF;AA2HD;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,SAAS,GAAG,MAAM,EACxB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,SAAS,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,eAAe,EAAE,YAAY,GAAG,aAAa,GAAG,QAAQ,GAAG,WAAW,GAAG,iBAAiB,CAAC,CAAC,GACpH,eAAe,CAejB"}

package/dist/cli/output/errors.js

@@ -0,0 +1,182 @@
+// [META] since:2026-04-30 | owner:cli-team | stable:false
+// [WHY] Mode-aware error formatting — structured JSON for machines, chalk-colored text for humans
+import chalk from 'chalk';
+import { isActionableError } from './types.js';
+import { ErrorCodes, ErrorRemediation } from './error-codes.js';
+/**
+ * Format an error based on output mode.
+ *
+ * - JSON mode: returns JSON string of {type:"error", code, message, ...actionableFields}
+ * - Human mode: returns chalk-colored readable string
+ */
+export function formatError(error, mode, attempted) {
+    const normalized = normalizeError(error, attempted);
+    if (mode === 'json') {
+        const base = {
+            type: 'error',
+            code: normalized.code,
+            message: normalized.message,
+            ...(normalized.remediation ? { remediation: normalized.remediation } : {}),
+        };
+        if (isActionableError(normalized)) {
+            const json = {
+                ...base,
+                attempted: normalized.attempted,
+                rootCause: normalized.rootCause,
+                remediationPlan: normalized.remediationPlan,
+                confidence: normalized.confidence,
+            };
+            if (normalized.nextCommand)
+                json.nextCommand = normalized.nextCommand;
+            if (normalized.causes && normalized.causes.length > 0)
+                json.causes = normalized.causes;
+            return JSON.stringify(json);
+        }
+        return JSON.stringify(base);
+    }
+    // Human mode
+    let output = chalk.red('Error: ') + normalized.message;
+    if (normalized.code && normalized.code !== 'UNKNOWN') {
+        output = chalk.red('Error: ') + `[${normalized.code}] ${normalized.message}`;
+    }
+    output += '\n  ' + chalk.cyan('Attempted: ') + normalized.attempted;
+    output += '\n  ' + chalk.cyan('Root cause: ') + normalized.rootCause;
+    if (normalized.remediationPlan) {
+        const pct = Math.round(normalized.confidence * 100);
+        output += `\n  ${chalk.yellow('Suggestion: ')}${normalized.remediationPlan} (${pct}% confidence)`;
+    }
+    if (normalized.nextCommand) {
+        output += '\n  ' + chalk.green('Next: ') + normalized.nextCommand;
+    }
+    return output;
+}
+/**
+ * Normalize any thrown value into an ActionableError with auto-detected codes.
+ */
+function normalizeError(error, attempted) {
+    if (error instanceof Error) {
+        const err = error;
+        const detected = detectErrorPattern(err);
+        return {
+            type: 'error',
+            code: detected.code,
+            message: err.message,
+            name: 'ActionableError',
+            attempted: attempted ?? 'unknown operation',
+            rootCause: detectRootCause(err),
+            remediationPlan: detected.remediation.message,
+            confidence: detected.remediation.confidence,
+            nextCommand: detected.remediation.nextCommand,
+            remediation: detected.remediation.nextCommand ?? detected.remediation.message,
+            causes: extractCauses(err),
+        };
+    }
+    return {
+        type: 'error',
+        code: ErrorCodes.RUN_COMMAND_FAILED,
+        message: String(error),
+        name: 'ActionableError',
+        attempted: attempted ?? 'unknown operation',
+        rootCause: String(error),
+        remediationPlan: ErrorRemediation.RUN_COMMAND_FAILED.message,
+        confidence: 0.1,
+    };
+}
+/**
+ * Map Node.js error codes and patterns to our error code registry.
+ */
+function detectErrorPattern(err) {
+    const errCode = err.code ?? '';
+    const msg = err.message.toLowerCase();
+    // Node.js system error codes
+    if (errCode === 'MODULE_NOT_FOUND') {
+        return { code: ErrorCodes.DEP_MODULE_NOT_FOUND, remediation: ErrorRemediation.DEP_MODULE_NOT_FOUND };
+    }
+    if (errCode === 'EACCES' || errCode === 'EPERM') {
+        return { code: ErrorCodes.FS_PERMISSION_DENIED, remediation: ErrorRemediation.FS_PERMISSION_DENIED };
+    }
+    if (errCode === 'ENOENT') {
+        return { code: ErrorCodes.FS_FILE_NOT_FOUND, remediation: ErrorRemediation.FS_FILE_NOT_FOUND };
+    }
+    if (errCode && Object.values(ErrorCodes).includes(errCode)) {
+        const registryRemediation = ErrorRemediation[errCode] ?? { message: 'Check the error details and try again', confidence: 0.3 };
+        return {
+            code: errCode,
+            remediation: {
+                ...registryRemediation,
+                ...(err.remediation ? { message: err.remediation } : {}),
+                ...(err.nextCommand ? { nextCommand: err.nextCommand } : {}),
+                ...(typeof err.confidence === 'number' ? { confidence: err.confidence } : {}),
+            },
+        };
+    }
+    // Preserve custom error codes from callers (e.g., MISSING_TARGET, INDEX_NOT_FOUND)
+    if (errCode && !Object.values(ErrorCodes).includes(errCode)) {
+        const customRemediation = err.remediation
+            ? { message: err.remediation, confidence: 0.7 }
+            : { message: 'Check the error details and try again', confidence: 0.3 };
+        return { code: errCode, remediation: customRemediation };
+    }
+    // Content-based detection for native dependency failures
+    if (msg.includes('tree-sitter') || msg.includes('better-sqlite3')) {
+        return { code: ErrorCodes.DEP_NATIVE_MISSING, remediation: ErrorRemediation.DEP_NATIVE_MISSING };
+    }
+    if (msg.includes('config.json') || msg.includes('.mycodemap')) {
+        return { code: ErrorCodes.CFG_INVALID_CONFIG, remediation: ErrorRemediation.CFG_INVALID_CONFIG };
+    }
+    if (msg.includes('not initialized') || msg.includes('workspace not found')) {
+        return { code: ErrorCodes.CFG_WORKSPACE_NOT_INITIALIZED, remediation: ErrorRemediation.CFG_WORKSPACE_NOT_INITIALIZED };
+    }
+    return { code: ErrorCodes.RUN_COMMAND_FAILED, remediation: ErrorRemediation.RUN_COMMAND_FAILED };
+}
+/**
+ * Extract the deepest root cause from an error message or cause chain.
+ */
+function detectRootCause(err) {
+    if (err.cause instanceof Error) {
+        return detectRootCause(err.cause);
+    }
+    return err.message;
+}
+/**
+ * Walk the error.cause chain and convert each to ActionableError.
+ */
+function extractCauses(err) {
+    const causes = [];
+    let current = err.cause;
+    while (current instanceof Error) {
+        const causeErr = current;
+        causes.push({
+            type: 'error',
+            code: causeErr.code ?? 'UNKNOWN',
+            message: causeErr.message,
+            name: 'ActionableError',
+            attempted: 'nested error',
+            rootCause: causeErr.message,
+            remediationPlan: '',
+            confidence: 0,
+        });
+        current = causeErr.cause;
+    }
+    return causes;
+}
+/**
+ * Programmatically create an ActionableError with sensible defaults.
+ */
+export function createActionableError(code, message, attempted, overrides) {
+    const remediation = ErrorRemediation[code] ?? { message: 'Check the error details', confidence: 0.3 };
+    return {
+        type: 'error',
+        code,
+        message,
+        name: 'ActionableError',
+        attempted,
+        rootCause: overrides?.rootCause ?? message,
+        remediationPlan: overrides?.remediationPlan ?? remediation.message,
+        confidence: overrides?.confidence ?? remediation.confidence,
+        nextCommand: overrides?.nextCommand ?? remediation.nextCommand,
+        remediation: overrides?.nextCommand ?? remediation.message,
+        ...(overrides?.causes ? { causes: overrides.causes } : {}),
+    };
+}
+//# sourceMappingURL=errors.js.map

package/dist/cli/output/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/cli/output/errors.ts"],"names":[],"mappings":"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"}

package/dist/cli/output/index.d.ts

@@ -0,0 +1,13 @@
+export { resolveOutputMode } from './mode.js';
+export { createProgressEmitter } from './progress.js';
+export { formatError, createActionableError } from './errors.js';
+export { renderOutput } from './render.js';
+export type { OutputMode, OutputModeOptions, ProgressEmitter, StructuredError, ActionableError } from './types.js';
+export { isActionableError, APPLY_SUGGESTION_CONFIDENCE_THRESHOLD } from './types.js';
+export { ErrorCodes, ErrorRemediation } from './error-codes.js';
+export type { ErrorCode } from './error-codes.js';
+export { tryApplySuggestion } from './apply-suggestion.js';
+export type { SuggestionResult } from './apply-suggestion.js';
+export { checkAndActivateWasmFallback, createNativeDepError } from './wasm-fallback.js';
+export type { WasmFallbackResult } from './wasm-fallback.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/output/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cli/output/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,eAAe,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AACnH,OAAO,EAAE,iBAAiB,EAAE,qCAAqC,EAAE,MAAM,YAAY,CAAC;AACtF,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAChE,YAAY,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,YAAY,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,4BAA4B,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AACxF,YAAY,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/cli/output/index.js

@@ -0,0 +1,11 @@
+// [META] since:2026-04-30 | owner:cli-team | stable:false
+// [WHY] Barrel exports for output mode module — single import point for all commands
+export { resolveOutputMode } from './mode.js';
+export { createProgressEmitter } from './progress.js';
+export { formatError, createActionableError } from './errors.js';
+export { renderOutput } from './render.js';
+export { isActionableError, APPLY_SUGGESTION_CONFIDENCE_THRESHOLD } from './types.js';
+export { ErrorCodes, ErrorRemediation } from './error-codes.js';
+export { tryApplySuggestion } from './apply-suggestion.js';
+export { checkAndActivateWasmFallback, createNativeDepError } from './wasm-fallback.js';
+//# sourceMappingURL=index.js.map

package/dist/cli/output/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cli/output/index.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAC1D,qFAAqF;AAErF,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,EAAE,iBAAiB,EAAE,qCAAqC,EAAE,MAAM,YAAY,CAAC;AACtF,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEhE,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAE3D,OAAO,EAAE,4BAA4B,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/cli/output/mode.d.ts

@@ -0,0 +1,12 @@
+import type { OutputMode, OutputModeOptions } from './types.js';
+/**
+ * Resolve output mode from CLI flags and TTY state.
+ *
+ * Priority: --json wins over --human (explicit machine-readable takes priority).
+ * No flags: TTY auto-detect (human in terminal, json when piped).
+ *
+ * @param options - CLI flags { json?, human? }
+ * @param ttyOverride - Override for process.stdout.isTTY (useful in tests). Defaults to process.stdout.isTTY.
+ */
+export declare function resolveOutputMode(options?: OutputModeOptions, ttyOverride?: boolean): OutputMode;
+//# sourceMappingURL=mode.d.ts.map

package/dist/cli/output/mode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mode.d.ts","sourceRoot":"","sources":["../../../src/cli/output/mode.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEhE;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,GAAE,iBAAsB,EAC/B,WAAW,CAAC,EAAE,OAAO,GACpB,UAAU,CAYZ"}

package/dist/cli/output/mode.js

@@ -0,0 +1,23 @@
+// [META] since:2026-04-30 | owner:cli-team | stable:false
+// [WHY] Unified TTY/flag detection — single source of truth for output mode resolution
+/**
+ * Resolve output mode from CLI flags and TTY state.
+ *
+ * Priority: --json wins over --human (explicit machine-readable takes priority).
+ * No flags: TTY auto-detect (human in terminal, json when piped).
+ *
+ * @param options - CLI flags { json?, human? }
+ * @param ttyOverride - Override for process.stdout.isTTY (useful in tests). Defaults to process.stdout.isTTY.
+ */
+export function resolveOutputMode(options = {}, ttyOverride) {
+    if (options.json) {
+        return 'json';
+    }
+    if (options.human) {
+        return 'human';
+    }
+    // No explicit flag: auto-detect from TTY
+    const isTTY = ttyOverride ?? process.stdout.isTTY;
+    return isTTY ? 'human' : 'json';
+}
+//# sourceMappingURL=mode.js.map

package/dist/cli/output/mode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mode.js","sourceRoot":"","sources":["../../../src/cli/output/mode.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAC1D,uFAAuF;AAIvF;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAC/B,UAA6B,EAAE,EAC/B,WAAqB;IAErB,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;QACjB,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;QAClB,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,yCAAyC;IACzC,MAAM,KAAK,GAAG,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC;IAClD,OAAO,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC;AAClC,CAAC"}

package/dist/cli/output/progress.d.ts

@@ -0,0 +1,9 @@
+import type { OutputMode, ProgressEmitter } from './types.js';
+/**
+ * Create a progress emitter appropriate for the output mode.
+ *
+ * - JSON mode: writes NDJSON lines {type:"progress", percent, message} to stderr
+ * - Human mode: uses ora spinner on stderr (no stdout pollution)
+ */
+export declare function createProgressEmitter(mode: OutputMode, prefix?: string): ProgressEmitter;
+//# sourceMappingURL=progress.d.ts.map

package/dist/cli/output/progress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.d.ts","sourceRoot":"","sources":["../../../src/cli/output/progress.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE9D;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,UAAU,EAChB,MAAM,CAAC,EAAE,MAAM,GACd,eAAe,CAKjB"}

package/dist/cli/output/progress.js

@@ -0,0 +1,65 @@
+// [META] since:2026-04-30 | owner:cli-team | stable:false
+// [WHY] Progress emitter abstraction — NDJSON to stderr in JSON mode, ora spinner in human mode
+import ora from 'ora';
+/**
+ * Create a progress emitter appropriate for the output mode.
+ *
+ * - JSON mode: writes NDJSON lines {type:"progress", percent, message} to stderr
+ * - Human mode: uses ora spinner on stderr (no stdout pollution)
+ */
+export function createProgressEmitter(mode, prefix) {
+    if (mode === 'json') {
+        return createJsonProgressEmitter();
+    }
+    return createHumanProgressEmitter(prefix);
+}
+/**
+ * JSON mode: structured NDJSON progress on stderr
+ */
+function createJsonProgressEmitter() {
+    let lastPercent = -1;
+    return {
+        update(percent, message) {
+            // Rate-limit: only emit when percent changes by >= 5 or message changes
+            if (Math.abs(percent - lastPercent) < 5 && lastPercent >= 0) {
+                return;
+            }
+            lastPercent = percent;
+            const line = JSON.stringify({ type: 'progress', percent, message });
+            process.stderr.write(line + '\n');
+        },
+        complete() {
+            const line = JSON.stringify({ type: 'progress', percent: 100, message: 'complete' });
+            process.stderr.write(line + '\n');
+        },
+        fail(message) {
+            const line = JSON.stringify({ type: 'progress', percent: -1, message: message ?? 'failed' });
+            process.stderr.write(line + '\n');
+        },
+    };
+}
+/**
+ * Human mode: ora spinner on stderr
+ */
+function createHumanProgressEmitter(prefix) {
+    const spinner = ora({ spinner: 'dots', prefixText: prefix });
+    return {
+        update(_percent, message) {
+            if (!spinner.isSpinning) {
+                spinner.start();
+            }
+            spinner.text = message;
+        },
+        complete() {
+            if (spinner.isSpinning) {
+                spinner.succeed();
+            }
+        },
+        fail(message) {
+            if (spinner.isSpinning) {
+                spinner.fail(message);
+            }
+        },
+    };
+}
+//# sourceMappingURL=progress.js.map

package/dist/cli/output/progress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.js","sourceRoot":"","sources":["../../../src/cli/output/progress.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAC1D,gGAAgG;AAEhG,OAAO,GAAG,MAAM,KAAK,CAAC;AAGtB;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CACnC,IAAgB,EAChB,MAAe;IAEf,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACpB,OAAO,yBAAyB,EAAE,CAAC;IACrC,CAAC;IACD,OAAO,0BAA0B,CAAC,MAAM,CAAC,CAAC;AAC5C,CAAC;AAED;;GAEG;AACH,SAAS,yBAAyB;IAChC,IAAI,WAAW,GAAG,CAAC,CAAC,CAAC;IAErB,OAAO;QACL,MAAM,CAAC,OAAe,EAAE,OAAe;YACrC,wEAAwE;YACxE,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,GAAG,WAAW,CAAC,GAAG,CAAC,IAAI,WAAW,IAAI,CAAC,EAAE,CAAC;gBAC5D,OAAO;YACT,CAAC;YACD,WAAW,GAAG,OAAO,CAAC;YACtB,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;YACpE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;QACpC,CAAC;QAED,QAAQ;YACN,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC,CAAC;YACrF,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;QACpC,CAAC;QAED,IAAI,CAAC,OAAgB;YACnB,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,CAAC,CAAC;YAC7F,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;QACpC,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAS,0BAA0B,CAAC,MAAe;IACjD,MAAM,OAAO,GAAG,GAAG,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC;IAE7D,OAAO;QACL,MAAM,CAAC,QAAgB,EAAE,OAAe;YACtC,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC;gBACxB,OAAO,CAAC,KAAK,EAAE,CAAC;YAClB,CAAC;YACD,OAAO,CAAC,IAAI,GAAG,OAAO,CAAC;QACzB,CAAC;QAED,QAAQ;YACN,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;gBACvB,OAAO,CAAC,OAAO,EAAE,CAAC;YACpB,CAAC;QACH,CAAC;QAED,IAAI,CAAC,OAAgB;YACnB,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;gBACvB,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACxB,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/cli/output/render.d.ts

@@ -0,0 +1,11 @@
+import type { OutputMode } from './types.js';
+/**
+ * Render data to stdout based on output mode.
+ *
+ * - JSON mode: writes JSON.stringify(data) + newline to stdout
+ * - Human mode: writes humanRenderer(data) + newline to stdout
+ *
+ * Uses process.stdout.write (not console.log) for predictable output formatting.
+ */
+export declare function renderOutput<T>(data: T, humanRenderer: (data: T) => string, mode: OutputMode): void;
+//# sourceMappingURL=render.d.ts.map

package/dist/cli/output/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../../src/cli/output/render.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAC5B,IAAI,EAAE,CAAC,EACP,aAAa,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,EAClC,IAAI,EAAE,UAAU,GACf,IAAI,CAON"}

package/dist/cli/output/render.js

@@ -0,0 +1,18 @@
+// [META] since:2026-04-30 | owner:cli-team | stable:false
+// [WHY] Mode-aware stdout writer — JSON.stringify in json mode, human renderer in human mode
+/**
+ * Render data to stdout based on output mode.
+ *
+ * - JSON mode: writes JSON.stringify(data) + newline to stdout
+ * - Human mode: writes humanRenderer(data) + newline to stdout
+ *
+ * Uses process.stdout.write (not console.log) for predictable output formatting.
+ */
+export function renderOutput(data, humanRenderer, mode) {
+    if (mode === 'json') {
+        process.stdout.write(JSON.stringify(data) + '\n');
+        return;
+    }
+    process.stdout.write(humanRenderer(data) + '\n');
+}
+//# sourceMappingURL=render.js.map

package/dist/cli/output/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../../../src/cli/output/render.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAC1D,6FAA6F;AAI7F;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAC1B,IAAO,EACP,aAAkC,EAClC,IAAgB;IAEhB,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACpB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;QAClD,OAAO;IACT,CAAC;IAED,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;AACnD,CAAC"}

package/dist/cli/output/types.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Output mode: 'json' for non-TTY/CI/piped consumers, 'human' for interactive terminals
+ */
+export type OutputMode = 'json' | 'human';
+/**
+ * Options passed from CLI flags to resolveOutputMode
+ */
+export interface OutputModeOptions {
+    json?: boolean;
+    human?: boolean;
+}
+/**
+ * Structured progress emitter — abstracts away NDJSON-vs-spinner differences
+ */
+export interface ProgressEmitter {
+    update(percent: number, message: string): void;
+    complete(): void;
+    fail(message?: string): void;
+}
+/**
+ * Structured error shape for JSON mode output
+ */
+export interface StructuredError {
+    type: 'error';
+    code: string;
+    message: string;
+    remediation?: string;
+}
+/**
+ * Actionable error with recovery context — extends StructuredError
+ * with fields that enable automated or guided remediation.
+ */
+export interface ActionableError extends StructuredError {
+    type: 'error';
+    code: string;
+    name: string;
+    attempted: string;
+    rootCause: string;
+    remediationPlan: string;
+    confidence: number;
+    nextCommand?: string;
+    causes?: ActionableError[];
+}
+/**
+ * Type guard: checks if an error has actionable recovery fields
+ */
+export declare function isActionableError(error: StructuredError | ActionableError): error is ActionableError;
+/**
+ * Confidence threshold for --apply-suggestion auto-execution.
+ * Suggestions below this threshold are not auto-executed.
+ */
+export declare const APPLY_SUGGESTION_CONFIDENCE_THRESHOLD = 0.8;
+//# sourceMappingURL=types.d.ts.map