@oaklandzoo/ostup 0.10.0 → 0.12.0

package/src/doctor-privacy.mjs

@@ -0,0 +1,103 @@
+// doctor-privacy.mjs: HTTP probes for ostup doctor --privacy.
+// Auto-detects deployed URL from .vercel/project.json; --url overrides.
+
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const PROBE_PATHS = [
+  '/api/health',
+  '/api/contact',
+  '/api/booking/request',
+  '/api/account/settings',
+  '/api/blob/test.jpg',
+  '/uploads/test.jpg',
+  '/_next/image?url=https%3A%2F%2Fexample.com%2Ftest.jpg&w=64&q=75',
+  '/dashboard',
+  '/dashboard/settings',
+];
+
+const AUDIT_HEALTH_PATH = '/api/audit/health';
+
+export async function detectDeployedUrl(cwd = process.cwd()) {
+  const projectJson = join(cwd, '.vercel', 'project.json');
+  if (!existsSync(projectJson)) return null;
+  try {
+    const raw = await readFile(projectJson, 'utf8');
+    const data = JSON.parse(raw);
+    if (data.productionDomain) {
+      const host = String(data.productionDomain).replace(/^https?:\/\//, '');
+      return `https://${host}`;
+    }
+    if (data.production_alias) {
+      const host = String(data.production_alias).replace(/^https?:\/\//, '');
+      return `https://${host}`;
+    }
+    if (data.projectId) {
+      return null; // We could shell out to `vercel inspect`, but skip in v1.
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+async function probeOne(baseUrl, path, fetchImpl = fetch) {
+  const url = `${baseUrl.replace(/\/+$/, '')}${path}`;
+  try {
+    const res = await fetchImpl(url, {
+      method: 'GET',
+      redirect: 'manual',
+      headers: { 'user-agent': 'ostup-doctor-privacy/1.0' },
+    });
+    return { url, status: res.status, ok: res.status === 401 || res.status === 404 || res.status === 403 || (res.status >= 300 && res.status < 400) };
+  } catch (err) {
+    return { url, status: 0, ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+async function probeAuditHealth(baseUrl, fetchImpl = fetch) {
+  const url = `${baseUrl.replace(/\/+$/, '')}${AUDIT_HEALTH_PATH}`;
+  try {
+    const res = await fetchImpl(url, { method: 'GET', headers: { 'user-agent': 'ostup-doctor-privacy/1.0' } });
+    if (!res.ok) return { url, status: res.status, ok: false };
+    const body = await res.json().catch(() => null);
+    return { url, status: res.status, ok: body?.ok === true, body };
+  } catch (err) {
+    return { url, status: 0, ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+export async function runPrivacyChecks({ url, cwd = process.cwd(), report, fetchImpl = fetch } = {}) {
+  let baseUrl = url;
+  if (!baseUrl) baseUrl = await detectDeployedUrl(cwd);
+  if (!baseUrl) {
+    report('fail', 'privacy url', 'could not resolve deployed URL. Pass --url <vercel-url> or run from a Vercel-linked project dir.');
+    return;
+  }
+  report('ok', 'privacy url', baseUrl);
+
+  for (const p of PROBE_PATHS) {
+    const result = await probeOne(baseUrl, p, fetchImpl);
+    if (result.error) {
+      report('warn', `probe ${p}`, `network error: ${result.error}`);
+      continue;
+    }
+    if (result.ok) {
+      report('ok', `probe ${p}`, `${result.status} (denied as expected)`);
+    } else {
+      report('fail', `probe ${p}`, `${result.status} (expected 401/403/404/redirect; got 2xx)`);
+    }
+  }
+
+  const audit = await probeAuditHealth(baseUrl, fetchImpl);
+  if (audit.error) {
+    report('warn', 'probe audit-health', `network error: ${audit.error}`);
+  } else if (audit.ok) {
+    report('ok', 'probe audit-health', `${audit.status} (audit pipeline wired)`);
+  } else {
+    report('fail', 'probe audit-health', `${audit.status} (audit pipeline NOT wired)`);
+  }
+}
+
+export { PROBE_PATHS, AUDIT_HEALTH_PATH };

package/src/doctor.mjs

@@ -25,7 +25,7 @@ function runCapture(cmd) {
   }
 }
 
-export async function runDoctor() {
+export async function runDoctor({ flags = {} } = {}) {
   const findings = [];
   let okCount = 0;
   let failCount = 0;
@@ -38,6 +38,12 @@ export async function runDoctor() {
     else warnCount++;
   }
 
+  if (flags.privacy) {
+    const { runPrivacyChecks } = await import('./doctor-privacy.mjs');
+    await runPrivacyChecks({ url: flags.url, report });
+    return { findings, okCount, warnCount, failCount };
+  }
+
   // === Tool detection (shared with bootstrap) ===
   const detection = detectAll();
   for (const f of detection.found) {

package/src/mvp-flow.mjs

@@ -134,6 +134,33 @@ 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;
+    const priv = await applyPrivate({ targetDir, profile });
+    process.stdout.write(
+      `[private] applied default-deny. ${priv.touched.length} file(s) touched. ` +
+        `rate-limit backend: ${priv.useKvRateLimit ? 'kv' : 'in-memory'}\n`,
+    );
+  }
+
   await exec('git-init',  'git', ['init'], { cwd: targetDir });
   await exec('git-branch','git', ['branch', '-M', 'main'], { cwd: targetDir });
   await exec('git-add',   'git', ['add', '.'], { cwd: targetDir });

package/src/private-cmd.mjs

@@ -0,0 +1,35 @@
+// private-cmd.mjs: ostup private add|remove|status subcommand.
+
+import { applyPrivate, removePrivate, statusPrivate, PrivateError } from './private.mjs';
+
+export async function runPrivate({ action = 'status', flags = {}, cwd = process.cwd() } = {}) {
+  if (action === 'add') {
+    const result = await applyPrivate({ targetDir: cwd, force: !!flags.force });
+    process.stdout.write(
+      `[private] applied. ${result.touched.length} file(s) touched. ` +
+        `rate-limit backend: ${result.useKvRateLimit ? 'kv' : 'in-memory'}\n`,
+    );
+    process.stdout.write(`[private] manifest: .ostup/private.json (run 'ostup private remove' to undo)\n`);
+    return;
+  }
+  if (action === 'remove') {
+    const result = await removePrivate({ targetDir: cwd, force: !!flags.force });
+    process.stdout.write(`[private] removed. ${result.restored.length} file(s) reverted.\n`);
+    return;
+  }
+  if (action === 'status') {
+    const result = await statusPrivate({ targetDir: cwd });
+    if (!result.applied) {
+      process.stdout.write(`[private] not applied. Run 'ostup private add' to enable.\n`);
+      return;
+    }
+    process.stdout.write(`[private] applied at ${result.manifest.appliedAt}\n`);
+    process.stdout.write(`[private] rate-limit backend: ${result.manifest.useKvRateLimit ? 'kv' : 'in-memory'}\n`);
+    process.stdout.write(`[private] files under management:\n`);
+    for (const op of result.manifest.ops) {
+      process.stdout.write(`  ${op.kind === 'created' ? '+' : '~'} ${op.path}\n`);
+    }
+    return;
+  }
+  throw new PrivateError('PRIVATE_UNKNOWN_ACTION', `unknown action '${action}'. Use: add | remove | status`);
+}

package/src/private.mjs

@@ -0,0 +1,215 @@
+// private.mjs: applyPrivate post-processor. Lays down default-deny middleware,
+// blob proxy, audit + rate-limit libs, locked next.config, CLAUDE.md Part 20.
+// Captures original content of patched files for clean rollback by `ostup private remove`.
+
+import { readFile, writeFile, mkdir, rm } from 'node:fs/promises';
+import { existsSync, readFileSync } 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 PRIVATE_TEMPLATES = resolve(PKG_ROOT, 'templates', 'private');
+
+const SAAS_CONFLICT_MSG =
+  '--private is not compatible with the saas-dashboard profile. ' +
+  'saas-dashboard already provides Better Auth + a session-checking middleware.ts. ' +
+  'Layering default-deny on top creates two competing matchers.\n\n' +
+  'Pick one:\n' +
+  '  - Use --private alone for a generic single-user-protected app\n' +
+  '  - Use --profile saas-dashboard alone for the SaaS shell';
+
+export const PRIVATE_MANIFEST_PATH = '.ostup/private.json';
+
+class PrivateError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+
+function detectSaas(targetDir, profile) {
+  if (profile === 'saas-dashboard') return true;
+  const pkgPath = join(targetDir, 'package.json');
+  if (!existsSync(pkgPath)) return false;
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+    return Boolean(deps['better-auth']);
+  } catch {
+    return false;
+  }
+}
+
+function plannedOperations(targetDir, useKvRateLimit) {
+  // Each op: { kind: 'create'|'patch', dest: <relative path>, src: <template relpath>|null, patcher?: fn }
+  const rateLimitSrc = useKvRateLimit ? 'lib-rate-limit-kv.ts' : 'lib-rate-limit-memory.ts';
+  return [
+    { kind: 'create', dest: 'middleware.ts', src: 'middleware.ts' },
+    { kind: 'create', dest: 'next.config.ts', src: 'next.config.ts' },
+    { kind: 'create', dest: 'app/api/blob/[...path]/route.ts', src: 'api-blob-proxy.ts' },
+    { kind: 'create', dest: 'app/api/audit/health/route.ts', src: 'api-audit-health.ts' },
+    { kind: 'create', dest: 'lib/audit.ts', src: 'lib-audit.ts' },
+    { kind: 'create', dest: 'lib/rate-limit.ts', src: rateLimitSrc },
+    { kind: 'patch', dest: 'CLAUDE.md', src: 'CLAUDE_PART_20.md', mode: 'append' },
+    { kind: 'patch', dest: 'app/layout.tsx', src: null, mode: 'layout-robots' },
+  ];
+}
+
+async function loadTemplate(rel) {
+  return readFile(join(PRIVATE_TEMPLATES, rel), 'utf8');
+}
+
+function patchLayoutRobots(body) {
+  // Inject `robots: { index: false, follow: false }` into the metadata export, if present.
+  // Idempotent: skip if already contains "robots:".
+  if (/robots\s*:/.test(body)) return body;
+  // Match: export const metadata: Metadata = {  ...  };
+  const re = /(export\s+const\s+metadata\s*:\s*Metadata\s*=\s*\{)([^}]*)(\})/;
+  if (!re.test(body)) return body;
+  return body.replace(re, (_full, open, inner, close) => {
+    const trimmed = inner.replace(/\s*$/, '');
+    const sep = trimmed.endsWith(',') ? '' : (trimmed.length > 0 ? ',' : '');
+    const insert = `${trimmed}${sep}\n  robots: { index: false, follow: false },\n`;
+    return `${open}${insert}${close}`;
+  });
+}
+
+function envMentions(targetDir, names) {
+  for (const file of ['.env', '.env.local', '.env.production', '.env.example']) {
+    const p = join(targetDir, file);
+    if (!existsSync(p)) continue;
+    try {
+      const body = readFileSync(p, 'utf8');
+      for (const n of names) {
+        if (new RegExp(`^${n}=`, 'm').test(body)) return true;
+      }
+    } catch {}
+  }
+  return false;
+}
+
+export async function applyPrivate({ targetDir, profile = null, force = false } = {}) {
+  if (detectSaas(targetDir, profile)) {
+    throw new PrivateError('PRIVATE_SAAS_CONFLICT', SAAS_CONFLICT_MSG);
+  }
+
+  const manifestPath = join(targetDir, PRIVATE_MANIFEST_PATH);
+  if (existsSync(manifestPath) && !force) {
+    throw new PrivateError(
+      'PRIVATE_ALREADY_APPLIED',
+      `${PRIVATE_MANIFEST_PATH} already exists. Run 'ostup private remove' first, or pass --force.`,
+    );
+  }
+
+  const useKv = envMentions(targetDir, ['KV_URL', 'KV_REST_API_URL']);
+  const ops = plannedOperations(targetDir, useKv);
+
+  const performed = [];
+
+  for (const op of ops) {
+    const destPath = join(targetDir, op.dest);
+
+    if (op.kind === 'create') {
+      if (existsSync(destPath) && !force) {
+        throw new PrivateError(
+          'PRIVATE_DIRTY',
+          `${op.dest} already exists; refusing to overwrite without --force.`,
+        );
+      }
+      const content = await loadTemplate(op.src);
+      await mkdir(dirname(destPath), { recursive: true });
+      await writeFile(destPath, content, 'utf8');
+      performed.push({ kind: 'created', path: op.dest });
+    } else if (op.kind === 'patch') {
+      if (!existsSync(destPath)) {
+        // Patching a missing file is a soft-skip (e.g. no app/layout.tsx exists).
+        continue;
+      }
+      const prior = await readFile(destPath, 'utf8');
+      let next;
+      if (op.mode === 'append') {
+        const addition = await loadTemplate(op.src);
+        if (prior.includes('# PART 20: PRIVACY DEFAULT-DENY')) {
+          continue;
+        }
+        next = prior + addition;
+      } else if (op.mode === 'layout-robots') {
+        next = patchLayoutRobots(prior);
+        if (next === prior) continue;
+      } else {
+        continue;
+      }
+      await writeFile(destPath, next, 'utf8');
+      performed.push({ kind: 'patched', path: op.dest, prior });
+    }
+  }
+
+  await mkdir(dirname(manifestPath), { recursive: true });
+  await writeFile(
+    manifestPath,
+    JSON.stringify(
+      {
+        appliedAt: new Date().toISOString(),
+        useKvRateLimit: useKv,
+        ops: performed,
+      },
+      null,
+      2,
+    ) + '\n',
+    'utf8',
+  );
+
+  return { applied: true, touched: performed.map((p) => p.path), useKvRateLimit: useKv };
+}
+
+export async function removePrivate({ targetDir, force = false } = {}) {
+  const manifestPath = join(targetDir, PRIVATE_MANIFEST_PATH);
+  if (!existsSync(manifestPath)) {
+    throw new PrivateError('PRIVATE_NOT_APPLIED', `${PRIVATE_MANIFEST_PATH} not found; nothing to remove.`);
+  }
+  const manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+  const restored = [];
+
+  // Walk in reverse so dependent files come back in the right order.
+  for (const op of [...manifest.ops].reverse()) {
+    const p = join(targetDir, op.path);
+    if (op.kind === 'created') {
+      if (existsSync(p)) {
+        await rm(p, { force: true });
+        restored.push({ kind: 'deleted', path: op.path });
+      }
+    } else if (op.kind === 'patched') {
+      if (!existsSync(p)) {
+        if (!force) {
+          throw new PrivateError(
+            'PRIVATE_DIRTY',
+            `${op.path} is gone; cannot restore. Re-add the file or pass --force to skip.`,
+          );
+        }
+        continue;
+      }
+      // Optional: integrity check against prior. Skipped in v1.
+      await writeFile(p, op.prior, 'utf8');
+      restored.push({ kind: 'restored', path: op.path });
+    }
+  }
+
+  await rm(manifestPath, { force: true });
+  // Best-effort: remove empty .ostup/ dir.
+  try {
+    await rm(join(targetDir, '.ostup'), { recursive: false });
+  } catch {}
+
+  return { restored: restored.map((r) => r.path) };
+}
+
+export async function statusPrivate({ targetDir } = {}) {
+  const manifestPath = join(targetDir, PRIVATE_MANIFEST_PATH);
+  if (!existsSync(manifestPath)) {
+    return { applied: false, manifest: null };
+  }
+  const manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+  return { applied: true, manifest };
+}
+
+export { PrivateError };

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/add-storage.md

@@ -62,7 +62,17 @@ Confirm `.env.local` got the new keys. Common ones:
 npm install @vercel/<type>
 ```
 
-Create `src/lib/<type>.ts` with typed helpers. Example for blob:
+### Privacy mode check (before writing blob helpers)
+
+Before writing `src/lib/blob.ts`, check whether this project is in privacy mode by looking for `.ostup/private.json` at the project root OR a `# PART 20: PRIVACY DEFAULT-DENY` section in `CLAUDE.md`. If either is present:
+
+- Default the helper to `access: 'private'` (not `'public'`).
+- Also scaffold `app/api/blob/[...path]/route.ts` as the auth-checked proxy if it does not already exist (the `--private` applier may have already created it). Do NOT serve blob URLs directly to the client.
+- Skip the `vercel blob create-store --access public` flag from Step 3. Re-create the store without `--access public` if it was already created public.
+
+### Blob helper template
+
+Default (no privacy mode):
 
 ```typescript
 // src/lib/blob.ts
@@ -81,6 +91,26 @@ export async function deleteFile(url: string) {
 }
 ```
 
+Privacy mode:
+
+```typescript
+// src/lib/blob.ts
+import { put, list, del } from '@vercel/blob';
+
+export async function uploadFile(path: string, body: Blob | ArrayBuffer | string) {
+  // access: 'private' is mandatory in privacy mode. Serve via /api/blob/[...path] proxy.
+  return put(path, body, { access: 'private' as 'private' });
+}
+
+export async function listFiles(prefix?: string) {
+  return list({ prefix });
+}
+
+export async function deleteFile(url: string) {
+  return del(url);
+}
+```
+
 Match the project's existing TypeScript conventions (named exports, no defaults, etc.).
 
 ## Step 6: update AGENTS.md

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"
+  }
+}