@oaklandzoo/ostup 0.7.0 → 0.9.0

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,17 @@ 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`. |
 
 ## Advanced: API tokens instead of interactive login
 

package/bin/cli.mjs

@@ -5,12 +5,13 @@ import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { loadDotEnv } from '../src/env-loader.mjs';
 import { setDryRun } from '../src/exec.mjs';
+import { startRun, endRun, disableTracer, traceError } from '../src/tracer.mjs';
 
 loadDotEnv();
 
 const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
-const SUBCOMMANDS = new Set(['init', 'update', 'brief', 'export-pro']);
+const SUBCOMMANDS = new Set(['init', 'update', 'brief', 'export-pro', 'doctor', 'bootstrap']);
 
 async function readPkg() {
   const raw = await readFile(resolve(PKG_ROOT, 'package.json'), 'utf8');
@@ -44,6 +45,9 @@ function parseArgs(argv) {
     else if (a === '--output') flags.output = argv[++i];
     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);
@@ -59,13 +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: tool detection + auth + permissions + disk + Chrome. Read-only.',
       '  update              Refresh bundled templates from the pinned source.',
       '',
       'Flags for `ostup init`:',
@@ -79,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.',
@@ -93,6 +111,7 @@ function printHelp() {
       'Global flags:',
       '  --version, -v       Print version and exit.',
       '  --help, -h          Print this help and exit.',
+      '  --no-log            Disable auto-logging to ~/.ostup/logs/. (default: write a log per run)',
       '',
     ].join('\n')
   );
@@ -171,6 +190,36 @@ if (subcommand === 'export-pro') {
   }
 }
 
+if (subcommand === 'doctor') {
+  const { runDoctor, printDoctorReport } = await import('../src/doctor.mjs');
+  try {
+    const result = await runDoctor();
+    process.stdout.write(printDoctorReport(result));
+    process.exit(result.failCount > 0 ? 1 : 0);
+  } catch (err) {
+    process.stderr.write(`doctor failed: ${err.message}\n`);
+    process.exit(2);
+  }
+}
+
+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');
@@ -185,12 +234,20 @@ if (flags.kitOnly) {
   }
 }
 
+if (flags.noLog) disableTracer();
+const logPath = await startRun({ label: 'init' });
+if (logPath) process.stdout.write(`Logging this run to ${logPath}\n`);
+
 const { runMvp } = await import('../src/mvp-flow.mjs');
 try {
   await runMvp({ flags });
+  await endRun({ ok: true });
   process.exit(0);
 } catch (err) {
+  await traceError('init', err);
+  await endRun({ ok: false });
   process.stderr.write(`${err.message}\n`);
+  if (logPath) process.stderr.write(`Full run log: ${logPath}\n`);
   const userErrors = new Set([
     'NO_TTY',
     'USER_ABORT',
@@ -200,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.7.0",
+  "version": "0.9.0",
   "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 "$@"