@tyroneross/navgator 0.2.2 → 0.9.0

package/dist/cli/commands/freshness.js

@@ -0,0 +1,90 @@
+import { spawn } from 'child_process';
+import { markDirty } from '../../freshness/dirty-ledger.js';
+import { drain, drainUntilClean } from '../../freshness/drainer.js';
+import { computeStamp, readStamp } from '../../freshness/stamp.js';
+import { scan } from '../../scanner.js';
+/** Production scanFn: run the real incremental scan; it persists everything. */
+const realScan = async (root) => {
+    await scan(root, {});
+};
+/** Testable core: append paths to the dirty ledger. */
+export function runMarkDirty(paths, root) {
+    markDirty(paths, root);
+}
+/** Testable core: run a drain with the real scanner. */
+export async function runDrain(root, minIntervalMs) {
+    return drain(root, { scanFn: realScan, minIntervalMs });
+}
+/** Testable core: drain repeatedly until the ledger is empty (trailing-edge). */
+export async function runDrainUntilClean(root, minIntervalMs) {
+    return drainUntilClean(root, { scanFn: realScan, minIntervalMs });
+}
+/** Testable core: return the current stamp (computing a transient one if none). */
+export async function runFreshness(root) {
+    return readStamp(root) ?? (await computeStamp(root, { inFlight: false }));
+}
+/**
+ * Testable core: populate the enrichment cache by resolving boundary nodes
+ * (npm/pip/spm/...) upstream, then return the drift report. This is the
+ * network leg of the freshness axis — the offline scan only STAMPS from cache,
+ * so this is what makes external enrichment actually resolve. Run it from
+ * session-start, a cron, or the external-resolver agent (pinned to haiku).
+ */
+export async function runRefreshExternal(root, force) {
+    const { loadAllComponents } = await import('../../storage.js');
+    const { loadCache } = await import('../../enrich/cache.js');
+    const { refreshExternal } = await import('../../enrich/external-resolver.js');
+    const components = await loadAllComponents(undefined, root);
+    const cache = loadCache();
+    return refreshExternal(components, cache, Date.now(), { force });
+}
+export function registerFreshnessCommands(program) {
+    program
+        .command('mark-dirty <paths...>')
+        .description('Append changed file paths to the dirty-set ledger (used by the PostToolUse hook)')
+        .option('--drain', 'Spawn a detached background drain after marking')
+        .action((paths, options) => {
+        const root = process.cwd();
+        runMarkDirty(paths, root);
+        if (options.drain) {
+            // Detached + unref so the hook returns immediately (non-blocking). Uses
+            // --until-clean so the trailing edits of a burst still get drained.
+            const child = spawn(process.execPath, [process.argv[1], 'drain', '--until-clean'], {
+                cwd: root,
+                detached: true,
+                stdio: 'ignore',
+            });
+            child.unref();
+        }
+        console.log(JSON.stringify({ ok: true, marked: paths.length }));
+    });
+    program
+        .command('drain')
+        .description('Coalesce the dirty set and run an incremental scan under the single-writer lock')
+        .option('--min-interval <ms>', 'Debounce window in ms', (v) => parseInt(v, 10))
+        .option('--until-clean', 'Keep draining past debounce/busy until the ledger is empty (trailing-edge)')
+        .action(async (options) => {
+        if (options.untilClean) {
+            const results = await runDrainUntilClean(process.cwd(), options.minInterval);
+            console.log(JSON.stringify({ attempts: results.length, last: results[results.length - 1] }));
+            return;
+        }
+        const result = await runDrain(process.cwd(), options.minInterval);
+        console.log(JSON.stringify(result));
+    });
+    program
+        .command('freshness')
+        .description('Print the freshness stamp for the architecture view (honesty contract)')
+        .action(async () => {
+        console.log(JSON.stringify(await runFreshness(process.cwd()), null, 2));
+    });
+    program
+        .command('refresh-external')
+        .description('Resolve external boundary nodes (npm/pip/spm/...) upstream and populate the enrichment cache')
+        .option('--force', 'Re-check every node, ignoring the freshness window')
+        .action(async (options) => {
+        const report = await runRefreshExternal(process.cwd(), options.force);
+        console.log(JSON.stringify(report, null, 2));
+    });
+}
+//# sourceMappingURL=freshness.js.map

package/dist/cli/commands/freshness.js.map

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

package/dist/cli/commands/helpers.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Check if NavGator data exists in the current directory or parent directories.
+ * Traverses upward like git does to find the project root.
+ * Returns a warning message if not found, or null if data exists.
+ */
+export declare function checkDataAvailability(): string | null;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/cli/commands/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/helpers.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,GAAG,IAAI,CAuBrD"}

package/dist/cli/commands/helpers.js

@@ -0,0 +1,30 @@
+import * as fs from 'fs';
+import * as path from 'path';
+/**
+ * Check if NavGator data exists in the current directory or parent directories.
+ * Traverses upward like git does to find the project root.
+ * Returns a warning message if not found, or null if data exists.
+ */
+export function checkDataAvailability() {
+    let dir = process.cwd();
+    const root = path.parse(dir).root;
+    // Walk up the directory tree looking for .navgator/
+    while (dir !== root) {
+        const navDir = path.join(dir, '.navgator', 'architecture');
+        if (fs.existsSync(navDir)) {
+            const indexPath = path.join(navDir, 'index.json');
+            if (!fs.existsSync(indexPath)) {
+                return `NavGator data incomplete in ${dir}. Run \`navgator scan\` to rebuild.`;
+            }
+            // Found it — if it's not in CWD, tell the user
+            if (dir !== process.cwd()) {
+                // Change CWD to the project root so commands work
+                process.chdir(dir);
+            }
+            return null;
+        }
+        dir = path.dirname(dir);
+    }
+    return `No NavGator project found.\nRun \`navgator scan\` in your project root, or \`navgator projects\` to find scanned projects.`;
+}
+//# sourceMappingURL=helpers.js.map

package/dist/cli/commands/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../../src/cli/commands/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAE7B;;;;GAIG;AACH,MAAM,UAAU,qBAAqB;IACnC,IAAI,GAAG,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IACxB,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;IAElC,oDAAoD;IACpD,OAAO,GAAG,KAAK,IAAI,EAAE,CAAC;QACpB,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,EAAE,cAAc,CAAC,CAAC;QAC3D,IAAI,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YAC1B,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;YAClD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;gBAC9B,OAAO,+BAA+B,GAAG,qCAAqC,CAAC;YACjF,CAAC;YACD,+CAA+C;YAC/C,IAAI,GAAG,KAAK,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC;gBAC1B,kDAAkD;gBAClD,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YACrB,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;QACD,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC1B,CAAC;IAED,OAAO,4HAA4H,CAAC;AACtI,CAAC"}

package/dist/cli/commands/impact.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function registerImpactCommand(program: Command): void;
+//# sourceMappingURL=impact.d.ts.map

package/dist/cli/commands/impact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"impact.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/impact.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AASpC,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAkL5D"}

package/dist/cli/commands/impact.js

@@ -0,0 +1,172 @@
+import { loadAllComponents, loadAllConnections, loadFileMap } from '../../storage.js';
+import { getConfig } from '../../config.js';
+import { computeImpact } from '../../impact.js';
+import { wrapInEnvelope } from '../../agent-output.js';
+import { resolveComponent, findCandidates } from '../../resolve.js';
+import { resolveFileConnections, formatFileImpact } from '../../file-resolve.js';
+import { checkDataAvailability } from './helpers.js';
+export function registerImpactCommand(program) {
+    program
+        .command('impact <component>')
+        .description('Show what\'s affected if you change a component')
+        .option('--json', 'Output as JSON')
+        .option('--agent', 'Output wrapped in agent envelope (implies --json)')
+        .action(async (componentName, options) => {
+        try {
+            const dataWarning = checkDataAvailability();
+            if (dataWarning) {
+                console.log(dataWarning);
+                return;
+            }
+            const config = getConfig();
+            const components = await loadAllComponents(config);
+            const connections = await loadAllConnections(config);
+            const fileMap = await loadFileMap(config);
+            // Resolve the component (supports name, file path, partial match)
+            const component = resolveComponent(componentName, components, fileMap);
+            if (!component) {
+                // Fall back to file-level import analysis
+                const { looksLikeFilePath } = await import('../../file-resolve.js');
+                if (looksLikeFilePath(componentName)) {
+                    const fc = resolveFileConnections(componentName, connections);
+                    if (fc) {
+                        if (options.agent) {
+                            console.log(wrapInEnvelope('impact', {
+                                file: fc.filePath,
+                                imported_by: fc.importedBy.length,
+                                imports: fc.imports.length,
+                                other_connections: fc.otherFrom.length + fc.otherTo.length,
+                                importers: fc.importedBy.map(c => ({
+                                    file: c.from.component_id.replace('FILE:', ''),
+                                    line: c.code_reference?.line_start,
+                                    symbol: c.code_reference?.symbol,
+                                })),
+                            }));
+                            return;
+                        }
+                        if (options.json) {
+                            console.log(JSON.stringify(fc, null, 2));
+                            return;
+                        }
+                        console.log(formatFileImpact(fc));
+                        return;
+                    }
+                }
+                console.log(`Component "${componentName}" not found.`);
+                const candidates = findCandidates(componentName, components);
+                if (candidates.length > 0) {
+                    console.log('\nDid you mean:');
+                    for (const name of candidates) {
+                        console.log(`  - ${name}`);
+                    }
+                }
+                else {
+                    console.log('\nAvailable components:');
+                    for (const c of components.slice(0, 10)) {
+                        console.log(`  - ${c.name} (${c.type})`);
+                    }
+                    if (components.length > 10) {
+                        console.log(`  ... and ${components.length - 10} more`);
+                    }
+                }
+                return;
+            }
+            // Compute impact with severity
+            const impact = computeImpact(component, components, connections);
+            // Also compute incoming/outgoing for display
+            const incoming = connections.filter((c) => c.to.component_id === component.component_id);
+            const outgoing = connections.filter((c) => c.from.component_id === component.component_id);
+            if (options.agent) {
+                console.log(wrapInEnvelope('impact', {
+                    component: { name: component.name, type: component.type, layer: component.role.layer },
+                    severity: impact.severity,
+                    summary: impact.summary,
+                    total_files_affected: impact.total_files_affected,
+                    affected: impact.affected.map((a) => ({
+                        name: a.component.name,
+                        type: a.component.type,
+                        impact_type: a.impact_type,
+                        change_required: a.change_required,
+                    })),
+                    incoming_count: incoming.length,
+                    outgoing_count: outgoing.length,
+                }));
+                return;
+            }
+            if (options.json) {
+                console.log(JSON.stringify({
+                    component,
+                    severity: impact.severity,
+                    summary: impact.summary,
+                    total_files_affected: impact.total_files_affected,
+                    affected: impact.affected.map((a) => ({
+                        name: a.component.name,
+                        type: a.component.type,
+                        impact_type: a.impact_type,
+                        change_required: a.change_required,
+                    })),
+                    incoming,
+                    outgoing,
+                }, null, 2));
+                return;
+            }
+            console.log(`NavGator - Impact Analysis: ${component.name}\n`);
+            console.log('========================================');
+            console.log(`Component: ${component.name}`);
+            console.log(`Type: ${component.type}`);
+            console.log(`Layer: ${component.role.layer}`);
+            console.log(`Purpose: ${component.role.purpose}`);
+            console.log(`Severity: ${impact.severity.toUpperCase()}`);
+            console.log(`Summary: ${impact.summary}`);
+            if (incoming.length > 0) {
+                console.log(`\nINCOMING CONNECTIONS (${incoming.length}):`);
+                console.log('These files/components USE this component:\n');
+                for (const conn of incoming) {
+                    const lineInfo = conn.code_reference.line_start ? `:${conn.code_reference.line_start}` : '';
+                    console.log(`  ${conn.code_reference.file}${lineInfo}`);
+                    if (conn.code_reference.symbol) {
+                        const symbolType = conn.code_reference.symbol_type ? ` (${conn.code_reference.symbol_type})` : '';
+                        console.log(`    Symbol: ${conn.code_reference.symbol}${symbolType}`);
+                    }
+                    if (conn.code_reference.code_snippet) {
+                        console.log(`    Code: ${conn.code_reference.code_snippet}`);
+                    }
+                    console.log('');
+                }
+            }
+            if (outgoing.length > 0) {
+                console.log(`\nOUTGOING CONNECTIONS (${outgoing.length}):`);
+                console.log('This component USES these:\n');
+                for (const conn of outgoing) {
+                    const target = components.find((c) => c.component_id === conn.to.component_id);
+                    console.log(`  → ${target?.name || conn.to.component_id}`);
+                    console.log(`    Type: ${conn.connection_type}`);
+                    console.log('');
+                }
+            }
+            // Show transitive impacts if any
+            const transitiveAffected = impact.affected.filter((a) => a.impact_type === 'transitive');
+            if (transitiveAffected.length > 0) {
+                console.log(`\nTRANSITIVE IMPACT (${transitiveAffected.length}):`);
+                for (const a of transitiveAffected) {
+                    console.log(`  ~ ${a.component.name} (${a.component.type})`);
+                    console.log(`    ${a.change_required}`);
+                }
+            }
+            if (incoming.length === 0 && outgoing.length === 0) {
+                console.log('\nNo connections found for this component.');
+            }
+            console.log('\n========================================');
+            console.log(`Files that may need changes if you modify ${component.name}:`);
+            const affectedFiles = new Set(incoming.map((c) => c.code_reference.file));
+            for (const file of affectedFiles) {
+                console.log(`  - ${file}`);
+            }
+        }
+        catch (error) {
+            console.error('Impact analysis failed:', error);
+            process.exit(1);
+        }
+    });
+}
+//# sourceMappingURL=impact.js.map

package/dist/cli/commands/impact.js.map

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

package/dist/cli/commands/lessons.d.ts

@@ -0,0 +1,6 @@
+/**
+ * NavGator `lessons` subcommand — local + global architectural lessons store.
+ */
+import { Command } from 'commander';
+export declare function registerLessonsCommand(program: Command): void;
+//# sourceMappingURL=lessons.d.ts.map

package/dist/cli/commands/lessons.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lessons.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/lessons.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA+GpC,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAkL7D"}

package/dist/cli/commands/lessons.js

@@ -0,0 +1,279 @@
+/**
+ * NavGator `lessons` subcommand — local + global architectural lessons store.
+ */
+import * as path from 'path';
+import { ensureGlobalLessonsFile, listLessons, searchLessons, findLessonById, promoteLesson, demoteLesson, } from '../../lessons-store.js';
+import { wrapInEnvelope } from '../../agent-output.js';
+// =============================================================================
+// HELPERS
+// =============================================================================
+function isAgentMode(options) {
+    return Boolean(options.agent) || process.env.NAVGATOR_AGENT === '1';
+}
+function wantsJson(options) {
+    return Boolean(options.json) || isAgentMode(options);
+}
+function emit(command, data, options) {
+    if (isAgentMode(options)) {
+        console.log(wrapInEnvelope(command, data));
+        return true;
+    }
+    if (options.json) {
+        console.log(JSON.stringify(data, null, 2));
+        return true;
+    }
+    return false;
+}
+function collect(value, previous = []) {
+    return previous.concat([value]);
+}
+function formatLessonSummary(l) {
+    const tags = l.applies_to;
+    const source = l.source_project;
+    const promotedMarker = l.promoted ? ' [promoted]' : '';
+    const sourceStr = source ? ` [from: ${source}]` : '';
+    const tagStr = tags && tags.length > 0 ? ` {${tags.join(', ')}}` : '';
+    const pat = l.pattern.length > 80 ? l.pattern.slice(0, 77) + '...' : l.pattern;
+    return `  ${l.id.padEnd(40)} ${l.severity.padEnd(9)} ${l.category.padEnd(24)} ${pat}${tagStr}${sourceStr}${promotedMarker}`;
+}
+function printTable(title, lessons) {
+    console.log(title);
+    console.log('─'.repeat(Math.min(title.length, 60)));
+    if (lessons.length === 0) {
+        console.log('  (none)');
+        return;
+    }
+    console.log(`  ${'ID'.padEnd(40)} ${'SEVERITY'.padEnd(9)} ${'CATEGORY'.padEnd(24)} PATTERN`);
+    for (const l of lessons)
+        console.log(formatLessonSummary(l));
+}
+function printLessonDetail(l) {
+    console.log(`ID:        ${l.id}`);
+    console.log(`Category:  ${l.category}`);
+    console.log(`Severity:  ${l.severity}`);
+    console.log(`Pattern:   ${l.pattern}`);
+    if (l.signature && l.signature.length > 0) {
+        console.log(`Signature: ${l.signature.join(' | ')}`);
+    }
+    const g = l;
+    if (g.source_project)
+        console.log(`Source:    ${g.source_project}`);
+    if (g.applies_to && g.applies_to.length > 0) {
+        console.log(`Tags:      ${g.applies_to.join(', ')}`);
+    }
+    if (g.promoted_at)
+        console.log(`Promoted:  ${g.promoted_at}`);
+    if (g.promoted_from)
+        console.log(`From:      ${g.promoted_from}`);
+    if (l.promoted)
+        console.log(`Promoted:  true (local)`);
+    if (l.context) {
+        console.log('Context:');
+        if (l.context.first_seen)
+            console.log(`  first_seen: ${l.context.first_seen}`);
+        if (l.context.last_seen)
+            console.log(`  last_seen:  ${l.context.last_seen}`);
+        if (typeof l.context.occurrences === 'number') {
+            console.log(`  occurrences: ${l.context.occurrences}`);
+        }
+        if (l.context.files_affected && l.context.files_affected.length > 0) {
+            console.log(`  files: ${l.context.files_affected.join(', ')}`);
+        }
+        if (l.context.resolution)
+            console.log(`  resolution: ${l.context.resolution}`);
+    }
+    if (l.example) {
+        console.log('Example:');
+        if (l.example.bad)
+            console.log(`  bad:  ${l.example.bad}`);
+        if (l.example.good)
+            console.log(`  good: ${l.example.good}`);
+        if (l.example.why)
+            console.log(`  why:  ${l.example.why}`);
+    }
+}
+// =============================================================================
+// COMMAND
+// =============================================================================
+export function registerLessonsCommand(program) {
+    const lessons = program
+        .command('lessons')
+        .description('Manage local and global architectural lessons');
+    // ---- list --------------------------------------------------------------
+    lessons
+        .command('list')
+        .description('List lessons (local by default)')
+        .option('--global', 'List the global lessons store')
+        .option('--all', 'List local + global lessons combined')
+        .option('--json', 'Output as JSON')
+        .option('--agent', 'Output wrapped in agent envelope (implies --json)')
+        .action((options) => {
+        try {
+            ensureGlobalLessonsFile();
+            const projectRoot = process.cwd();
+            let data = [];
+            if (options.all) {
+                const local = listLessons({ scope: 'local', projectRoot });
+                const global = listLessons({ scope: 'global' });
+                data = [...local, ...global];
+                if (!emit('lessons.list', { scope: 'all', lessons: data }, options)) {
+                    printTable(`Lessons (local: ${local.length}, global: ${global.length})`, data);
+                }
+                return;
+            }
+            if (options.global) {
+                const global = listLessons({ scope: 'global' });
+                data = global;
+                if (!emit('lessons.list', { scope: 'global', lessons: data }, options)) {
+                    printTable(`Global Lessons (${global.length})`, global);
+                }
+                return;
+            }
+            const local = listLessons({ scope: 'local', projectRoot });
+            data = local;
+            if (!emit('lessons.list', { scope: 'local', project: projectRoot, lessons: data }, options)) {
+                printTable(`Local Lessons — ${path.basename(projectRoot)} (${local.length})`, local);
+            }
+        }
+        catch (err) {
+            console.error('lessons list failed:', err instanceof Error ? err.message : err);
+            process.exit(1);
+        }
+    });
+    // ---- show --------------------------------------------------------------
+    lessons
+        .command('show <id>')
+        .description('Show full detail for a single lesson')
+        .option('--scope <scope>', 'Scope to search (local | global | all)', 'all')
+        .option('--json', 'Output as JSON')
+        .option('--agent', 'Output wrapped in agent envelope (implies --json)')
+        .action((id, options) => {
+        try {
+            ensureGlobalLessonsFile();
+            const projectRoot = process.cwd();
+            const scope = (options.scope || 'all');
+            let found = null;
+            if (scope === 'local' || scope === 'all') {
+                found = findLessonById(id, { scope: 'local', projectRoot });
+            }
+            if (!found && (scope === 'global' || scope === 'all')) {
+                found = findLessonById(id, { scope: 'global' });
+            }
+            if (!found) {
+                if (wantsJson(options)) {
+                    emit('lessons.show', { id, found: false }, options);
+                }
+                else {
+                    console.log(`No lesson with id "${id}" in scope=${scope}`);
+                }
+                process.exitCode = 1;
+                return;
+            }
+            if (!emit('lessons.show', found, options)) {
+                printLessonDetail(found);
+            }
+        }
+        catch (err) {
+            console.error('lessons show failed:', err instanceof Error ? err.message : err);
+            process.exit(1);
+        }
+    });
+    // ---- search ------------------------------------------------------------
+    lessons
+        .command('search <query>')
+        .description('Search lessons by regex against pattern, signature, examples, and resolution')
+        .option('--scope <scope>', 'Scope (local | global | all)', 'all')
+        .option('--category <cat>', 'Filter by category')
+        .option('--severity <sev>', 'Filter by severity (critical | important | minor)')
+        .option('--tag <tag>', 'Filter by applies_to tag (repeatable, global only)', collect, [])
+        .option('--json', 'Output as JSON')
+        .option('--agent', 'Output wrapped in agent envelope (implies --json)')
+        .action((query, options) => {
+        try {
+            ensureGlobalLessonsFile();
+            const projectRoot = process.cwd();
+            const scope = (options.scope || 'all');
+            const results = searchLessons(query, {
+                scope,
+                projectRoot,
+                category: options.category,
+                severity: options.severity,
+                tags: options.tag && options.tag.length > 0 ? options.tag : undefined,
+            });
+            if (!emit('lessons.search', { query, scope, results }, options)) {
+                printTable(`Search: /${query}/ in ${scope} (${results.length})`, results);
+            }
+        }
+        catch (err) {
+            console.error('lessons search failed:', err instanceof Error ? err.message : err);
+            process.exit(1);
+        }
+    });
+    // ---- promote -----------------------------------------------------------
+    lessons
+        .command('promote <id>')
+        .description('Promote a local lesson to the global store (copy-then-mark)')
+        .option('--tag <tag>', 'applies_to tag (repeatable)', collect, [])
+        .option('--project-name <name>', 'Override auto-detected project name')
+        .option('--json', 'Output as JSON')
+        .option('--agent', 'Output wrapped in agent envelope (implies --json)')
+        .action((id, options) => {
+        try {
+            ensureGlobalLessonsFile();
+            const projectRoot = process.cwd();
+            const result = promoteLesson(id, projectRoot, {
+                applies_to: options.tag && options.tag.length > 0 ? options.tag : undefined,
+                project_name: options.projectName,
+            });
+            if (!emit('lessons.promote', result, options)) {
+                if (result.promoted) {
+                    console.log(`Promoted ${id} to global store.`);
+                    if (result.globalLesson?.applies_to?.length) {
+                        console.log(`  Tags: ${result.globalLesson.applies_to.join(', ')}`);
+                    }
+                }
+                else {
+                    console.log(`Not promoted: ${result.reason}`);
+                    process.exitCode = 1;
+                }
+            }
+            else if (!result.promoted) {
+                process.exitCode = 1;
+            }
+        }
+        catch (err) {
+            console.error('lessons promote failed:', err instanceof Error ? err.message : err);
+            process.exit(1);
+        }
+    });
+    // ---- demote ------------------------------------------------------------
+    lessons
+        .command('demote <id>')
+        .description('Remove a lesson from the global store (idempotent; local is untouched)')
+        .option('--keep-local', 'No-op flag — kept for symmetry; local is always preserved', true)
+        .option('--json', 'Output as JSON')
+        .option('--agent', 'Output wrapped in agent envelope (implies --json)')
+        .action((id, options) => {
+        try {
+            ensureGlobalLessonsFile();
+            const result = demoteLesson(id);
+            if (!emit('lessons.demote', result, options)) {
+                if (result.demoted) {
+                    console.log(`Demoted ${id} from global store.`);
+                }
+                else {
+                    console.log(`Not demoted: ${result.reason}`);
+                    process.exitCode = 1;
+                }
+            }
+            else if (!result.demoted) {
+                process.exitCode = 1;
+            }
+        }
+        catch (err) {
+            console.error('lessons demote failed:', err instanceof Error ? err.message : err);
+            process.exit(1);
+        }
+    });
+}
+//# sourceMappingURL=lessons.js.map