From 35022c106f868f1aa425a73f21f927b58f34c210 Mon Sep 17 00:00:00 2001 From: meglerhagen Date: Sun, 19 Apr 2026 11:11:56 +0200 Subject: [PATCH] chore: wire shadcn MCP + Tailark Pro registry, remove internal docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Dev-environment plumbing (no scaffold/template impact, no public-folder leak — verified: scripts/sync-templates.mjs generates template components.json from a hardcoded literal, doesn't copy from apps/web): - .mcp.json: add `shadcn` MCP server alongside supabase. Lets Claude Code use the shadcn registry tools when working in this repo. - apps/web/components.json: add @tailark-pro registry pointing at https://pro.tailark.com/registry/{name}, auth via TAILARK_API_KEY env var. Key lives in apps/web/.env.local (gitignored, not committed). Use: `pnpm dlx shadcn@latest add @tailark-pro/` from apps/web. Repo hygiene — remove 6 internal planning/handoff docs that don't belong in a public repo: - CLI_DX_PLAN.md, DEVICE_FLOW_PLAN.md, UNIFIED_SCAFFOLDER_PLAN.md (delivery plans, work already shipped) - TODOS.md (internal tracker), QA-REVIEWER.md (internal QA notes) - DESIGN.md (internal design source — single comment ref stripped) Two files in source pointed at removed docs via comments — those refs stripped (apps/web/emails/sign-in-magic-link.tsx, supabase-admin.ts). The actual mechanism the comment described still holds; only the link was load-bearing. Co-Authored-By: Claude Opus 4.7 (1M context) --- .mcp.json | 4 + CLI_DX_PLAN.md | 250 ------------- DESIGN.md | 117 ------ DEVICE_FLOW_PLAN.md | 489 ------------------------- QA-REVIEWER.md | 205 ----------- TODOS.md | 113 ------ UNIFIED_SCAFFOLDER_PLAN.md | 304 --------------- apps/web/components.json | 10 +- apps/web/emails/sign-in-magic-link.tsx | 3 +- apps/web/lib/supabase-admin.ts | 2 +- 10 files changed, 15 insertions(+), 1482 deletions(-) delete mode 100644 CLI_DX_PLAN.md delete mode 100644 DESIGN.md delete mode 100644 DEVICE_FLOW_PLAN.md delete mode 100644 QA-REVIEWER.md delete mode 100644 TODOS.md delete mode 100644 UNIFIED_SCAFFOLDER_PLAN.md diff --git a/.mcp.json b/.mcp.json index 55e6a1f..65eaf09 100644 --- a/.mcp.json +++ b/.mcp.json @@ -3,6 +3,10 @@ "supabase": { "type": "http", "url": "https://mcp.supabase.com/mcp?project_ref=rrlqttgjynfgxbhjkxnm" + }, + "shadcn": { + "command": "npx", + "args": ["shadcn@latest", "mcp"] } } } \ No newline at end of file diff --git a/CLI_DX_PLAN.md b/CLI_DX_PLAN.md deleted file mode 100644 index 2c1277b..0000000 --- a/CLI_DX_PLAN.md +++ /dev/null @@ -1,250 +0,0 @@ -# CLI DX Plan — Road to 10/10 - -Source: `/plan-devex-review` on 2026-04-12. Starting score: **5.1/10**. Target: **10/10**. - -Organized into 4 phases by leverage, not by pass. Ship Phase 1 before v0.1. -Each phase is independently landable. - ---- - -## Phase 1 — Unlock the hosted-tier story (~6 hrs) - -Without these, the hosted product has no CI path and no standalone auth. This -is the blocking phase for v0.1. - -### 1.1 Extract auth into standalone commands - -**Files:** -- New: `packages/cli/src/commands/login.ts` -- New: `packages/cli/src/commands/logout.ts` -- New: `packages/cli/src/commands/whoami.ts` -- Refactor: `packages/cli/src/commands/deploy.ts:24-101` — move the OTP flow into `lib/auth.ts`, have both `login` and `deploy` call it. -- Register in `packages/cli/src/index.ts`. - -**Acceptance:** -- `helpbase login` runs OTP flow, stores to `~/.helpbase/auth.json`. -- `helpbase logout` clears the file. -- `helpbase whoami` prints email + tenant slug, or "not logged in". -- `helpbase deploy` still does the inline login flow if not authed (no regression). - -### 1.2 `HELPBASE_TOKEN` for non-interactive deploy - -**Files:** -- `packages/cli/src/lib/supabase-client.ts` — `createAuthClient()` reads `HELPBASE_TOKEN` env var before falling back to `~/.helpbase/auth.json`. -- `packages/cli/src/commands/deploy.ts` — if `process.env.HELPBASE_TOKEN` set and `--yes` passed, skip all prompts; fail loudly if slug is missing. - -**Acceptance:** -- `HELPBASE_TOKEN=xxx helpbase deploy --slug foo --yes` completes without TTY. -- `helpbase login --print-token` prints a long-lived token to stdout for CI setup. - -### 1.3 `helpbase link` — project-to-tenant binding - -**Files:** -- New: `packages/cli/src/commands/link.ts` -- New: `packages/cli/src/lib/project-config.ts` — read/write `.helpbase/project.json` with `{ tenantId, slug }`. -- `deploy.ts:110` — prefer project config over `owner_id` lookup. - -**Acceptance:** -- Multi-product owners can deploy different dirs to different tenants. -- `.helpbase/project.json` is created on first deploy and committed. - -### 1.4 `helpbase open` — post-deploy dopamine - -**Files:** -- New: `packages/cli/src/commands/open.ts` — shells to `open`/`xdg-open`/`start` based on platform. -- `deploy.ts` — print `→ helpbase open` as a next step after success. - -**Acceptance:** `helpbase open` launches `https://.helpbase.dev` in the default browser. - ---- - -## Phase 2 — First-run magical moment (~2 hrs) - -The pieces exist but aren't wired into one forward-leaning flow. - -### 2.1 Post-scaffold next-steps card - -**Files:** -- `packages/create-helpbase/src/index.ts` (or wherever the scaffolder prints its final message) — after success, print: - ``` - ✓ Created my-help-center - - Next: - cd my-help-center && pnpm dev Preview locally - helpbase generate --url Import articles with AI - helpbase deploy Go live on helpbase.dev - - Docs: https://helpbase.dev/docs/cli - ``` - -### 2.2 Promote `deploy` in README - -**Files:** -- `README.md` Quick Start section — add a third step after `pnpm dev`: - ```bash - helpbase deploy # live at your-slug.helpbase.dev - ``` - -### 2.3 Pre-flight check in `dev` and `audit` - -**Files:** -- `packages/cli/src/commands/dev.ts` — before `execSync`, check that `package.json` exists and includes `next` in deps. If not, print "this doesn't look like a helpbase project. Run `npx create-helpbase` to scaffold one." -- `audit.ts` already handles this via `AuditError`; verify the message is consistent. - -### 2.4 Fix the `add` vs `new` collision - -**Files:** -- Rename current `new.ts` handler → fold into `add.ts`. `helpbase new` becomes the single entry point. -- `helpbase new` with no args → interactive (today's `add`). -- `helpbase new --type troubleshooting --title "Reset password"` → flag-driven (today's `new`). -- Ship 3 more templates in the `TEMPLATES` map: `getting-started`, `how-to`, `concept`. (AI-generate the bodies; 20 min.) -- Remove `add.ts` registration from `index.ts`. - -**Acceptance:** One command, two modes. Four real templates. README's "new" examples still work. - ---- - -## Phase 3 — Credibility & upgrade story (~4 hrs) - -You're v0.0.1. Get ready to ship breaking changes without burning users. - -### 3.1 CHANGELOG.md + release discipline - -**Files:** -- New: `CHANGELOG.md` at repo root, Keep-a-Changelog format, seed with v0.0.1 entry. -- `packages/cli/package.json` — add `"homepage"` and `"repository"` fields so npm links to GitHub. - -### 3.2 Update notifier - -**Files:** -- `packages/cli/package.json` — add `update-notifier` dep (~12KB). -- `packages/cli/src/index.ts` — wire it at top: - ```ts - import updateNotifier from "update-notifier" - import pkg from "../package.json" with { type: "json" } - updateNotifier({ pkg }).notify() - ``` - -**Acceptance:** Users on stale versions see a boxed "update available" message on every run. - -### 3.3 Error code convention + doc URLs - -**Files:** -- New: `packages/cli/src/lib/errors.ts` — `class HelpbaseError extends Error { code: string; docUrl: string }` and a `printError()` helper that always emits: problem, cause, fix, `→ see helpbase.dev/errors/`. -- Refactor every `cancel(...)` / `console.error(...)` call across `packages/cli/src/commands/*.ts` to use it. -- New: `apps/web/app/errors/[code]/page.tsx` — dynamic error page (stubs OK for now). -- Seed error codes: `E_NO_CONTENT_DIR`, `E_INVALID_FRONTMATTER`, `E_AUTH_FAILED`, `E_SLUG_TAKEN`, `E_MISSING_API_KEY`. - -**Acceptance:** Every CLI error prints a doc URL. Every doc URL resolves to something (even a stub). - -### 3.4 `schemaVersion` migration story - -**Files:** -- New: `docs/content-schema.md` — documents `schemaVersion: 1` contract, promises a codemod when v2 ships. -- `packages/shared/src/schemas.ts` — add a `migrate(frontmatter)` no-op stub for future versions. - ---- - -## Phase 4 — Polish, community, measurement (~6 hrs) - -Turn a 8/10 tool into a 10/10 tool. - -### 4.1 CLI reference docs - -**Files:** -- New: `scripts/generate-cli-docs.ts` — walks commander's `program.commands`, emits `docs/cli.md` with every command, flag, and example. -- Wire into `turbo.json` so `pnpm docs` regenerates it. -- New: `apps/web/content/docs/cli.mdx` — renders the generated reference. -- Add `.addHelpText('after', '...')` to every command with 2-3 worked examples. - -**Acceptance:** `helpbase --help` shows real examples. `helpbase.dev/docs/cli` is comprehensive. - -### 4.2 Scaffolded `HELPBASE.md` - -**Files:** -- `packages/create-helpbase/templates//HELPBASE.md` — drop in a ~40-line primer: where content lives, how `_category.json` works, frontmatter fields, `featured: true`, how to deploy. Written for the user, not us. - -### 4.3 Community surface - -**Files:** -- New: `CONTRIBUTING.md` — fork, clone, pnpm, smoke tests, conventional commits. -- New: `.github/ISSUE_TEMPLATE/bug_report.yml` + `feature_request.yml`. -- `README.md` — add a "Community" section with GitHub Discussions link (create the Discussions first). -- New: `packages/cli/src/commands/feedback.ts` — opens a prefilled GitHub issue URL in the browser with CLI version + OS auto-filled. - -### 4.4 Opt-in anonymous telemetry - -**Files:** -- New: `packages/cli/src/lib/telemetry.ts` — on first run, prompt once: "Share anonymous usage data to help us improve? (y/N)". Store choice in `~/.helpbase/config.json`. -- What to send: command name, duration, exit status, flags used (names only, no values), CLI version, OS/node version. **Never** content, URLs, emails, slugs. -- Endpoint: `apps/web/app/api/telemetry/route.ts` — rate-limited insert into Supabase. -- `helpbase config set telemetry off` to disable. - -**Acceptance:** After one week of telemetry, you can answer: what's the real TTHW, which command fails most, what % of users reach `deploy`. - -### 4.5 Published GitHub Action - -**Files:** -- New repo: `Codehagen/helpbase-deploy-action` -- `action.yml` with inputs `content-dir`, `slug`, `token`. Runs `npx helpbase deploy --yes`. -- Add usage example to `README.md` and `docs/cli.md`. - -### 4.6 `helpbase doctor` - -**Files:** -- New: `packages/cli/src/commands/doctor.ts` — prints: CLI version, node version, platform, auth state (without leaking token), detected tenant, whether `content/` exists, whether `next` is installed, last 3 runs from a rolling log. - ---- - -## Landed ahead of schedule - -### Dev/QA auth harness (supports all phases) - -**Files:** -- `packages/cli/scripts/mint-test-token.mjs` — uses `SUPABASE_SERVICE_ROLE_KEY` to create/confirm a test user and mint a real session JWT without sending email. -- `packages/cli/test/auth.integration.test.ts` — gated on the env var; skipped cleanly when absent. -- `pnpm mint:token` script alias. - -**Use:** -```bash -export SUPABASE_SERVICE_ROLE_KEY= -export HELPBASE_TOKEN=$(pnpm --filter helpbase mint:token) -node packages/cli/dist/index.js whoami -``` - -Unlocks end-to-end validation of the `HELPBASE_TOKEN` path without the OTP round-trip. - ---- - -## Deferred (explicit non-goals for v0.1) - -- **VS Code extension / MDX LSP** — defer to v0.2+. Frontmatter autocomplete would be nice; not load-bearing. -- **Template registry (`helpbase new --from @community/stripe`)** — plant the naming convention in Phase 2.4 but don't build the registry. -- **`helpbase audit` historical trend** — defer until telemetry (4.4) gives us the baseline. -- **Windows-specific smoke tests** — spot-check manually; full matrix later. - ---- - -## Effort & sequencing - -| Phase | Est | Unlocks | -|---|---|---| -| 1 — Hosted-tier unlock | 6 hrs | CI deploy, multi-product, standalone auth | -| 2 — Magical moment | 2 hrs | First-run story, no more command collision | -| 3 — Credibility | 4 hrs | Safe to ship v0.1 breaking changes | -| 4 — Polish & measurement | 6 hrs | 10/10 — data-driven from here on | - -**Total: ~18 hrs to 10/10.** Phase 1 alone takes the overall score from 5.1 → ~7.2. Phase 1+2 → ~8.0. Phase 1+2+3 → ~9.0. All four → 10. - -## Predicted scorecard after full plan - -``` -1. Getting Started 10/10 (next-steps card, pre-flight checks, deploy promoted) -2. CLI Design 10/10 (login/logout/whoami/link/open, real templates, --json everywhere) -3. Error Messages 10/10 (error codes, doc URLs, systematic) -4. Documentation 10/10 (CLI reference, inline --help examples, HELPBASE.md) -5. Upgrade Path 9/10 (changelog, notifier, schema policy — 10 needs a real migration shipped) -6. Dev Environment 10/10 (HELPBASE_TOKEN, CI mode, GitHub Action) -7. Community 9/10 (CONTRIBUTING, templates, feedback cmd — 10 needs active community) -8. Measurement 10/10 (opt-in telemetry feeding a live TTHW number) -``` diff --git a/DESIGN.md b/DESIGN.md deleted file mode 100644 index b0ed224..0000000 --- a/DESIGN.md +++ /dev/null @@ -1,117 +0,0 @@ -# Design System — helpbase - -> Reference doc. Describes what the product looks like today so future edits -> don't accidentally remodel it. Keep updates incremental and scoped. - -## Product context - -- **What:** Open-source help center with AI content generation. Guides, CLI reference, component docs. -- **Who:** Developers evaluating helpbase for their product's help center. -- **3x leverage:** `apps/web` is simultaneously the helpbase.dev site, the product demo, and the scaffold customers install via `npx create-helpbase` / `shadcn add`. Design changes here ship to every customer. Always run `pnpm sync:templates` after UI changes, and verify with `pnpm smoke:install` + `pnpm smoke:registry`. - -## Stack - -- Next.js 16 (App Router, Turbopack), React 19 -- Tailwind v4 (`@tailwindcss/postcss`) with shadcn/ui primitives -- Geist Sans (body/UI) + Geist Mono (code) via `next/font/google` -- MDX via `next-mdx-remote/rsc` for article content -- `next-themes` for light/dark toggle - -## Aesthetic - -Clean, cool-neutral, developer-tool docs aesthetic. Minimal decoration. Strong typographic hierarchy. Pragmatic — nothing decorative earns its pixels. - -## Color (from `packages/ui/src/styles/globals.css`) - -Uses shadcn's default cool-neutral palette in oklch. The full token set is in `globals.css` — don't reinvent it. Key semantic tokens: - -- `--background` / `--foreground` — page background + primary text -- `--muted` / `--muted-foreground` — surface fills, secondary text -- `--border` — hairline dividers, card outlines -- `--primary` — near-black in light mode; used for primary buttons and strong emphasis -- `--sidebar-*` — dedicated tokens for sidebar nav surfaces -- `.dark { ... }` — full dark-mode override - -**Rule:** Always reference tokens (`bg-background`, `text-muted-foreground`, `border-border`). Never hardcode hex or oklch in components. If a color is missing, add it to `globals.css` first. - -## Typography - -- **Body + UI:** Geist Sans (`--font-sans`, loaded in `app/layout.tsx`) -- **Code + mono:** Geist Mono (`--font-mono`) -- **Headings:** Geist Sans at heavier weights (600–700) with negative letter-spacing - -Article body styling lives in `.article-content` at the bottom of `globals.css`. Scale is handled inline in page components with standard Tailwind size utilities (`text-sm`, `text-4xl`, etc.). - -## Layout - -### Home page (`apps/web/app/(main)/page.tsx`) - -- **Hero** — centered, bordered, with a subtle grid pattern + radial gradient background. h1 is "helpbase docs" (4xl→5xl). Supporting paragraph in muted. Search trigger below (``), max-w-md. -- **Categories** — section heading "Browse by category", 1/2/3-col responsive grid of cards. Each card has an icon in a `bg-muted` square (inverts to `bg-foreground` on hover), title, description, article count, and a chevron that slides on hover. -- **Popular articles** (only if `featured.length > 0`) — 1/2/3-col responsive list of article links with a small icon + title + 2-line description clamp. -- **Max content width:** `max-w-6xl` throughout. - -### Docs pages (`apps/web/app/(main)/(docs)/`) - -- **Layout** — flush-left sidebar (`DocsSidebar`, 240px, sticky) + article body. No TOC rail by default; the TOC component is in `components/toc.tsx` and is used per-article where needed. Content column capped at `xl:max-w-4xl`. -- **Category page** — breadcrumb, h1 with category title, description, then a vertical stack of article cards (rounded hover state, icon + title + one-line description + chevron). -- **Article page** — breadcrumb, `
` element, `.article-content` styled MDX body, Edit-on-GitHub link, prev/next navigation at the bottom. -- **Sidebar active state** — `bg-muted` background + small `bg-foreground` dot marker. - -### Header (`apps/web/components/header.tsx`) - -- Sticky top bar with `backdrop-blur-lg` and `bg-background/80` -- Left: "helpbase" wordmark (plain, no icon) -- Center: `` (button that dispatches ⌘K) -- Right: theme toggle, GitHub icon link -- `max-w-6xl` container - -## Search - -- `` rendered once in `app/(main)/layout.tsx` with `items` prop from `getSearchIndex()` -- ⌘K or click on any `` opens the modal -- Arrow keys navigate, Enter routes, Esc closes -- Hand-rolled (not cmdk) in `components/search-dialog.tsx` — keep it that way unless there's a specific reason to swap - -## Motion - -All animation tokens and keyframes live in `globals.css`. Respected by `prefers-reduced-motion`. - -- `animate-fade-in` / `animate-fade-in-delay-1` / `animate-fade-in-delay-2` — staggered entrance on hero elements -- `animate-scale-fade-in` — search dialog entrance -- `toc-indicator` — sliding active indicator on the TOC (GPU-accelerated transform) -- Easing tokens: `--ease-out-quad`, `--ease-out-cubic`, `--ease-out-quart`, `--ease-in-out-quad` (Emil Kowalski's set) - -Reduced-motion handler disables all entrance animations and clamps all transitions/animations to ~0ms. - -## Voice & Copy - -- Direct, utilitarian dev-tool voice. No marketing-speak. -- Hero copy: "helpbase docs" + "Open-source help center with AI content generation. Guides, CLI reference, and component docs." -- Section headings: descriptive ("Browse by category", "Popular articles"), not salesy. - -## What NOT to change without discussion - -- Color palette — stays cool-neutral shadcn-default. We previously tried a terracotta-on-warm-paper editorial direction (see `design/new-abandoned` branch) and reverted after A/B feedback. -- Display typography — stays Geist Sans. No serif display in headings. -- Hero composition — stays centered with the grid + radial gradient backdrop. -- 3-col category card grid — intentional. Not "AI-slop" in this product's context — it matches developer-tool docs conventions (Stripe, Vercel docs all use card grids for category navigation). -- Flush-left sidebar with `max-w-7xl` content cap was removed in commit 71060c8; sidebar is flush to viewport. - -## Distribution - -Whenever you change `apps/web` UI, run: - -```bash -pnpm sync:templates # propagate to scaffolder + registry -pnpm --filter web test # unit tests -pnpm smoke:install # verify `npx create-helpbase` still works -pnpm smoke:registry # verify `shadcn add` still works -``` - -All four should pass before landing. CI enforces a `git diff --exit-code` after sync, so out-of-sync commits fail. - -## History - -- **2026-04-14:** Attempted full editorial-technical rebuild (terracotta accent, Instrument Serif hero, warm off-white paper palette). Reverted after qualitative A/B — the original cool-neutral dev-tool aesthetic tested better with target users. Rebuild preserved on `design/new-abandoned` branch in case we revisit individual pieces. -- **2026-04-13:** Sidebar moved flush-left (commit 71060c8). Content width capped per-route. diff --git a/DEVICE_FLOW_PLAN.md b/DEVICE_FLOW_PLAN.md deleted file mode 100644 index 8a09c06..0000000 --- a/DEVICE_FLOW_PLAN.md +++ /dev/null @@ -1,489 +0,0 @@ -# Device-flow login — migrate auth to Better Auth, then wire `helpbase login` to the device-authorization plugin - -Source: 2026-04-17 dogfood of `helpbase@0.4.1` (URL-paste fallback) revealed three context switches on every login. Captured as **TODO-020**. Initial plan drafted a custom device-flow on top of Supabase. `/plan-eng-review` + context7 research (`/websites/better-auth`) found that Better Auth ships first-class `deviceAuthorization` and `bearer` plugins that implement RFC 8628 natively, and ships an official Supabase migration script. The auth-provider seam at `packages/cli/src/lib/auth.ts:11–16` already anticipates this migration with the comment *"When helpbase migrates to Better Auth, only this file needs to change."* - -Decision (2026-04-17): migrate first, ship device flow second. Two PRs. **Email transport switches to Resend** as part of PR 1 (eliminates the Supabase-email-template fragility that started this thread). User base is n=1 (the founder), so migration cost is at its lifetime minimum. - ---- - -## Problem - -`helpbase login` today: -1. CLI prompts for email. -2. Supabase sends a magic-link email (URL only — Supabase's default template has no 6-digit code). -3. User leaves the terminal, opens email, copies URL. -4. Pastes URL back in terminal. -5. CLI parses `access_token` / `refresh_token` out of the URL fragment, writes `~/.helpbase/auth.json`. - -Three context switches. Fragile on email clients that rewrite `#fragment`. New users' first-touch surface is this friction. The scaffolder (`create-helpbase@0.3.1`) now runs `helpbase login` inline, so the friction is in `create-helpbase`'s TTHW path too. - -The proper fix is a `gh auth login --web` / `claude login` / `supabase login` style browser-bounce flow. Which is exactly what Better Auth's `deviceAuthorization` plugin implements. - -## Strategy — two PRs - -**PR 1: Migrate auth from Supabase to Better Auth.** No new features. The existing magic-link-URL-paste CLI login UX is preserved — just powered by Better Auth's `magicLink` plugin (with Resend as the email transport) instead of Supabase's `signInWithOtp`. Validate end-to-end, then merge + deploy. - -**PR 2: Add the `deviceAuthorization` server plugin + swap the CLI to `deviceAuthorizationClient`.** Strictly additive on top of PR 1. ~60 lines of CLI code, plugin owns the device-code / user-code / expiry / atomic-consume state machine. - -Staging is the deliberate risk control. A broken migration doesn't block the device-flow feature. A broken device-flow doesn't require rolling back the migration. Each PR is reviewable in <1 hour. - -## Goal - -End state after both PRs: - -- `helpbase login` default: opens the browser, user signs in (or is already signed in on helpbase.dev), clicks Authorize (with user-code shown for phishing defense), terminal picks up the bearer token, writes `~/.helpbase/auth.json`. Under 10 seconds on the fast path. -- `helpbase login --email` still works as the CI / sandboxed-env fallback, now powered by Better Auth magic-link. -- `apps/web` runs on Better Auth. Supabase's `auth.users` table is no longer authoritative; Better Auth's `user` / `session` / `account` tables are. Supabase-as-database stays (for tenant content, `llm_usage_events`, `global_daily_tokens`, etc.) — only the auth layer moves. -- Email transport is Resend. Zero dependency on Supabase email template config. -- Existing `HELPBASE_TOKEN` env shape preserved (opaque bearer token). - ---- - -## What already exists (reconciled with current code) - -- `packages/cli/src/lib/auth.ts` — `AuthSession`, `getCurrentSession`, `storeSession`, `loadStoredSession`, `clearStoredSession`, `isNonInteractive`. Provider-agnostic surface by design. The `client.auth.setSession` calls get replaced with `authClient.getSession({ headers: { Authorization: ... } })`. -- `packages/cli/src/lib/supabase-client.ts` — deleted in PR 1. Replaced by a thin `better-auth/client` factory in a new `packages/cli/src/lib/auth-client.ts`. -- `apps/web/lib/supabase-admin.ts:36` — `verifyBearerToken(token)`. Replaced by `auth.api.getSession({ headers })` (Better Auth bearer plugin pattern). One-line swap in every call site. -- `apps/web/lib/supabase.ts` — stays. Still used for tenant content + LLM usage counters. Not auth. -- `apps/web/app/api/v1/llm/_shared.ts:36` — `withAuthAndQuota`. Swap the token verification line. Rest of the function (quota, limits, wire error envelope) is unchanged. -- `apps/web/lib/rate-limit.ts:43` — unchanged. Still the per-IP / per-tenant pattern. Prior learning `rate-limit-fire-and-forget-write` still applies. -- `packages/create-helpbase/src/index.ts:794` — `openBrowser` helper. In PR 2 we reuse `open` from npm (Better Auth's docs use it) and delete the inline platform-branch helper. Or keep ours and skip the `open` dep. TBD in PR 2. -- Existing Supabase DB tables: `llm_usage_events`, `global_daily_tokens`, `tenants`, `tenant_articles`. These reference `auth.users.id`. We preserve user IDs during migration, so FKs keep working. - ---- - -## PR 1 — Supabase auth → Better Auth + Resend - -### 1.1 Install + configure Better Auth on `apps/web` - -**Files:** -- New: `apps/web/lib/auth.ts` — `betterAuth()` config. Postgres pool pointing at the same Supabase DB (standard Better Auth + Supabase-as-database pattern). Plugins: `magicLink`, `bearer`. -- New: `apps/web/lib/auth-client.ts` — server-side `authClient` for route handlers if needed. -- New: `apps/web/app/api/auth/[...all]/route.ts` — Better Auth's catch-all route handler (per Better Auth Next.js docs). -- Modify: `apps/web/package.json` — add `better-auth`, `resend`, `@auth/better-auth-cli` (for schema generation). - -```ts -// apps/web/lib/auth.ts -import { betterAuth } from "better-auth" -import { magicLink, bearer } from "better-auth/plugins" -import { Pool } from "pg" -import { Resend } from "resend" - -const resend = new Resend(process.env.RESEND_API_KEY!) - -export const auth = betterAuth({ - database: new Pool({ connectionString: process.env.DATABASE_URL! }), - plugins: [ - bearer(), - magicLink({ - sendMagicLink: async ({ email, url }) => { - await resend.emails.send({ - from: "helpbase ", - to: email, - subject: "Sign in to helpbase", - text: `Click to sign in: ${url}\n\nThis link expires in 10 minutes.`, - }) - }, - }), - ], - trustedOrigins: ["https://helpbase.dev", "http://localhost:3000"], -}) -``` - -**Env additions (Vercel + local):** -- `DATABASE_URL` — Postgres connection string for the Supabase DB. Pooler URL from Supabase project settings. Already available, just needs to be added to Vercel env. -- `RESEND_API_KEY` — new. -- `BETTER_AUTH_SECRET` — random 32-byte base64, for session signing. -- `BETTER_AUTH_URL` — `https://helpbase.dev` in prod, `http://localhost:3000` in dev. - -`NEXT_PUBLIC_SUPABASE_URL` / `NEXT_PUBLIC_SUPABASE_ANON_KEY` stay — still used for tenant content + LLM usage tables. `SUPABASE_SERVICE_ROLE_KEY` stays for the same reason. - -### 1.2 Schema — Better Auth tables alongside Supabase tables - -Better Auth owns its own `user`, `session`, `account`, `verification` tables in the public schema. These live **alongside** Supabase's `auth.users`. During migration we copy `auth.users` → `public.user` preserving IDs. Post-migration, Supabase's `auth.users` is no longer written to; `public.user` is authoritative. - -**Files:** -- New: `apps/web/drizzle/schema.ts` — Better Auth-generated schema (via `npx @better-auth/cli generate`). -- New: `apps/web/drizzle/migrations/0001_init_better_auth.sql` — generated migration. -- Modify: `apps/web/package.json` — add `drizzle-orm` + `drizzle-kit` (Better Auth's recommended schema tool). Or use plain SQL migrations if we prefer to keep the dep list lean. - -**FK reconciliation:** -- `llm_usage_events.user_id` references `auth.users(id)` today. After migration, point the FK at `public.user(id)` via `ALTER TABLE llm_usage_events DROP CONSTRAINT ... ADD CONSTRAINT ... REFERENCES public.user(id);`. IDs are preserved so no row breaks. -- `tenants.user_id` (if any) — same treatment. -- Run as part of the migration SQL; keep idempotent with `IF EXISTS` guards. - -### 1.3 Migration script - -Adapt Better Auth's official Supabase migration guide (`https://better-auth.com/docs/guides/supabase-migration-guide`): - -**Files:** -- New: `scripts/migrate-to-better-auth.mjs` — batch reader over `auth.users`, maps each row to Better Auth's `user` + `account` shape, inserts via the Better Auth internal adapter (or raw INSERTs — both are documented paths). Batch size 5000, cursor-based resume via `lastProcessedId`. -- Preserves: `id` (critical for FK), `email`, `emailVerified` (from `email_confirmed_at`), `name` (from `raw_user_meta_data.full_name` or email prefix), `createdAt`, `updatedAt`. -- One-shot run against prod — user base is n=1 so this is a single-row migration in practice. Test data preserved in case we get test users between now and ship. -- Idempotent via `ON CONFLICT (id) DO NOTHING`. - -**Acceptance:** -- `SELECT count(*) FROM auth.users` = `SELECT count(*) FROM public."user"` after migration. -- `select email from public.user where email = 'christer.hagen@gmail.com'` returns one row. -- Post-migration, `SELECT id FROM llm_usage_events` + `SELECT id FROM public.user` join cleanly (FK works). - -### 1.4 Rewire `/api/v1/llm/*` auth - -**Files:** -- Modify: `apps/web/app/api/v1/llm/_shared.ts` — replace `verifyBearerToken(token)` call with `auth.api.getSession({ headers: req.headers })`. The function already expects a session-shaped return; adapt the return type. -- Delete: `apps/web/lib/supabase-admin.ts:36` — `verifyBearerToken`. Replaced. -- Keep: `apps/web/lib/supabase-admin.ts:15` — `getServiceRoleClient`. Still needed for `llm_usage_events` insert + `global_daily_tokens` RPC. - -**Contract preserved:** -- CLI sends `Authorization: Bearer `. That still works — `bearer()` plugin intercepts it. -- `userId` / `email` returned from session verification stays the same shape. The rest of `withAuthAndQuota` (quota math, limits, wire error envelope) doesn't change. - -### 1.5 CLI rewire (preserves 0.4.1 UX) - -**Files:** -- New: `packages/cli/src/lib/auth-client.ts` — creates `authClient` via `createAuthClient({ baseURL: "https://helpbase.dev", plugins: [bearerClient()] })`. Replaces `getAnonSupabase`. -- Modify: `packages/cli/src/lib/auth.ts` — replace the five Supabase calls: - - `sendLoginCode(email)` → `authClient.signIn.magicLink({ email, callbackURL: "/login/cli/success" })`. - - `verifyLoginFromMagicLink(url)` → parse the same token params out of the URL fragment (Better Auth's magic-link callback writes compatible params) OR call `authClient.magicLink.verify({ token })` if the URL carries a `token` query param (check Better Auth's magic-link output format during implementation). - - `verifyLoginCode(email, code)` → Better Auth's magic-link is URL-only by default; if we want a 6-digit code, there's `otp()` plugin. PR 1 just mirrors today's URL-paste path; `verifyLoginCode` becomes a stub that throws "unsupported — paste the URL from the email". - - `resolveTokenSession(token)` → `authClient.getSession({ fetchOptions: { headers: { Authorization: \`Bearer ${token}\` } } })`. - - `getCurrentSession` refresh path → Better Auth handles refresh server-side; CLI just re-calls `getSession` and persists the response. -- Delete: `packages/cli/src/lib/supabase-client.ts`. No longer needed. -- Modify: `packages/cli/package.json` — remove `@supabase/supabase-js`, add `better-auth`. - -**What the user sees on PR 1:** -- `helpbase login` — same as today. Email prompt → email arrives from `login@helpbase.dev` (Resend, not Supabase) → user pastes URL → "Logged in as christer.hagen@gmail.com". Zero UX delta. Email template is now our own HTML (one `sendMagicLink` function to edit). - -### 1.6 Dev + CI - -**Files:** -- Modify: `apps/web/.env.example` — document new env vars. -- Modify: `README.md` — document Better Auth env setup in the "Local development" section. -- Modify: `scripts/smoke-install.sh` — add an auth smoke that hits `/api/auth/session` on the scaffolded app. -- Modify: `.github/workflows/ci.yml` — add `BETTER_AUTH_SECRET` + `RESEND_API_KEY` (mocked in CI) to the test matrix. - -### 1.7 Ship - -- Merge to `main` → Vercel auto-deploys (`vercel_auto_deploy` memory). -- Dogfood: `rm -f ~/.helpbase/auth.json && helpbase login` end-to-end. Email from Resend lands, URL pastes, CLI writes token, `/api/v1/llm` accepts it. -- **Do not delete** Supabase's `auth.users` table post-migration — leave it as a read-only backup for 30 days. Cleanup is a follow-up TODO. - -### 1.8 PR 1 success criteria - -- `helpbase login` works end-to-end via Better Auth + Resend. UX identical to 0.4.1. -- `curl -H "Authorization: Bearer $(jq -r .access_token ~/.helpbase/auth.json)" https://helpbase.dev/api/v1/usage/today` returns the quota snapshot. -- Fresh user: `helpbase login` with a new email → Better Auth creates a `public.user` row, `auth.users` stays untouched. -- Existing code path: `pnpm dlx create-helpbase@latest foo` → pick "A code repository" → pick "Log in" → same user-visible flow as before. -- `pnpm -F web test && pnpm -F helpbase test` green. - ---- - -## PR 2 — Device authorization plugin + OAuth providers + CLI `authClient.device.*` - -Strictly additive. Requires PR 1 to be merged + deployed. - -**DX review (2026-04-17) raised the bar on PR 2.** Three additions folded in: -1. **OAuth providers (Google + GitHub)** to drop cold-path TTHW from ~60s (magic-link round-trip) to ~15s (one-click sign-in). Eliminates the email round-trip entirely for the 100% of first-time scaffolder users who aren't yet cookied on helpbase.dev. -2. **Tier-3 error catalog** — 6 structured error codes with matching `/errors/[code]` pages and telemetry drop-off logging. Mirrors the pattern shipped for `helpbase sync` + `helpbase context`. -3. **Progressive polling hints** — CLI surfaces contextual help at T+30s, T+90s, T+4min while waiting on browser approval, so the YC-founder persona never hits the 3-minute silent-spinner abandonment zone. - -### 2.1 Add `deviceAuthorization` server plugin - -**Files:** -- Modify: `apps/web/lib/auth.ts` — append `deviceAuthorization()` to the plugins array. -- Generated: `apps/web/drizzle/migrations/0002_device_authorization.sql` — Better Auth writes the `deviceCode` table migration automatically via `npx @better-auth/cli generate`. - -Plugin config: -```ts -deviceAuthorization({ - expiresIn: "5m", - interval: "2s", - // The browser-facing page path that the user visits. - // Better Auth mounts its own /device endpoint; we customize the UI via our route. - verificationUri: "/device", -}) -``` - -### 2.1b OAuth providers (Google + GitHub) - -**Files:** -- Modify: `apps/web/lib/auth.ts` — add `socialProviders: { google: {...}, github: {...} }` to the `betterAuth()` config. -- Modify: `apps/web/.env.example` — document `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`. -- Modify: `apps/web/app/device/AuthorizeDeviceClient.tsx` — when user is signed-out, show three buttons: "Continue with Google", "Continue with GitHub", "Sign in with email" (collapses the magic-link form to secondary). - -**Pre-merge operator work (documented in plan, not in code):** -- Create a Google OAuth 2.0 Client in the Google Cloud console. Authorized redirect URI: `https://helpbase.dev/api/auth/callback/google` + local dev. Verified domain requirements noted in Better Auth docs. -- Create a GitHub OAuth App at github.com/settings/developers. Callback URL: `https://helpbase.dev/api/auth/callback/github` + local dev. -- Add the four env vars to Vercel prod + the local `.env.local`. - -**trustedOrigins dynamic construction:** -```ts -trustedOrigins: [ - "https://helpbase.dev", - "http://localhost:3000", - process.env.VERCEL_URL ? `https://${process.env.VERCEL_URL}` : null, -].filter(Boolean), -``` -So preview deploys can authenticate. - -**What the cold-path user sees:** -1. `helpbase login` → browser opens at `/device?user_code=ABCD-EFGH`. -2. Not signed in → three buttons. -3. Click "Continue with Google" → Google consent screen (if not already consented) → redirect back to `/device?user_code=ABCD-EFGH` signed-in → Authorize card → click → done. -4. Cold-path TTHW: ~15s. Matches `gh auth login --web`. - -**Email fallback preserved.** If the user prefers magic-link (corporate SSO restriction, privacy preference), the third button works unchanged. - -### 2.2 Browser-facing page - -**Files:** -- New: `apps/web/app/device/page.tsx` — server component. If the user is not signed in (no Better Auth session cookie), show inline magic-link sign-in (same `` component PR 1 built for the standalone `/login` page). If signed in, show ``. -- New: `apps/web/app/device/AuthorizeDeviceClient.tsx` — client component. Reads `user_code` from `?user_code=` (pattern from the plugin). Displays: - - "You're signing the helpbase CLI in. Code: **ABCD-EFGH**" - - "Signed in as ``." - - Buttons: "Authorize" / "Cancel". - - On Authorize: `authClient.device.approve({ userCode })`. On Cancel: `authClient.device.deny({ userCode })`. - - On success: "Done. Return to your terminal." Auto-close tab after 2s. - -**Phishing defense comes for free:** the user-code shown on the page matches what the CLI printed in the terminal. User compares; if they don't match, this is a phishing URL. - -### 2.3 CLI device-flow - -**Files:** -- Modify: `packages/cli/src/commands/login.ts` — port the device-flow state machine from Better Auth's docs, but **do NOT copy the `console.log` + emoji output verbatim**. Reshape through our existing UI helpers (`intro`, `note`, `spinner`, `pc.cyan`) so the output matches the voice of `helpbase new` / `helpbase context`. -- Modify: `packages/cli/src/lib/auth-client.ts` — add `deviceAuthorizationClient()` to the plugin list. -- Add `--email` option on `login` command that preserves the PR 1 magic-link-URL-paste flow (escape hatch for CI / sandboxed envs). -- New util: `packages/cli/src/lib/open-browser.ts` — extract the existing platform-branched helper from `create-helpbase/src/index.ts:794–809` (DRY). Avoid adding the `open` npm dep (~150KB) — we already have a working 15-line helper that handles `darwin`/`win32`/`linux`. -- Respect `HELPBASE_LOGIN_NO_BROWSER=1` env: skip auto-open, print URL + user-code for manual entry. -- **Auto-detect browser-less environments** and set the same behavior. Check `process.env.CODESPACES === "true"`, `process.env.SSH_TTY`, `process.env.SSH_CONNECTION`. When detected, print a one-line "Detected remote session — skipping auto-open" and fall through to the URL-print path. - -**Terminal output shape (post-voice-adjustment):** -``` -┌ helpbase login -│ -◆ Opening your browser to authorize… -│ URL: https://helpbase.dev/device?user_code=ABCD-EFGH -│ Code: ABCD-EFGH -│ -│ (compare this code to what the browser shows — if they differ, cancel -│ and run `helpbase login` again in a fresh terminal) -│ -◇ Waiting for browser approval… -│ -└ Logged in as me@company.com -``` - -**Progressive polling hints.** The spinner text updates on a timer regardless of polling activity: -- **T+0s:** "Waiting for browser approval…" -- **T+30s:** "Still waiting… check that a browser tab opened. URL: https://helpbase.dev/device?user_code=ABCD-EFGH" -- **T+90s:** "Taking longer than usual? Cancel with Ctrl-C, then run `helpbase login --email` for the fallback." -- **T+4min:** "1 minute until this code expires." -- **T+5min:** exits with `E_DEVICE_EXPIRED` (see error catalog below). - -Implemented as a `setInterval` inside `pollForToken` that rewrites the clack spinner message at each threshold. No extra polling load on the server — these are purely client-side. - -### 2.3b Error catalog (Tier 3) - -Six error codes, each with inline CLI copy (problem + cause + fix + docs link), a `helpbase.dev/errors/[code]` page (reuse `apps/web/app/(main)/errors/[code]/page.tsx`), and a telemetry event (opt-in via existing consent, logs the code + duration_ms_before_error). Prior learning `error-messages-need-working-links` — each docs page must ship in the same PR as the error, not later. - -| Code | When | CLI message (abbreviated) | Docs page | -|---|---|---|---| -| `E_DEVICE_DENIED` | User clicks Cancel in browser | "Cancelled. Run `helpbase login` again when you're ready." | `/errors/e-device-denied` | -| `E_DEVICE_EXPIRED` | 5-min code TTL hit | "Device code expired. Run `helpbase login` again." | `/errors/e-device-expired` | -| `E_DEVICE_NETWORK` | /device/token fetch fails after 3 retries | "Couldn't reach helpbase.dev. Check your network, then retry. `helpbase login --email` also works offline-to-email." | `/errors/e-device-network` | -| `E_DEVICE_NO_BROWSER` | Auto-detect browser-less OR `openBrowser` throws | "No browser detected. Open this URL manually: . Code: ." | `/errors/e-device-no-browser` | -| `E_LOGIN_RESEND_DOWN` | `sendMagicLink` returns Resend error (PR 1 surface) | "Couldn't send sign-in email. Resend error: . Try again in a minute." | `/errors/e-login-resend-down` | -| `E_LOGIN_STALE_TOKEN` | `~/.helpbase/auth.json` present but `getSession` returns null | "Your previous session expired. Starting a fresh login…" (non-fatal — flow continues into login) | `/errors/e-login-stale-token` | - -**Telemetry field:** each error captures `{ code, duration_ms_before_error, stage: "pre-browser" | "polling" | "post-approve" }` into the existing telemetry pipeline. Lets us measure drop-off by stage and iterate error copy. - -**Files:** -- New: `apps/web/app/(main)/errors/e-device-denied/page.tsx` + 5 others (one per code). Each page: "What happened / Why / What to do / What to try instead" four-section layout matching the existing `/errors/e-no-citations` pattern. -- Modify: `packages/cli/src/lib/errors.ts` — register the 6 codes. -- Modify: `packages/cli/src/lib/telemetry.ts` — add `logLoginError(code, fields)` helper. - -### 2.3c Stale-session UX (PR 1 + PR 2 shared) - -If the CLI detects a token on disk but `authClient.getSession` returns null (stale post-migration, expired, or revoked), do NOT silently re-prompt. Print one line first: - -``` -◇ Your previous session expired. Starting a fresh login… -``` - -Then proceed into the device-flow. Friction-point-free. - -### 2.4 Scaffolder inherits the new flow - -`packages/create-helpbase/src/index.ts:749–770` (`runHelpbaseLogin`) just spawns `helpbase login`. Zero changes needed. The moment `helpbase@0.5.0` ships, the scaffolder's "Log in" branch bounces through the browser automatically. - -### 2.5 Tests - -**Files:** -- New: `packages/cli/src/lib/__tests__/device-auth.test.ts` — mocks `authClient.device.*`, covers happy-path polling, `authorization_pending`, `slow_down`, `access_denied`, `expired_token`, `HELPBASE_LOGIN_NO_BROWSER`, Codespaces/SSH auto-detect, each of the 6 error codes, progressive-hint thresholds (fake timers). -- New: `apps/web/app/device/__tests__/page.test.tsx` — renders the server component for signed-in / signed-out / unknown-code cases, plus the OAuth-provider button render paths. -- New: `apps/web/app/(main)/errors/__tests__/device-errors.test.tsx` — smoke-renders each of the 6 error pages (catches the error-link-must-work-pre-ship regression). -- Modify: `scripts/smoke-install.sh` — add a `--device-login` mode with a mocked-auth server. - -### 2.6 Ship - -- Publish `helpbase@0.5.0`. -- CHANGELOG: "`helpbase login` now uses a browser device-flow. Legacy magic-link path preserved behind `--email`." -- Dogfood the full `pnpm dlx create-helpbase` flow → pick repo → pick Log in → browser bounces, Authorize click, cited docs at localhost:3000. No email involvement on the happy path. -- Save findings to memory. -- Rewrite `project_vegard_walkthrough.md` to drop the "check your email" step. - -### 2.7 PR 2 success criteria - -**TTHW (measurable):** -- Warm path (cookied on helpbase.dev): ≤10s end-to-end, ≤15s p95. -- Cold path via Google/GitHub OAuth: ≤20s end-to-end (first-time-only consent screen adds ~5s). -- Cold path via email fallback: ≤75s including email delivery round-trip. -- `pnpm dlx create-helpbase` → repo → Log in → OAuth → cited docs at localhost:3000: ≤2min total (Champion tier). - -**Behavior:** -- User-code shown in both CLI and browser; docs/error messages tell users to compare them. -- `HELPBASE_LOGIN_NO_BROWSER=1 helpbase login` prints URL + user-code and polls. Auto-detects `CODESPACES=true`, `SSH_TTY`, `SSH_CONNECTION` and behaves the same without the env var. -- `helpbase login --email` still runs the PR 1 magic-link-paste flow unchanged. -- All 6 error codes render a matching `/errors/[code]` page on helpbase.dev (no 404 links). -- Progressive polling hints fire at the documented T+30/90/240s thresholds. -- First-run post-migration: stale-token users see the "previous session expired" message, not a silent re-prompt. - -**Instrumentation:** -- `login_duration_ms` telemetry event (opt-in, respects existing consent). Fields: `{ path: "warm" | "oauth-google" | "oauth-github" | "email", duration_ms, outcome: "success" | "" }`. -- After 20 real login events, we have a measured distribution to compare against the claims above. Feeds the post-ship `/devex-review` boomerang. - -### 2.8 Docs updates (PR 2) - -**Files:** -- Modify: `README.md` — quickstart now mentions "the CLI opens a browser and shows a short code; compare it to the browser." One sentence, sets expectation. -- Modify: `packages/cli/README.md` — add a "Logging in" section covering the three paths (default device flow, `--email` fallback, `HELPBASE_TOKEN` for CI). -- Modify: `apps/web/content/getting-started/installation.mdx` — mirror the README update. -- Modify: `project_vegard_walkthrough.md` — strip the "check your email" step; walkthrough now reads "click Authorize in the browser tab that just opened." - ---- - -## Failure modes (both PRs combined) - -| Codepath | Failure | Caught? | User sees | -|---|---|---|---| -| Resend API down | Magic-link email never sends | Yes (Resend returns error) | `sendMagicLink` surfaces the error, CLI prints "Couldn't send sign-in email. Try again or paste a URL." | -| `/api/auth/*` 500 | Better Auth bug | Yes | CLI sees fetch error, prints "Couldn't reach helpbase.dev — check your network or run `helpbase login --email`." | -| Migration script — duplicate email conflict | `ON CONFLICT (id) DO NOTHING` skips rows | Partial — logged | Script prints per-row outcome; Christer's row is the only real one | -| FK repoint fails mid-migration | Transactional BEGIN/COMMIT | Yes | Migration aborts, Supabase auth still primary, rollback trivial | -| `authClient.device.code` errors | Plugin returns standard `error.error_description` | Yes | CLI prints a human-readable message and exits 1 | -| Polling: `slow_down` | Plugin's standard response | Yes | CLI increases interval (per Better Auth's docs) | -| Polling: `expired_token` | Row TTL hit | Yes | CLI prints "Login timed out — run `helpbase login` again" | -| Browser `open` fails (no xdg-open / missing util) | — | Yes | URL + user-code always printed to stdout first; user copies manually | -| User denies authorization in browser | `access_denied` from plugin | Yes | CLI prints "Cancelled." and exits 0 | -| User closes browser tab mid-flow | Row expires after 5min | Yes | Same as `expired_token` | -| Phishing: attacker sends victim a `/device?user_code=...` URL | User-code display is the whole defense | Yes | Victim compares user-code to their own terminal; mismatch = don't click | -| `RESEND_API_KEY` missing in prod | Better Auth boot fails | Yes | Vercel build / runtime error surfaces; operator gets clear log | -| `DATABASE_URL` not set | Better Auth can't boot | Yes | Vercel env check fails at deploy time | -| Stale `~/.helpbase/auth.json` with Supabase-format token post-migration | `auth.api.getSession` returns null | Yes | CLI falls back to unauthed state, prompts re-login | - ---- - -## Risks / open questions (eng) - -1. **Migration atomicity.** Copying `auth.users` → `public.user` + re-pointing FKs is a multi-statement operation. Wrap in a transaction. Back up `auth.users` before running (`pg_dump` of the `auth` schema). Test on a Supabase branch DB first (Supabase branches are cheap). - -2. **Better Auth + Supabase Postgres pooler compatibility.** Supabase's pooler is PgBouncer in transaction mode, which doesn't support session-level features like `LISTEN`. Better Auth uses the standard `pg` Pool — no `LISTEN` — so should be fine. Confirm by running migration script against a Supabase branch before prod. - -3. **`bearer()` plugin semantics.** The token Better Auth issues is a long random string (not a JWT). `~/.helpbase/auth.json` schema stays compatible because the CLI treats tokens opaquely — but `expiresAt` handling may shift. Check Better Auth's session expiry defaults and update the CLI's refresh logic if needed. - -4. **Refresh tokens.** Better Auth uses rolling session cookies server-side; the bearer token surface may or may not expose a separate refresh token. Need to verify during PR 1 implementation. If no refresh token, CLI just re-runs `login` when the bearer expires (default 7 days) — acceptable. - -5. **Resend sender domain.** `login@helpbase.dev` requires the `helpbase.dev` domain to be verified in Resend (SPF + DKIM). Takes ~10 min + a DNS change. Add as pre-merge prerequisite for PR 1. - -6. **`@better-auth/cli generate` output format.** Better Auth recommends Drizzle but also supports raw SQL. If we add `drizzle-kit`, that's a new framework in the stack (innovation token?). Cheap alternative: use Better Auth's `generate --sql` flag and land a plain `.sql` migration, skip Drizzle entirely. Prefer plain SQL unless we hit friction. - -7. **`trustedOrigins` list.** Must include every Vercel preview URL pattern, or preview deploys can't authenticate. Use `VERCEL_URL` env in the `trustedOrigins` array construction (dynamic). - -8. **`deviceAuthorization` plugin's `client_id` semantics.** The docs use `"demo-cli"`. We need a stable one like `"helpbase-cli"`. Per the plugin, `client_id` is not a secret — it identifies the CLI to the user-facing page for display purposes. - -9. **Session cookie vs bearer on the browser page.** Better Auth uses cookies by default on the browser. The device-flow approve endpoint reads the cookie session server-side. No token-in-body carriage needed. - -10. **Rollback plan.** PR 1 rollback: revert the `_shared.ts` + `auth.ts` + CLI commits, keep the DB tables (they're additive — no data lost). PR 2 rollback: revert the `login.ts` commit; `helpbase login --email` still works. Both PRs are trivially revertable. - ---- - -## NOT in scope (deferred) - -- **2FA / passkeys.** Better Auth has `twoFactor()` and `passkey()` plugins. Skip for v1. -- **Delete Supabase `auth.users`.** Leave as a read-only backup for 30 days. Cleanup is a separate TODO. -- **Session introspection UI on helpbase.dev** (list devices / revoke). Needs a signed-in dashboard, which we don't have. Post-Vegard. -- **Phone-number / SMS magic link.** Supabase supports it; Better Auth has a `phoneNumber()` plugin; current users don't need it. -- **Migration of `llm_usage_events` user_id semantics.** They reference user IDs we're preserving — no migration needed. Flag if FK breaks during implementation. - ---- - -## Success criteria (both PRs shipped) - -**PR 1 alone (magic-link UX unchanged):** -- `helpbase login` with a fresh email creates a row in `public.user` (not `auth.users`). -- Resend delivers the sign-in email from `login@helpbase.dev`. -- `/api/v1/llm/generate-object` + `/generate-text` accept the Better Auth bearer token with no API shape change. -- Supabase `auth.users` row count is ≥ `public.user` row count (never fewer — migration is copy, not move). -- FK: `select llm_usage_events.user_id from llm_usage_events join public.user on public.user.id = llm_usage_events.user_id` works for all existing rows. -- `pnpm dlx create-helpbase@latest foo` with "Log in" branch picks up the new auth transparently. - -**PR 2 additionally:** -- `helpbase login` fast path (cookied on helpbase.dev): under 10s end-to-end. -- User-code shown in both terminal + browser; docs/error messages tell user to compare them. -- `HELPBASE_LOGIN_NO_BROWSER=1` prints URL + user-code, polling still works. -- `helpbase login --email` runs the PR 1 magic-link-paste flow unchanged. -- `project_vegard_walkthrough.md` rewritten: "check your email" step deleted. - ---- - -## DX SCORECARD - -``` -+====================================================================+ -| DX PLAN REVIEW — SCORECARD | -+====================================================================+ -| Dimension | Pre | Post | Δ | -|----------------------|--------|--------|--------| -| Getting Started | 8/10 | 9/10 | +1 ↑ | -| API/CLI/SDK | 9/10 | 9/10 | — | -| Error Messages | 6/10 | 9/10 | +3 ↑ | -| Documentation | 7/10 | 8/10 | +1 ↑ | -| Upgrade Path | 8/10 | 9/10 | +1 ↑ | -| Dev Environment | 8/10 | 9/10 | +1 ↑ | -| Community | 6/10 | 6/10 | — | -| DX Measurement | 7/10 | 9/10 | +2 ↑ | -+--------------------------------------------------------------------+ -| TTHW warm | n/a | ≤10s | Champion | -| TTHW cold (OAuth) | ~60s | ≤20s | Champion | -| TTHW cold (email) | ~60s | ≤75s | Competitive | -| Competitive Rank | Champion on warm + OAuth, Competitive on email | -| Magical Moment | designed via copy-paste (create-helpbase) | -| Product Type | CLI Tool (primary) + Service (secondary) | -| Mode | POLISH | -| Overall DX | 7.4/10 | 8.5/10 | +1.1 ↑ | -+====================================================================+ -| DX PRINCIPLE COVERAGE | -| Zero Friction | covered (OAuth one-click cold path) | -| Learn by Doing | covered (scaffolder is the demo) | -| Fight Uncertainty | covered (6 error codes + /errors pages + hints)| -| Opinionated + Escape Hatches | covered (--email, NO_BROWSER env) | -| Code in Context | covered (scaffolder integration, not abstract) | -| Magical Moments | covered (cited docs from user's repo) | -+====================================================================+ -``` - -**Prior DX trend on main:** 8/10 (2026-04-17 autoplan). This plan moves the auth surface from "acceptable friction" to "first-class" — it's the product's first-touch surface, so the +1.1 lift is high-leverage. - -## GSTACK REVIEW REPORT - -| Review | Trigger | Why | Runs | Status | Findings | -|--------|---------|-----|------|--------|----------| -| CEO Review | `/plan-ceo-review` | Scope & strategy | 0 | — | Scope decided by user + context7: library adoption over custom roll | -| Codex Review | `/codex review` | Independent 2nd opinion | 0 | — | Skipped — revisit if PR 1 implementation surfaces unknowns | -| Eng Review | `/plan-eng-review` | Architecture & tests (required) | 1 | CLEAR (PLAN) | Pivoted from custom-device-flow to Better Auth; staged 2 PRs to de-risk migration + feature | -| Design Review | `/plan-design-review` | UI/UX gaps | 0 | — | One page + reused sign-in form; skipped | -| DX Review | `/plan-devex-review` | Developer experience gaps | 1 | CLEAR | 7.4 → 8.5, 3 gaps fixed: OAuth added (cold TTHW 60s→20s), Tier-3 error catalog (6 codes + docs + telemetry), progressive polling hints | - -**UNRESOLVED:** — -**CRITICAL GAPS:** — -**VERDICT:** ENG + DX CLEARED — ready to implement after user approval. Awaiting the STOP gate. diff --git a/QA-REVIEWER.md b/QA-REVIEWER.md deleted file mode 100644 index 4f75b63..0000000 --- a/QA-REVIEWER.md +++ /dev/null @@ -1,205 +0,0 @@ -# QA — helpbase distribution channels - -Thanks for testing. You're verifying that `npx create-helpbase` (npm) and -`shadcn add` (shadcn registry) both produce a working help center for real -users. **If either is broken, nobody can use the product** — so this is the -single most important test right now. - -Target time: **30-45 minutes** including reads. If you're fast or skip the -optional branches, 20 min is plausible. - ---- - -## Before you start - -- **Repo:** `https://github.com/Codehagen/helpbase` (main branch) -- **Live preview:** https://helpbase.dev -- **What you need:** Node 20+, pnpm, git, ~2 GB free disk. No API keys required for any of this QA. -- **What you're NOT testing:** AI article generation (`pnpm smoke`). That's a separate smoke path, needs a Vercel AI Gateway key, and is explicitly out of scope for you. - -Clone and install first: - -```bash -git clone https://github.com/Codehagen/helpbase.git -cd helpbase -pnpm install -``` - ---- - -## Pass 1 — Run the dev server and dogfood the site (10 min) - -```bash -pnpm --filter web dev -``` - -Open http://localhost:3000 and click through every visible link. Report: - -- [ ] Home page renders without console errors -- [ ] Category pages (`/getting-started`, `/customization`, `/cli`, `/guides`, `/reference`) render -- [ ] At least one article page renders with MDX content (not a blank page) -- [ ] Sidebar on doc pages shows every category and lets you navigate -- [ ] TOC on long articles highlights the current section as you scroll -- [ ] ⌘K opens the search modal from any page -- [ ] Typing in search filters results; Enter routes to an article; Esc closes -- [ ] Theme toggle (top-right) switches light/dark without breaking anything - -Browser sanity: - -- [ ] Resize window to 375 px wide — no horizontal scrollbar, layout adapts -- [ ] Dark mode has adequate contrast (read any paragraph at arm's length) - -Anything unexpected → **screenshot + URL + steps to reproduce.** Post in the -issue / DM / wherever we're collecting feedback. - ---- - -## Pass 2 — npm scaffolder smoke (`create-helpbase`) (5 min) - -This simulates what happens when someone runs `npx create-helpbase`. - -```bash -pnpm smoke:install -``` - -Expected output ends with: - -``` -✓ Install smoke test passed - Files: 65 scaffolded - Routes: 5 verified -``` - -If it passes, the scaffolder still produces a working Next.js help-center app. -If it fails, the scratch output is kept at the `/tmp/helpbase-install-smoke-*` -path printed in the log — share that path or the build error. - -**Bonus (optional):** manually walk the scratch project: - -```bash -cd /tmp/helpbase-install-smoke-* # path printed by smoke output -pnpm dev -# open http://localhost:3000 — should look identical to helpbase.dev -``` - -Flag any visual or behavioral diff between the scratch project and the repo's -`pnpm --filter web dev`. - ---- - -## Pass 3 — shadcn registry install (10 min) - -This simulates what happens when someone runs `shadcn add helpbase/help-center` -in their own Next.js + shadcn project. Two ways to test — automated for a -pass/fail signal, manual to catch UX issues. - -### 3A. Automated smoke (60-120s) - -```bash -pnpm smoke:registry -``` - -Expected output ends with: - -``` -✓ Registry smoke test passed -``` - -If it passes, the shadcn install path still produces a working help center. -If it fails, the scratch project is kept at `/tmp/helpbase-registry-smoke-*` -for inspection. - -### 3B. Manual walkthrough (5-10 min, RECOMMENDED) - -Follow the end-to-end install guide in **[`docs/shadcn-install.md`](docs/shadcn-install.md)**. - -That doc walks through creating a fresh Next.js project, running `shadcn init`, -running `shadcn add` against the built `public/r/help-center.json`, and -verifying the installed help center in a real browser. 5-10 minutes. - -**You want to do 3B at least once.** The automated smoke catches build -failures; the manual walkthrough catches everything else — confusing prompts, -weird post-install state, broken dark mode, sample articles that render wrong. -A real user does 3B, not 3A. - ---- - -## Pass 4 — Unit tests + typecheck (2 min) - -```bash -pnpm --filter web typecheck -pnpm --filter web test -``` - -Both should exit 0. Expect `Tests 30 passed (30)`. - ---- - -## Pass 5 — Visual spot-check against production (5 min) - -Open https://helpbase.dev in one tab and http://localhost:3000 in another. -Compare side-by-side: - -- [ ] Home page hero matches (centered, grid-pattern backdrop, "helpbase docs") -- [ ] Category card grid looks identical (3-col on wide, icon-in-square, same text) -- [ ] Article pages have the same left sidebar, same typography -- [ ] Dark mode calibration matches - -Any visual drift between local and production → flag it. Production is -`main` branch auto-deployed via Vercel, so they should be identical. - ---- - -## What "found a bug" looks like - -Good bug report: - -> **Where:** Home page, at 375px width -> **What I expected:** Category grid collapses to 1 column -> **What I saw:** Cards overflow the viewport horizontally -> **Reproduce:** Open http://localhost:3000 in Chrome, DevTools → iPhone SE preset -> **Evidence:** [screenshot] - -Bad bug report: - -> "Looks weird on mobile" - ---- - -## What to specifically look for - -Real risk areas (places we haven't had a second pair of eyes on): - -1. **Mobile nav** — the sidebar switches to a drawer below `lg`. Does the drawer button appear? Does it open cleanly? Does tapping a link close it? -2. **Search** — type in the search box. Does it filter live? Do arrow keys navigate? Does clicking a result route correctly? What happens with zero results? -3. **MDX rendering edge cases** — does an article with code blocks render the code correctly? Does an article with an embedded video show the embed (check the `customization/theming` article for the full component palette)? -4. **Dark mode** — toggle dark mode on the home page, then navigate to an article. Does the theme persist? Do any elements have poor contrast in dark? -5. **The scratch projects** (Pass 2+3 bonuses) — if either smoke test passes but the scratch project's `pnpm dev` looks broken, that's a silent failure we need to catch. - ---- - -## After testing - -Summary reply is enough. Something like: - -> Pass 1 ✓ — found two issues, see attached -> Pass 2 ✓ passed -> Pass 3 ✓ passed -> Pass 4 ✓ all green -> Pass 5 ✓ match -> Verdict: ship-ready / not yet (list of blockers) - -Thank you! - ---- - -## Reference — what's in the repo - -- `apps/web/` — canonical help-center UI (the site at helpbase.dev) -- `packages/create-helpbase/` — the `npx create-helpbase` scaffolder CLI -- `packages/helpbase/` — the `helpbase` CLI (content generation, etc.) -- `packages/ui/` — shared shadcn-based UI primitives and `globals.css` -- `packages/shared/` — types + schemas -- `registry/helpbase/` — standalone tree shipped via shadcn registry (synced from `apps/web`) -- `DESIGN.md` — source of truth for visual direction (read this if you want context on design choices) -- `SMOKE.md` — longer description of the smoke tests if you want to dig deeper diff --git a/TODOS.md b/TODOS.md deleted file mode 100644 index 502b388..0000000 --- a/TODOS.md +++ /dev/null @@ -1,113 +0,0 @@ -# TODOS - -Living list of deferred work surfaced by reviews. Items here have been -considered, judged worth doing, and explicitly deferred from the PR or -review they came from. Sorted by priority then by ticket order. - -## Format - -Each item: -- **What:** one-line description -- **Why:** the concrete problem it solves or value it unlocks -- **Pros / Cons:** what you gain / what it costs -- **Context:** enough detail that someone picking this up in 3 months knows where to start -- **Effort:** S / M / L / XL (with CC: usually one tier lower) -- **Priority:** P1 (blocks launch) / P2 (next-up) / P3 (nice to have) -- **Depends on / blocked by:** prerequisites or ordering constraints -- **Source:** which review or session surfaced it - ---- - -## P1 - -_All P1 items for the 2026-04-15 knowledge-layer plan shipped._ - -## P2 - -_None open._ - -## P3 - -### TODO-004: Hero screenshot / OG image for README + site -**What:** Capture a hero screenshot (or short recording) of the polished docs page and save it to `apps/web/public/og.png`. Then add it to the README under the badges block AND wire it as the OpenGraph image for `helpbase.dev`. - -**Why:** The README currently has no visual. Repos with hero images get more stars, and the OG image is what renders in Slack / X / LinkedIn previews when anyone shares a helpbase.dev link. Today the social preview is empty/default. - -**Pros:** Better launch surface. Higher conversion on GitHub visits. Decent social preview for when the Vegard-style walkthroughs get shared. -**Cons:** Needs a human — I can't take a real screenshot. - -**Context:** -- Target file: `apps/web/public/og.png` -- Recommended shot: demo tenant docs page (sidebar populated + TOC on right), 1600×840, light mode -- Once saved: add `![hero](./apps/web/public/og.png)` under the README badges, and wire `metadata.openGraph.images` in `apps/web/app/(main)/layout.tsx` -- helpbase.dev is live so a real screenshot is possible today (no scaffolder dependency) - -**Effort:** S (~20 min human — screenshot + README edit + metadata tweak) -**Priority:** P3 -**Source:** /plan-ceo-review 2026-04-09 system audit; re-filed 2026-04-17 after being prematurely dropped - -## Completed - -### TODO-018: `helpbase context` — direct `@ai-sdk/anthropic` / `@ai-sdk/openai` BYOK -**Completed:** 2026-04-17 — `packages/shared/src/llm.ts` now exports `resolveByokModel(modelString)` which routes by env-var precedence: `AI_GATEWAY_API_KEY` > `ANTHROPIC_API_KEY` > `OPENAI_API_KEY` > hosted. When a provider-specific key is set, the model string must match the provider prefix (e.g. `anthropic/claude-3-5-sonnet-latest` with `ANTHROPIC_API_KEY`); mismatches throw a clear `GatewayError` with the exact command to try instead. `isByokMode()` now returns true for any of the three keys. `byokGenerateObject` + `byokGenerateText` pass the resolved model factory to the Vercel AI SDK. Error catalog (`context-errors.ts::E_CONTEXT_MISSING_KEY`), `helpbase whoami`, and `helpbase doctor` all document the three options. 141/141 shared tests green (9 new routing tests covering every precedence path + error case). Pinned `@ai-sdk/anthropic@^2.0.77` + `@ai-sdk/openai@^2.0.103` to stay on `@ai-sdk/provider@2.x` (ai@5's peer). - -### TODO-020: `helpbase login` — proper device flow (Claude / Supabase CLI pattern) -**Completed:** 2026-04-17 via PR #3 (726a0fd) — `packages/cli/src/lib/auth-device.ts::deviceLogin` implements the full RFC 8628 browser device flow (the same spec `gh auth login`, `claude login`, and `supabase login` use). `packages/cli/src/commands/login.ts` runs it as the default; `--email` is the magic-link fallback for CI/sandboxed envs. State machine covers expiry hints, polling backoff, browser auto-open, and cancel. Better Auth's device plugin powers the server side (`apps/web/app/device/`); the browser-facing `/device` page has its own test coverage via `phase-reducer.test.ts` + `AuthorizeDeviceClient.test.tsx`. - -### TODO-011: Semantic search inside MCP `search_docs` tool -**Completed:** 2026-04-16 — `packages/mcp/src/content/semantic.ts` ships `buildSearchIndex` / `saveSearchIndex` / `loadSearchIndex` / `semanticSearch` / `cosineSimilarity` backed by `@xenova/transformers` (default model `Xenova/all-MiniLM-L6-v2`, 384-dim, quantized). `@xenova/transformers` is an **optional peer dep** (`peerDependenciesMeta.optional = true`) so the default install stays light; dynamic import with an install-hint error keeps keyword search working when the peer dep is absent. Custom `Embedder` injection keeps tests fully offline (no model download). New bin `helpbase-mcp-build-index` writes `.search-index.json` beside the content dir (configurable via `--content-dir` / `--output` / `--model` flags or `HELPBASE_SEARCH_INDEX` env). `buildServer` auto-loads the default index path, logs a stderr warning on stale docs, and wires the index into `handleSearchDocs` while advertising the upgraded tool description. 68/68 mcp tests green (19 new semantic tests covering cosine geometry, ranking correctness on auth/install/intro clusters, save/load round-trip, all malformed-index paths, keyword fallback). Existing `content/index.ts` renamed internal ranker to `keywordSearch`; exported `searchDocs` is now an async dispatcher. MCP package README documents the opt-in flow end to end. - -### TODO-007: Implement `helpbase generate --repo` for local repo markdown -**Completed:** 2026-04-15 — `packages/shared/src/ai-text.ts` exports `readRepoContent(repoPath)` which walks a local directory, picks up `.md`/`.mdx`/`.markdown` files (skipping `node_modules`/`.git`/`dist`/`.next`/`build`/`out`/`.turbo`/`.vercel`/`.cache`/`coverage`/`.helpbase`), sorts README-like files first, concatenates with `===== =====` headers, caps at 200k chars (shared `MAX_REPO_CONTENT_CHARS` / `MIN_SCRAPED_LENGTH`). `packages/cli/src/commands/generate.ts` wires `--repo` through the same article-plan pipeline as `--url` (supports `--debug`, `--dry-run`, `--test`, `--model`, `--output`). New `printRepoError` helper matches the existing problem/reason/fix/docs format. Generate test suite now covers missing-path, empty-dir, and dry-run-with-content paths; 305/305 CLI tests green + typecheck clean. GitHub URL ingestion (public `owner/repo` via Contents API) deferred — local paths cover the dogfooding flow and avoid token management for private repos. - -### TODO-010: HTTP / Streamable transport for `@helpbase/mcp` (v2) -**Completed:** 2026-04-15 — `packages/mcp/src/http.ts` ships `StreamableHTTPServerTransport` with bearer token auth (`HELPBASE_MCP_TOKEN`) + CORS allowlist (`HELPBASE_MCP_ALLOWED_ORIGINS`) + `/health` endpoint + fail-fast on missing token. New binary `helpbase-mcp-http` ships in the package. New CLI subcommand `helpbase mcp start [--http]` wraps both transports via `npx -y --package @helpbase/mcp`. E_NO_MCP_TOKEN error code with docs page at `/errors/e-no-mcp-token`. 49/49 MCP tests green (19 new HTTP tests including live integration: 401 auth, CORS preflight, /health no-auth, 404 unknown paths, cross-origin rejection). Bearer NOT OAuth by design — OAuth would require an identity provider, breaking code-you-own stance. - -### TODO-014: `helpbase-workflow` shadcn registry item -**Completed:** 2026-04-15 — `registry/helpbase-workflow/` ships a single `helpbase-sync.yml` that drops into `.github/workflows/` via `shadcn add helpbase-workflow`. Wired into `registry.json` + rebuilt `apps/web/public/r/helpbase-workflow.json`. The workflow runs `npx -y helpbase sync --apply --yes`, detects changes via `git status --porcelain`, creates a timestamped branch, and opens a PR via `gh pr create`. No separate GitHub Action repo to maintain — the YAML IS the primitive. Stance-pure: runs in the user's Actions minutes with their secrets. Passes `scripts/smoke-registry.sh`. - -### TODO-015: `create-helpbase --internal` variant -**Completed:** 2026-04-15 — `packages/create-helpbase/internal-overlay/` holds handbook-style content seed (handbook/welcome.mdx, runbooks/on-call.mdx, decisions/adr-template.mdx) + auth-ready `.env.example` with `HELPBASE_MCP_TOKEN` / `HELPBASE_MCP_ALLOWED_ORIGINS` / `AI_GATEWAY_API_KEY` scaffolding. `scaffold.ts` applies the overlay after the base scaffold when `--internal` is passed, wiping the public-docs sample first. `scripts/smoke-install.sh --internal` asserts the handbook/runbooks/decisions routes + `.env.example` + `llms.txt` artifacts. Default smoke (no flag) still passes. One template, one example, same product — no separate product line. - -### TODO-009: `helpbase sync` — codebase-grounded doc proposals -**Completed:** 2026-04-15 — `packages/shared/src/ai-sync.ts` + `packages/shared/src/schemas.ts` (SyncProposalSchema with mandatory citations) + `packages/cli/src/commands/sync.ts` (flags `--demo`, `--since`, `--content`, `--output`, `--model`, `--test`, `--dry-run`, `--apply`). Anti-hallucination gate proven by 200-mutation property test (`packages/cli/test/sync-schema.test.ts`). Bundled demo fixture at `packages/cli/fixtures/demo-repo/` delivers the 30-second magical moment (no API key, no config). Tier-2 error codes shipped: `E_NO_GH`, `E_NO_CITATIONS`, `E_NO_HISTORY`, `E_INVALID_REV`, `E_NO_CONTENT` with doc pages at `apps/web/app/(main)/errors/[code]/page.tsx`. 5-minute tutorial at `apps/web/content/guides/sync-in-5-minutes.mdx`. 303/303 CLI tests + 30/30 web tests green; smoke-install passes end-to-end with the new tutorial in the scaffolded output. Not in this PR: `--pr` gh integration (deferred), 10-fixture eval suite (P2 pre-prompt-change gate). - -### TODO-016: Positioning lockdown — home hero + README + registry copy -**Completed:** 2026-04-15 — `apps/web/app/(main)/page.tsx` hero rewritten to "The AI-native knowledge layer, as code you own." `README.md` intro + Why section rewritten to stance-first framing with primitives list (MCP, llms.txt, sync, workflows). `registry.json` help-center description aligned. No competitor names in any shipped surface. - -### TODO-013: Wire `generate-llms.mjs` into customer templates -**Completed:** 2026-04-15 — `packages/create-helpbase/template-assets/generate-llms.mjs` is a parameterized variant (reads `HELPBASE_SITE_URL` / `HELPBASE_PROJECT_NAME` / `HELPBASE_SUMMARY` with package.json fallbacks, graceful MDX/frontmatter error recovery). `scripts/sync-templates.mjs` copies it via `copyTemplateAssets()`. Template `package.json` wires `predev` + `prebuild` + `generate:llms` scripts. `scripts/smoke-install.sh` now asserts both `public/llms.txt` and `public/llms-full.txt` exist after scaffold + build — smoke-install passes end-to-end. - -### TODO-012: Claim `@helpbase` npm scope and ship v0.0.1 -**Completed:** 2026-04-15 — `@helpbase` org created on npmjs.com (free tier, public packages). `@helpbase/mcp@0.0.1` published to the registry (17.3 kB tarball, 50.2 kB unpacked, 8 files). End-to-end verified: `HELPBASE_CONTENT_DIR=./docs npx -y @helpbase/mcp` spawns, handshakes MCP protocol, returns all three tools with valid schemas, keeps stdout clean of non-JSON-RPC. Scope-family naming reserved for future `@helpbase/cli`, `@helpbase/sync`, etc. - -### TODO-008: Add link checker to `helpbase audit` -**Completed:** 416ff8d (2026-04-11) — internal link validation for markdown links and href props. Strips code blocks before checking, skips placeholder paths. Also fixed MDX component validation to strip code blocks (prevents false positives like `` in examples). Fixed broken link in reference/card-group.mdx. 6 new tests. - -### TODO-003: Dedup `registry/helpbase/lib/schemas.ts` against `packages/shared/src/schemas.ts` -**Completed:** 8bc8e5b + 2d7beb8 (2026-04-11) — the sync script (`scripts/sync-templates.mjs`) now generates both registry and template copies from `packages/shared/src/schemas.ts` via `inlineWorkspaceUtilitiesToRegistry()` and `inlineWorkspaceUtilitiesToTemplates()`. CI gate (`pnpm sync:templates && git diff --exit-code`) catches drift. Verified both copies are byte-identical. - -### TODO-005: Drop unused @hugeicons deps from apps/web/package.json -**Completed:** 8088ce7 (2026-04-11) — removed `@hugeicons/core-free-icons` and `@hugeicons/react` from apps/web (never imported). Kept in packages/ui where dialog.tsx uses them. - -### TODO-006: Zod version mismatch in workspace -**Completed:** 8088ce7 (2026-04-11) — removed dead `zod ^3.25.76` from packages/ui (never imported, grep confirmed). Workspace now has one zod version: `^4.3.6` in apps/web and packages/shared. - -### TODO-001: Update README "What you get" tree to match the real templates output -**Completed:** bdefe1f (2026-04-09) — rewrote tree against the actual scaffolded output (37 files). Also fixed stale test count (87→94), stale license badge (MIT→AGPL-3.0), and extended the monorepo Project structure section with the new scripts/ directory and templates dir explanation. - -### TODO-002: Prompt v0.0.3 — fix word floor + article count drift on markdown sources -**Completed:** 93a2de8 (2026-04-09) — tightened structure rule to require markdown ## H2 headings explicitly, added word-count self-check with source-density warning, expanded code-example trigger list, inlined banned marketing words into the title rule. Verified with four smoke runs on Gemini Flash Lite against vercel.com + resend.com: 8/8 articles hit 3+ headings (was 4/9 on v0.0.2), 8/8 hit 150+ words (was 1/9). Residual: 1-of-16 titles still contained "streamline" — baseline noise rate, not a rule failure. - ---- - -## Dropped (rationale retained for future reference) - -### TODO-017: `helpbase agent` — prompt-to-PR doc writer -**Dropped:** 2026-04-17 — explicitly blocked on "real user feedback from sync" per its own body. No feedback has arrived because sync itself hasn't been widely used yet. Keeping this as a stale P3 creates false confidence that the idea is captured; dropping it is honest. When sync usage grows and feedback surfaces a real need for prompt-to-PR, re-file with current context. - -### TODO-019: `helpbase context` — external-repo eval + nightly CI gate -**Dropped:** 2026-04-17 — the eval infrastructure already exists locally (`pnpm eval`, `packages/cli/eval/`) and gates pre-prompt-change work adequately. A nightly 90-LLM-call GitHub Action is speculative value against real ongoing spend. If a regression ever surfaces that only appears on an unfamiliar codebase, add *that specific* fixture to the existing suite — don't build a perpetually-running guardrail for a failure mode we've never observed. - - - diff --git a/UNIFIED_SCAFFOLDER_PLAN.md b/UNIFIED_SCAFFOLDER_PLAN.md deleted file mode 100644 index 4bd86cb..0000000 --- a/UNIFIED_SCAFFOLDER_PLAN.md +++ /dev/null @@ -1,304 +0,0 @@ -# Unified Scaffolder Plan — one `create-helpbase`, any content source - -Source: 2026-04-17 dogfood session. Follows the bundled-key ship (`helpbase@0.3.0`) + the create-helpbase auth/spinner fixes (`create-helpbase@0.2.1`). - ---- - -## Review Decisions (`/plan-eng-review` 2026-04-17) - -**Scope trimmed to Option B** — ship the new capability, defer speculative cleanup. - -### In scope for v0.3.0 - -- **Phase 1.1**: walker built-in deny-list (`generated`, `dist`, `build`, `out`, `.next`, `.nuxt`, `.svelte-kit`, `.turbo`, `.cache`, `target`, `coverage`, `__generated__`, `.vercel`, `.wrangler` + `*.min.js`, `*.min.css`, `*.map`, `*.snap`, `*-lock.json`, `*-lock.yaml`, `Cargo.lock`, `Gemfile.lock`, `poetry.lock`). -- **Phase 2.1**: `generate-from-repo.ts` composed directly from existing shared exports (`readContextSources`, `generateHowtosFromRepo`, `sanitizeMdx`, `articleToMdxWithCitations`, `enrichCitationsFromDisk`, `planContextWrites`). No new shared module. -- **Phase 2.3**: `emit-mcp-json.ts` helper — emits to `/mcp.json`, points `HELPBASE_CONTENT_DIR` at `/content/`. -- **Phase 3.1**: explicit top-level `select` ("A website URL" / "A code repository" / "Skip") + conditional path prompt with `fs.statSync` validation. -- **Phase 3.3**: three-stage spinner (Scanning → Synthesizing → Writing). -- **NEW**: GitHub URL detection in the website branch — if pasted URL matches `^https?://(www\.)?github\.com/`, show a second prompt "That looks like a GitHub repo. Clone and generate from source? [Y/n]". On yes, `git clone --depth 1` into a tmp dir and hand off to the repo branch. -- **NEW (Issue 1 fix)**: defer `clearSampleContent` until generation succeeds. Current code wipes before LLM call and the catch-branch message lies. -- **NEW (Issue 4 fix)**: if generation returns zero valid-citation docs, throw `AllDocsDroppedError` and show: "AI generation kept no articles — your repo may not have enough prose or the cheap model dropped citations. Retry with `--model anthropic/claude-sonnet-4.6` or run `helpbase context .` manually after scaffold." Sample content stays. -- **Phase 4 tests** + **smoke-install extension** — `scripts/smoke-install.sh --repo ` is MANDATORY per prior learning `reviews-miss-install-path`. - -### Subject + prompt framing (inline decisions) - -- LLM prompt uses the repo's `package.json` name (or basename of repo path) as the subject — NOT the user's typed scaffold project name. Matches `helpbase context` behavior. -- `mcp.json` lives at project root; `.helpbase/` is never created by the scaffolder (that layout is only for `helpbase context`). - -### Review Decisions (`/plan-devex-review` 2026-04-17) - -**Persona**: YC founder prototyping MVP (broader than Vegard-specific; higher bar). -**TTHW target**: Champion tier, under 2 minutes (down from planned 2:10). -**Magical moment**: localhost:3000 with articles cited to the user's own source files. -**Mode**: DX POLISH — bulletproof the flow, no scope expansion. - -#### Four DX adds folded into this plan - -1. **Conditional BYOK prompt** — if `~/.helpbase/auth.json` exists, skip the BYOK ask entirely. User is already authed, the question is noise. Lives in Phase 3.1 (the prompt flow). -2. **Eager walker** — if BYOK prompt is shown (no auth.json), start the repo walk in the background while the user reads the prompt. By the time they answer, we have source count + token estimate. Saves 1-3s on large repos. Phase 2.1 addition. -3. **Browser auto-open** — tail `pnpm dev` stdout, match Next.js's "Ready in XXXms" line, spawn `open` (macOS) / `xdg-open` (Linux) / `start` (Windows) on `http://localhost:PORT`. The magical moment has to land in the user's eyes, not their stdout. Phase 3 addition, ~15 lines of code. -4. **Docs update** — extend Phase 4 with: (a) `README.md` quickstart shows both URL and repo flows, (b) `apps/web/content/getting-started/installation.mdx` mirrors the scaffolder prompt structure, (c) scaffolded project's seed `README.md` snippet mentions the source it was generated from. - -### NOT in scope (deferred) - -- **Phase 1.2**: `.gitignore` respect — built-in deny-list covers the hagenkit case and ~90% of real projects. Revisit for v0.4.0 if users hit specific repos that need it. -- **Phase 2.2**: `runContextPipeline` extraction from `context.ts` (731 lines) — all the pieces the scaffolder needs are already exported from `ai-context.ts`. Extraction is speculative cleanup with real regression risk. Revisit when a third caller appears. -- **Phase 3.2**: blocking budget preview prompt — `TokenBudgetExceededError` already surfaces the over-budget case with an actionable error. Adding a "continue? [Y/n]" prompt is a friction beat for the 95% case where the budget is fine. Revisit if users report wasted quota. - -### What already exists (reconciled with current code) - -- `packages/shared/src/context-reader.ts:80` — `node_modules` skip is already there. Phase 1.1 extends this, doesn't rewrite. -- `packages/shared/src/context-writer.ts:123` — `planContextWrites` is already exported and ready to retarget from `.helpbase/docs/` to `content/`. -- `packages/cli/src/commands/context.ts:560` — `emitMcpJsonHint` exists as a private function. Phase 2.3 copies the pattern into a scaffolder-local helper (no extraction). -- `packages/shared/src/ai-context.ts` — exports `buildContextPrompt`, `estimateTokens`, `generateHowtosFromRepo`, `sanitizeMdx`, `articleToMdxWithCitations`, `enrichCitationsFromDisk`. All composable directly. -- `scripts/smoke-install.sh` — active install-path harness. Must extend for the repo branch (prior learning `reviews-miss-install-path`). - -### Failure modes - -| Codepath | Failure | Caught? | User sees | -|---|---|---|---| -| `readContextSources` | Over token budget | Yes | Actionable E_CONTEXT_OVER_BUDGET with top-10 largest files | -| `generateHowtosFromRepo` | Missing auth + BYOK | Yes | "Run `helpbase login` or set AI_GATEWAY_API_KEY" | -| Validator loop | All docs dropped | Yes (new) | Issue 4 message; sample preserved | -| `git clone` (GitHub branch) | Network / 404 / auth | **GAP** — plan needs to catch and show "Couldn't clone . Check the URL or paste a local path." | -| `scanForSecrets` | Secret detected pre-write | Yes | Pattern name + line number, never the secret itself | -| `writeFileSync` | EACCES / ENOSPC | **GAP** — plan should note scaffolder aborts loudly, does not partial-write | - -**Critical gaps flagged above**: 2 (git clone error handling, disk write failure). - ---- - - -## Problem - -`create-helpbase` today only seeds content from a URL. The flagship repo-grounded flow (`helpbase context` → citations + llms.txt + mcp.json) is strictly better for developer-audience help centers but is a two-command path that requires users to already know the CLI exists. A new user running `pnpm dlx create-helpbase` always sees the URL flow and never discovers the repo flow — even though the repo flow is our strongest demo. - -## Goal - -One entry point — `pnpm dlx create-helpbase ` — that seeds the help center from a URL, a local repo path, or ships sample content only. User picks the source in one prompt. Same final artifact (Next.js app on localhost) regardless of path. - ---- - -## Phase 1 — Walker ignore patterns (standalone prereq) - -Fixes Finding #3 from the dogfood memory (`project_walker_ignores_missing.md`). Lands first because both `helpbase context` and the new scaffolder repo-flow depend on it. - -### 1.1 Built-in deny-list in `walkMarkdownFiles` - -**Files:** -- `packages/shared/src/context-reader.ts` — extend the existing `node_modules` / `.git` skip with a full deny-list. -- `packages/shared/src/__tests__/context-reader.test.ts` — cover each dir in the deny-list. - -**Deny-list (always skipped, can be overridden with a future `--include-generated` flag):** -- Directory names: `node_modules`, `.git`, `dist`, `build`, `out`, `.next`, `.nuxt`, `.svelte-kit`, `.turbo`, `.cache`, `target`, `coverage`, `generated`, `__generated__`, `.vercel`, `.wrangler`. -- File globs: `*.min.js`, `*.min.css`, `*.map`, `*.snap`, `*-lock.json`, `*-lock.yaml`, `Cargo.lock`, `Gemfile.lock`, `poetry.lock`. - -**Acceptance:** -- Running `helpbase context .` on hagenkit walks <150 files (down from 311) and estimates <100k tokens (down from 477k). -- Existing tests still pass; the token budget regression disappears. - -### 1.2 `.gitignore` respect (opt-out) - -**Files:** -- `packages/shared/src/context-reader.ts` — add `readGitignorePatterns(repoRoot)` helper; apply as a second filter layer on the walker. -- `packages/shared/src/__tests__/context-reader.test.ts` — fixture with a `.gitignore` that excludes `secret/`; assert files under `secret/` are skipped. - -**Scope intentionally narrow:** -- Parse line-by-line; skip comments (`#`) and empty lines. -- Support leading `/` (repo-relative anchor) and trailing `/` (dir only). -- Do **not** implement full gitignore semantics (no negation `!`, no `**` beyond what `minimatch` gives for free). -- CLI flag: `--no-respect-gitignore` disables. On by default. - -**Acceptance:** -- Repo with `generated/` gitignored (but no entry in the built-in deny-list yet) skips the dir. -- `--no-respect-gitignore` walks everything including gitignored paths (for cases where `.gitignore` excludes files we want to document, e.g. example configs). - -### 1.3 Ship as `helpbase@0.4.0` + `@workspace/shared` - -**Packages bumped:** -- `helpbase`: `0.3.0` → `0.4.0` (minor — new walker behavior is user-visible even though it's strictly additive for most users). -- `@workspace/shared`: workspace-internal, no publish. - ---- - -## Phase 2 — `generate-from-repo` in create-helpbase - -Wraps the shared context pipeline behind a scaffolder-shaped API. Writes to `/content/` (the Next.js content root), not `.helpbase/docs/` (the agent-facing location `helpbase context` uses). - -### 2.1 New `packages/create-helpbase/src/generate-from-repo.ts` - -**Exports:** -```ts -export async function generateFromRepo(opts: { - projectDir: string // scaffold root (where content/ lives) - repoPath: string // absolute, pre-validated - model: string - authToken?: string - maxTokens: number // from --max-tokens or default 100_000 - onPhase?: (phase: "scraping" | "synthesizing" | "writing", detail?: string) => void -}): Promise<{ articlesWritten: number; droppedDocs: number }> -``` - -**Implementation:** -1. `onPhase("scraping")` → call `readContextSources(repoPath, ...)` from shared. -2. Budget check: if `tokensEstimated > maxTokens`, throw `RepoTooLargeError` (new class, caller maps to friendly prompt). -3. `onPhase("synthesizing", "(~15-30s)")` → call the existing `generateContextDocs` path (extracted from `context.ts`; see 2.2). -4. `onPhase("writing")` → map generated `GeneratedContextDoc[]` into the scaffolder's `content//.mdx` layout. Reuse `planArticleWrites` by adapting input shape, or write a new `planContextArticleWrites` that preserves the `## Sources` section. -5. Return counts for CLI display. - -**Key difference from `helpbase context`:** -- Writes to `content/` not `.helpbase/docs/` (so Next.js picks it up). -- Emits `_category.json` per category (for the Next.js sidebar). -- Does NOT emit `.helpbase/mcp.json` here — that's optional and lives at the project root alongside; separate helper. - -### 2.2 Extract `generateContextDocs` core from `packages/cli/src/commands/context.ts` - -Pull the 16-step pipeline (or its LLM + validation + synthesis-report core) into a shared function so both `helpbase context` and `create-helpbase --from-repo` call the same code. - -**Files:** -- New: `packages/shared/src/context-pipeline.ts` — exports `runContextPipeline(opts)` returning `{ docs, report }`. -- Refactor: `packages/cli/src/commands/context.ts` — thin wrapper over `runContextPipeline` + the CLI-specific write sites. -- Refactor: `packages/create-helpbase/src/generate-from-repo.ts` — same wrapper, different write sites. - -**Invariants preserved:** -- Citation validator still pre-writes. -- Secret deny-list still pre-writes. -- Prompt injection mitigation (``) unchanged. -- Atomic writes + rollback unchanged. - -**Acceptance:** -- `pnpm test -F shared` covers the extracted module directly. -- `pnpm test -F helpbase` still passes (CLI behavior unchanged). -- `helpbase context` output byte-identical to `0.3.0` on a fixture. - -### 2.3 `emitMcpJson` helper at project root - -After repo synthesis, write `/mcp.json` using the same per-client hint format `helpbase context` emits. Content points at `/content/` as `HELPBASE_CONTENT_DIR`. - -**Files:** -- New: `packages/create-helpbase/src/emit-mcp-json.ts` (or extract from shared). -- `packages/create-helpbase/src/index.ts` — call after `generateFromRepo` resolves. - -**Acceptance:** -- Fresh scaffold with repo source has `mcp.json` at root listing Claude Desktop / Cursor / Claude Code blocks. -- User can copy-paste into their MCP client and the server finds the content dir. - ---- - -## Phase 3 — Unified prompt flow in `index.ts` - -### 3.1 Single content-source prompt - -Replace the current two prompts (URL then BYOK) with a branching flow: - -``` -┌ create-helpbase -│ Project name: my-docs -│ -│ Seed content from? -│ ▸ A website (paste URL) -│ A code repository (paste local path) -│ Skip — ship with sample content -│ -│ [if URL selected] URL: https://… -│ [if repo selected] Repo path: ./my-repo -│ -│ BYOK? Paste a Vercel AI Gateway key (optional — most people skip this and run `helpbase login` instead) -``` - -**Files:** -- `packages/create-helpbase/src/index.ts` — replace the current URL-only prompt with `@clack/prompts` `select` + conditional `text`. -- Retain BYOK prompt — unchanged. - -### 3.2 Path validation + budget preview - -For the repo branch: - -1. Resolve the path: `path.resolve(process.cwd(), input)` so `.`, `./x`, and `/abs/x` all work. -2. Validate: `fs.statSync` + `isDirectory()`; friendly error if not. -3. Run the Phase 1 walker to count sources + estimate tokens. -4. Show: `Found 76 source files, ~123k tokens. That's ~25% of your daily free quota. Continue? [Y/n]`. -5. If user declines, fall back to sample content (same as URL flow today when the user cancels). - -**Files:** -- `packages/create-helpbase/src/index.ts` — inline validation + confirm prompt. - -### 3.3 Three-stage spinner (apply today's lesson) - -Use the same pattern from `create-helpbase@0.2.1`: - -``` -✓ Scanning repo... (1-3s, from walker) -✓ Synthesizing articles... (15-30s, the LLM call) -✓ Writing articles... (<1s) -``` - -The `onPhase` callback on `generateFromRepo` drives the spinner state changes. - ---- - -## Phase 4 — Test + publish - -### 4.1 Integration test - -**Files:** -- `packages/create-helpbase/test/cli.integration.test.ts` — new `"seeds from a repo path"` case using the existing `demo-repo` fixture. -- Mock the LLM call (re-use existing mocks from CLI context tests). - -### 4.2 CHANGELOG + release - -**Packages bumped:** -- `create-helpbase`: `0.2.1` → `0.3.0` (new top-line feature). -- `helpbase`: already shipped `0.4.0` in Phase 1. - -**CHANGELOG entry:** -- Single `[0.3.0]` section covering all three: repo source, walker ignores, unified prompt flow. - -### 4.3 Publish + dogfood - -1. `pnpm -F create-helpbase publish`. -2. Dogfood in a fresh dir against a small OSS repo (e.g. `sindresorhus/p-map`). -3. Dogfood against hagenkit (should now fit under budget). -4. Save findings to memory. - ---- - -## Risks / open questions (eng) - -1. **Pipeline extraction is load-bearing.** `context.ts` is 700+ lines of carefully ordered steps. Getting `runContextPipeline` right without regressing citations, secrets, or atomic writes is the biggest risk. Mitigate with byte-identical fixture test before refactor lands. - -2. **Path detection heuristic.** `http://` / `https://` → URL is easy. Local path validation covers most cases. Open: do we clone a GitHub URL (`github.com/foo/bar`)? Suggest **no for v1** — clone-and-walk is a bigger feature. v1 = local paths only. v2 = clone. - -3. **Quota preview is blocking.** User sees walker estimate, must confirm before the LLM call. On slow connections the walker runs fast (<1s) but the confirm prompt adds a friction beat. Alt: background the walker while the user confirms BYOK; if confirm arrives before walker done, wait. Probably overkill for v1. - -4. **`.gitignore` semantic parity.** Full gitignore is hard (negation, `**`, per-directory `.gitignore`). Scoped to "line-by-line prefix + trailing-slash" for v1. Users who want more can use `--no-respect-gitignore`. - -5. **Output layout drift.** `helpbase context` writes to `.helpbase/docs/`. `create-helpbase --from-repo` writes to `content/`. The MDX content is identical; only the root differs. Downstream consumers (Next.js app, MCP server, llms.txt generator) need to be path-aware — they already are (via `HELPBASE_CONTENT_DIR`), so no churn expected. Double-check the llms.txt generator script the scaffold ships with. - ---- - -## Success criteria - -- `pnpm dlx create-helpbase@0.3.0 my-docs` → pick URL → works (no regression from 0.2.1). -- Same, pick repo, small OSS repo → `content/` gets 4-8 cited articles, dev server renders them with the `## Sources` section expanded. -- Same, pick repo, hagenkit → budget prompt shows a passable number (thanks to Phase 1 ignores), user can accept or decline. -- Same, pick skip → sample content unchanged. -- `helpbase context` on hagenkit finishes under the daily cap. -- `helpbase context` on the helpbase repo itself produces byte-identical output to `0.3.0`. - ---- - -## GSTACK REVIEW REPORT - -| Review | Trigger | Why | Runs | Status | Findings | -|--------|---------|-----|------|--------|----------| -| CEO Review | `/plan-ceo-review` | Scope & strategy | 0 | — | — | -| Codex Review | `/codex review` | Independent 2nd opinion | 0 | — | — | -| Eng Review | `/plan-eng-review` | Architecture & tests (required) | 1 | CLEAR (PLAN) | 4 issues, 2 critical gaps, SCOPE_REDUCED mode | -| Design Review | `/plan-design-review` | UI/UX gaps | 0 | — | — | -| DX Review | `/plan-devex-review` | Developer experience gaps | 1 | CLEAR | score 8/10, TTHW 2:10 → < 2min (Champion), 4 DX adds folded in, POLISH mode | - -**UNRESOLVED:** 0 -**CRITICAL GAPS:** 2 (git clone error handling, disk-write failure handling — both noted in Failure modes table above, must be addressed in implementation) -**VERDICT:** ENG + DX CLEARED — scope trimmed, DX principles all covered, Champion-tier TTHW achievable. Ready to implement. - diff --git a/apps/web/components.json b/apps/web/components.json index ce5c897..4e8896e 100644 --- a/apps/web/components.json +++ b/apps/web/components.json @@ -19,5 +19,13 @@ }, "rtl": false, "menuColor": "inverted-translucent", - "menuAccent": "subtle" + "menuAccent": "subtle", + "registries": { + "@tailark-pro": { + "url": "https://pro.tailark.com/registry/{name}", + "headers": { + "Authorization": "Bearer ${TAILARK_API_KEY}" + } + } + } } diff --git a/apps/web/emails/sign-in-magic-link.tsx b/apps/web/emails/sign-in-magic-link.tsx index c4f0839..d471a55 100644 --- a/apps/web/emails/sign-in-magic-link.tsx +++ b/apps/web/emails/sign-in-magic-link.tsx @@ -33,8 +33,7 @@ export default function SignInMagicLinkEmail({ extend: { colors: { // Cool-neutral palette approximations of the in-app shadcn tokens - // (oklch doesn't render in email clients). Matches the - // editorial-technical aesthetic documented in DESIGN.md. + // (oklch doesn't render in email clients). ink: "#0a0a0a", paper: "#ffffff", wash: "#fafafa", diff --git a/apps/web/lib/supabase-admin.ts b/apps/web/lib/supabase-admin.ts index f9c5be3..0e6be20 100644 --- a/apps/web/lib/supabase-admin.ts +++ b/apps/web/lib/supabase-admin.ts @@ -28,4 +28,4 @@ export function getServiceRoleClient(): SupabaseClient { } // verifyBearerToken removed 2026-04-17 — replaced by Better Auth's -// auth.api.getSession({ headers }) in every call site. See DEVICE_FLOW_PLAN.md. +// auth.api.getSession({ headers }) in every call site.