borgmcp 1.1.14 → 2.0.1

package/src/parse-assimilate-args.ts

@@ -0,0 +1,125 @@
+import type { AssimilateFlags } from './assimilate-cmd.js';
+
+export interface ParseAssimilateResult {
+  ok: true;
+  role: string | undefined;
+  flags: AssimilateFlags;
+}
+
+export type ParseResult =
+  | ParseAssimilateResult
+  | { ok: false; error: string };
+
+/**
+ * Parse argv for `borg assimilate [role] [--worktree <n>] [--template <n>]
+ * [--no-template] [--cube-name <n>] [--host <host>] [--enroll] [--here] [--yes]`. The `assimilate`
+ * subcommand token must already be stripped by the caller.
+ */
+export function parseAssimilateArgs(rawArgs: string[]): ParseResult {
+  let role: string | undefined;
+  const flags: AssimilateFlags = {};
+
+  for (let i = 0; i < rawArgs.length; i += 1) {
+    const arg = rawArgs[i];
+    if (arg === '--worktree') {
+      const next = rawArgs[i + 1];
+      if (typeof next !== 'string' || next.length === 0) {
+        return { ok: false, error: '--worktree requires a name argument (e.g. `--worktree drone-2`)' };
+      }
+      flags.worktree = next;
+      i += 1;
+    } else if (arg === '--template') {
+      const next = rawArgs[i + 1];
+      if (typeof next !== 'string' || next.length === 0) {
+        return { ok: false, error: '--template requires a name argument (e.g. `--template software-dev`)' };
+      }
+      flags.template = next;
+      i += 1;
+    } else if (arg === '--no-template') {
+      flags.noTemplate = true;
+    } else if (arg === '--cube-name') {
+      const next = rawArgs[i + 1];
+      if (typeof next !== 'string' || next.length === 0) {
+        return { ok: false, error: '--cube-name requires a name argument (e.g. `--cube-name my-cube`)' };
+      }
+      flags.cubeName = next;
+      i += 1;
+    } else if (arg === '--here') {
+      flags.here = true;
+    } else if (arg === '--host') {
+      const next = rawArgs[i + 1];
+      if (typeof next !== 'string' || next.length === 0 || next.startsWith('-')) {
+        return { ok: false, error: '--host requires a host or URL (e.g. `--host localhost:7091`)' };
+      }
+      flags.server = next;
+      i += 1;
+    } else if (arg.startsWith('--host=')) {
+      const value = arg.slice('--host='.length);
+      if (!value) {
+        return { ok: false, error: '--host requires a host or URL (e.g. `--host localhost:7091`)' };
+      }
+      flags.server = value;
+    } else if (arg === '--enroll') {
+      flags.enroll = true;
+    } else if (arg === '--yes' || arg === '-y') {
+      flags.yes = true;
+    } else if (arg === '--cli') {
+      const next = rawArgs[i + 1];
+      if (next !== 'claude' && next !== 'codex' && next !== 'opencode') {
+        return { ok: false, error: '--cli requires claude, codex, or opencode' };
+      }
+      flags.cli = next;
+      i += 1;
+    } else if (arg.startsWith('--cli=')) {
+      const value = arg.slice('--cli='.length);
+      if (value !== 'claude' && value !== 'codex' && value !== 'opencode') {
+        return { ok: false, error: '--cli requires claude, codex, or opencode' };
+      }
+      flags.cli = value;
+    } else if (arg === '--model' || arg === '--backend') {
+      // --backend is the deprecated alias for --model (kept so existing
+      // invocations don't break); both set flags.model.
+      const next = rawArgs[i + 1];
+      if (typeof next !== 'string' || next.length === 0) {
+        return { ok: false, error: '--model requires a descriptor (e.g. `--model claude:claude-opus-4-8`)' };
+      }
+      const match = next.match(/^claude:[A-Za-z0-9._:\/-]+$/);
+      if (!match) {
+        return { ok: false, error: `invalid model descriptor '${next}' — expected claude:<model>; configure local models in the agent CLI` };
+      }
+      flags.model = next;
+      i += 1;
+    } else if (arg.startsWith('--model=') || arg.startsWith('--backend=')) {
+      const value = arg.slice(arg.indexOf('=') + 1);
+      const match = value.match(/^claude:[A-Za-z0-9._:\/-]+$/);
+      if (!match) {
+        return { ok: false, error: `invalid model descriptor '${value}' — expected claude:<model>; configure local models in the agent CLI` };
+      }
+      flags.model = value;
+    } else if (arg.startsWith('--')) {
+      return {
+        ok: false,
+        error: `unknown flag: ${arg}. Supported: --worktree, --template, --no-template, --cube-name, --host, --enroll, --here, --yes, --cli, --model`,
+      };
+    } else {
+      if (role !== undefined) {
+        return { ok: false, error: `unexpected extra argument: ${arg} (already have role "${role}")` };
+      }
+      role = arg;
+    }
+  }
+
+  // CR-PF-F1 (drone-2 Phase F review 2026-05-18T05:04Z): spec rev-2
+  // §Error paths mandates an argparse-level error when both --template
+  // and --no-template are passed. Catch at parse time rather than in
+  // the orchestrator so the failure happens before any auth / network /
+  // worktree-spawn work.
+  if (flags.template !== undefined && flags.noTemplate) {
+    return { ok: false, error: '--template and --no-template are mutually exclusive' };
+  }
+  if (flags.enroll && flags.server === undefined) {
+    return { ok: false, error: '--enroll requires --host <host>' };
+  }
+
+  return { ok: true, role, flags };
+}

package/src/parse-launch-all-args.ts

@@ -0,0 +1,100 @@
+// gh#556 Part 2 — argument parser for `borg launch-all [cube] [flags]` (spec §9.1).
+// Pure: rawArgs → validated LaunchAllArgs | error. Mirror of parse-assimilate-args.
+
+export interface LaunchAllFlags {
+  mode?: 'tmux' | 'windows' | 'pastelist';
+  only?: string;
+  dryRun?: boolean;
+  cli?: 'claude' | 'codex' | 'opencode';
+  noAttach?: boolean;
+  yes?: boolean;
+  force?: boolean;
+  /**
+   * Milliseconds to wait BETWEEN each drone launch, to avoid the per-user/IP
+   * rate limiter when a fleet's worth of agents all bootstrap at once
+   * (assimilate + regen + roster). 0 disables. Default + env override: see
+   * launch-all-cmd (DEFAULT_LAUNCH_DELAY_MS / BORG_LAUNCH_DELAY_MS).
+   */
+  launchDelayMs?: number;
+}
+
+export interface LaunchAllArgs {
+  cubeName?: string;
+  flags: LaunchAllFlags;
+}
+
+export type ParseLaunchAllResult =
+  | { ok: true; args: LaunchAllArgs }
+  | { ok: false; error: string };
+
+const SUPPORTED =
+  '--mode <tmux|windows|pastelist>, --only <name>, --dry-run, --cli <claude|codex|opencode>, ' +
+  '--no-attach, --yes/-y, --force, --launch-delay <ms>';
+
+export function parseLaunchAllArgs(rawArgs: string[]): ParseLaunchAllResult {
+  const flags: LaunchAllFlags = {};
+  let cubeName: string | undefined;
+
+  for (let i = 0; i < rawArgs.length; i++) {
+    const arg = rawArgs[i];
+    switch (arg) {
+      case '--mode': {
+        const v = rawArgs[++i];
+        if (v !== 'tmux' && v !== 'windows' && v !== 'pastelist') {
+          return { ok: false, error: `--mode must be one of tmux|windows|pastelist (got: ${v ?? '<missing>'})` };
+        }
+        flags.mode = v;
+        break;
+      }
+      case '--only': {
+        const v = rawArgs[++i];
+        if (v === undefined || v.startsWith('--')) {
+          return { ok: false, error: `--only requires a value (role name or drone label)` };
+        }
+        flags.only = v;
+        break;
+      }
+      case '--cli': {
+        const v = rawArgs[++i];
+        if (v !== 'claude' && v !== 'codex' && v !== 'opencode') {
+          return { ok: false, error: `--cli must be one of claude|codex|opencode (got: ${v ?? '<missing>'})` };
+        }
+        flags.cli = v;
+        break;
+      }
+      case '--launch-delay': {
+        const v = rawArgs[++i];
+        const n = v === undefined ? NaN : Number(v);
+        if (!Number.isInteger(n) || n < 0) {
+          return { ok: false, error: `--launch-delay requires a non-negative integer (milliseconds); got: ${v ?? '<missing>'}` };
+        }
+        flags.launchDelayMs = n;
+        break;
+      }
+      case '--dry-run':
+        flags.dryRun = true;
+        break;
+      case '--no-attach':
+        flags.noAttach = true;
+        break;
+      case '--yes':
+      case '-y':
+        flags.yes = true;
+        break;
+      case '--force':
+        flags.force = true;
+        break;
+      default:
+        if (arg.startsWith('-')) {
+          return { ok: false, error: `unknown flag: ${arg}. Supported: ${SUPPORTED}` };
+        }
+        if (cubeName !== undefined) {
+          return { ok: false, error: `unexpected extra argument: ${arg}` };
+        }
+        cubeName = arg;
+        break;
+    }
+  }
+
+  return { ok: true, args: { cubeName, flags } };
+}

package/src/postinstall-banner.ts

@@ -0,0 +1,37 @@
+// Pure builder for the post-install banner text. Kept separate from
+// postinstall.ts (which is a side-effectful entry script that runs detection
+// + console output + process.exit on import) so the message content is unit-
+// testable without triggering those side effects.
+//
+// gh#653 B1: a non-expert who installs borgmcp WITHOUT an agent CLI (Claude
+// Code / Codex) present would otherwise be sent straight to "Next step: borg
+// setup", which dead-ends at "No supported agent CLI found". When no agent CLI
+// is detected, surface the install-an-agent-CLI step FIRST so the banner never
+// points the user into a wall.
+
+export function composeInstallBanner(hasAgentCli: boolean): string {
+  const lines = [
+    '',
+    '╔════════════════════════════════════╗',
+    '║       ◼ Borg MCP Installed ◼       ║',
+    '╚════════════════════════════════════╝',
+    '',
+  ];
+
+  if (!hasAgentCli) {
+    lines.push(
+      '⚠ No agent CLI detected. Borg runs on top of Claude Code or Codex —',
+      '  install one first:',
+      '    Claude Code: https://claude.ai/download',
+      '    Codex:       https://developers.openai.com/codex',
+      '',
+      'Then run:',
+      '  borg setup',
+      '',
+    );
+  } else {
+    lines.push('Next step:', '  borg setup', '');
+  }
+
+  return lines.join('\n');
+}

package/src/postinstall.ts

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+/**
+ * Post-install script
+ *
+ * Detects local vs global installation and rejects local installs.
+ * gh#653 B1: also detects whether an agent CLI (Claude Code / Codex) is present
+ * and adjusts the "next step" banner so a user with no agent CLI is told to
+ * install one FIRST rather than being sent into `borg setup`'s dead-end.
+ */
+
+import { detectCliAvailability, installedCliNames } from './cli-platform.js';
+import { composeInstallBanner } from './postinstall-banner.js';
+
+// Check if this is a local install (npm_config_global is not set)
+const isGlobal = process.env.npm_config_global === 'true';
+
+if (!isGlobal) {
+  console.error('\n◼ Error: borg must be installed globally\n');
+  console.error('Please install with:');
+  console.error('  npm install -g borgmcp\n');
+  console.error('Local installation is not supported.\n');
+  process.exit(1);
+}
+
+// Global install — show instructions. Detect agent-CLI presence so the banner
+// never points a user with no Claude Code / Codex at `borg setup` (which would
+// dead-end). On any detection error, default to assuming an agent CLI is
+// present so we never emit a false "install an agent CLI" warning.
+let hasAgentCli = true;
+try {
+  hasAgentCli = installedCliNames(detectCliAvailability()).length > 0;
+} catch {
+  hasAgentCli = true;
+}
+
+console.log(composeInstallBanner(hasAgentCli));

package/src/readiness-probe.ts

@@ -0,0 +1,12 @@
+/** Environment contract for the short-lived `borg assimilate` MCP readiness child. */
+export const MCP_READINESS_PROBE_ENV = 'BORG_MCP_READINESS_PROBE';
+
+export function isMcpReadinessProbe(env: NodeJS.ProcessEnv = process.env): boolean {
+  return env[MCP_READINESS_PROBE_ENV] === '1';
+}
+
+export function readinessProbeEnv(
+  env: NodeJS.ProcessEnv = process.env
+): NodeJS.ProcessEnv {
+  return { ...env, [MCP_READINESS_PROBE_ENV]: '1' };
+}