@oaklandzoo/ostup 0.8.0 → 0.9.1

package/README.md

@@ -1,7 +1,8 @@
 # ostup
 
 Scaffold a new client project with one command. Get a live GitHub repo
-and live Vercel deploy URL in under five minutes.
+and live Vercel deploy URL in under ten minutes, even from a stock
+computer.
 
 ## What this does
 
@@ -17,60 +18,79 @@ When you run this tool, it will:
    prior materials (research, reference repos, screenshots, brand
    assets) you want the agent to have on hand
 
-## What you need before running it
+## Quick Start
 
-### One-time machine setup (you only do this once)
+Pick the path that matches your computer.
 
-1. Install Node.js 20 or higher. Download from https://nodejs.org
+### Mac (beginner — stock computer with nothing installed)
 
-2. Install GitHub CLI. In Terminal:
-   ```
-   brew install gh
-   ```
-   Then log in:
-   ```
-   gh auth login
-   ```
-   Choose: GitHub.com, then HTTPS, then "Login with a web browser."
-   Follow the prompts.
+Open Terminal and paste:
 
-3. Install Vercel CLI. In Terminal:
-   ```
-   npm install -g vercel
-   ```
-   Then log in:
-   ```
-   vercel login
-   ```
-   Choose your email login method.
+```
+/bin/bash -c "$(curl -fsSL https://ostup-install.vercel.app/install.sh)"
+```
+
+That script installs Homebrew and Node (if missing), then runs `ostup init`,
+which installs Git, GitHub CLI, and Vercel CLI and walks you through signing
+in. Total time: about 5-10 minutes the first time, mostly download waits.
 
-### Accounts you need
+To pre-set flags (advanced):
 
-- GitHub account: free at https://github.com/signup
-- Vercel account: free at https://vercel.com/signup (sign in with GitHub)
+```
+/bin/bash -c "$(curl -fsSL https://ostup-install.vercel.app/install.sh)" -- --yes --profile=default
+```
 
-If you do not have these accounts, the tool will pause and walk you
-through creating them when you reach that step.
+### Windows (beginner — stock computer with nothing installed)
+
+Open PowerShell and paste:
+
+```
+irm https://ostup-install.vercel.app/install.ps1 | iex
+```
 
-## Install
+That script installs Node via WinGet (if missing), then runs `ostup init`,
+which installs Git, GitHub CLI, and Vercel CLI and walks you through signing
+in. Total time: about 5-10 minutes the first time.
 
-The fastest path:
+To pre-set flags (advanced):
 
 ```
-npx @oaklandzoo/ostup init
+irm https://ostup-install.vercel.app/install.ps1 -OutFile install.ps1
+./install.ps1 --yes --profile=default
 ```
 
-That is the whole install. `npx` downloads ostup on first run, nothing
-to install permanently.
+### Developer (you already have Node 20+ and npm)
+
+```
+npx @oaklandzoo/ostup@latest init
+```
+
+ostup will detect any missing tools (`git`, `gh`, `vercel`) and offer to
+install them. Pass `--skip-bootstrap` to bypass detection or `--no-install`
+to see what would be installed without making changes.
 
 If you'd rather install it globally so the command is just `ostup`:
 
 ```
 npm install -g @oaklandzoo/ostup
-ostup --version    # should print 0.1.0
 ostup init
 ```
 
+## What ostup needs (handled for you by the beginner installer)
+
+The beginner installer scripts above handle this list automatically.
+This is what they're installing under the hood:
+
+- Node.js 20+
+- Git
+- GitHub CLI (`gh`)
+- Vercel CLI (`vercel`)
+- A free GitHub account (https://github.com/signup) — sign in during the flow
+- A free Vercel account (https://vercel.com/signup) — sign in during the flow
+
+If you do not have GitHub or Vercel accounts yet, the tool pauses and
+walks you through creating them when you reach those steps.
+
 ### Alternate: install from source
 
 If you cloned https://github.com/DubsFan/goodshin and want to run from
@@ -168,16 +188,18 @@ you do not have to repeat them every session.
 
 | Problem | Fix |
 |---|---|
-| "node: command not found" | Install Node 20+ from https://nodejs.org |
-| "gh: command not found" | Run `brew install gh` |
-| "vercel: command not found" | Run `npm install -g vercel` |
-| "gh auth required" | Run `gh auth login` |
-| "vercel auth required" | Run `vercel login` |
+| "command not found" for node/gh/vercel | Run the beginner installer for your OS (top of this README). Or run `ostup bootstrap` if you already have Node. |
+| "gh auth required" | Re-run `ostup init` and pick "Sign in to GitHub in your browser". Or run `gh auth login`. |
+| "vercel auth required" | Re-run `ostup init` and pick "Sign in to Vercel in your browser". Or run `vercel login`. |
 | "Project name invalid" | Use only lowercase letters, numbers, and hyphens |
 | "Repo already exists" | Pick a different project name |
 | Vercel deploy hangs more than 5 minutes | Cancel with Ctrl-C, run again |
 | Deploy URL returns 401 | The tool tried to auto-disable Vercel deployment protection but could not. Open Vercel dashboard, find your project, Settings, Deployment Protection, Disable. |
 | "ingest path not found" | The path you gave does not exist. Re-run and provide a valid absolute or relative path. |
+| Beginner installer failed | The bash and PowerShell installers log to `~/.ostup/logs/install-*.log`. The ostup CLI logs to `~/.ostup/logs/init-*.log`. Open the most recent log for the failing command's stderr. |
+| "BOOTSTRAP_FAILED: Homebrew missing" | You ran `npx ostup init` on a Mac without Homebrew. Run the Mac beginner installer at the top of this README instead. |
+| "BOOTSTRAP_FAILED: WinGet missing" | Update App Installer from the Microsoft Store: `ms-windows-store://pdp/?productid=9NBLGGH4NNS1`. |
+| "/opt/homebrew/Cellar is not writable" | You are on a shared Mac where Homebrew was installed by another user. 0.9.1+ handles this automatically by installing `gh` to `~/.local/bin/` and routing `vercel` through `~/.npm-global/`. If you saw this error, you are on 0.9.0; upgrade with `npx @oaklandzoo/ostup@latest`. |
 
 ## Advanced: API tokens instead of interactive login
 

package/bin/cli.mjs

@@ -11,7 +11,7 @@ loadDotEnv();
 
 const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
-const SUBCOMMANDS = new Set(['init', 'update', 'brief', 'export-pro', 'doctor']);
+const SUBCOMMANDS = new Set(['init', 'update', 'brief', 'export-pro', 'doctor', 'bootstrap']);
 
 async function readPkg() {
   const raw = await readFile(resolve(PKG_ROOT, 'package.json'), 'utf8');
@@ -46,6 +46,8 @@ function parseArgs(argv) {
     else if (a.startsWith('--output=')) flags.output = a.slice('--output='.length);
     else if (a === '--white-label') flags.whiteLabel = true;
     else if (a === '--no-log') flags.noLog = true;
+    else if (a === '--skip-bootstrap') flags.skipBootstrap = true;
+    else if (a === '--no-install') flags.noInstall = true;
     else if (a.startsWith('-')) {
       process.stderr.write(`unknown flag: ${a}\n`);
       process.exit(1);
@@ -61,14 +63,21 @@ function printHelp() {
     [
       'ostup: scaffold a new repo with the Ostup Agent Kit plus GitHub and Vercel.',
       '',
+      'First time on this computer? Use the beginner installer for your OS:',
+      '  Mac:      /bin/bash -c "$(curl -fsSL https://ostup-install.vercel.app/install.sh)"',
+      '  Windows:  irm https://ostup-install.vercel.app/install.ps1 | iex',
+      '',
+      'Already have Node 20+ and npm? Use this CLI directly.',
+      '',
       'Usage:',
       '  ostup <command> [flags]',
       '',
       'Commands:',
       '  init                Scaffold a new project (interactive or with --yes).',
+      '  bootstrap           Install missing tools (git, gh, vercel) on this machine.',
       '  brief               Run the 10-question operator intake; write docs/brief.md + brief.json.',
       '  export-pro          Bundle brief + brand + content + initial PRD into a ZIP for client handoff.',
-      '  doctor              Self-diagnosis: preflight + auth + permissions + disk + Chrome. Read-only.',
+      '  doctor              Self-diagnosis: tool detection + auth + permissions + disk + Chrome. Read-only.',
       '  update              Refresh bundled templates from the pinned source.',
       '',
       'Flags for `ostup init`:',
@@ -82,6 +91,12 @@ function printHelp() {
       '  --white-label       Strip OSTUP / Goodshin attribution from generated docs (Studio tier).',
       '  --kit-only          Drop the markdown kit into a target dir, no GitHub or Vercel.',
       '  --config <path>     Read .ostup-config.yml from this path (kit-only mode).',
+      '  --skip-bootstrap    Skip the in-CLI tool detection / install step (advanced).',
+      '  --no-install        Detect missing tools, print the install plan, exit without installing.',
+      '',
+      'Flags for `ostup bootstrap`:',
+      '  --yes, -y           Auto-accept the install prompt and choose browser auth where possible.',
+      '  --no-install        Print the install plan, exit without installing.',
       '',
       'Flags for `ostup brief`:',
       '  --brief <path>      Load brief.json from <path> instead of running the intake.',
@@ -187,6 +202,24 @@ if (subcommand === 'doctor') {
   }
 }
 
+if (subcommand === 'bootstrap') {
+  const { runBootstrapStandalone } = await import('../src/bootstrap.mjs');
+  try {
+    await runBootstrapStandalone({ flags });
+    process.exit(0);
+  } catch (err) {
+    process.stderr.write(`${err.message}\n`);
+    const userErrors = new Set([
+      'NO_TTY_BOOTSTRAP',
+      'BOOTSTRAP_DECLINED',
+      'BOOTSTRAP_FAILED',
+      'BOOTSTRAP_VERIFY_FAILED',
+      'UNSUPPORTED_OS_INSTALL',
+    ]);
+    process.exit(userErrors.has(err.code) ? 1 : 2);
+  }
+}
+
 // subcommand === 'init'
 if (flags.kitOnly) {
   const { scaffold } = await import('../src/scaffold.mjs');
@@ -224,6 +257,11 @@ try {
     'INGEST_PATH_NOT_FOUND',
     'BRIEF_NOT_FOUND',
     'BRIEF_INVALID',
+    'NO_TTY_BOOTSTRAP',
+    'BOOTSTRAP_DECLINED',
+    'BOOTSTRAP_FAILED',
+    'BOOTSTRAP_VERIFY_FAILED',
+    'UNSUPPORTED_OS_INSTALL',
   ]);
   process.exit(userErrors.has(err.code) ? 1 : 2);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oaklandzoo/ostup",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "description": "Scaffolds a new repo with the Ostup Agent Kit pre-installed: slash commands, doc templates, and a clean working state.",
   "type": "module",
   "bin": {
@@ -44,6 +44,7 @@
   "files": [
     "bin/",
     "src/",
+    "scripts/",
     "templates/",
     "LICENSE",
     "README.md"

package/scripts/install.ps1

@@ -0,0 +1,115 @@
+# ostup beginner installer for Windows.
+#
+# Stage 1: get this PC to "can run Node 20+". That means installing Node via WinGet
+# (if missing or below v20). Nothing else. Git, GitHub CLI, Vercel CLI, auth, scaffold,
+# and deploy all happen in stage 2 — the ostup CLI's in-CLI bootstrap.
+#
+# Usage:
+#   irm https://ostup-install.vercel.app/install.ps1 | iex
+#
+# Forward flags to `ostup init` (download then run):
+#   irm https://ostup-install.vercel.app/install.ps1 -OutFile install.ps1
+#   ./install.ps1 --yes --profile=default
+
+#Requires -Version 5.1
+$ErrorActionPreference = 'Stop'
+
+# --- logging -----------------------------------------------------------------
+$LogDir = Join-Path $env:USERPROFILE '.ostup\logs'
+New-Item -ItemType Directory -Force -Path $LogDir | Out-Null
+$ts = (Get-Date).ToUniversalTime().ToString('yyyyMMddTHHmmssZ')
+$LogFile = Join-Path $LogDir "install-$ts.log"
+try { Start-Transcript -Path $LogFile -ErrorAction Stop | Out-Null } catch {}
+
+# --- detect ------------------------------------------------------------------
+$hasWinget = $null -ne (Get-Command winget -ErrorAction SilentlyContinue)
+$hasNodeOk = $false
+$nodeVerDetected = ''
+if (Get-Command node -ErrorAction SilentlyContinue) {
+  try {
+    $nodeVerDetected = (& node --version).Trim()
+    if ($nodeVerDetected -match '^v(\d+)') {
+      $nodeMajor = [int]$Matches[1]
+      if ($nodeMajor -ge 20) { $hasNodeOk = $true }
+    }
+  } catch {}
+}
+
+# --- WinGet gate -------------------------------------------------------------
+if (-not $hasWinget) {
+  Write-Host ''
+  Write-Host 'WinGet (Microsoft App Installer) is required to install Node automatically.'
+  Write-Host 'On Windows 11, WinGet is built in. On Windows 10, you may need to update App Installer:'
+  Write-Host '  ms-windows-store://pdp/?productid=9NBLGGH4NNS1'
+  Write-Host 'Open that URL in your browser, install or update App Installer, then re-run.'
+  try { Stop-Transcript | Out-Null } catch {}
+  exit 1
+}
+
+$needNode = -not $hasNodeOk
+
+# --- explainer + consent (only when something is missing) -------------------
+if ($needNode) {
+  Write-Host ''
+  Write-Host "You're about to set up your PC to run modern web tools."
+  Write-Host ''
+  if ($nodeVerDetected) {
+    Write-Host "  1. Node.js  - The engine that runs the website setup tool (ostup)."
+    Write-Host "              Your current Node $nodeVerDetected is too old; we need v20+."
+  } else {
+    Write-Host "  1. Node.js  - The engine that runs the website setup tool (ostup)."
+  }
+  Write-Host ''
+  Write-Host 'Node will install via WinGet (Microsoft package manager). Windows may show a prompt'
+  Write-Host 'asking you to allow the install.'
+  Write-Host ''
+  Write-Host 'After this, ostup will continue and install Git, GitHub CLI, and Vercel CLI,'
+  Write-Host 'then walk you through signing in.'
+  Write-Host ''
+  Write-Host 'Total time: about 3-5 minutes for this step. Requires an internet connection.'
+  Write-Host ''
+
+  if ([Environment]::UserInteractive) {
+    $yn = Read-Host 'Continue? [Y/n]'
+    if ($yn -and $yn -notmatch '^(y|yes)$') {
+      Write-Host 'Cancelled. Re-run when ready.'
+      try { Stop-Transcript | Out-Null } catch {}
+      exit 1
+    }
+  } else {
+    Write-Host '(non-interactive session; proceeding)'
+  }
+
+  Write-Host ''
+  Write-Host 'Installing Node via WinGet...'
+  & winget install -e --id OpenJS.NodeJS.LTS --accept-package-agreements --accept-source-agreements
+  if ($LASTEXITCODE -ne 0) {
+    Write-Host ''
+    Write-Host "ERROR: WinGet returned exit code $LASTEXITCODE."
+    Write-Host "Log: $LogFile"
+    try { Stop-Transcript | Out-Null } catch {}
+    exit 1
+  }
+
+  # Patch PATH for this PowerShell session so npx works without restarting.
+  $env:Path = "C:\Program Files\nodejs;$env:Path"
+
+  if (-not (Get-Command node -ErrorAction SilentlyContinue)) {
+    Write-Host 'ERROR: Node install completed but node is not on PATH in this session.'
+    Write-Host 'Open a new PowerShell window and re-run, or check the log:'
+    Write-Host "  $LogFile"
+    try { Stop-Transcript | Out-Null } catch {}
+    exit 1
+  }
+  $postVer = (& node --version).Trim()
+  Write-Host "Node $postVer installed."
+}
+
+# --- hand off to the ostup CLI ----------------------------------------------
+Write-Host ''
+Write-Host 'Stage 1 complete. Continuing with ostup...'
+Write-Host ''
+
+try { Stop-Transcript | Out-Null } catch {}
+& npx '@oaklandzoo/ostup@latest' init @args
+exit $LASTEXITCODE

package/scripts/install.sh

@@ -0,0 +1,144 @@
+#!/bin/bash
+# ostup beginner installer for macOS.
+#
+# Stage 1: get this Mac to "can run Node 20+". That means installing Homebrew (if missing)
+# and Node (if missing or below v20). Nothing else. Git, GitHub CLI, Vercel CLI, auth,
+# scaffold, and deploy all happen in stage 2 — the ostup CLI's in-CLI bootstrap.
+#
+# Usage:
+#   /bin/bash -c "$(curl -fsSL https://ostup-install.vercel.app/install.sh)"
+#
+# Forward flags to `ostup init`:
+#   /bin/bash -c "$(curl -fsSL ...install.sh)" -- --yes --profile=default
+
+set -euo pipefail
+
+# --- logging -----------------------------------------------------------------
+LOG_DIR="${HOME}/.ostup/logs"
+mkdir -p "$LOG_DIR"
+LOG_FILE="${LOG_DIR}/install-$(date -u +%Y%m%dT%H%M%SZ).log"
+exec > >(tee -a "$LOG_FILE") 2>&1
+
+# --- platform check ----------------------------------------------------------
+UNAME_S="$(uname -s 2>/dev/null || echo unknown)"
+if [ "$UNAME_S" != "Darwin" ]; then
+  cat <<EOF
+This installer is for macOS only.
+
+On Windows, open PowerShell and run:
+  irm https://ostup-install.vercel.app/install.ps1 | iex
+
+On Linux, install Node 20+ from https://nodejs.org or your package manager, then run:
+  npx @oaklandzoo/ostup@latest init
+EOF
+  exit 1
+fi
+
+# --- detect ------------------------------------------------------------------
+HAS_BREW=0
+HAS_NODE_OK=0
+NODE_VER_DETECTED=""
+
+if command -v brew >/dev/null 2>&1; then
+  HAS_BREW=1
+fi
+
+if command -v node >/dev/null 2>&1; then
+  NODE_VER_DETECTED="$(node --version 2>/dev/null || echo '')"
+  NODE_MAJOR="$(echo "$NODE_VER_DETECTED" | sed -E 's/^v([0-9]+).*/\1/')"
+  if [ -n "$NODE_MAJOR" ] && [ "$NODE_MAJOR" -ge 20 ] 2>/dev/null; then
+    HAS_NODE_OK=1
+  fi
+fi
+
+# --- explainer + consent (only when something is missing) --------------------
+NEED_BREW=$(( 1 - HAS_BREW ))
+NEED_NODE=$(( 1 - HAS_NODE_OK ))
+
+if [ "$NEED_BREW" -eq 1 ] || [ "$NEED_NODE" -eq 1 ]; then
+  echo ""
+  echo "You're about to set up your Mac to run modern web tools."
+  echo ""
+  i=1
+  if [ "$NEED_BREW" -eq 1 ]; then
+    echo "  $i. Homebrew  - Apple's package manager. Used to install Node."
+    i=$((i + 1))
+  fi
+  if [ "$NEED_NODE" -eq 1 ]; then
+    if [ -n "$NODE_VER_DETECTED" ]; then
+      echo "  $i. Node.js   - The engine that runs the website setup tool (ostup)."
+      echo "                Your current Node $NODE_VER_DETECTED is too old; we need v20+."
+    else
+      echo "  $i. Node.js   - The engine that runs the website setup tool (ostup)."
+    fi
+  fi
+  echo ""
+  if [ "$NEED_BREW" -eq 1 ]; then
+    echo "You'll be asked for your Mac login password once (for Homebrew). It goes"
+    echo "straight to your Mac, not to ostup - we never see or store it."
+    echo ""
+  fi
+  echo "After this, ostup will continue and install GitHub CLI and Vercel CLI,"
+  echo "then walk you through signing in."
+  echo ""
+  echo "Total time: about 3-5 minutes for this step, depending on your internet."
+  echo "Requires an internet connection."
+  echo ""
+  if [ -t 0 ]; then
+    read -r -p "Continue? [Y/n] " yn
+    case "$yn" in
+      ""|y|Y|yes|YES) ;;
+      *)
+        echo "Cancelled. Re-run the command when ready."
+        exit 1
+        ;;
+    esac
+  else
+    echo "(no terminal detected; proceeding non-interactively)"
+  fi
+fi
+
+# --- install Homebrew if missing --------------------------------------------
+if [ "$HAS_BREW" -eq 0 ]; then
+  echo ""
+  echo "[1/2] Installing Homebrew..."
+  /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+  # Add brew to current shell's PATH.
+  if [ -x /opt/homebrew/bin/brew ]; then
+    eval "$(/opt/homebrew/bin/brew shellenv)"
+  elif [ -x /usr/local/bin/brew ]; then
+    eval "$(/usr/local/bin/brew shellenv)"
+  else
+    echo "ERROR: Homebrew installation appears to have failed (brew not found at /opt/homebrew/bin or /usr/local/bin)."
+    echo "Log: $LOG_FILE"
+    exit 1
+  fi
+  echo "Homebrew installed."
+fi
+
+# --- install Node if missing or too old --------------------------------------
+if [ "$HAS_NODE_OK" -eq 0 ]; then
+  echo ""
+  echo "[2/2] Installing Node via Homebrew..."
+  brew install node
+  # Confirm node is now on PATH and at ≥20.
+  if ! command -v node >/dev/null 2>&1; then
+    echo "ERROR: Node install completed but 'node' is not on PATH. Open a new Terminal window and re-run."
+    echo "Log: $LOG_FILE"
+    exit 1
+  fi
+  POST_VER="$(node --version)"
+  POST_MAJOR="$(echo "$POST_VER" | sed -E 's/^v([0-9]+).*/\1/')"
+  if [ "$POST_MAJOR" -lt 20 ] 2>/dev/null; then
+    echo "ERROR: Node $POST_VER installed but version is still below 20. Run: brew upgrade node"
+    echo "Log: $LOG_FILE"
+    exit 1
+  fi
+  echo "Node $POST_VER installed."
+fi
+
+# --- hand off to the ostup CLI ----------------------------------------------
+echo ""
+echo "Stage 1 complete. Continuing with ostup..."
+echo ""
+exec npx @oaklandzoo/ostup@latest init "$@"

package/src/bootstrap.mjs

@@ -0,0 +1,347 @@
+// bootstrap.mjs: in-CLI stage 2. Detect missing tools via tool-registry, explain in plain English,
+// confirm, install via exec.run (stdio: inherit so OS prompts reach the terminal), patch PATH,
+// verify, and continue. Stage 1 (install.sh / install.ps1) handles Node and Homebrew/winget; this
+// module never touches those — but it does check that brew/winget exist before attempting installs
+// that require them, so beginners who skipped stage 1 get a clear pointer back to it.
+import * as p from '@clack/prompts';
+import { execSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { existsSync, constants as fsConstants } from 'node:fs';
+import { access, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { detectAll, installCommandFor } from './tool-registry.mjs';
+import { run as exec } from './exec.mjs';
+
+const STAGE1_HINT = {
+  darwin: 'Mac installer: /bin/bash -c "$(curl -fsSL https://ostup-install.vercel.app/install.sh)"',
+  win32: 'Windows installer: irm https://ostup-install.vercel.app/install.ps1 | iex',
+  linux: 'On Linux, install Node 20+ from https://nodejs.org or your package manager, then re-run.',
+};
+
+function buildExplainer(missing) {
+  const items = missing.map((m, i) => `  ${i + 1}. ${m.tool.name.padEnd(14)} ${m.tool.blurb}`);
+  return [
+    '',
+    'ostup needs the following before it can build your site:',
+    '',
+    ...items,
+    '',
+  ].join('\n');
+}
+
+function describePlan(plan) {
+  if (plan.kind === 'manual') {
+    return `(manual) ${plan.url}${plan.note ? ` — ${plan.note}` : ''}`;
+  }
+  return `${plan.cmd} ${(plan.args || []).join(' ')}`;
+}
+
+function defaultHasOnPath(bin) {
+  try {
+    if (process.platform === 'win32') {
+      execSync(`where.exe ${bin}`, { stdio: ['ignore', 'pipe', 'ignore'] });
+    } else {
+      execSync(`command -v ${bin}`, { stdio: ['ignore', 'pipe', 'ignore'], shell: '/bin/bash' });
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function patchPathFor(plan) {
+  if (!plan.postPath || plan.postPath.length === 0) return;
+  const sep = process.platform === 'win32' ? ';' : ':';
+  const existing = (process.env.PATH || '').split(sep);
+  const toAdd = plan.postPath.filter((dir) => !existing.includes(dir));
+  if (toAdd.length === 0) return;
+  process.env.PATH = toAdd.join(sep) + sep + (process.env.PATH || '');
+}
+
+// --- darwin multi-user helpers ----------------------------------------------
+// On a Mac where Homebrew was installed by a different user (shared / refurbished /
+// family Mac), the current user can READ /opt/homebrew/ (so detection passes) but
+// cannot WRITE to it (so `brew install gh` fails). Same applies to npm's global
+// prefix which lives under brew. These helpers detect that state and switch to
+// user-local install strategies that don't need sudo or admin handoff.
+
+async function isPathWritable(path) {
+  try {
+    await access(path, fsConstants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function checkBrewWritable() {
+  for (const cellar of ['/opt/homebrew/Cellar', '/usr/local/Cellar']) {
+    if (existsSync(cellar)) {
+      return { exists: true, writable: await isPathWritable(cellar), cellar };
+    }
+  }
+  return { exists: false, writable: false, cellar: null };
+}
+
+async function checkNpmGlobalWritable() {
+  let prefix = null;
+  try {
+    prefix = execSync('npm prefix -g', { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+  } catch {
+    return { prefix: null, writable: false };
+  }
+  if (!prefix) return { prefix: null, writable: false };
+  return { prefix, writable: await isPathWritable(prefix) };
+}
+
+async function appendToZshrcIfMissing(line) {
+  const zshrc = join(homedir(), '.zshrc');
+  try {
+    const body = existsSync(zshrc) ? await readFile(zshrc, 'utf8') : '';
+    if (body.includes(line)) return false;
+    const sep = body.length === 0 || body.endsWith('\n') ? '' : '\n';
+    await writeFile(zshrc, body + sep + line + '\n');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function prependToProcessPath(dir) {
+  const sep = process.platform === 'win32' ? ';' : ':';
+  const parts = (process.env.PATH || '').split(sep);
+  if (parts.includes(dir)) return;
+  process.env.PATH = dir + sep + (process.env.PATH || '');
+}
+
+async function fetchLatestGhVersion() {
+  try {
+    const out = execSync(
+      'curl -fsSL https://api.github.com/repos/cli/cli/releases/latest',
+      { stdio: ['ignore', 'pipe', 'ignore'] }
+    ).toString();
+    const m = out.match(/"tag_name"\s*:\s*"v([0-9]+\.[0-9]+\.[0-9]+)"/);
+    return m ? m[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+async function installGhBinaryDirect() {
+  // Multi-user-Mac fallback: download gh from its GitHub release tarball into
+  // ~/.local/bin/gh. No brew, no sudo, no admin handoff. Patches PATH for the
+  // current process and appends an export line to ~/.zshrc for future shells.
+  const home = homedir();
+  const binDir = join(home, '.local', 'bin');
+  const arch = process.arch === 'arm64' ? 'macOS_arm64' : 'macOS_amd64';
+  const version = (await fetchLatestGhVersion()) || '2.82.1';
+  const url = `https://github.com/cli/cli/releases/download/v${version}/gh_${version}_${arch}.tar.gz`;
+
+  const installScript = [
+    'set -euo pipefail',
+    `mkdir -p "${binDir}"`,
+    'tmp=$(mktemp -d)',
+    'cd "$tmp"',
+    `curl -fL -o gh.tar.gz "${url}"`,
+    'tar -xzf gh.tar.gz',
+    `cp gh_${version}_${arch}/bin/gh "${binDir}/gh"`,
+    `chmod +x "${binDir}/gh"`,
+    'rm -rf "$tmp"',
+  ].join('\n');
+
+  await exec('bootstrap-gh-direct', 'bash', ['-c', installScript], { stdio: 'inherit' });
+  prependToProcessPath(binDir);
+  await appendToZshrcIfMissing(`export PATH="${binDir}:$PATH"`);
+}
+
+async function setupUserNpmPrefix() {
+  // Multi-user-Mac fallback: route `npm install -g` into ~/.npm-global so the
+  // current user owns the directory and doesn't need write access to brew's
+  // npm prefix.
+  const home = homedir();
+  const prefix = join(home, '.npm-global');
+  const binDir = join(prefix, 'bin');
+  await exec('bootstrap-npm-prefix', 'npm', ['config', 'set', 'prefix', prefix], { stdio: 'inherit' });
+  prependToProcessPath(binDir);
+  await appendToZshrcIfMissing(`export PATH="${binDir}:$PATH"`);
+}
+
+function checkInstallPrerequisites(missing, hasOnPath, platform) {
+  const reasons = [];
+  for (const m of missing) {
+    const plan = installCommandFor(m.tool, platform);
+    if (plan.kind === 'brew' && !hasOnPath('brew')) {
+      reasons.push({
+        tool: m.tool.name,
+        prereq: 'Homebrew',
+        hint: STAGE1_HINT.darwin,
+      });
+    }
+    if (plan.kind === 'winget' && !hasOnPath('winget')) {
+      reasons.push({
+        tool: m.tool.name,
+        prereq: 'WinGet (Microsoft App Installer)',
+        hint: 'Update App Installer from the Microsoft Store: ms-windows-store://pdp/?productid=9NBLGGH4NNS1',
+      });
+    }
+  }
+  // Dedupe by prereq
+  const seen = new Set();
+  return reasons.filter((r) => {
+    if (seen.has(r.prereq)) return false;
+    seen.add(r.prereq);
+    return true;
+  });
+}
+
+function printInstallPlan(missing, platform = process.platform) {
+  process.stdout.write('Install plan:\n');
+  for (const m of missing) {
+    const plan = installCommandFor(m.tool, platform);
+    process.stdout.write(`  ${m.tool.name}: ${describePlan(plan)}\n`);
+  }
+  process.stdout.write('\n');
+}
+
+export async function runBootstrap({
+  flags = {},
+  detect = detectAll,
+  hasOnPath = defaultHasOnPath,
+  platform = process.platform,
+} = {}) {
+  const { found, missing } = detect();
+  if (missing.length === 0) {
+    if (flags.bootstrapOnly) {
+      process.stdout.write('[bootstrap] all required tools present. Nothing to install.\n');
+    }
+    return { found, missing: [], installed: [], skipped: true };
+  }
+
+  process.stdout.write(buildExplainer(missing));
+
+  // --no-install: print plan, exit 0 without changing anything.
+  if (flags.noInstall) {
+    printInstallPlan(missing, platform);
+    process.stdout.write('No changes made. Re-run without --no-install to actually install.\n');
+    return { found, missing, installed: [], deferred: 'no-install' };
+  }
+
+  // Manual-only missing tools (e.g. Node version mismatch): cannot auto-install here.
+  // Point the user at the stage-1 installer for their OS and bail.
+  const manualOnly = missing.filter((m) => installCommandFor(m.tool, platform).kind === 'manual');
+  if (manualOnly.length > 0) {
+    const lines = ['Some tools cannot be installed by ostup directly:'];
+    for (const m of manualOnly) {
+      const plan = installCommandFor(m.tool, platform);
+      lines.push(`  - ${m.tool.name}: ${plan.url}`);
+      if (plan.note) lines.push(`    ${plan.note}`);
+    }
+    lines.push('');
+    lines.push(STAGE1_HINT[platform] || STAGE1_HINT.linux);
+    lines.push('');
+    process.stdout.write(lines.join('\n') + '\n');
+    const err = new Error('Manual install required for: ' + manualOnly.map((m) => m.tool.name).join(', '));
+    err.code = 'UNSUPPORTED_OS_INSTALL';
+    throw err;
+  }
+
+  // Prerequisite check (brew on Mac, winget on Windows).
+  const prereqProblems = checkInstallPrerequisites(missing, hasOnPath, platform);
+  if (prereqProblems.length > 0) {
+    const lines = ['Cannot install — a prerequisite is missing on your machine:'];
+    for (const r of prereqProblems) {
+      lines.push(`  - ${r.prereq} (needed for ${r.tool})`);
+      lines.push(`    ${r.hint}`);
+    }
+    lines.push('');
+    process.stdout.write(lines.join('\n') + '\n');
+    const err = new Error('Bootstrap cannot run: ' + prereqProblems.map((r) => r.prereq).join(', ') + ' missing.');
+    err.code = 'BOOTSTRAP_FAILED';
+    throw err;
+  }
+
+  // Need a TTY for the confirm prompt unless --yes.
+  if (!flags.yes && !process.stdin.isTTY) {
+    const err = new Error('Cannot prompt to install: no terminal detected. Pass --no-install to print the plan, or --yes to auto-accept, or run in a terminal.');
+    err.code = 'NO_TTY_BOOTSTRAP';
+    throw err;
+  }
+
+  printInstallPlan(missing, platform);
+
+  if (!flags.yes) {
+    const ok = await p.confirm({ message: 'Install these now?' });
+    if (p.isCancel(ok) || ok === false) {
+      const err = new Error('Bootstrap declined. Re-run when ready, or install the tools manually.');
+      err.code = 'BOOTSTRAP_DECLINED';
+      throw err;
+    }
+  }
+
+  // On darwin: detect multi-user-Mac scenario (brew owned by another user) and
+  // switch to user-local install strategies before running the loop. Skip when
+  // running under an injected hasOnPath (tests use platform-agnostic flows).
+  const useUserGhFallback = new Set();
+  let needsUserNpmPrefix = false;
+  if (platform === 'darwin' && hasOnPath === defaultHasOnPath) {
+    const brewMissing = missing.filter((m) => installCommandFor(m.tool, platform).kind === 'brew');
+    const npmgMissing = missing.filter((m) => installCommandFor(m.tool, platform).kind === 'npm-g');
+    if (brewMissing.length > 0) {
+      const brewState = await checkBrewWritable();
+      if (brewState.exists && !brewState.writable) {
+        process.stdout.write('\n[bootstrap] Homebrew is installed but owned by another user.\n');
+        process.stdout.write('[bootstrap] Switching to user-local install for brew-managed tools (no sudo, no admin handoff).\n\n');
+        for (const m of brewMissing) {
+          if (m.tool.id === 'gh') useUserGhFallback.add(m.tool.id);
+        }
+      }
+    }
+    if (npmgMissing.length > 0) {
+      const npmState = await checkNpmGlobalWritable();
+      if (!npmState.writable) {
+        process.stdout.write('[bootstrap] npm global prefix is not writable by this user. Setting up ~/.npm-global as a per-user prefix.\n\n');
+        needsUserNpmPrefix = true;
+      }
+    }
+  }
+  if (needsUserNpmPrefix) {
+    await setupUserNpmPrefix();
+  }
+
+  // Run installs sequentially. stdio: 'inherit' so sudo/UAC prompts, progress bars, and
+  // any interactive winget/brew confirmations reach the user's terminal.
+  const installed = [];
+  for (const m of missing) {
+    if (useUserGhFallback.has(m.tool.id)) {
+      await installGhBinaryDirect();
+      installed.push(m.tool.id);
+      continue;
+    }
+    const plan = installCommandFor(m.tool, platform);
+    await exec(`bootstrap-${m.tool.id}`, plan.cmd, plan.args || [], {
+      stdio: 'inherit',
+      cwd: homedir(),
+    });
+    patchPathFor(plan);
+    installed.push(m.tool.id);
+  }
+
+  // Re-detect to verify the installs worked.
+  const second = detect();
+  if (second.missing.length > 0) {
+    const stillMissing = second.missing.map((m) => m.tool.name).join(', ');
+    const err = new Error(
+      `Bootstrap finished but these tools are still not detected: ${stillMissing}. ` +
+      `Open a new terminal and re-run, or check the run log for details.`
+    );
+    err.code = 'BOOTSTRAP_VERIFY_FAILED';
+    throw err;
+  }
+
+  process.stdout.write(`\n[bootstrap] installed ${installed.length} tool(s): ${installed.join(', ')}. Continuing.\n\n`);
+  return { found: second.found, missing: [], installed };
+}
+
+export async function runBootstrapStandalone({ flags = {} } = {}) {
+  return runBootstrap({ flags: { ...flags, bootstrapOnly: true } });
+}

package/src/credential-prompts.mjs

@@ -1,6 +1,7 @@
 // credential-prompts.mjs: detect GitHub and Vercel credentials, prompt and persist only if missing.
 import * as p from '@clack/prompts';
 import { execSync } from 'node:child_process';
+import { run as exec } from './exec.mjs';
 
 export function checkGithubAuth({ env = process.env, runner = defaultCmdOk } = {}) {
   if (env.GH_TOKEN) return { ok: true, source: 'env-or-dotenv' };
@@ -80,21 +81,71 @@ export async function promptForVercelToken() {
   return typeof token === 'string' && token.trim() ? token.trim() : null;
 }
 
-export async function ensureCredentials({ stack = 'next' } = {}) {
+function binaryOnPath(bin) {
+  try {
+    execSync(`${bin} --version`, { stdio: ['ignore', 'ignore', 'ignore'] });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function chooseAuthMethod({ provider }) {
+  const choice = await p.select({
+    message: `${provider}: how would you like to sign in?`,
+    options: [
+      { value: 'browser', label: `Sign in to ${provider} in your browser (recommended)` },
+      { value: 'token', label: 'Paste a personal access token instead' },
+    ],
+    initialValue: 'browser',
+  });
+  if (p.isCancel(choice)) return 'token';
+  return choice;
+}
+
+async function attemptBrowserAuth({ provider }) {
+  try {
+    if (provider === 'GitHub') {
+      await exec('gh-auth', 'gh', ['auth', 'login', '--web', '-h', 'github.com'], { stdio: 'inherit' });
+    } else if (provider === 'Vercel') {
+      await exec('vercel-auth', 'vercel', ['login'], { stdio: 'inherit' });
+    }
+    return true;
+  } catch {
+    process.stdout.write(`${provider} browser sign-in did not complete. Falling back to token paste.\n`);
+    return false;
+  }
+}
+
+export async function ensureCredentials({ stack = 'next', flags = {} } = {}) {
   const collected = {};
 
   const gh = checkGithubAuth();
   if (gh.ok) {
     process.stdout.write(`GitHub: using existing auth (${gh.source}).\n`);
   } else {
-    const token = await promptForGithubToken();
-    if (!token) {
-      const err = new Error('GitHub credentials are required.');
-      err.code = 'NO_GH_CREDS';
-      throw err;
+    let signedIn = false;
+    if (binaryOnPath('gh')) {
+      const method = flags.yes ? 'browser' : await chooseAuthMethod({ provider: 'GitHub' });
+      if (method === 'browser') {
+        signedIn = await attemptBrowserAuth({ provider: 'GitHub' });
+        if (signedIn && checkGithubAuth().ok) {
+          process.stdout.write('GitHub: signed in via browser.\n');
+        } else {
+          signedIn = false;
+        }
+      }
+    }
+    if (!signedIn) {
+      const token = await promptForGithubToken();
+      if (!token) {
+        const err = new Error('GitHub credentials are required.');
+        err.code = 'NO_GH_CREDS';
+        throw err;
+      }
+      process.env.GH_TOKEN = token;
+      collected.GH_TOKEN = token;
     }
-    process.env.GH_TOKEN = token;
-    collected.GH_TOKEN = token;
   }
 
   if (stack !== 'none') {
@@ -102,14 +153,28 @@ export async function ensureCredentials({ stack = 'next' } = {}) {
     if (v.ok) {
       process.stdout.write(`Vercel: using existing auth (${v.source}).\n`);
     } else {
-      const token = await promptForVercelToken();
-      if (!token) {
-        const err = new Error('Vercel credentials are required for stack=' + stack + '.');
-        err.code = 'NO_VERCEL_CREDS';
-        throw err;
+      let signedIn = false;
+      if (binaryOnPath('vercel')) {
+        const method = flags.yes ? 'browser' : await chooseAuthMethod({ provider: 'Vercel' });
+        if (method === 'browser') {
+          signedIn = await attemptBrowserAuth({ provider: 'Vercel' });
+          if (signedIn && checkVercelAuth().ok) {
+            process.stdout.write('Vercel: signed in via browser.\n');
+          } else {
+            signedIn = false;
+          }
+        }
+      }
+      if (!signedIn) {
+        const token = await promptForVercelToken();
+        if (!token) {
+          const err = new Error('Vercel credentials are required for stack=' + stack + '.');
+          err.code = 'NO_VERCEL_CREDS';
+          throw err;
+        }
+        process.env.VERCEL_TOKEN = token;
+        collected.VERCEL_TOKEN = token;
       }
-      process.env.VERCEL_TOKEN = token;
-      collected.VERCEL_TOKEN = token;
     }
   }
 

package/src/doctor.mjs

@@ -5,7 +5,7 @@ import { execSync } from 'node:child_process';
 import { homedir } from 'node:os';
 import { join, resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { preflight } from './preflight.mjs';
+import { detectAll, installCommandFor } from './tool-registry.mjs';
 import { checkGithubAuth, checkVercelAuth } from './credential-prompts.mjs';
 
 function runOk(cmd) {
@@ -38,18 +38,20 @@ export async function runDoctor() {
     else warnCount++;
   }
 
-  // === Preflight ===
-  const pf = preflight();
-  if (pf.ok) {
-    report('ok', 'preflight', 'all required binaries present (node 20+, git, gh, vercel)');
-  } else {
-    report('fail', `preflight: ${pf.failed?.name || 'unknown'}`, pf.reason || pf.failed?.fix || '(no detail)');
-  }
-
-  // === Node version detail ===
-  const nodeVer = runCapture('node --version');
-  if (nodeVer) {
-    report('ok', 'node', nodeVer);
+  // === Tool detection (shared with bootstrap) ===
+  const detection = detectAll();
+  for (const f of detection.found) {
+    report('ok', f.tool.name.toLowerCase().replace(/\s+/g, '-'), f.version);
+  }
+  for (const m of detection.missing) {
+    const plan = installCommandFor(m.tool);
+    const planStr = plan.kind === 'manual'
+      ? plan.url
+      : `${plan.cmd} ${(plan.args || []).join(' ')}`;
+    const detail = m.reason === 'version-too-old'
+      ? `${m.detected} too old; need ${m.tool.detect.minMajor}+. Fix: ${planStr}`
+      : `not installed. Fix: ${planStr}`;
+    report('fail', m.tool.name.toLowerCase().replace(/\s+/g, '-'), detail);
   }
 
   // === Git config ===

package/src/mvp-flow.mjs

@@ -5,6 +5,7 @@ import { homedir } from 'node:os';
 import { resolve, join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { preflightOrExit } from './preflight.mjs';
+import { runBootstrap } from './bootstrap.mjs';
 import { runProjectPrompts, printSummary as printAnswersSummary, confirmProceed } from './project-prompts.mjs';
 import { ensureCredentials } from './credential-prompts.mjs';
 import { maybeScaffoldStack } from './steps/next-app.mjs';
@@ -34,6 +35,10 @@ export async function runMvp({ flags = {}, cwd = process.cwd() } = {}) {
     throw err;
   }
 
+  if (!flags.skipBootstrap) {
+    await runBootstrap({ flags });
+  }
+
   preflightOrExit();
 
   let brief = null;
@@ -79,7 +84,7 @@ export async function runMvp({ flags = {}, cwd = process.cwd() } = {}) {
     }
   }
 
-  const creds = await ensureCredentials({ stack: answers.stack });
+  const creds = await ensureCredentials({ stack: answers.stack, flags });
 
   const targetDir = resolve(cwd, answers.projectName);
   await ensureFreshTarget(targetDir, flags.force);

package/src/preflight.mjs

@@ -1,12 +1,9 @@
 // preflight.mjs: verify required binaries (node, git, gh, vercel) are installed.
+// CHECKS now comes from tool-registry.mjs — single source of truth shared with bootstrap and doctor.
 import { execSync } from 'node:child_process';
+import { CHECKS as REGISTRY_CHECKS } from './tool-registry.mjs';
 
-export const CHECKS = [
-  { name: 'Node',       cmd: ['node', '--version'],   fix: 'Install Node 20+ from https://nodejs.org', minNodeMajor: 20 },
-  { name: 'Git',        cmd: ['git', '--version'],    fix: 'Install git from https://git-scm.com' },
-  { name: 'GitHub CLI', cmd: ['gh', '--version'],     fix: 'Install: brew install gh' },
-  { name: 'Vercel CLI', cmd: ['vercel', '--version'], fix: 'Install: npm i -g vercel' },
-];
+export const CHECKS = REGISTRY_CHECKS;
 
 function defaultRunner(cmd) {
   return execSync(cmd.join(' '), { stdio: ['ignore', 'pipe', 'ignore'] }).toString();

package/src/tool-registry.mjs

@@ -0,0 +1,164 @@
+// tool-registry.mjs: single source of truth for the binaries ostup needs (node, git, gh, vercel).
+// Detection logic lives here. Install commands per platform live here. Anything that wants to know
+// "what does the user need installed" reads from REGISTRY. Avoids drift between preflight, bootstrap,
+// and doctor.
+import { execSync } from 'node:child_process';
+
+export const REGISTRY = [
+  {
+    id: 'node',
+    name: 'Node',
+    blurb: 'The engine that runs the website setup tool (ostup).',
+    detect: { cmd: 'node', args: ['--version'], minMajor: 20 },
+    fix: 'Install Node 20+ from https://nodejs.org',
+    install: {
+      darwin: {
+        kind: 'manual',
+        url: 'https://nodejs.org',
+        note: 'The Mac installer (install.sh) handles Node via Homebrew. Re-run the bash installer to get it.',
+      },
+      linux: {
+        kind: 'manual',
+        url: 'https://nodejs.org',
+        note: 'Install Node 20+ from nodejs.org or your package manager.',
+      },
+      win32: {
+        kind: 'manual',
+        url: 'https://nodejs.org',
+        note: 'The Windows installer (install.ps1) handles Node via WinGet. Re-run the PowerShell installer to get it.',
+      },
+    },
+  },
+  {
+    id: 'git',
+    name: 'Git',
+    blurb: 'Saves versions of your project as you work.',
+    detect: { cmd: 'git', args: ['--version'] },
+    fix: 'Install git from https://git-scm.com',
+    install: {
+      darwin: {
+        kind: 'brew',
+        cmd: 'brew',
+        args: ['install', 'git'],
+        postPath: ['/opt/homebrew/bin', '/usr/local/bin'],
+      },
+      linux: {
+        kind: 'apt',
+        cmd: 'apt-get',
+        args: ['install', '-y', 'git'],
+        requiresRoot: true,
+        url: 'https://git-scm.com',
+      },
+      win32: {
+        kind: 'winget',
+        cmd: 'winget',
+        args: ['install', '-e', '--id', 'Git.Git', '--accept-package-agreements', '--accept-source-agreements'],
+        postPath: ['C:\\Program Files\\Git\\cmd'],
+      },
+    },
+  },
+  {
+    id: 'gh',
+    name: 'GitHub CLI',
+    blurb: 'Saves your project on GitHub so it is not just on your laptop.',
+    detect: { cmd: 'gh', args: ['--version'] },
+    fix: 'Install: brew install gh',
+    install: {
+      darwin: {
+        kind: 'brew',
+        cmd: 'brew',
+        args: ['install', 'gh'],
+        postPath: ['/opt/homebrew/bin', '/usr/local/bin'],
+      },
+      linux: {
+        kind: 'apt',
+        cmd: 'apt-get',
+        args: ['install', '-y', 'gh'],
+        requiresRoot: true,
+        url: 'https://cli.github.com',
+      },
+      win32: {
+        kind: 'winget',
+        cmd: 'winget',
+        args: ['install', '-e', '--id', 'GitHub.cli', '--accept-package-agreements', '--accept-source-agreements'],
+        postPath: ['C:\\Program Files\\GitHub CLI'],
+      },
+    },
+  },
+  {
+    id: 'vercel',
+    name: 'Vercel CLI',
+    blurb: 'Publishes your site to a public URL on the internet.',
+    detect: { cmd: 'vercel', args: ['--version'] },
+    fix: 'Install: npm i -g vercel',
+    install: {
+      darwin: {
+        kind: 'npm-g',
+        cmd: 'npm',
+        args: ['install', '-g', 'vercel'],
+      },
+      linux: {
+        kind: 'npm-g',
+        cmd: 'npm',
+        args: ['install', '-g', 'vercel'],
+        note: 'Stock apt-installed Node may need sudo for global installs.',
+      },
+      win32: {
+        kind: 'npm-g',
+        cmd: 'npm',
+        args: ['install', '-g', 'vercel'],
+        note: '%APPDATA%\\npm is on PATH by default with WinGet-installed Node.',
+      },
+    },
+  },
+];
+
+// Back-compat shape for preflight.mjs (and test/preflight.test.mjs which imports CHECKS).
+// Keep the array shape: { name, cmd: [bin, ...args], fix, minNodeMajor? }.
+export const CHECKS = REGISTRY.map((tool) => ({
+  name: tool.name,
+  cmd: [tool.detect.cmd, ...(tool.detect.args || [])],
+  fix: tool.fix,
+  ...(tool.detect.minMajor ? { minNodeMajor: tool.detect.minMajor } : {}),
+}));
+
+function defaultRunner(cmd, args = []) {
+  return execSync([cmd, ...args].join(' '), { stdio: ['ignore', 'pipe', 'ignore'] }).toString();
+}
+
+export function detectAll({ runner = defaultRunner } = {}) {
+  const found = [];
+  const missing = [];
+  for (const tool of REGISTRY) {
+    let out;
+    try {
+      out = runner(tool.detect.cmd, tool.detect.args || []);
+    } catch {
+      missing.push({ tool, reason: 'not-found' });
+      continue;
+    }
+    if (tool.detect.minMajor) {
+      const major = parseInt(String(out).replace(/^v/, '').split('.')[0], 10);
+      if (!Number.isFinite(major) || major < tool.detect.minMajor) {
+        missing.push({ tool, reason: 'version-too-old', detected: String(out).trim() });
+        continue;
+      }
+    }
+    found.push({ tool, version: String(out).trim() });
+  }
+  return { found, missing };
+}
+
+export function installCommandFor(toolOrId, platform = process.platform) {
+  const tool = typeof toolOrId === 'string'
+    ? REGISTRY.find((t) => t.id === toolOrId)
+    : toolOrId;
+  if (!tool) return null;
+  const plan = tool.install[platform];
+  if (plan) return plan;
+  return {
+    kind: 'manual',
+    url: tool.install.linux?.url || tool.install.darwin?.url || 'https://nodejs.org',
+    note: `No automatic install for platform ${platform}. Install ${tool.name} manually.`,
+  };
+}