@oaklandzoo/ostup 0.7.0 → 0.8.0

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']);
 
 async function readPkg() {
   const raw = await readFile(resolve(PKG_ROOT, 'package.json'), 'utf8');
@@ -44,6 +45,7 @@ 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.startsWith('-')) {
       process.stderr.write(`unknown flag: ${a}\n`);
       process.exit(1);
@@ -66,6 +68,7 @@ function printHelp() {
       '  init                Scaffold a new project (interactive or with --yes).',
       '  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.',
       '  update              Refresh bundled templates from the pinned source.',
       '',
       'Flags for `ostup init`:',
@@ -93,6 +96,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 +175,18 @@ 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);
+  }
+}
+
 // subcommand === 'init'
 if (flags.kitOnly) {
   const { scaffold } = await import('../src/scaffold.mjs');
@@ -185,12 +201,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',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oaklandzoo/ostup",
-  "version": "0.7.0",
+  "version": "0.8.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": {

package/src/doctor.mjs

@@ -0,0 +1,186 @@
+// doctor.mjs: self-diagnosis subcommand. Runs preflight + auth checks + permissions + reports.
+
+import { existsSync } from 'node:fs';
+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 { checkGithubAuth, checkVercelAuth } from './credential-prompts.mjs';
+
+function runOk(cmd) {
+  try {
+    execSync(cmd, { stdio: ['ignore', 'pipe', 'ignore'] });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function runCapture(cmd) {
+  try {
+    return execSync(cmd, { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+  } catch {
+    return null;
+  }
+}
+
+export async function runDoctor() {
+  const findings = [];
+  let okCount = 0;
+  let failCount = 0;
+  let warnCount = 0;
+
+  function report(level, label, detail) {
+    findings.push({ level, label, detail });
+    if (level === 'ok') okCount++;
+    else if (level === 'fail') failCount++;
+    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);
+  }
+
+  // === Git config ===
+  const gitName = runCapture('git config --global user.name');
+  const gitEmail = runCapture('git config --global user.email');
+  if (gitName && gitEmail) {
+    report('ok', 'git config', `${gitName} <${gitEmail}>`);
+  } else {
+    report('fail', 'git config', 'user.name or user.email not set; commits will fail. Run: git config --global user.name "Your Name" && git config --global user.email you@example.com');
+  }
+
+  // === GitHub auth ===
+  const gh = checkGithubAuth();
+  if (gh.ok) {
+    const ghUser = runCapture('gh api user --jq .login') || '(unknown)';
+    report('ok', 'gh auth', `authenticated as ${ghUser} (source: ${gh.source})`);
+    // Check scopes
+    const scopes = runCapture('gh auth status 2>&1 | grep -oE "Token scopes:.*"');
+    if (scopes) {
+      report('ok', 'gh scopes', scopes.replace('Token scopes:', '').trim());
+      if (!scopes.includes('delete_repo')) {
+        report('warn', 'gh delete_repo scope', 'missing; synthetic test cleanup will require manual deletion. Run: gh auth refresh -h github.com -s delete_repo');
+      }
+    }
+  } else {
+    report('fail', 'gh auth', 'not authenticated; run: gh auth login');
+  }
+
+  // === Vercel auth ===
+  const v = checkVercelAuth();
+  if (v.ok) {
+    const vUser = runCapture('vercel whoami');
+    report('ok', 'vercel auth', `authenticated as ${vUser || '(unknown)'} (source: ${v.source})`);
+
+    // Detect personal-account-as-scope risk
+    const teams = runCapture('vercel teams ls 2>&1 | grep -E "^✔|^\\*" | head -5');
+    if (teams) {
+      report('ok', 'vercel teams', teams.replace(/\n/g, '; '));
+    }
+  } else {
+    report('fail', 'vercel auth', 'not authenticated; run: vercel login');
+  }
+
+  // === Vercel AI Gateway key (optional but needed for /generate-image) ===
+  if (process.env.VERCEL_AI_GATEWAY_KEY) {
+    report('ok', 'VERCEL_AI_GATEWAY_KEY', 'present (image generation enabled)');
+  } else {
+    report('warn', 'VERCEL_AI_GATEWAY_KEY', 'not set; /generate-image will fail until set. Get key at https://vercel.com/dashboard/ai-gateway');
+  }
+
+  // === Chrome for screenshot verification ===
+  const chromeMac = '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome';
+  if (existsSync(chromeMac)) {
+    report('ok', 'chrome', 'present (visual verification supported per CLAUDE.md Part 19)');
+  } else if (runOk('which chromium 2>/dev/null') || runOk('which google-chrome 2>/dev/null')) {
+    report('ok', 'chrome', 'chromium or google-chrome on PATH');
+  } else {
+    report('warn', 'chrome', 'no Chrome detected; visual verification per CLAUDE.md Part 19 will not work. Install from https://www.google.com/chrome/');
+  }
+
+  // === Disk space in home dir ===
+  const dfHome = runCapture(`df -k ${homedir()} | tail -1 | awk '{print $4}'`);
+  if (dfHome) {
+    const kbFree = parseInt(dfHome, 10);
+    if (Number.isFinite(kbFree) && kbFree < 1024 * 1024) {
+      // less than 1 GB free
+      report('warn', 'disk space', `${(kbFree / 1024).toFixed(0)} MB free in ${homedir()}; scaffolds may fail (npm install needs ~500 MB)`);
+    } else {
+      report('ok', 'disk space', `${(kbFree / 1024 / 1024).toFixed(1)} GB free in ${homedir()}`);
+    }
+  }
+
+  // === Memory dir creatable ===
+  const memTest = join(homedir(), '.claude', 'projects', '__ostup_doctor_test__', 'memory');
+  try {
+    const { mkdir, rm } = await import('node:fs/promises');
+    await mkdir(memTest, { recursive: true });
+    await rm(memTest, { recursive: true, force: true });
+    report('ok', 'memory dir', 'can create ~/.claude/projects/<project>/memory at scaffold time');
+  } catch (err) {
+    report('fail', 'memory dir', `cannot create ~/.claude/projects/__ostup_doctor_test__/memory: ${err.message}`);
+  }
+
+  // === Log dir creatable ===
+  try {
+    const { mkdir } = await import('node:fs/promises');
+    await mkdir(join(homedir(), '.ostup', 'logs'), { recursive: true });
+    report('ok', 'log dir', `~/.ostup/logs/ writable (run logs land here)`);
+  } catch (err) {
+    report('fail', 'log dir', `cannot create ~/.ostup/logs/: ${err.message}`);
+  }
+
+  // === npm version (we don't call `npm bin` anymore, but warn on very old npm) ===
+  const npmVer = runCapture('npm --version');
+  if (npmVer) {
+    const major = parseInt(npmVer.split('.')[0], 10);
+    if (major < 9) {
+      report('warn', 'npm version', `${npmVer} is old; recommend npm 9+. Run: npm install -g npm@latest`);
+    } else {
+      report('ok', 'npm', npmVer);
+    }
+  }
+
+  // === ostup tarball install location (sanity) ===
+  const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+  report('ok', 'ostup install', pkgRoot);
+
+  return { findings, okCount, warnCount, failCount };
+}
+
+export function printDoctorReport({ findings, okCount, warnCount, failCount }) {
+  const lines = [];
+  lines.push('');
+  lines.push('=====================================');
+  lines.push('  ostup doctor: self-diagnosis');
+  lines.push('=====================================');
+  lines.push('');
+  for (const f of findings) {
+    const sym = f.level === 'ok' ? '  OK  ' : f.level === 'warn' ? ' WARN ' : ' FAIL ';
+    lines.push(`[${sym}] ${f.label.padEnd(28)} ${f.detail || ''}`);
+  }
+  lines.push('');
+  lines.push(`Summary: ${okCount} OK, ${warnCount} WARN, ${failCount} FAIL`);
+  lines.push('');
+  if (failCount > 0) {
+    lines.push('Fix the FAILs before running `ostup init`. WARNs are optional.');
+  } else if (warnCount > 0) {
+    lines.push('No blockers. WARNs are optional improvements.');
+  } else {
+    lines.push('Everything clean. Ready to scaffold.');
+  }
+  lines.push('');
+  return lines.join('\n');
+}

package/src/exec.mjs

@@ -1,5 +1,6 @@
 // exec.mjs: uniform shell call wrapper with logging, dry-run capture, and step-aware error formatting.
 import { execa } from 'execa';
+import { traceStep, getLogPath } from './tracer.mjs';
 
 const HINTS = {
   'gh repo create': 'Confirm the repo name is not already taken under this owner.',
@@ -56,19 +57,55 @@ export async function run(step, cmd, args = [], opts = {}) {
     return { stdout: '', stderr: '', exitCode: 0, dryRun: true };
   }
   if (!_quiet) process.stdout.write(`[${step}] start: ${display}\n`);
+  const start = Date.now();
   try {
-    return await _runner(cmd, args, { ...opts });
+    const result = await _runner(cmd, args, { ...opts });
+    const duration = Date.now() - start;
+    await traceStep({
+      step, cmd, args,
+      stdout: result?.stdout || '',
+      stderr: result?.stderr || '',
+      exitCode: result?.exitCode || 0,
+      durationMs: duration,
+    });
+    return result;
   } catch (err) {
-    const stderr = (err && (err.stderr || err.shortMessage || err.message) || '').toString().trim();
-    process.stderr.write(
-      [
-        `[${step}] FAIL`,
-        `  Command: ${display}`,
-        `  Stderr:  ${stderr || '(empty)'}`,
-        `  Fix:     ${hintFor(cmd, args)}`,
-        'Exit 1.',
-      ].join('\n') + '\n'
-    );
+    const duration = Date.now() - start;
+    const stdout = (err && err.stdout || '').toString();
+    const stderr = (err && err.stderr || '').toString();
+    const message = (err && (err.shortMessage || err.message) || '').toString().trim();
+
+    // Capture both stdout AND stderr (was stderr-only). Some tools (vercel, gh) output errors to stdout.
+    const stdoutTail = stdout.split('\n').slice(-15).join('\n').trim();
+    const stderrTail = stderr.split('\n').slice(-15).join('\n').trim();
+    const logPath = getLogPath();
+
+    const lines = [`[${step}] FAIL`, `  Command: ${display}`];
+    if (stderrTail) {
+      lines.push(`  Stderr (last 15 lines):`);
+      for (const l of stderrTail.split('\n')) lines.push(`    ${l}`);
+    }
+    if (stdoutTail) {
+      lines.push(`  Stdout (last 15 lines):`);
+      for (const l of stdoutTail.split('\n')) lines.push(`    ${l}`);
+    }
+    if (!stderrTail && !stdoutTail && message) {
+      lines.push(`  Error: ${message}`);
+    }
+    lines.push(`  Fix:     ${hintFor(cmd, args)}`);
+    if (logPath) {
+      lines.push(`  Log:     ${logPath}`);
+    }
+    lines.push('Exit 1.');
+    process.stderr.write(lines.join('\n') + '\n');
+
+    await traceStep({
+      step, cmd, args,
+      stdout, stderr,
+      exitCode: err?.exitCode || 1,
+      durationMs: duration,
+    });
+
     const e = new Error(`step ${step} failed`);
     e.code = 'STEP_FAILED';
     e.step = step;

package/src/tracer.mjs

@@ -0,0 +1,116 @@
+// tracer.mjs: structured per-run log file. Writes every step + output to ~/.ostup/logs/<run-id>.log.
+// Auto-enabled on every ostup init / brief / export-pro run unless --no-log is passed.
+
+import { existsSync } from 'node:fs';
+import { mkdir, appendFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+let _enabled = true;
+let _logPath = null;
+let _runId = null;
+
+export function disableTracer() {
+  _enabled = false;
+}
+
+export function enableTracer() {
+  _enabled = true;
+}
+
+export function isTracerEnabled() {
+  return _enabled;
+}
+
+export async function startRun({ label = 'run' } = {}) {
+  if (!_enabled) return null;
+  _runId = `${label}-${new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19)}`;
+  const dir = join(homedir(), '.ostup', 'logs');
+  await mkdir(dir, { recursive: true });
+  _logPath = join(dir, `${_runId}.log`);
+  await appendFile(_logPath, `# ostup run ${_runId}\n# started: ${new Date().toISOString()}\n# cwd: ${process.cwd()}\n# argv: ${process.argv.slice(2).join(' ')}\n\n`);
+  return _logPath;
+}
+
+export async function trace(category, message) {
+  if (!_enabled || !_logPath) return;
+  const stamp = new Date().toISOString();
+  const line = `[${stamp}] [${category}] ${message}\n`;
+  try {
+    await appendFile(_logPath, line);
+  } catch {
+    // Logging must never crash the main flow.
+  }
+}
+
+export async function traceStep({ step, cmd, args = [], stdout = '', stderr = '', exitCode = 0, durationMs = 0 }) {
+  if (!_enabled || !_logPath) return;
+  const display = `${cmd} ${(args || []).join(' ')}`.trim();
+  const stdoutTail = (stdout || '').toString().split('\n').slice(-30).join('\n');
+  const stderrTail = (stderr || '').toString().split('\n').slice(-30).join('\n');
+  const lines = [
+    `## step ${step} | exit=${exitCode} | ${durationMs}ms`,
+    `  cmd: ${display}`,
+  ];
+  if (stdoutTail.trim()) {
+    lines.push(`  stdout (last 30 lines):`);
+    for (const l of stdoutTail.split('\n')) lines.push(`    ${l}`);
+  }
+  if (stderrTail.trim()) {
+    lines.push(`  stderr (last 30 lines):`);
+    for (const l of stderrTail.split('\n')) lines.push(`    ${l}`);
+  }
+  lines.push('');
+  try {
+    await appendFile(_logPath, lines.join('\n'));
+  } catch {
+    // ignore
+  }
+}
+
+export async function traceError(category, err) {
+  if (!_enabled || !_logPath) return;
+  const stamp = new Date().toISOString();
+  const lines = [
+    `## ERROR [${stamp}] [${category}]`,
+    `  message: ${err?.message || err}`,
+    `  code:    ${err?.code || '(none)'}`,
+  ];
+  if (err?.cause) {
+    lines.push(`  cause:`);
+    const causeStr = (err.cause.message || String(err.cause)).split('\n');
+    for (const l of causeStr.slice(0, 20)) lines.push(`    ${l}`);
+  }
+  if (err?.stack) {
+    lines.push(`  stack (first 10 lines):`);
+    for (const l of err.stack.split('\n').slice(0, 10)) lines.push(`    ${l}`);
+  }
+  lines.push('');
+  try {
+    await appendFile(_logPath, lines.join('\n'));
+  } catch {
+    // ignore
+  }
+}
+
+export async function endRun({ ok = true } = {}) {
+  if (!_enabled || !_logPath) return null;
+  const stamp = new Date().toISOString();
+  try {
+    await appendFile(_logPath, `\n# ended: ${stamp}\n# status: ${ok ? 'ok' : 'failed'}\n`);
+  } catch {
+    // ignore
+  }
+  const path = _logPath;
+  _logPath = null;
+  _runId = null;
+  return path;
+}
+
+export function getLogPath() {
+  return _logPath;
+}
+
+export function getRunId() {
+  return _runId;
+}