borgmcp 1.1.15 → 2.0.2

package/src/cli-help.ts

@@ -0,0 +1,116 @@
+/**
+ * Pure CLI help-text + flag helpers.
+ *
+ * Kept in its own module (not in claude.ts) so importing them in tests does NOT
+ * run claude.ts's `main()` side effects — the same pattern as parse-assimilate-args.ts
+ * and cli-platform.ts.
+ */
+
+/** True for the standard help flags `--help` / `-h`. */
+export function isHelpFlag(arg: string | undefined): boolean {
+  return arg === '--help' || arg === '-h';
+}
+
+/**
+ * Help text for top-level `borg --help`.
+ *
+ * Kept pure so tests can pin user-facing discoverability without importing
+ * claude.ts, which launches agent CLIs as a side effect.
+ */
+export function topLevelHelpText(version: string): string {
+  return (
+    `borgmcp ${version} — run several AI coding agents on one project, together.\n` +
+    `              They coordinate through a shared log (a "cube"). For Claude Code, Codex & OpenCode.\n\n` +
+    `Docs & quickstart: https://github.com/Byte-Ventures/borg-mcp-client#readme\n\n` +
+    `Install Claude Code, Codex, or OpenCode first. Type \`borg ...\` in your terminal;\n` +
+    `type \`borg_...\` inside your agent session once you've joined a cube ("assimilate").\n\n` +
+    `Usage:\n` +
+    `  borg                     Launch your agent CLI; in a TTY, bare borg may show the launch menu\n` +
+    `  borg setup               Set up borg MCP server + agent CLI integration\n` +
+    `  borg assimilate [role]   Join or create a cube\n` +
+    `  borg assimilate --host <host>   Join or create on an explicit server\n` +
+    `  borg assimilate --worktree <name>   Spawn a worktree drone (in ~/.borg/worktrees/<repo>/<name>)\n` +
+    `  borg reset-local-seat    Clear ONLY this worktree's saved local seat (offline; after a rejection)\n` +
+    `  borg sync [--prune]      Sync this worktree's branch to origin/main\n` +
+    `  borg cleanup [--prune]   Report (or --prune) worktrees orphaned by evicted drones\n` +
+    `  borg launch-all [cube]   Launch all drone worktrees of a cube (default: active cube)\n` +
+    `  borg launch-all [cube] --cli claude|codex|opencode\n` +
+    `                           Launch all drone worktrees with that agent CLI\n` +
+    `  borg --cli claude|codex|opencode  Launch that agent CLI directly\n` +
+    `  borg --version           Show installed version\n\n` +
+    `All other arguments are passed through to the selected agent CLI.\n`
+  );
+}
+
+/**
+ * Help text for `borg assimilate --help` — the home for the full assimilate flag
+ * set. Model/provider configuration belongs to the selected agent CLI.
+ */
+export function assimilateHelpText(version: string): string {
+  return (
+    `borg assimilate (borgmcp ${version}) — join or create a cube under a role\n\n` +
+    `Usage:\n` +
+    `  borg assimilate [role]               Join the active cube under [role] (default role if omitted)\n` +
+    `  borg assimilate [role] --worktree <name>   Spawn the drone in an isolated git worktree\n` +
+    `                                       (~/.borg/worktrees/<repo>/<name>)\n` +
+    `  borg assimilate --here               Assimilate in the current worktree (no sibling spawn)\n` +
+    `  borg assimilate --host <host>        Join an authorized self-hosted cube\n` +
+    `  borg assimilate --host <host> --enroll   Operator-terminal enrollment, then create/join (preview)\n` +
+    `  borg assimilate --help               Show this help\n\n` +
+    `Flags:\n` +
+    `  --worktree <name>          Create + launch the drone in a sibling git worktree\n` +
+    `  --here                     Stay in the current worktree (no sibling spawn)\n` +
+    `  --cube-name <name>         Cube to join/create (otherwise confirm repo basename)\n` +
+    `  --host <host>              Borg server host or URL (bare hosts default to HTTPS)\n` +
+    `  --enroll                   Prompt for a hidden enrollment invitation in the operator terminal\n` +
+    `  --template <name>          Bootstrap a new cube from a bundled role template\n` +
+    `  --no-template              Create the cube with no template roles\n` +
+    `  --cli claude|codex|opencode         Agent CLI to launch (default: claude)\n` +
+    `  --model claude:<model>   Legacy Claude model override (configure models in the agent CLI)\n` +
+    `  --yes, -y                  Skip confirmation prompts\n\n` +
+    `An enrolled owner client may create an idempotent repository cube; ordinary clients\n` +
+    `require an explicit cube grant. Agent seats begin only after enrollment. Preview only.\n` +
+    `See docs/LOCAL_SERVER.md for self-hosted setup and current status.\n\n` +
+    `For local or provider-specific models, configure the selected agent CLI directly.\n` +
+    `OpenCode supports Ollama and other providers through its own model configuration.\n`
+  );
+}
+
+/**
+ * Help text for `borg reset-local-seat --help`. The offline, network-free seat
+ * reset recommended by the pin-matched SESSION_REJECTED diagnostic (#1082).
+ */
+export function resetLocalSeatHelpText(version: string): string {
+  return (
+    `borg reset-local-seat (borgmcp ${version}) — clear ONLY this worktree's saved local seat\n\n` +
+    `Offline and network-free: it contacts no server and revokes nothing server-side. It clears\n` +
+    `just this worktree's saved local seat — its credential and cube binding together — from the\n` +
+    `local seat store on this machine. Server, trust anchor, cube, and every sibling worktree are\n` +
+    `left untouched.\n\n` +
+    `Use it after \`borg assimilate\` reports this worktree's seat was revoked or taken over\n` +
+    `(a pin-matched rejection), then ask the operator for a new invitation and re-enroll.\n\n` +
+    `Usage:\n` +
+    `  borg reset-local-seat                 Reset this worktree's saved seat (TTY confirms [y/N])\n` +
+    `  borg reset-local-seat --host <host>   No-op unless this worktree's seat is on <host>\n` +
+    `  borg reset-local-seat --yes           Reset without a prompt (required when non-interactive)\n` +
+    `  borg reset-local-seat --help          Show this help\n\n` +
+    `Flags:\n` +
+    `  --host <host>              Only act if this worktree's saved seat is on <host> (else no-op)\n` +
+    `  --yes, -y                  Skip the confirmation prompt (required in non-TTY contexts)\n`
+  );
+}
+
+/**
+ * Help text for `borg setup --help` (gh#520 — previously this ran the setup
+ * wizard instead of showing help). Mirrors the `borg setup` description in the
+ * top-level `borg --help`.
+ */
+export function setupHelpText(version: string): string {
+  return (
+    `borg setup (borgmcp ${version}) — set up borg MCP server + agent CLI integration\n\n` +
+    `Borg MCP needs Claude Code, Codex, or OpenCode installed first.\n\n` +
+    `Usage:\n` +
+    `  borg setup               Run the interactive setup wizard\n` +
+    `  borg setup --help        Show this help\n`
+  );
+}

package/src/cli-platform.ts

@@ -0,0 +1,127 @@
+import which from 'which';
+import type { BorgCli } from './cubes.js';
+import { getProjectCliPreference, setProjectCliPreference } from './cubes.js';
+
+export interface CliAvailability {
+  claude: string | null;
+  codex: string | null;
+  opencode: string | null;
+}
+
+export interface CliChoiceDeps {
+  detectCli: () => CliAvailability;
+  getPreference: () => Promise<BorgCli | null>;
+  setPreference: (cli: BorgCli) => Promise<void>;
+  prompt: (message: string) => Promise<string>;
+  isTTY: () => boolean;
+}
+
+export function detectCliAvailability(): CliAvailability {
+  return {
+    claude: findCommand('claude'),
+    codex: findCommand('codex'),
+    opencode: findCommand('opencode'),
+  };
+}
+
+function findCommand(name: string): string | null {
+  try {
+    return which.sync(name);
+  } catch {
+    return null;
+  }
+}
+
+export function installedCliNames(availability: CliAvailability): BorgCli[] {
+  const out: BorgCli[] = [];
+  if (availability.claude) out.push('claude');
+  if (availability.codex) out.push('codex');
+  if (availability.opencode) out.push('opencode');
+  return out;
+}
+
+async function setPreferenceAndReturn(cli: BorgCli, deps: CliChoiceDeps): Promise<BorgCli> {
+  await deps.setPreference(cli);
+  return cli;
+}
+
+export async function resolveCliChoice(
+  explicit: BorgCli | undefined,
+  deps: CliChoiceDeps
+): Promise<BorgCli> {
+  const availability = deps.detectCli();
+  const installed = installedCliNames(availability);
+  if (installed.length === 0) {
+    throw new Error('No supported agent CLI found (claude, codex, opencode). Install one of them, then run borg again.');
+  }
+
+  if (explicit) {
+    if (!installed.includes(explicit)) {
+      throw new Error(`${explicit} CLI is not installed.`);
+    }
+    await deps.setPreference(explicit);
+    return explicit;
+  }
+
+  const stored = await deps.getPreference();
+  if (stored && installed.includes(stored)) return stored;
+
+  if (installed.length === 1) {
+    await deps.setPreference(installed[0]);
+    return installed[0];
+  }
+
+  if (!deps.isTTY()) {
+    throw new Error('Multiple agent CLIs detected. Pass --cli claude, --cli codex, or --cli opencode to choose.');
+  }
+
+  const promptLines = installed.map((cli, i) => `  ${i + 1}) ${cli}`);
+  const answer = (await deps.prompt(`Use which CLI for this project?\n${promptLines.join('\n')}\n[1]: `)).trim();
+  if (answer === '' || answer === '1') return setPreferenceAndReturn(installed[0], deps);
+  const num = parseInt(answer, 10);
+  if (!Number.isNaN(num) && num >= 1 && num <= installed.length) {
+    return setPreferenceAndReturn(installed[num - 1], deps);
+  }
+  const lower = answer.toLowerCase();
+  for (const cli of installed) {
+    if (lower === cli) return setPreferenceAndReturn(cli, deps);
+  }
+  throw new Error(`invalid CLI choice "${answer}"`);
+}
+
+export function defaultCliChoiceDeps(prompt: (message: string) => Promise<string>, isTTY: () => boolean): CliChoiceDeps {
+  return {
+    detectCli: detectCliAvailability,
+    getPreference: getProjectCliPreference,
+    setPreference: setProjectCliPreference,
+    prompt,
+    isTTY,
+  };
+}
+
+const VALID_CLIS: readonly BorgCli[] = ['claude', 'codex', 'opencode'];
+
+export function parseCliFlag(args: string[]): { cli?: BorgCli; rest: string[]; error?: string } {
+  const rest: string[] = [];
+  let cli: BorgCli | undefined;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--cli') {
+      const next = args[i + 1];
+      if (!next || !(VALID_CLIS as readonly string[]).includes(next)) {
+        return { rest, error: `--cli requires one of: ${VALID_CLIS.join(', ')}` };
+      }
+      cli = next as BorgCli;
+      i += 1;
+    } else if (arg.startsWith('--cli=')) {
+      const value = arg.slice('--cli='.length);
+      if (!(VALID_CLIS as readonly string[]).includes(value)) {
+        return { rest, error: `--cli requires one of: ${VALID_CLIS.join(', ')}` };
+      }
+      cli = value as BorgCli;
+    } else {
+      rest.push(arg);
+    }
+  }
+  return { cli, rest };
+}