@bhooai/nexus-cli 0.1.0

package/src/commands/node.ts

@@ -0,0 +1,101 @@
+import { loadConfigAuto } from '../../../nexus-core/src/index.js';
+import { NodeAgent, nodeIdFor } from '@bhooai/nexus-cluster';
+const GREEN = '\x1b[32m';
+const RED = '\x1b[31m';
+const CYAN = '\x1b[36m';
+const DIM = '\x1b[2m';
+const RESET = '\x1b[0m';
+
+/**
+ * `nexus node <subcommand>` - run THIS machine as a cluster node.
+ *
+ *   node id --role <role>                  print this node's stable id
+ *   node serve --role=<role> [--port]     start the agent + role service
+ *
+ * Onboarding per the mesh flow:
+ *   server$ nexus node serve --role=backend
+ *   -> prints agent URL + pairing token; paste the URL on the central:
+ *   central$ nexus cluster link http://<this-host>:7575
+ */
+export async function node(args: string[]): Promise<number> {
+  const sub = args[0];
+  const role = argValue(args, '--role') ?? 'backend';
+
+  const cfg = await loadConfigAuto({ root: process.cwd() });
+  const token = cfg.cluster.token;
+  const port = Number(argValue(args, '--port') ?? '7575');
+  const agentHost = cfg.cluster.nodeAgentHost;
+  const defaultPort = Number.isInteger(cfg.cluster.nodeAgentPort) ? cfg.cluster.nodeAgentPort : 7575;
+  const effectivePort = Number.isInteger(port) ? port : defaultPort;
+
+  if (sub === 'id') {
+    console.log(nodeIdFor(process.cwd(), role as never));
+    return 0;
+  }
+
+  if (sub === 'serve') {
+    const description = roleDescription(role);
+    const command = serviceCommand(role, cfg);
+    const agent = new NodeAgent({
+      projectRoot: process.cwd(),
+      role: role as never,
+      tier: 'dev',
+      port: effectivePort,
+      token,
+      version: '0.1.0',
+      services: serviceUrls(role, cfg),
+      serviceCommand: command,
+      advertisedUrl: process.env.NEXUS_NODE_ADVERTISED_URL,
+    });
+    await agent.listen(agentHost);
+    console.log(`${CYAN}node-agent${RESET} ready - role ${role} ${description}`);
+    console.log(`  ${GREEN}agent url:  http://${agentHost}:${effectivePort}${RESET}`);
+    console.log(`  ${GREEN}token:      ${token ? `${token}` : '<empty - set cluster.token>'}`)
+    console.log(`  ${DIM}link it from the central:  nexus cluster link http://${agentHost}:${effectivePort}${RESET}`);
+    if (command.length) {
+      agent.startService();
+      console.log(`  started role service: ${command.join(' ')}`);
+    }
+    // Hold the process.
+    return await new Promise<number>(() => {});
+  }
+
+  console.log('Usage: nexus node <id|serve> [--role=backend|files|database|ai] [--port=N]');
+  return 1;
+}
+
+function argValue(args: string[], name: string): string | undefined {
+  const i = args.indexOf(name);
+  if (i >= 0) return args[i + 1];
+  return args.find((a) => a.startsWith(`${name}=`))?.slice(name.length + 1);
+}
+
+function roleDescription(role: string): string {
+  switch (role) {
+    case 'backend': return '(API core)';
+    case 'files': return '(static + uploads storage)';
+    case 'database': return '(Mongo + Redis)';
+    case 'ai': return '(AI inference engine)';
+    default: return '';
+  }
+}
+
+function serviceCommand(role: string, cfg: Awaited<ReturnType<typeof loadConfigAuto>>): string[] {
+  switch (role) {
+    case 'backend':
+      return ['tsx', 'apps/backend/src/main.ts'];
+    case 'ai':
+      return ['python', 'main.py'];
+    case 'files':
+      // Fall back to the framework uploads server launcher if present.
+      return ['tsx', 'apps/backend/src/main.ts'];
+    case 'database':
+      return ['tsx', 'apps/backend/src/main.ts'];
+    default:
+      return [];
+  }
+}
+
+function serviceUrls(role: string, cfg: Awaited<ReturnType<typeof loadConfigAuto>>): Partial<Record<'backend' | 'files' | 'database' | 'ai', string>> {
+  return { [role]: `http://localhost:${cfg.server.port}` };
+}

package/src/commands/pysetup.ts

@@ -0,0 +1,136 @@
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { versionOf } from '../util.js';
+import { isInteractive as wizardInteractive, confirm, prompt, closeWizard } from '../wizard.js';
+
+/**
+ * Install the Python AI server dependencies (plus any extra packages).
+ *
+ * Locates `apps/ai-server/requirements.txt` (or a path given with --requirements),
+ * optionally creates a virtualenv with --venv, and streams pip output through so the
+ * user can watch progress.
+ *
+ *   nexus pysetup                        install from requirements.txt
+ *   nexus pysetup openai pandas          install requirements.txt + extra packages
+ *   nexus pysetup --venv                 create ./apps/ai-server/.venv and install into it
+ *   nexus pysetup --interactive          prompt for venv y/n + python path (TTY only)
+ *   nexus pysetup --upgrade              upgrade existing packages
+ *   nexus pysetup --python C:/Python/Python314/python.exe
+ *   nexus pysetup --requirements ./my-requirements.txt
+ */
+export async function pysetup(args: string[]): Promise<number> {
+  let opts: PyOpts = parseArgs(args);
+
+  // -- interactive wizard mode (TTY only) ---------------------------
+  if (opts.interactive && wizardInteractive()) {
+    opts = await interactivePrompt(opts);
+    closeWizard();
+  }
+
+  const reqFile = resolve(process.cwd(), opts.requirements || findRequirementsFile(process.cwd()));
+  const py = await resolvePython(opts.python);
+
+  if (!opts.requirements && !findRequirementsFile(process.cwd())) {
+    console.error('Could not find apps/ai-server/requirements.txt - pass one with --requirements <path>.');
+    return 1;
+  }
+  if (!existsSync(reqFile)) {
+    console.error(`requirements file not found: ${reqFile}`);
+    return 1;
+  }
+  if (!py) {
+    console.error(`Python interpreter not found (tried python / python3). Pass --python <path>.`);
+    return 1;
+  }
+
+  const venvPy = opts.venv ? join(opts.venvDir, process.platform === 'win32' ? 'Scripts/python.exe' : 'bin/python') : py;
+  const createVenv = async () => {
+    if (existsSync(venvPy)) return 0;
+    console.log(`\n\x1b[36m[pysetup]\x1b[0m creating venv at ${opts.venvDir}`);
+    return run(py, ['-m', 'venv', opts.venvDir]);
+  };
+
+  console.log(`\n\x1b[36m[pysetup]\x1b[0m installing python packages`);
+  console.log(`  python      : ${py}${opts.venv ? ` -> ${venvPy}` : ''}`);
+  console.log(`  requirements: ${reqFile}`);
+  console.log(`  extras      : ${opts.extras.length ? opts.extras.join(', ') : '(none)'}`);
+  if (opts.venv) console.log(`  venv        : ${opts.venvDir}`);
+
+  if (opts.venv) {
+    const venvCode = await createVenv();
+    if (venvCode !== 0) return venvCode;
+  }
+
+  const pipArgs = ['-m', 'pip', 'install'];
+  if (opts.upgrade) pipArgs.push('--upgrade');
+  pipArgs.push('-r', reqFile, ...opts.extras);
+
+  const code = await run(venvPy ?? py, pipArgs);
+  if (code !== 0) {
+    console.error(`\n[pysetup] install failed (exit ${code}).`);
+    return code;
+  }
+  console.log(`\n\x1b[32m[pysetup]\x1b[0m done - ${opts.extras.length ? opts.extras.join(' ') : 'core requirements'} installed.`);
+  return 0;
+}
+
+/** Interactive prompts for venv + python path. Returns updated opts. */
+async function interactivePrompt(opts: PyOpts): Promise<PyOpts> {
+  const wantVenv = await confirm('Create a virtualenv for the AI server?', opts.venv);
+  const pythonPath = await prompt('Python interpreter path (blank = auto-detect)', opts.python || '');
+  return { ...opts, venv: wantVenv, python: pythonPath.trim() };
+}
+
+interface PyOpts { python: string; requirements: string; extras: string[]; upgrade: boolean; venv: boolean; venvDir: string; interactive: boolean }
+
+function parseArgs(args: string[]): PyOpts {
+  let python = '';
+  let requirements = '';
+  let upgrade = false;
+  let venv = false;
+  let interactive = false;
+  const extras: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--python') { python = args[++i] ?? ''; continue; }
+    if (a === '--requirements' || a === '-r') { requirements = args[++i] ?? ''; continue; }
+    if (a === '--upgrade' || a === '-U') { upgrade = true; continue; }
+    if (a === '--venv') { venv = true; continue; }
+    if (a === '--interactive') { interactive = true; continue; }
+    if (a.startsWith('--') || a.startsWith('-')) continue;
+    extras.push(a);
+  }
+  const reqDir = requirements ? resolve(requirements) : join(process.cwd(), 'apps', 'ai-server');
+  return { python, requirements, extras, upgrade, venv, venvDir: join(reqDir, '.venv'), interactive };
+}
+
+/** Find a requirements.txt under the cwd that belongs to the AI server. */
+function findRequirementsFile(cwd: string): string {
+  const candidates = [
+    join(cwd, 'apps', 'ai-server', 'requirements.txt'),
+    join(cwd, 'apps', 'server', 'requirements.txt'),
+    join(cwd, 'requirements.txt'),
+  ];
+  return candidates.find((p) => existsSync(p)) ?? '';
+}
+
+async function resolvePython(explicit: string): Promise<string> {
+  if (explicit) return existsSync(explicit) ? explicit : explicit;
+  const candidates = process.platform === 'win32' ? ['python', 'py'] : ['python3', 'python'];
+  for (const c of candidates) {
+    if (await versionOf(c)) return c;
+  }
+  return '';
+}
+
+function run(cmd: string, args: string[]): Promise<number> {
+  return new Promise((resolveRun) => {
+    const child = spawn(cmd, args, { stdio: 'inherit', shell: process.platform === 'win32' });
+    child.on('error', (err) => {
+      console.error(`\x1b[31m[pysetup]\x1b[0m failed to run ${cmd}: ${err.message}`);
+      resolveRun(1);
+    });
+    child.on('close', (code) => resolveRun(code ?? 0));
+  });
+}

package/src/commands/sync.ts

@@ -0,0 +1,116 @@
+import { loadConfigAuto } from '../../../nexus-core/src/index.js';
+import {
+  readFingerprint,
+  syncConfig,
+  type FileSyncReport,
+  type SyncReport,
+} from '../config-sync.js';
+
+const GREEN = '\x1b[32m';
+const CYAN = '\x1b[36m';
+const YELLOW = '\x1b[33m';
+const DIM = '\x1b[2m';
+const BOLD = '\x1b[1m';
+const RESET = '\x1b[0m';
+
+/**
+ * `nexus sync` - rewrite every derived artifact (Dockerfile, docker.* helpers,
+ * bin/serve-all.mjs, apps/admin/package.json, the shared project-info DB) to
+ * match the single `nexus.config.ts` source of truth.
+ *
+ * Returns the process exit code and always prints the resolved values so the
+ * "one config prints everywhere" contract is visible.
+ */
+export async function syncCommand(args: string[] = []): Promise<number> {
+  const root = process.cwd();
+  const opts = {
+    write: !args.includes('--check') && !args.includes('--dry-run'),
+    db: !args.includes('--no-db'),
+  };
+
+  if (!opts.write) {
+    process.stdout.write(`${DIM}  nexus sync - dry run (nothing written)${RESET}\n\n`);
+  }
+
+  const cfg = await loadConfigAuto({ root });
+  const report = await syncConfig(root, cfg, opts);
+
+  printReport(report, root);
+
+  if (!opts.write) {
+    process.stdout.write(`\n  ${YELLOW}Dry run - run \`nexus sync\` (no flag) to write the changes.${RESET}\n`);
+  }
+
+  const changed = report.files.some((f) => f.status === 'updated');
+  if (changed) {
+    process.stdout.write(`\n  ${GREEN}Synced. Run \`nexus dev\` to boot the stack on the new values.${RESET}\n`);
+  } else {
+    process.stdout.write(`\n  ${DIM}Everything is already in sync.${RESET}\n`);
+  }
+
+  return 0;
+}
+
+/** Print the per-value summary + per-file status table. */
+function printReport(report: SyncReport, root: string): void {
+  const v = report.values;
+
+  process.stdout.write(`\n${BOLD}  *  Nexus config sync${RESET} ${DIM}${root}${RESET}\n\n`);
+
+  process.stdout.write(`  ${CYAN}Value${RESET}${' '.repeat(12 - 5)}Config -> everywhere\n`);
+  process.stdout.write(`  -----------------------------\n`);
+  const rows: Array<[string, string]> = [
+    ['backend', `${v.serverPort}`],
+    ['frontend', `${v.frontendPort}`],
+    ['admin', `${v.adminPort}`],
+    ['node agent', `${v.nodePort}`],
+    ['cluster LB', `${v.lbPort}`],
+    ['AI server', `${v.aiPort}`],
+    ['database', `${v.dbName}`],
+  ];
+  for (const [label, value] of rows) {
+    const pad = label.padEnd(10);
+    process.stdout.write(`  ${CYAN}${pad}${RESET} ${value}\n`);
+  }
+
+  process.stdout.write('\n');
+  for (const f of report.files) {
+    const status = statusLabel(f);
+    process.stdout.write(`  ${f.file.padEnd(28)}${status}\n`);
+    if (f.status === 'updated' && f.changes.length > 0) {
+      for (const line of f.changes) {
+        process.stdout.write(`    ${DIM}${line}${RESET}\n`);
+      }
+    }
+  }
+
+  process.stdout.write(`\n  ${BOLD}Database${RESET}  ${dbLabel(report.db)}\n`);
+
+  if (readFingerprint(root)) {
+    process.stdout.write(`  ${DIM}fingerprint ${report.fingerprint}${RESET}\n`);
+  }
+}
+
+function statusLabel(f: FileSyncReport): string {
+  switch (f.status) {
+    case 'updated':
+      return `${GREEN}updated${RESET}`;
+    case 'in-sync':
+      return `${DIM}in sync${RESET}`;
+    case 'missing':
+      return `${YELLOW}missing${RESET}`;
+    default:
+      return `${YELLOW}no match - review${RESET}`;
+  }
+}
+
+function dbLabel(db: SyncReport['db']): string {
+  switch (db) {
+    case 'updated':
+      return `${GREEN}project record upserted${RESET}`;
+    case 'failed':
+      return `${YELLOW}unreachable - skipped${RESET}`;
+    default:
+      return `${DIM}skipped${RESET}`;
+  }
+}

package/src/commands/uninstall.ts

@@ -0,0 +1,287 @@
+import { existsSync, rmSync, chmodSync, readdirSync, statSync } from 'node:fs';
+import { resolve, basename, join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { loadConfigAuto } from '../../../nexus-core/src/index.js';
+import {
+  resolveProjectInfo,
+  connectProjectInfo,
+  getProjectInfo,
+  deleteProjectInfo,
+  dropProjectDatabase,
+  closeProjectInfo,
+} from '@bhooai/nexus-data';
+import { tcpReachable, parseHostPort } from '../util.js';
+import { isInteractive as wizardInteractive, banner, confirm, prompt, closeWizard, COLORS } from '../wizard.js';
+
+const { GREEN, RED, YELLOW, CYAN, DIM, BOLD, RESET } = COLORS;
+
+/**
+ * `nexus uninstall [target]` - remove a project from disk + the databases.
+ *
+ * What it deletes:
+ *   1. The project's own MongoDB database (e.g. `test_app`)
+ *   2. The project's record in `nexus_projects.projects`
+ *   3. (optional, with --purge) the project directory itself
+ *
+ * What it does NOT touch:
+ *   - The `nexus_projects` database (other projects' records remain)
+ *   - The framework (`bhooai-nexus`) install
+ *   - Any other project's database
+ *
+ * Flags:
+ *   --target <path>   project root (default: current directory)
+ *   --force           skip the confirmation prompt
+ *   --purge           also delete the project directory from disk
+ *   --no-interactive  never prompt (imply --force unless --dry-run)
+ *   --dry-run         show what would be deleted, change nothing
+ *   --keep-db         do not drop the project database (only remove the record)
+ *   --keep-files      synonym for omitting --purge (default)
+ *
+ *   Run from inside the project:        `nexus uninstall --purge`
+ *   Or point at another project:        `nexus uninstall --target ../my-app --purge`
+ *   Preview only:                       `nexus uninstall --dry-run`
+ */
+export async function uninstall(args: string[]): Promise<number> {
+  const target = resolve(argValue(args, '--target') ?? '.');
+  const force = args.includes('--force');
+  const purge = args.includes('--purge');
+  const dryRun = args.includes('--dry-run');
+  const keepDb = args.includes('--keep-db');
+  const noInteractive = args.includes('--no-interactive') || !wizardInteractive();
+
+  // -- banner ------------------------------------------------------
+  banner('BhooAI Nexus - uninstall', [
+    dryRun ? 'DRY RUN - nothing will be deleted.' : 'Removes the project DB + its nexus_projects record.',
+    purge ? 'Will also DELETE the project directory from disk.' : 'Project files are kept (pass --purge to remove them).',
+  ]);
+
+  // -- validate the target is a nexus project ----------------------
+  if (!existsSync(resolve(target, 'package.json'))) {
+    console.log(`  ${RED}[X] not a project directory: no package.json at ${target}${RESET}\n`);
+    return 1;
+  }
+  const configExists = ['ts', 'js', 'mjs', 'cjs'].some((ext) => existsSync(resolve(target, `nexus.config.${ext}`)));
+  if (!configExists) {
+    console.log(`  ${RED}[X] not a nexus project: no nexus.config.{ts,js,mjs,cjs} at ${target}${RESET}\n`);
+    return 1;
+  }
+
+  // -- resolve identity + config -----------------------------------
+  const project = await resolveProjectInfo(target);
+  let cfg: Awaited<ReturnType<typeof loadConfigAuto>> | undefined;
+  try {
+    cfg = await loadConfigAuto({ root: target });
+  } catch (err) {
+    console.log(`  ${YELLOW}[!]  could not load nexus.config: ${(err as Error).message}${RESET}`);
+  }
+  const dbName = cfg?.db?.name ?? project.dbName;
+  const mongoUri = cfg?.db?.uri ?? 'mongodb://localhost:27017';
+
+  console.log(`  ${BOLD}Project${RESET}`);
+  console.log(`  ${CYAN}name${RESET}     ${project.name}`);
+  console.log(`  ${CYAN}path${RESET}     ${target}`);
+  console.log(`  ${CYAN}database${RESET} ${dbName}`);
+  console.log(`  ${CYAN}mongo uri${RESET} ${mongoUri}`);
+  console.log(`  ${CYAN}purge files${RESET} ${purge ? 'yes' : 'no'}`);
+  console.log();
+
+  // -- confirm -----------------------------------------------------
+  if (dryRun) {
+    // Show the stored record too, for reference.
+    await previewRecord(mongoUri, project.name);
+    console.log(`\n  ${DIM}Dry run complete - no changes made.${RESET}\n`);
+    return 0;
+  }
+
+  if (!force && !noInteractive) {
+    const ok = await confirm(`Delete the database \`${dbName}\` and remove the \`${project.name}\` record?`, false);
+    if (!ok) {
+      console.log(`  ${DIM}Aborted.${RESET}`);
+      closeWizard();
+      return 1;
+    }
+    if (purge) {
+      const ok2 = await confirm(`Also DELETE the directory ${target} from disk? This cannot be undone.`, false);
+      if (!ok2) {
+        console.log(`  ${YELLOW}Keeping files - only the DB + record will be removed.${RESET}`);
+      } else {
+        // confirmed purge
+      }
+    }
+    closeWizard();
+  } else if (!force && noInteractive) {
+    // Non-interactive without --force: refuse to destructively delete.
+    console.log(`  ${RED}[X] Refusing to uninstall non-interactively without --force.${RESET}`);
+    console.log(`  ${DIM}Pass --force to proceed, or run interactively.${RESET}\n`);
+    return 1;
+  }
+
+  // -- 1. drop the project database --------------------------------
+  if (!keepDb) {
+    const mongo = parseHostPort(mongoUri, 27017);
+    const mongoOk = await tcpReachable(mongo.host, mongo.port, 1500);
+    if (!mongoOk) {
+      console.log(`  ${YELLOW}[!]  Mongo unreachable at ${mongo.host}:${mongo.port} - skipping DB drop${RESET}`);
+    } else {
+      try {
+        connectProjectInfo(mongoUri, { autoIndex: false });
+        const dropped = await dropProjectDatabase(dbName);
+        console.log(`  ${dropped ? GREEN + '[OK]' : YELLOW + '[!]'}  dropped database${RESET} ${CYAN}${dbName}${RESET} ${dropped ? '' : '(already absent)'}`);
+      } catch (err) {
+        console.log(`  ${RED}[X] failed to drop database ${dbName}: ${(err as Error).message}${RESET}`);
+      }
+    }
+  } else {
+    console.log(`  ${DIM}--keep-db: leaving database ${dbName} in place${RESET}`);
+  }
+
+  // -- 2. delete the nexus_projects.projects record ---------------
+  if (!keepDb || true) {
+    try {
+      // connectProjectInfo may already be open from the drop step; reusing is fine.
+      if (!keepDb) {
+        // already connected above
+      } else {
+        const mongo = parseHostPort(mongoUri, 27017);
+        if (await tcpReachable(mongo.host, mongo.port, 1500)) connectProjectInfo(mongoUri, { autoIndex: false });
+      }
+      const deleted = await deleteProjectInfo(project.name);
+      console.log(`  ${deleted ? GREEN + '[OK]' : YELLOW + '[!]'}  deleted record${RESET} ${CYAN}${project.name}${RESET} ${deleted ? 'from nexus_projects.projects' : '(not found)'}`);
+    } catch (err) {
+      console.log(`  ${RED}[X] failed to delete project record: ${(err as Error).message}${RESET}`);
+    } finally {
+      try { await closeProjectInfo(); } catch { /* ignore */ }
+    }
+  }
+
+  // -- 3. purge project files from disk ----------------------------
+  if (purge) {
+    const removed = await removeDir(target);
+    if (removed) {
+      console.log(`  ${GREEN}[OK]${RESET} removed directory ${CYAN}${target}${RESET}`);
+    } else {
+      console.log(`  ${RED}[X] could not fully remove ${target}${RESET}`);
+      console.log(`  ${DIM}Some files may be locked by a running process (node_modules, .venv, an editor).${RESET}`);
+      console.log(`  ${DIM}Close any servers/editors holding the directory and run:${RESET}`);
+      if (process.platform === 'win32') {
+        console.log(`    ${CYAN}rd /s /q "${target}"${RESET}`);
+      } else {
+        console.log(`    ${CYAN}rm -rf "${target}"${RESET}`);
+      }
+    }
+  }
+
+  console.log(`\n  ${GREEN}[OK] Uninstall complete.${RESET}${purge ? '' : ` ${DIM}(project files kept - pass --purge to remove them)${RESET}`}\n`);
+  return 0;
+}
+
+/** Print the stored nexus_projects record for the project (dry-run preview). */
+async function previewRecord(mongoUri: string, name: string): Promise<void> {
+  const mongo = parseHostPort(mongoUri, 27017);
+  const mongoOk = await tcpReachable(mongo.host, mongo.port, 1500);
+  if (!mongoOk) {
+    console.log(`  ${YELLOW}[!]  Mongo unreachable - cannot preview the stored record${RESET}`);
+    return;
+  }
+  try {
+    connectProjectInfo(mongoUri, { autoIndex: false });
+    const rec = await getProjectInfo(name);
+    if (rec) {
+      console.log(`  ${BOLD}Stored record${RESET}`);
+      console.log(`  ${CYAN}name${RESET}     ${rec.name}`);
+      console.log(`  ${CYAN}status${RESET}   ${rec.status ?? '?'}`);
+      console.log(`  ${CYAN}path${RESET}     ${rec.path}`);
+      console.log(`  ${CYAN}dbName${RESET}   ${rec.dbName}`);
+    } else {
+      console.log(`  ${DIM}no record found in nexus_projects.projects for \`${name}\`${RESET}`);
+    }
+    await closeProjectInfo();
+  } catch (err) {
+    console.log(`  ${YELLOW}[!]  could not read record: ${(err as Error).message}${RESET}`);
+  }
+}
+
+function argValue(args: string[], name: string): string | undefined {
+  const i = args.indexOf(name);
+  if (i >= 0) return args[i + 1];
+  return args.find((a) => a.startsWith(`${name}=`))?.slice(name.length + 1);
+}
+
+/**
+ * Robustly remove a directory tree, working around Windows EPERM errors.
+ *  1. Recursively clear the read-only attribute on every entry (Windows sets
+ *     it on `node_modules/.bin` shims, `.venv` files, etc. - `rmSync` then
+ *     throws EPERM instead of deleting).
+ *  2. Try `rmSync`; retry up to 3 times with a short backoff (handles files
+ *     briefly locked by a just-killed process or an antivirus scan).
+ *  3. Fall back to the OS shell (`rd /s /q` on Windows, `rm -rf` elsewhere)
+ *     which uses a different deletion path and often succeeds where Node's
+ *     libuv-based unlink fails.
+ * Returns true if the directory is gone (or never existed), false otherwise.
+ */
+async function removeDir(target: string): Promise<boolean> {
+  if (!existsSync(target)) return true;
+
+  // Step 1: clear read-only attrs recursively (no-op on non-Windows; cheap).
+  clearReadOnly(target);
+
+  // Step 2: rmSync with retries.
+  for (let attempt = 1; attempt <= 3; attempt++) {
+    try {
+      rmSync(target, { recursive: true, force: true });
+      if (!existsSync(target)) return true;
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code;
+      if (attempt < 3 && (code === 'EPERM' || code === 'EBUSY' || code === 'ENOTEMPTY')) {
+        await new Promise((r) => setTimeout(r, 250 * attempt));
+        // Re-clear attrs in case a new locked file appeared.
+        clearReadOnly(target);
+        continue;
+      }
+      break; // give up on rmSync, fall through to shell
+    }
+  }
+
+  if (!existsSync(target)) return true;
+
+  // Step 3: OS shell fallback.
+  try {
+    if (process.platform === 'win32') {
+      // `rd /s /q` ignores read-only attrs and forces deletion.
+      const r = spawnSync('cmd', ['/c', 'rd', '/s', '/q', target], { windowsHide: true });
+      return r.status === 0 && !existsSync(target);
+    }
+    const r = spawnSync('rm', ['-rf', target]);
+    return r.status === 0 && !existsSync(target);
+  } catch {
+    return !existsSync(target);
+  }
+}
+
+/** Recursively walk `dir` and clear the read-only bit on every file/dir.
+ *  Windows-only in effect; on other platforms chmod is a no-op on the
+ *  immutable bits. Uses `0o666` for files and `0o777` for dirs. */
+function clearReadOnly(dir: string): void {
+  let entries: string[];
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return;
+  }
+  for (const name of entries) {
+    const p = join(dir, name);
+    let st;
+    try {
+      st = statSync(p);
+    } catch {
+      continue;
+    }
+    try {
+      chmodSync(p, st.isDirectory() ? 0o777 : 0o666);
+    } catch { /* ignore - best effort */ }
+    if (st.isDirectory()) clearReadOnly(p);
+  }
+  try {
+    chmodSync(dir, 0o777);
+  } catch { /* ignore */ }
+}