cgraphx 1.1.0

package/dist/installer/targets/types.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Agent target abstraction for the installer.
+ *
+ * Each MCP-capable agent (Claude Code, Cursor, Codex CLI, opencode, ...)
+ * implements this interface so the installer orchestrator can write the
+ * right MCP-server config + instructions file + permissions for that
+ * agent without baking client-specific paths into core code. Adding a
+ * new agent = one new file in `targets/` + one entry in `registry.ts`.
+ *
+ * Closes the Claude-locked installer issue (upstream #137). The
+ * runtime MCP server is already agent-agnostic; this brings the
+ * installer to the same surface.
+ */
+export type Location = 'global' | 'local';
+/**
+ * Stable string id used in the `--target` CLI flag and the registry
+ * lookup. New targets add a value here when they're added to the
+ * registry. Keep these short and lowercase.
+ */
+export type TargetId = 'claude' | 'cursor' | 'codex' | 'opencode' | 'hermes' | 'gemini' | 'antigravity' | 'kiro';
+/**
+ * Result of `target.detect(location)`.
+ *
+ * `installed` is a best-effort heuristic that the agent's CLI / app /
+ * config dir is present on this system — used to default the
+ * multiselect prompt to "what's actually here." False positives are
+ * acceptable (we still write); false negatives just mean the user
+ * has to opt in manually.
+ *
+ * `alreadyConfigured` reports whether CodeGraph has already been
+ * wired into this target at this location — drives the
+ * "Updated"-vs-"Added" log line and lets `--check` exit 0/1.
+ */
+export interface DetectionResult {
+    installed: boolean;
+    alreadyConfigured: boolean;
+    /** Path inspected; surfaced in diagnostic / dry-run output. */
+    configPath?: string;
+}
+/**
+ * What `target.install(location)` actually changed on disk. The
+ * orchestrator renders one log line per file using `action`.
+ *
+ * `unchanged` means we touched the file but its contents were already
+ * what we'd write — used for byte-identical idempotent re-runs.
+ */
+export interface WriteResult {
+    files: Array<{
+        path: string;
+        action: 'created' | 'updated' | 'unchanged' | 'removed' | 'not-found' | 'kept' | 'overwritten';
+    }>;
+    /**
+     * Optional one-line notes the orchestrator surfaces verbatim — e.g.
+     * "Restart Cursor to apply." Keep these short; multi-line goes in
+     * the README.
+     */
+    notes?: string[];
+}
+export interface InstallOptions {
+    /**
+     * Whether to write the agent's permissions / auto-allow surface
+     * (Claude `settings.json`, others where applicable). When the
+     * target has no permissions concept this option is a no-op.
+     */
+    autoAllow: boolean;
+    /**
+     * Front-load prompt hook (Claude `UserPromptSubmit`) that injects
+     * codegraph_explore context for structural prompts. `true` installs it,
+     * `false` removes any prior install (so opt-out round-trips), `undefined`
+     * leaves it untouched. Targets without a prompt-hook concept ignore it.
+     */
+    promptHook?: boolean;
+}
+export interface AgentTarget {
+    /** Stable id; matches the `TargetId` union. */
+    readonly id: TargetId;
+    /** Human-readable name shown in clack prompts and log lines. */
+    readonly displayName: string;
+    /** Optional URL for "where do I learn more about this agent." */
+    readonly docsUrl?: string;
+    /**
+     * Whether this target supports the given install location.
+     *
+     * Some agents (Codex CLI as of 2026-05) have no project-local
+     * config concept — only a single `~/.codex/` dir. Returning false
+     * for an unsupported (target, location) pair lets the orchestrator
+     * skip cleanly with a clear message.
+     */
+    supportsLocation(loc: Location): boolean;
+    detect(loc: Location): DetectionResult;
+    install(loc: Location, opts: InstallOptions): WriteResult;
+    /**
+     * Inverse of install. Removes only what install would have written;
+     * preserves sibling MCP servers, sibling permissions, and unrelated
+     * markdown sections. Must be safe to call when nothing was ever
+     * installed (returns `not-found` actions).
+     */
+    uninstall(loc: Location): WriteResult;
+    /**
+     * Print the MCP-server snippet a user would paste manually for this
+     * target. Used by `cgraphx install --print-config <id>` and by
+     * the README. Must NOT touch the filesystem.
+     */
+    printConfig(loc: Location): string;
+    /** Filesystem paths this target would write to at this location. */
+    describePaths(loc: Location): string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/installer/targets/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/installer/targets/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE1C;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,aAAa,GAAG,MAAM,CAAC;AAEjH;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,OAAO,CAAC;IACnB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,KAAK,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,SAAS,GAAG,WAAW,GAAG,MAAM,GAAG,aAAa,CAAC;KAChG,CAAC,CAAC;IACH;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,SAAS,EAAE,OAAO,CAAC;IACnB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC;IACtB,gEAAgE;IAChE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,iEAAiE;IACjE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;;OAOG;IACH,gBAAgB,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC;IACzC,MAAM,CAAC,GAAG,EAAE,QAAQ,GAAG,eAAe,CAAC;IACvC,OAAO,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,cAAc,GAAG,WAAW,CAAC;IAC1D;;;;;OAKG;IACH,SAAS,CAAC,GAAG,EAAE,QAAQ,GAAG,WAAW,CAAC;IACtC;;;;OAIG;IACH,WAAW,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM,CAAC;IACnC,oEAAoE;IACpE,aAAa,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM,EAAE,CAAC;CACxC"}

package/dist/installer/targets/types.js

@@ -0,0 +1,16 @@
+"use strict";
+/**
+ * Agent target abstraction for the installer.
+ *
+ * Each MCP-capable agent (Claude Code, Cursor, Codex CLI, opencode, ...)
+ * implements this interface so the installer orchestrator can write the
+ * right MCP-server config + instructions file + permissions for that
+ * agent without baking client-specific paths into core code. Adding a
+ * new agent = one new file in `targets/` + one entry in `registry.ts`.
+ *
+ * Closes the Claude-locked installer issue (upstream #137). The
+ * runtime MCP server is already agent-agnostic; this brings the
+ * installer to the same surface.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/installer/targets/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/installer/targets/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG"}

package/dist/markdown/cli.d.ts

@@ -0,0 +1,16 @@
+/**
+ * CLI wiring for the markdown knowledge base.
+ *
+ * Exposes a single `registerDocsCommands(program)` entry point that the main
+ * CLI (`src/bin/codegraph.ts`) calls once. All docs subcommands live under
+ * `cgraphx docs <subcommand>` and are implemented in this file.
+ */
+import type { Command } from 'commander';
+/**
+ * Attach the `docs` command group to a commander program.
+ *
+ * Called once from `src/bin/codegraph.ts`. Kept as a function (not a top-level
+ * side effect) so the main CLI controls when registration happens.
+ */
+export declare function registerDocsCommands(program: Command): void;
+//# sourceMappingURL=cli.d.ts.map

package/dist/markdown/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/markdown/cli.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAsBzC;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAwT3D"}

package/dist/markdown/cli.js

@@ -0,0 +1,533 @@
+"use strict";
+/**
+ * CLI wiring for the markdown knowledge base.
+ *
+ * Exposes a single `registerDocsCommands(program)` entry point that the main
+ * CLI (`src/bin/codegraph.ts`) calls once. All docs subcommands live under
+ * `cgraphx docs <subcommand>` and are implemented in this file.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerDocsCommands = registerDocsCommands;
+const node_path_1 = __importDefault(require("node:path"));
+const errors_1 = require("./errors");
+const indexer_1 = require("./indexer");
+const query_1 = require("./query");
+const schema_bootstrap_1 = require("./schema-bootstrap");
+/**
+ * Attach the `docs` command group to a commander program.
+ *
+ * Called once from `src/bin/codegraph.ts`. Kept as a function (not a top-level
+ * side effect) so the main CLI controls when registration happens.
+ */
+function registerDocsCommands(program) {
+    const docs = program
+        .command('docs')
+        .description('Markdown knowledge base — index and query docs/knowledge/');
+    // -- docs index ----------------------------------------------------------
+    docs
+        .command('index [project-path]')
+        .description('Scan docs/knowledge/ and rebuild the markdown knowledge base (cover-the-table)')
+        .option('--json', 'Output machine-readable JSON instead of progress text')
+        .action(async (pathArg, options) => {
+        const projectRoot = pathArg ? node_path_1.default.resolve(pathArg) : process.cwd();
+        if (options.json) {
+            const report = await (0, indexer_1.indexMarkdownKnowledgeBase)(projectRoot);
+            process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+            if (report.error)
+                process.exitCode = 1;
+            return;
+        }
+        const report = await (0, indexer_1.indexMarkdownKnowledgeBase)(projectRoot, {
+            onProgress: (msg) => process.stdout.write(`${msg}\n`),
+        });
+        if (report.error) {
+            process.stderr.write(`Error: ${report.error}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        printIndexReport(report);
+        if (report.skippedFiles > 0)
+            process.exitCode = 2; // partial: success but skips
+    });
+    // -- docs concepts / domains / tags -------------------------------------
+    // concepts has its own registration (extra --sort / --limit options); the
+    // remaining vocabulary commands (domains, tags) still go through
+    // registerListCommand below.
+    docs
+        .command('concepts [project-path]')
+        .description('List all concepts (with document count and domains)')
+        .option('--sort <mode>', 'Sort mode: doc-count (default) | name', 'doc-count')
+        .option('--limit <n>', 'Cap results (default: no limit)', (v) => {
+        // 严格 regex 校验:只接受纯数字字符串。commander 把 parser 抛出的错误
+        // 当作无效参数处理(报错 + exit 1),所以不需要在 action 里再 try/catch。
+        if (!/^\d+$/.test(v)) {
+            throw new TypeError(`--limit expects a non-negative integer, got '${v}'`);
+        }
+        return parseInt(v, 10);
+    })
+        .option('--json', 'Output JSON')
+        .action(async (pathArg, options) => {
+        const projectRoot = pathArg ? node_path_1.default.resolve(pathArg) : process.cwd();
+        try {
+            const sort = (options.sort ?? 'doc-count');
+            const limit = options.limit; // may be undefined → no limit
+            const rows = withQuery(projectRoot, q => q.listConcepts({ sort, limit }));
+            if (options.json) {
+                process.stdout.write(JSON.stringify(rows, null, 2) + '\n');
+            }
+            else {
+                process.stdout.write(formatConcepts(rows));
+            }
+        }
+        catch (err) {
+            handleQueryError(err);
+        }
+    });
+    registerListCommand(docs, 'domains', 'List all domains (with document count)', q => q.listDomains(), formatDomains);
+    registerListCommand(docs, 'tags', 'List all tags (with document count)', q => q.listTags(), formatTags);
+    // -- docs find -----------------------------------------------------------
+    docs
+        .command('find [project-path]')
+        .description('Find documents by concept/domain/tag/status/type/keyword')
+        .option('--concept <name>', 'Filter by concept (case-sensitive)')
+        .option('--domain <name>', 'Filter by domain')
+        .option('--tag <name>', 'Filter by tag')
+        .option('--status <status>', 'Filter by status (draft/active/superseded/deprecated)')
+        .option('--type <type>', 'Filter by document_type (decision/architecture/guide/...)')
+        .option('--q <keyword>', 'Full-text keyword (matches title + summary)')
+        .option('--limit <n>', 'Max results (default 20, max 100)', '20')
+        .option('--json', 'Output JSON')
+        .action(async (pathArg, options) => {
+        const projectRoot = pathArg ? node_path_1.default.resolve(pathArg) : process.cwd();
+        const filter = {
+            concept: options.concept,
+            domain: options.domain,
+            tag: options.tag,
+            status: options.status,
+            documentType: options.type,
+            q: options.q,
+            limit: options.limit ? Number(options.limit) : undefined,
+        };
+        try {
+            const results = withQuery(projectRoot, q => q.find(filter));
+            if (options.json) {
+                process.stdout.write(JSON.stringify(results, null, 2) + '\n');
+            }
+            else {
+                process.stdout.write(formatFindResults(results));
+            }
+        }
+        catch (err) {
+            handleQueryError(err);
+        }
+    });
+    // -- docs refs -----------------------------------------------------------
+    docs
+        .command('refs <doc-id-or-path> [project-path]')
+        .description('Show outgoing + incoming references for a document')
+        .option('--json', 'Output JSON')
+        .action(async (docIdOrPath, pathArg, options) => {
+        const projectRoot = pathArg ? node_path_1.default.resolve(pathArg) : process.cwd();
+        try {
+            const docRef = normalizeDocRef(docIdOrPath, projectRoot);
+            const view = withQuery(projectRoot, q => q.getReferences(docRef));
+            if (options.json) {
+                process.stdout.write(JSON.stringify(view, null, 2) + '\n');
+            }
+            else {
+                process.stdout.write(formatReferences(view));
+            }
+        }
+        catch (err) {
+            handleQueryError(err);
+        }
+    });
+    // -- docs dedup ---------------------------------------------------------
+    docs
+        .command('dedup [project-path]')
+        .description('Check concept names against the indexed vocabulary (exact + alias match)')
+        .requiredOption('--names <names>', 'Comma-separated candidate names')
+        .option('--json', 'Output JSON')
+        .action(async (pathArg, options) => {
+        const projectRoot = pathArg ? node_path_1.default.resolve(pathArg) : process.cwd();
+        const names = options.names
+            .split(',')
+            .map(s => s.trim())
+            .filter(s => s.length > 0);
+        try {
+            const resp = withQuery(projectRoot, q => q.checkConceptDedup(names));
+            if (options.json) {
+                process.stdout.write(JSON.stringify(resp, null, 2) + '\n');
+            }
+            else {
+                process.stdout.write(formatDedupResponse(resp));
+            }
+        }
+        catch (err) {
+            handleQueryError(err);
+        }
+    });
+    // -- docs seen-names -----------------------------------------------------
+    docs
+        .command('seen-names [project-path]')
+        .description('Layer 1 entry-point name dedup — persist + check which names were already explored')
+        .option('--add <names>', 'Add comma-separated names (idempotent)')
+        .option('--check <names>', 'Check whether names are already seen')
+        .option('--list', 'List all seen names (debug)', false)
+        .option('--clear', 'Clear all seen names for this project', false)
+        .option('--json', 'Output JSON')
+        .action(async (pathArg, options) => {
+        const projectRoot = pathArg ? node_path_1.default.resolve(pathArg) : process.cwd();
+        // Mutually exclusive: exactly one of --add / --check / --list / --clear.
+        const modes = [];
+        if (options.add !== undefined)
+            modes.push('add');
+        if (options.check !== undefined)
+            modes.push('check');
+        if (options.list === true)
+            modes.push('list');
+        if (options.clear === true)
+            modes.push('clear');
+        if (modes.length !== 1) {
+            process.stderr.write('Error: exactly one of --add / --check / --list / --clear is required\n');
+            process.exitCode = 1;
+            return;
+        }
+        // --add / --check need a non-empty names string.
+        const mode = modes[0];
+        if (mode === 'add' || mode === 'check') {
+            const raw = options[mode];
+            if (!raw || raw.trim().length === 0) {
+                process.stderr.write(`Error: --${mode} requires at least one name\n`);
+                process.exitCode = 1;
+                return;
+            }
+        }
+        try {
+            const result = withQuery(projectRoot, q => {
+                if (mode === 'add') {
+                    return q.addSeenNames(parseNames(options.add));
+                }
+                if (mode === 'check') {
+                    const names = parseNames(options.check);
+                    return checkInBatches(q, names);
+                }
+                if (mode === 'list')
+                    return q.listSeenNames();
+                return q.clearSeenNames(); // mode === 'clear'
+            });
+            if (options.json) {
+                process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+            }
+            else {
+                process.stdout.write(formatSeenNamesResult(result, mode));
+            }
+        }
+        catch (err) {
+            handleQueryError(err);
+        }
+    });
+    // -- docs show -----------------------------------------------------------
+    docs
+        .command('show <doc-id-or-path> [project-path]')
+        .description('Show metadata + summary for a document (does not print the full body)')
+        .option('--json', 'Output JSON')
+        .action(async (docIdOrPath, pathArg, options) => {
+        const projectRoot = pathArg ? node_path_1.default.resolve(pathArg) : process.cwd();
+        try {
+            const docRef = normalizeDocRef(docIdOrPath, projectRoot);
+            const detail = withQuery(projectRoot, q => q.getDocumentDetail(docRef));
+            if (detail === null) {
+                process.stderr.write(`Document not found: ${docIdOrPath}\n`);
+                process.exitCode = 1;
+                return;
+            }
+            if (options.json) {
+                process.stdout.write(JSON.stringify(detail, null, 2) + '\n');
+            }
+            else {
+                process.stdout.write(formatDetail(detail));
+            }
+        }
+        catch (err) {
+            handleQueryError(err);
+        }
+    });
+}
+// ----- helpers -----------------------------------------------------------
+/**
+ * Open the DB, ensure markdown schema, run a query, close.
+ *
+ * Single connection per command — matches codegraph's main CLI pattern.
+ */
+function withQuery(projectRoot, fn) {
+    const connection = (0, schema_bootstrap_1.openMarkdownDb)(projectRoot);
+    try {
+        return fn(new query_1.MarkdownQuery(connection.getDb()));
+    }
+    finally {
+        connection.close();
+    }
+}
+/**
+ * Normalize a "doc-id-or-path" argument. Accepts:
+ *   - 64-hex document ID (returned unchanged)
+ *   - Absolute path under projectRoot (converted to project-relative POSIX)
+ *   - Project-relative path (returned unchanged, backslashes → slashes)
+ */
+function normalizeDocRef(input, projectRoot) {
+    if (/^[a-f0-9]{64}$/.test(input))
+        return input;
+    const normalized = input.split('\\').join('/');
+    if (node_path_1.default.isAbsolute(input)) {
+        const rel = node_path_1.default.relative(projectRoot, input).split(node_path_1.default.sep).join('/');
+        return rel || normalized;
+    }
+    return normalized;
+}
+function registerListCommand(parent, name, description, run, format) {
+    parent
+        .command(`${name} [project-path]`)
+        .description(description)
+        .option('--json', 'Output JSON')
+        .action(async (pathArg, options) => {
+        const projectRoot = pathArg ? node_path_1.default.resolve(pathArg) : process.cwd();
+        try {
+            const rows = withQuery(projectRoot, run);
+            if (options.json) {
+                process.stdout.write(JSON.stringify(rows, null, 2) + '\n');
+            }
+            else {
+                process.stdout.write(format(rows));
+            }
+        }
+        catch (err) {
+            handleQueryError(err);
+        }
+    });
+}
+/** Friendly handling for the two expected error types. */
+function handleQueryError(err) {
+    if (err instanceof errors_1.ProjectNotInitializedError) {
+        process.stderr.write(`${err.message}\nRun \`cgraphx init\` in ${err.projectPath} first.\n`);
+        process.exitCode = 1;
+        return;
+    }
+    if (err instanceof errors_1.DocumentNotFoundError) {
+        process.stderr.write(`Document not found: ${err.queriedIdOrPath}\n` +
+            `Use \`cgraphx docs find\` to list valid documents.\n`);
+        process.exitCode = 1;
+        return;
+    }
+    process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exitCode = 1;
+}
+/** Split a `--add`/`--check` comma-separated names string. */
+function parseNames(input) {
+    return input
+        .split(',')
+        .map(s => s.trim())
+        .filter(s => s.length > 0);
+}
+/**
+ * Batch `checkSeenNames` so a single IN-clause stays manageable.
+ * The query layer takes a full array (per spec §3.3); batching lives here.
+ */
+function checkInBatches(q, names, batchSize = 500) {
+    const results = [];
+    for (let i = 0; i < names.length; i += batchSize) {
+        const slice = names.slice(i, i + batchSize);
+        const resp = q.checkSeenNames(slice);
+        results.push(...resp.results);
+    }
+    return { results };
+}
+// ----- formatters --------------------------------------------------------
+function printIndexReport(report) {
+    process.stdout.write('\n');
+    process.stdout.write(`Indexed ${report.indexedDocuments} document(s)\n`);
+    if (report.skippedFiles > 0) {
+        process.stdout.write(`Skipped ${report.skippedFiles} file(s):\n`);
+        for (const [reason, count] of Object.entries(report.skipBreakdown)) {
+            if (count > 0 && reason !== 'dangling_reference') {
+                process.stdout.write(`  - ${reason}: ${count}\n`);
+            }
+        }
+    }
+    process.stdout.write('\nStatistics:\n');
+    process.stdout.write(`  Documents:  ${report.indexedDocuments}\n`);
+    process.stdout.write(`  Concepts:   ${report.conceptsCreated}\n`);
+    process.stdout.write(`  Domains:    ${report.domainsCreated}\n`);
+    process.stdout.write(`  Tags:       ${report.tagsCreated}\n`);
+    process.stdout.write(`  References: ${report.referencesCreated}` +
+        (report.danglingReferences > 0
+            ? ` (${report.danglingReferences} dangling)\n`
+            : '\n'));
+    process.stdout.write(`\nDone in ${(report.durationMs / 1000).toFixed(1)}s\n`);
+}
+function formatConcepts(rows) {
+    if (rows.length === 0)
+        return 'No concepts indexed. Run `cgraphx docs index` first.\n';
+    const out = ['NAME\tDOCS\tDOMAINS'];
+    for (const r of rows) {
+        out.push(`${r.name}\t${r.documentCount}\t${r.domains.join(', ') || '-'}`);
+    }
+    out.push('');
+    out.push(`Total: ${rows.length} concept(s)`);
+    return out.join('\n') + '\n';
+}
+function formatDomains(rows) {
+    if (rows.length === 0)
+        return 'No domains indexed.\n';
+    const out = ['NAME\tDOCS'];
+    for (const r of rows)
+        out.push(`${r.name}\t${r.documentCount}`);
+    out.push('');
+    out.push(`Total: ${rows.length} domain(s)`);
+    return out.join('\n') + '\n';
+}
+function formatTags(rows) {
+    if (rows.length === 0)
+        return 'No tags indexed.\n';
+    const out = ['NAME\tDOCS'];
+    for (const r of rows)
+        out.push(`${r.name}\t${r.documentCount}`);
+    out.push('');
+    out.push(`Total: ${rows.length} tag(s)`);
+    return out.join('\n') + '\n';
+}
+function formatFindResults(rows) {
+    if (rows.length === 0)
+        return 'No matching documents.\n';
+    const out = ['TITLE\tTYPE\tSTATUS\tUPDATED\tPATH'];
+    for (const r of rows) {
+        out.push(`${r.title}\t${r.documentType}\t${r.status}\t${r.updatedAt ?? '-'}\t${r.path}`);
+    }
+    out.push('');
+    out.push(`Showing ${rows.length} document(s)`);
+    return out.join('\n') + '\n';
+}
+function formatReferences(view) {
+    const out = [];
+    out.push(`Document: ${view.documentTitle}`);
+    out.push(`Path:     ${view.documentPath}`);
+    out.push('');
+    out.push(`Outgoing references (${view.outgoing.length}):`);
+    if (view.outgoing.length === 0) {
+        out.push('  (none)');
+    }
+    else {
+        for (const t of view.outgoing) {
+            out.push(`  → ${t.title}  [${t.path}]`);
+        }
+    }
+    out.push('');
+    out.push(`Incoming references (${view.incoming.length}):`);
+    if (view.incoming.length === 0) {
+        out.push('  (none)');
+    }
+    else {
+        for (const t of view.incoming) {
+            out.push(`  ← ${t.title}  [${t.path}]`);
+        }
+    }
+    return out.join('\n') + '\n';
+}
+function formatDetail(d) {
+    const out = [];
+    out.push(`# ${d.title}`);
+    out.push('');
+    out.push('| Field | Value |');
+    out.push('|---|---|');
+    out.push(`| type | ${d.documentType} |`);
+    out.push(`| status | ${d.status} |`);
+    out.push(`| source | ${d.sourceType} |`);
+    out.push(`| updated | ${d.updatedAt ?? '-'} |`);
+    out.push(`| created | ${d.createdAt ?? '-'} |`);
+    out.push(`| owners | ${d.owners.join(', ') || '-'} |`);
+    out.push(`| aliases | ${d.aliases.join(', ') || '-'} |`);
+    out.push(`| path | ${d.path} |`);
+    out.push('');
+    out.push(`**Concepts:** ${d.concepts.join(', ') || '-'}`);
+    out.push(`**Domains:** ${d.domains.join(', ') || '-'}`);
+    out.push(`**Tags:** ${d.tags.join(', ') || '-'}`);
+    out.push('');
+    out.push('## Summary');
+    out.push('');
+    out.push(d.summary || '(no summary)');
+    out.push('');
+    out.push('---');
+    out.push('Read the full document at the path above for sections beyond Summary.');
+    return out.join('\n') + '\n';
+}
+function formatDedupResponse(resp) {
+    if (resp.results.length === 0) {
+        return 'No candidates to check.\n';
+    }
+    const out = ['NAME\tSTATUS\tMATCHED_VIA\tMATCHED_TO'];
+    for (const r of resp.results) {
+        const status = r.is_duplicate ? 'DUPLICATE' : 'NEW';
+        const matchedTo = r.matched_concept ?? '-';
+        const via = r.matched_via ?? '-';
+        out.push(`${r.name}\t${status}\t${via}\t${matchedTo}`);
+    }
+    if (resp.warnings && resp.warnings.length > 0) {
+        out.push('');
+        out.push('Warnings:');
+        for (const w of resp.warnings) {
+            out.push(`  - ${w}`);
+        }
+    }
+    return out.join('\n') + '\n';
+}
+/**
+ * Human-readable formatter for the 4 seen-names modes.
+ *
+ * Union input is safe because each branch only reads fields its mode produced.
+ * `--json` bypasses this entirely (raw payload printed in action above).
+ */
+function formatSeenNamesResult(result, mode) {
+    if (mode === 'add') {
+        const r = result;
+        const out = [];
+        out.push(`Added ${r.added.length} name(s):`);
+        for (const n of r.added)
+            out.push(`  - ${n}`);
+        if (r.skipped_already_present.length > 0) {
+            out.push(`Skipped ${r.skipped_already_present.length} (already present):`);
+            for (const n of r.skipped_already_present)
+                out.push(`  - ${n}`);
+        }
+        out.push(`Total seen: ${r.total_seen}`);
+        return out.join('\n') + '\n';
+    }
+    if (mode === 'check') {
+        const r = result;
+        if (r.results.length === 0)
+            return 'No names to check.\n';
+        const out = ['NAME\tSTATUS'];
+        for (const item of r.results) {
+            out.push(`${item.name}\t${item.is_seen ? 'SEEN' : 'NEW'}`);
+        }
+        return out.join('\n') + '\n';
+    }
+    if (mode === 'list') {
+        const r = result;
+        if (r.names.length === 0)
+            return 'No seen names yet.\n';
+        const out = ['ORIGINAL\tNORMALIZED\tADDED_AT'];
+        for (const e of r.names) {
+            out.push(`${e.original}\t${e.normalized}\t${new Date(e.added_at).toISOString()}`);
+        }
+        out.push('');
+        out.push(`Total: ${r.total}`);
+        return out.join('\n') + '\n';
+    }
+    // mode === 'clear'
+    const r = result;
+    return `Removed ${r.removed} name(s).\n`;
+}
+//# sourceMappingURL=cli.js.map