@bridge_gpt/mcp-server 0.2.30 → 0.2.31

package/build/command-assets-doctor.js

@@ -0,0 +1,72 @@
+/**
+ * Read-only worktree Claude command-asset diagnostic (doctor-only, BAPI-664).
+ *
+ * Reports whether the current worktree contains every packaged Claude slash
+ * command under `.claude/commands/`. This probe ONLY reads command paths — it
+ * never writes, creates directories, invokes Git, spawns a process, compares or
+ * reports command file CONTENTS, or leaks raw exceptions. A committed customer
+ * version of a command counts as present regardless of its contents (the command
+ * bundle is fill-only and never refreshed), so the probe checks presence /
+ * readability, not freshness. The sole injected dependencies are `readFile` and
+ * `platform`.
+ */
+import path from "path";
+import { COMMANDS } from "./commands.generated.js";
+/** Stable user-facing relative location shown in every detail string. */
+const COMMAND_DIR_LABEL = ".claude/commands/";
+/** How many missing filenames to list before summarizing the remainder. */
+const MAX_LISTED_MISSING = 5;
+/** The `path` API for the target platform (win32 vs posix). */
+function pathApiForPlatform(platform) {
+    return platform === "win32" ? path.win32 : path.posix;
+}
+/** Render a bounded, deterministic list of missing filenames (generated order). */
+function formatMissing(missing) {
+    if (missing.length <= MAX_LISTED_MISSING) {
+        return missing.join(", ");
+    }
+    const shown = missing.slice(0, MAX_LISTED_MISSING).join(", ");
+    return `${shown} (+${missing.length - MAX_LISTED_MISSING} more)`;
+}
+/**
+ * Probe whether `<worktreeRoot>/.claude/commands/` contains every packaged
+ * command asset. A `readFile` that resolves counts the asset as present (any
+ * contents); a rejection (missing OR unreadable) counts it as absent. Returns
+ * `found: true` only when every packaged command filename is present, otherwise a
+ * `found: false` result with a concise, actionable, secret-free detail that
+ * points the operator back to `start-tickets` (never to manually copying or
+ * committing generated files).
+ */
+export async function probeWorktreeCommandAssets(worktreeRoot, deps) {
+    const filenames = Object.keys(COMMANDS);
+    if (filenames.length === 0) {
+        return {
+            found: false,
+            detail: "Packaged command bundle is empty — reinstall or rebuild the MCP server package.",
+        };
+    }
+    const api = pathApiForPlatform(deps.platform);
+    const commandsDir = api.join(worktreeRoot, ".claude", "commands");
+    const missing = [];
+    for (const filename of filenames) {
+        try {
+            await deps.readFile(api.join(commandsDir, filename));
+        }
+        catch {
+            // Missing OR unreadable — either way the asset is not usable. We never
+            // surface the underlying error (it can carry paths / exception text).
+            missing.push(filename);
+        }
+    }
+    if (missing.length === 0) {
+        return {
+            found: true,
+            detail: `${filenames.length} packaged command assets present under ${COMMAND_DIR_LABEL}`,
+        };
+    }
+    return {
+        found: false,
+        detail: `${missing.length} of ${filenames.length} packaged command assets missing or unreadable under ` +
+            `${COMMAND_DIR_LABEL} (${formatMissing(missing)}). Re-run start-tickets to provision them.`,
+    };
+}

package/build/command-provisioning.js

@@ -0,0 +1,157 @@
+/**
+ * Shared Claude command-asset provisioning (BAPI-664).
+ *
+ * Materializes the FULL packaged command bundle (`COMMANDS` from
+ * `commands.generated.ts`, the single source of truth) into a worktree's
+ * `.claude/commands/` directory so every packaged slash command is runnable from
+ * a freshly created worktree — whether spawned by the interactive `start-tickets`
+ * orchestration or by the headless conductor executor.
+ *
+ * Semantics (locked ticket decisions):
+ *   - FULL bundle: every entry in `COMMANDS` is provisioned.
+ *   - FILL-ONLY: a command file that already exists is treated as a customer asset
+ *     and left byte-for-byte unchanged — its contents are never read-compared or
+ *     refreshed. Only a missing (`ENOENT`) file is created. There is no refresh
+ *     flag.
+ *   - Repository-common exclude: after materialization, `.claude/commands/` is
+ *     added to the worktree's Git `info/exclude` (resolved via Git for linked
+ *     worktrees). `info/exclude` lives in the common Git directory shared by
+ *     sibling worktrees, and an ignore rule never hides an already-tracked file,
+ *     so this common scope is safe.
+ *
+ * All filesystem + command access is dependency-injected so this is unit-testable
+ * with no real I/O. This module NEVER imports `node:fs` / `child_process`, writes
+ * to stdout/stderr, or registers an MCP tool — failures are surfaced structurally
+ * and rendered by the caller's existing orchestration boundary.
+ */
+import path from "path";
+import { COMMANDS } from "./commands.generated.js";
+import { ensureGitInfoExcluded } from "./git-ignore-utils.js";
+/** The exact exclude entry appended for the command directory (POSIX-relative). */
+const COMMAND_DIR_EXCLUDE_ENTRY = ".claude/commands/";
+/** Bounded, secret-free error surfaced when the packaged bundle is empty. */
+const EMPTY_BUNDLE_ERROR = "Command provisioning failed: the packaged command bundle is empty — reinstall or rebuild the MCP server package.";
+/**
+ * Resolve the path API for the target platform. Local (not imported from
+ * `start-tickets.ts`) to avoid a runtime import cycle.
+ */
+export function pathApiForCommandProvisioningPlatform(platform) {
+    return platform === "win32" ? path.win32 : path.posix;
+}
+/** True only for a Node `ENOENT` (missing-file) error. */
+function isEnoentError(err) {
+    return (typeof err === "object" &&
+        err !== null &&
+        err.code === "ENOENT");
+}
+/**
+ * Fill every MISSING packaged command asset into `<worktreeRoot>/.claude/commands/`
+ * without touching any existing customer file, then ensure `.claude/commands/` is
+ * added to the worktree's Git exclude. Returns a structured result; never throws
+ * for an expected filesystem/Git failure, and never leaks raw exception text,
+ * command output, or file contents.
+ */
+export async function provisionCommandsForWorktree(worktreeRoot, deps) {
+    const api = pathApiForCommandProvisioningPlatform(deps.platform);
+    const normalizedRoot = api.isAbsolute(worktreeRoot)
+        ? api.normalize(worktreeRoot)
+        : api.resolve(deps.cwd, worktreeRoot);
+    const commandsDir = api.join(normalizedRoot, ".claude", "commands");
+    const entries = Object.entries(COMMANDS);
+    if (entries.length === 0) {
+        // No runnable slash commands could ever be provisioned — fail loudly rather
+        // than reporting a hollow success.
+        return { ok: false, error: EMPTY_BUNDLE_ERROR };
+    }
+    // Phase 1 — discover which packaged files are absent. A successful read means
+    // the customer already owns that asset; leave it untouched. Only ENOENT counts
+    // as "missing"; any other read failure is a bounded, secret-free error.
+    let fillError = null;
+    const missing = [];
+    for (const [filename, content] of entries) {
+        const target = api.join(commandsDir, filename);
+        try {
+            await deps.readFile(target);
+        }
+        catch (err) {
+            if (isEnoentError(err)) {
+                missing.push([filename, content]);
+            }
+            else {
+                fillError = `Command provisioning failed: could not read existing command asset '${filename}'.`;
+                break;
+            }
+        }
+    }
+    // Phase 2 — create the directory (only when something is missing) and write the
+    // absent files in bundle order using the packaged string unchanged.
+    if (!fillError && missing.length > 0) {
+        try {
+            await deps.mkdir(commandsDir, { recursive: true });
+            for (const [filename, content] of missing) {
+                await deps.writeFile(api.join(commandsDir, filename), content);
+            }
+        }
+        catch {
+            fillError =
+                "Command provisioning failed: could not write one or more packaged command assets.";
+        }
+    }
+    // Phase 3 — ALWAYS attempt exclusion, even after a partial or failed fill, so
+    // partially bootstrapped files are never left visible to Git. The primary fill
+    // failure is preserved if both the fill and the exclusion fail.
+    let excludeError = null;
+    try {
+        await ensureGitInfoExcluded(normalizedRoot, COMMAND_DIR_EXCLUDE_ENTRY, {
+            readFile: deps.readFile,
+            writeFile: deps.writeFile,
+            mkdir: deps.mkdir,
+            runCommand: deps.runCommand,
+            platform: deps.platform,
+        });
+    }
+    catch {
+        excludeError =
+            "Command provisioning failed: could not add '.claude/commands/' to the worktree Git exclude file.";
+    }
+    if (fillError)
+        return { ok: false, error: fillError };
+    if (excludeError)
+        return { ok: false, error: excludeError };
+    return { ok: true };
+}
+/**
+ * Provision command assets for every eligible (`created`, path-bearing) row, in
+ * input order, serially. A non-`created` row or a `created` row without a usable
+ * path is returned unchanged. A per-worktree bootstrap failure marks ONLY that
+ * row `spawn-failed` (with a secret-free `Command provisioning failed: …` error)
+ * so the affected worker is skipped by all later spawn logic while its siblings
+ * proceed. A defensive per-row catch guarantees one unexpected failure cannot
+ * abort later rows or reject the overall call.
+ */
+export async function provisionCommandsForCreatedWorktrees(rows, deps) {
+    const out = [];
+    for (const row of rows) {
+        if (row.status !== "created" || !row.path) {
+            out.push(row);
+            continue;
+        }
+        try {
+            const result = await provisionCommandsForWorktree(row.path, deps);
+            if (result.ok) {
+                out.push(row);
+            }
+            else {
+                out.push({ ...row, status: "spawn-failed", error: result.error });
+            }
+        }
+        catch {
+            out.push({
+                ...row,
+                status: "spawn-failed",
+                error: "Command provisioning failed: an unexpected error occurred while bootstrapping worktree command assets.",
+            });
+        }
+    }
+    return out;
+}

package/build/executor/test-clock.js

@@ -73,7 +73,9 @@ export function makeFakeExecutorDeps(clock, overrides = {}) {
             throw new Error("spawnProcess not configured for this test");
         },
         readFile: async () => {
-            throw new Error("ENOENT");
+            // Mirror real fs/promises: a missing-file rejection carries code "ENOENT"
+            // (so BAPI-664 command provisioning treats absent files as fillable).
+            throw Object.assign(new Error("ENOENT"), { code: "ENOENT" });
         },
         writeFile: async () => { },
         mkdir: async () => undefined,

package/build/executor/worktree.js

@@ -9,6 +9,7 @@
 import { fetchAndResolveBaseSha } from "../base-ref.js";
 import { commandSucceeded } from "../start-tickets-prereqs.js";
 import { createWorktreeForTicket } from "../worktree-core.js";
+import { provisionCommandsForWorktree } from "../command-provisioning.js";
 /**
  * Resolve the branch for a real spawn job: `expected_branch` wins; else
  * `feature/<ticket_key>`; else a structured contract failure.
@@ -35,6 +36,34 @@ function toWorktreeCoreDeps(deps) {
         cwd: deps.cwd,
     };
 }
+/** Build the command-provisioning boundary from the executor deps (BAPI-664). */
+function toCommandProvisioningDeps(deps) {
+    return {
+        readFile: deps.readFile,
+        writeFile: deps.writeFile,
+        mkdir: deps.mkdir,
+        runCommand: deps.runCommand,
+        platform: deps.platform,
+        cwd: deps.cwd,
+    };
+}
+/**
+ * Finalize a resolved executor worktree by bootstrapping the packaged Claude
+ * command assets into it (BAPI-664) BEFORE the worker process is handed the
+ * worktree path. A provisioning failure is mapped into the executor's existing
+ * bounded non-success worktree result so the affected worker is not launched with
+ * a missing slash command, while the executor process stays available for later
+ * jobs. On success the existing successful ensure-worktree result shape is
+ * preserved unchanged. Errors stay secret-free (no raw filesystem exception, Git
+ * output, or command contents).
+ */
+async function finalizeExecutorWorktree(worktreePath, branch, deps) {
+    const provisioned = await provisionCommandsForWorktree(worktreePath, toCommandProvisioningDeps(deps));
+    if (!provisioned.ok) {
+        return { ok: false, error: provisioned.error };
+    }
+    return { ok: true, worktreePath, branch };
+}
 /**
  * Ensure the worktree for a job exists, delegating to the shared Worktrunk
  * primitive. A create failure is returned as a structured failure that the job
@@ -92,7 +121,7 @@ export async function ensureExecutorWorktree(job, options, deps, policy = {}) {
         // (= `origin/<branch>`) inside the primitive, so both land at origin.
         { freshenFromOrigin: originRef });
         if (row.status === "created" && typeof row.path === "string") {
-            return { ok: true, worktreePath: row.path, branch };
+            return finalizeExecutorWorktree(row.path, branch, deps);
         }
         return { ok: false, error: row.error ?? `worktree creation failed for branch '${branch}'` };
     }
@@ -117,7 +146,7 @@ export async function ensureExecutorWorktree(job, options, deps, policy = {}) {
     const baseSha = resolvedBase.base_sha;
     const row = await createWorktreeForTicket(toWorktreeCoreDeps(deps), key, { [key]: branch }, options.worktrunkBinary, baseSha, guardStaleWorktree, { alignExistingBranchTo: baseSha, verifyHeadMatches: baseSha });
     if (row.status === "created" && typeof row.path === "string") {
-        return { ok: true, worktreePath: row.path, branch };
+        return finalizeExecutorWorktree(row.path, branch, deps);
     }
     return { ok: false, error: row.error ?? `worktree creation failed for branch '${branch}'` };
 }

package/build/git-ignore-utils.js

@@ -4,22 +4,49 @@
  * Two idempotent, exact-line appenders:
  *   - `ensureGitignored` writes the tracked `<cwd>/.gitignore` (shared with the
  *     existing `--init` scaffolding behavior).
- *   - `ensureGitInfoExcluded` writes the UNtracked `<worktreeRoot>/.git/info/exclude`,
- *     used for Tier-3 file credentials that must never enter version control and
- *     must never touch the tracked `.gitignore`.
+ *   - `ensureGitInfoExcluded` writes the UNtracked, repository-common
+ *     `info/exclude`, used for Tier-3 file credentials and (BAPI-664) bootstrapped
+ *     Claude command assets that must never enter version control and must never
+ *     touch the tracked `.gitignore`.
+ *
+ * Linked-worktree note (BAPI-664): a worktree created by `git worktree add` (as
+ * Worktrunk does) does NOT contain a `.git` directory — it contains a `.git`
+ * *file* that points at the common Git directory. So the historical
+ * `<worktreeRoot>/.git/info/exclude` join is WRONG for a linked worktree. When a
+ * list-based `runCommand` and `platform` are injected, this helper asks Git for
+ * the authoritative path with `git rev-parse --git-path info/exclude` (relative
+ * to the worktree root); `info/exclude` lives in the common Git directory shared
+ * by all sibling worktrees, and an ignore rule never hides an already-tracked
+ * file, so the shared scope is safe. When `runCommand`/`platform` are absent the
+ * helper falls back to the legacy `<worktreeRoot>/.git/info/exclude` join, which
+ * remains correct for a main repository whose `.git` is a real directory (the
+ * SFCC dw.json caller relies on this).
  *
  * Both are dependency-injected so they are unit-testable without real I/O, and
- * neither ever includes credential file contents in an error.
+ * neither ever includes credential file contents — or raw Git/command output —
+ * in an error.
  */
 import path from "path";
+/** The `path` API for the target platform (win32 vs posix). */
+function pathApiForPlatform(platform) {
+    return platform === "win32" ? path.win32 : path.posix;
+}
 /** True when `content` already contains `entry` as its own exact (trimmed) line. */
 function hasExactLine(content, entry) {
     return content.split("\n").some((line) => line.trim() === entry);
 }
-/** Append `entry` to `content`, inserting a separating newline only if needed. */
+/** Detect the newline convention of existing content (CRLF wins if present). */
+function detectNewline(content) {
+    return /\r\n/.test(content) ? "\r\n" : "\n";
+}
+/**
+ * Append `entry` to `content`, inserting a separating newline only if needed and
+ * using the file's own newline convention (CRLF preserved when already present).
+ */
 function appendLine(content, entry) {
-    const separator = content.length > 0 && !content.endsWith("\n") ? "\n" : "";
-    return content + separator + entry + "\n";
+    const newline = detectNewline(content);
+    const separator = content.length > 0 && !content.endsWith("\n") ? newline : "";
+    return content + separator + entry + newline;
 }
 /**
  * Idempotently ensure `filePath` is listed in `<cwd>/.gitignore`. An absolute
@@ -41,20 +68,46 @@ export async function ensureGitignored(cwd, filePath, deps) {
     await deps.writeFile(gitignorePath, appendLine(content, entry));
 }
 /**
- * Idempotently ensure `relativePath` is listed in the worktree's local-only
- * `<worktreeRoot>/.git/info/exclude`. Creates `<worktreeRoot>/.git/info` if it
- * does not exist. Matching is exact-line (so `dw.json` is not treated as present
- * just because `dw.json.bak` exists). Never edits the tracked `.gitignore`.
+ * Resolve the worktree's `info/exclude` path. With an injected `runCommand` +
+ * `platform`, ask Git (`git rev-parse --git-path info/exclude`) so linked
+ * worktrees resolve to the common Git directory; a Git failure or empty path
+ * throws a bounded, output-free error. Without them, fall back to the legacy
+ * `<worktreeRoot>/.git/info/exclude` join (correct for a main repository).
  */
-export async function ensureGitInfoExcluded(worktreeRoot, relativePath, deps) {
+async function resolveInfoExcludeLocation(worktreeRoot, deps) {
+    if (deps.runCommand && deps.platform) {
+        const api = pathApiForPlatform(deps.platform);
+        const result = await deps.runCommand("git", ["rev-parse", "--git-path", "info/exclude"], { cwd: worktreeRoot });
+        if (result.exitCode !== 0) {
+            // Never surface raw Git stdout/stderr (it can echo paths / tokens).
+            throw new Error("Failed to resolve the worktree info/exclude path via 'git rev-parse --git-path'.");
+        }
+        const raw = result.stdout.trim();
+        if (raw.length === 0) {
+            throw new Error("'git rev-parse --git-path info/exclude' returned an empty path.");
+        }
+        const excludePath = api.isAbsolute(raw) ? api.normalize(raw) : api.resolve(worktreeRoot, raw);
+        return { excludePath, infoDir: api.dirname(excludePath) };
+    }
     const infoDir = path.join(worktreeRoot, ".git", "info");
-    const excludePath = path.join(infoDir, "exclude");
+    return { excludePath: path.join(infoDir, "exclude"), infoDir };
+}
+/**
+ * Idempotently ensure `relativePath` is listed in the worktree's local-only,
+ * repository-common `info/exclude`. Resolves the exclude path via Git for linked
+ * worktrees (see module docstring) and creates its parent directory if missing.
+ * Matching is exact-line (so `dw.json` is not treated as present just because
+ * `dw.json.bak` exists) and the append respects the file's newline convention.
+ * Never edits the tracked `.gitignore`.
+ */
+export async function ensureGitInfoExcluded(worktreeRoot, relativePath, deps) {
+    const { excludePath, infoDir } = await resolveInfoExcludeLocation(worktreeRoot, deps);
     let content = "";
     try {
         content = await deps.readFile(excludePath);
     }
     catch {
-        /* exclude file (or .git/info) doesn't exist yet */
+        /* exclude file (or info dir) doesn't exist yet */
     }
     if (hasExactLine(content, relativePath))
         return;