@bridge_gpt/mcp-server 0.2.53 → 0.2.55

package/build/implement-epic/spawn.js

@@ -0,0 +1,113 @@
+/**
+ * Secret-free agent-tab spawning for `implement-epic spawn` (BAPI-803).
+ *
+ * `spawn` opens exactly ONE terminal tab in a ticket's worktree running the
+ * agent against a prompt the CALLER wrote to a file. The prompt is arbitrary
+ * operator/loop-authored text — it can contain apostrophes, `$(…)`, backticks,
+ * and newlines — so it is placed inside a single-quoted shell literal using the
+ * repository's existing quoting helpers rather than any local escaping. Reusing
+ * `shSquoteInner` / `powershellSquote` is the point: a second escaping
+ * implementation is a second place for a quoting bug to produce shell execution.
+ *
+ * Two invariants this module is responsible for:
+ *
+ * - **Exactly one tab, and only after every check passes.** The spawn seam is
+ *   invoked once, at the end, after the agent is validated and the command is
+ *   built. A partial failure must leave no tab, because the caller increments
+ *   `sessions_spawned` on success and a phantom tab would desynchronize it.
+ * - **No credential reaches the command.** Nothing here resolves, receives, or
+ *   formats Bridge access data. The spawned agent resolves its own credentials
+ *   from the user-scoped store, exactly as `start-tickets` workers do; a key in
+ *   argv would be visible to every process on the machine via `ps`.
+ */
+import { powershellSquote, shSquoteInner, } from "../start-tickets.js";
+import { INDEX_SCOPE_ENV_VAR } from "../index-scope-contract.js";
+/** The agents `implement-epic spawn` may launch. */
+export const CONDUCT_EPIC_AGENTS = ["claude", "cursor-agent"];
+/** The repository's established default agent. */
+export const CONDUCT_EPIC_DEFAULT_AGENT = "claude";
+/**
+ * Validate an agent value, defaulting to {@link CONDUCT_EPIC_DEFAULT_AGENT}.
+ *
+ * Rejects before any command is built. The agent name becomes the executable in
+ * a shell command, so an unvalidated value is a command-injection surface even
+ * though the surrounding operands are quoted.
+ */
+export function resolveConductEpicAgent(agent) {
+    if (agent === undefined || agent.trim().length === 0) {
+        return { ok: true, agent: CONDUCT_EPIC_DEFAULT_AGENT };
+    }
+    const trimmed = agent.trim();
+    if (!CONDUCT_EPIC_AGENTS.includes(trimmed)) {
+        return {
+            ok: false,
+            error: `Unsupported agent '${trimmed}'. Expected one of: ${CONDUCT_EPIC_AGENTS.join(", ")}`,
+        };
+    }
+    return { ok: true, agent: trimmed };
+}
+/**
+ * Build `cd '<worktree>' && <agent> '<prompt>'` (POSIX) or the PowerShell
+ * equivalent, with both operands quoted by the shared helpers.
+ *
+ * Returns the command as a string rather than an argv array because that is what
+ * every terminal spawner in this repository consumes — a tab is opened by handing
+ * a shell a command line, not by `exec`ing a process.
+ *
+ * BAPI-844: a validated `indexScope` is prefixed as an environment assignment
+ * using the SAME quoting helpers as the rest of the command — the shell's own
+ * environment mechanism, not an argument the agent can see. An absent scope emits
+ * no prefix, so the unscoped command is unchanged byte-for-byte.
+ */
+export function buildConductEpicAgentCommand(input) {
+    const resolved = resolveConductEpicAgent(input.agent);
+    if (!resolved.ok)
+        return resolved;
+    if (input.worktreePath.trim().length === 0) {
+        return { ok: false, error: "A worktree path is required to build the agent command." };
+    }
+    if (input.platform === "win32") {
+        const scopePrefix = input.indexScope
+            ? `$env:${INDEX_SCOPE_ENV_VAR} = ${powershellSquote(input.indexScope)}; `
+            : "";
+        return {
+            ok: true,
+            command: `${scopePrefix}Set-Location -LiteralPath ${powershellSquote(input.worktreePath)}; ` +
+                `${resolved.agent} ${powershellSquote(input.prompt)}`,
+        };
+    }
+    const scopePrefix = input.indexScope
+        ? `export ${INDEX_SCOPE_ENV_VAR}='${shSquoteInner(input.indexScope)}' && `
+        : "";
+    return {
+        ok: true,
+        command: `${scopePrefix}cd '${shSquoteInner(input.worktreePath)}' && ` +
+            `${resolved.agent} '${shSquoteInner(input.prompt)}'`,
+    };
+}
+/**
+ * Build the command and open exactly one tab through `spawnTab`.
+ *
+ * The seam is invoked once and only after construction succeeds. A spawner
+ * failure is returned as `{ ok: false }` with the spawner's own sanitized
+ * message — never the command, which embeds the full prompt text.
+ */
+export async function spawnConductEpicAgentTab(input, spawnTab) {
+    const built = buildConductEpicAgentCommand(input);
+    if (!built.ok)
+        return built;
+    let result;
+    try {
+        result = await spawnTab(built.command, {
+            key: input.ticketKey,
+            worktreePath: input.worktreePath,
+            title: `implement-epic ${input.ticketKey}`,
+        });
+    }
+    catch {
+        return { ok: false, error: "The terminal tab could not be opened." };
+    }
+    if (!result.ok)
+        return { ok: false, error: result.error };
+    return { ok: true, command: built.command };
+}