dsh-gitnexus-plus 0.0.0-stage → 0.1.2

package/lib/gitnexus/analyze.d.ts

@@ -0,0 +1,173 @@
+/**
+ * Run `gitnexus analyze --index-only` through the host's shell executor.
+ *
+ * WHY THIS REPLACED HANDING OVER A COMMAND
+ * ----------------------------------------
+ * The plugin used to print a command and let the operator paste it. That was
+ * justified as "a plugin that spawns processes bypasses the permission system", and
+ * the justification was wrong — not in spirit, but in what it assumed permission
+ * meant here.
+ *
+ * DSH's approval service governs **sandbox escalation**: widening the scope a session
+ * was granted. Its audit pair must be turn-enclosed, and `ApprovalService.request()`
+ * throws outside an open turn. A panel route has no turn, so it cannot ask — but it
+ * also does not need to, because this command does not escalate anything. It writes
+ * `.gitnexus/` **inside the workspace**, which is already within the granted scope.
+ *
+ * The confinement is not something a caller opts into. It is what `ctx.shell` *is* in
+ * a given deployment: `dsh-pwsh-local` exposes the argv seam that `dsh-pwsh-sandbox`
+ * wraps through `ctx.sandbox.confine`. So routing through the executor gives this
+ * plugin exactly the isolation the agent's own shell tool gets.
+ *
+ * THE ONE RULE THAT MATTERS
+ * -------------------------
+ * `sandboxPolicy` is never set here, and must never be. Passing it would be this
+ * plugin choosing its own confinement — the escalation the approval service exists to
+ * gate, requested through a door that cannot ask. Leaving it undefined takes the
+ * deployment's decision. A denial is then reported as a denial, not retried wider:
+ * the same rule the subagent prompt states, for the same reason.
+ */
+import { type ToolchainOptions } from './toolchain.js';
+/** Where a run got to. `unavailable` is decided before anything is spawned. */
+export type AnalyzeState = 
+/** No `gitnexus` executable was found — there is nothing to run. */
+'unavailable' | 'running' | 'done'
+/** The command ran and exited non-zero. */
+ | 'failed' | 'timed-out' | 'cancelled'
+/** The sandbox refused a write. Reported, never retried wider. */
+ | 'denied';
+export interface AnalyzeStatus {
+    repoPath: string;
+    state: AnalyzeState;
+    /** Whether this run was a full rebuild (`--force`). */
+    force: boolean;
+    /** The command as run, so a failure can be reproduced by hand. */
+    command: string;
+    startedAt: number;
+    finishedAt: number | null;
+    exitCode: number | null;
+    /** A short operator-facing explanation, or null when the state speaks for itself. */
+    message: string | null;
+    /** The tail of combined output, capped. */
+    output: string;
+}
+/**
+ * The slice of `ctx.shell` this module uses.
+ *
+ * Structural rather than an import: the plugin declares no runtime dependency on the
+ * DSH packages, and a test can supply a stub without a shell on the machine.
+ */
+export interface ShellRequestLike {
+    command: string;
+    workdir?: string;
+    timeoutMs?: number;
+    onExpiry?: 'kill' | 'none';
+    stdoutMaxBytes?: number;
+    signal?: AbortSignal;
+}
+export interface ShellResultLike {
+    exitCode?: number | null;
+    signal?: string | null;
+    timedOut?: boolean;
+    aborted?: boolean;
+    stdout?: {
+        text?: string;
+    } | null;
+    stderr?: {
+        text?: string;
+    } | null;
+}
+export interface ShellExecutionLike {
+    result(): Promise<ShellResultLike>;
+    kill?(): boolean | Promise<boolean>;
+}
+export interface ShellLike {
+    /** Applies the executor's defaults and caps. `execute` only accepts a resolved spec. */
+    resolve(request: ShellRequestLike): unknown;
+    execute(spec: unknown): Promise<ShellExecutionLike>;
+}
+export interface AnalyzeRunnerOptions {
+    /**
+     * The host's shell executor, or `null` when the deployment has none.
+     *
+     * `null` is a real composition rather than a test convenience: `ctx.shell` is mounted
+     * per profile, and a headless one need not have it. A runner that reported "failed"
+     * for a missing service would send the operator looking for a GitNexus problem that
+     * is really a deployment shape.
+     */
+    shell: ShellLike | null;
+    /** Wall-clock ceiling for one run. Default 10 minutes — a full rebuild is minutes. */
+    timeoutMs?: number;
+    /** Captured-output ceiling handed to the executor. */
+    outputLimit?: number;
+    /** How much output this module keeps for the panel. */
+    tailLimit?: number;
+    toolchain?: ToolchainOptions;
+    /**
+     * Pass `GITNEXUS_MEMORY=off` and the heap override, exactly as the handed-over
+     * commands do. On by default: the CLI re-spawns itself over piped stdio without it,
+     * which a confined process denies.
+     */
+    memoryOff?: boolean;
+    heapMb?: number;
+    /**
+     * `true` forces `--skip-fts`. `false`/absent is **automatic**: the runner asks the
+     * index whether FTS exists and skips it when it does not. A static `false` was
+     * measured to fail with `spawn EPERM` on an index without FTS (the extension tries
+     * to install out-of-process), while a static `true` forces a full rebuild on one
+     * that has it.
+     */
+    skipFts?: boolean;
+    /** Override the redirect of the global registry write. */
+    gitnexusHome?: string | null;
+    now?: () => number;
+}
+export interface AnalyzeRunner {
+    /**
+     * Begin a run, or report the one already in flight for this repository.
+     *
+     * `force` selects a full rebuild. It is a request, not a second run: two analyze
+     * processes on one store contend, so a force request while an incremental run is
+     * in flight returns that run.
+     */
+    start(repoPath: string, options?: {
+        force?: boolean;
+    }): AnalyzeStatus;
+    status(repoPath: string): AnalyzeStatus | null;
+    cancel(repoPath: string): boolean;
+    /** Abort every in-flight run. Called on plugin teardown. */
+    dispose(): void;
+}
+/**
+ * Build the command line, as the shell will read it.
+ *
+ * TWO THINGS HERE WERE WRONG ON THE FIRST ATTEMPT, AND TOGETHER THEY MADE THE BUTTON
+ * DO NOTHING VISIBLE — a run started, finished, and the index never changed.
+ *
+ * 1. PowerShell needs the call operator before a quoted path.
+ *    `'C:\...\gitnexus.cmd' analyze` is not a command: the single-quoted string is a
+ *    string *literal*, and the parser dies on the next token. Measured:
+ *    "表达式或语句中包含意外的标记" for the whole statement. The paste-able text in
+ *    `commands.ts` never hit this because it names a bare `gitnexus` and lets PATH
+ *    resolve it — a difference that exists only because this path is absolute.
+ *
+ * 2. The environment prefix is not optional. `GITNEXUS_MEMORY=off` stops the CLI
+ *    re-spawning itself over piped stdio, which a confined process denies. Dropping it
+ *    because the command "looked simpler" reintroduces exactly the failure the
+ *    maintenance text was written to avoid.
+ *
+ * Exported so the shape can be asserted without a shell.
+ */
+export declare function analyzeCommandLine(cliPath: string, repoPath: string, options?: {
+    flavor?: 'win32' | 'posix';
+    memoryOff?: boolean;
+    heapMb?: number;
+    viaNode?: boolean;
+    /** Full rebuild. This is the destructive escape hatch; the button must say so. */
+    force?: boolean;
+    /** Must match `maintenanceCommands`; see the note on the runner option. */
+    skipFts?: boolean;
+    gitnexusHome?: string | null;
+}): string;
+export declare function createAnalyzeRunner(options: AnalyzeRunnerOptions): AnalyzeRunner;
+//# sourceMappingURL=analyze.d.ts.map

package/lib/gitnexus/analyze.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../../src/gitnexus/analyze.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAIH,OAAO,EAAmB,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAExE,+EAA+E;AAC/E,MAAM,MAAM,YAAY;AACtB,oEAAoE;AAClE,aAAa,GACb,SAAS,GACT,MAAM;AACR,2CAA2C;GACzC,QAAQ,GACR,WAAW,GACX,WAAW;AACb,kEAAkE;GAChE,QAAQ,CAAC;AAEb,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,YAAY,CAAC;IACpB,uDAAuD;IACvD,KAAK,EAAE,OAAO,CAAC;IACf,kEAAkE;IAClE,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,qFAAqF;IACrF,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAClC,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,IAAI,OAAO,CAAC,eAAe,CAAC,CAAC;IACnC,IAAI,CAAC,IAAI,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,SAAS;IACxB,wFAAwF;IACxF,OAAO,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC;IAC5C,OAAO,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;CACrD;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;;;;OAOG;IACH,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;IACxB,sFAAsF;IACtF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B;;;;;;OAMG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,aAAa,CAAC;IACtE,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAAC;IAC/C,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IAClC,4DAA4D;IAC5D,OAAO,IAAI,IAAI,CAAC;CACjB;AAmBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;IACP,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;IAC3B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,kFAAkF;IAClF,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB,GACL,MAAM,CAgCR;AAoBD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa,CA0MhF"}

package/lib/gitnexus/analyze.js

@@ -0,0 +1,308 @@
+/**
+ * Run `gitnexus analyze --index-only` through the host's shell executor.
+ *
+ * WHY THIS REPLACED HANDING OVER A COMMAND
+ * ----------------------------------------
+ * The plugin used to print a command and let the operator paste it. That was
+ * justified as "a plugin that spawns processes bypasses the permission system", and
+ * the justification was wrong — not in spirit, but in what it assumed permission
+ * meant here.
+ *
+ * DSH's approval service governs **sandbox escalation**: widening the scope a session
+ * was granted. Its audit pair must be turn-enclosed, and `ApprovalService.request()`
+ * throws outside an open turn. A panel route has no turn, so it cannot ask — but it
+ * also does not need to, because this command does not escalate anything. It writes
+ * `.gitnexus/` **inside the workspace**, which is already within the granted scope.
+ *
+ * The confinement is not something a caller opts into. It is what `ctx.shell` *is* in
+ * a given deployment: `dsh-pwsh-local` exposes the argv seam that `dsh-pwsh-sandbox`
+ * wraps through `ctx.sandbox.confine`. So routing through the executor gives this
+ * plugin exactly the isolation the agent's own shell tool gets.
+ *
+ * THE ONE RULE THAT MATTERS
+ * -------------------------
+ * `sandboxPolicy` is never set here, and must never be. Passing it would be this
+ * plugin choosing its own confinement — the escalation the approval service exists to
+ * gate, requested through a door that cannot ask. Leaving it undefined takes the
+ * deployment's decision. A denial is then reported as a denial, not retried wider:
+ * the same rule the subagent prompt states, for the same reason.
+ */
+import path from 'node:path';
+import { defaultGitnexusHome, effectiveSkipFts } from './commands.js';
+import { findGitnexusCli } from './toolchain.js';
+const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
+const DEFAULT_OUTPUT_LIMIT = 256 * 1024;
+const DEFAULT_TAIL_LIMIT = 4 * 1024;
+/**
+ * Quote one argument for the shell the executor will spawn.
+ *
+ * Windows and POSIX disagree, and `commands.ts` already carries the same pair — kept
+ * separate here because these two modules are allowed to have different lifetimes:
+ * one produces text for a human to paste, the other produces argv for a spawn, and
+ * collapsing them would make a change to the paste-able text silently alter what
+ * actually runs.
+ */
+function quoteFor(shell, value) {
+    return shell === 'win32' ? `'${value.replace(/'/g, "''")}'` : `'${value.replace(/'/g, "'\\''")}'`;
+}
+/**
+ * Build the command line, as the shell will read it.
+ *
+ * TWO THINGS HERE WERE WRONG ON THE FIRST ATTEMPT, AND TOGETHER THEY MADE THE BUTTON
+ * DO NOTHING VISIBLE — a run started, finished, and the index never changed.
+ *
+ * 1. PowerShell needs the call operator before a quoted path.
+ *    `'C:\...\gitnexus.cmd' analyze` is not a command: the single-quoted string is a
+ *    string *literal*, and the parser dies on the next token. Measured:
+ *    "表达式或语句中包含意外的标记" for the whole statement. The paste-able text in
+ *    `commands.ts` never hit this because it names a bare `gitnexus` and lets PATH
+ *    resolve it — a difference that exists only because this path is absolute.
+ *
+ * 2. The environment prefix is not optional. `GITNEXUS_MEMORY=off` stops the CLI
+ *    re-spawning itself over piped stdio, which a confined process denies. Dropping it
+ *    because the command "looked simpler" reintroduces exactly the failure the
+ *    maintenance text was written to avoid.
+ *
+ * Exported so the shape can be asserted without a shell.
+ */
+export function analyzeCommandLine(cliPath, repoPath, options = {}) {
+    const flavor = options.flavor ?? (process.platform === 'win32' ? 'win32' : 'posix');
+    const memoryOff = options.memoryOff !== false;
+    const heapMb = options.heapMb ?? 8192;
+    // A CLI taken from the declared dependency is the package's `dist/cli/index.js`, so it
+    // is spawned through `node`. This is the better shape when available: no shim, no
+    // `.cmd`/`.ps1` selection, and therefore no reliance on the shell's call operator.
+    const viaNode = options.viaNode === true;
+    const args = `analyze --index-only` +
+        `${options.skipFts === true ? ' --skip-fts' : ''}` +
+        `${options.force === true ? ' --force' : ''} ` +
+        quoteFor(flavor, repoPath);
+    const head = viaNode ? `node ${quoteFor(flavor, cliPath)}` : quoteFor(flavor, cliPath);
+    // On Windows a `.cmd` or `.ps1` reached by absolute path needs `&`. POSIX needs none,
+    // because an absolute path in command position is already a command.
+    const invocation = viaNode || flavor !== 'win32' ? `${head} ${args}` : `& ${head} ${args}`;
+    const heap = quoteFor(flavor, `--max-old-space-size=${heapMb}`);
+    const home = typeof options.gitnexusHome === 'string' && options.gitnexusHome !== ''
+        ? quoteFor(flavor, options.gitnexusHome)
+        : null;
+    if (flavor === 'win32') {
+        const prefix = memoryOff ? `$env:GITNEXUS_MEMORY='off'; ` : '';
+        const homePrefix = home === null ? '' : `$env:GITNEXUS_HOME=${home}; `;
+        return `${prefix}${homePrefix}$env:NODE_OPTIONS=${heap}; ${invocation}`;
+    }
+    const prefix = memoryOff ? `GITNEXUS_MEMORY='off' ` : '';
+    const homePrefix = home === null ? '' : `GITNEXUS_HOME=${home} `;
+    return `${prefix}${homePrefix}NODE_OPTIONS=${heap} ${invocation}`;
+}
+/**
+ * A sandbox refusal, recognised from the marker DSH writes into the output.
+ *
+ * Tested before the generic non-zero path because a denial is not a failure of
+ * GitNexus — retrying it, or reporting it as "analyze failed", both mislead.
+ */
+function looksDenied(text) {
+    return /\[sandbox:[^\]]*denied/i.test(text) || /access is denied|permission denied|EPERM/i.test(text);
+}
+/** Keep the last `limit` characters, on a line boundary when one is available. */
+function tail(text, limit) {
+    if (text.length <= limit)
+        return text;
+    const cut = text.slice(text.length - limit);
+    const firstBreak = cut.indexOf('\n');
+    return firstBreak === -1 ? cut : cut.slice(firstBreak + 1);
+}
+export function createAnalyzeRunner(options) {
+    const { shell } = options;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const outputLimit = options.outputLimit ?? DEFAULT_OUTPUT_LIMIT;
+    const tailLimit = options.tailLimit ?? DEFAULT_TAIL_LIMIT;
+    const now = options.now ?? (() => Date.now());
+    const shellFlavor = process.platform === 'win32' ? 'win32' : 'posix';
+    const runs = new Map();
+    const inFlight = new Map();
+    /** The shape a status starts from, before any run has touched it. */
+    const BLANK = {
+        state: 'failed',
+        force: false,
+        command: '',
+        startedAt: 0,
+        finishedAt: null,
+        exitCode: null,
+        message: null,
+        output: '',
+    };
+    const finish = (repoPath, patch) => {
+        const next = {
+            repoPath,
+            ...BLANK,
+            ...runs.get(repoPath),
+            ...patch,
+            // Set last and unconditionally: every path that reaches `finish` is finishing, so
+            // a caller passing `finishedAt: null` is asking for "not finished", not for a
+            // silent no-op. The spread above cannot express that.
+            finishedAt: patch.finishedAt ?? now(),
+        };
+        runs.set(repoPath, next);
+        inFlight.delete(repoPath);
+        return next;
+    };
+    const start = (repoPath, request = {}) => {
+        const key = path.resolve(repoPath);
+        // Named `request`, not `options`: the runner's own configuration is the outer
+        // `options`, and shadowing it silently dropped `toolchain`, `memoryOff` and
+        // `heapMb` from every run built after the force argument was added.
+        const force = request.force === true;
+        // Both decisions are per repository, not per plugin: the skip-fts policy depends
+        // on the index's own FTS capability, and the registry redirect belongs beside the
+        // index so it stays inside the workspace the host was granted.
+        const skipFts = effectiveSkipFts(key, options.skipFts === true);
+        const gitnexusHome = options.gitnexusHome ?? defaultGitnexusHome(key);
+        // One run per repository. Two concurrent `analyze` processes would contend for the
+        // same store, and the second would report a failure that says nothing about the
+        // repository — so a second request reports the first rather than starting one.
+        const running = runs.get(key);
+        if (running !== undefined && running.state === 'running')
+            return running;
+        if (shell === null) {
+            return finish(key, {
+                state: 'unavailable',
+                force,
+                command: `gitnexus analyze --index-only${force ? ' --force' : ''}`,
+                startedAt: now(),
+                output: '',
+                message: '当前部署没有提供 shell 执行器（ctx.shell 未挂载），无法运行命令。' +
+                    '请复制下面的命令在终端中执行。',
+            });
+        }
+        // `moduleUrl` is what lets the probe find the `gitnexus` that npm installed beside
+        // this plugin. Omitting it would make the dependency branch unreachable and silently
+        // fall back to PATH forever — the dependency would be installed and never used.
+        const cli = findGitnexusCli({ moduleUrl: import.meta.url, ...(options.toolchain ?? {}) });
+        if (!cli.present) {
+            return finish(key, {
+                state: 'unavailable',
+                force,
+                command: `gitnexus analyze --index-only${force ? ' --force' : ''}`,
+                startedAt: now(),
+                output: '',
+                message: '本机没有找到 gitnexus 命令，无法执行。安装后重试：`npm i -g gitnexus`。' +
+                    '扫描与覆盖数据仍然可用 —— 那部分不需要 CLI。',
+            });
+        }
+        // `--index-only` is not negotiable here: without it `analyze` rewrites AGENTS.md,
+        // CLAUDE.md and the agent skill files inside the repository, which is a much larger
+        // change than "refresh the index" and not what the button says it does.
+        const command = analyzeCommandLine(cli.cliPath, key, {
+            flavor: shellFlavor,
+            memoryOff: options.memoryOff,
+            heapMb: options.heapMb,
+            viaNode: cli.viaNode,
+            force,
+            skipFts,
+            gitnexusHome,
+        });
+        const controller = new AbortController();
+        inFlight.set(key, controller);
+        const started = {
+            repoPath: key,
+            state: 'running',
+            force,
+            command,
+            startedAt: now(),
+            finishedAt: null,
+            exitCode: null,
+            message: null,
+            output: '',
+        };
+        runs.set(key, started);
+        const spec = shell.resolve({
+            command,
+            workdir: key,
+            timeoutMs,
+            onExpiry: 'kill',
+            stdoutMaxBytes: outputLimit,
+            signal: controller.signal,
+            // `sandboxPolicy` is deliberately absent. See the module comment.
+        });
+        void (async () => {
+            let execution;
+            try {
+                execution = await shell.execute(spec);
+            }
+            catch (cause) {
+                // `execute` rejects only for infrastructure failures — an unusable workdir, no
+                // shell. A cancellation rejects here too, before a handle exists.
+                const aborted = controller.signal.aborted;
+                finish(key, {
+                    state: aborted ? 'cancelled' : 'failed',
+                    message: aborted ? '已取消。' : `无法启动命令：${String(cause?.message ?? cause)}`,
+                });
+                return;
+            }
+            let result;
+            try {
+                result = await execution.result();
+            }
+            catch (cause) {
+                finish(key, { state: 'failed', message: `执行失败：${String(cause?.message ?? cause)}` });
+                return;
+            }
+            const combined = `${result.stdout?.text ?? ''}${result.stderr?.text ?? ''}`;
+            const body = tail(combined, tailLimit);
+            const exitCode = typeof result.exitCode === 'number' ? result.exitCode : null;
+            // Order matters. A denial can also be a non-zero exit, and reporting it as a
+            // generic failure sends the operator looking for a GitNexus bug that is not
+            // there. Cancellation is checked before timeout because a kill from `cancel()`
+            // and a kill from the deadline both surface as a killed process.
+            if (controller.signal.aborted) {
+                finish(key, { state: 'cancelled', exitCode, output: body, message: '已取消。' });
+            }
+            else if (result.timedOut === true) {
+                finish(key, {
+                    state: 'timed-out',
+                    exitCode,
+                    output: body,
+                    message: `超过 ${Math.round(timeoutMs / 1000)} 秒上限已终止。大仓库的全量重建可能需要更长时间。`,
+                });
+            }
+            else if (looksDenied(combined)) {
+                finish(key, {
+                    state: 'denied',
+                    exitCode,
+                    output: body,
+                    message: '沙箱拒绝了这次写入。本插件不会申请扩权 —— 需要在终端里手动执行这条命令。',
+                });
+            }
+            else if (exitCode === 0) {
+                finish(key, { state: 'done', exitCode, output: body, message: null });
+            }
+            else {
+                finish(key, {
+                    state: 'failed',
+                    exitCode,
+                    output: body,
+                    message: `gitnexus 以退出码 ${exitCode ?? '未知'} 结束。`,
+                });
+            }
+        })();
+        return started;
+    };
+    return {
+        start,
+        status: (repoPath) => runs.get(path.resolve(repoPath)) ?? null,
+        cancel: (repoPath) => {
+            const key = path.resolve(repoPath);
+            const controller = inFlight.get(key);
+            if (controller === undefined)
+                return false;
+            controller.abort();
+            return true;
+        },
+        dispose: () => {
+            for (const controller of inFlight.values())
+                controller.abort();
+            inFlight.clear();
+        },
+    };
+}
+//# sourceMappingURL=analyze.js.map

package/lib/gitnexus/analyze.js.map

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

package/lib/gitnexus/commands.d.ts

@@ -0,0 +1,129 @@
+/**
+ * The maintenance commands this plugin hands to the operator.
+ *
+ * WHY THE TEXT STILL EXISTS AFTER THE BUTTONS
+ * -------------------------------------------
+ * A first revision spawned `gitnexus analyze` directly from the plugin and exposed
+ * it as a button. That was wrong: a plugin that spawns processes bypasses the host's
+ * permission system. The correction was not "never run it" but "run it through
+ * `ctx.shell`", which is what the analyze runner does. The exact command is still the
+ * deliverable here because it is what the confirmation shows, what a failed run can
+ * be reproduced with, and what an operator can paste when the deployment has no
+ * shell executor at all. The two must not drift: the runner builds its argv from the
+ * same decisions this module documents.
+ *
+ * WHAT MAKES THE COMMANDS NON-OBVIOUS
+ * -----------------------------------
+ * A bare `gitnexus analyze` does **not** work in every deployment, and the failures
+ * are silent-ish. Measured on this machine, under a confined DSH process:
+ *
+ *   - `ensureHeap` re-spawns the CLI with a larger heap over piped stdio, which a
+ *     confined sandbox denies (`spawn EPERM`). `GITNEXUS_MEMORY=off` suppresses the
+ *     respawn; `NODE_OPTIONS` supplies the heap it was trying to obtain.
+ *   - The FTS extension installs itself out-of-process and fails the same way.
+ *     `--skip-fts` builds the index without it.
+ *   - The global registry write (`~/.gitnexus/registry.json`) is outside the
+ *     workspace and may be denied. `GITNEXUS_HOME` redirects it.
+ *
+ * `--index-only` on both commands is deliberate and not a sandbox workaround:
+ * the default `analyze` also rewrites AGENTS.md, CLAUDE.md and agent skill files
+ * inside the repository. A maintenance button must not edit the working tree.
+ */
+/**
+ * Where this plugin keeps GitNexus's global registry for one repository.
+ *
+ * `GITNEXUS_HOME` is normally `~/.gitnexus`, outside a confined host's writable
+ * scope. Pointing it at a directory inside the project's own `.gitnexus/` keeps the
+ * registry write next to the index and inside the workspace — which is the scope the
+ * operator already granted. The analysis itself still writes `.gitnexus/lbug`; this
+ * only moves the global registry side effect.
+ */
+export declare function defaultGitnexusHome(repoPath: string): string;
+/**
+ * Whether this index says content-level FTS is available.
+ *
+ * A missing manifest, a legacy manifest, or a status other than `available` all mean
+ * "do not attempt FTS". The read is synchronous because both the maintenance-command
+ * builder and the analyze runner are synchronous; the manifest is a few kilobytes.
+ */
+export declare function ftsAvailable(repoPath: string): boolean;
+/**
+ * The effective `--skip-fts` decision for one repository.
+ *
+ * `false` (the default) means **automatic**: skip FTS when the index does not have
+ * it, so a refresh in a confined process does not die trying to install an extension
+ * out-of-process. `true` forces the flag. There is deliberately no "force FTS on":
+ * that is a repair action (`gitnexus analyze --repair-fts`), not an incremental
+ * refresh, and hiding a repair behind a config boolean would mislead.
+ *
+ * The alternative — a static default — was measured wrong in both directions: `true`
+ * forces a 21x full rebuild on an index that already has FTS, while `false` makes the
+ * refresh fail with `spawn EPERM` on an index that does not.
+ */
+export declare function effectiveSkipFts(repoPath: string, configured: boolean): boolean;
+export type MaintenanceMode = 'init' | 'full';
+export interface MaintenanceCommand {
+    mode: MaintenanceMode;
+    label: string;
+    /** When the operator should reach for this one. */
+    when: string;
+    /** The command alone, for reference. */
+    argv: string;
+    /** The command with the environment it needs, ready to paste. */
+    shell: string;
+    /** Whether it discards existing index work. */
+    destructive: boolean;
+    caveat: string | null;
+}
+export interface MaintenanceOptions {
+    platform?: NodeJS.Platform;
+    /**
+     * Add `--skip-fts`. Off by default, and that default is load-bearing — see the
+     * measurement in {@link maintenanceCommands}.
+     */
+    skipFts?: boolean;
+    memoryOff?: boolean;
+    gitnexusHome?: string | null;
+}
+/** The resolved form of {@link MaintenanceOptions}, after defaults are applied. */
+interface ResolvedOptions {
+    platform: NodeJS.Platform;
+    skipFts: boolean;
+    memoryOff: boolean;
+    gitnexusHome: string | null;
+}
+/**
+ * Build the two commands for a repository.
+ *
+ * Pure, because the exact text is the deliverable — a reviewer should be able to
+ * assert on it without spawning anything.
+ *
+ * WHY `--skip-fts` IS NOT A DEFAULT
+ * ---------------------------------
+ * It was one, on the reasoning that the FTS extension installs out-of-process and a
+ * confined process denies that (`spawn EPERM`). Measured on a 39-file repository,
+ * that reasoning is wrong in the case that matters:
+ *
+ *   index has FTS + `--skip-fts`   179.22 s   full DB wipe + bulk COPY
+ *   index has FTS, no flag           8.57 s   FTS fails to load, degrades cleanly
+ *   index has no FTS + `--skip-fts`  8.25 s   changed=0, 39 rows preserved
+ *   same, warm                       6.56 s
+ *
+ * Disabling a search index the store already has forces GitNexus to rebuild the
+ * whole graph store, which is the exact opposite of incremental — a 21x penalty on
+ * the one transition an operator is most likely to hit. Letting FTS fail on its own
+ * costs nothing: it prints a warning and indexes anyway.
+ *
+ * The flag remains available for the case it was written for, where the extension
+ * file is *absent* and the install itself is what fails.
+ */
+export declare function maintenanceCommands(repoPath: string, options?: MaintenanceOptions): MaintenanceCommand[];
+/** The options {@link commandRationale} needs — a subset of the command options. */
+export type RationaleOptions = Pick<ResolvedOptions, 'skipFts' | 'memoryOff' | 'gitnexusHome'>;
+/**
+ * A one-line explanation of why the environment prefix is there at all, for the
+ * panel to show under the commands rather than leaving them looking arbitrary.
+ */
+export declare function commandRationale(options: RationaleOptions): string[];
+export {};
+//# sourceMappingURL=commands.d.ts.map

package/lib/gitnexus/commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../src/gitnexus/commands.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAQH;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAetD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,GAAG,OAAO,CAE/E;AAED,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,CAAC;AAE9C,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,eAAe,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,KAAK,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,WAAW,EAAE,OAAO,CAAC;IACrB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC3B;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,mFAAmF;AACnF,UAAU,eAAe;IACvB,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB,GAAG,kBAAkB,EAAE,CA0D5G;AAED,oFAAoF;AACpF,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,eAAe,EAAE,SAAS,GAAG,WAAW,GAAG,cAAc,CAAC,CAAC;AAE/F;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,gBAAgB,GAAG,MAAM,EAAE,CAcpE"}