borgmcp 1.1.15 → 2.0.2

package/src/setup-confirm.ts

@@ -0,0 +1,171 @@
+/**
+ * gh#818 P3 — disclose + confirm the `borg setup` global-config mutation.
+ *
+ * Step-1 of the setup wizard writes the user's GLOBAL agent config
+ * (registers the borg MCP server + hooks). Before gh#818 this happened
+ * silently on first run. This module adds informed-consent disclosure:
+ * it lists WHICH files will be written (well-known `os.homedir()` paths)
+ * and asks to continue before the first mutation.
+ *
+ * Pure / dep-injected (mirrors `resolveCliChoice` + `setup-action.ts`) so
+ * the decision is unit-testable without spawning a prompt or touching argv.
+ *
+ * SECURITY (SR-light, gh#818 221c43df): the disclosure lists file PATHS +
+ * at most the PUBLIC `BORG_API_URL` — there is NO token/secret in the
+ * written config to echo. Local credentials live in the local 0600-permission
+ * seat store, and the written config never contains a token or secret.
+ */
+
+export interface ConfigMutationTarget {
+  /** Human-readable config file path (tilde form). */
+  file: string;
+  /** What is added to it. */
+  change: string;
+}
+
+/**
+ * The set of global config files Step-1 writes, scoped to the detected
+ * agent CLIs. Paths mirror `config-utils.ts`:
+ *   Claude Code: ~/.claude.json (MCP server) + ~/.claude/settings.json (hook)
+ *   Codex:       ~/.codex/config.toml (MCP server) + ~/.codex/hooks.json (hooks)
+ *   OpenCode:    ~/.config/opencode/opencode.json (MCP server)
+ */
+export function configMutationTargets(deps: {
+  claude: boolean;
+  codex: boolean;
+  opencode?: boolean;
+}): ConfigMutationTarget[] {
+  const targets: ConfigMutationTarget[] = [];
+  if (deps.claude) {
+    targets.push({
+      file: '~/.claude.json',
+      change: 'registers the borg MCP server',
+    });
+    targets.push({
+      file: '~/.claude/settings.json',
+      change: 'adds a UserPromptSubmit hook',
+    });
+  }
+  if (deps.codex) {
+    targets.push({
+      file: '~/.codex/config.toml',
+      change: 'registers the borg MCP server',
+    });
+    targets.push({
+      file: '~/.codex/hooks.json',
+      change: 'adds SessionStart + UserPromptSubmit hooks',
+    });
+  }
+  if (deps.opencode) {
+    targets.push({
+      file: '~/.config/opencode/opencode.json',
+      change: 'registers the borg MCP server (with BORG_SESSION activation)',
+    });
+  }
+  return targets;
+}
+
+/**
+ * Disclosure text: the files Step-1 will write + an undo note. Pure so SR
+ * can pin "lists paths only, no secret". Lists the public `BORG_API_URL`
+ * only by reference (the MCP-server registration env), never a credential.
+ */
+export function formatConfigMutationDisclosure(
+  targets: ConfigMutationTarget[]
+): string {
+  const lines: string[] = [];
+  lines.push('borg setup will register the borg MCP server in your agent config:');
+  for (const t of targets) {
+    lines.push(`  • ${t.file}  (${t.change})`);
+  }
+  lines.push(
+    'These changes are additive and reversible — remove the "borg" entries to undo.'
+  );
+  return lines.join('\n');
+}
+
+export type ConfirmDecision = 'proceed' | 'abort';
+
+export interface ConfirmConfigMutationDeps {
+  /** `process.stdin.isTTY === true`. */
+  isTTY: boolean;
+  /** `--yes` / `-y` present in argv. */
+  yes: boolean;
+  /**
+   * Injected interactive confirm — returns the user's yes(true)/no(false).
+   * Only invoked in the TTY-and-not-`--yes` path; NEVER called otherwise
+   * (so a non-TTY never reads stdin — see item 1 below).
+   */
+  confirm: () => Promise<boolean>;
+}
+
+/**
+ * Decide whether to proceed with the Step-1 config mutation.
+ *
+ * The six CR-binding build-gate items (gh#818, 3b3e85a5) live here:
+ *   1. (THE load-bearing headless no-regress) non-TTY → 'proceed' WITHOUT
+ *      prompting. We return before touching `confirm`, so a non-TTY run
+ *      (CI / pipe / headless) never reads stdin → no hang.
+ *   2. `--yes`/`-y` → 'proceed' without prompting (scripted-but-TTY +
+ *      explicit non-interactive). No collision with --no-browser/--device.
+ *   3. TTY + interactive → ask; decline → 'abort' (the caller exits BEFORE
+ *      any write).
+ *   6. This dep-injected shape IS the testable seam.
+ */
+export async function confirmConfigMutation(
+  deps: ConfirmConfigMutationDeps
+): Promise<ConfirmDecision> {
+  if (!deps.isTTY) return 'proceed'; // item 1 — never block on stdin
+  if (deps.yes) return 'proceed'; // item 2 — explicit bypass
+  const ok = await deps.confirm(); // item 3 — interactive consent
+  return ok ? 'proceed' : 'abort';
+}
+
+/**
+ * Scan argv for the `--yes` / `-y` bypass. Kept separate so the flag set
+ * is pinned in tests (item 2 — no collision with the existing
+ * --no-browser/--device scan in setup.ts).
+ */
+export function parseYesFlag(argv: string[]): boolean {
+  return argv.includes('--yes') || argv.includes('-y');
+}
+
+/**
+ * gh#844 — whether Step-1 has ANY config mutation worth disclosing.
+ *
+ * The disclosure + confirm prompt exists to obtain informed consent for the
+ * config writes Step-1 performs (gh#818). On a pure refresh — the normal
+ * setup re-run where every DETECTED agent CLI already has the full
+ * borg setup (MCP server registered AND every hook write already applied) —
+ * there is no mutation to consent to, so the prompt is redundant and skipped.
+ *
+ * CRITICAL (gh#844 SR finding 8d9c732e): the gate must cover the FULL disclosed
+ * mutation set — MCP registration AND every hook write (claude UserPromptSubmit
+ * + the legacy SessionStart removal; codex SessionStart + UserPromptSubmit) —
+ * not MCP registration alone. Otherwise an MCP-configured user with a pending
+ * hook write (e.g. a pre-gh#673 upgrader whose legacy global hook must be
+ * removed) would have settings.json mutated with consent silently skipped.
+ * Caller derives `claudeHookPending`/`codexHookPending` from the SAME peeks
+ * that gate the individual writers, so the gate and the writers cannot drift.
+ *
+ * Scoped to DETECTED CLIs: a claude-only user is never gated on codex config
+ * state (and vice-versa). A naive `!isMcpServerConfigured() ||
+ * !isCodexMcpServerConfigured()` gate would mis-fire for single-CLI users —
+ * the absent CLI's config is unconfigured, so the OR would always be true.
+ */
+export function setupMutationPending(deps: {
+  claude: boolean;
+  codex: boolean;
+  opencode: boolean;
+  claudeMcpConfigured: boolean;
+  codexMcpConfigured: boolean;
+  opencodeMcpConfigured: boolean;
+  claudeHookPending: boolean;
+  codexHookPending: boolean;
+}): boolean {
+  return (
+    (deps.claude && (!deps.claudeMcpConfigured || deps.claudeHookPending)) ||
+    (deps.codex && (!deps.codexMcpConfigured || deps.codexHookPending)) ||
+    (deps.opencode && !deps.opencodeMcpConfigured)
+  );
+}

package/src/setup.ts

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+/**
+ * Borg MCP Setup Wizard
+ *
+ * Interactive setup flow:
+ * 1. Configure agent CLI MCP settings + orientation hooks
+ * 2. Print how to connect to a local self-hosted Borg server
+ *
+ * There is no cloud authority: setup offers/executes NO cloud auth, Google
+ * auth, subscription, or checkout.
+ */
+
+import prompts from 'prompts';
+import chalk from 'chalk';
+import which from 'which';
+import {
+  confirmConfigMutation,
+  configMutationTargets,
+  formatConfigMutationDisclosure,
+  parseYesFlag,
+  setupMutationPending,
+} from './setup-confirm.js';
+import {
+  addUserPromptSubmitHook,
+  addCodexSessionStartHook,
+  addCodexUserPromptSubmitHook,
+  isMcpServerConfigured,
+  isCodexMcpServerConfigured,
+  isOpenCodeMcpServerConfigured,
+  isSessionStartHookRegistered,
+  isUserPromptSubmitHookRegistered,
+  isCodexSessionStartHookRegistered,
+  isCodexUserPromptSubmitHookRegistered,
+  removeSessionStartHook,
+} from './config-utils.js';
+import { ensureCliMcpConfigured } from './ensure-mcp-config.js';
+import { handleVersionFlag } from './version.js';
+import { initDebugFromArgv } from './debug.js';
+import { defaultApprovalIo, setupApprovalWarnings } from './cli-tool-approval.js';
+
+/**
+ * Main setup wizard
+ */
+async function main() {
+  initDebugFromArgv(process.argv);
+  handleVersionFlag();
+  console.log(chalk.blue.bold('\n◼ Borg MCP Setup Wizard ◼'));
+
+  let claudeCliPath: string | null = null;
+  let codexCliPath: string | null = null;
+  let opencodeCliPath: string | null = null;
+  try { claudeCliPath = which.sync('claude'); } catch { /* optional */ }
+  try { codexCliPath = which.sync('codex'); } catch { /* optional */ }
+  try { opencodeCliPath = which.sync('opencode'); } catch { /* optional */ }
+
+  if (claudeCliPath) console.log(chalk.gray(`Found Claude CLI: ${claudeCliPath}`));
+  if (codexCliPath) console.log(chalk.gray(`Found Codex CLI: ${codexCliPath}`));
+  if (opencodeCliPath) console.log(chalk.gray(`Found OpenCode CLI: ${opencodeCliPath}`));
+  if (claudeCliPath || codexCliPath || opencodeCliPath) console.log('');
+
+  if (!claudeCliPath && !codexCliPath && !opencodeCliPath) {
+    console.error(chalk.red('◼ No supported agent CLI found\n'));
+    console.error(chalk.yellow('Please install Claude Code, Codex, or OpenCode first:'));
+    console.error(chalk.gray('  Claude Code: https://claude.ai/download'));
+    console.error(chalk.gray('  Codex: https://developers.openai.com/codex'));
+    console.error(chalk.gray('  OpenCode: https://opencode.ai\n'));
+    process.exit(1);
+  }
+
+  // Step 1: Configure every detected agent CLI
+  console.log(chalk.blue('◼ Agent CLI Integration'));
+
+  const yes = parseYesFlag(process.argv);
+
+  const claudeDetected = claudeCliPath !== null;
+  const codexDetected = codexCliPath !== null;
+  const opencodeDetected = opencodeCliPath !== null;
+  const claudeMcpConfigured = isMcpServerConfigured();
+  const codexMcpConfigured = isCodexMcpServerConfigured();
+  const opencodeMcpConfigured = isOpenCodeMcpServerConfigured();
+  const claudeLegacyHookPending = claudeDetected && isSessionStartHookRegistered();
+  const claudeUpsHookPending = claudeDetected && !isUserPromptSubmitHookRegistered();
+  const codexSessionHookPending = codexDetected && !isCodexSessionStartHookRegistered();
+  const codexUpsHookPending = codexDetected && !isCodexUserPromptSubmitHookRegistered();
+  const claudeHookPending = claudeLegacyHookPending || claudeUpsHookPending;
+  const codexHookPending = codexSessionHookPending || codexUpsHookPending;
+
+  if (
+    setupMutationPending({
+      claude: claudeDetected,
+      codex: codexDetected,
+      opencode: opencodeDetected,
+      claudeMcpConfigured,
+      codexMcpConfigured,
+      opencodeMcpConfigured,
+      claudeHookPending,
+      codexHookPending,
+    })
+  ) {
+    console.log(
+      formatConfigMutationDisclosure(
+        configMutationTargets({ claude: claudeDetected, codex: codexDetected, opencode: opencodeDetected })
+      )
+    );
+    const mutationDecision = await confirmConfigMutation({
+      isTTY: process.stdin.isTTY === true,
+      yes,
+      confirm: async () => {
+        const { proceed } = await prompts({
+          type: 'confirm',
+          name: 'proceed',
+          message: 'Continue with these changes?',
+          initial: true,
+        });
+        return proceed === true;
+      },
+    });
+    if (mutationDecision === 'abort') {
+      console.log(chalk.yellow('\n◼ Setup cancelled — no changes made.\n'));
+      process.exit(0);
+    }
+  }
+  console.log('');
+
+  if (claudeCliPath) {
+    try {
+      ensureCliMcpConfigured('claude');
+      if (claudeLegacyHookPending) removeSessionStartHook();
+      if (claudeUpsHookPending) addUserPromptSubmitHook();
+      console.log(chalk.green('◼ borg configured for Claude Code'));
+    } catch (error: any) {
+      console.error(chalk.red(`\n◼ Failed to configure Claude Code: ${error.message}\n`));
+      process.exit(1);
+    }
+  }
+  if (codexCliPath) {
+    try {
+      ensureCliMcpConfigured('codex');
+      if (codexSessionHookPending) addCodexSessionStartHook();
+      if (codexUpsHookPending) addCodexUserPromptSubmitHook();
+      console.log(chalk.green('◼ borg configured for Codex'));
+    } catch (error: any) {
+      console.error(chalk.red(`\n◼ Failed to configure Codex: ${error.message}\n`));
+      process.exit(1);
+    }
+  }
+  if (opencodeCliPath) {
+    try {
+      ensureCliMcpConfigured('opencode');
+      console.log(chalk.green('◼ borg configured for OpenCode'));
+    } catch (error: any) {
+      console.error(chalk.red(`\n◼ Failed to configure OpenCode: ${error.message}\n`));
+      process.exit(1);
+    }
+  }
+  const approvalIo = defaultApprovalIo(async () => '', () => false, {
+    cwd: process.cwd(),
+    env: process.env,
+    codexArgs: [],
+  });
+  for (const warning of await setupApprovalWarnings(approvalIo, {
+    codex: codexDetected,
+    opencode: opencodeDetected,
+  })) {
+    console.log(chalk.yellow(`warning: ${warning}`));
+  }
+  console.log('');
+
+  // Step 2: Server connection — local self-hosted only.
+  console.log(chalk.blue('◼ Server Connection'));
+  console.log(chalk.gray('Local self-hosted server mode — no account or subscription needed.'));
+
+  // Success message
+  console.log(chalk.green.bold('\nSetup complete!\n'));
+  console.log(chalk.yellow('🔄 Restart Claude Code / Codex / OpenCode (or open a new session) for the changes to take effect.\n'));
+  console.log(chalk.gray('◼ Next steps:'));
+  console.log(chalk.gray('1. cd into your project, then run "borg assimilate --host <host>" to join a cube'));
+  console.log(chalk.gray('   (this connects to your local server and launches your agent)'));
+  console.log(chalk.gray('2. Use `borg assimilate --host <host> --enroll` from the operator terminal to enroll a new client\n'));
+}
+
+// Run wizard
+main().catch((error) => {
+  console.error(chalk.red(`\n◼ Setup failed: ${error.message}\n`));
+  process.exit(1);
+});

package/src/shell-escape.ts

@@ -0,0 +1,22 @@
+// POSIX-safe shell-escaping for paste-intended emission.
+//
+// Sprint 18 (gh-tracked via dispatch 10:41:47Z): when the CLI emits a
+// `cd <path>` line for the user to copy-paste into their shell, the path is
+// a filesystem-controlled string with no character constraints (unlike
+// DB-CHECK-constrained role/cube names). Paths can legally contain spaces,
+// `$VAR`, backticks, `$(cmd)`, embedded single-quotes, and other shell
+// metacharacters that would execute on paste under naive emission.
+//
+// drone-11 SR-LANE (cube entry 2026-05-19T10:44:35Z) escalation: double-
+// quoting handles spaces but `$VAR` / backtick / `$(cmd)` still expand
+// inside double-quotes. Single-quotes with internal-quote escape (`'\''`
+// = close-quote / escaped-quote / re-open-quote) defang every shell
+// metachar including embedded `'`. POSIX-defined, copy-paste-runnable
+// across bash / zsh / dash / sh.
+//
+// Behavior: returns the input wrapped in single-quotes with any internal
+// `'` rewritten as `'\''`. Empty string returns `''`.
+
+export function shellEscape(s: string): string {
+  return `'${s.replace(/'/g, `'\\''`)}'`;
+}

package/src/spawn.ts

@@ -0,0 +1,31 @@
+/**
+ * `borg spawn` — deprecation stub.
+ *
+ * Replaced by `borg assimilate [role] --worktree <name>` (see
+ * `assimilate-cmd.ts`). The new command folds worktree creation,
+ * cube creation, template application, and drone assimilation into one
+ * shell call. This file remains so existing
+ * scripts and tab-completion entries fail loudly with an actionable
+ * migration message rather than silently mis-routing.
+ *
+ * `validateName` continues to be re-exported from here for callers
+ * that still depend on the symbol (it lives in `name-validator.ts`
+ * now — single source of truth).
+ */
+
+export { validateName } from './name-validator.js';
+
+export async function runSpawn(): Promise<number> {
+  const msg =
+    'borg spawn is removed. Use:\n' +
+    '  borg assimilate [role] --worktree <name>\n' +
+    '\n' +
+    'Example: if you previously ran `borg spawn drone-2`, the equivalent is\n' +
+    '  borg assimilate --worktree drone-2\n' +
+    '(role is optional; defaults per first-drone rules)\n' +
+    '\n' +
+    'If you want a specific role:\n' +
+    '  borg assimilate builder --worktree drone-2\n';
+  process.stderr.write(msg);
+  return 2;
+}

package/src/startup-services.ts

@@ -0,0 +1,36 @@
+export type McpStartupTask = () => void | Promise<void>;
+
+/** Required named services: omission from index wiring is a type error. */
+export interface McpStartupServices {
+  sessionStartHook: McpStartupTask;
+  auditHook: McpStartupTask;
+  sseStream: McpStartupTask;
+  openCode: McpStartupTask;
+}
+
+/**
+ * Run normal long-lived MCP child startup work. The assimilation readiness
+ * child must reach the initialize response without acquiring leases, fetching
+ * SSE, mutating hooks, or starting timers because it is intentionally killed
+ * immediately after that response.
+ */
+export async function runMcpStartupServices(
+  readinessProbe: boolean,
+  services: McpStartupServices
+): Promise<void> {
+  if (readinessProbe) return;
+  const tasks = [
+    services.sessionStartHook,
+    services.auditHook,
+    services.sseStream,
+    services.openCode,
+  ];
+  for (const task of tasks) {
+    try {
+      await task();
+    } catch {
+      // Every background service is best-effort and independent. A failure in
+      // one must neither break MCP initialize nor suppress later services.
+    }
+  }
+}