@polishd/next 0.1.0 → 0.2.0

package/AGENTS.md

@@ -18,13 +18,19 @@ Read these from the target app before changing anything.
 | Next.js App Router | an `app/` or `src/app/` directory exists | Stop. Polishd has no Pages Router support. |
 | Next.js ≥ 15 | `next` version in `package.json` | Stop and report. |
 | Node ≥ 22.5 | `node -v`, plus `engines`/`.nvmrc`/host setting | Capture silently no-ops on older Node. Warn the user and continue only if they accept that. |
-| Tailwind CSS | `tailwindcss` in dependencies | The dashboard renders unstyled. See Phase 4. |
 | Package manager | lockfile name | Use it consistently; don't mix. |
 
 Record two facts you will need throughout:
 
 - **`BASE`** — `src` if `src/app/` exists, otherwise `` (repo root).
-- **`NEXT_MAJOR`** — 16+ uses `proxy.ts`; 15 uses `middleware.ts`.
+- **`NEXT_MAJOR`** — 16+ uses `proxy.ts`; 15 uses `middleware.ts`. Read the
+  *installed* version from `node_modules/next/package.json`, not the range in
+  `package.json` — `^16`, `latest` and `canary` tell you nothing about what is
+  actually installed. The CLI does this for you; you need it only for Phase 3b.
+
+Getting `NEXT_MAJOR` wrong is a silent total failure, not a build error: Next
+simply never loads a file under the other name, so no session cookie is minted,
+every beacon still returns 200, and nothing is ever stored.
 
 ## Phase 2 — Install
 
@@ -37,18 +43,25 @@ Postgres URL is configured. No separate install is needed.
 
 ## Phase 3 — Scaffold
 
-Prefer the CLI. It handles every branch in Phase 1 and Phase 4 for you:
+Prefer the CLI. It detects `BASE` and `NEXT_MAJOR` itself, so you do not have
+to branch on them:
 
 ```bash
-npx polishd init
+npx @polishd/next init
 ```
 
-Flags: `--dry-run` (preview), `--force` (overwrite existing), `--js` (JavaScript
-output), `--config` (also emit `polishd.config.ts`).
+Flags: `--dry-run` (preview), `--force` (regenerate files the CLI itself wrote,
+backing each up to `.bak` first), `--js` (JavaScript output), `--config` (also
+emit `polishd.config.ts`).
+
+It writes four files and appends `.polishd/` to `.gitignore`.
+It names the proxy file for the detected Next major and reports which it chose;
+if it could not determine the version it says so — check that against Phase 1
+and rename by hand if it guessed wrong.
 
-It writes four files, appends `.polishd/` to `.gitignore`, and wires Tailwind.
-If it reports that a file already exists, do not overwrite blindly — merge by
-hand following Phase 3b.
+**`--force` will not overwrite a file the CLI did not write**, so it is safe to
+re-run. When it finds a proxy it did not author it prints merge instructions
+instead. Follow Phase 3c, not Phase 3b, in that case.
 
 ### Phase 3b — Manual scaffold (only if the CLI could not run)
 
@@ -70,9 +83,7 @@ export const config = {
 };
 ```
 
-If the app already has a proxy/middleware, do **not** replace it. Call
-`withPolishdSession(request, existingResponse)` in the existing handler and
-merge the matcher, keeping the `api` exclusion.
+If the app already has a proxy/middleware, do **not** replace it — see Phase 3c.
 
 **2. `{BASE}/instrumentation-client.ts`** — starts browser capture.
 
@@ -96,6 +107,7 @@ export const POST = createPolishdRoute();
 **4. `{BASE}/app/polishd/page.tsx`** — the dashboard.
 
 ```tsx
+import "@polishd/next/dashboard.css";
 import { createPolishdPage } from "@polishd/next/dashboard";
 
 export const runtime = "nodejs";
@@ -106,29 +118,62 @@ export default createPolishdPage();
 
 Then add `.polishd/` to `.gitignore`.
 
-## Phase 4 — Wire Tailwind
+### Phase 3c — The app already has a proxy or middleware
+
+Next loads exactly one proxy module, so Polishd goes **inside** the existing
+one. Never replace it: that file typically carries auth redirects, i18n, A/B
+routing, or rate limiting.
+
+The trap is the matcher. One file means one `config.matcher`, so merging means
+widening it to the union — and Polishd's matcher is near-total. A handler that
+was scoped to two routes silently begins running on every request in the app.
+Nothing errors; its redirects just start firing where they never did before.
+
+Use `composePolishd` and declare the handler's original scope, which is
+re-applied as an internal guard:
+
+```ts
+import { composePolishd } from "@polishd/next/proxy";
 
-The dashboard is built from Tailwind utility classes and ships **no stylesheet**.
-Tailwind will not find it on its own — v4's content detection deliberately
-ignores `node_modules`, and v3 only scans the globs you give it. Skipping this
-step produces a dashboard that returns HTTP 200 and is completely unstyled.
+// Existing handler, unchanged.
+function myProxy(request: NextRequest) { /* … */ }
 
-**Tailwind v4** (no `tailwind.config.*`; CSS has `@import "tailwindcss"`) — add
-to that CSS file, with the path relative to the file itself:
+// Keeps running only on /admin/*, though the matcher below is near-total.
+export const proxy = composePolishd(myProxy, { matcher: "/admin/:path*" });
 
-```css
-@import "tailwindcss";
-@source "../../node_modules/@polishd/next/dist";
+export const config = {
+  matcher: ["/((?!api|_next/static|_next/image|favicon|assets).*)"],
+};
 ```
 
-**Tailwind v3** — add to `content` in `tailwind.config.*`:
+Read the existing `config.matcher` **before** you overwrite it and pass exactly
+that value as `matcher`. On Next 15 the file is `middleware.ts` and the export
+must be named `middleware`.
 
-```ts
-content: ["./src/**/*.{ts,tsx}", "./node_modules/@polishd/next/dist/**/*.js"],
+`matcher` accepts Next's matcher strings or a `RegExp`. The union literal itself
+must still be written by hand — Next statically parses it (Invariant 1).
+
+## Phase 4 — Styling
+
+One import in the dashboard page, which the CLI writes for you:
+
+```tsx
+import "@polishd/next/dashboard.css";
 ```
 
-**No Tailwind** — tell the user the dashboard will be unstyled. Do not add
-Tailwind to their app to fix this unless they ask.
+The stylesheet is compiled at publish time and self-contained. **Do not add
+Tailwind to the app, and do not add an `@source` line** — neither is needed, and
+the host's Tailwind version is irrelevant to how the dashboard renders.
+
+It carries no global preflight and every rule is scoped to `.polishd-root`, so
+it cannot restyle the host app.
+
+**On an existing 0.1.x install**, a `@source ".../@polishd/next/dist"` line in
+the host's Tailwind config is still doing the styling and the dashboard is not
+broken. Do not remove it as a first step. Add the stylesheet import, verify the
+dashboard still renders correctly, and only then remove the `@source` line —
+removing it first is the one order that leaves the dashboard unstyled. If the
+app has no Tailwind at all, the import is the only thing that styles it.
 
 ## Phase 5 — Invariants
 
@@ -145,10 +190,13 @@ style preferences.
    fails the build with *"Next.js can't recognize the exported `runtime` field
    in route. It mustn't be reexported."*
 
-3. **Gate the dashboard in production.** With no `authenticate` callback, the
-   dashboard *and its server actions* are public: anyone reaching the URL can
-   read the analytics, change the configured model and API base URL, and spend
-   the owner's model tokens. See Phase 6.
+3. **The dashboard refuses to serve in production until access is decided.**
+   It is not a read-only report: its settings change the configured model and
+   API base URL, so reaching it means being able to redirect the owner's
+   requests and spend their key. With no `POLISHD_DASHBOARD_TOKEN`, no
+   `authenticate` callback, and no `POLISHD_DASHBOARD_PUBLIC=true`, production
+   renders a locked screen and every server action denies. Development is
+   unaffected. See Phase 6.
 
 4. **Never import `@polishd/next/server` from a client component.** It pulls
    database drivers into the browser bundle. Use `@polishd/next/client` there.
@@ -158,8 +206,32 @@ style preferences.
 
 ## Phase 6 — Protect the dashboard
 
-If the app has any auth helper, wire it up. Ask the user which one rather than
-guessing.
+Pick one of three. **If the app has no auth of its own, use the token** — do not
+hand-roll a gate, and do not leave it for the user to figure out later.
+
+**1. Built-in token (default choice for an app with no auth).** No code:
+
+```bash
+POLISHD_DASHBOARD_TOKEN=$(openssl rand -hex 32)
+```
+
+Add it to the app's `.env.example` and tell the user to set it in their
+deployment environment. The locked screen renders a password form; the token is
+exchanged for an httpOnly, path-scoped cookie by a server action, so it never
+travels in a URL. Constant-time comparison, HMAC in the cookie rather than the
+raw token, server-side expiry, and per-IP rate limiting are all handled.
+
+Pass options only if the dashboard is not at `/polishd`:
+
+```tsx
+import { createPolishdPage, polishdTokenAuth } from "@polishd/next/dashboard";
+export default createPolishdPage({
+  authenticate: polishdTokenAuth({ basePath: "/admin/polishd" }),
+});
+```
+
+**2. The app's own auth.** If the app has an auth helper, prefer it. Ask the
+user which one rather than guessing.
 
 ```tsx
 import { createPolishdPage } from "@polishd/next/dashboard";
@@ -170,25 +242,50 @@ export const runtime = "nodejs";
 export const dynamic = "force-dynamic";
 
 export default createPolishdPage({
-  authenticate: isAuthenticated,   // () => boolean | Promise<boolean>
+  authenticate: isAuthenticated,   // (ctx) => boolean | Promise<boolean>
   unauthorized: <MyLogin />,       // optional; a minimal screen otherwise
 });
 ```
 
-The same callback guards the AI server actions, re-running per request against
-the caller's cookies. Polishd ships no auth code of its own.
+`authenticate` receives `{ cookies, headers }` for the request, so it need not
+call `cookies()`/`headers()` itself. A zero-argument callback still works.
 
-A common pattern is to stay open in development and require auth in production:
+**3. Deliberately public.** Only if the user asks for it:
 
-```tsx
-authenticate: async () =>
-  process.env.NODE_ENV !== "production" || (await isAuthenticated()),
+```bash
+POLISHD_DASHBOARD_PUBLIC=true
 ```
 
+In every case the same policy guards the AI server actions, re-running per
+request against the caller's cookies. Note that an app which deletes
+`app/polishd/page.tsx` while keeping the package leaves those actions routable
+but always denying — correct, but confusing if you meet it cold.
+
 ## Phase 7 — Verify
 
 Run all of these. Report the results; do not declare success from the build
-alone.
+alone — most of what can be wrong here builds cleanly and fails silently.
+
+Start with the doctor, which checks the whole wiring in one command:
+
+```bash
+npx @polishd/next doctor
+```
+
+It verifies the proxy is named and exported for the detected Next major, that
+`config.matcher` is an inline literal excluding `/api`, that `runtime` and
+`dynamic` are declared rather than re-exported, that capture and ingest exist,
+that the dashboard stylesheet is imported, and the access posture. Fix everything it
+reports before continuing.
+
+With the app running, add live checks — this is the only way to confirm the
+cookie is really minted and events really store:
+
+```bash
+npx @polishd/next doctor --url http://localhost:3000
+```
+
+Then confirm by hand:
 
 ```bash
 # 1. Build must pass.
@@ -213,7 +310,7 @@ curl -s -X POST http://localhost:3000/api/polishd \
 #    expect: {"ok":true,"stored":1}
 
 # 6. Styling is present — the stylesheet must contain dashboard utilities.
-#    Fetch the dashboard's CSS chunk and grep for `tabular-nums`.
+#    The dashboard page must import "@polishd/next/dashboard.css".
 ```
 
 In development the store writes `.polishd/analytics.db` (SQLite). Its presence
@@ -228,6 +325,9 @@ survive there.
 | Variable | Required | Purpose |
 |---|---|---|
 | `POLISHD_DATABASE_URL` | for production capture | Pooled Postgres connection string |
+| `POLISHD_DASHBOARD_TOKEN` | for production, unless auth is wired | Protects `/polishd`. `openssl rand -hex 32` |
+| `POLISHD_DASHBOARD_PUBLIC` | no | `true` to serve the dashboard unguarded on purpose |
+| `POLISHD_SESSION_COOKIE` | no | Rename the session cookie; read by both proxy and ingest |
 | `POLISHD_DB_PATH` | no | Custom SQLite path in dev |
 | `POLISHD_AI_*` | no | Preset AI provider/model/key instead of using the dashboard |
 | `POLISHD_GITHUB_*` | no | Repo + token for filing issues from findings |
@@ -240,14 +340,22 @@ a notice on the dashboard, and no impact on the host app.
 
 ## Troubleshooting
 
+Run `npx @polishd/next doctor` first — it names most of these directly.
+
 | Symptom | Cause | Fix |
 |---|---|---|
 | *"can't recognize the exported `runtime` field"* | Route segment config re-exported | Declare `runtime`/`dynamic` inline (Phase 3b) |
 | Every `/api/*` route 404s | Proxy matcher matches `/api` | Restore the `api` exclusion in the matcher |
-| Dashboard renders unstyled | Tailwind isn't scanning `dist` | Phase 4 |
+| Dashboard renders unstyled | `@polishd/next/dashboard.css` not imported in the page | Phase 4 |
 | Dashboard is empty, warning about the store | No writable backend | Set `POLISHD_DATABASE_URL`, or check Node ≥ 22.5 in dev |
+| Dashboard shows *"no session cookie — your proxy isn't running"* | Proxy missing, misnamed for the Next major, matcher not covering the path, or a botched merge | Phase 3c and `doctor --url` |
+| Beacons return 200 but nothing is stored | Same as above — ingest answers `{ok:true,stored:0,reason:"no_session"}` so the client cannot see a failure | `doctor --url http://localhost:3000` |
+| Proxy and ingest disagree on the cookie name | `sessionCookie` threaded into one layer but not another | Set `POLISHD_SESSION_COOKIE`; both read it |
 | `ERR_UNKNOWN_BUILTIN_MODULE: node:sqlite` | Node < 22.5 | Upgrade Node, or configure Postgres |
-| No `polishd_session` cookie | Proxy file missing/misnamed, or matcher excludes the path | Check `proxy.ts` (Next 16) vs `middleware.ts` (Next 15) |
+| `ExperimentalWarning: SQLite is an experimental feature` | Node's own `node:sqlite` module on 22.x | **Expected and harmless.** Not a Polishd instability. Do not "fix" it or switch stores because of it |
+| No `polishd_session` cookie | Proxy file missing/misnamed, or matcher excludes the path | Check `proxy.ts` (Next 16+) vs `middleware.ts` (Next 15) |
+| Dashboard content unreachable below the fold | Host `body` doesn't scroll | Fixed by default; if an ancestor sets `transform`/`filter`/`contain`, pass `shell: false` and use a route-group layout (docs/SETUP.md) |
+| Server actions 500 with an opaque digest | No dashboard page registered a policy | Expected if `app/polishd/page.tsx` was deleted — actions fail closed |
 | Database drivers in the client bundle | `@polishd/next/server` imported client-side | Import from `@polishd/next/client` |
 
 ## Entry points
@@ -258,5 +366,12 @@ a notice on the dashboard, and no impact on the host app.
 | `@polishd/next/client` | `initPolishd`, `PolishdMonitor` | browser |
 | `@polishd/next/server` | store, ingest, queries, `withPolishdSession` | Node only |
 | `@polishd/next/route` | `POST`, `createPolishdRoute` | Node only |
-| `@polishd/next/proxy` | `proxy`, `config`, `withPolishdSession`, `polishdMatcher` | Edge-safe |
-| `@polishd/next/dashboard` | `createPolishdPage`, `PolishdDashboard` | Node only |
+| `@polishd/next/proxy` | `proxy`, `config`, `withPolishdSession`, `polishdMatcher`, `composePolishd` | Edge-safe |
+| `@polishd/next/dashboard` | `createPolishdPage`, `polishdTokenAuth`, `PolishdDashboard` | Node only |
+
+## CLI
+
+| Command | Purpose |
+|---|---|
+| `npx @polishd/next init` | Scaffold. `--dry-run`, `--force`, `--js`, `--config` |
+| `npx @polishd/next doctor` | Check the install. `--url <origin>` adds live checks |

package/CHANGELOG.md

@@ -0,0 +1,128 @@
+# Changelog
+
+## 0.2.0
+
+Everything in this release came out of the first real third-party integration of
+the package, and most of it is the same underlying problem: Polishd assumed
+things about the host app that it never checked and could not see.
+
+### Upgrading from 0.1.x
+
+**Styling keeps working with no changes.** Your existing `@source
+".../@polishd/next/dist"` still compiles the dashboard's utilities exactly as
+it did, so upgrading will not leave you with an unstyled page. Verified by
+rendering the dashboard both ways: 491 elements, no visible differences.
+
+There is **one required change**, and it is about access, not styling.
+
+**Decide how the dashboard is protected in production.** It now refuses to serve
+unless you have chosen one:
+
+```bash
+POLISHD_DASHBOARD_TOKEN=$(openssl rand -hex 32)   # built-in gate, no code
+```
+
+or pass your own `authenticate` to `createPolishdPage()`, or opt out explicitly
+with `POLISHD_DASHBOARD_PUBLIC=true`. Development is unaffected.
+
+Then run `npx @polishd/next doctor`, which checks that and much else.
+
+#### Optional: move to the shipped stylesheet
+
+Recommended, but at your own pace. **Order matters** — add the import first, and
+only then remove the old wiring, so the dashboard is never unstyled in between:
+
+1. Add to `app/polishd/page.tsx`:
+   ```tsx
+   import "@polishd/next/dashboard.css";
+   ```
+2. Confirm the dashboard still looks right.
+3. *Then* delete the `@source ".../@polishd/next/dist"` line from your Tailwind
+   entry stylesheet (or the `content` glob in `tailwind.config.*`).
+
+Doing this drops Tailwind as a requirement for your app and stops your build
+compiling utilities only the dashboard uses. `doctor` reports which of the two
+setups it finds, and never calls a working 0.1.x setup broken.
+
+#### If you are on Next 15, check this
+
+0.1.0's CLI wrote `proxy.ts` regardless of the installed Next major, and **Next
+15 does not load that file**. If you are on Next 15 your proxy has never run:
+no session cookie, every beacon returning 200, and nothing captured, with no
+error anywhere to show for it. Rename it to `middleware.ts` and rename the
+exported function to `middleware`. `doctor` reports this explicitly.
+
+### Breaking
+
+- **The dashboard fails shut in production.** With no `POLISHD_DASHBOARD_TOKEN`,
+  no `authenticate` callback and no `POLISHD_DASHBOARD_PUBLIC=true`, production
+  renders a locked screen and every AI server action denies. Previously the
+  default was open, and the warning about it was suppressed in production —
+  exactly where it was worth acting on. The dashboard's settings can change the
+  configured model and API base URL, so an open one is arbitrary spend on the
+  owner's key, not merely an analytics leak.
+- **The dashboard renders in its own shell** (`position: fixed`, own background
+  and scroll container) rather than inheriting the host page. Pass
+  `shell: false` to `createPolishdPage()` for the old behaviour.
+
+### Added
+
+- **`npx @polishd/next doctor`** — checks the wiring that fails silently: the
+  proxy named and exported for the installed Next major, `config.matcher` as an
+  inline literal excluding `/api`, `runtime`/`dynamic` declared rather than
+  re-exported, the stylesheet import, access posture, Node version.
+  `--url <origin>` adds live checks that the cookie is minted and events store.
+- **Built-in token auth.** Setting `POLISHD_DASHBOARD_TOKEN` is the whole
+  integration for an app with no auth of its own — no import, no page edit. The
+  token is exchanged for an httpOnly, path-scoped cookie by a server action, so
+  it never appears in a URL, in history, in logs or in a `Referer` header. The
+  cookie holds an HMAC rather than the token, comparison is constant-time,
+  expiry is enforced server-side, and the unlock form is rate limited.
+  `polishdTokenAuth()` is exported for hosts that want to configure it.
+- **`dist/dashboard.css`** — the dashboard ships its own stylesheet, compiled at
+  publish time. Tailwind is no longer required in the host app.
+- **`composePolishd(handler, { matcher })`** — for apps that already have a
+  proxy. Declaring the handler's original scope re-applies it as an internal
+  guard, so widening `config.matcher` to the union doesn't silently start
+  running your handler on every request in the app.
+- **`authenticate` receives the request context** (`cookies`, `headers`), so
+  callbacks are ordinary functions of their inputs and testable without a live
+  request. Zero-argument callbacks keep working unchanged.
+- **`POLISHD_SESSION_COOKIE`** — read by both the proxy and the ingest route, so
+  renaming the cookie cannot go half-applied.
+
+### Fixed
+
+- **`--force` destroyed hand-written proxies.** Both the exists-guard and the
+  merge hint were skipped under the flag, so a user who passed it to regenerate
+  an unrelated file lost their real proxy wholesale. Generated files now carry a
+  sentinel; files the CLI did not author are never overwritten, with or without
+  `--force`, and its own files are backed up to `.bak` before regenerating.
+- **The CLI ignored the installed Next major**, always writing `proxy.ts`. On
+  Next 15 — a supported version — that file never runs: no session cookie, every
+  beacon still 200, nothing stored, no error anywhere. It now resolves the
+  installed version and picks the filename and exported function to match.
+- **The merge hint keyed off the wrong filename**, so the Next 16 collision —
+  the one that actually happens — got no guidance and only `--force` as a
+  remedy, which was the data-loss bug above.
+- **A missing session cookie is no longer silent.** Ingest records the rejection
+  in `polishd_meta`, the dashboard shows a banner naming the expected proxy
+  filename per Next major, and the client warns once in the dev console.
+- **`--dry-run` under-reported**, omitting the `.gitignore` change.
+- **`polishd.config.ts` was documented as being loaded automatically.** Nothing
+  imports it; it cannot be auto-loaded, because the three consumers run in three
+  runtimes and the Edge one has no filesystem. The docs now say what actually
+  has to happen.
+
+### Also
+
+- Node `>= 22.5.0` is checked by the CLI rather than left to a confusing
+  "cannot find module `node:sqlite`" at first request.
+- `bin/` is included in the published files. npm auto-includes the bin entry but
+  not the modules it imports, so the CLI would otherwise have shipped broken.
+- Docs carry a paste-ready prompt pointing a coding agent at `AGENTS.md`, in the
+  README, `docs/SETUP.md` and `polishd --help`.
+
+## 0.1.0
+
+Initial release.