cgraphx 2.0.1 → 2.0.3

package/dist/core/code/engine/cli/cli-message.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cliInfo = cliInfo;
+exports.cliInfoKey = cliInfoKey;
+exports.cliWarn = cliWarn;
+exports.cliWarnKey = cliWarnKey;
+exports.cliError = cliError;
+exports.cliErrorKey = cliErrorKey;
+/**
+ * CLI message helpers — for user-facing banners, error guidance, and
+ * recovery hints emitted by `gitnexus` subcommands.
+ *
+ * These functions write **plain text** directly to `process.stderr` AND
+ * tee a structured pino record through the singleton `logger`. Plain text
+ * preserves the human-readable contract for users running `gitnexus`
+ * interactively, redirecting to a file, or piping to `cat`/`grep`. The
+ * structured tee keeps log aggregators happy.
+ *
+ * **Use these for:**
+ *   - User-facing banners ("Server listening on http://...:N")
+ *   - Validation errors ("--worker-timeout must be at least 1 second")
+ *   - Recovery hints ("Suggestions: 1. Clear the npm cache, 2. ...")
+ *   - One-line user notices ("No indexed repositories found.")
+ *
+ * **Do NOT use these for:**
+ *   - Internal diagnostics (worker progress, retry counts, telemetry)
+ *     — use `logger.info`/`warn`/`error` directly. Internal logs only
+ *     need structured fields, not double-output to stderr.
+ *   - High-volume hot paths — every `cliMessage` call writes twice (raw
+ *     + structured). Acceptable for user-facing messages, wasteful for
+ *     ingestion pipeline events.
+ *
+ * Design note: stderr is the right channel even for non-error messages
+ * because GitNexus CLI tools (`context`, `cypher`, `impact`) emit JSON
+ * data on stdout for piping (`cgraph cypher | jq`). User banners on
+ * stdout would corrupt that pipeline.
+ */
+const logger_js_1 = require("../core/logger.js");
+const index_js_1 = require("./i18n/index.js");
+function writeStderr(msg) {
+    // Direct write — bypassing `console.*` so it cannot be intercepted by
+    // progress-bar redirection (see `cli/analyze.ts:barLog`) or other
+    // routing. The structured tee below still goes through the logger so
+    // log aggregation works either way.
+    process.stderr.write(msg.endsWith('\n') ? msg : msg + '\n');
+}
+/**
+ * User-facing informational message. Use for banners, listening URLs,
+ * and any message the user expects to read in plain text.
+ */
+function cliInfo(msg, fields) {
+    writeStderr(msg);
+    logger_js_1.logger.info(fields ?? {}, msg);
+}
+/**
+ * Key-based informational message. Keeps the legacy string API intact while
+ * allowing commands to opt into localized user-facing stderr output.
+ */
+function cliInfoKey(key, vars, fields) {
+    cliInfo((0, index_js_1.t)(key, vars), fields);
+}
+/**
+ * User-facing warning. Operator-actionable but non-fatal — `cliWarn`
+ * indicates the command can still proceed in some form.
+ */
+function cliWarn(msg, fields) {
+    writeStderr(msg);
+    logger_js_1.logger.warn(fields ?? {}, msg);
+}
+function cliWarnKey(key, vars, fields) {
+    cliWarn((0, index_js_1.t)(key, vars), fields);
+}
+/**
+ * User-facing error. Indicates the command cannot proceed; usually
+ * paired with a non-zero exit code at the call site.
+ */
+function cliError(msg, fields) {
+    writeStderr(msg);
+    logger_js_1.logger.error(fields ?? {}, msg);
+}
+function cliErrorKey(key, vars, fields) {
+    cliError((0, index_js_1.t)(key, vars), fields);
+}

package/dist/core/code/engine/cli/detect-changes-format.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatDetectChangesResult = formatDetectChangesResult;
+const index_js_1 = require("./i18n/index.js");
+function formatDetectChangesResult(result) {
+    const payload = (result ?? {});
+    if (payload.error)
+        return (0, index_js_1.t)('common.error', { message: String(payload.error) });
+    const summary = payload.summary ?? {};
+    if ((summary.changed_count ?? 0) === 0) {
+        return (0, index_js_1.t)('tool.detectChanges.noChanges');
+    }
+    const lines = [];
+    lines.push((0, index_js_1.t)('tool.detectChanges.changesSummary', {
+        files: summary.changed_files ?? 0,
+        symbols: summary.changed_count ?? 0,
+    }));
+    lines.push((0, index_js_1.t)('tool.detectChanges.affectedProcesses', { count: summary.affected_count ?? 0 }));
+    lines.push((0, index_js_1.t)('tool.detectChanges.riskLevel', {
+        risk: summary.risk_level || (0, index_js_1.t)('tool.detectChanges.unknownRisk'),
+    }));
+    lines.push('');
+    const changed = Array.isArray(payload.changed_symbols) ? payload.changed_symbols : [];
+    if (changed.length > 0) {
+        lines.push((0, index_js_1.t)('tool.detectChanges.changedSymbols'));
+        const shown = changed.slice(0, 15);
+        for (const symbol of shown) {
+            lines.push(`  ${symbol.type ?? 'Symbol'} ${symbol.name ?? '?'} → ${symbol.filePath ?? '?'}`);
+        }
+        // Overflow is measured against the TRUE total (summary.changed_count), not
+        // the array length — the array may already be `--limit`-sliced, so using its
+        // length would under-report (or hide) how many symbols are not shown.
+        const totalChanged = summary.changed_count ?? changed.length;
+        if (totalChanged > shown.length) {
+            lines.push((0, index_js_1.t)('tool.detectChanges.overflowMore', { count: totalChanged - shown.length }));
+        }
+        lines.push('');
+    }
+    const affected = Array.isArray(payload.affected_processes) ? payload.affected_processes : [];
+    if (affected.length > 0) {
+        lines.push((0, index_js_1.t)('tool.detectChanges.affectedExecutionFlows'));
+        const shownAffected = affected.slice(0, 10);
+        for (const processInfo of shownAffected) {
+            const changedSteps = Array.isArray(processInfo.changed_steps)
+                ? processInfo.changed_steps
+                : [];
+            const steps = changedSteps.map((step) => step.symbol ?? '?').join(', ');
+            lines.push(`  • ${processInfo.name ?? '?'} (${(0, index_js_1.t)('tool.detectChanges.steps', {
+                count: processInfo.step_count ?? 0,
+            })}) — ${(0, index_js_1.t)('tool.detectChanges.changedSteps', { steps })}`);
+        }
+        const totalAffected = summary.affected_count ?? affected.length;
+        if (totalAffected > shownAffected.length) {
+            lines.push((0, index_js_1.t)('tool.detectChanges.overflowMore', { count: totalAffected - shownAffected.length }));
+        }
+    }
+    return lines.join('\n').trim();
+}

package/dist/core/code/engine/cli/embedding-dims.js

@@ -0,0 +1,43 @@
+"use strict";
+/**
+ * Strict positive-integer normalization for the `--embedding-dims` flag /
+ * `CGRAPH_EMBEDDING_DIMS` value.
+ *
+ * Single source of truth shared by two write paths:
+ *   1. the `analyze` `preAction` hook (CLI path) — it must set the env var
+ *      BEFORE `schema.ts` reads `CGRAPH_EMBEDDING_DIMS` at module-load time
+ *      (the static import chain `analyze.ts → run-analyze.ts → schema.ts`
+ *      bakes `FLOAT[dims]` into the vector-table DDL), and
+ *   2. `analyzeCommandImpl` (direct / programmatic-call path, which bypasses
+ *      the commander hook).
+ *
+ * Keep this module dependency-free. `index.ts` imports it eagerly, so pulling
+ * in anything that transitively loads `schema.ts` (e.g. `analyze.ts`) — or
+ * even `cli-message.ts`, which drags in the logger + i18n — would defeat the
+ * lazy `import('./analyze.js')` the hook exists to enable. Callers print the
+ * error themselves (the hook to stderr, the impl via `cliError`).
+ *
+ * Trim-then-validate, matching the sibling URL/MODEL/TOKEN flags: surrounding
+ * whitespace is tolerated, but the remaining value must be all digits and
+ * `> 0`. This rejects scientific notation (`1e3`), hex (`0x10`), fractions
+ * (`3.5`), signs (`+5`/`-5`), and trailing junk (`4096x`) so the three
+ * downstream readers — `schema.ts` (`parseInt`), `http-client.ts` (`/^\d+$/`),
+ * and this helper — all agree on one canonical value. Without it, `1e3` parsed
+ * to `FLOAT[1]` at module-load but requested 1000-dim vectors at runtime.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeEmbeddingDims = exports.EMBEDDING_DIMS_ERROR = void 0;
+/** Shared error message so both call sites surface identical wording. */
+exports.EMBEDDING_DIMS_ERROR = '--embedding-dims must be a positive integer.';
+/**
+ * Returns the canonical positive-integer string (e.g. `"007"` → `"7"`), or
+ * `null` when the input is not a strict positive integer.
+ */
+const normalizeEmbeddingDims = (raw) => {
+    const trimmed = raw.trim();
+    if (!/^\d+$/.test(trimmed) || parseInt(trimmed, 10) <= 0) {
+        return null;
+    }
+    return String(parseInt(trimmed, 10));
+};
+exports.normalizeEmbeddingDims = normalizeEmbeddingDims;

package/dist/core/code/engine/cli/format-elapsed.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatElapsed = formatElapsed;
+function formatElapsed(secs) {
+    if (secs < 60)
+        return `${secs}s`;
+    if (secs < 3600)
+        return `${Math.floor(secs / 60)}m ${secs % 60}s`;
+    const h = Math.floor(secs / 3600);
+    const m = Math.floor((secs % 3600) / 60);
+    return `${h}h ${m}m`;
+}

package/dist/core/code/engine/cli/help-i18n.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.localizeCliHelp = localizeCliHelp;
+const index_js_1 = require("./i18n/index.js");
+const TITLE_KEYS = {
+    'Usage:': 'help.title.usage',
+    'Arguments:': 'help.title.arguments',
+    'Options:': 'help.title.options',
+    'Global Options:': 'help.title.globalOptions',
+    'Commands:': 'help.title.commands',
+};
+const COMMAND_DESCRIPTION_KEYS = {
+    '': 'help.description.root',
+    analyze: 'help.command.analyze.description',
+    status: 'help.command.status.description',
+    context: 'help.command.context.description',
+    impact: 'help.command.impact.description',
+    cypher: 'help.command.cypher.description',
+    'detect-changes': 'help.command.detectChanges.description',
+    trace: 'help.command.trace.description',
+    'route-map': 'help.command.routeMap.description',
+    'api-impact': 'help.command.apiImpact.description',
+    'shape-check': 'help.command.shapeCheck.description',
+    'tool-map': 'help.command.toolMap.description',
+};
+const OPTION_DESCRIPTION_KEYS = {
+    '|-V, --version': 'help.option.version',
+    'analyze|-f, --force': 'help.option.analyze.force',
+    'analyze|--embeddings [limit]': 'help.option.analyze.embeddings',
+    'analyze|--drop-embeddings': 'help.option.analyze.dropEmbeddings',
+    'analyze|--name <alias>': 'help.option.analyze.name',
+    'analyze|--allow-duplicate-name': 'help.option.analyze.allowDuplicateName',
+    'analyze|-v, --verbose': 'help.option.verbose',
+    'analyze|--max-file-size <kb>': 'help.option.analyze.maxFileSize',
+    'analyze|--worker-timeout <seconds>': 'help.option.analyze.workerTimeout',
+    'analyze|--wal-checkpoint-threshold <bytes>': 'help.option.analyze.walCheckpointThreshold',
+    'analyze|--workers <n>': 'help.option.analyze.workers',
+    'analyze|--embedding-threads <n>': 'help.option.analyze.embeddingThreads',
+    'analyze|--embedding-batch-size <n>': 'help.option.analyze.embeddingBatchSize',
+    'analyze|--embedding-sub-batch-size <n>': 'help.option.analyze.embeddingSubBatchSize',
+    'analyze|--embedding-device <device>': 'help.option.analyze.embeddingDevice',
+    'status|--json': 'help.option.status.json',
+    'context|-r, --repo <name>': 'help.option.repo.target',
+    'context|--branch <name>': 'help.option.branch',
+    'context|-u, --uid <uid>': 'help.option.context.uid',
+    'context|-f, --file <path>': 'help.option.context.file',
+    'context|-l, --limit <n>': 'help.option.context.limit',
+    'context|--content': 'help.option.content',
+    'impact|-d, --direction <dir>': 'help.option.impact.direction',
+    'impact|-r, --repo <name>': 'help.option.repo.target',
+    'impact|--branch <name>': 'help.option.branch',
+    'impact|-u, --uid <uid>': 'help.option.context.uid',
+    'impact|-f, --file <path>': 'help.option.context.file',
+    'impact|--kind <kind>': 'help.option.impact.kind',
+    'impact|--depth <n>': 'help.option.impact.depth',
+    'impact|--include-tests': 'help.option.impact.includeTests',
+    'impact|-l, --limit <n>': 'help.option.impact.limit',
+    'impact|--offset <n>': 'help.option.impact.offset',
+    'impact|--summary-only': 'help.option.impact.summaryOnly',
+    'cypher|-r, --repo <name>': 'help.option.repo.target',
+    'cypher|--branch <name>': 'help.option.branch',
+    'cypher|-l, --limit <n>': 'help.option.cypher.limit',
+    'detect-changes|-s, --scope <scope>': 'help.option.detectChanges.scope',
+    'detect-changes|-b, --base-ref <ref>': 'help.option.detectChanges.baseRef',
+    'detect-changes|-l, --limit <n>': 'help.option.detectChanges.limit',
+    'detect-changes|-r, --repo <name>': 'help.option.repo.target',
+    'detect-changes|--branch <name>': 'help.option.branch',
+    'trace|--from-uid <uid>': 'help.option.trace.fromUid',
+    'trace|-f, --file <path>': 'help.option.trace.file',
+    'trace|--from-file <path>': 'help.option.trace.fromFile',
+    'trace|--to-uid <uid>': 'help.option.trace.toUid',
+    'trace|--to-file <path>': 'help.option.trace.toFile',
+    'trace|--depth <n>': 'help.option.trace.depth',
+    'trace|--include-tests': 'help.option.trace.includeTests',
+    'trace|-r, --repo <name>': 'help.option.repo.target',
+    'trace|--branch <name>': 'help.option.branch',
+    'api-impact|-f, --file <path>': 'help.option.apiImpact.file',
+    'api-impact|--method <verb>': 'help.option.apiImpact.method',
+};
+function localizeTitle(title) {
+    const key = TITLE_KEYS[title];
+    return key ? (0, index_js_1.t)(key) : title;
+}
+function localizeOptionDescription(option) {
+    const extraInfo = [];
+    if (option.argChoices) {
+        const label = (0, index_js_1.t)('help.optionMeta.choices');
+        extraInfo.push(`${label}: ${option.argChoices.map((choice) => JSON.stringify(choice)).join(', ')}`);
+    }
+    if (option.defaultValue !== undefined) {
+        const showDefault = option.required ||
+            option.optional ||
+            (option.isBoolean() && typeof option.defaultValue === 'boolean');
+        if (showDefault) {
+            const label = (0, index_js_1.t)('help.optionMeta.default');
+            extraInfo.push(`${label}: ${option.defaultValueDescription || JSON.stringify(option.defaultValue)}`);
+        }
+    }
+    if (option.presetArg !== undefined && option.optional) {
+        const label = (0, index_js_1.t)('help.optionMeta.preset');
+        extraInfo.push(`${label}: ${JSON.stringify(option.presetArg)}`);
+    }
+    if (option.envVar !== undefined) {
+        const label = (0, index_js_1.t)('help.optionMeta.env');
+        extraInfo.push(`${label}: ${option.envVar}`);
+    }
+    if (extraInfo.length > 0) {
+        const extraDescription = `(${extraInfo.join(', ')})`;
+        if (option.description)
+            return `${option.description} ${extraDescription}`;
+        return extraDescription;
+    }
+    return option.description;
+}
+function pathFor(commandPath, command) {
+    if (!command.parent)
+        return '';
+    return commandPath ? `${commandPath} ${command.name()}` : command.name();
+}
+function applyHelpI18n(command, commandPath = '') {
+    const descriptionKey = COMMAND_DESCRIPTION_KEYS[commandPath];
+    if (descriptionKey)
+        command.description((0, index_js_1.t)(descriptionKey));
+    command.helpOption('-h, --help', (0, index_js_1.t)('help.option.help'));
+    command.configureHelp({
+        styleTitle: localizeTitle,
+        optionDescription: localizeOptionDescription,
+    });
+    if (command.commands.length > 0) {
+        command.helpCommand('help [command]', (0, index_js_1.t)('help.command.help.description'));
+    }
+    for (const option of command.options) {
+        const optionKey = OPTION_DESCRIPTION_KEYS[`${commandPath}|${option.flags}`];
+        if (optionKey)
+            option.description = (0, index_js_1.t)(optionKey);
+    }
+    for (const subcommand of command.commands) {
+        applyHelpI18n(subcommand, pathFor(commandPath, subcommand));
+    }
+}
+function localizeCliHelp(program) {
+    applyHelpI18n(program);
+    return program;
+}

package/dist/core/code/engine/cli/i18n/en.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.en = void 0;
+exports.en = {
+    'common.runAnalyzeShort': 'Run: cgraph analyze',
+    'common.error': 'Error: {{message}}',
+    'status.notGitRepo': 'Not a git repository.',
+    'status.staleKuzu': 'Repository has a stale KuzuDB index from a previous version.',
+    'status.rebuildLadybug': 'Run: cgraph analyze   (rebuilds the index with LadybugDB)',
+    'status.repoNotIndexed': 'Repository not indexed.',
+    'status.repository': 'Repository',
+    'status.indexed': 'Indexed',
+    'status.indexedCommit': 'Indexed commit',
+    'status.currentCommit': 'Current commit',
+    'status.indexRunnerIdentity': 'Indexed analyzer runner identity',
+    'status.currentRunnerIdentity': 'Current analyzer runner identity',
+    'status.branch': 'Branch',
+    'status.detached': '(detached HEAD)',
+    'status.plainFolderMode': 'Mode: plain-folder (no .git — commit tracking unavailable)',
+    'status.workspaceIndexLabel': "Workspace index: last analyzed on '{{primary}}' (re-run cgraph analyze to follow the current branch)",
+    'status.status': 'Status',
+    'status.upToDate': '✅ up-to-date',
+    'status.stale': '⚠️ stale (re-run cgraph analyze)',
+    'tool.noIndexed': '[cgraph] No index found in {{searchedPath}}. Run: cgraph analyze to build it',
+    'tool.usage.context': 'Usage: cgraph context <symbol_name> [--uid <uid>] [--file <path>]',
+    'tool.usage.impact': 'Usage: cgraph impact <symbol_name> [--uid <uid>] [--file <path>] [--kind <kind>] [--direction upstream|downstream]',
+    'tool.usage.trace': 'Usage: cgraph trace <from> <to> [-f|--file <path>] [--from-file <path>] [--to-file <path>] [--from-uid <uid>] [--to-uid <uid>] [--depth <n>]',
+    'tool.usage.cypher': 'Usage: cgraph cypher <cypher_query>',
+    'tool.usage.apiImpact': 'Usage: cgraph api-impact <route> [--file <path>] [--method <verb>]',
+    'tool.warn.unknownKind': "--kind '{{kind}}' is not a known symbol kind (e.g. Function, Class, Method); it will not narrow the result.",
+    'tool.detectChanges.noChanges': 'No changes detected.',
+    'tool.detectChanges.changesSummary': 'Changes: {{files}} files, {{symbols}} symbols',
+    'tool.detectChanges.affectedProcesses': 'Affected processes: {{count}}',
+    'tool.detectChanges.riskLevel': 'Risk level: {{risk}}',
+    'tool.detectChanges.unknownRisk': 'unknown',
+    'tool.detectChanges.changedSymbols': 'Changed symbols:',
+    'tool.detectChanges.overflowMore': '... and {{count}} more',
+    'tool.detectChanges.affectedExecutionFlows': 'Affected execution flows:',
+    'tool.detectChanges.steps': '{{count}} steps',
+    'tool.detectChanges.steps_one': '{{count}} step',
+    'tool.detectChanges.steps_other': '{{count}} steps',
+    'tool.detectChanges.changedSteps': 'changed: {{steps}}',
+    'help.title.usage': 'Usage:',
+    'help.title.arguments': 'Arguments:',
+    'help.title.options': 'Options:',
+    'help.title.globalOptions': 'Global Options:',
+    'help.title.commands': 'Commands:',
+    'help.optionMeta.choices': 'choices',
+    'help.optionMeta.default': 'default',
+    'help.optionMeta.preset': 'preset',
+    'help.optionMeta.env': 'env',
+    'help.description.root': 'cgraph local CLI',
+    'help.command.help.description': 'display help for command',
+    'help.option.help': 'display help for command',
+    'help.option.version': 'output the version number',
+    'help.command.analyze.description': 'Index a repository (full analysis)',
+    'help.command.status.description': 'Show index status for current repo',
+    'help.command.context.description': '360-degree view of a code symbol: callers, callees, processes',
+    'help.command.impact.description': 'Blast radius analysis: what breaks if you change a symbol',
+    'help.command.trace.description': 'Find the shortest directed path between two symbols (call + class-member edges)',
+    'help.command.cypher.description': 'Execute raw Cypher query against the knowledge graph',
+    'help.command.detectChanges.description': 'Map git diff hunks to indexed symbols and affected execution flows',
+    'help.command.routeMap.description': 'Map API routes to handlers and consumers (front-end HTTP consumers require workspace config)',
+    'help.command.apiImpact.description': 'Pre-change impact report for an API route handler',
+    'help.command.shapeCheck.description': 'Detect response-shape vs consumer access mismatches (front-end HTTP consumers require workspace config)',
+    'help.command.toolMap.description': 'Map MCP/RPC tool definitions to handlers',
+    'help.option.analyze.force': 'Force full re-index even if up to date',
+    'help.option.analyze.embeddings': 'Enable embedding generation for semantic search (off by default). Optional [limit] overrides the 50,000-node safety cap; pass 0 to disable the cap entirely.',
+    'help.option.analyze.dropEmbeddings': 'Drop existing embeddings on rebuild. By default, an `analyze` without `--embeddings` preserves any embeddings already present in the index.',
+    'help.option.analyze.name': 'Register this repo under a custom name (disambiguates repos whose paths share a basename, e.g. two different .../app folders)',
+    'help.option.analyze.allowDuplicateName': 'Register this repo even if another path already uses the same --name alias. Leaves `-r <name>` ambiguous for the two paths; use -r <path> to disambiguate.',
+    'help.option.verbose': 'Enable verbose output',
+    'help.option.analyze.maxFileSize': 'Skip files larger than this (KB). Default: 512. Hard cap: 32768 (tree-sitter limit).',
+    'help.option.analyze.workerTimeout': 'Worker sub-batch idle timeout before retry/fallback. Default: 30.',
+    'help.option.analyze.walCheckpointThreshold': 'LadybugDB WAL auto-checkpoint threshold in bytes during analyze (integer >= -1; default: 67108864 = 64 MiB; -1 keeps Ladybug stock ~16 MiB).',
+    'help.option.analyze.workers': 'Parse worker pool size (>=1). Default: cores-1 capped at 16, auto-sized to the repo.',
+    'help.option.analyze.embeddingThreads': 'Limit local ONNX embedding CPU threads',
+    'help.option.analyze.embeddingBatchSize': 'Number of nodes per embedding batch',
+    'help.option.analyze.embeddingSubBatchSize': 'Number of chunks per embedding model call',
+    'help.option.analyze.embeddingDevice': 'Embedding device: auto, cpu, dml, cuda, or wasm',
+    'help.option.status.json': 'Emit machine-readable index and analyzer provenance',
+    'help.option.repo.target': 'Target repository',
+    'help.option.branch': 'Scope to a specific branch index (multi-branch repos)',
+    'help.option.content': 'Include full symbol source code',
+    'help.option.context.uid': 'Direct symbol UID (zero-ambiguity lookup)',
+    'help.option.context.file': 'File path to disambiguate common names',
+    'help.option.context.limit': 'Max callers/callees/processes to return',
+    'help.option.impact.kind': 'Kind filter to disambiguate common names (e.g. Function, Class, Method)',
+    'help.option.impact.direction': 'upstream (dependants) or downstream (dependencies)',
+    'help.option.impact.depth': 'Max relationship depth (default: 3)',
+    'help.option.impact.includeTests': 'Include test files in results',
+    'help.option.impact.limit': 'Max symbols per depth level and affected processes/modules to return (default: 100)',
+    'help.option.impact.offset': 'Skip N symbols per depth level for pagination',
+    'help.option.impact.summaryOnly': 'Return counts and risk only, omit symbol list',
+    'help.option.trace.fromUid': 'Source symbol UID (zero-ambiguity lookup)',
+    'help.option.trace.file': 'Source file path hint (alias for --from-file)',
+    'help.option.trace.fromFile': 'Source file path to disambiguate common names',
+    'help.option.trace.toUid': 'Target symbol UID (zero-ambiguity lookup)',
+    'help.option.trace.toFile': 'Target file path to disambiguate common names',
+    'help.option.trace.depth': 'Max path length in hops (default: 10)',
+    'help.option.trace.includeTests': 'Traverse through test-file symbols (default: false)',
+    'help.option.apiImpact.file': 'Handler file path (alternative to a route name in <target>)',
+    'help.option.apiImpact.method': 'HTTP verb to narrow multi-verb routes (e.g. GET, POST)',
+    'help.option.detectChanges.scope': 'What to analyze: unstaged, staged, all, or compare',
+    'help.option.detectChanges.baseRef': 'Branch/commit for compare scope (e.g. main)',
+    'help.option.detectChanges.limit': 'Max changed symbols to return',
+    'help.option.cypher.limit': 'Max result rows to return',
+    'help.identityCache.environment': '\nAnalyzer identity cache:\n  CGRAPH_ANALYZER_IDENTITY_CACHE_DIR=/absolute/protected/dir\n    Operator-trusted persistent cache for warm cross-process status. The directory must pre-exist, be outside the GitNexus package/build roots, and contain no symlink or junction components. Defaults remain fail-closed on platforms without POSIX ownership APIs.',
+    'help.analyze.environment': '\nEnvironment variables:\n  CGRAPH_NO_GITIGNORE=1   Skip .gitignore parsing (still reads .cgraphignore)\n  CGRAPH_MAX_FILE_SIZE=N  Override large-file skip threshold (KB). Default 512, max 32768.\n  CGRAPH_ANALYZER_IDENTITY_CACHE_DIR=/absolute/protected/dir  Operator-trusted persistent analyzer identity cache; must pre-exist, be outside package/build roots, and contain no symlink/junction components.\n  CGRAPH_WORKER_SUB_BATCH_TIMEOUT_MS=N  Worker idle timeout in milliseconds. Default 30000.\n  CGRAPH_WAL_CHECKPOINT_THRESHOLD=N  LadybugDB WAL auto-checkpoint threshold in bytes (default 67108864 = 64 MiB; -1 keeps Ladybug stock ~16 MiB).\n  CGRAPH_WORKER_SUB_BATCH_MAX_BYTES=N  Worker job byte budget. Default 8388608.\n  CGRAPH_WORKER_POOL_SIZE=N  Parse worker count override. Default cores-1 capped at 16.\n  CGRAPH_PARSE_CHUNK_CONCURRENCY=N  Concurrent in-flight parse chunks. Default 2.\n  CGRAPH_WORKER_MAX_RESPAWNS_PER_SLOT=N  Max replacement spawns per slot before drop. Default 3.\n  CGRAPH_WORKER_MAX_CUMULATIVE_TIMEOUT_MS=N  Total retry wall-time per job. Default 5x sub-batch timeout.\n  CGRAPH_WORKER_CONSECUTIVE_FAILURE_THRESHOLD=N  Per-slot deaths to trip circuit breaker. Default max(3, poolSize).\n  CGRAPH_WORKER_SHUTDOWN_DRAIN_MS=N  Max wait at pool shutdown for a retired worker still inside native code (terminated at its next safe point instead of aborting the process). Default 30000.\n  CGRAPH_CPP_CAPTURE_BUDGET_MS=N  Per-file wall-clock budget for C++ capture extraction; on breach the file keeps partial captures with a warning. Default 20000.\n\nFlags override the corresponding env vars when both are provided.\n\nTip: `.cgraphignore` supports `.gitignore`-style negation. Add e.g.\n     `!__tests__/` to index a directory that is auto-filtered by default (#771).',
+};

package/dist/core/code/engine/cli/i18n/index.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectCliLanguage = detectCliLanguage;
+exports.setCliLanguage = setCliLanguage;
+exports.getCliLanguage = getCliLanguage;
+exports.t = t;
+const resources_js_1 = require("./resources.js");
+let overrideLanguage = null;
+function normalizeCliLanguage(raw) {
+    const normalized = raw.trim().split('.')[0]?.replace(/_/g, '-').toLowerCase() ?? '';
+    if (!normalized)
+        return 'en';
+    // GitNexus currently ships Simplified Chinese only. Do not map Traditional
+    // Chinese locales (zh-TW/zh-HK/zh-Hant) to zh-CN just because they start
+    // with "zh".
+    if (normalized === 'zh' ||
+        normalized === 'zh-cn' ||
+        normalized.startsWith('zh-cn-') ||
+        normalized === 'zh-hans' ||
+        normalized.startsWith('zh-hans-')) {
+        return 'zh-CN';
+    }
+    return 'en';
+}
+function detectCliLanguage(env = process.env) {
+    const raw = env.CGRAPH_LANG || env.LC_ALL || env.LC_MESSAGES || env.LANG || '';
+    return normalizeCliLanguage(raw);
+}
+function setCliLanguage(language) {
+    overrideLanguage = language;
+}
+function getCliLanguage() {
+    return overrideLanguage ?? detectCliLanguage();
+}
+function t(key, vars = {}) {
+    const language = getCliLanguage();
+    const count = typeof vars.count === 'number' && Number.isFinite(vars.count) ? vars.count : null;
+    const pluralKey = count === null ? null : `${String(key)}_${count === 1 ? 'one' : 'other'}`;
+    const template = (pluralKey ? (resources_js_1.cliResources[language][pluralKey] ?? resources_js_1.cliResources.en[pluralKey]) : undefined) ??
+        resources_js_1.cliResources[language][key] ??
+        resources_js_1.cliResources.en[key] ??
+        key;
+    return template.replace(/\{\{\s*([\w.-]+)\s*\}\}/g, (_match, name) => {
+        const value = vars[name];
+        return value === undefined || value === null ? '' : String(value);
+    });
+}

package/dist/core/code/engine/cli/i18n/resources.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cliResources = void 0;
+const en_js_1 = require("./en.js");
+const zh_CN_js_1 = require("./zh-CN.js");
+exports.cliResources = {
+    en: en_js_1.en,
+    'zh-CN': zh_CN_js_1.zhCN,
+};

package/dist/core/code/engine/cli/i18n/zh-CN.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.zhCN = void 0;
+exports.zhCN = {
+    'common.runAnalyzeShort': '运行：cgraph analyze',
+    'common.error': '错误：{{message}}',
+    'status.notGitRepo': '当前目录不是 git 仓库。',
+    'status.staleKuzu': '仓库包含旧版本遗留的 KuzuDB 索引。',
+    'status.rebuildLadybug': '运行：cgraph analyze   （使用 LadybugDB 重建索引）',
+    'status.repoNotIndexed': '仓库尚未索引。',
+    'status.repository': '仓库',
+    'status.indexed': '索引时间',
+    'status.indexedCommit': '索引提交',
+    'status.currentCommit': '当前提交',
+    'status.indexRunnerIdentity': '索引记录的分析器运行身份',
+    'status.currentRunnerIdentity': '当前分析器运行身份',
+    'status.branch': '分支',
+    'status.detached': '（分离 HEAD）',
+    'status.plainFolderMode': '模式：纯目录（无 .git——commit 跟踪不可用）',
+    'status.workspaceIndexLabel': "工作区索引：最近在 '{{primary}}' 分支上分析（重新运行 cgraph analyze 以跟随当前分支）",
+    'status.status': '状态',
+    'status.upToDate': '✅ 已是最新',
+    'status.stale': '⚠️ 已过期（重新运行 cgraph analyze）',
+    'tool.noIndexed': '[cgraph] 在 {{searchedPath}} 未找到索引。请运行：cgraph analyze 构建索引',
+    'tool.usage.context': '用法：cgraph context <符号名> [--uid <uid>] [--file <路径>]',
+    'tool.usage.impact': '用法：cgraph impact <符号名> [--uid <uid>] [--file <路径>] [--kind <类型>] [--direction upstream|downstream]',
+    'tool.usage.trace': '用法：cgraph trace <起点> <终点> [-f|--file <路径>] [--from-file <路径>] [--to-file <路径>] [--from-uid <uid>] [--to-uid <uid>] [--depth <n>]',
+    'tool.usage.cypher': '用法：cgraph cypher <Cypher 查询>',
+    'tool.usage.apiImpact': '用法：cgraph api-impact <路由> [--file <路径>] [--method <动词>]',
+    'tool.warn.unknownKind': "--kind '{{kind}}' 不是已知的符号类型（如 Function、Class、Method），不会用于缩小结果范围。",
+    'tool.detectChanges.noChanges': '未检测到变更。',
+    'tool.detectChanges.changesSummary': '变更：{{files}} 个文件，{{symbols}} 个符号',
+    'tool.detectChanges.affectedProcesses': '受影响流程：{{count}}',
+    'tool.detectChanges.riskLevel': '风险等级：{{risk}}',
+    'tool.detectChanges.unknownRisk': '未知',
+    'tool.detectChanges.changedSymbols': '已变更符号：',
+    'tool.detectChanges.overflowMore': '... 以及另外 {{count}} 个',
+    'tool.detectChanges.affectedExecutionFlows': '受影响执行流程：',
+    'tool.detectChanges.steps': '{{count}} 步',
+    'tool.detectChanges.steps_one': '{{count}} 步',
+    'tool.detectChanges.steps_other': '{{count}} 步',
+    'tool.detectChanges.changedSteps': '已变更：{{steps}}',
+    'help.title.usage': '用法：',
+    'help.title.arguments': '参数：',
+    'help.title.options': '选项：',
+    'help.title.globalOptions': '全局选项：',
+    'help.title.commands': '命令：',
+    'help.optionMeta.choices': '可选值',
+    'help.optionMeta.default': '默认',
+    'help.optionMeta.preset': '预设',
+    'help.optionMeta.env': '环境变量',
+    'help.description.root': 'GitNexus 本地 CLI',
+    'help.command.help.description': '显示命令帮助',
+    'help.option.help': '显示命令帮助',
+    'help.option.version': '输出版本号',
+    'help.command.analyze.description': '索引仓库（完整分析）',
+    'help.command.status.description': '显示当前仓库的索引状态',
+    'help.command.context.description': '查看代码符号的 360 度视图：调用者、被调用者、流程',
+    'help.command.impact.description': '影响面分析：修改符号会影响什么',
+    'help.command.trace.description': '查找两个符号之间的最短有向路径（调用与类成员边）',
+    'help.command.cypher.description': '对知识图谱执行原始 Cypher 查询',
+    'help.command.detectChanges.description': '将 git diff hunk 映射到已索引符号和受影响执行流程',
+    'help.command.routeMap.description': '映射 API 路由到 handler 与消费方（前端 HTTP 消费关系需 workspace 配置声明）',
+    'help.command.apiImpact.description': '针对 API 路由 handler 的改动前影响报告',
+    'help.command.shapeCheck.description': '检测接口响应形状与消费方属性访问的不匹配（前端 HTTP 消费关系需 workspace 配置声明）',
+    'help.command.toolMap.description': '映射 MCP/RPC 工具定义到 handler',
+    'help.option.analyze.force': '即使已是最新也强制完整重建索引',
+    'help.option.analyze.embeddings': '启用语义搜索的嵌入生成（默认关闭）。可选 [limit] 覆盖 50,000 节点安全上限；传 0 可完全禁用上限。',
+    'help.option.analyze.dropEmbeddings': '重建时删除现有嵌入。默认情况下，未传 `--embeddings` 的 `analyze` 会保留索引中已有嵌入。',
+    'help.option.analyze.name': '使用自定义名称注册该仓库（用于区分路径 basename 相同的仓库，例如两个不同的 .../app 目录）',
+    'help.option.analyze.allowDuplicateName': '即使已有其他路径使用相同 --name 别名，也注册该仓库。会使两个路径的 `-r <name>` 产生歧义；请用 -r <path> 消除歧义。',
+    'help.option.verbose': '启用详细输出',
+    'help.option.analyze.maxFileSize': '跳过大于该值的文件（KB）。默认：512。硬上限：32768（tree-sitter 限制）。',
+    'help.option.analyze.workerTimeout': 'Worker 子批次空闲超时，超时后重试/回退。默认：30。',
+    'help.option.analyze.walCheckpointThreshold': 'analyze 期间 LadybugDB WAL 自动 checkpoint 阈值（字节，整数 >= -1；默认：67108864 = 64 MiB；-1 保持 Ladybug 默认约 16 MiB）。',
+    'help.option.analyze.workers': '解析 worker 池大小（>=1）。默认：cores-1，最多 16，按仓库规模自适应。',
+    'help.option.analyze.embeddingThreads': '限制本地 ONNX 嵌入 CPU 线程数',
+    'help.option.analyze.embeddingBatchSize': '每个嵌入批次的节点数',
+    'help.option.analyze.embeddingSubBatchSize': '每次嵌入模型调用的分块数',
+    'help.option.analyze.embeddingDevice': '嵌入设备：auto、cpu、dml、cuda 或 wasm',
+    'help.option.status.json': '输出机器可读的索引和分析器来源信息',
+    'help.option.repo.target': '目标仓库',
+    'help.option.branch': '将查询限定到指定分支的索引（多分支仓库）',
+    'help.option.content': '包含完整符号源码',
+    'help.option.context.uid': '直接符号 UID（零歧义查找）',
+    'help.option.context.file': '用于消除常见名称歧义的文件路径',
+    'help.option.context.limit': '最多返回的调用者/被调用者/流程数',
+    'help.option.impact.kind': '用于消除常见名称歧义的类型过滤（如 Function、Class、Method）',
+    'help.option.impact.direction': 'upstream（依赖它的项）或 downstream（它依赖的项）',
+    'help.option.impact.depth': '最大关系遍历深度（默认：3）',
+    'help.option.impact.includeTests': '在结果中包含测试文件',
+    'help.option.impact.limit': '每层深度最大符号数及最多返回的受影响流程/模块数（默认：100）',
+    'help.option.impact.offset': '每层深度跳过 N 个符号（分页用）',
+    'help.option.impact.summaryOnly': '仅返回计数和风险等级，省略符号列表',
+    'help.option.trace.fromUid': '源符号 UID（零歧义查找）',
+    'help.option.trace.file': '源文件路径提示（--from-file 的别名）',
+    'help.option.trace.fromFile': '源文件路径，用于消除常见名称歧义',
+    'help.option.trace.toUid': '目标符号 UID（零歧义查找）',
+    'help.option.trace.toFile': '目标文件路径，用于消除常见名称歧义',
+    'help.option.trace.depth': '最大路径跳数（默认：10）',
+    'help.option.trace.includeTests': '遍历时包含测试文件中的符号（默认：false）',
+    'help.option.apiImpact.file': 'handler 文件路径（与 <target> 路由名二选一）',
+    'help.option.apiImpact.method': '用于收窄多动词路由的 HTTP 动词（如 GET、POST）',
+    'help.option.detectChanges.scope': '分析范围：unstaged、staged、all 或 compare',
+    'help.option.detectChanges.baseRef': 'compare 范围的分支/提交（例如 main）',
+    'help.option.detectChanges.limit': '最多返回的已变更符号数',
+    'help.option.cypher.limit': '最多返回的结果行数',
+    'help.identityCache.environment': '\n分析器身份缓存：\n  CGRAPH_ANALYZER_IDENTITY_CACHE_DIR=/absolute/protected/dir\n    由操作员明确信任的持久缓存，用于跨进程快速查询状态。目录必须预先存在、位于 GitNexus 包/构建根目录之外，且路径中不得包含符号链接或 junction。缺少 POSIX 所有权 API 的平台默认保持故障关闭。',
+    'help.analyze.environment': '\n环境变量：\n  CGRAPH_NO_GITIGNORE=1   跳过 .gitignore 解析（仍读取 .cgraphignore）\n  CGRAPH_MAX_FILE_SIZE=N  覆盖大文件跳过阈值（KB）。默认 512，最大 32768。\n  CGRAPH_ANALYZER_IDENTITY_CACHE_DIR=/absolute/protected/dir  由操作员明确信任的持久分析器身份缓存；目录必须预先存在、位于包/构建根目录之外，且路径中不得包含符号链接或 junction。\n  CGRAPH_WORKER_SUB_BATCH_TIMEOUT_MS=N  Worker 空闲超时（毫秒）。默认 30000。\n  CGRAPH_WAL_CHECKPOINT_THRESHOLD=N  LadybugDB WAL 自动 checkpoint 阈值（字节，默认 67108864 = 64 MiB；-1 保持 Ladybug 默认约 16 MiB）。\n  CGRAPH_WORKER_SUB_BATCH_MAX_BYTES=N  Worker 作业字节预算。默认 8388608。\n  CGRAPH_WORKER_POOL_SIZE=N  解析 worker 数量覆盖值。默认 cores-1，最多 16。\n  CGRAPH_PARSE_CHUNK_CONCURRENCY=N  并发进行中的解析分块数。默认 2。\n  CGRAPH_WORKER_MAX_RESPAWNS_PER_SLOT=N  每个 slot 丢弃前允许的最大替换进程数。默认 3。\n  CGRAPH_WORKER_MAX_CUMULATIVE_TIMEOUT_MS=N  每个作业的总重试墙钟时间。默认 5 倍子批次超时。\n  CGRAPH_WORKER_CONSECUTIVE_FAILURE_THRESHOLD=N  每个 slot 触发熔断的死亡次数。默认 max(3, poolSize)。\n  CGRAPH_WORKER_SHUTDOWN_DRAIN_MS=N  线程池关闭时等待仍在原生代码中的已退役 worker 的最长时间（到达安全点后再终止，避免进程级 abort）。默认 30000。\n  CGRAPH_CPP_CAPTURE_BUDGET_MS=N  C++ 捕获提取的每文件墙钟预算；超出后该文件保留部分捕获并输出警告。默认 20000。\n\n当参数和对应环境变量同时提供时，参数优先。\n\n提示：`.cgraphignore` 支持 `.gitignore` 风格的取反。比如添加\n     `!__tests__/` 可以索引默认自动过滤的目录（#771）。',
+};