ucn 3.7.24 → 3.7.25

package/cli/index.js

@@ -10,15 +10,19 @@
 const fs = require('fs');
 const path = require('path');
 
-const { parse, parseFile, extractFunction, extractClass, cleanHtmlScriptTags, detectLanguage, isSupported } = require('../core/parser');
-const { getParser, getLanguageModule } = require('../languages');
+const { parseFile, detectLanguage } = require('../core/parser');
 const { ProjectIndex } = require('../core/project');
 const { expandGlob, findProjectRoot } = require('../core/discovery');
 const output = require('../core/output');
-const { pickBestDefinition } = require('../core/shared');
+// pickBestDefinition moved to execute.js — no longer needed here
 const { getCliCommandSet, resolveCommand } = require('../core/registry');
 const { execute } = require('../core/execute');
-const { ExpandCache, renderExpandItem } = require('../core/expand-cache');
+const { ExpandCache } = require('../core/expand-cache');
+
+// Sentinel error for command failures that have already printed their message.
+// Thrown instead of process.exit(1) so finally blocks can run (cache save).
+class CommandError extends Error { constructor() { super(); } }
+function fail(msg) { console.error(msg); throw new CommandError(); }
 
 // ============================================================================
 // ARGUMENT PARSING
@@ -36,70 +40,79 @@ const args = doubleDashIdx === -1 ? rawArgs : rawArgs.slice(0, doubleDashIdx);
 const argsAfterDoubleDash = doubleDashIdx === -1 ? [] : rawArgs.slice(doubleDashIdx + 1);
 
 // Parse flags
-const flags = {
-    json: args.includes('--json'),
-    quiet: !args.includes('--verbose') && !args.includes('--no-quiet'),
-    codeOnly: args.includes('--code-only'),
-    caseSensitive: args.includes('--case-sensitive'),
-    withTypes: args.includes('--with-types'),
-    topLevel: args.includes('--top-level'),
-    exact: args.includes('--exact'),
-    cache: !args.includes('--no-cache'),
-    clearCache: args.includes('--clear-cache'),
-    context: parseInt(args.find(a => a.startsWith('--context='))?.split('=')[1] || '0'),
-    file: args.find(a => a.startsWith('--file='))?.split('=')[1] || null,
-    // Semantic filters (--not is alias for --exclude)
-    exclude: args.find(a => a.startsWith('--exclude=') || a.startsWith('--not='))?.split('=')[1]?.split(',') || [],
-    in: args.find(a => a.startsWith('--in='))?.split('=')[1] || null,
-    // Test file inclusion (by default, tests are excluded from usages/find)
-    includeTests: args.includes('--include-tests'),
-    // Deadcode options
-    includeExported: args.includes('--include-exported'),
-    includeDecorated: args.includes('--include-decorated'),
-    // Uncertain matches (off by default)
-    includeUncertain: args.includes('--include-uncertain'),
-    // Detailed listing (e.g. toc with all symbols)
-    detailed: args.includes('--detailed'),
-    // Output depth
-    depth: args.find(a => a.startsWith('--depth='))?.split('=')[1] || null,
-    // Inline expansion for callees
-    expand: args.includes('--expand'),
-    // Interactive REPL mode
-    interactive: args.includes('--interactive') || args.includes('-i'),
-    // Plan command options
-    addParam: args.find(a => a.startsWith('--add-param='))?.split('=')[1] || null,
-    removeParam: args.find(a => a.startsWith('--remove-param='))?.split('=')[1] || null,
-    renameTo: args.find(a => a.startsWith('--rename-to='))?.split('=')[1] || null,
-    defaultValue: args.find(a => a.startsWith('--default='))?.split('=')[1] || null,
-    // Smart filtering for find results
-    top: parseInt(args.find(a => a.startsWith('--top='))?.split('=')[1] || '0'),
-    all: args.includes('--all'),
-    // Include method calls in caller/callee analysis
-    // Tri-state: true (--include-methods), false (--include-methods=false), undefined (let command decide default)
-    includeMethods: args.includes('--include-methods=false') ? false : args.includes('--include-methods') ? true : undefined,
-    // Tests: only show call/test-case matches
-    callsOnly: args.includes('--calls-only'),
-    // Graph direction (imports/importers/both)
-    direction: args.find(a => a.startsWith('--direction='))?.split('=')[1] || null,
-    // Symlink handling (follow by default)
-    followSymlinks: !args.includes('--no-follow-symlinks'),
-    // Diff-impact options
-    base: args.find(a => a.startsWith('--base='))?.split('=')[1] || null,
-    staged: args.includes('--staged'),
-    // Regex search mode (default: ON; --no-regex to force plain text)
-    regex: args.includes('--no-regex') ? false : undefined,
-    // Stats: per-function line counts
-    functions: args.includes('--functions'),
-    // Class: max lines to show (0 = no limit)
-    maxLines: parseInt(args.find(a => a.startsWith('--max-lines='))?.split('=')[1] || '0') || null
-};
-
-// Handle --file flag with space
-const fileArgIdx = args.indexOf('--file');
-if (fileArgIdx !== -1 && args[fileArgIdx + 1]) {
-    flags.file = args[fileArgIdx + 1];
+/**
+ * Parse flags from an array of tokens. Supports both --flag=value and --flag value forms.
+ * Shared between global CLI mode and interactive mode.
+ */
+function parseFlags(tokens) {
+    function getValueFlag(flagName) {
+        const eqForm = tokens.find(a => a.startsWith(flagName + '='));
+        if (eqForm) return eqForm.split('=').slice(1).join('=');
+        const idx = tokens.indexOf(flagName);
+        if (idx !== -1 && idx + 1 < tokens.length && !tokens[idx + 1].startsWith('-')) {
+            return tokens[idx + 1];
+        }
+        return null;
+    }
+    function parseExclude() {
+        const result = [];
+        for (const a of tokens) {
+            if (a.startsWith('--exclude=') || a.startsWith('--not=')) {
+                result.push(...a.split('=').slice(1).join('=').split(','));
+            }
+        }
+        for (const flag of ['--exclude', '--not']) {
+            for (let i = 0; i < tokens.length; i++) {
+                if (tokens[i] === flag && i + 1 < tokens.length && !tokens[i + 1].startsWith('-')) {
+                    result.push(...tokens[i + 1].split(','));
+                }
+            }
+        }
+        return result;
+    }
+    return {
+        file: getValueFlag('--file'),
+        exclude: parseExclude(),
+        in: getValueFlag('--in'),
+        includeTests: tokens.includes('--include-tests'),
+        includeExported: tokens.includes('--include-exported'),
+        includeDecorated: tokens.includes('--include-decorated'),
+        includeUncertain: tokens.includes('--include-uncertain'),
+        includeMethods: tokens.some(a => a === '--include-methods=false') ? false : tokens.some(a => a === '--include-methods' || (a.startsWith('--include-methods=') && a !== '--include-methods=false')) ? true : undefined,
+        detailed: tokens.includes('--detailed'),
+        topLevel: tokens.includes('--top-level'),
+        all: tokens.includes('--all'),
+        exact: tokens.includes('--exact'),
+        callsOnly: tokens.includes('--calls-only'),
+        codeOnly: tokens.includes('--code-only'),
+        caseSensitive: tokens.includes('--case-sensitive'),
+        withTypes: tokens.includes('--with-types'),
+        expand: tokens.includes('--expand'),
+        depth: getValueFlag('--depth'),
+        top: parseInt(getValueFlag('--top') || '0'),
+        context: parseInt(getValueFlag('--context') || '0'),
+        direction: getValueFlag('--direction'),
+        addParam: getValueFlag('--add-param'),
+        removeParam: getValueFlag('--remove-param'),
+        renameTo: getValueFlag('--rename-to'),
+        defaultValue: getValueFlag('--default'),
+        base: getValueFlag('--base'),
+        staged: tokens.includes('--staged'),
+        maxLines: getValueFlag('--max-lines') || null,
+        regex: tokens.includes('--no-regex') ? false : undefined,
+        functions: tokens.includes('--functions'),
+    };
 }
 
+// Parse shared flags from CLI args, then add global-only flags
+const flags = parseFlags(args);
+flags.json = args.includes('--json');
+flags.quiet = !args.includes('--verbose') && !args.includes('--no-quiet');
+flags.cache = !args.includes('--no-cache');
+flags.clearCache = args.includes('--clear-cache');
+flags.interactive = args.includes('--interactive') || args.includes('-i');
+flags.followSymlinks = !args.includes('--no-follow-symlinks');
+
 // Known flags for validation
 const knownFlags = new Set([
     '--help', '-h', '--mcp',
@@ -110,7 +123,7 @@ const knownFlags = new Set([
     '--file', '--context', '--exclude', '--not', '--in',
     '--depth', '--direction', '--add-param', '--remove-param', '--rename-to',
     '--default', '--top', '--no-follow-symlinks',
-    '--base', '--staged',
+    '--base', '--staged', '--stack',
     '--regex', '--no-regex', '--functions',
     '--max-lines'
 ]);
@@ -135,12 +148,19 @@ if (unknownFlags.length > 0) {
     process.exit(1);
 }
 
+// Value flags that consume the next token (space form: --flag value)
+const VALUE_FLAGS = new Set([
+    '--file', '--depth', '--top', '--context', '--direction',
+    '--add-param', '--remove-param', '--rename-to', '--default',
+    '--base', '--exclude', '--not', '--in', '--max-lines'
+]);
+
 // Remove flags from args, then add args after -- (which are all positional)
 const positionalArgs = [
     ...args.filter((a, idx) =>
         !a.startsWith('--') &&
         a !== '-i' &&
-        !(idx > 0 && args[idx - 1] === '--file')
+        !(idx > 0 && VALUE_FLAGS.has(args[idx - 1]) && !args[idx - 1].includes('='))
     ),
     ...argsAfterDoubleDash
 ];
@@ -160,8 +180,7 @@ const positionalArgs = [
  */
 function requireArg(arg, usage) {
     if (!arg) {
-        console.error(usage);
-        process.exit(1);
+        fail(usage);
     }
 }
 
@@ -241,406 +260,92 @@ function main() {
 // ============================================================================
 
 function runFileCommand(filePath, command, arg) {
-    const code = fs.readFileSync(filePath, 'utf-8');
-    const lines = code.split('\n');
     const language = detectLanguage(filePath);
-
     if (!language) {
         console.error(`Unsupported file type: ${filePath}`);
         process.exit(1);
     }
 
-    const result = parse(code, language);
+    const canonical = resolveCommand(command, 'cli') || command;
 
-    switch (command) {
-        case 'toc':
-            printFileToc(result, filePath);
-            break;
+    // Commands that need full project index — auto-route to project mode
+    const fileLocalCommands = new Set(['toc', 'fn', 'class', 'find', 'usages', 'search', 'lines', 'typedef', 'api']);
 
-        case 'fn': {
-            requireArg(arg, 'Usage: ucn <file> fn <name>');
-            const { fn, code: fnCode } = extractFunction(code, language, arg);
-            if (fn) {
-                printOutput({ fn, fnCode },
-                    r => output.formatFunctionJson(r.fn, r.fnCode),
-                    r => {
-                        console.log(`${output.lineRange(r.fn.startLine, r.fn.endLine)} ${output.formatFunctionSignature(r.fn)}`);
-                        console.log('─'.repeat(60));
-                        console.log(r.fnCode);
-                    }
-                );
-            } else {
-                console.error(`Function "${arg}" not found`);
-                suggestSimilar(arg, result.functions.map(f => f.name));
-            }
-            break;
+    if (!fileLocalCommands.has(canonical)) {
+        // Auto-detect project root and route to project mode
+        const projectRoot = findProjectRoot(path.dirname(filePath));
+        let effectiveArg = arg;
+        if (['imports', 'exporters', 'fileExports', 'graph'].includes(canonical) && !arg) {
+            effectiveArg = filePath;
         }
+        runProjectCommand(projectRoot, command, effectiveArg);
+        return;
+    }
 
-        case 'class': {
-            requireArg(arg, 'Usage: ucn <file> class <name>');
-            const { cls, code: clsCode } = extractClass(code, language, arg);
-            if (cls) {
-                printOutput({ cls, clsCode },
-                    r => JSON.stringify({ ...r.cls, code: r.clsCode }, null, 2),
-                    r => {
-                        console.log(`${output.lineRange(r.cls.startLine, r.cls.endLine)} ${output.formatClassSignature(r.cls)}`);
-                        console.log('─'.repeat(60));
-                        console.log(r.clsCode);
-                    }
-                );
-            } else {
-                console.error(`Class "${arg}" not found`);
-                suggestSimilar(arg, result.classes.map(c => c.name));
-            }
-            break;
-        }
+    // Require arg for commands that need it
+    const needsArg = { fn: 'fn <name>', class: 'class <name>', find: 'find <name>', usages: 'usages <name>', search: 'search <term>', lines: 'lines <start-end>', typedef: 'typedef <name>' };
+    if (needsArg[canonical]) {
+        requireArg(arg, `Usage: ucn <file> ${needsArg[canonical]}`);
+    }
+
+    // Build single-file index and route through execute()
+    const index = new ProjectIndex(path.dirname(filePath));
+    index.buildSingleFile(filePath);
+    const relativePath = path.relative(index.root, path.resolve(filePath));
+
+    // Map command args to execute() params
+    const paramsByCommand = {
+        toc:     { ...flags },
+        fn:      { name: arg, file: relativePath, ...flags },
+        class:   { name: arg, file: relativePath, ...flags },
+        find:    { name: arg, file: relativePath, ...flags },
+        usages:  { name: arg, ...flags },
+        search:  { term: arg, ...flags },
+        lines:   { file: relativePath, range: arg },
+        typedef: { name: arg, ...flags },
+        api:     { file: relativePath },
+    };
 
-        case 'find': {
-            requireArg(arg, 'Usage: ucn <file> find <name>');
-            findInFile(result, arg, filePath);
-            break;
-        }
+    const { ok, result, error } = execute(index, canonical, paramsByCommand[canonical]);
+    if (!ok) fail(error);
 
-        case 'usages': {
-            requireArg(arg, 'Usage: ucn <file> usages <name>');
-            usagesInFile(code, lines, arg, filePath, result);
+    // Format output using same formatters as project mode
+    switch (canonical) {
+        case 'toc':
+            printOutput(result, output.formatTocJson, r => output.formatToc(r, {
+                detailedHint: 'Add --detailed to list all functions, or "ucn . about <name>" for full details on a symbol',
+                uncertainHint: 'use --include-uncertain to include all'
+            }));
             break;
-        }
-
-        case 'search': {
-            requireArg(arg, 'Usage: ucn <file> search <term>');
-            searchFile(filePath, lines, arg);
+        case 'find':
+            printOutput(result,
+                r => output.formatSymbolJson(r, arg),
+                r => output.formatFindDetailed(r, arg, { depth: flags.depth, top: flags.top, all: flags.all })
+            );
             break;
-        }
-
-        case 'lines': {
-            requireArg(arg, 'Usage: ucn <file> lines <start-end>');
-            printLines(lines, arg);
+        case 'fn':
+            if (result.notes.length) result.notes.forEach(n => console.error('Note: ' + n));
+            printOutput(result, output.formatFnResultJson, output.formatFnResult);
             break;
-        }
-
-        case 'typedef': {
-            requireArg(arg, 'Usage: ucn <file> typedef <name>');
-            typedefInFile(result, arg, filePath);
+        case 'class':
+            if (result.notes.length) result.notes.forEach(n => console.error('Note: ' + n));
+            printOutput(result, output.formatClassResultJson, output.formatClassResult);
+            break;
+        case 'lines':
+            printOutput(result, output.formatLinesJson, r => output.formatLines(r));
+            break;
+        case 'usages':
+            printOutput(result, r => output.formatUsagesJson(r, arg), r => output.formatUsages(r, arg));
+            break;
+        case 'search':
+            printOutput(result, r => output.formatSearchJson(r, arg), r => output.formatSearch(r, arg));
+            break;
+        case 'typedef':
+            printOutput(result, r => output.formatTypedefJson(r, arg), r => output.formatTypedef(r, arg));
             break;
-        }
-
         case 'api':
-            apiInFile(result, filePath);
-            break;
-
-        // Project commands - auto-route to project mode
-        case 'smart':
-        case 'context':
-        case 'tests':
-        case 'about':
-        case 'impact':
-        case 'trace':
-        case 'related':
-        case 'example':
-        case 'graph':
-        case 'stats':
-        case 'deadcode':
-        case 'imports':
-        case 'what-imports':
-        case 'exporters':
-        case 'who-imports':
-        case 'verify':
-        case 'plan':
-        case 'expand':
-        case 'stacktrace':
-        case 'stack':
-        case 'diff-impact':
-        case 'file-exports':
-        case 'what-exports': {
-            // Auto-detect project root and route to project mode
-            const projectRoot = findProjectRoot(path.dirname(filePath));
-
-            // For file-specific commands (imports/exporters/graph), use the target file as arg if no arg given
-            const fileCanonical = resolveCommand(command, 'cli') || command;
-            let effectiveArg = arg;
-            if ((fileCanonical === 'imports' || fileCanonical === 'exporters' ||
-                 fileCanonical === 'fileExports' || fileCanonical === 'graph') && !arg) {
-                effectiveArg = filePath;
-            }
-
-            // For stats/deadcode, no arg needed
-            if (fileCanonical === 'stats' || fileCanonical === 'deadcode') {
-                effectiveArg = arg;  // may be undefined, that's ok
-            }
-
-            runProjectCommand(projectRoot, command, effectiveArg);
+            printOutput(result, r => output.formatApiJson(r, arg), r => output.formatApi(r, arg));
             break;
-        }
-
-        default:
-            console.error(`Unknown command: ${command}`);
-            printUsage();
-            process.exit(1);
-    }
-}
-
-function printFileToc(result, filePath) {
-    // Filter for top-level only if flag is set
-    let functions = result.functions;
-    if (flags.topLevel) {
-        functions = functions.filter(fn => !fn.isNested && fn.indent === 0);
-    }
-
-    if (flags.json) {
-        console.log(output.formatTocJson({
-            totalFiles: 1,
-            totalLines: result.totalLines,
-            totalFunctions: functions.length,
-            totalClasses: result.classes.length,
-            totalState: result.stateObjects.length,
-            byFile: [{
-                file: filePath,
-                language: result.language,
-                lines: result.totalLines,
-                functions,
-                classes: result.classes,
-                state: result.stateObjects
-            }]
-        }));
-        return;
-    }
-
-    console.log(`FILE: ${filePath} (${result.totalLines} lines)`);
-    console.log('═'.repeat(60));
-
-    if (functions.length > 0) {
-        console.log('\nFUNCTIONS:');
-        for (const fn of functions) {
-            const sig = output.formatFunctionSignature(fn);
-            console.log(`  ${output.lineRange(fn.startLine, fn.endLine)} ${sig}`);
-            if (fn.docstring) {
-                console.log(`      ${fn.docstring}`);
-            }
-        }
-    }
-
-    if (result.classes.length > 0) {
-        console.log('\nCLASSES:');
-        for (const cls of result.classes) {
-            console.log(`  ${output.lineRange(cls.startLine, cls.endLine)} ${output.formatClassSignature(cls)}`);
-            if (cls.docstring) {
-                console.log(`      ${cls.docstring}`);
-            }
-            if (cls.members && cls.members.length > 0) {
-                for (const m of cls.members) {
-                    console.log(`    ${output.lineLoc(m.startLine)} ${output.formatMemberSignature(m)}`);
-                }
-            }
-        }
-    }
-
-    if (result.stateObjects.length > 0) {
-        console.log('\nSTATE:');
-        for (const s of result.stateObjects) {
-            console.log(`  ${output.lineRange(s.startLine, s.endLine)} ${s.name}`);
-        }
-    }
-}
-
-function findInFile(result, name, filePath) {
-    const matches = [];
-    const lowerName = name.toLowerCase();
-
-    for (const fn of result.functions) {
-        if (flags.exact ? fn.name === name : fn.name.toLowerCase().includes(lowerName)) {
-            matches.push({ ...fn, type: 'function' });
-        }
-    }
-
-    for (const cls of result.classes) {
-        if (flags.exact ? cls.name === name : cls.name.toLowerCase().includes(lowerName)) {
-            matches.push({ ...cls });
-        }
-    }
-
-    if (flags.json) {
-        console.log(output.formatSymbolJson(matches.map(m => ({ ...m, relativePath: filePath })), name));
-    } else {
-        if (matches.length === 0) {
-            console.log(`No symbols found for "${name}" in ${filePath}`);
-        } else {
-            console.log(`Found ${matches.length} match(es) for "${name}" in ${filePath}:`);
-            console.log('─'.repeat(60));
-            for (const m of matches) {
-                const sig = m.params !== undefined
-                    ? output.formatFunctionSignature(m)
-                    : output.formatClassSignature(m);
-                console.log(`${filePath}:${m.startLine}  ${sig}`);
-            }
-        }
-    }
-}
-
-function usagesInFile(code, lines, name, filePath, result) {
-    const usages = [];
-
-    // Get definitions
-    const defs = [];
-    for (const fn of result.functions) {
-        if (fn.name === name) {
-            defs.push({ ...fn, type: 'function', isDefinition: true, line: fn.startLine });
-        }
-    }
-    for (const cls of result.classes) {
-        if (cls.name === name) {
-            defs.push({ ...cls, isDefinition: true, line: cls.startLine });
-        }
-    }
-
-    // Try AST-based detection first
-    const lang = detectLanguage(filePath);
-    const langModule = getLanguageModule(lang);
-
-    if (langModule && typeof langModule.findUsagesInCode === 'function') {
-        try {
-            const parser = getParser(lang);
-            if (parser) {
-                const astUsages = langModule.findUsagesInCode(code, name, parser);
-
-                for (const u of astUsages) {
-                    // Skip definition lines
-                    if (defs.some(d => d.startLine === u.line)) {
-                        continue;
-                    }
-
-                    const lineContent = lines[u.line - 1] || '';
-                    const usage = {
-                        file: filePath,
-                        relativePath: filePath,
-                        line: u.line,
-                        content: lineContent,
-                        usageType: u.usageType,
-                        isDefinition: false
-                    };
-
-                    // Add context
-                    if (flags.context > 0) {
-                        const idx = u.line - 1;
-                        const before = [];
-                        const after = [];
-                        for (let i = 1; i <= flags.context; i++) {
-                            if (idx - i >= 0) before.unshift(lines[idx - i]);
-                            if (idx + i < lines.length) after.push(lines[idx + i]);
-                        }
-                        usage.before = before;
-                        usage.after = after;
-                    }
-
-                    usages.push(usage);
-                }
-
-                // Add definitions to result and output
-                const allUsages = [
-                    ...defs.map(d => ({
-                        ...d,
-                        relativePath: filePath,
-                        content: lines[d.startLine - 1],
-                        signature: d.params !== undefined
-                            ? output.formatFunctionSignature(d)
-                            : output.formatClassSignature(d)
-                    })),
-                    ...usages
-                ];
-
-                if (flags.json) {
-                    console.log(output.formatUsagesJson(allUsages, name));
-                } else {
-                    console.log(output.formatUsages(allUsages, name));
-                }
-                return;
-            }
-        } catch (e) {
-            // AST parsing failed — usages will be empty, only definitions shown
-        }
-    }
-
-    // Output definitions + any usages found via AST
-    const allUsages = [
-        ...defs.map(d => ({
-            ...d,
-            relativePath: filePath,
-            content: lines[d.startLine - 1],
-            signature: d.params !== undefined
-                ? output.formatFunctionSignature(d)
-                : output.formatClassSignature(d)
-        })),
-        ...usages
-    ];
-
-    if (flags.json) {
-        console.log(output.formatUsagesJson(allUsages, name));
-    } else {
-        console.log(output.formatUsages(allUsages, name));
-    }
-}
-
-function typedefInFile(result, name, filePath) {
-    const typeKinds = ['type', 'interface', 'enum', 'struct', 'trait', 'class'];
-    const matches = result.classes.filter(c =>
-        typeKinds.includes(c.type) &&
-        (flags.exact ? c.name === name : c.name.toLowerCase().includes(name.toLowerCase()))
-    );
-
-    // Extract source code for each match
-    const absPath = path.resolve(filePath);
-    let fileLines = null;
-    try { fileLines = fs.readFileSync(absPath, 'utf-8').split('\n'); } catch (e) { /* ignore */ }
-    const enriched = matches.map(m => {
-        const obj = { ...m, relativePath: filePath };
-        if (fileLines && m.startLine && m.endLine) {
-            obj.code = fileLines.slice(m.startLine - 1, m.endLine).join('\n');
-        }
-        return obj;
-    });
-
-    if (flags.json) {
-        console.log(output.formatTypedefJson(enriched, name));
-    } else {
-        console.log(output.formatTypedef(enriched, name));
-    }
-}
-
-function apiInFile(result, filePath) {
-    const exported = [];
-
-    for (const fn of result.functions) {
-        if (fn.modifiers && (fn.modifiers.includes('export') || fn.modifiers.includes('public'))) {
-            exported.push({
-                name: fn.name,
-                type: 'function',
-                file: filePath,
-                startLine: fn.startLine,
-                endLine: fn.endLine,
-                params: fn.params,
-                returnType: fn.returnType,
-                signature: output.formatFunctionSignature(fn)
-            });
-        }
-    }
-
-    for (const cls of result.classes) {
-        if (cls.modifiers && (cls.modifiers.includes('export') || cls.modifiers.includes('public'))) {
-            exported.push({
-                name: cls.name,
-                type: cls.type,
-                file: filePath,
-                startLine: cls.startLine,
-                endLine: cls.endLine,
-                signature: output.formatClassSignature(cls)
-            });
-        }
-    }
-
-    if (flags.json) {
-        console.log(output.formatApiJson(exported, filePath));
-    } else {
-        console.log(output.formatApi(exported, filePath));
     }
 }
 
@@ -687,13 +392,10 @@ function runProjectCommand(rootDir, command, arg) {
 
     // Build/rebuild if cache not used
     // If cache was loaded but stale, force rebuild to avoid duplicates
+    let needsCacheSave = false;
     if (!usedCache) {
         index.build(null, { quiet: flags.quiet, forceRebuild: cacheWasLoaded, followSymlinks: flags.followSymlinks });
-
-        // Save cache if enabled
-        if (flags.cache) {
-            index.saveCache();
-        }
+        needsCacheSave = flags.cache;
     }
 
     try {
@@ -705,7 +407,7 @@ function runProjectCommand(rootDir, command, arg) {
 
         case 'toc': {
             const { ok, result, error } = execute(index, 'toc', flags);
-            if (!ok) { console.error(error); process.exit(1); }
+            if (!ok) fail(error);
             printOutput(result, output.formatTocJson, r => output.formatToc(r, {
                 detailedHint: 'Add --detailed to list all functions, or "ucn . about <name>" for full details on a symbol',
                 uncertainHint: 'use --include-uncertain to include all'
@@ -715,17 +417,17 @@ function runProjectCommand(rootDir, command, arg) {
 
         case 'find': {
             const { ok, result, error } = execute(index, 'find', { name: arg, ...flags });
-            if (!ok) { console.error(error); process.exit(1); }
+            if (!ok) fail(error);
             printOutput(result,
                 r => output.formatSymbolJson(r, arg),
-                r => { printSymbols(r, arg, { depth: flags.depth, top: flags.top, all: flags.all }); }
+                r => output.formatFindDetailed(r, arg, { depth: flags.depth, top: flags.top, all: flags.all })
             );
             break;
         }
 
         case 'usages': {
             const { ok, result, error } = execute(index, 'usages', { name: arg, ...flags });
-            if (!ok) { console.error(error); process.exit(1); }
+            if (!ok) fail(error);
             printOutput(result,
                 r => output.formatUsagesJson(r, arg),
                 r => output.formatUsages(r, arg)
@@ -735,7 +437,7 @@ function runProjectCommand(rootDir, command, arg) {
 
         case 'example': {
             const { ok, result, error } = execute(index, 'example', { name: arg });
-            if (!ok) { console.error(error); process.exit(1); }
+            if (!ok) fail(error);
             printOutput(result,
                 r => output.formatExampleJson(r, arg),
                 r => output.formatExample(r, arg)
@@ -745,7 +447,7 @@ function runProjectCommand(rootDir, command, arg) {
 
         case 'context': {
             const { ok, result: ctx, error } = execute(index, 'context', { name: arg, ...flags });
-            if (!ok) { console.log(error); break; }
+            if (!ok) fail(error);
             if (flags.json) {
                 console.log(output.formatContextJson(ctx));
             } else {
@@ -789,26 +491,22 @@ function runProjectCommand(rootDir, command, arg) {
             requireArg(arg, 'Usage: ucn . expand <N>\nFirst run "ucn . context <name>" to get numbered items');
             const expandNum = parseInt(arg);
             if (isNaN(expandNum)) {
-                console.error(`Invalid item number: "${arg}"`);
-                process.exit(1);
+                fail(`Invalid item number: "${arg}"`);
             }
             const cached = loadExpandableItems(index.root);
-            if (!cached || !cached.items || cached.items.length === 0) {
-                console.error('No expandable items found. Run "ucn . context <name>" first.');
-                process.exit(1);
-            }
-            const item = cached.items.find(i => i.num === expandNum);
-            if (!item) {
-                console.error(`Item ${expandNum} not found. Available: 1-${cached.items.length}`);
-                process.exit(1);
-            }
-            printExpandedItem(item, cached.root || index.root);
+            const items = cached?.items || [];
+            const match = items.find(i => i.num === expandNum);
+            const { ok, result, error } = execute(index, 'expand', {
+                match, itemNum: expandNum, itemCount: items.length
+            });
+            if (!ok) fail(error);
+            console.log(result.text);
             break;
         }
 
         case 'smart': {
             const { ok, result, error } = execute(index, 'smart', { name: arg, ...flags });
-            if (!ok) { console.error(error); break; }
+            if (!ok) fail(error);
             printOutput(result, output.formatSmartJson, r => output.formatSmart(r, {
                 uncertainHint: 'use --include-uncertain to include all'
             }));
@@ -817,7 +515,7 @@ function runProjectCommand(rootDir, command, arg) {
 
         case 'about': {
             const { ok, result, error } = execute(index, 'about', { name: arg, ...flags });
-            if (!ok) { console.error(error); process.exit(1); }
+            if (!ok) fail(error);
             printOutput(result,
                 output.formatAboutJson,
                 r => output.formatAbout(r, { expand: flags.expand, root: index.root, depth: flags.depth })
@@ -827,80 +525,71 @@ function runProjectCommand(rootDir, command, arg) {
 
         case 'impact': {
             const { ok, result, error } = execute(index, 'impact', { name: arg, ...flags });
-            if (!ok) { console.error(error); process.exit(1); }
+            if (!ok) fail(error);
             printOutput(result, output.formatImpactJson, output.formatImpact);
             break;
         }
 
         case 'plan': {
             const { ok, result, error } = execute(index, 'plan', { name: arg, ...flags });
-            if (!ok) { console.error(error); process.exit(1); }
+            if (!ok) fail(error);
             printOutput(result, output.formatPlanJson, output.formatPlan);
             break;
         }
 
         case 'trace': {
             const { ok, result, error } = execute(index, 'trace', { name: arg, ...flags });
-            if (!ok) { console.error(error); process.exit(1); }
+            if (!ok) fail(error);
             printOutput(result, output.formatTraceJson, output.formatTrace);
             break;
         }
 
         case 'stacktrace': {
             const { ok, result, error } = execute(index, 'stacktrace', { stack: arg });
-            if (!ok) { console.error(error); process.exit(1); }
+            if (!ok) fail(error);
             printOutput(result, output.formatStackTraceJson, output.formatStackTrace);
             break;
         }
 
         case 'verify': {
             const { ok, result, error } = execute(index, 'verify', { name: arg, file: flags.file });
-            if (!ok) { console.error(error); process.exit(1); }
+            if (!ok) fail(error);
             printOutput(result, output.formatVerifyJson, output.formatVerify);
             break;
         }
 
         case 'related': {
             const { ok, result, error } = execute(index, 'related', { name: arg, ...flags });
-            if (!ok) { console.error(error); process.exit(1); }
+            if (!ok) fail(error);
             printOutput(result, output.formatRelatedJson, r => output.formatRelated(r, { showAll: flags.all, top: flags.top }));
             break;
         }
 
-        // ── Commands staying in adapter (complex I/O) ───────────────────
+        // ── Extraction commands (via execute) ────────────────────────────
 
         case 'fn': {
             requireArg(arg, 'Usage: ucn . fn <name>');
-            if (arg.includes(',')) {
-                const fnNames = arg.split(',').map(n => n.trim()).filter(Boolean);
-                for (let i = 0; i < fnNames.length; i++) {
-                    if (i > 0) console.log('\n' + '═'.repeat(60) + '\n');
-                    extractFunctionFromProject(index, fnNames[i]);
-                }
-            } else {
-                extractFunctionFromProject(index, arg);
-            }
+            const { ok, result, error } = execute(index, 'fn', { name: arg, file: flags.file, all: flags.all });
+            if (!ok) fail(error);
+            if (result.notes.length) result.notes.forEach(n => console.error('Note: ' + n));
+            printOutput(result, output.formatFnResultJson, output.formatFnResult);
             break;
         }
 
         case 'class': {
             requireArg(arg, 'Usage: ucn . class <name>');
-            extractClassFromProject(index, arg);
+            const { ok, result, error } = execute(index, 'class', { name: arg, file: flags.file, all: flags.all, maxLines: flags.maxLines });
+            if (!ok) fail(error);
+            if (result.notes.length) result.notes.forEach(n => console.error('Note: ' + n));
+            printOutput(result, output.formatClassResultJson, output.formatClassResult);
             break;
         }
 
         case 'lines': {
-            if (!arg || !flags.file) {
-                console.error('Usage: ucn . lines <range> --file <path>');
-                process.exit(1);
-            }
-            const filePath = index.findFile(flags.file);
-            if (!filePath) {
-                console.error(`File not found: ${flags.file}`);
-                process.exit(1);
-            }
-            const fileContent = fs.readFileSync(filePath, 'utf-8');
-            printLines(fileContent.split('\n'), arg);
+            requireArg(arg, 'Usage: ucn . lines <range> --file <path>');
+            const { ok, result, error } = execute(index, 'lines', { file: flags.file, range: arg });
+            if (!ok) fail(error);
+            printOutput(result, output.formatLinesJson, r => output.formatLines(r));
             break;
         }
 
@@ -908,7 +597,7 @@ function runProjectCommand(rootDir, command, arg) {
 
         case 'imports': {
             const { ok, result, error } = execute(index, 'imports', { file: arg });
-            if (!ok) { console.error(error); process.exit(1); }
+            if (!ok) fail(error);
             printOutput(result,
                 r => output.formatImportsJson(r, arg),
                 r => output.formatImports(r, arg)
@@ -918,7 +607,7 @@ function runProjectCommand(rootDir, command, arg) {
 
         case 'exporters': {
             const { ok, result, error } = execute(index, 'exporters', { file: arg });
-            if (!ok) { console.error(error); process.exit(1); }
+            if (!ok) fail(error);
             printOutput(result,
                 r => output.formatExportersJson(r, arg),
                 r => output.formatExporters(r, arg)
@@ -928,7 +617,7 @@ function runProjectCommand(rootDir, command, arg) {
 
         case 'fileExports': {
             const { ok, result, error } = execute(index, 'fileExports', { file: arg });
-            if (!ok) { console.error(error); process.exit(1); }
+            if (!ok) fail(error);
             printOutput(result,
                 r => JSON.stringify({ file: arg, exports: r }, null, 2),
                 r => output.formatFileExports(r, arg)
@@ -938,14 +627,14 @@ function runProjectCommand(rootDir, command, arg) {
 
         case 'graph': {
             const { ok, result, error } = execute(index, 'graph', { file: arg, direction: flags.direction, depth: flags.depth, all: flags.all });
-            if (!ok) { console.error(error); process.exit(1); }
+            if (!ok) fail(error);
             printOutput(result,
                 r => JSON.stringify({
                     root: path.relative(index.root, r.root),
                     nodes: r.nodes.map(n => ({ file: n.relativePath, depth: n.depth })),
                     edges: r.edges.map(e => ({ from: path.relative(index.root, e.from), to: path.relative(index.root, e.to) }))
                 }, null, 2),
-                r => output.formatGraph(r, { showAll: flags.all || flags.depth !== undefined, maxDepth: flags.depth ?? 2, file: arg })
+                r => output.formatGraph(r, { showAll: flags.all || flags.depth != null, maxDepth: flags.depth != null ? parseInt(flags.depth, 10) : 2, file: arg })
             );
             break;
         }
@@ -954,7 +643,7 @@ function runProjectCommand(rootDir, command, arg) {
 
         case 'typedef': {
             const { ok, result, error } = execute(index, 'typedef', { name: arg, exact: flags.exact });
-            if (!ok) { console.error(error); process.exit(1); }
+            if (!ok) fail(error);
             printOutput(result,
                 r => output.formatTypedefJson(r, arg),
                 r => output.formatTypedef(r, arg)
@@ -964,7 +653,7 @@ function runProjectCommand(rootDir, command, arg) {
 
         case 'tests': {
             const { ok, result, error } = execute(index, 'tests', { name: arg, callsOnly: flags.callsOnly });
-            if (!ok) { console.error(error); process.exit(1); }
+            if (!ok) fail(error);
             printOutput(result,
                 r => output.formatTestsJson(r, arg),
                 r => output.formatTests(r, arg)
@@ -974,7 +663,7 @@ function runProjectCommand(rootDir, command, arg) {
 
         case 'api': {
             const { ok, result, error } = execute(index, 'api', { file: arg });
-            if (!ok) { console.error(error); process.exit(1); }
+            if (!ok) fail(error);
             printOutput(result,
                 r => output.formatApiJson(r, arg),
                 r => output.formatApi(r, arg)
@@ -984,7 +673,7 @@ function runProjectCommand(rootDir, command, arg) {
 
         case 'search': {
             const { ok, result, error } = execute(index, 'search', { term: arg, ...flags });
-            if (!ok) { console.error(error); process.exit(1); }
+            if (!ok) fail(error);
             printOutput(result,
                 r => output.formatSearchJson(r, arg),
                 r => output.formatSearch(r, arg)
@@ -994,7 +683,7 @@ function runProjectCommand(rootDir, command, arg) {
 
         case 'deadcode': {
             const { ok, result, error } = execute(index, 'deadcode', { ...flags, in: flags.in || subdirScope });
-            if (!ok) { console.error(error); process.exit(1); }
+            if (!ok) fail(error);
             printOutput(result,
                 output.formatDeadcodeJson,
                 r => output.formatDeadcode(r, {
@@ -1008,7 +697,7 @@ function runProjectCommand(rootDir, command, arg) {
 
         case 'stats': {
             const { ok, result, error } = execute(index, 'stats', { functions: flags.functions });
-            if (!ok) { console.error(error); process.exit(1); }
+            if (!ok) fail(error);
             printOutput(result,
                 output.formatStatsJson,
                 r => output.formatStats(r, { top: flags.top })
@@ -1018,7 +707,7 @@ function runProjectCommand(rootDir, command, arg) {
 
         case 'diffImpact': {
             const { ok, result, error } = execute(index, 'diffImpact', { base: flags.base, staged: flags.staged, file: flags.file });
-            if (!ok) { console.error(error); process.exit(1); }
+            if (!ok) fail(error);
             printOutput(result, output.formatDiffImpactJson, output.formatDiffImpact);
             break;
         }
@@ -1026,310 +715,25 @@ function runProjectCommand(rootDir, command, arg) {
         default:
             console.error(`Unknown command: ${canonical}`);
             printUsage();
-            process.exit(1);
+            throw new CommandError();
     }
     } catch (e) {
-        console.error(`Error: ${e.message}`);
-        process.exit(1);
-    }
-}
-
-function extractFunctionFromProject(index, name, overrideFlags) {
-    const f = overrideFlags || flags;
-    const matches = index.find(name, { file: f.file }).filter(m => m.type === 'function' || m.params !== undefined);
-
-    if (matches.length === 0) {
-        console.error(`Function "${name}" not found`);
-        return;
-    }
-
-    if (matches.length > 1 && !f.file && f.all) {
-        // Show all definitions
-        for (let i = 0; i < matches.length; i++) {
-            const m = matches[i];
-            const code = fs.readFileSync(m.file, 'utf-8');
-            const lines = code.split('\n');
-            const extracted = lines.slice(m.startLine - 1, m.endLine);
-            const fnCode = cleanHtmlScriptTags(extracted, detectLanguage(m.file)).join('\n');
-            if (i > 0) console.log('');
-            if (f.json) {
-                console.log(output.formatFunctionJson(m, fnCode));
-            } else {
-                console.log(output.formatFn(m, fnCode));
-            }
-        }
-        return;
-    }
-
-    let match;
-    if (matches.length > 1 && !f.file) {
-        // Auto-select best match using same scoring as resolveSymbol
-        match = pickBestDefinition(matches);
-        const others = matches.filter(m => m !== match).map(m => `${m.relativePath}:${m.startLine}`).join(', ');
-        console.error(`Note: Found ${matches.length} definitions for "${name}". Using ${match.relativePath}:${match.startLine}. Also in: ${others}. Use --file to disambiguate or --all to show all.`);
-    } else {
-        match = matches[0];
-    }
-
-    // Extract code directly using symbol index location (works for class methods and overloads)
-    const code = fs.readFileSync(match.file, 'utf-8');
-    const lines = code.split('\n');
-    const extracted = lines.slice(match.startLine - 1, match.endLine);
-    const fnCode = cleanHtmlScriptTags(extracted, detectLanguage(match.file)).join('\n');
-
-    if (f.json) {
-        console.log(output.formatFunctionJson(match, fnCode));
-    } else {
-        console.log(output.formatFn(match, fnCode));
-    }
-}
-
-function extractClassFromProject(index, name, overrideFlags) {
-    const f = overrideFlags || flags;
-    const matches = index.find(name, { file: f.file }).filter(m =>
-        ['class', 'interface', 'type', 'enum', 'struct', 'trait'].includes(m.type)
-    );
-
-    if (matches.length === 0) {
-        console.error(`Class "${name}" not found`);
-        return;
-    }
-
-    if (matches.length > 1 && !f.file && f.all) {
-        // Show all definitions using index data (no re-parsing)
-        for (let i = 0; i < matches.length; i++) {
-            const m = matches[i];
-            const code = fs.readFileSync(m.file, 'utf-8');
-            const codeLines = code.split('\n');
-            const extracted = codeLines.slice(m.startLine - 1, m.endLine);
-            const clsCode = cleanHtmlScriptTags(extracted, detectLanguage(m.file)).join('\n');
-            if (i > 0) console.log('');
-            if (f.json) {
-                console.log(JSON.stringify({ ...m, code: clsCode }, null, 2));
-            } else {
-                console.log(output.formatClass(m, clsCode));
-            }
-        }
-        return;
-    }
-
-    let match;
-    if (matches.length > 1 && !f.file) {
-        // Auto-select best match using same scoring as resolveSymbol
-        match = pickBestDefinition(matches);
-        const others = matches.filter(m => m !== match).map(m => `${m.relativePath}:${m.startLine}`).join(', ');
-        console.error(`Note: Found ${matches.length} definitions for "${name}". Using ${match.relativePath}:${match.startLine}. Also in: ${others}. Use --file to disambiguate or --all to show all.`);
-    } else {
-        match = matches[0];
-    }
-
-    // Use index data directly instead of re-parsing the file
-    const code = fs.readFileSync(match.file, 'utf-8');
-    const codeLines = code.split('\n');
-    const classLineCount = match.endLine - match.startLine + 1;
-
-    // Large class summary (>200 lines) when no --max-lines specified
-    if (classLineCount > 200 && !f.maxLines) {
-        if (f.json) {
-            const extracted = codeLines.slice(match.startLine - 1, match.endLine);
-            const clsCode = cleanHtmlScriptTags(extracted, detectLanguage(match.file)).join('\n');
-            console.log(JSON.stringify({ ...match, code: clsCode }, null, 2));
-        } else {
-            const lines = [];
-            lines.push(`${match.relativePath}:${match.startLine}`);
-            lines.push(`${output.lineRange(match.startLine, match.endLine)} ${output.formatClassSignature(match)}`);
-            lines.push('\u2500'.repeat(60));
-            const methods = index.findMethodsForType(match.name);
-            if (methods.length > 0) {
-                lines.push(`\nMethods (${methods.length}):`);
-                for (const m of methods) {
-                    lines.push(`  ${output.formatFunctionSignature(m)}  [line ${m.startLine}]`);
-                }
-            }
-            lines.push(`\nClass is ${classLineCount} lines. Use --max-lines=N to see source, or "fn <method>" for individual methods.`);
-            console.log(lines.join('\n'));
-        }
-        return;
-    }
-
-    // Truncated source with --max-lines
-    if (f.maxLines && classLineCount > f.maxLines) {
-        const truncated = codeLines.slice(match.startLine - 1, match.startLine - 1 + f.maxLines);
-        const truncatedCode = cleanHtmlScriptTags(truncated, detectLanguage(match.file)).join('\n');
-        if (f.json) {
-            console.log(JSON.stringify({ ...match, code: truncatedCode, truncated: true, totalLines: classLineCount }, null, 2));
-        } else {
-            console.log(output.formatClass(match, truncatedCode));
-            console.log(`\n... showing ${f.maxLines} of ${classLineCount} lines`);
-        }
-        return;
-    }
-
-    const extracted = codeLines.slice(match.startLine - 1, match.endLine);
-    const clsCode = cleanHtmlScriptTags(extracted, detectLanguage(match.file)).join('\n');
-
-    if (f.json) {
-        console.log(JSON.stringify({ ...match, code: clsCode }, null, 2));
-    } else {
-        console.log(output.formatClass(match, clsCode));
-    }
-}
-
-
-function printSymbols(symbols, query, options = {}) {
-    const { depth, top, all } = options;
-    const DEFAULT_LIMIT = 5;
-
-    if (symbols.length === 0) {
-        console.log(`No symbols found for "${query}"`);
-        return;
-    }
-
-    // Determine how many to show
-    const limit = all ? symbols.length : (top > 0 ? top : DEFAULT_LIMIT);
-    const showing = Math.min(limit, symbols.length);
-    const hidden = symbols.length - showing;
-
-    if (hidden > 0) {
-        console.log(`Found ${symbols.length} match(es) for "${query}" (showing top ${showing}):`);
-    } else {
-        console.log(`Found ${symbols.length} match(es) for "${query}":`);
-    }
-    console.log('─'.repeat(60));
-
-    for (let i = 0; i < showing; i++) {
-        const s = symbols[i];
-        // Depth 0: just location
-        if (depth === '0') {
-            console.log(`${s.relativePath}:${s.startLine}`);
-            continue;
-        }
-
-        // Depth 1 (default): location + signature
-        const sig = s.params !== undefined
-            ? output.formatFunctionSignature(s)
-            : output.formatClassSignature(s);
-
-        // Compute and display confidence indicator
-        const confidence = computeConfidence(s);
-        const confStr = confidence.level !== 'high' ? ` [${confidence.level}]` : '';
-
-        console.log(`${s.relativePath}:${s.startLine}  ${sig}${confStr}`);
-        if (s.usageCounts !== undefined) {
-            const c = s.usageCounts;
-            const parts = [];
-            if (c.calls > 0) parts.push(`${c.calls} calls`);
-            if (c.definitions > 0) parts.push(`${c.definitions} def`);
-            if (c.imports > 0) parts.push(`${c.imports} imports`);
-            if (c.references > 0) parts.push(`${c.references} refs`);
-            console.log(`  (${c.total} usages: ${parts.join(', ')})`);
-        } else if (s.usageCount !== undefined) {
-            console.log(`  (${s.usageCount} usages)`);
-        }
-
-        // Show confidence reason if not high
-        if (confidence.level !== 'high' && confidence.reasons.length > 0) {
-            console.log(`  ⚠ ${confidence.reasons.join(', ')}`);
-        }
-
-        // Depth 2: + first 10 lines of code
-        if (depth === '2' || depth === 'full') {
-            try {
-                const content = fs.readFileSync(s.file, 'utf-8');
-                const lines = content.split('\n');
-                const maxLines = depth === 'full' ? (s.endLine - s.startLine + 1) : 10;
-                const endLine = Math.min(s.startLine + maxLines - 1, s.endLine);
-                console.log('  ───');
-                for (let i = s.startLine - 1; i < endLine; i++) {
-                    console.log(`  ${lines[i]}`);
-                }
-                if (depth === '2' && s.endLine > endLine) {
-                    console.log(`  ... (${s.endLine - endLine} more lines)`);
-                }
-            } catch (e) {
-                // Skip code extraction on error
-            }
+        if (!(e instanceof CommandError)) {
+            console.error(`Error: ${e.message}`);
         }
-        console.log('');
-    }
-
-    // Show hint about hidden results
-    if (hidden > 0) {
-        console.log(`... ${hidden} more result(s). Use --all to see all, or --top=N to see more.`);
-    }
-}
-
-/**
- * Compute confidence level for a symbol match
- * @returns {{ level: 'high'|'medium'|'low', reasons: string[] }}
- */
-function computeConfidence(symbol) {
-    const reasons = [];
-    let score = 100;
-
-    // Check function span (very long functions may have incorrect boundaries)
-    const span = (symbol.endLine || symbol.startLine) - symbol.startLine;
-    if (span > 500) {
-        score -= 30;
-        reasons.push('very long function (>500 lines)');
-    } else if (span > 200) {
-        score -= 15;
-        reasons.push('long function (>200 lines)');
-    }
-
-    // Check for complex type annotations (nested generics)
-    const params = Array.isArray(symbol.params) ? symbol.params : [];
-    const signature = params.map(p => p.type || '').join(' ') + (symbol.returnType || '');
-    const genericDepth = countNestedGenerics(signature);
-    if (genericDepth > 3) {
-        score -= 20;
-        reasons.push('complex nested generics');
-    } else if (genericDepth > 2) {
-        score -= 10;
-        reasons.push('nested generics');
-    }
-
-    // Check file size by checking if file property exists and getting line count
-    if (symbol.file) {
-        try {
-            const stats = fs.statSync(symbol.file);
-            const sizeKB = stats.size / 1024;
-            if (sizeKB > 500) {
-                score -= 20;
-                reasons.push('very large file (>500KB)');
-            } else if (sizeKB > 200) {
-                score -= 10;
-                reasons.push('large file (>200KB)');
-            }
-        } catch (e) {
-            // Skip file size check on error
+        process.exitCode = 1;
+    } finally {
+        // Save cache after command execution so callsCache populated
+        // by findCallers/findCallees gets persisted to disk.
+        // On cache-hit runs, only re-save if callsCache was mutated.
+        if (flags.cache && (needsCacheSave || index.callsCacheDirty)) {
+            try { index.saveCache(); } catch (e) { /* best-effort */ }
         }
     }
-
-    // Determine level
-    let level = 'high';
-    if (score < 50) level = 'low';
-    else if (score < 80) level = 'medium';
-
-    return { level, reasons };
 }
 
-/**
- * Count depth of nested generic brackets
- */
-function countNestedGenerics(str) {
-    let maxDepth = 0;
-    let depth = 0;
-    for (const char of str) {
-        if (char === '<') {
-            depth++;
-            maxDepth = Math.max(maxDepth, depth);
-        } else if (char === '>') {
-            depth--;
-        }
-    }
-    return maxDepth;
-}
+// extractFunctionFromProject and extractClassFromProject removed —
+// all surfaces now use execute(index, 'fn'/'class', params) from core/execute.js
 
 
 /**
@@ -1368,30 +772,7 @@ function loadExpandableItems(root) {
 /**
  * Print expanded code for a cached item
  */
-function printExpandedItem(item, root) {
-    const filePath = item.file || (root && item.relativePath ? path.join(root, item.relativePath) : null);
-    if (!filePath) {
-        console.error(`Cannot locate file for ${item.name}`);
-        return;
-    }
-
-    try {
-        const content = fs.readFileSync(filePath, 'utf-8');
-        const lines = content.split('\n');
-        const startLine = item.startLine || item.line || 1;
-        const endLine = item.endLine || startLine + 20;
-
-        console.log(`[${item.num}] ${item.name} (${item.type})`);
-        console.log(`${item.relativePath}:${startLine}-${endLine}`);
-        console.log('═'.repeat(60));
-
-        for (let i = startLine - 1; i < Math.min(endLine, lines.length); i++) {
-            console.log(lines[i]);
-        }
-    } catch (e) {
-        console.error(`Error reading ${filePath}: ${e.message}`);
-    }
-}
+// printExpandedItem removed — all surfaces now use execute(index, 'expand', ...)
 
 
 
@@ -1440,22 +821,21 @@ function runGlobCommand(pattern, command, arg) {
                 }
             }
 
-            const tocRaw = { totalFiles: files.length, totalLines, totalFunctions, totalClasses, totalState, byFile };
+            // Convert glob toc to shared formatter format
+            const toc = {
+                totals: { files: files.length, lines: totalLines, functions: totalFunctions, classes: totalClasses, state: totalState },
+                files: byFile.map(f => ({
+                    file: f.file,
+                    lines: f.lines,
+                    functions: f.functions.length,
+                    classes: f.classes.length,
+                    state: f.stateObjects ? f.stateObjects.length : (f.state ? f.state.length : 0)
+                })),
+                meta: {}
+            };
             if (flags.json) {
-                console.log(output.formatTocJson(tocRaw));
+                console.log(output.formatTocJson(toc));
             } else {
-                // Convert glob toc to shared formatter format
-                const toc = {
-                    totals: { files: files.length, lines: totalLines, functions: totalFunctions, classes: totalClasses, state: totalState },
-                    files: byFile.map(f => ({
-                        file: f.file,
-                        lines: f.lines,
-                        functions: f.functions.length,
-                        classes: f.classes.length,
-                        state: f.stateObjects ? f.stateObjects.length : (f.state ? f.state.length : 0)
-                    })),
-                    meta: {}
-                };
                 console.log(output.formatToc(toc, {
                     detailedHint: 'Add --detailed to list all functions, or "ucn . about <name>" for full details on a symbol'
                 }));
@@ -1511,7 +891,7 @@ function findInGlobFiles(files, name) {
     if (flags.json) {
         console.log(output.formatSymbolJson(allMatches, name));
     } else {
-        printSymbols(allMatches, name, { depth: flags.depth, top: flags.top, all: flags.all });
+        console.log(output.formatFindDetailed(allMatches, name, { depth: flags.depth, top: flags.top, all: flags.all }));
     }
 }
 
@@ -1573,103 +953,6 @@ function searchGlobFiles(files, term) {
 // HELPERS
 // ============================================================================
 
-function searchFile(filePath, lines, term) {
-    const useRegex = flags.regex !== false;
-    let regex;
-    if (useRegex) {
-        try { regex = new RegExp(term, flags.caseSensitive ? '' : 'i'); } catch (e) { regex = new RegExp(escapeRegExp(term), flags.caseSensitive ? '' : 'i'); }
-    } else {
-        regex = new RegExp(escapeRegExp(term), flags.caseSensitive ? '' : 'i');
-    }
-    const matches = [];
-
-    lines.forEach((line, idx) => {
-        if (regex.test(line)) {
-            if (flags.codeOnly && isCommentOrString(line)) {
-                return;
-            }
-
-            const match = { line: idx + 1, content: line };
-
-            if (flags.context > 0) {
-                const before = [];
-                const after = [];
-                for (let i = 1; i <= flags.context; i++) {
-                    if (idx - i >= 0) before.unshift(lines[idx - i]);
-                    if (idx + i < lines.length) after.push(lines[idx + i]);
-                }
-                match.before = before;
-                match.after = after;
-            }
-
-            matches.push(match);
-        }
-    });
-
-    if (flags.json) {
-        console.log(output.formatSearchJson([{ file: filePath, matches }], term));
-    } else {
-        console.log(`Found ${matches.length} matches for "${term}" in ${filePath}:`);
-        for (const m of matches) {
-            console.log(`  ${m.line}: ${m.content.trim()}`);
-            if (m.before && m.before.length > 0) {
-                for (const line of m.before) {
-                    console.log(`      ... ${line.trim()}`);
-                }
-            }
-            if (m.after && m.after.length > 0) {
-                for (const line of m.after) {
-                    console.log(`      ... ${line.trim()}`);
-                }
-            }
-        }
-    }
-}
-
-function printLines(lines, range) {
-    const parts = range.split('-');
-    const start = parseInt(parts[0], 10);
-    const end = parts.length > 1 ? parseInt(parts[1], 10) : start;
-
-    // Validate input
-    if (isNaN(start) || isNaN(end)) {
-        console.error(`Invalid line range: "${range}". Expected format: <start>-<end> or <line>`);
-        process.exit(1);
-    }
-
-    if (start < 1) {
-        console.error(`Invalid start line: ${start}. Line numbers must be >= 1`);
-        process.exit(1);
-    }
-
-    // Handle reversed range by swapping
-    const startLine = Math.min(start, end);
-    const endLine = Math.max(start, end);
-
-    // Check for out-of-bounds
-    if (startLine > lines.length) {
-        console.error(`Line ${startLine} is out of bounds. File has ${lines.length} lines.`);
-        process.exit(1);
-    }
-
-    // Print lines (clamping end to file length)
-    const actualEnd = Math.min(endLine, lines.length);
-    for (let i = startLine - 1; i < actualEnd; i++) {
-        console.log(`${output.lineNum(i + 1)} │ ${lines[i]}`);
-    }
-}
-
-function suggestSimilar(query, names) {
-    const lower = query.toLowerCase();
-    const similar = names.filter(n => n.toLowerCase().includes(lower));
-    if (similar.length > 0) {
-        console.log('\nDid you mean:');
-        for (const s of similar.slice(0, 5)) {
-            console.log(`  - ${s}`);
-        }
-    }
-}
-
 function escapeRegExp(text) {
     return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
@@ -1874,10 +1157,26 @@ Flags can be added per-command: context myFunc --include-methods
         // Parse command, flags, and arg from interactive input
         const tokens = input.split(/\s+/);
         const command = tokens[0];
-        const flagTokens = tokens.filter(t => t.startsWith('--'));
-        const argTokens = tokens.slice(1).filter(t => !t.startsWith('--'));
+        // Flags that take a space-separated value (--flag value)
+        const valueFlagNames = new Set(['--file', '--in', '--base', '--add-param', '--remove-param', '--rename-to', '--default', '--depth', '--top', '--context', '--max-lines', '--direction', '--exclude', '--not', '--stack']);
+        const flagTokens = [];
+        const argTokens = [];
+        const skipNext = new Set();
+        for (let i = 1; i < tokens.length; i++) {
+            if (skipNext.has(i)) { continue; }
+            if (tokens[i].startsWith('--')) {
+                flagTokens.push(tokens[i]);
+                // If it's a value-flag without = and next token exists and isn't a flag, consume it too
+                if (valueFlagNames.has(tokens[i]) && !tokens[i].includes('=') && i + 1 < tokens.length && !tokens[i + 1].startsWith('--')) {
+                    flagTokens.push(tokens[i + 1]);
+                    skipNext.add(i + 1);
+                }
+            } else {
+                argTokens.push(tokens[i]);
+            }
+        }
         const arg = argTokens.join(' ');
-        const iflags = parseInteractiveFlags(flagTokens);
+        const iflags = parseFlags(flagTokens);
 
         try {
             const iCanonical = resolveCommand(command, 'cli') || command;
@@ -1894,89 +1193,36 @@ Flags can be added per-command: context myFunc --include-methods
     });
 }
 
-/**
- * Parse flags from interactive command tokens.
- * Returns a flags object similar to the global flags but scoped to this command.
- */
-function parseInteractiveFlags(tokens) {
-    return {
-        file: tokens.find(a => a.startsWith('--file='))?.split('=')[1] || null,
-        exclude: tokens.find(a => a.startsWith('--exclude=') || a.startsWith('--not='))?.split('=')[1]?.split(',') || [],
-        in: tokens.find(a => a.startsWith('--in='))?.split('=')[1] || null,
-        includeTests: tokens.includes('--include-tests'),
-        includeExported: tokens.includes('--include-exported'),
-        includeDecorated: tokens.includes('--include-decorated'),
-        includeUncertain: tokens.includes('--include-uncertain'),
-        includeMethods: tokens.includes('--include-methods=false') ? false : tokens.includes('--include-methods') ? true : undefined,
-        detailed: tokens.includes('--detailed'),
-        topLevel: tokens.includes('--top-level'),
-        all: tokens.includes('--all'),
-        exact: tokens.includes('--exact'),
-        callsOnly: tokens.includes('--calls-only'),
-        codeOnly: tokens.includes('--code-only'),
-        caseSensitive: tokens.includes('--case-sensitive'),
-        withTypes: tokens.includes('--with-types'),
-        expand: tokens.includes('--expand'),
-        depth: tokens.find(a => a.startsWith('--depth='))?.split('=')[1] || null,
-        top: parseInt(tokens.find(a => a.startsWith('--top='))?.split('=')[1] || '0'),
-        context: parseInt(tokens.find(a => a.startsWith('--context='))?.split('=')[1] || '0'),
-        direction: tokens.find(a => a.startsWith('--direction='))?.split('=')[1] || null,
-        addParam: tokens.find(a => a.startsWith('--add-param='))?.split('=')[1] || null,
-        removeParam: tokens.find(a => a.startsWith('--remove-param='))?.split('=')[1] || null,
-        renameTo: tokens.find(a => a.startsWith('--rename-to='))?.split('=')[1] || null,
-        defaultValue: tokens.find(a => a.startsWith('--default='))?.split('=')[1] || null,
-        base: tokens.find(a => a.startsWith('--base='))?.split('=')[1] || null,
-        staged: tokens.includes('--staged'),
-        maxLines: parseInt(tokens.find(a => a.startsWith('--max-lines='))?.split('=')[1] || '0') || null,
-        regex: tokens.includes('--no-regex') ? false : undefined,
-        functions: tokens.includes('--functions'),
-    };
-}
+// parseInteractiveFlags removed — both global and interactive mode now use parseFlags()
 
 function executeInteractiveCommand(index, command, arg, iflags = {}, cache = null) {
     switch (command) {
 
-        // ── Special commands (complex I/O, stay in adapter) ──────────────
+        // ── Extraction commands (via execute) ────────────────────────────
 
         case 'fn': {
-            if (!arg) {
-                console.log('Usage: fn <name>[,name2,...] [--file=<pattern>]');
-                return;
-            }
-            // Support comma-separated names for bulk extraction
-            if (arg.includes(',')) {
-                const fnNames = arg.split(',').map(n => n.trim()).filter(Boolean);
-                for (let i = 0; i < fnNames.length; i++) {
-                    if (i > 0) console.log('\n' + '═'.repeat(60) + '\n');
-                    extractFunctionFromProject(index, fnNames[i], iflags);
-                }
-            } else {
-                extractFunctionFromProject(index, arg, iflags);
-            }
+            if (!arg) { console.log('Usage: fn <name>[,name2,...] [--file=<pattern>]'); return; }
+            const { ok, result, error } = execute(index, 'fn', { name: arg, file: iflags.file, all: iflags.all });
+            if (!ok) { console.log(error); return; }
+            if (result.notes.length) result.notes.forEach(n => console.log('Note: ' + n));
+            console.log(output.formatFnResult(result));
             break;
         }
 
         case 'class': {
-            if (!arg) {
-                console.log('Usage: class <name> [--file=<pattern>]');
-                return;
-            }
-            extractClassFromProject(index, arg, iflags);
+            if (!arg) { console.log('Usage: class <name> [--file=<pattern>]'); return; }
+            const { ok, result, error } = execute(index, 'class', { name: arg, file: iflags.file, all: iflags.all, maxLines: iflags.maxLines });
+            if (!ok) { console.log(error); return; }
+            if (result.notes.length) result.notes.forEach(n => console.log('Note: ' + n));
+            console.log(output.formatClassResult(result));
             break;
         }
 
         case 'lines': {
-            if (!arg || !iflags.file) {
-                console.log('Usage: lines <range> --file=<file>');
-                return;
-            }
-            const filePath = index.findFile(iflags.file);
-            if (!filePath) {
-                console.log(`File not found: ${iflags.file}`);
-                return;
-            }
-            const fileContent = fs.readFileSync(filePath, 'utf-8');
-            printLines(fileContent.split('\n'), arg);
+            if (!arg) { console.log('Usage: lines <range> --file=<file>'); return; }
+            const { ok, result, error } = execute(index, 'lines', { file: iflags.file, range: arg });
+            if (!ok) { console.log(error); return; }
+            console.log(output.formatLines(result));
             break;
         }
 
@@ -1990,46 +1236,30 @@ function executeInteractiveCommand(index, command, arg, iflags = {}, cache = nul
                 console.log(`Invalid item number: "${arg}"`);
                 return;
             }
+            let match, itemCount, symbolName;
             if (cache) {
-                const { match, itemCount } = cache.lookup(index.root, expandNum);
-                if (!match && itemCount === 0) {
-                    console.log('No expandable items. Run context first.');
-                    return;
-                }
-                if (!match) {
-                    console.log(`Item ${expandNum} not found. Available: 1-${itemCount}`);
-                    return;
-                }
-                const rendered = renderExpandItem(match, index.root);
-                if (!rendered.ok) { console.log(rendered.error); return; }
-                console.log(rendered.text);
+                const lookup = cache.lookup(index.root, expandNum);
+                match = lookup.match;
+                itemCount = lookup.itemCount;
+                symbolName = lookup.symbolName;
             } else {
-                // Fallback to file-based cache (CLI one-shot)
                 const cached = loadExpandableItems(index.root);
-                if (!cached || !cached.items || cached.items.length === 0) {
-                    console.log('No expandable items. Run context first.');
-                    return;
-                }
-                const expandMatch = cached.items.find(i => i.num === expandNum);
-                if (!expandMatch) {
-                    console.log(`Item ${expandNum} not found. Available: 1-${cached.items.length}`);
-                    return;
-                }
-                printExpandedItem(expandMatch, cached.root || index.root);
+                const items = cached?.items || [];
+                match = items.find(i => i.num === expandNum);
+                itemCount = items.length;
             }
+            const { ok, result, error } = execute(index, 'expand', {
+                match, itemNum: expandNum, itemCount, symbolName
+            });
+            if (!ok) { console.log(error); return; }
+            console.log(result.text);
             break;
         }
 
-        // ── find: uses printSymbols (interactive-only formatter) ─────────
-
         case 'find': {
             const { ok, result, error } = execute(index, 'find', { name: arg, ...iflags });
             if (!ok) { console.log(error); return; }
-            if (result.length === 0) {
-                console.log(`No symbols found for "${arg}"`);
-            } else {
-                printSymbols(result, arg, { top: iflags.top });
-            }
+            console.log(output.formatFindDetailed(result, arg, { depth: iflags.depth, top: iflags.top, all: iflags.all }));
             break;
         }
 
@@ -2080,7 +1310,7 @@ function executeInteractiveCommand(index, command, arg, iflags = {}, cache = nul
         case 'about': {
             const { ok, result, error } = execute(index, 'about', { name: arg, ...iflags });
             if (!ok) { console.log(error); return; }
-            console.log(output.formatAbout(result, { expand: iflags.expand, root: index.root, showAll: iflags.all }));
+            console.log(output.formatAbout(result, { expand: iflags.expand, root: index.root, showAll: iflags.all, depth: iflags.depth }));
             break;
         }
 
@@ -2230,7 +1460,8 @@ function executeInteractiveCommand(index, command, arg, iflags = {}, cache = nul
 // ============================================================================
 
 if (flags.interactive) {
-    const target = positionalArgs[0] || '.';
+    let target = positionalArgs[0] || '.';
+    if (COMMANDS.has(target)) target = '.';
     runInteractive(target);
 } else {
     main();