peaks-loop 4.1.2 → 4.1.3

package/dist/cli/commands/worktree-lease-spawn-command.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `peaks worktree spawn` — write a lease and run `git worktree add`.
+ *
+ * Extracted verbatim from `worktree-lease-commands.ts` (mechanical move of
+ * the `.action()` body plus its two local helpers). The command name,
+ * every option and its help text, the ok/fail envelopes and the
+ * `process.exitCode = 1` on failure are unchanged.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerWorktreeLeaseSpawnCommand(auth: Command, io: ProgramIO): void;

package/dist/cli/commands/worktree-lease-spawn-command.js

@@ -0,0 +1,119 @@
+/**
+ * `peaks worktree spawn` — write a lease and run `git worktree add`.
+ *
+ * Extracted verbatim from `worktree-lease-commands.ts` (mechanical move of
+ * the `.action()` body plus its two local helpers). The command name,
+ * every option and its help text, the ok/fail envelopes and the
+ * `process.exitCode = 1` on failure are unchanged.
+ */
+import { fail, ok } from 'peaks-loop-shared/result';
+import { execSync } from 'node:child_process';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { atomicWriteJson } from '../../services/ide/shared/atomic-json.js';
+import { emitLeaseEvent } from '../../services/observability/observability-service.js';
+import { finalizeLease, generateLeaseId, leaseFilePath, ttlForRole, worktreePath } from '../../services/worktree/worktree-lease.js';
+import { joinPathSession, resolveProjectRoot, resolveSessionId } from './worktree-lease-session.js';
+const SPAWN_DESCRIPTION = `Spawn a worktree under .peaks/_runtime/<sid>/worktrees/<leaseId>/ with a managed lease. ` +
+    `The lease is the source of truth for the L2 hook gate (Part 2 of this slice); ` +
+    `until the hook integration ships, sub-agents may still invoke raw \`git worktree add\` ` +
+    `with a current \`peaks worktree auth grant\` token. Default TTL is role-aware ` +
+    `(rd=30m / qa=15m / ui=1h); pass --ttl <ms> to override.`;
+const SPAWN_TTL_DESCRIPTION = `time-to-live in ms (default role-aware; override with positive number)`;
+// Branch names must be safe for git ref-format; the cap keeps a pathological
+// rid from producing an unusable ref.
+const MAX_BRANCH_NAME_LENGTH = 80;
+function resolveTtlMs(raw, role) {
+    if (typeof raw !== 'string' || raw.length === 0)
+        return ttlForRole(role);
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return ttlForRole(role);
+    return parsed;
+}
+function deriveBranch(rid) {
+    // Branch names must be safe for git ref-format. Strip leading
+    // `rid-` if present and replace any non-safe chars with `-`.
+    return rid.replace(/[^A-Za-z0-9._/-]/g, '-').slice(0, MAX_BRANCH_NAME_LENGTH);
+}
+function printSpawnOk(io, options, ctx) {
+    const { lease, sessionId, projectRoot, ttlMs, wtPath, branch } = ctx;
+    printResult(io, ok('worktree.spawn', {
+        lease,
+        sessionId,
+        projectRoot,
+        ttlMs,
+        nextActions: [
+            `Worktree path: ${wtPath}`,
+            `Branch: ${branch}`,
+            `Lease expires at: ${new Date(lease.expiresAt).toISOString()}`,
+            'Run `peaks worktree release --lease-id <leaseId>` when done',
+            'Hook integration (lease-aware gate) ships in Part 2'
+        ]
+    }, [], []), options.json);
+}
+function printSpawnFailed(io, options, error, sessionId) {
+    printResult(io, fail('worktree.spawn', 'SPAWN_FAILED', getErrorMessage(error), { rid: options.rid, role: options.role, sessionId }, [
+        'Verify `git worktree add` succeeded (output above).',
+        'If the lease file was NOT written, retry; the lease directory is .peaks/_runtime/<sid>/worktree-leases/.',
+        'For an existing branch, pass --branch <name> explicitly (the spawn refuses to overwrite an active branch).'
+    ]), options.json);
+    process.exitCode = 1;
+}
+function runSpawn(options, io) {
+    const projectRoot = resolveProjectRoot(options);
+    const sessionId = resolveSessionId(options, projectRoot);
+    try {
+        const leaseId = generateLeaseId();
+        const now = Date.now();
+        const ttlMs = resolveTtlMs(options.ttl, options.role);
+        const branch = options.branch ?? deriveBranch(options.rid);
+        const wtPath = worktreePath(joinPathSession(projectRoot, sessionId), leaseId);
+        const lease = finalizeLease({
+            leaseId,
+            rid: options.rid,
+            role: options.role,
+            path: wtPath,
+            branch,
+            createdAt: now,
+            expiresAt: now + ttlMs,
+            purpose: options.purpose
+        });
+        // Run `git worktree add` from the project root. The PreToolUse hook
+        // (Part 2 of this slice) will consult the lease file we just wrote
+        // and authorize this very `git worktree add`; for Part 1 we still
+        // require a current `peaks worktree auth grant` token to remain
+        // consistent with the slice-027 hard gate contract.
+        execSync(`git worktree add "${wtPath}" -b "${branch}"`, {
+            cwd: projectRoot,
+            stdio: 'pipe',
+            encoding: 'utf8',
+            windowsHide: true
+        });
+        atomicWriteJson(leaseFilePath(joinPathSession(projectRoot, sessionId), leaseId), lease);
+        // Part 4.A: emit spawn metric (fire-and-forget; never blocks).
+        emitLeaseEvent({
+            sessionId,
+            projectRoot,
+            kind: 'spawn',
+            leaseId,
+            rid: options.rid,
+            role: options.role
+        });
+        printSpawnOk(io, options, { lease, sessionId, projectRoot, ttlMs, wtPath, branch });
+    }
+    catch (error) {
+        printSpawnFailed(io, options, error, sessionId);
+    }
+}
+export function registerWorktreeLeaseSpawnCommand(auth, io) {
+    addJsonOption(auth
+        .command('spawn')
+        .description(SPAWN_DESCRIPTION)
+        .requiredOption('--rid <rid>', 'peaks request id the lease is associated with')
+        .requiredOption('--role <role>', 'sub-agent role (rd | qa | ui | sc | prd | general-purpose)')
+        .requiredOption('--purpose <text>', 'why this worktree was spawned (audit log)')
+        .option('--ttl <ms>', SPAWN_TTL_DESCRIPTION)
+        .option('--branch <name>', 'git branch name (default: derived from rid)')
+        .option('--session <sid>', 'override session id')
+        .option('--project <path>', 'project root (default: findProjectRoot(cwd))')).action((options) => runSpawn(options, io));
+}

package/dist/cli/commands/worktree-lease-status-command.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `peaks worktree lease-status` — show one lease in detail.
+ *
+ * Extracted verbatim from `worktree-lease-commands.ts` (mechanical move of
+ * the `.action()` body). The lease-file failures route through the shared
+ * `loadLeaseOrStop`; the computed `live` flag, the on-disk path
+ * diagnostics and the ok/fail envelopes are unchanged.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerWorktreeLeaseStatusCommand(auth: Command, io: ProgramIO): void;

package/dist/cli/commands/worktree-lease-status-command.js

@@ -0,0 +1,86 @@
+/**
+ * `peaks worktree lease-status` — show one lease in detail.
+ *
+ * Extracted verbatim from `worktree-lease-commands.ts` (mechanical move of
+ * the `.action()` body). The lease-file failures route through the shared
+ * `loadLeaseOrStop`; the computed `live` flag, the on-disk path
+ * diagnostics and the ok/fail envelopes are unchanged.
+ */
+import { fail, ok } from 'peaks-loop-shared/result';
+import { existsSync, statSync } from 'node:fs';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { isLeaseActive, leaseFilePath } from '../../services/worktree/worktree-lease.js';
+import { loadLeaseOrStop } from './worktree-lease-load.js';
+import { joinPathSession, resolveProjectRoot, resolveSessionId } from './worktree-lease-session.js';
+const LEASE_STATUS_DESCRIPTION = 'Show one lease in detail: full lease record + computed `live` flag (active AND not past ' +
+    'expiry) + path/branch/path-exists-on-disk diagnostics. Use this when triaging why a ' +
+    'sub-agent cannot write to a worktree.';
+const STATUS_MISSING_HINTS = ['Run `peaks worktree list` to inspect available leases.'];
+const STATUS_INVALID_HINTS = ['Delete the malformed lease file manually and re-spawn.'];
+/** Whether the lease path is present on disk and is a directory. */
+function inspectLeasePath(leasePath) {
+    const pathExists = existsSync(leasePath);
+    if (!pathExists)
+        return { pathExists, pathIsDirectory: false };
+    try {
+        return { pathExists, pathIsDirectory: statSync(leasePath).isDirectory() };
+    }
+    catch {
+        return { pathExists, pathIsDirectory: false };
+    }
+}
+function printLeaseStatusOk(io, options, ctx) {
+    const { lease, sessionId, projectRoot } = ctx;
+    const now = Date.now();
+    const { pathExists, pathIsDirectory } = inspectLeasePath(lease.path);
+    const live = isLeaseActive(lease, now);
+    printResult(io, ok('worktree.lease-status', {
+        sessionId,
+        projectRoot,
+        file: '.peaks/_runtime/' + sessionId + '/worktree-leases/' + lease.leaseId + '.json',
+        lease,
+        live,
+        diagnostics: {
+            now,
+            remainingMs: lease.expiresAt - now,
+            pathExists,
+            pathIsDirectory
+        }
+    }, [], [
+        `Lease ${lease.leaseId} is ${live ? 'LIVE' : 'NOT LIVE'} ` +
+            `(status=${lease.status}, remaining=${lease.expiresAt - now}ms).`,
+        `Worktree path ${lease.path} ${pathExists ? (pathIsDirectory ? 'exists (dir)' : 'exists (NOT a dir)') : 'MISSING'}.`
+    ]), options.json);
+}
+function printLeaseStatusFailed(io, options, err, sessionId) {
+    printResult(io, fail('worktree.lease-status', 'STATUS_FAILED', getErrorMessage(err), { leaseId: options.leaseId, sessionId }, ['Re-run after fixing the failure (see cause in the error message).']), options.json);
+    process.exitCode = 1;
+}
+function runLeaseStatus(options, io) {
+    const projectRoot = resolveProjectRoot(options);
+    const sessionId = resolveSessionId(options, projectRoot);
+    try {
+        const file = leaseFilePath(joinPathSession(projectRoot, sessionId), options.leaseId);
+        const loaded = loadLeaseOrStop(io, options, {
+            command: 'worktree.lease-status',
+            file,
+            hints: { missing: STATUS_MISSING_HINTS, invalid: STATUS_INVALID_HINTS }
+        });
+        if (loaded.stop) {
+            process.exitCode = 1;
+            return;
+        }
+        printLeaseStatusOk(io, options, { lease: loaded.lease, sessionId, projectRoot });
+    }
+    catch (err) {
+        printLeaseStatusFailed(io, options, err, sessionId);
+    }
+}
+export function registerWorktreeLeaseStatusCommand(auth, io) {
+    addJsonOption(auth
+        .command('lease-status')
+        .description(LEASE_STATUS_DESCRIPTION)
+        .requiredOption('--lease-id <id>', 'lease id to inspect')
+        .option('--session <sid>', 'override session id')
+        .option('--project <path>', 'project root (default: findProjectRoot(cwd))')).action((options) => runLeaseStatus(options, io));
+}

package/dist/cli/commands/worktree-lease-store.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Shared lease-store reader for the two sweep-style commands (`list`, `gc`).
+ *
+ * Both enumerate the session's lease directory through the pure
+ * `listLeasesSync` helper with the same real-fs bindings, and both render
+ * the same `Malformed lease: <file> (<error>)` warning line per unreadable
+ * file. Extracted verbatim from `worktree-lease-commands.ts`.
+ */
+import { type LeaseListResult } from '../../services/worktree/worktree-lease.js';
+export interface LeaseStoreSnapshot {
+    storeDir: string;
+    result: LeaseListResult;
+}
+export declare function loadLeaseStore(projectRoot: string, sessionId: string): LeaseStoreSnapshot;
+/** One warning line per malformed lease file skipped by the store reader. */
+export declare function malformedLeaseWarnings(errors: ReadonlyArray<{
+    file: string;
+    error: string;
+}>): string[];

package/dist/cli/commands/worktree-lease-store.js

@@ -0,0 +1,24 @@
+/**
+ * Shared lease-store reader for the two sweep-style commands (`list`, `gc`).
+ *
+ * Both enumerate the session's lease directory through the pure
+ * `listLeasesSync` helper with the same real-fs bindings, and both render
+ * the same `Malformed lease: <file> (<error>)` warning line per unreadable
+ * file. Extracted verbatim from `worktree-lease-commands.ts`.
+ */
+import { existsSync, readdirSync, readFileSync as readFileSyncNode } from 'node:fs';
+import { leaseStoreDir, listLeasesSync } from '../../services/worktree/worktree-lease.js';
+import { joinPathSession } from './worktree-lease-session.js';
+export function loadLeaseStore(projectRoot, sessionId) {
+    const storeDir = leaseStoreDir(joinPathSession(projectRoot, sessionId));
+    const result = listLeasesSync(storeDir, {
+        readdir: (p) => readdirSync(p),
+        readFile: (p) => readFileSyncNode(p, 'utf8'),
+        existsSync: (p) => existsSync(p)
+    });
+    return { storeDir, result };
+}
+/** One warning line per malformed lease file skipped by the store reader. */
+export function malformedLeaseWarnings(errors) {
+    return errors.map((e) => `Malformed lease: ${e.file} (${e.error})`);
+}

package/dist/cli/program.js

@@ -8,6 +8,7 @@ import { registerWorkflowCommands } from './commands/workflow-commands.js';
 import { registerCapabilityWorkerConfigAndSCCommands } from './commands/capability-worker-config-sc-commands.js';
 import { registerSubAgentCommands } from './commands/sub-agent-commands.js';
 import { registerLeaseMetricsCommand } from './commands/lease-metrics-commands.js';
+import { registerMcpCommands } from './commands/mcp-commands.js';
 import { registerLeaseStatsCommand } from './commands/lease-stats-commands.js';
 import { registerContainerCommand } from './commands/container-commands.js';
 import { registerVmCommand } from './commands/vm-commands.js';
@@ -197,6 +198,10 @@ Run peaks (no arguments) for a quickstart. You likely want one of:
     registerVmCommand(program, io);
     registerCronCommand(program, io);
     registerCronSchedulerCommand(program, io);
+    // The read-only MCP surface's command family. `serve` spawns the server
+    // module by path rather than importing it, so `src/services/mcp/` stays
+    // deletable (see the header of `mcp-commands.ts`).
+    registerMcpCommands(program, io);
     // Auto-route the remaining 60+ commands after the orchestrators so the
     // lazy `skill` parent (used by adapter-commands / sediment-commands)
     // finds the existing `peaks skill` group registered by

package/dist/services/distribution/mcp-install-runner.d.ts

@@ -0,0 +1,21 @@
+import type { McpInstallCommand, McpInstallOutcome, McpInstallRunner } from './mcp-install.js';
+/**
+ * Ceiling on ONE harness command. `spawnSync` without `timeout` has no ceiling
+ * at all, and the failure it lets through is measured, not hypothetical: a
+ * real harness binary on this host starts and then does not return within 25 s.
+ * Unbounded, that blocks `peaks mcp install` in the foreground forever. Same
+ * class the MCP CLI executor bounds (`cli-executor.ts`), set to twice its 15 s
+ * because the child is the harness's binary and its startup is its own to
+ * spend. A plan is at most three commands, so the install is bounded at 3x.
+ */
+export declare const MCP_INSTALL_TIMEOUT_MS = 30000;
+/**
+ * One harness command, with the deadline applied. `windowsHide` is the tree's
+ * spawn contract: a CLI that briefly runs a harness must not flash a console
+ * window on a desktop OS. `timeoutMs` is a parameter only so a test can watch
+ * the deadline fire without waiting out the production value — callers want
+ * `spawnMcpInstallRunner`, which fixes it.
+ */
+export declare function spawnMcpInstallCommand(command: McpInstallCommand, timeoutMs?: number): McpInstallOutcome;
+/** The production runner: the deadline above, and nothing else left to decide. */
+export declare const spawnMcpInstallRunner: McpInstallRunner;

package/dist/services/distribution/mcp-install-runner.js

@@ -0,0 +1,59 @@
+// src/services/distribution/mcp-install-runner.ts
+//
+// The production runner behind the vendor-neutral MCP registration engine
+// (`mcp-install.ts`): it runs one harness command under a deadline and reports
+// what the process said. It lives in its own module only so the engine keeps its
+// size; the engine RE-EXPORTS it, so every caller still imports it from
+// `mcp-install.js` and no import path moved.
+//
+// THE FIELD THIS MODULE EXISTS FOR. A run that exits non-zero ANSWERED the
+// question — "no such registration" — and a run the deadline kills, or one that
+// never launches, did not: `answered: false` is the only place that distinction
+// is born, and it is what stops `peaks mcp uninstall` from reporting a hung
+// harness's scope as "nothing was there".
+import { spawnSync } from 'node:child_process';
+/**
+ * Ceiling on ONE harness command. `spawnSync` without `timeout` has no ceiling
+ * at all, and the failure it lets through is measured, not hypothetical: a
+ * real harness binary on this host starts and then does not return within 25 s.
+ * Unbounded, that blocks `peaks mcp install` in the foreground forever. Same
+ * class the MCP CLI executor bounds (`cli-executor.ts`), set to twice its 15 s
+ * because the child is the harness's binary and its startup is its own to
+ * spend. A plan is at most three commands, so the install is bounded at 3x.
+ */
+export const MCP_INSTALL_TIMEOUT_MS = 30_000;
+/**
+ * One harness command, with the deadline applied. `windowsHide` is the tree's
+ * spawn contract: a CLI that briefly runs a harness must not flash a console
+ * window on a desktop OS. `timeoutMs` is a parameter only so a test can watch
+ * the deadline fire without waiting out the production value — callers want
+ * `spawnMcpInstallRunner`, which fixes it.
+ */
+export function spawnMcpInstallCommand(command, timeoutMs = MCP_INSTALL_TIMEOUT_MS) {
+    const result = spawnSync(command.command, [...command.args], {
+        stdio: 'pipe',
+        windowsHide: true,
+        encoding: 'utf8',
+        timeout: timeoutMs
+    });
+    if (result.error !== undefined) {
+        // `spawnSync` kills the child at the deadline and reports its own timeout as
+        // ETIMEDOUT. A deadline and a launch failure are different facts, but they
+        // share the one that matters here: the harness never rendered a verdict.
+        const timedOut = result.error.code === 'ETIMEDOUT';
+        return {
+            ok: false,
+            answered: false,
+            detail: timedOut
+                ? `timed out after ${timeoutMs} ms and was killed: ${command.command} ${command.args.join(' ')}`
+                : result.error.message
+        };
+    }
+    if (result.status === 0) {
+        return { ok: true, detail: '' };
+    }
+    const stderr = (result.stderr ?? '').trim();
+    return { ok: false, detail: stderr.length > 0 ? stderr : `exit ${result.status ?? 'unknown'}` };
+}
+/** The production runner: the deadline above, and nothing else left to decide. */
+export const spawnMcpInstallRunner = (command) => spawnMcpInstallCommand(command);

package/dist/services/distribution/mcp-install.d.ts

@@ -0,0 +1,95 @@
+import type { IdeAdapter, IdeId } from '../ide/ide-types.js';
+import { type IdeMcpInstallProfile } from '../ide/ide-mcp-install-types.js';
+/** One process the plan wants run, as command + args. Never a joined string. */
+export interface McpInstallCommand {
+    readonly command: string;
+    readonly args: readonly string[];
+}
+/** What one operation is for, so a report can say which step did what. */
+export type McpInstallOperation = 'remove' | 'add';
+export interface McpInstallStep {
+    readonly operation: McpInstallOperation;
+    /** The scope this step acts on; the target scope for an `add`. */
+    readonly scope: string;
+    readonly command: McpInstallCommand;
+}
+/** What a runner says happened. `detail` is surfaced verbatim when it did not. */
+export interface McpInstallOutcome {
+    readonly ok: boolean;
+    readonly detail: string;
+    /**
+     * `false` only when the harness NEVER RENDERED A VERDICT — the deadline killed
+     * it, or it never launched. A non-zero exit answered ("no such registration"),
+     * so an absent value reads as `true`, as does every outcome that predates this
+     * field.
+     */
+    readonly answered?: boolean;
+}
+/** The seam: a test supplies one, the CLI supplies the spawning one below. */
+export type McpInstallRunner = (command: McpInstallCommand) => McpInstallOutcome;
+export interface McpInstallReport {
+    readonly serverName: string;
+    /** Scopes where the removal reported success — i.e. there was something to remove. */
+    readonly removed: readonly string[];
+    /** Scopes where the removal reported failure — normally "nothing was there". */
+    readonly absent: readonly string[];
+    /**
+     * Scopes whose removal never reached a verdict — the harness timed out or never
+     * launched — so it is neither `removed` nor honestly `absent`. Optional because
+     * the install sweep tolerates a failed removal (it is about to write) and never
+     * populates it; the uninstall sweep always does.
+     */
+    readonly unknown?: readonly string[];
+    readonly added: boolean;
+    readonly ok: boolean;
+    readonly detail: string;
+}
+/**
+ * The argv that launches THIS installation's read-only MCP server.
+ *
+ * An interpreter and an entry path, in array form: the same shape `mcp serve`
+ * spawns and the same one the read-only executor uses. A bare CLI name would be
+ * a `.cmd` shim on some platforms, and picking a spelling per platform is the
+ * branch this tree forbids — resolving the pair needs none.
+ */
+export declare function resolveMcpServerArgv(): readonly string[];
+/** The plan: one removal per declared scope, then the addition. Order is the contract. */
+export declare function buildMcpInstallPlan(profile: IdeMcpInstallProfile, serverArgv: readonly string[]): readonly McpInstallStep[];
+/** Every removal, then the addition. A failed removal is a fact, not a failure. */
+export declare function runMcpInstallPlan(profile: IdeMcpInstallProfile, serverArgv: readonly string[], runner: McpInstallRunner): McpInstallReport;
+/**
+ * The removal sweep on its own — what `uninstall` is, and all that it is.
+ *
+ * `exit 0` removed it, `exit != 0` answered "no" (absent, unchanged) — but a run the
+ * deadline killed, or one that never launched, ANSWERED NOTHING, and calling that
+ * "nothing was there" is the lie this sweep used to tell. Those scopes are `unknown`,
+ * and `ok` is false whenever any scope is unknown: with a scope the harness never
+ * spoke for, the removal is unconfirmed and the state is not known.
+ */
+export declare function runMcpUninstallPlan(profile: IdeMcpInstallProfile, serverArgv: readonly string[], runner: McpInstallRunner): McpInstallReport;
+/**
+ * One adapter's outcome. `skipped` is a FIRST-CLASS result and not an error: the
+ * install's contract with an adapter that declares no registration entry is
+ * silence, and a caller that has to distinguish "did nothing" from
+ * "failed" needs the distinction to be in the value, not in a log line.
+ */
+export type AdapterMcpInstallResult = {
+    readonly ideId: IdeId;
+    readonly skipped: true;
+    readonly reason: string;
+} | {
+    readonly ideId: IdeId;
+    readonly skipped: false;
+    readonly report: McpInstallReport;
+};
+export declare const NO_MCP_INSTALL_REASON = "adapter declares no mcpInstall profile";
+/** Register this adapter's harness, or report that there is nothing to register. */
+export declare function installMcpForAdapter(adapter: IdeAdapter, serverArgv: readonly string[], runner: McpInstallRunner): AdapterMcpInstallResult;
+/** The same, for the removal side. */
+export declare function uninstallMcpForAdapter(adapter: IdeAdapter, serverArgv: readonly string[], runner: McpInstallRunner): AdapterMcpInstallResult;
+/**
+ * The production runner and its deadline live in `mcp-install-runner.ts` — split
+ * out only to keep this engine within the file-size cap. They are re-exported, so
+ * the boundary is invisible: every caller still imports them from here.
+ */
+export { MCP_INSTALL_TIMEOUT_MS, spawnMcpInstallCommand, spawnMcpInstallRunner } from './mcp-install-runner.js';

package/dist/services/distribution/mcp-install.js

@@ -0,0 +1,179 @@
+// src/services/distribution/mcp-install.ts
+//
+// The vendor-neutral MCP registration engine (spec §8.3). It owns the SHAPE of
+// an install — delete every scope, then add — and owns no harness's spelling of
+// anything: the server key, the scopes and the argv come from the adapter's
+// `mcpInstall` profile, and the process that runs the argv is an injected
+// runner.
+//
+// WHY DELETE-THEN-ADD AND NOT "CHECK, THEN ADD IF ABSENT". The harness's own
+// register verb is not idempotent: the same name in the same scope fails, and
+// there is no `--force` and no `update` to reach for. A conditional add would
+// therefore have to be right about a state it cannot see — so the engine does
+// the one thing that is right in both states: it removes what is there (a
+// removal that finds nothing is tolerated) and then adds. That is also what
+// makes the install SEMANTICALLY idempotent: two runs produce the same argv in
+// the same order, so the registration left behind has the same CONTENT, even
+// though the second run performed operations the first one did too.
+//
+// WHY THE DELETE SWEEPS EVERY SCOPE. The entry can already exist in a scope the
+// install is not writing to — an earlier install, or a user who moved it. The
+// removal names a scope, and the harness fails on the wrong or empty one, so a
+// targeted delete would leave the old entry behind and the add would then fail
+// on the duplicate it left. Sweeping all declared scopes is the only version of
+// this that is correct for a state the engine cannot enumerate.
+//
+// WHAT "ONLY OURS" MEANS HERE. The engine never reads or writes the
+// harness's configuration file. It runs the harness's own removal and addition,
+// and the only key either of them names is the adapter's `serverName` — so no
+// other entry can be touched by construction. The honest limit of that
+// guarantee is the name itself: an entry the USER named the same thing is
+// indistinguishable from ours, and is the one case this cannot tell apart.
+//
+// NO HARNESS BRANCH, NO PLATFORM BRANCH. Every value is either the caller's or
+// the adapter's. `resolveMcpServerArgv` returns an interpreter and an entry path
+// for the same reason `cli-executor.ts` does: a shipped CLI name is a shim on
+// some platforms, and choosing between the two spellings would be the platform
+// branch this module is forbidden to contain.
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { assertMcpInstallProfile, expandMcpArgv } from '../ide/ide-mcp-install-types.js';
+/** `<packageRoot>` — this file's tree is `<root>/src/services/distribution` or `<root>/dist/…`. */
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+/**
+ * The argv that launches THIS installation's read-only MCP server.
+ *
+ * An interpreter and an entry path, in array form: the same shape `mcp serve`
+ * spawns and the same one the read-only executor uses. A bare CLI name would be
+ * a `.cmd` shim on some platforms, and picking a spelling per platform is the
+ * branch this tree forbids — resolving the pair needs none.
+ */
+export function resolveMcpServerArgv() {
+    return [process.execPath, join(PACKAGE_ROOT, 'bin', 'peaks.js'), 'mcp', 'serve'];
+}
+/** The plan: one removal per declared scope, then the addition. Order is the contract. */
+export function buildMcpInstallPlan(profile, serverArgv) {
+    assertMcpInstallProfile(profile);
+    const removals = profile.scopes.map((scope) => ({
+        operation: 'remove',
+        scope,
+        command: {
+            command: profile.removeArgv[0] ?? '',
+            args: expandMcpArgv(profile.removeArgv.slice(1), {
+                serverName: profile.serverName,
+                scope,
+                serverArgv
+            })
+        }
+    }));
+    const addition = {
+        operation: 'add',
+        scope: profile.targetScope,
+        command: {
+            command: profile.addArgv[0] ?? '',
+            args: expandMcpArgv(profile.addArgv.slice(1), {
+                serverName: profile.serverName,
+                scope: profile.targetScope,
+                serverArgv
+            })
+        }
+    };
+    return [...removals, addition];
+}
+/** Every removal, then the addition. A failed removal is a fact, not a failure. */
+export function runMcpInstallPlan(profile, serverArgv, runner) {
+    const plan = buildMcpInstallPlan(profile, serverArgv);
+    const removed = [];
+    const absent = [];
+    let detail = '';
+    for (const step of plan) {
+        const outcome = runner(step.command);
+        if (step.operation === 'remove') {
+            if (outcome.ok)
+                removed.push(step.scope);
+            else
+                absent.push(step.scope);
+            continue;
+        }
+        if (!outcome.ok) {
+            return {
+                serverName: profile.serverName,
+                removed,
+                absent,
+                added: false,
+                ok: false,
+                detail: `the registration was not written: ${outcome.detail}`
+            };
+        }
+        detail = `registered in scope '${step.scope}'`;
+    }
+    return { serverName: profile.serverName, removed, absent, added: true, ok: true, detail };
+}
+/**
+ * The removal sweep on its own — what `uninstall` is, and all that it is.
+ *
+ * `exit 0` removed it, `exit != 0` answered "no" (absent, unchanged) — but a run the
+ * deadline killed, or one that never launched, ANSWERED NOTHING, and calling that
+ * "nothing was there" is the lie this sweep used to tell. Those scopes are `unknown`,
+ * and `ok` is false whenever any scope is unknown: with a scope the harness never
+ * spoke for, the removal is unconfirmed and the state is not known.
+ */
+export function runMcpUninstallPlan(profile, serverArgv, runner) {
+    const plan = buildMcpInstallPlan(profile, serverArgv).filter((step) => step.operation === 'remove');
+    const removed = [];
+    const absent = [];
+    const unknown = [];
+    for (const step of plan) {
+        const outcome = runner(step.command);
+        if (outcome.ok)
+            removed.push(step.scope);
+        else if (outcome.answered === false)
+            unknown.push(step.scope);
+        else
+            absent.push(step.scope);
+    }
+    return {
+        serverName: profile.serverName,
+        removed,
+        absent,
+        unknown,
+        added: false,
+        ok: unknown.length === 0,
+        detail: unknown.length > 0
+            ? `the '${profile.serverName}' removal is unconfirmed: ${unknown.length} scope(s) never answered`
+            : removed.length === 0
+                ? `no '${profile.serverName}' registration was present in any declared scope`
+                : `removed '${profile.serverName}' from ${removed.length} scope(s)`
+    };
+}
+export const NO_MCP_INSTALL_REASON = 'adapter declares no mcpInstall profile';
+/** Register this adapter's harness, or report that there is nothing to register. */
+export function installMcpForAdapter(adapter, serverArgv, runner) {
+    const profile = adapter.mcpInstall;
+    if (profile === undefined) {
+        return { ideId: adapter.id, skipped: true, reason: NO_MCP_INSTALL_REASON };
+    }
+    return {
+        ideId: adapter.id,
+        skipped: false,
+        report: runMcpInstallPlan(profile, serverArgv, runner)
+    };
+}
+/** The same, for the removal side. */
+export function uninstallMcpForAdapter(adapter, serverArgv, runner) {
+    const profile = adapter.mcpInstall;
+    if (profile === undefined) {
+        return { ideId: adapter.id, skipped: true, reason: NO_MCP_INSTALL_REASON };
+    }
+    return {
+        ideId: adapter.id,
+        skipped: false,
+        report: runMcpUninstallPlan(profile, serverArgv, runner)
+    };
+}
+/**
+ * The production runner and its deadline live in `mcp-install-runner.ts` — split
+ * out only to keep this engine within the file-size cap. They are re-exported, so
+ * the boundary is invisible: every caller still imports them from here.
+ */
+export { MCP_INSTALL_TIMEOUT_MS, spawnMcpInstallCommand, spawnMcpInstallRunner } from './mcp-install-runner.js';