borgmcp 3.10.0 → 3.11.0

package/src/claude.ts

@@ -42,8 +42,12 @@ import { runSpawn } from './spawn.js';
 import { buildClaudeLaunchArgs } from './claude-launch-args.js';
 import { parseCleanupArgs, runCleanup } from './cleanup-cmd.js';
 import { parseAssimilateArgs } from './parse-assimilate-args.js';
+import { parseQuickstartArgs } from './parse-quickstart-args.js';
+import { parseCloneArgs, safeCloneParseError } from './parse-clone-args.js';
 import { runAssimilate } from './assimilate-cmd.js';
 import { buildDefaultAssimilateDeps } from './assimilate-deps.js';
+import { buildDefaultQuickstartDeps, runQuickstart } from './quickstart-cmd.js';
+import { buildDefaultCloneDeps, runClone } from './clone-cmd.js';
 import {
   parseResetLocalSeatArgs,
   runResetLocalSeat,
@@ -251,6 +255,24 @@ async function main() {
     const code = await runAssimilateEntry(process.argv.slice(3));
     process.exit(code);
   }
+  if (process.argv[2] === 'clone') {
+    const parsed = parseCloneArgs(process.argv.slice(3));
+    if (!parsed.ok) {
+      process.stderr.write(chalk.red(`${consolePrefix()}◼ borg clone: ${safeCloneParseError(parsed)}\n`));
+      process.stderr.write(`Run \`borg clone --help\` for usage.\n`);
+      process.exit(1);
+    }
+    process.exit(await runClone(parsed.args, buildDefaultCloneDeps()));
+  }
+  if (process.argv[2] === 'quickstart') {
+    const parsed = parseQuickstartArgs(process.argv.slice(3));
+    if (!parsed.ok) {
+      process.stderr.write(chalk.red(`${consolePrefix()}◼ borg quickstart: ${parsed.error}\n`));
+      process.stderr.write(`Run \`borg quickstart --help\` for usage.\n`);
+      process.exit(1);
+    }
+    process.exit(await runQuickstart(parsed.args, buildDefaultQuickstartDeps()));
+  }
   if (process.argv[2] === 'reset-local-connection') {
     const parsed = parseResetLocalSeatArgs(process.argv.slice(3));
     if (!parsed.ok) {

package/src/cli-help.ts

@@ -51,6 +51,35 @@ export function launchAllHelpText(version: string): string {
   );
 }
 
+export function quickstartHelpText(version: string): string {
+  return (
+    `borg quickstart (borgmcp ${version}) — create, staff, and launch this repository's cube\n\n` +
+    `Usage:\n` +
+    `  borg quickstart [options]\n\n` +
+    `Options:\n` +
+    `  --template ${NEW_CUBE_TEMPLATE_OPTIONS}  Choose the new-cube template without prompting\n` +
+    `  --role <slug>[:<count>]            Fully specify the roster (repeatable)\n` +
+    `  --yes, -y                          Accept the displayed plan\n` +
+    `  --help, -h                         Show this help\n\n` +
+    `Quickstart requires a running Borg server and never starts one. Rerun the same\n` +
+    `command after a partial failure; existing drones are kept and skipped.\n`
+  );
+}
+
+export function cloneHelpText(version: string): string {
+  return (
+    `borg clone (borgmcp ${version}) — clone a repository and run quickstart\n\n` +
+    `Usage:\n` +
+    `  borg clone <repository-url> [directory] [--no-launch]\n\n` +
+    `Options:\n` +
+    `  --no-launch  Stop after the checkout is ready; do not create or launch a cube\n` +
+    `  --help, -h   Show this help\n\n` +
+    `A repeated command reuses a checkout only when its origin matches. Default\n` +
+    `destination names avoid non-repository collisions. Credential-bearing URLs are\n` +
+    `refused; use a Git credential helper or SSH configuration instead.\n`
+  );
+}
+
 export function seatsHelpText(version: string): string {
   return (
     `borg drones (borgmcp ${version}) — list this machine's registered drones\n\n` +
@@ -91,7 +120,9 @@ export function clientSubcommandHelpText(
   if (!args.some(isHelpFlag)) return null;
   switch (command) {
     case 'setup': return setupHelpText(version);
+    case 'clone': return cloneHelpText(version);
     case 'assimilate': return assimilateHelpText(version);
+    case 'quickstart': return quickstartHelpText(version);
     case 'reset-local-connection': return resetLocalSeatHelpText(version);
     case 'recover-enrollment': return recoverEnrollmentHelpText(version);
     case 'cleanup': return cleanupHelpText(version);
@@ -107,7 +138,7 @@ export function setupNextStepsText(): string {
   return (
     `◼ Next steps:\n` +
     `1. Run \`borg server start\` and leave that terminal open.\n` +
-    `2. In a second terminal, cd into your project's Git repository and run \`borg assimilate\`.\n`
+    `2. In a second terminal, cd into your project's Git repository and run \`borg quickstart\`.\n`
   );
 }
 
@@ -129,6 +160,8 @@ export function topLevelHelpText(version: string): string {
     `  borg setup               Set up borg MCP server + agent CLI integration\n` +
     `  borg update              Update the client and installed local server together\n` +
     `  borg doctor              Check agent hook commands, versions, configs, and the OpenCode plugin\n` +
+    `  borg clone <url> [dir]   Clone a repository, then create and launch its cube\n` +
+    `  borg quickstart          Create a cube and a drone for every role, then launch them\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` +

package/src/clone-cmd.ts

@@ -0,0 +1,243 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readdirSync, rmSync, statSync } from 'node:fs';
+import { basename, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { hasCloneCredentials, redactCloneSecrets } from './clone-security.js';
+import type { CloneArgs } from './parse-clone-args.js';
+import { buildDefaultQuickstartDeps, runQuickstart } from './quickstart-cmd.js';
+import { shellEscape } from './shell-escape.js';
+
+export interface GitRunResult {
+  status: number | null;
+  stdout: string;
+  stderr: string;
+}
+
+export interface CloneDeps {
+  cwd: () => string;
+  chdir: (path: string) => void;
+  runSync: (cmd: string, args: string[], cwd?: string) => GitRunResult;
+  pathExists: (path: string) => boolean;
+  isDirectory: (path: string) => boolean;
+  readDirectory: (path: string) => string[];
+  createDirectory: (path: string) => boolean;
+  removeTree: (path: string) => void;
+  quickstart: (cwd: string) => Promise<number>;
+  stdout: (text: string) => void;
+  stderr: (text: string) => void;
+}
+
+const CONTROL_RE = /[\u0000-\u001f\u007f]/;
+const ALLOWED_SCHEMES = new Set(['file:', 'git:', 'git+ssh:', 'http:', 'https:', 'ssh:']);
+const SCP_REMOTE_RE = /^[^@\s/:]+@[^:\s]+:[^\s]+$/;
+
+function defaultRunSync(cmd: string, args: string[], cwd?: string): GitRunResult {
+  const result = spawnSync(cmd, args, { cwd, encoding: 'utf8' });
+  return {
+    status: result.status,
+    stdout: result.stdout ?? '',
+    stderr: result.stderr ?? (result.error instanceof Error ? result.error.message : ''),
+  };
+}
+
+export function buildDefaultCloneDeps(): CloneDeps {
+  return {
+    cwd: () => process.cwd(),
+    chdir: (path) => process.chdir(path),
+    runSync: defaultRunSync,
+    pathExists: existsSync,
+    isDirectory: (path) => {
+      try { return statSync(path).isDirectory(); } catch { return false; }
+    },
+    readDirectory: (path) => readdirSync(path),
+    createDirectory: (path) => {
+      mkdirSync(dirname(path), { recursive: true });
+      try {
+        mkdirSync(path);
+        return true;
+      } catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'EEXIST') return false;
+        throw error;
+      }
+    },
+    removeTree: (path) => rmSync(path, { recursive: true, force: true }),
+    quickstart: async (cwd) => {
+      process.chdir(cwd);
+      return runQuickstart({ roles: [], yes: false }, buildDefaultQuickstartDeps());
+    },
+    stdout: (text) => process.stdout.write(text),
+    stderr: (text) => process.stderr.write(text),
+  };
+}
+
+export function validateCloneRepositoryUrl(value: string): { ok: true } | { ok: false; error: string } {
+  if (!value || value.trim() !== value || /\s/.test(value) || CONTROL_RE.test(value)) {
+    return { ok: false, error: 'repository URL contains whitespace or control characters' };
+  }
+  if (value.startsWith('-')) return { ok: false, error: 'repository URL must not start with a hyphen' };
+  if (hasCloneCredentials(value)) {
+    return { ok: false, error: 'credential-bearing repository URLs are not accepted; use a credential helper or SSH configuration instead' };
+  }
+  if (SCP_REMOTE_RE.test(value)) return { ok: true };
+  const scheme = /^([a-z][a-z0-9+.-]*):/i.exec(value)?.[1];
+  if (!scheme) return { ok: true }; // Local path.
+  if (!value.toLowerCase().startsWith(`${scheme.toLowerCase()}://`) && scheme.toLowerCase() !== 'file') {
+    return { ok: false, error: 'repository URL is not a supported hierarchical URL' };
+  }
+  try {
+    const parsed = new URL(value);
+    if (!ALLOWED_SCHEMES.has(parsed.protocol)) return { ok: false, error: `unsupported repository URL scheme ${parsed.protocol}` };
+    if (parsed.search || parsed.hash) return { ok: false, error: 'repository URLs with query strings or fragments are not accepted' };
+    if (parsed.protocol !== 'file:' && !parsed.hostname) return { ok: false, error: 'repository URL must include a host' };
+    if (!parsed.pathname || parsed.pathname === '/') return { ok: false, error: 'repository URL must include a repository path' };
+    return { ok: true };
+  } catch {
+    return { ok: false, error: 'repository URL is not valid' };
+  }
+}
+
+function sourceName(value: string): string {
+  let leaf = value;
+  try {
+    const parsed = new URL(value);
+    leaf = parsed.protocol === 'file:' ? fileURLToPath(parsed) : parsed.pathname;
+  } catch {
+    if (SCP_REMOTE_RE.test(value)) leaf = value.slice(value.indexOf(':') + 1);
+  }
+  const name = basename(leaf.replace(/\/+$/, '')).replace(/\.git$/i, '')
+    .replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');
+  return name || 'repository';
+}
+
+function remoteKey(value: string, base: string): string {
+  if (SCP_REMOTE_RE.test(value)) {
+    const colon = value.indexOf(':');
+    const login = value.slice(0, colon);
+    const at = login.lastIndexOf('@');
+    const user = login.slice(0, at);
+    const host = login.slice(at + 1).toLowerCase();
+    return `ssh://${user}@${host}/${value.slice(colon + 1).replace(/\/+$/, '').replace(/\.git$/i, '')}`;
+  }
+  try {
+    const parsed = new URL(value);
+    if (parsed.protocol === 'file:') return `file:${resolve(fileURLToPath(parsed))}`;
+    const user = parsed.username ? `${parsed.username}@` : '';
+    const port = parsed.port ? `:${parsed.port}` : '';
+    return `${parsed.protocol}//${user}${parsed.hostname.toLowerCase()}${port}${parsed.pathname.replace(/\/+$/, '').replace(/\.git$/i, '')}`;
+  } catch {
+    return `file:${resolve(base, value)}`;
+  }
+}
+
+function readOrigin(deps: CloneDeps, directory: string): string | null {
+  const result = deps.runSync('git', ['remote', 'get-url', 'origin'], directory);
+  return result.status === 0 && result.stdout.trim() ? result.stdout.trim() : null;
+}
+
+function repositoryAt(deps: CloneDeps, directory: string): boolean {
+  return deps.runSync('git', ['rev-parse', '--is-inside-work-tree'], directory).status === 0;
+}
+
+function validateDestination(value: string): string | null {
+  if (!value || value.trim() !== value || CONTROL_RE.test(value) || value.startsWith('-') || hasCloneCredentials(value)) {
+    return 'destination contains an unsafe path value';
+  }
+  return null;
+}
+
+function chooseDestination(deps: CloneDeps, args: CloneArgs): { path: string } | { error: string } {
+  const base = deps.cwd();
+  if (args.destination !== undefined) {
+    const error = validateDestination(args.destination);
+    return error ? { error } : { path: resolve(base, args.destination) };
+  }
+  const name = sourceName(args.repositoryUrl);
+  for (let n = 1; n < 10_000; n += 1) {
+    const candidate = resolve(base, n === 1 ? name : `${name}-${n}`);
+    if (!deps.pathExists(candidate)) return { path: candidate };
+    if (deps.isDirectory(candidate) && repositoryAt(deps, candidate)) {
+      const origin = readOrigin(deps, candidate);
+      if (origin && !hasCloneCredentials(origin) && remoteKey(origin, candidate) === remoteKey(args.repositoryUrl, base)) {
+        return { path: candidate };
+      }
+      if (n === 1) return { error: `existing checkout at ${candidate} points at another remote; choose an explicit destination` };
+    }
+  }
+  return { error: `could not find a collision-safe destination for ${name}` };
+}
+
+export async function runClone(args: CloneArgs, rawDeps: CloneDeps): Promise<number> {
+  const deps: CloneDeps = {
+    ...rawDeps,
+    stdout: (text) => rawDeps.stdout(redactCloneSecrets(text)),
+    stderr: (text) => rawDeps.stderr(redactCloneSecrets(text)),
+  };
+  const valid = validateCloneRepositoryUrl(args.repositoryUrl);
+  if (!valid.ok) {
+    deps.stderr(`borg clone: ${valid.error}.\n`);
+    return 1;
+  }
+  const selected = chooseDestination(deps, args);
+  if ('error' in selected) {
+    deps.stderr(`borg clone: ${selected.error}.\n`);
+    return 1;
+  }
+  const destination = selected.path;
+  let cloned = false;
+  const destinationExisted = deps.pathExists(destination);
+  const emptyDestination = destinationExisted && deps.isDirectory(destination) && deps.readDirectory(destination).length === 0;
+  if (destinationExisted && !emptyDestination) {
+    if (!deps.isDirectory(destination) || !repositoryAt(deps, destination)) {
+      deps.stderr(`borg clone: destination ${destination} exists and is not a Git checkout; it was left untouched.\n`);
+      return 1;
+    }
+    const origin = readOrigin(deps, destination);
+    if (!origin || hasCloneCredentials(origin)) {
+      deps.stderr(`borg clone: the existing checkout has no safe, readable origin remote; it was left untouched.\n`);
+      return 1;
+    }
+    if (remoteKey(origin, destination) !== remoteKey(args.repositoryUrl, deps.cwd())) {
+      deps.stderr(`borg clone: remote mismatch at ${destination}; existing ${origin}, requested ${args.repositoryUrl}. The checkout was left untouched.\n`);
+      return 1;
+    }
+    deps.stdout(`Reusing existing checkout at ${destination}; its origin remote matches.\n`);
+  } else {
+    const createdDestination = destinationExisted ? false : deps.createDirectory(destination);
+    if (!destinationExisted && !createdDestination) {
+      deps.stderr(`borg clone: destination ${destination} appeared while preparing the clone; it was left untouched. Retry with another directory.\n`);
+      return 1;
+    }
+    const result = deps.runSync('git', ['clone', '--', args.repositoryUrl, destination], deps.cwd());
+    if (result.status !== 0) {
+      if (createdDestination && deps.pathExists(destination)) {
+        deps.removeTree(destination);
+      }
+      deps.stderr(
+        `borg clone: clone failed${result.stderr.trim() ? `: ${result.stderr.trim()}` : ''}.\n` +
+        `Rollback: ${destinationExisted
+          ? `the pre-existing empty destination ${destination} was preserved; inspect it for partial Git files`
+          : deps.pathExists(destination) ? `partial checkout remains at ${destination}` : `the directory borg created at ${destination} was removed`}.\n`,
+      );
+      return 1;
+    }
+    cloned = true;
+    deps.stdout(`Cloned ${sourceName(args.repositoryUrl)} into ${destination}.\n`);
+  }
+
+  if (args.noLaunch) {
+    deps.stdout(
+      `Checkout ready at ${destination}. No cube or drone was created.\n` +
+      `Next: cd ${shellEscape(destination)} && borg quickstart\n`,
+    );
+    return 0;
+  }
+  deps.chdir(destination);
+  const code = await deps.quickstart(destination);
+  if (code !== 0) {
+    deps.stderr(
+      `The checkout${cloned ? '' : ' you already had'} is ready at ${destination}, but quickstart did not finish. ` +
+      `It was left untouched; cd there and run \`borg quickstart\` again.\n`,
+    );
+  }
+  return code;
+}

package/src/clone-security.ts

@@ -0,0 +1,40 @@
+/** Redaction and fail-closed credential detection for untrusted Git remotes. */
+
+const URL_USERINFO_RE = /([a-z][a-z0-9+.-]*:\/\/)([^/\s@]+)@/gi;
+const URL_SUFFIX_RE = /([a-z][a-z0-9+.-]*:\/\/[^\s?#)]+)([?#])[^\s)]*/gi;
+const NAMED_SECRET_RE = /([?&](?:access[_-]?token|api[_-]?key|auth(?:entication)?|credential|password|passwd|private[_-]?key|secret|token)=)[^&#\s)]+/gi;
+const NAMED_SECRET_TEST_RE = new RegExp(NAMED_SECRET_RE.source, 'i');
+const OPTION_SECRET_RE = /((?:^|[\s("'`])--(?:access[_-]?token|api[_-]?key|auth(?:entication)?|credential|password|passwd|private[_-]?key|secret|token)=)[^\s)]*/gi;
+const SCP_REMOTE_RE = /^[^@\s/:]+@[^:\s]+:[^\s]+$/;
+
+export function redactCloneSecrets(value: string): string {
+  return value
+    .replace(URL_USERINFO_RE, '$1<credentials>@')
+    .replace(URL_SUFFIX_RE, '$1$2<redacted>')
+    .replace(NAMED_SECRET_RE, '$1<redacted>')
+    .replace(OPTION_SECRET_RE, '$1<redacted>')
+    .replace(/(^|[\s("'`])[^/\s:@]+:[^@\s/]+@(?=[^\s/])/g, '$1<credentials>@');
+}
+
+/**
+ * True means the value must never reach subprocess argv, output, or Git config.
+ * Opaque `scheme:...@...` forms fail closed; URL() accepts those but exposes no
+ * username/password fields, which is precisely the class that escaped the old flow.
+ */
+export function hasCloneCredentials(value: string): boolean {
+  if (NAMED_SECRET_TEST_RE.test(value)) return true;
+  if (SCP_REMOTE_RE.test(value)) return false;
+  const scheme = /^([a-z][a-z0-9+.-]*):/i.exec(value)?.[1].toLowerCase();
+  if (scheme && !value.toLowerCase().startsWith(`${scheme}://`) && scheme !== 'file') {
+    return value.includes('@');
+  }
+  try {
+    const parsed = new URL(value);
+    if (parsed.protocol === 'ssh:' || parsed.protocol === 'git+ssh:') {
+      return parsed.password.length > 0;
+    }
+    return parsed.username.length > 0 || parsed.password.length > 0;
+  } catch {
+    return /[^/\s:@]+:[^@\s/]+@/.test(value);
+  }
+}

package/src/launch-all-cmd.ts

@@ -16,6 +16,9 @@ import { runPastelistBackend } from './backends/launch-all-pastelist.js';
 
 type Backend = 'tmux' | 'terminals' | 'pastelist';
 
+/** Internal strict-seam result: requested sessions were not dispatched. */
+export const LAUNCH_ALL_NO_DISPATCH_EXIT_CODE = 2;
+
 const TMUX_INSTALL_HINT =
   'borg launch-all: tmux not found.\n' +
   '  macOS:  brew install tmux\n' +
@@ -239,6 +242,12 @@ export interface RunLaunchAllOptions {
   sleep?: (ms: number) => Promise<void>;
   nowISO?: () => string;
   borgPath?: string;
+  /** Internal quickstart filter: launch only the requested staffed roster. */
+  droneIds?: readonly string[];
+  /** Fail when any requested registered drone cannot be discovered or launched. */
+  requireAllRequested?: boolean;
+  /** Internal resolved target avoids ambiguous same-name lookup during composition. */
+  targetCube?: { cubeId: string; name: string };
 }
 
 export async function runLaunchAll(
@@ -253,7 +262,7 @@ export async function runLaunchAll(
   const launchDelayMs = resolveLaunchDelayMs(args.flags.launchDelayMs, deps.getEnv('BORG_LAUNCH_DELAY_MS'));
 
   // 1. resolve target cube
-  const resolved = await resolveTargetCube(args, deps);
+  const resolved = opts.targetCube ?? await resolveTargetCube(args, deps);
   if ('error' in resolved) {
     deps.stderr(`borg launch-all: ${resolved.error}\n`);
     return 1;
@@ -264,7 +273,18 @@ export async function runLaunchAll(
   sweepStaleLocks(deps, cubeId, now());
 
   // 3. discover candidates
-  const discovered = await discoverDroneCandidates({ targetCubeId: cubeId, only: args.flags.only }, deps);
+  let discovered = await discoverDroneCandidates({ targetCubeId: cubeId, only: args.flags.only }, deps);
+  if (opts.droneIds !== undefined) {
+    const requested = new Set(opts.droneIds);
+    discovered = discovered.filter((candidate) => requested.has(candidate.droneId));
+    if (opts.requireAllRequested && discovered.length !== requested.size) {
+      deps.stderr(
+        `borg launch-all: found ${discovered.length} of ${requested.size} requested registered drone worktrees; ` +
+        'nothing was launched. Run `borg drones` to inspect the missing local registration.\n',
+      );
+      return 1;
+    }
+  }
   if (discovered.length === 0) {
     if (args.flags.only !== undefined) {
       deps.stdout(`No worktrees matched --only '${args.flags.only}' for cube '${cubeName}'\n`);
@@ -392,6 +412,14 @@ export async function runLaunchAll(
     }
     launchable.push(c);
   }
+  const terminalSkipCount = evictedCount + revokedCount + rejectedCount + trustMismatchCount + credentialRejectedCount;
+  if (opts.requireAllRequested && terminalSkipCount > 0) {
+    deps.stderr(
+      `borg launch-all: ${terminalSkipCount} requested registered drone(s) are not launchable; ` +
+      'nothing was launched. Resolve the cause reported above, then retry.\n',
+    );
+    return 1;
+  }
   if (launchable.length === 0) {
     // Accurate cause counts — an all-rejected sweep must NOT claim "evicted"
     // (and vice-versa). Only name a cause when at least one seat hit it.
@@ -441,6 +469,13 @@ export async function runLaunchAll(
     deps.stderr(sel.hardFail);
     return 1;
   }
+  if (sel.backend === 'pastelist' && opts.requireAllRequested) {
+    deps.stderr(
+      'borg launch-all: pastelist mode prints commands for manual use but does not launch sessions; ' +
+      'nothing was launched. Run `borg launch-all` separately to print the commands.\n',
+    );
+    return LAUNCH_ALL_NO_DISPATCH_EXIT_CODE;
+  }
   const sessionName = sanitizeSessionName(cubeName);
   const launchStartISO = nowISO();
 

package/src/parse-clone-args.ts

@@ -0,0 +1,44 @@
+import { redactCloneSecrets } from './clone-security.js';
+
+export interface CloneArgs {
+  repositoryUrl: string;
+  destination?: string;
+  noLaunch: boolean;
+}
+
+export type ParseCloneResult =
+  | { ok: true; args: CloneArgs }
+  | { ok: false; error: string };
+
+export function parseCloneArgs(rawArgs: readonly string[]): ParseCloneResult {
+  let repositoryUrl: string | undefined;
+  let destination: string | undefined;
+  let noLaunch = false;
+  for (const arg of rawArgs) {
+    if (arg === '--no-launch') {
+      if (noLaunch) return { ok: false, error: '--no-launch was provided more than once' };
+      noLaunch = true;
+      continue;
+    }
+    if (arg.startsWith('-')) {
+      const option = arg.startsWith('--') ? arg.split('=', 1)[0] : arg.slice(0, 2);
+      return { ok: false, error: `unknown option ${option}; the only option is --no-launch` };
+    }
+    if (repositoryUrl === undefined) repositoryUrl = arg;
+    else if (destination === undefined) destination = arg;
+    else return { ok: false, error: 'unexpected extra argument' };
+  }
+  if (!repositoryUrl) return { ok: false, error: 'a repository URL is required' };
+  return {
+    ok: true,
+    args: {
+      repositoryUrl,
+      ...(destination === undefined ? {} : { destination }),
+      noLaunch,
+    },
+  };
+}
+
+export function safeCloneParseError(result: Extract<ParseCloneResult, { ok: false }>): string {
+  return redactCloneSecrets(result.error);
+}

package/src/parse-quickstart-args.ts

@@ -0,0 +1,54 @@
+import { NEW_CUBE_TEMPLATE_PRESENTATIONS } from 'borgmcp-shared/templates';
+
+export interface QuickstartRoleRequest {
+  slug: string;
+  count: number;
+}
+
+export interface QuickstartArgs {
+  template?: string;
+  roles: QuickstartRoleRequest[];
+  yes: boolean;
+}
+
+export type ParseQuickstartResult =
+  | { ok: true; args: QuickstartArgs }
+  | { ok: false; error: string };
+
+const templates = new Set<string>(NEW_CUBE_TEMPLATE_PRESENTATIONS.map(({ name }) => name));
+
+function parseRole(value: string): QuickstartRoleRequest | null {
+  const match = /^([a-z0-9]+(?:-[a-z0-9]+)*)(?::([1-9]\d*))?$/.exec(value);
+  if (!match) return null;
+  const count = match[2] === undefined ? 1 : Number(match[2]);
+  return Number.isSafeInteger(count) ? { slug: match[1], count } : null;
+}
+
+export function parseQuickstartArgs(rawArgs: readonly string[]): ParseQuickstartResult {
+  const args: QuickstartArgs = { roles: [], yes: false };
+  for (let i = 0; i < rawArgs.length; i += 1) {
+    const arg = rawArgs[i];
+    if (arg === '--yes' || arg === '-y') {
+      args.yes = true;
+      continue;
+    }
+    if (arg === '--template') {
+      const value = rawArgs[++i];
+      if (!value) return { ok: false, error: '--template requires software-dev, starter, or local-model' };
+      if (!templates.has(value)) return { ok: false, error: `unknown template '${value}'; choose software-dev, starter, or local-model` };
+      if (args.template !== undefined) return { ok: false, error: '--template was provided more than once' };
+      args.template = value;
+      continue;
+    }
+    if (arg === '--role') {
+      const value = rawArgs[++i];
+      if (!value) return { ok: false, error: '--role requires <slug>[:<count>]' };
+      const role = parseRole(value);
+      if (!role) return { ok: false, error: `invalid role '${value}'; use <slug>[:<positive-count>]` };
+      args.roles.push(role);
+      continue;
+    }
+    return { ok: false, error: `unknown option: ${arg}. Supported: --template, --role, --yes/-y` };
+  }
+  return { ok: true, args };
+}