@polishd/next 0.1.0 → 0.2.1-dev.0

package/bin/init.mjs

@@ -1,224 +1,251 @@
-#!/usr/bin/env node
 /**
  * `npx @polishd/next init` — scaffold the glue files a Next.js app needs to wire
  * up Polishd. Node builtins only; zero runtime dependencies.
  *
  * Flags:
- *   --force     overwrite existing files
+ *   --force     regenerate files this CLI wrote (backed up first). Files it did
+ *               not write are never overwritten, with or without this flag.
  *   --dry-run   print what would happen, write nothing
  *   --js        emit .js/.jsx instead of TypeScript
  *   --config    also write a starter polishd.config.ts
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync } from "node:fs";
+import { appendFileSync, copyFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 
-const args = new Set(process.argv.slice(2));
-const FORCE = args.has("--force");
-const DRY = args.has("--dry-run");
-const JS = args.has("--js");
-const WANT_CONFIG = args.has("--config");
-const cwd = process.cwd();
-
-const c = {
-  ok: (s) => `\x1b[32m${s}\x1b[0m`,
-  warn: (s) => `\x1b[33m${s}\x1b[0m`,
-  dim: (s) => `\x1b[2m${s}\x1b[0m`,
-  bold: (s) => `\x1b[1m${s}\x1b[0m`,
-};
-
-// ── Detect project layout ────────────────────────────────────────────────────
-const hasSrcApp = existsSync(join(cwd, "src", "app"));
-const hasRootApp = existsSync(join(cwd, "app"));
-if (!hasSrcApp && !hasRootApp) {
-  console.error(
-    c.warn("✗ Could not find an `app/` or `src/app/` directory.\n") +
-      "  Run this from the root of a Next.js App Router project.",
+import {
+  c,
+  detectLayout,
+  detectNextMajor,
+  nodeVersionOk,
+  proxyShape,
+  readText,
+} from "./shared.mjs";
+
+// Every generated file carries this marker. It is what lets `--force` tell "a
+// file I wrote and may regenerate" apart from "the user's own code", which is
+// the difference between a convenience flag and a data-loss bug.
+const SENTINEL = "@polishd/next init";
+const STAMP =
+  `// Generated by \`npx ${SENTINEL}\`. Edit freely — \`--force\` backs up\n` +
+  `// this file before regenerating it.\n`;
+
+export function runInit(argv, cwd) {
+  const args = new Set(argv);
+  const FORCE = args.has("--force");
+  const DRY = args.has("--dry-run");
+  const JS = args.has("--js");
+  const WANT_CONFIG = args.has("--config");
+  const codeExt = JS ? "js" : "ts";
+  const pageExt = JS ? "jsx" : "tsx";
+
+  // ── Detect project layout ──────────────────────────────────────────────────
+  const layout = detectLayout(cwd);
+  if (!layout.found) {
+    console.error(
+      c.warn("✗ Could not find an `app/` or `src/app/` directory.\n") +
+        "  Run this from the root of a Next.js App Router project.",
+    );
+    return 1;
+  }
+  const { base, appDir } = layout;
+  console.log(
+    c.ok(`✔ Detected Next.js App Router`) +
+      c.dim(` (${layout.hasSrcApp ? "src/ layout" : "root layout"})`),
   );
-  process.exit(1);
-}
-const base = hasSrcApp ? "src" : ""; // where proxy/instrumentation live
-const appDir = hasSrcApp ? join("src", "app") : "app";
-const ext = JS ? "tsx" : "tsx"; // page is always JSX
-const codeExt = JS ? "js" : "ts";
-const pageExt = JS ? "jsx" : "tsx";
-
-console.log(
-  c.ok(`✔ Detected Next.js App Router`) +
-    c.dim(` (${hasSrcApp ? "src/ layout" : "root layout"})`),
-);
-
-// ── File templates ───────────────────────────────────────────────────────────
-const files = [
-  {
-    path: join(base, `proxy.${codeExt}`),
-    merge: join(base, `middleware.${codeExt}`),
-    body:
-      (JS ? "" : `import type { NextRequest } from "next/server";\n`) +
-      `import { withPolishdSession } from "@polishd/next/proxy";\n\n` +
-      `export function proxy(request${JS ? "" : ": NextRequest"}) {\n` +
-      `  return withPolishdSession(request);\n` +
-      `}\n\n` +
-      `// Next statically parses config.matcher, so it must be an inline literal\n` +
-      `// here. Excluding all of /api is required — under Next 16 + Turbopack a\n` +
-      `// matcher that touches /api breaks the whole /api segment.\n` +
-      `export const config = {\n` +
-      `  matcher: ["/((?!api|_next/static|_next/image|favicon|assets).*)"],\n` +
-      `};\n`,
-  },
-  {
-    path: join(base, `instrumentation-client.${codeExt}`),
-    body: `import { initPolishd } from "@polishd/next/client";\n\ninitPolishd();\n`,
-  },
-  {
-    path: join(appDir, "api", "polishd", `route.${codeExt}`),
-    // runtime/dynamic must be declared here, not re-exported: Next statically
-    // parses route segment config and rejects `export { runtime } from ...`
-    // ("Next.js can't recognize the exported `runtime` field in route").
-    body:
-      `import { createPolishdRoute } from "@polishd/next/route";\n\n` +
-      `// node:sqlite / pg need the Node runtime — never the Edge runtime.\n` +
-      `export const runtime = "nodejs";\n` +
-      `// This route mutates per-request; it must never be statically cached.\n` +
-      `export const dynamic = "force-dynamic";\n\n` +
-      `export const POST = createPolishdRoute();\n`,
-  },
-  {
-    path: join(appDir, "polishd", `page.${pageExt}`),
-    body:
-      `import { createPolishdPage } from "@polishd/next/dashboard";\n\n` +
-      `// Next requires these to be declared inline in the page module.\n` +
-      `export const runtime = "nodejs";\n` +
-      `export const dynamic = "force-dynamic";\n\n` +
-      `// Unguarded by default. To protect it, pass an authenticate callback:\n` +
-      `//   export default createPolishdPage({ authenticate: isAuthenticated });\n` +
-      `export default createPolishdPage();\n`,
-  },
-];
-
-if (WANT_CONFIG) {
-  files.push({
-    path: `polishd.config.${codeExt}`,
-    body:
-      `import { definePolishdConfig } from "@polishd/next";\n\n` +
-      `export default definePolishdConfig({\n` +
-      `  // sampleRate: 1,\n` +
-      `  // rageClick: { count: 3, windowMs: 500 },\n` +
-      `});\n`,
-  });
-}
 
-// ── Write ────────────────────────────────────────────────────────────────────
-function write(file) {
-  const abs = join(cwd, file.path);
-  if (existsSync(abs) && !FORCE) {
-    console.log(c.warn(`⚠ ${file.path} exists`) + c.dim(" — skipped (use --force)"));
-    return;
-  }
-  // If a middleware.ts already exists for the proxy file, print a merge snippet.
-  if (file.merge && existsSync(join(cwd, file.merge)) && !FORCE) {
+  // The dev store uses `node:sqlite`, which landed in 22.5.0. Checked here
+  // rather than left to a confusing "cannot find module" at first request.
+  if (!nodeVersionOk()) {
     console.log(
-      c.warn(`⚠ ${file.merge} exists`) +
-        c.dim(" — add this to it (and keep the matcher):\n") +
-        `    import { withPolishdSession, polishdMatcher } from "@polishd/next/proxy";\n` +
-        `    // call withPolishdSession(request) in your handler;\n` +
-        `    // and merge polishdMatcher into your config.matcher`,
+      c.warn(`⚠ Node ${process.versions.node}`) +
+        c.dim(" — Polishd needs >= 22.5.0 (the dev store uses node:sqlite)."),
     );
-    return;
-  }
-  if (DRY) {
-    console.log(c.dim(`• would write ${file.path}`));
-    return;
   }
-  mkdirSync(dirname(abs), { recursive: true });
-  writeFileSync(abs, file.body);
-  console.log(c.ok(`✔ Created ${file.path}`));
-}
 
-for (const f of files) write(f);
+  // ── Detect the installed Next major ────────────────────────────────────────
+  const next = detectNextMajor(cwd);
+  const shape = proxyShape(next, base, codeExt);
 
-// ── .gitignore ───────────────────────────────────────────────────────────────
-const giPath = join(cwd, ".gitignore");
-if (!DRY) {
-  const gi = existsSync(giPath) ? readFileSync(giPath, "utf8") : "";
-  if (!gi.includes(".polishd")) {
-    appendFileSync(giPath, `${gi.endsWith("\n") || gi === "" ? "" : "\n"}.polishd/\n`);
-    console.log(c.ok("✔ Added .polishd/ to .gitignore"));
-  }
-}
-
-// ── Tailwind ─────────────────────────────────────────────────────────────────
-// The dashboard is styled entirely with Tailwind utility classes and ships no
-// stylesheet of its own, so Tailwind has to be told to scan the package's dist.
-// Neither version finds it by default: v4's automatic content detection skips
-// node_modules, and v3 only scans the globs it is given. Without this the
-// dashboard renders completely unstyled.
-const DIST_GLOB = "node_modules/@polishd/next/dist";
-
-function wireTailwind() {
-  const v3Config = ["tailwind.config.ts", "tailwind.config.js", "tailwind.config.mjs"]
-    .map((f) => join(cwd, f))
-    .find((f) => existsSync(f));
-
-  if (v3Config) {
+  if (next.major === null) {
+    // An unannounced guess here is exactly the silent failure this detection
+    // exists to prevent, so say so.
+    console.log(
+      c.warn("⚠ Could not determine the installed Next.js version") +
+        c.dim(`\n  Assuming 16+ and writing ${shape.path}.`) +
+        c.dim(`\n  On Next 15 rename it to ${shape.otherPath} and rename the exported`) +
+        c.dim(`\n  function to \`${shape.other}\` — Next 15 does not load ${shape.path}.`),
+    );
+  } else {
     console.log(
-      c.warn(`⚠ Tailwind v3 config detected`) +
-        c.dim(" — add this to its `content` array:\n") +
-        `    "./${DIST_GLOB}/**/*.js"`,
+      c.ok(`✔ Detected Next.js ${next.version}`) +
+        c.dim(` — using ${shape.path}`) +
+        (next.source === "package.json" ? c.dim(" (from package.json range)") : ""),
     );
-    return;
   }
 
-  // Tailwind v4: find the entry stylesheet that imports tailwind.
-  const cssCandidates = [
-    join("src", "app", "globals.css"),
-    join("app", "globals.css"),
-    join("src", "styles", "globals.css"),
-    join("styles", "globals.css"),
-    join("src", "app", "global.css"),
+  // ── File templates ─────────────────────────────────────────────────────────
+  const mergeHint =
+    c.dim(`  Add Polishd to your existing handler instead:\n`) +
+    `    import { composePolishd } from "@polishd/next/proxy";\n` +
+    `    export const ${shape.name} = composePolishd(myHandler, { matcher: "/your/scope" });\n` +
+    c.dim(`    // Then widen your inline config.matcher to the union of both.\n`) +
+    c.dim(`    // Declaring your original scope keeps your handler running only where\n`) +
+    c.dim(`    // it ran before, even though the matcher now feeds Polishd everything.\n`) +
+    c.dim(`    // See README → "Composing with an existing proxy".`);
+
+  const files = [
+    {
+      path: shape.path,
+      // The other spelling of this same file. A host on Next 16 that still has
+      // a middleware.ts (or vice versa) has a real collision worth flagging.
+      counterpart: shape.otherPath,
+      mergeHint,
+      body:
+        (JS ? "" : `import type { NextRequest } from "next/server";\n`) +
+        `import { withPolishdSession } from "@polishd/next/proxy";\n\n` +
+        `export function ${shape.name}(request${JS ? "" : ": NextRequest"}) {\n` +
+        `  return withPolishdSession(request);\n` +
+        `}\n\n` +
+        `// Next statically parses config.matcher, so it must be an inline literal\n` +
+        `// here. Excluding all of /api is required — under Next 16 + Turbopack a\n` +
+        `// matcher that touches /api breaks the whole /api segment.\n` +
+        `export const config = {\n` +
+        `  matcher: ["/((?!api|_next/static|_next/image|favicon|assets).*)"],\n` +
+        `};\n`,
+    },
+    {
+      path: join(base, `instrumentation-client.${codeExt}`),
+      body: `import { initPolishd } from "@polishd/next/client";\n\ninitPolishd();\n`,
+    },
+    {
+      path: join(appDir, "api", "polishd", `route.${codeExt}`),
+      // runtime/dynamic must be declared here, not re-exported: Next statically
+      // parses route segment config and rejects `export { runtime } from ...`
+      // ("Next.js can't recognize the exported `runtime` field in route").
+      body:
+        `import { createPolishdRoute } from "@polishd/next/route";\n\n` +
+        `// node:sqlite / pg need the Node runtime — never the Edge runtime.\n` +
+        `export const runtime = "nodejs";\n` +
+        `// This route mutates per-request; it must never be statically cached.\n` +
+        `export const dynamic = "force-dynamic";\n\n` +
+        `export const POST = createPolishdRoute();\n`,
+    },
+    {
+      path: join(appDir, "polishd", `page.${pageExt}`),
+      body:
+        `// The dashboard's own stylesheet. Self-contained and scoped to\n` +
+        `// .polishd-root, so it needs no Tailwind in this app and cannot\n` +
+        `// affect anything outside the dashboard.\n` +
+        `import "@polishd/next/dashboard.css";\n` +
+        `import { createPolishdPage } from "@polishd/next/dashboard";\n\n` +
+        `// Next requires these to be declared inline in the page module.\n` +
+        `export const runtime = "nodejs";\n` +
+        `export const dynamic = "force-dynamic";\n\n` +
+        `// In production the dashboard refuses to render until you either set\n` +
+        `// POLISHD_DASHBOARD_TOKEN, pass your own \`authenticate\`, or opt out\n` +
+        `// explicitly with POLISHD_DASHBOARD_PUBLIC=true. It can change your AI\n` +
+        `// settings and spend your model tokens, so it is not public by default.\n` +
+        `export default createPolishdPage();\n`,
+    },
   ];
-  for (const rel of cssCandidates) {
-    const abs = join(cwd, rel);
-    if (!existsSync(abs)) continue;
-    const css = readFileSync(abs, "utf8");
-    if (!/@import\s+["']tailwindcss["']/.test(css)) continue;
-    if (css.includes("@polishd/next")) {
-      console.log(c.dim(`• ${rel} already sources Polishd's styles`));
+
+  if (WANT_CONFIG) {
+    files.push({
+      path: `polishd.config.${codeExt}`,
+      body:
+        `import { definePolishdConfig } from "@polishd/next";\n\n` +
+        `// NOTE: nothing imports this for you. Pass it to initPolishd(),\n` +
+        `// createPolishdRoute() and your proxy explicitly, or the layers will\n` +
+        `// disagree. For the session cookie name prefer POLISHD_SESSION_COOKIE,\n` +
+        `// which every runtime can read.\n` +
+        `export default definePolishdConfig({\n` +
+        `  // sampleRate: 1,\n` +
+        `  // rageClick: { count: 3, windowMs: 500 },\n` +
+        `});\n`,
+    });
+  }
+
+  // ── Write ──────────────────────────────────────────────────────────────────
+  /** Did this CLI write the file currently at `abs`? */
+  const isOurs = (abs) => (readText(abs) ?? "").includes(SENTINEL);
+
+  function write(file) {
+    const abs = join(cwd, file.path);
+    const body = STAMP + file.body;
+
+    // A proxy under the *other* name is a collision even when our target is
+    // free: the host already has a handler, and Next loads only one of these.
+    const counterpartAbs = file.counterpart ? join(cwd, file.counterpart) : null;
+    if (counterpartAbs && existsSync(counterpartAbs) && !isOurs(counterpartAbs)) {
+      console.log(
+        c.warn(`⚠ ${file.counterpart} already exists`) +
+          c.dim(` — Next loads only one proxy module, and on this version it is ${file.path}.\n`) +
+          mergeHint,
+      );
+      return;
+    }
+
+    if (existsSync(abs)) {
+      // Never overwrite code this CLI did not author — not even with --force.
+      // Losing a hand-written proxy (auth redirects, i18n, rate limiting) to a
+      // flag someone passed for an unrelated skipped file is not a tradeoff.
+      if (!isOurs(abs)) {
+        console.log(
+          c.warn(`⚠ ${file.path} exists and was not written by Polishd`) +
+            c.dim(" — left untouched.\n") +
+            (file.mergeHint ?? c.dim(`  Rename or delete it to have a fresh copy scaffolded.`)),
+        );
+        return;
+      }
+      if (!FORCE) {
+        console.log(
+          c.dim(`• ${file.path} already scaffolded — skipped (use --force to regenerate)`),
+        );
+        return;
+      }
+      if (DRY) {
+        console.log(c.dim(`• would back up ${file.path} → ${file.path}.bak and regenerate`));
+        return;
+      }
+      copyFileSync(abs, `${abs}.bak`);
+      writeFileSync(abs, body);
+      console.log(
+        c.ok(`✔ Regenerated ${file.path}`) + c.dim(` (previous copy saved as ${file.path}.bak)`),
+      );
       return;
     }
-    // `@source` is resolved relative to the stylesheet, so walk back up to root.
-    const depth = dirname(rel).split(/[\\/]/).filter(Boolean).length;
-    const source = `${"../".repeat(depth)}${DIST_GLOB}`;
+
     if (DRY) {
-      console.log(c.dim(`• would add @source "${source}" to ${rel}`));
+      console.log(c.dim(`• would write ${file.path}`));
       return;
     }
-    writeFileSync(
-      abs,
-      css.replace(
-        /(@import\s+["']tailwindcss["'];?)/,
-        `$1\n/* Generate the Polishd dashboard's utility classes (Tailwind skips node_modules). */\n@source "${source}";`,
-      ),
-    );
-    console.log(c.ok(`✔ Added @source "${source}" to ${rel}`));
-    return;
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, body);
+    console.log(c.ok(`✔ Created ${file.path}`));
   }
 
-  console.log(
-    c.warn("⚠ No Tailwind entry stylesheet found") +
-      c.dim(" — the dashboard needs Tailwind to render styled.\n") +
-      c.dim("  v4: add to your CSS →  ") +
-      `@source "<path-to>/${DIST_GLOB}";\n` +
-      c.dim("  v3: add to content →  ") +
-      `"./${DIST_GLOB}/**/*.js"`,
-  );
-}
+  for (const f of files) write(f);
 
-wireTailwind();
+  // ── .gitignore ─────────────────────────────────────────────────────────────
+  const giPath = join(cwd, ".gitignore");
+  const gi = readText(giPath) ?? "";
+  if (!gi.includes(".polishd")) {
+    if (DRY) {
+      console.log(c.dim("• would add .polishd/ to .gitignore"));
+    } else {
+      appendFileSync(giPath, `${gi.endsWith("\n") || gi === "" ? "" : "\n"}.polishd/\n`);
+      console.log(c.ok("✔ Added .polishd/ to .gitignore"));
+    }
+  }
 
-// ── Next steps ───────────────────────────────────────────────────────────────
-console.log(`
+  console.log(`
 ${c.bold("Next steps:")}
   1. Local dev needs nothing — events write to ${c.dim(".polishd/analytics.db")} (SQLite).
   2. For production, set ${c.dim("POLISHD_DATABASE_URL")} (pooled Postgres). See DATABASE.md.
-  3. Visit ${c.bold("/polishd")} to see the dashboard.
+  3. Set ${c.dim("POLISHD_DASHBOARD_TOKEN")} to protect ${c.bold("/polishd")} in production.
+  4. Visit ${c.bold("/polishd")} to see the dashboard.
+  5. Check the wiring with ${c.bold("npx @polishd/next doctor")}.
 ${DRY ? c.warn("\n(dry run — nothing was written)") : ""}`);
+
+  return 0;
+}

package/bin/polishd.mjs

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+/**
+ * The `polishd` CLI.
+ *
+ *   npx @polishd/next init     scaffold the glue files
+ *   npx @polishd/next doctor   check that an install is actually wired up
+ *
+ * `init` is the default so the historical `npx polishd` keeps working.
+ * Node builtins only; zero runtime dependencies.
+ */
+import { c } from "./shared.mjs";
+
+const argv = process.argv.slice(2);
+const cwd = process.cwd();
+const command = argv[0] && !argv[0].startsWith("-") ? argv[0] : "init";
+const rest = argv.filter((a) => a !== command);
+
+if (argv.includes("--help") || argv.includes("-h")) {
+  console.log(`
+${c.bold("polishd")} — drop-in product analytics for Next.js
+
+${c.bold("Usage")}
+  npx @polishd/next init [options]      scaffold the files a Next.js app needs
+  npx @polishd/next doctor [options]    check an existing install
+
+${c.bold("init options")}
+  --force        regenerate files this CLI wrote (backed up to .bak first).
+                 Files it did not write are never overwritten.
+  --dry-run      print what would happen, write nothing
+  --js           emit .js/.jsx instead of TypeScript
+  --config       also write a starter polishd.config.ts
+
+${c.bold("doctor options")}
+  --url <origin> also run live checks against a running server
+  --js           inspect .js/.jsx files instead of TypeScript
+
+${c.bold("Installing with a coding agent")}
+  Polishd ships a machine-readable install procedure. Paste this to Claude Code,
+  Cursor, Copilot, or any other coding agent and let it do the whole install:
+
+${c.dim("  ───────────────────────────────────────────────────────────────────────")}
+  Install @polishd/next into this Next.js app.
+
+  Follow the procedure in AGENTS.md from the package exactly — after
+  installing, read node_modules/@polishd/next/AGENTS.md. If the package
+  isn't installed yet, read it at
+  https://github.com/muskanvaswan/polishd/blob/main/AGENTS.md
+
+  Work through its phases in order and do not skip Phase 7 (verification).
+  Several of its constraints fail silently at runtime rather than at build
+  time, so a passing build does not mean the install worked.
+
+  Finish by running \`npx @polishd/next doctor\` and fixing everything it
+  reports.
+${c.dim("  ───────────────────────────────────────────────────────────────────────")}
+
+${c.bold("Docs")}
+  AGENTS.md     the install procedure (agent-oriented, and the most precise)
+  README.md     overview, protecting the dashboard, configuration
+  docs/SETUP.md full walkthrough, every variant, troubleshooting
+  DATABASE.md   production database setup, schema, retention
+`);
+  process.exit(0);
+}
+
+let code = 0;
+switch (command) {
+  case "init": {
+    const { runInit } = await import("./init.mjs");
+    code = runInit(rest, cwd);
+    break;
+  }
+  case "doctor": {
+    const { runDoctor } = await import("./doctor.mjs");
+    code = await runDoctor(rest, cwd);
+    break;
+  }
+  default:
+    console.error(
+      c.err(`✗ Unknown command "${command}"`) + c.dim("\n  Try `init` or `doctor`, or --help."),
+    );
+    code = 1;
+}
+
+process.exit(code);

package/bin/shared.mjs

@@ -0,0 +1,114 @@
+/**
+ * Shared helpers for the `polishd` CLI. Node builtins only.
+ *
+ * `init` and `doctor` have to agree exactly about where things live and which
+ * Next major is installed — a doctor that inspected different paths than init
+ * wrote would be worse than no doctor at all.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+
+export const c = {
+  ok: (s) => `\x1b[32m${s}\x1b[0m`,
+  warn: (s) => `\x1b[33m${s}\x1b[0m`,
+  err: (s) => `\x1b[31m${s}\x1b[0m`,
+  dim: (s) => `\x1b[2m${s}\x1b[0m`,
+  bold: (s) => `\x1b[1m${s}\x1b[0m`,
+};
+
+export function readJSON(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export function readText(path) {
+  try {
+    return readFileSync(path, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+/** Where the app's code lives: `src/app` layout or root `app`. */
+export function detectLayout(cwd) {
+  const hasSrcApp = existsSync(join(cwd, "src", "app"));
+  const hasRootApp = existsSync(join(cwd, "app"));
+  return {
+    found: hasSrcApp || hasRootApp,
+    hasSrcApp,
+    base: hasSrcApp ? "src" : "",
+    appDir: hasSrcApp ? join("src", "app") : "app",
+  };
+}
+
+/**
+ * Which Next major is actually installed.
+ *
+ * Load-bearing: 16+ loads `proxy.ts`, 15 loads `middleware.ts`, and writing
+ * the wrong one means the file never runs — no session cookie, every beacon
+ * still 200, nothing stored, and no error to follow.
+ */
+export function detectNextMajor(cwd) {
+  // Prefer the resolved install. A declared range ("^16", "latest", "canary")
+  // does not tell you what is actually in node_modules.
+  const direct = readJSON(join(cwd, "node_modules", "next", "package.json"));
+  if (direct?.version) {
+    const major = Number.parseInt(direct.version, 10);
+    if (Number.isFinite(major)) {
+      return { major, version: direct.version, source: "node_modules" };
+    }
+  }
+  // Hoisted / pnpm / workspace installs won't be at that path.
+  try {
+    const require = createRequire(join(cwd, "package.json"));
+    const resolved = readJSON(require.resolve("next/package.json"));
+    if (resolved?.version) {
+      const major = Number.parseInt(resolved.version, 10);
+      if (Number.isFinite(major)) {
+        return { major, version: resolved.version, source: "node_modules" };
+      }
+    }
+  } catch {
+    // `next` not installed yet, or its exports map hides package.json.
+  }
+  // Last resort: the declared range. Better than guessing blind.
+  const pkg = readJSON(join(cwd, "package.json"));
+  const range =
+    pkg?.dependencies?.next ?? pkg?.devDependencies?.next ?? pkg?.peerDependencies?.next;
+  if (typeof range === "string") {
+    const major = Number.parseInt(range.replace(/^[^\d]*/, ""), 10);
+    if (Number.isFinite(major)) return { major, version: range, source: "package.json" };
+  }
+  return { major: null, version: null, source: null };
+}
+
+/**
+ * The proxy file this app should have, given its Next major.
+ * An undetermined version is treated as modern, which is also what init writes.
+ */
+export function proxyShape(next, base, codeExt) {
+  const useMiddleware = next.major !== null && next.major <= 15;
+  const name = useMiddleware ? "middleware" : "proxy";
+  const other = useMiddleware ? "proxy" : "middleware";
+  return {
+    useMiddleware,
+    name,
+    other,
+    path: join(base, `${name}.${codeExt}`),
+    otherPath: join(base, `${other}.${codeExt}`),
+  };
+}
+
+export const MIN_NODE = { major: 22, minor: 5 };
+
+export function nodeVersionOk() {
+  const [major, minor] = process.versions.node.split(".").map(Number);
+  return major > MIN_NODE.major || (major === MIN_NODE.major && minor >= MIN_NODE.minor);
+}
+
+/** The dist path Tailwind must be told to scan (v4 `@source`, v3 `content`). */
+export const DIST_GLOB = "node_modules/@polishd/next/dist";