@oaklandzoo/ostup 0.11.0 → 0.12.0

package/README.md

@@ -32,6 +32,18 @@ When you run this tool, it will:
    verify. Toggle on/off an existing project with `ostup private add` /
    `ostup private remove` (manifest at `.ostup/private.json` makes the
    remove cleanly revertable).
+9. Optionally pass `--auth=clerk` or `--auth=google` to wire **a
+   working login flow** into the scaffold. Clerk uses `@clerk/nextjs`
+   (hosted UI, free up to 10k MAU); Google uses NextAuth v5 with the
+   Google provider (free; you create the OAuth app on Google Cloud).
+   Both ship sign-in / sign-up pages out of the box. `--auth` composes
+   cleanly with `--private` (the default-deny middleware recognizes
+   both providers' session cookies).
+10. Optionally pass `--publish-ready` if this CLI will be used to
+    publish an npm package later. ostup walks you through getting an
+    npm Bypass-2FA token (browser flow or guided token paste) and
+    saves it to `~/.npmrc`. After that, the `/publish` slash command
+    lets your agent ship a new version with one command.
 
 ## Quick Start
 

package/bin/cli.mjs

@@ -45,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 === '--auth') flags.auth = argv[++i];
+    else if (a.startsWith('--auth=')) flags.auth = a.slice('--auth='.length);
+    else if (a === '--publish-ready') flags.publishReady = true;
     else if (a === '--private') flags.private = true;
     else if (a === '--privacy') flags.privacy = true;
     else if (a === '--url') flags.url = argv[++i];
@@ -96,6 +99,8 @@ function printHelp() {
       '  --brief <path>      Load a brief.json from <path> and write brief files + apply profile overlay.',
       '  --white-label       Strip OSTUP / Goodshin attribution from generated docs (Studio tier).',
       '  --private           App-level default-deny: middleware, blob proxy, image-optimizer lock, audit + rate-limit, CLAUDE.md Part 20. Refused with --profile saas-dashboard.',
+      '  --auth <provider>   Wire authentication. Values: clerk (Clerk + @clerk/nextjs), google (NextAuth v5 + Google), none. Refused with --profile saas-dashboard.',
+      '  --publish-ready     Walk through npm token setup so this CLI can publish later (writes ~/.npmrc).',
       '  --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).',
@@ -283,6 +288,13 @@ try {
     'INGEST_PATH_NOT_FOUND',
     'BRIEF_NOT_FOUND',
     'BRIEF_INVALID',
+    'AUTH_ALREADY_APPLIED',
+    'AUTH_PROFILE_CONFLICT',
+    'AUTH_DIRTY',
+    'AUTH_UNKNOWN_PROVIDER',
+    'PRIVATE_SAAS_CONFLICT',
+    'PRIVATE_ALREADY_APPLIED',
+    'PRIVATE_DIRTY',
     'NO_TTY_BOOTSTRAP',
     'BOOTSTRAP_DECLINED',
     'BOOTSTRAP_FAILED',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oaklandzoo/ostup",
-  "version": "0.11.0",
+  "version": "0.12.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/scripts/verify-auth.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# verify-auth.sh: apply an auth overlay to a fresh temp dir and assert files + manifest land.
+#
+# Usage: bash scripts/verify-auth.sh <clerk|google>
+
+set -euo pipefail
+
+PROVIDER="${1:-}"
+case "$PROVIDER" in
+  clerk|google) ;;
+  *)
+    echo "usage: $0 <clerk|google>" >&2
+    exit 2
+    ;;
+esac
+
+OSTUP_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+TEST_FILE="$OSTUP_ROOT/test/auth-$PROVIDER.test.mjs"
+
+echo ">> verifying auth provider: $PROVIDER"
+echo ">> running: node --test $TEST_FILE"
+cd "$OSTUP_ROOT"
+node --test "$TEST_FILE"
+
+echo ">> ok: $PROVIDER overlay applies and asserts pass"
+echo ""
+echo ">> for live verification (operator only):"
+echo "   1. ostup init --yes --name verify-auth --brief test/fixtures/brief-leadgen.json --auth=$PROVIDER"
+echo "   2. cd verify-auth && npm install && npx next build"
+echo "   3. open the deployed URL, sign in, verify session lands on /dashboard"

package/src/auth-clerk.mjs

@@ -0,0 +1,146 @@
+// auth-clerk.mjs: applyAuthClerk post-processor. Drops Clerk integration into a scaffold.
+
+import { readFile, writeFile, mkdir, rm } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const TEMPLATES_ROOT = resolve(PKG_ROOT, 'templates', 'auth-clerk');
+
+export const AUTH_MANIFEST_PATH = '.ostup/auth.json';
+
+class AuthError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+
+function plannedOps(targetDir) {
+  return [
+    { kind: 'create-or-overwrite', dest: 'middleware.ts', src: 'middleware.ts' },
+    { kind: 'create-or-overwrite', dest: 'app/layout.tsx', src: 'layout.tsx' },
+    { kind: 'create', dest: 'app/sign-in/[[...sign-in]]/page.tsx', src: 'sign-in-page.tsx' },
+    { kind: 'create', dest: 'app/sign-up/[[...sign-up]]/page.tsx', src: 'sign-up-page.tsx' },
+    { kind: 'package-merge', dest: 'package.json', src: 'package.json.additions' },
+    { kind: 'env-append', dest: '.env.example', src: 'env.example.additions' },
+  ];
+}
+
+async function loadTemplate(rel) {
+  return readFile(join(TEMPLATES_ROOT, rel), 'utf8');
+}
+
+function tokenSubstitute(body, tokens) {
+  if (!tokens) return body;
+  return body.replace(/\{\{([A-Z_][A-Z_0-9]*)\}\}/g, (m, k) => (tokens[k] != null ? String(tokens[k]) : 'TBD'));
+}
+
+function mergePackageJson(existing, additionsText) {
+  const additions = JSON.parse(additionsText);
+  const target = existing ? JSON.parse(existing) : {};
+  for (const section of ['dependencies', 'devDependencies', 'scripts']) {
+    if (additions[section]) {
+      target[section] = { ...(target[section] || {}), ...additions[section] };
+    }
+  }
+  return JSON.stringify(target, null, 2) + '\n';
+}
+
+export async function applyAuthClerk({ targetDir, profile = null, tokens = {}, force = false } = {}) {
+  const manifestPath = join(targetDir, AUTH_MANIFEST_PATH);
+  if (existsSync(manifestPath) && !force) {
+    const manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+    throw new AuthError(
+      'AUTH_ALREADY_APPLIED',
+      `${AUTH_MANIFEST_PATH} already exists (provider: ${manifest.provider}). Run remove first, or pass --force.`,
+    );
+  }
+  if (profile === 'saas-dashboard') {
+    throw new AuthError(
+      'AUTH_PROFILE_CONFLICT',
+      '--auth=clerk is not compatible with --profile saas-dashboard. saas-dashboard ships Better Auth. Pick one.',
+    );
+  }
+
+  const ops = plannedOps(targetDir);
+  const performed = [];
+
+  for (const op of ops) {
+    const destPath = join(targetDir, op.dest);
+    const tmpl = await loadTemplate(op.src);
+    const content = tokenSubstitute(tmpl, tokens);
+
+    if (op.kind === 'create') {
+      if (existsSync(destPath) && !force) {
+        throw new AuthError('AUTH_DIRTY', `${op.dest} already exists; refuse to overwrite without --force.`);
+      }
+      await mkdir(dirname(destPath), { recursive: true });
+      await writeFile(destPath, content, 'utf8');
+      performed.push({ kind: 'created', path: op.dest });
+    } else if (op.kind === 'create-or-overwrite') {
+      const prior = existsSync(destPath) ? await readFile(destPath, 'utf8') : null;
+      await mkdir(dirname(destPath), { recursive: true });
+      await writeFile(destPath, content, 'utf8');
+      if (prior !== null) {
+        performed.push({ kind: 'replaced', path: op.dest, prior });
+      } else {
+        performed.push({ kind: 'created', path: op.dest });
+      }
+    } else if (op.kind === 'package-merge') {
+      const prior = existsSync(destPath) ? await readFile(destPath, 'utf8') : null;
+      const merged = mergePackageJson(prior, content);
+      await mkdir(dirname(destPath), { recursive: true });
+      await writeFile(destPath, merged, 'utf8');
+      if (prior !== null) {
+        performed.push({ kind: 'patched', path: op.dest, prior });
+      } else {
+        performed.push({ kind: 'created', path: op.dest });
+      }
+    } else if (op.kind === 'env-append') {
+      const prior = existsSync(destPath) ? await readFile(destPath, 'utf8') : null;
+      const next = prior ? prior + (prior.endsWith('\n') ? '' : '\n') + '\n' + content : content;
+      await mkdir(dirname(destPath), { recursive: true });
+      await writeFile(destPath, next, 'utf8');
+      if (prior !== null) {
+        performed.push({ kind: 'patched', path: op.dest, prior });
+      } else {
+        performed.push({ kind: 'created', path: op.dest });
+      }
+    }
+  }
+
+  await mkdir(dirname(manifestPath), { recursive: true });
+  await writeFile(
+    manifestPath,
+    JSON.stringify({ appliedAt: new Date().toISOString(), provider: 'clerk', ops: performed }, null, 2) + '\n',
+    'utf8',
+  );
+
+  return { applied: true, provider: 'clerk', touched: performed.map((p) => p.path) };
+}
+
+export async function removeAuthClerk({ targetDir } = {}) {
+  const manifestPath = join(targetDir, AUTH_MANIFEST_PATH);
+  if (!existsSync(manifestPath)) {
+    throw new AuthError('AUTH_NOT_APPLIED', `${AUTH_MANIFEST_PATH} not found.`);
+  }
+  const manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+  const restored = [];
+  for (const op of [...manifest.ops].reverse()) {
+    const p = join(targetDir, op.path);
+    if (op.kind === 'created' && existsSync(p)) {
+      await rm(p, { force: true });
+      restored.push({ kind: 'deleted', path: op.path });
+    } else if ((op.kind === 'replaced' || op.kind === 'patched') && existsSync(p)) {
+      await writeFile(p, op.prior, 'utf8');
+      restored.push({ kind: 'restored', path: op.path });
+    }
+  }
+  await rm(manifestPath, { force: true });
+  try { await rm(join(targetDir, '.ostup'), { recursive: false }); } catch {}
+  return { restored: restored.map((r) => r.path), provider: manifest.provider };
+}
+
+export { AuthError };

package/src/auth-google.mjs

@@ -0,0 +1,137 @@
+// auth-google.mjs: applyAuthGoogle post-processor. Drops NextAuth v5 + Google provider into a scaffold.
+
+import { readFile, writeFile, mkdir, rm } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const TEMPLATES_ROOT = resolve(PKG_ROOT, 'templates', 'auth-google');
+
+export const AUTH_MANIFEST_PATH = '.ostup/auth.json';
+
+class AuthError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+
+function plannedOps() {
+  return [
+    { kind: 'create', dest: 'auth.ts', src: 'auth.ts' },
+    { kind: 'create', dest: 'app/api/auth/[...nextauth]/route.ts', src: 'route.ts' },
+    { kind: 'create', dest: 'app/sign-in/page.tsx', src: 'sign-in-page.tsx' },
+    { kind: 'create', dest: 'app/sign-up/page.tsx', src: 'sign-up-page.tsx' },
+    { kind: 'package-merge', dest: 'package.json', src: 'package.json.additions' },
+    { kind: 'env-append', dest: '.env.example', src: 'env.example.additions' },
+  ];
+}
+
+async function loadTemplate(rel) {
+  return readFile(join(TEMPLATES_ROOT, rel), 'utf8');
+}
+
+function tokenSubstitute(body, tokens) {
+  if (!tokens) return body;
+  return body.replace(/\{\{([A-Z_][A-Z_0-9]*)\}\}/g, (m, k) => (tokens[k] != null ? String(tokens[k]) : 'TBD'));
+}
+
+function mergePackageJson(existing, additionsText) {
+  const additions = JSON.parse(additionsText);
+  const target = existing ? JSON.parse(existing) : {};
+  for (const section of ['dependencies', 'devDependencies', 'scripts']) {
+    if (additions[section]) {
+      target[section] = { ...(target[section] || {}), ...additions[section] };
+    }
+  }
+  return JSON.stringify(target, null, 2) + '\n';
+}
+
+export async function applyAuthGoogle({ targetDir, profile = null, tokens = {}, force = false } = {}) {
+  const manifestPath = join(targetDir, AUTH_MANIFEST_PATH);
+  if (existsSync(manifestPath) && !force) {
+    const manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+    throw new AuthError(
+      'AUTH_ALREADY_APPLIED',
+      `${AUTH_MANIFEST_PATH} already exists (provider: ${manifest.provider}). Run remove first, or pass --force.`,
+    );
+  }
+  if (profile === 'saas-dashboard') {
+    throw new AuthError(
+      'AUTH_PROFILE_CONFLICT',
+      '--auth=google is not compatible with --profile saas-dashboard. saas-dashboard ships Better Auth. Pick one.',
+    );
+  }
+
+  const ops = plannedOps();
+  const performed = [];
+
+  for (const op of ops) {
+    const destPath = join(targetDir, op.dest);
+    const tmpl = await loadTemplate(op.src);
+    const content = tokenSubstitute(tmpl, tokens);
+
+    if (op.kind === 'create') {
+      if (existsSync(destPath) && !force) {
+        throw new AuthError('AUTH_DIRTY', `${op.dest} already exists; refuse to overwrite without --force.`);
+      }
+      await mkdir(dirname(destPath), { recursive: true });
+      await writeFile(destPath, content, 'utf8');
+      performed.push({ kind: 'created', path: op.dest });
+    } else if (op.kind === 'package-merge') {
+      const prior = existsSync(destPath) ? await readFile(destPath, 'utf8') : null;
+      const merged = mergePackageJson(prior, content);
+      await mkdir(dirname(destPath), { recursive: true });
+      await writeFile(destPath, merged, 'utf8');
+      if (prior !== null) {
+        performed.push({ kind: 'patched', path: op.dest, prior });
+      } else {
+        performed.push({ kind: 'created', path: op.dest });
+      }
+    } else if (op.kind === 'env-append') {
+      const prior = existsSync(destPath) ? await readFile(destPath, 'utf8') : null;
+      const next = prior ? prior + (prior.endsWith('\n') ? '' : '\n') + '\n' + content : content;
+      await mkdir(dirname(destPath), { recursive: true });
+      await writeFile(destPath, next, 'utf8');
+      if (prior !== null) {
+        performed.push({ kind: 'patched', path: op.dest, prior });
+      } else {
+        performed.push({ kind: 'created', path: op.dest });
+      }
+    }
+  }
+
+  await mkdir(dirname(manifestPath), { recursive: true });
+  await writeFile(
+    manifestPath,
+    JSON.stringify({ appliedAt: new Date().toISOString(), provider: 'google', ops: performed }, null, 2) + '\n',
+    'utf8',
+  );
+
+  return { applied: true, provider: 'google', touched: performed.map((p) => p.path) };
+}
+
+export async function removeAuthGoogle({ targetDir } = {}) {
+  const manifestPath = join(targetDir, AUTH_MANIFEST_PATH);
+  if (!existsSync(manifestPath)) {
+    throw new AuthError('AUTH_NOT_APPLIED', `${AUTH_MANIFEST_PATH} not found.`);
+  }
+  const manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+  const restored = [];
+  for (const op of [...manifest.ops].reverse()) {
+    const p = join(targetDir, op.path);
+    if (op.kind === 'created' && existsSync(p)) {
+      await rm(p, { force: true });
+      restored.push({ kind: 'deleted', path: op.path });
+    } else if (op.kind === 'patched' && existsSync(p)) {
+      await writeFile(p, op.prior, 'utf8');
+      restored.push({ kind: 'restored', path: op.path });
+    }
+  }
+  await rm(manifestPath, { force: true });
+  try { await rm(join(targetDir, '.ostup'), { recursive: false }); } catch {}
+  return { restored: restored.map((r) => r.path), provider: manifest.provider };
+}
+
+export { AuthError };

package/src/credential-prompts-npm.mjs

@@ -0,0 +1,154 @@
+// credential-prompts-npm.mjs: detect npm credentials, walk operator through token-paste or browser flow.
+
+import * as p from '@clack/prompts';
+import { execSync } from 'node:child_process';
+import { readFileSync, existsSync, appendFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { run as exec } from './exec.mjs';
+
+const NPMRC_PATH = join(homedir(), '.npmrc');
+
+export function checkNpmAuth({ env = process.env, runner = defaultCmdOk, npmrcReader = defaultNpmrcReader } = {}) {
+  if (env.NPM_TOKEN) return { ok: true, source: 'env' };
+  const npmrc = npmrcReader();
+  if (npmrc && /_authToken=/.test(npmrc)) return { ok: true, source: 'npmrc' };
+  if (runner('npm whoami')) return { ok: true, source: 'npm-cli' };
+  return { ok: false };
+}
+
+function defaultCmdOk(cmd) {
+  try {
+    execSync(cmd, { stdio: ['ignore', 'ignore', 'ignore'] });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function defaultNpmrcReader() {
+  try {
+    return existsSync(NPMRC_PATH) ? readFileSync(NPMRC_PATH, 'utf8') : '';
+  } catch {
+    return '';
+  }
+}
+
+const NPM_BLURB = [
+  '',
+  'npm credentials not found.',
+  '',
+  'Why this matters: if you ever want to publish a package from this machine,',
+  'you need a token. Skip this step if you are only building apps (most users).',
+  '',
+  'If you do not have an npm account yet:',
+  '  1. Open https://www.npmjs.com/signup',
+  '  2. Create an account, then return here.',
+  '',
+  'To create a granular Bypass-2FA token (recommended; survives 2FA-required publishes):',
+  '  1. Open https://www.npmjs.com/settings/<your-username>/tokens/new',
+  '  2. Token type: Granular access token',
+  '  3. Expiration: 90 days (or longer)',
+  '  4. Packages and scopes: select what you plan to publish',
+  '  5. Permissions: Read and Write',
+  '  6. 2FA: select "Bypass 2FA"',
+  '  7. Generate token, copy the value (starts with npm_)',
+  '',
+].join('\n');
+
+export async function promptForNpmToken() {
+  process.stdout.write(NPM_BLURB);
+  const token = await p.password({
+    message: 'Paste your npm token (starts with npm_; leave blank to skip)',
+  });
+  if (p.isCancel(token)) return null;
+  const trimmed = typeof token === 'string' ? token.trim() : '';
+  if (!trimmed) return null;
+  return trimmed;
+}
+
+function binaryOnPath(bin) {
+  try {
+    execSync(`${bin} --version`, { stdio: ['ignore', 'ignore', 'ignore'] });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function chooseNpmAuthMethod() {
+  const choice = await p.select({
+    message: 'npm: how would you like to set up publishing?',
+    options: [
+      { value: 'browser', label: 'Sign in via npm login --auth-type=web (recommended)' },
+      { value: 'token', label: 'Paste a Bypass-2FA token instead' },
+      { value: 'skip', label: 'Skip for now (no publishing from this machine)' },
+    ],
+    initialValue: 'browser',
+  });
+  if (p.isCancel(choice)) return 'skip';
+  return choice;
+}
+
+async function attemptBrowserAuth() {
+  try {
+    await exec('npm-login', 'npm', ['login', '--auth-type=web'], { stdio: 'inherit' });
+    return true;
+  } catch {
+    process.stdout.write('npm browser sign-in did not complete. Falling back to token paste.\n');
+    return false;
+  }
+}
+
+function writeNpmrcToken(token, npmrcPath = NPMRC_PATH) {
+  const line = `//registry.npmjs.org/:_authToken=${token}\n`;
+  if (existsSync(npmrcPath)) {
+    const existing = readFileSync(npmrcPath, 'utf8');
+    if (existing.includes('//registry.npmjs.org/:_authToken=')) {
+      const replaced = existing.replace(/^\/\/registry\.npmjs\.org\/:_authToken=.*$/m, line.trim());
+      writeFileSync(npmrcPath, replaced, 'utf8');
+    } else {
+      appendFileSync(npmrcPath, (existing.endsWith('\n') ? '' : '\n') + line, 'utf8');
+    }
+  } else {
+    writeFileSync(npmrcPath, line, 'utf8');
+  }
+}
+
+export async function ensureNpmCredentials({ flags = {} } = {}) {
+  const result = checkNpmAuth();
+  if (result.ok) {
+    process.stdout.write(`npm: using existing auth (${result.source}).\n`);
+    return { ok: true, source: result.source };
+  }
+
+  if (!binaryOnPath('npm')) {
+    process.stdout.write('npm CLI not on PATH; skipping npm setup.\n');
+    return { ok: false, source: 'missing-npm' };
+  }
+
+  const method = flags.yes ? 'skip' : await chooseNpmAuthMethod();
+  if (method === 'skip') {
+    process.stdout.write('npm: setup skipped. Run `npm login` later if you need to publish.\n');
+    return { ok: false, source: 'skipped' };
+  }
+
+  if (method === 'browser') {
+    const ok = await attemptBrowserAuth();
+    if (ok && checkNpmAuth().ok) {
+      process.stdout.write('npm: signed in via browser.\n');
+      return { ok: true, source: 'browser' };
+    }
+  }
+
+  const token = await promptForNpmToken();
+  if (!token) {
+    process.stdout.write('npm: no token provided. Skipping.\n');
+    return { ok: false, source: 'skipped' };
+  }
+  writeNpmrcToken(token);
+  process.stdout.write(`npm: token saved to ${NPMRC_PATH}.\n`);
+  return { ok: true, source: 'npmrc-write' };
+}
+
+export { writeNpmrcToken, NPMRC_PATH };

package/src/credential-prompts.mjs

@@ -2,6 +2,7 @@
 import * as p from '@clack/prompts';
 import { execSync } from 'node:child_process';
 import { run as exec } from './exec.mjs';
+import { ensureNpmCredentials } from './credential-prompts-npm.mjs';
 
 export function checkGithubAuth({ env = process.env, runner = defaultCmdOk } = {}) {
   if (env.GH_TOKEN) return { ok: true, source: 'env-or-dotenv' };
@@ -178,5 +179,9 @@ export async function ensureCredentials({ stack = 'next', flags = {} } = {}) {
     }
   }
 
+  if (flags.publishReady) {
+    await ensureNpmCredentials({ flags });
+  }
+
   return { collected };
 }

package/src/mvp-flow.mjs

@@ -134,6 +134,23 @@ export async function runMvp({ flags = {}, cwd = process.cwd() } = {}) {
     }
   }
 
+  if (flags.auth && flags.auth !== 'none') {
+    const profile = brief?.scaffold?.profile || null;
+    if (flags.auth === 'clerk') {
+      const { applyAuthClerk } = await import('./auth-clerk.mjs');
+      const r = await applyAuthClerk({ targetDir, profile, tokens });
+      process.stdout.write(`[auth] applied clerk overlay. ${r.touched.length} file(s) touched\n`);
+    } else if (flags.auth === 'google') {
+      const { applyAuthGoogle } = await import('./auth-google.mjs');
+      const r = await applyAuthGoogle({ targetDir, profile, tokens });
+      process.stdout.write(`[auth] applied google overlay. ${r.touched.length} file(s) touched\n`);
+    } else {
+      const err = new Error(`Unknown --auth value '${flags.auth}'. Use clerk, google, or none.`);
+      err.code = 'AUTH_UNKNOWN_PROVIDER';
+      throw err;
+    }
+  }
+
   if (flags.private) {
     const { applyPrivate } = await import('./private.mjs');
     const profile = brief?.scaffold?.profile || null;

package/templates/.claude/commands/add-auth.md

@@ -0,0 +1,87 @@
+---
+description: Add authentication to this project after the fact. Clerk or Google OAuth (NextAuth v5).
+---
+
+# Add auth
+
+Use this when the project was scaffolded without `--auth` and the operator now wants login.
+
+## Step 1: Which provider?
+
+If the operator named one (e.g. `/add-auth clerk`), use it. Otherwise ask:
+
+| Provider | Cost | Best for |
+|---|---|---|
+| `clerk` | Free tier up to 10k MAU | Production-grade hosted auth UI; faster setup |
+| `google` | Free | Sign in with Google only (no custom auth); requires Google Cloud Console |
+
+## Step 2: Apply the overlay
+
+Run from the project root:
+
+```bash
+ostup private add  # if you also want default-deny middleware (skip if already on)
+```
+
+Then for Clerk:
+
+```bash
+# Manually run the auth-clerk overlay path (or rerun ostup with --auth=clerk via update)
+```
+
+Or scaffold the files by hand from the templates at `node_modules/@oaklandzoo/ostup/templates/auth-clerk/` (or `auth-google/`).
+
+## Step 3: Get the keys
+
+### Clerk
+
+1. Open https://dashboard.clerk.com/apps
+2. Click **Create application** if you do not have one. Name it the project name. Select Email + Google.
+3. Once created, go to **API Keys**. Copy:
+   - **Publishable key** → `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY`
+   - **Secret key** → `CLERK_SECRET_KEY`
+4. Paste both into `.env.local`.
+
+### Google OAuth
+
+1. Open https://console.cloud.google.com/apis/credentials/oauthclient
+2. **Application type**: Web application.
+3. **Authorized redirect URIs**: add `http://localhost:3000/api/auth/callback/google` AND your production URL with the same path.
+4. Click **Create**. Copy:
+   - **Client ID** → `GOOGLE_CLIENT_ID`
+   - **Client secret** → `GOOGLE_CLIENT_SECRET`
+5. Generate a NextAuth secret:
+   ```bash
+   openssl rand -base64 32
+   ```
+   Paste as `AUTH_SECRET`.
+6. Paste all three into `.env.local`.
+
+## Step 4: Verify
+
+```bash
+npm run dev
+```
+
+Open http://localhost:3000/sign-in. You should see the Clerk widget or the Google sign-in button. Sign in. You should land on `/dashboard` or `/`.
+
+If the sign-in page renders but sign-in fails, double-check the env vars are loaded (`npm run dev` reads `.env.local` automatically).
+
+## Step 5: Deploy the env vars to Vercel
+
+```bash
+vercel env add NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY production    # repeat per env per key
+```
+
+Or paste them into the Vercel dashboard under **Settings → Environment Variables**.
+
+## Report
+
+```
+Added <provider> auth:
+- Provider:  <clerk|google>
+- Sign-in:   /sign-in
+- Sign-up:   /sign-up
+- Protected: /dashboard
+- Env vars:  added to .env.local (also push to Vercel before deploying)
+```

package/templates/.claude/commands/publish.md

@@ -0,0 +1,77 @@
+---
+description: Publish a new version of this package to npm. Bumps version, runs tests, publishes, tags, pushes.
+---
+
+# Publish to npm
+
+Use this when the operator says "publish a patch / minor / major" or "ship a new version".
+
+## Preflight
+
+- This command only makes sense if `package.json` has a `version` field and the project is an npm package (not a private app).
+- Confirm `~/.npmrc` has an authToken or `npm whoami` succeeds. If neither, stop and tell the operator to run `npm login` or paste a Bypass-2FA token from `https://www.npmjs.com/settings/<username>/tokens/new`.
+- Working tree must be clean (`git status --porcelain` returns empty). If dirty, refuse and ask the operator to commit or stash first.
+
+## Steps
+
+### 1. Pick the version bump
+
+If the operator named a level (patch / minor / major), use it. Otherwise ask:
+
+| Level | When |
+|---|---|
+| patch | Bug fixes, no API change |
+| minor | New backwards-compatible features |
+| major | Breaking changes |
+
+### 2. Bump the version
+
+```bash
+npm version <patch|minor|major> --no-git-tag-version
+```
+
+This updates `package.json` only. We tag manually at the end so the commit message + tag stay in sync.
+
+### 3. Run tests
+
+```bash
+npm test
+```
+
+If tests fail, stop. Revert the version bump (`git checkout package.json package-lock.json`) and report to the operator.
+
+### 4. Publish
+
+```bash
+npm publish
+```
+
+If npm asks for an OTP and the bypass token is missing, fail clearly and tell the operator to set up a token first.
+
+### 5. Commit + tag + push
+
+```bash
+VERSION=$(node -p "require('./package.json').version")
+git add package.json package-lock.json
+git commit -m "chore: release v$VERSION"
+git tag "v$VERSION"
+git push
+git push origin "v$VERSION"
+```
+
+### 6. Verify
+
+```bash
+npm view <package-name> version
+```
+
+Expect the new version. If npm's CDN hasn't propagated yet, retry after 30s.
+
+## Report
+
+```
+Published <package-name>@<version>
+- npm:    https://www.npmjs.com/package/<package-name>
+- Tag:    v<version> pushed to origin
+- Verify: npm view <package-name> version
+```

package/templates/auth-clerk/env.example.additions

@@ -0,0 +1,10 @@
+# --- Clerk auth additions ---
+# Get keys at https://dashboard.clerk.com/apps (create an app, copy from API Keys)
+NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=
+CLERK_SECRET_KEY=
+
+# Optional: where Clerk redirects after sign-in / sign-up
+NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
+NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
+NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL=/dashboard
+NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL=/dashboard

package/templates/auth-clerk/layout.tsx

@@ -0,0 +1,25 @@
+import type { Metadata } from 'next';
+import { ClerkProvider } from '@clerk/nextjs';
+import './globals.css';
+
+export const metadata: Metadata = {
+  title: '{{DISPLAY_NAME}}',
+  description: '{{PROJECT_PURPOSE_ONE_SENTENCE}}',
+};
+
+// Build-safe: wrap with ClerkProvider only when the publishable key is set.
+// This lets `next build` succeed in CI / fresh scaffolds before the operator
+// has configured the env. In production the key is present and Clerk handles auth.
+const Wrapper = process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY
+  ? ClerkProvider
+  : ({ children }: { children: React.ReactNode }) => <>{children}</>;
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <Wrapper>
+      <html lang="en">
+        <body className="bg-white text-slate-900 antialiased">{children}</body>
+      </html>
+    </Wrapper>
+  );
+}

package/templates/auth-clerk/middleware.ts

@@ -0,0 +1,20 @@
+import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server';
+
+const isProtectedRoute = createRouteMatcher([
+  '/dashboard(.*)',
+  '/api/account(.*)',
+]);
+
+export default clerkMiddleware(async (auth, req) => {
+  if (isProtectedRoute(req)) {
+    await auth.protect();
+  }
+});
+
+export const config = {
+  matcher: [
+    // Run middleware on all non-static routes.
+    '/((?!_next/static|_next/image|favicon\\.ico).*)',
+    '/(api|trpc)(.*)',
+  ],
+};

package/templates/auth-clerk/package.json.additions

@@ -0,0 +1,5 @@
+{
+  "dependencies": {
+    "@clerk/nextjs": "^6.0.0"
+  }
+}

package/templates/auth-clerk/sign-in-page.tsx

@@ -0,0 +1,9 @@
+import { SignIn } from '@clerk/nextjs';
+
+export default function SignInPage() {
+  return (
+    <main className="flex min-h-screen items-center justify-center p-6">
+      <SignIn />
+    </main>
+  );
+}

package/templates/auth-clerk/sign-up-page.tsx

@@ -0,0 +1,9 @@
+import { SignUp } from '@clerk/nextjs';
+
+export default function SignUpPage() {
+  return (
+    <main className="flex min-h-screen items-center justify-center p-6">
+      <SignUp />
+    </main>
+  );
+}

package/templates/auth-google/auth.ts

@@ -0,0 +1,12 @@
+import NextAuth from 'next-auth';
+import Google from 'next-auth/providers/google';
+
+export const { handlers, signIn, signOut, auth } = NextAuth({
+  providers: [
+    Google({
+      clientId: process.env.GOOGLE_CLIENT_ID || '',
+      clientSecret: process.env.GOOGLE_CLIENT_SECRET || '',
+    }),
+  ],
+  trustHost: true,
+});

package/templates/auth-google/env.example.additions

@@ -0,0 +1,9 @@
+# --- Google OAuth (NextAuth v5) additions ---
+# Create an OAuth 2.0 Client ID at:
+#   https://console.cloud.google.com/apis/credentials/oauthclient
+# Authorized redirect URI: <your-prod-url>/api/auth/callback/google
+GOOGLE_CLIENT_ID=
+GOOGLE_CLIENT_SECRET=
+
+# NextAuth secret. Generate one with: openssl rand -base64 32
+AUTH_SECRET=

package/templates/auth-google/package.json.additions

@@ -0,0 +1,5 @@
+{
+  "dependencies": {
+    "next-auth": "^5.0.0-beta.20"
+  }
+}

package/templates/auth-google/route.ts

@@ -0,0 +1,2 @@
+import { handlers } from '@/auth';
+export const { GET, POST } = handlers;

package/templates/auth-google/sign-in-page.tsx

@@ -0,0 +1,32 @@
+import { signIn } from '@/auth';
+
+export default function SignInPage() {
+  return (
+    <main className="flex min-h-screen items-center justify-center p-6">
+      <div className="w-full max-w-sm rounded-lg border border-slate-200 bg-white p-8">
+        <h1 className="text-2xl font-semibold tracking-tight">Sign in</h1>
+        <p className="mt-2 text-sm text-slate-600">Continue to {`{{DISPLAY_NAME}}`}.</p>
+        <form
+          action={async () => {
+            'use server';
+            await signIn('google', { redirectTo: '/dashboard' });
+          }}
+          className="mt-8"
+        >
+          <button
+            type="submit"
+            className="flex w-full items-center justify-center gap-2 rounded-md border border-slate-300 bg-white px-4 py-2 font-medium text-slate-900 hover:bg-slate-50"
+          >
+            <svg className="h-5 w-5" viewBox="0 0 24 24" aria-hidden="true">
+              <path d="M22.56 12.25c0-.78-.07-1.53-.2-2.25H12v4.26h5.92c-.26 1.37-1.04 2.53-2.21 3.31v2.77h3.57c2.08-1.92 3.28-4.74 3.28-8.09Z" fill="#4285F4"/>
+              <path d="M12 23c2.97 0 5.46-.98 7.28-2.66l-3.57-2.77c-.99.66-2.23 1.06-3.71 1.06-2.86 0-5.29-1.93-6.16-4.53H2.18v2.84A11 11 0 0 0 12 23Z" fill="#34A853"/>
+              <path d="M5.84 14.1A6.6 6.6 0 0 1 5.5 12c0-.73.13-1.43.34-2.1V7.07H2.18A11 11 0 0 0 1 12c0 1.77.42 3.45 1.18 4.93l3.66-2.83Z" fill="#FBBC05"/>
+              <path d="M12 5.38c1.62 0 3.06.56 4.21 1.65l3.15-3.15C17.45 2.09 14.97 1 12 1A11 11 0 0 0 2.18 7.07l3.66 2.83C6.71 7.3 9.14 5.38 12 5.38Z" fill="#EA4335"/>
+            </svg>
+            Sign in with Google
+          </button>
+        </form>
+      </div>
+    </main>
+  );
+}

package/templates/auth-google/sign-up-page.tsx

@@ -0,0 +1,32 @@
+import { signIn } from '@/auth';
+
+export default function SignUpPage() {
+  return (
+    <main className="flex min-h-screen items-center justify-center p-6">
+      <div className="w-full max-w-sm rounded-lg border border-slate-200 bg-white p-8">
+        <h1 className="text-2xl font-semibold tracking-tight">Create account</h1>
+        <p className="mt-2 text-sm text-slate-600">Sign up with Google to get started.</p>
+        <form
+          action={async () => {
+            'use server';
+            await signIn('google', { redirectTo: '/dashboard' });
+          }}
+          className="mt-8"
+        >
+          <button
+            type="submit"
+            className="flex w-full items-center justify-center gap-2 rounded-md border border-slate-300 bg-white px-4 py-2 font-medium text-slate-900 hover:bg-slate-50"
+          >
+            <svg className="h-5 w-5" viewBox="0 0 24 24" aria-hidden="true">
+              <path d="M22.56 12.25c0-.78-.07-1.53-.2-2.25H12v4.26h5.92c-.26 1.37-1.04 2.53-2.21 3.31v2.77h3.57c2.08-1.92 3.28-4.74 3.28-8.09Z" fill="#4285F4"/>
+              <path d="M12 23c2.97 0 5.46-.98 7.28-2.66l-3.57-2.77c-.99.66-2.23 1.06-3.71 1.06-2.86 0-5.29-1.93-6.16-4.53H2.18v2.84A11 11 0 0 0 12 23Z" fill="#34A853"/>
+              <path d="M5.84 14.1A6.6 6.6 0 0 1 5.5 12c0-.73.13-1.43.34-2.1V7.07H2.18A11 11 0 0 0 1 12c0 1.77.42 3.45 1.18 4.93l3.66-2.83Z" fill="#FBBC05"/>
+              <path d="M12 5.38c1.62 0 3.06.56 4.21 1.65l3.15-3.15C17.45 2.09 14.97 1 12 1A11 11 0 0 0 2.18 7.07l3.66 2.83C6.71 7.3 9.14 5.38 12 5.38Z" fill="#EA4335"/>
+            </svg>
+            Continue with Google
+          </button>
+        </form>
+      </div>
+    </main>
+  );
+}

package/templates/private/middleware.ts

@@ -3,7 +3,14 @@ import type { NextRequest } from 'next/server';
 import { rateLimit } from '@/lib/rate-limit';
 import { audit } from '@/lib/audit';
 
-const SESSION_COOKIE_NAMES = ['better-auth.session_token', 'authjs.session-token', 'session_token'];
+const SESSION_COOKIE_NAMES = [
+  '__session',                       // Clerk
+  '__clerk_db_jwt',                  // Clerk db cookie
+  'authjs.session-token',            // NextAuth v5
+  '__Secure-authjs.session-token',   // NextAuth v5 secure
+  'better-auth.session_token',       // Better Auth
+  'session_token',                   // Generic fallback
+];
 
 function getIp(req: NextRequest): string {
   const xff = req.headers.get('x-forwarded-for');