create-ailk 0.8.0 → 0.9.0

package/dist/legacy-nav-renderers.js

@@ -0,0 +1,545 @@
+/**
+ * Frozen, published-generator `renderNavConfig` bodies (#6908 D2) — one per
+ * era a create-ailk release ever shipped (E1–E4, `docs/specs/6908-add-module-
+ * treats-every-pre-spec.md` § 1.2). `surfaces.ts`'s own `renderNavConfig`
+ * self-hashes its output (D1) so a nav it wrote can always prove itself; a
+ * nav written before the stamp existed carries none, and this module is the
+ * only way `add-module` can still recognize it as unedited.
+ *
+ * Each `render` below is copied VERBATIM from the named tag's own
+ * `packages/create-ailk/src/surfaces.ts`, at the named commit, with exactly
+ * two changes from the original:
+ *
+ *   - `GATEABLE_SURFACES` is replaced by a frozen `{ id, navLabelKey }` table
+ *     of that tag's own entries, in that tag's own order (the era's own
+ *     `<era>_SURFACES` constant below) — so a later change to today's
+ *     `GATEABLE_SURFACES` can never move a byte of a legacy render.
+ *   - the `@working-theory/ui` import line stays fragment-assembled, exactly
+ *     as the original does, so THIS file never contains the literal import
+ *     string either (`tools/lint-architecture.ts` matches source text; see
+ *     the comment on each `navItemImport` below).
+ *
+ * The list is CLOSED (D2): after D1 ships, every published generator is
+ * unstamped only up to 0.8.0 (E4), so a future generator change never needs a
+ * fifth entry. Fixtures produced by each tag's own code (never by this
+ * vendored copy) pin these bodies exactly — see
+ * `__tests__/fixtures/legacy-nav/index.json`.
+ */
+// ---------------------------------------------------------------------------
+// E1 — 0.1.1, 0.2.0, 0.3.0, 0.4.0 (commit 52e0685f3bff54832a76b5e0ec737c2f39b9d960)
+// ---------------------------------------------------------------------------
+const E1_SURFACES = [
+    { id: "blog", navLabelKey: "blog" },
+    { id: "careers" },
+    { id: "case-studies" },
+    { id: "clients" },
+    { id: "courses" },
+    { id: "dev" },
+    { id: "docs", navLabelKey: "docs" },
+    { id: "downloads" },
+    { id: "events" },
+    { id: "flows" },
+    { id: "how-to" },
+    { id: "integrations" },
+    { id: "launch-service" },
+    { id: "partners" },
+    { id: "products" },
+    { id: "projects" },
+    { id: "resources" },
+    { id: "schedule", navLabelKey: "schedule" },
+    { id: "services" },
+    { id: "software" },
+    { id: "tech-articles" },
+    { id: "testimonials" },
+    { id: "use-cases" },
+    { id: "whitepapers" },
+];
+function renderNavConfigE1(enabled) {
+    const on = new Set(enabled);
+    const linked = E1_SURFACES.filter((s) => s.navLabelKey !== undefined && on.has(s.id));
+    const entries = [
+        '  { labelKey: "home", path: "/" },',
+        ...linked.map((s) => `  { labelKey: "${s.navLabelKey}", path: "/${s.id}" },`),
+    ];
+    // Fragment-assembled so this vendored copy never contains the literal
+    // import string either — see the module comment above.
+    const navItemImport = [
+        "import type { NavItem } ",
+        "from ",
+        '"@working-theory/ui";',
+    ].join("");
+    return `// nav-config.ts — site-nav registry.
+//
+// GENERATED by create-ailk from the declared route surfaces. Every entry here
+// points at a route this site actually carries — the nav is regenerated with
+// the surface set so it can never link a page that was not scaffolded.
+//
+// Adding a link: scaffold the page (the \`scaffold-page\` skill), then add an
+// entry below with a \`labelKey\` that exists in the \`nav\` namespace of
+// \`apps/web/messages/<locale>.json\`. Paths are locale-agnostic — Nav prefixes
+// them with the active locale at render.
+${navItemImport}
+
+export const navItems: NavItem[] = [
+${entries.join("\n")}
+];
+`;
+}
+// ---------------------------------------------------------------------------
+// E2 — 0.5.0, 0.6.0, 0.6.1 (commit b0a69cefecf491412aa7e6f1d64464a91620126d)
+// ---------------------------------------------------------------------------
+const E2_SURFACES = [
+    { id: "blog", navLabelKey: "blog" },
+    { id: "careers" },
+    { id: "case-studies" },
+    { id: "clients" },
+    { id: "courses" },
+    { id: "dev" },
+    { id: "docs", navLabelKey: "docs" },
+    { id: "downloads" },
+    { id: "events" },
+    { id: "flows" },
+    { id: "how-to" },
+    { id: "integrations" },
+    { id: "launch-service" },
+    { id: "meet", navLabelKey: "schedule" },
+    { id: "partners" },
+    { id: "pricing" },
+    { id: "privacy" },
+    { id: "products" },
+    { id: "projects" },
+    { id: "resources" },
+    { id: "services" },
+    { id: "software" },
+    { id: "tech-articles" },
+    { id: "terms" },
+    { id: "testimonials" },
+    { id: "use-cases" },
+    { id: "whitepapers" },
+];
+function renderNavConfigE2(enabled) {
+    const on = new Set(enabled);
+    const linked = E2_SURFACES.filter((s) => s.navLabelKey !== undefined && on.has(s.id));
+    const entries = [
+        "  {",
+        '    labelKey: "product",',
+        "    flyout: {",
+        '      presentation: "list",',
+        '      width: "trigger",',
+        "      features: [",
+        '        { labelKey: "howItWorks", descKey: "howItWorksDesc", icon: Layers, path: "/how-it-works" },',
+        '        { labelKey: "features", descKey: "featuresDesc", icon: Sparkles, path: "/features" },',
+        '        { labelKey: "faq", descKey: "faqDesc", icon: HelpCircle, path: "/faq" },',
+        "      ],",
+        '      actions: [{ labelKey: "docs", icon: BookOpen, path: "/how-it-works" }],',
+        "    },",
+        "  },",
+        '  { labelKey: "howItWorks", path: "/how-it-works" },',
+        ...(on.has("pricing") ? ['  { labelKey: "pricing", path: "/pricing" },'] : []),
+        '  { labelKey: "about", path: "/about" },',
+        ...linked.map((s) => `  { labelKey: "${s.navLabelKey}", path: "/${s.id}" },`),
+    ];
+    const navItemImport = [
+        "import type { NavItem } ",
+        "from ",
+        '"@working-theory/ui";',
+    ].join("");
+    return `// nav-config.ts — site-nav registry.
+//
+// GENERATED by create-ailk from the declared route surfaces. Every entry here
+// points at a route this site actually carries — the nav is regenerated with
+// the surface set so it can never link a page that was not scaffolded.
+//
+// Adding a link: scaffold the page (the \`scaffold-page\` skill), then add an
+// entry below with a \`labelKey\` that exists in the \`nav\` namespace of
+// \`apps/web/messages/<locale>.json\`. Paths are locale-agnostic — Nav prefixes
+// them with the active locale at render.
+${navItemImport}
+import { BookOpen, HelpCircle, Layers, Sparkles } from "lucide-react";
+
+export const navItems: NavItem[] = [
+${entries.join("\n")}
+];
+`;
+}
+// ---------------------------------------------------------------------------
+// E3 — 0.7.0 (commit cac431ba50c4b0ee5130b5bc206196240744be18)
+// ---------------------------------------------------------------------------
+const E3_SURFACES = [
+    { id: "blog", navLabelKey: "blog" },
+    { id: "book-a-call" },
+    { id: "careers" },
+    { id: "case-studies" },
+    { id: "clients" },
+    { id: "courses" },
+    { id: "dev" },
+    { id: "docs", navLabelKey: "docs" },
+    { id: "downloads" },
+    { id: "events" },
+    { id: "flows" },
+    { id: "glossary" },
+    { id: "how-to" },
+    { id: "integrations" },
+    { id: "launch-service" },
+    { id: "meet", navLabelKey: "schedule" },
+    { id: "newsletter" },
+    { id: "partners" },
+    { id: "pricing" },
+    { id: "privacy" },
+    { id: "products" },
+    { id: "projects" },
+    { id: "resources" },
+    { id: "services" },
+    { id: "tech-articles" },
+    { id: "terms" },
+    { id: "testimonials" },
+    { id: "use-cases" },
+    { id: "whitepapers" },
+];
+function renderNavConfigE3(enabled) {
+    const on = new Set(enabled);
+    // `blog` is linked unconditionally below (operator ruling 2026-09-23), so
+    // it is excluded here; `use-cases` is the Free roster's own page (a
+    // module-less surface the roster enables, like `pricing`), linked in its
+    // fixed positions below rather than appended.
+    const linked = E3_SURFACES.filter((s) => s.navLabelKey !== undefined &&
+        on.has(s.id) &&
+        s.id !== "blog" &&
+        s.id !== "use-cases");
+    const useCases = on.has("use-cases");
+    const entries = [
+        "  {",
+        '    labelKey: "product",',
+        "    flyout: {",
+        // SOFT_LOCK_OK: #6508 — width "panel" (D4/D5): a fixed 640px, two-column
+        // grid, replacing the "list"/"trigger" one-column menu. `presentation` is
+        // omitted — it defaults to "grid" (D5). The `docs` action is dropped (it
+        // duplicated the first feature's /how-it-works destination, § 1.4).
+        '      width: "panel",',
+        "      features: [",
+        ...(useCases
+            ? ['        { labelKey: "useCases", descKey: "useCasesDesc", icon: Layers, path: "/use-cases" },']
+            : []),
+        '        { labelKey: "features", descKey: "featuresDesc", icon: Sparkles, path: "/software/product" },',
+        '        { labelKey: "faq", descKey: "faqDesc", icon: HelpCircle, path: "/faq" },',
+        "      ],",
+        "      actions: [],",
+        "    },",
+        "  },",
+        // Operator ruling 2026-09-23: Product · Use cases · Blog · Pricing · About.
+        // `/blog` is always linked — the `blog` surface serves the real route, and
+        // with it off the `[slug]` route serves the overlay's module page.
+        ...(useCases ? ['  { labelKey: "useCases", path: "/use-cases" },'] : []),
+        '  { labelKey: "blog", path: "/blog" },',
+        ...(on.has("pricing") ? ['  { labelKey: "pricing", path: "/pricing" },'] : []),
+        '  { labelKey: "about", path: "/about" },',
+        ...linked.map((s) => `  { labelKey: "${s.navLabelKey}", path: "/${s.id}" },`),
+    ];
+    // The footer's column groups (operator ruling 2026-09-23, replacing #6468's
+    // Product/Company pair): Site pages, Features, Resources. Pricing rides the
+    // same `pricing` gate as the header item; `/blog` is always linked (above).
+    // The product links point at the product's own page, `/software/product`
+    // (#6658 D3): `software` is core, so they stay unconditional. Book a call,
+    // Glossary and Newsletter (#6658 D8) each ride their own surface's gate.
+    const footerEntries = [
+        "  {",
+        '    headingKey: "footerSitePagesHeading",',
+        "    items: [",
+        '      { labelKey: "features", path: "/software/product" },',
+        ...(on.has("pricing")
+            ? ['      { labelKey: "pricing", path: "/pricing" },']
+            : []),
+        ...(useCases ? ['      { labelKey: "useCases", path: "/use-cases" },'] : []),
+        '      { labelKey: "about", path: "/about" },',
+        '      { labelKey: "contact", path: "/contact" },',
+        ...(on.has("book-a-call")
+            ? ['      { labelKey: "bookACall", path: "/book-a-call" },']
+            : []),
+        "    ],",
+        "  },",
+        "  {",
+        '    headingKey: "footerFeaturesHeading",',
+        "    items: [",
+        '      { labelKey: "feature1", path: "/software/product" },',
+        '      { labelKey: "feature2", path: "/software/product" },',
+        '      { labelKey: "feature3", path: "/software/product" },',
+        '      { labelKey: "feature4", path: "/software/product" },',
+        '      { labelKey: "feature5", path: "/software/product" },',
+        '      { labelKey: "allFeatures", path: "/software/product" },',
+        "    ],",
+        "  },",
+        "  {",
+        '    headingKey: "footerResourcesHeading",',
+        "    items: [",
+        '      { labelKey: "blog", path: "/blog" },',
+        ...(on.has("glossary")
+            ? ['      { labelKey: "glossary", path: "/glossary" },']
+            : []),
+        ...(on.has("newsletter")
+            ? ['      { labelKey: "newsletter", path: "/newsletter" },']
+            : []),
+        '      { labelKey: "faq", path: "/faq" },',
+        "    ],",
+        "  },",
+    ];
+    const navItemImport = [
+        "import type { NavItem } ",
+        "from ",
+        '"@working-theory/ui";',
+    ].join("");
+    return `// nav-config.ts — site-nav registry.
+//
+// GENERATED by create-ailk from the declared route surfaces. Every entry here
+// points at a route this site actually carries — the nav is regenerated with
+// the surface set so it can never link a page that was not scaffolded.
+//
+// Adding a link: scaffold the page (the \`add-page\` skill), then add an
+// entry below with a \`labelKey\` that exists in the \`nav\` namespace of
+// \`apps/web/messages/<locale>.json\`. Paths are locale-agnostic — Nav prefixes
+// them with the active locale at render.
+${navItemImport}
+import { HelpCircle, Layers, Sparkles } from "lucide-react";
+
+export const navItems: NavItem[] = [
+${entries.join("\n")}
+];
+
+// Footer column groups. Keys only — the layout resolves each \`headingKey\`
+// and \`labelKey\` through the same \`nav\` labels as the header.
+export interface FooterColumnConfig {
+  headingKey: string;
+  items: { labelKey: string; path: string }[];
+}
+
+export const footerColumns: FooterColumnConfig[] = [
+${footerEntries.join("\n")}
+];
+`;
+}
+// ---------------------------------------------------------------------------
+// E4 — 0.8.0 (commit 060c02b8190090d7495d42e220836141d0549809)
+// ---------------------------------------------------------------------------
+const E4_SURFACES = [
+    { id: "blog", navLabelKey: "blog" },
+    { id: "book-a-call" },
+    { id: "careers" },
+    { id: "case-studies" },
+    { id: "clients" },
+    { id: "courses" },
+    { id: "dev" },
+    { id: "docs", navLabelKey: "docs" },
+    { id: "downloads" },
+    { id: "events" },
+    { id: "features" },
+    { id: "flows" },
+    { id: "glossary" },
+    { id: "how-to" },
+    { id: "integrations" },
+    { id: "launch-service" },
+    { id: "meet", navLabelKey: "schedule" },
+    { id: "newsletter" },
+    { id: "partners" },
+    { id: "portfolio" },
+    { id: "pricing" },
+    { id: "privacy" },
+    { id: "products" },
+    { id: "projects" },
+    { id: "resources" },
+    { id: "services" },
+    { id: "software" },
+    { id: "tech-articles" },
+    { id: "terms" },
+    { id: "testimonials" },
+    { id: "use-cases" },
+    { id: "whitepapers" },
+];
+function renderNavConfigE4(enabled) {
+    const on = new Set(enabled);
+    // `blog` is linked unconditionally below (operator ruling 2026-09-23), so
+    // it is excluded here; `use-cases` is the Free roster's own page (a
+    // module-less surface the roster enables, like `pricing`), linked in its
+    // fixed positions below rather than appended.
+    const linked = E4_SURFACES.filter((s) => s.navLabelKey !== undefined &&
+        on.has(s.id) &&
+        s.id !== "blog" &&
+        s.id !== "use-cases");
+    const useCases = on.has("use-cases");
+    const features = on.has("features");
+    // #6721 (operator ruling 2026-09-25): the Product flyout is two columns —
+    // Features and Use Cases — each a heading over three label-only links. The
+    // `groups` render the desktop panel; `features` carries the same links for
+    // the mobile disclosure and the active-path match. "Use cases" left the top
+    // nav (it lives in the flyout and its own footer column).
+    const featureLinks = features
+        ? [
+            '        { labelKey: "feature1", path: "/features/feature-1" },',
+            '        { labelKey: "feature2", path: "/features/feature-2" },',
+            '        { labelKey: "feature3", path: "/features/feature-3" },',
+        ]
+        : [];
+    const useCaseLinks = useCases
+        ? [
+            '        { labelKey: "useCase1", path: "/use-cases/persona-1" },',
+            '        { labelKey: "useCase2", path: "/use-cases/persona-2" },',
+            '        { labelKey: "useCase3", path: "/use-cases/persona-3" },',
+        ]
+        : [];
+    const indent = (line) => `    ${line}`;
+    const group = (headingKey, links) => links.length === 0
+        ? []
+        : [
+            "        {",
+            `          headingKey: "${headingKey}",`,
+            "          items: [",
+            ...links.map(indent),
+            "          ],",
+            "        },",
+        ];
+    const entries = [
+        "  {",
+        '    labelKey: "product",',
+        "    flyout: {",
+        // SOFT_LOCK_OK: #6508 — width "panel" (D4/D5): a fixed 640px panel.
+        '      width: "panel",',
+        "      features: [",
+        ...featureLinks,
+        ...useCaseLinks,
+        "      ],",
+        "      groups: [",
+        ...group("flyoutFeaturesHeading", featureLinks),
+        ...group("flyoutUseCasesHeading", useCaseLinks),
+        "      ],",
+        "      actions: [],",
+        "    },",
+        "  },",
+        // Operator ruling 2026-09-25: Product · Blog · Pricing · About.
+        // `/blog` is always linked — the `blog` surface serves the real route, and
+        // with it off the `[slug]` route serves the overlay's module page.
+        '  { labelKey: "blog", path: "/blog" },',
+        ...(on.has("pricing") ? ['  { labelKey: "pricing", path: "/pricing" },'] : []),
+        '  { labelKey: "about", path: "/about" },',
+        ...linked.map((s) => `  { labelKey: "${s.navLabelKey}", path: "/${s.id}" },`),
+    ];
+    // The footer's column groups (operator rulings 2026-09-23 + 2026-09-25):
+    // Site pages, Features, Use Cases, Resources. Pricing rides the same
+    // `pricing` gate as the header item; `/blog` is always linked (above). The
+    // Features column links the three feature pages and the /features hub; the
+    // Use Cases column the three use cases and the /use-cases hub — each rides
+    // its surface's gate. Book a call, Glossary and Newsletter (#6658 D8) each
+    // ride their own surface's gate.
+    const footerEntries = [
+        "  {",
+        '    headingKey: "footerSitePagesHeading",',
+        "    items: [",
+        ...(features ? ['      { labelKey: "features", path: "/features" },'] : []),
+        ...(on.has("pricing")
+            ? ['      { labelKey: "pricing", path: "/pricing" },']
+            : []),
+        '      { labelKey: "about", path: "/about" },',
+        '      { labelKey: "contact", path: "/contact" },',
+        ...(on.has("book-a-call")
+            ? ['      { labelKey: "bookACall", path: "/book-a-call" },']
+            : []),
+        "    ],",
+        "  },",
+        ...(features
+            ? [
+                "  {",
+                '    headingKey: "footerFeaturesHeading",',
+                "    items: [",
+                ...featureLinks.map((l) => l.slice(2)),
+                '      { labelKey: "allFeatures", path: "/features" },',
+                "    ],",
+                "  },",
+            ]
+            : []),
+        ...(useCases
+            ? [
+                "  {",
+                '    headingKey: "footerUseCasesHeading",',
+                "    items: [",
+                ...useCaseLinks.map((l) => l.slice(2)),
+                '      { labelKey: "allUseCases", path: "/use-cases" },',
+                "    ],",
+                "  },",
+            ]
+            : []),
+        "  {",
+        '    headingKey: "footerResourcesHeading",',
+        "    items: [",
+        '      { labelKey: "blog", path: "/blog" },',
+        ...(on.has("glossary")
+            ? ['      { labelKey: "glossary", path: "/glossary" },']
+            : []),
+        ...(on.has("newsletter")
+            ? ['      { labelKey: "newsletter", path: "/newsletter" },']
+            : []),
+        '      { labelKey: "faq", path: "/faq" },',
+        "    ],",
+        "  },",
+    ];
+    const navItemImport = [
+        "import type { NavItem } ",
+        "from ",
+        '"@working-theory/ui";',
+    ].join("");
+    return `// nav-config.ts — site-nav registry.
+//
+// GENERATED by create-ailk from the declared route surfaces. Every entry here
+// points at a route this site actually carries — the nav is regenerated with
+// the surface set so it can never link a page that was not scaffolded.
+//
+// Adding a link: scaffold the page (the \`add-page\` skill), then add an
+// entry below with a \`labelKey\` that exists in the \`nav\` namespace of
+// \`apps/web/messages/<locale>.json\`. Paths are locale-agnostic — Nav prefixes
+// them with the active locale at render.
+${navItemImport}
+
+export const navItems: NavItem[] = [
+${entries.join("\n")}
+];
+
+// Footer column groups. Keys only — the layout resolves each \`headingKey\`
+// and \`labelKey\` through the same \`nav\` labels as the header.
+export interface FooterColumnConfig {
+  headingKey: string;
+  items: { labelKey: string; path: string }[];
+}
+
+export const footerColumns: FooterColumnConfig[] = [
+${footerEntries.join("\n")}
+];
+`;
+}
+/**
+ * The closed set of published, pre-stamp `renderNavConfig` bodies (D2).
+ * `add-module`'s `isUneditedNav` tries these, in order, against an unstamped
+ * nav (`surfaces.ts` `readNavConfigStamp` returning `"absent"`) before giving
+ * up and reporting it as customer-edited.
+ */
+export const LEGACY_NAV_RENDERERS = [
+    {
+        era: "E1",
+        tags: ["0.1.1", "0.2.0", "0.3.0", "0.4.0"],
+        commit: "52e0685f3bff54832a76b5e0ec737c2f39b9d960",
+        render: renderNavConfigE1,
+    },
+    {
+        era: "E2",
+        tags: ["0.5.0", "0.6.0", "0.6.1"],
+        commit: "b0a69cefecf491412aa7e6f1d64464a91620126d",
+        render: renderNavConfigE2,
+    },
+    {
+        era: "E3",
+        tags: ["0.7.0"],
+        commit: "cac431ba50c4b0ee5130b5bc206196240744be18",
+        render: renderNavConfigE3,
+    },
+    {
+        era: "E4",
+        tags: ["0.8.0"],
+        commit: "060c02b8190090d7495d42e220836141d0549809",
+        render: renderNavConfigE4,
+    },
+];

package/dist/lib/auth-secret-file.d.ts

@@ -0,0 +1,19 @@
+export declare const AUTH_SECRET_ENV_VAR = "BETTER_AUTH_SECRET";
+/** The files the writer owns, web first. */
+export declare const AUTH_SECRET_ENV_FILES: readonly [string, string];
+/**
+ * `.gitignore` lines that already ignore `apps/<app>/.env.local`. An explicit
+ * set, never a glob evaluation; `/.env.local` is absent because, anchored to
+ * the root, it does not cover `apps/web/.env.local`.
+ */
+export declare const ENV_LOCAL_IGNORE_LINES: ReadonlySet<string>;
+export interface WriteAuthSecretOptions {
+    /** Injectable for tests; defaults to `node:crypto` `randomBytes`. */
+    randomBytes?: (size: number) => Buffer;
+}
+/**
+ * Give the scaffold at `dir` a `BETTER_AUTH_SECRET` (F1–F4 of the #6107
+ * spec). Generates at most one value, and only when no app already has one.
+ * Idempotent — a second call changes no byte.
+ */
+export declare function writeAuthSecretFile(dir: string, opts?: WriteAuthSecretOptions): void;

package/dist/lib/auth-secret-file.js

@@ -0,0 +1,112 @@
+/**
+ * Where a scaffold keeps its `BETTER_AUTH_SECRET` (#6107).
+ *
+ * `apps/web/auth.ts` refuses to serve in production without the secret
+ * (#6044), and so does the Admin app's `auth.ts`. A fresh scaffold therefore
+ * gets one random value, written to each app's gitignored `.env.local` — the
+ * file `next dev` and `next start` both load:
+ *
+ *   - `apps/web/.env.local` — always;
+ *   - `apps/admin/.env.local` — when the scaffold carries `apps/admin`, with
+ *     the SAME value (both apps sign cookies for one site).
+ *
+ * Never clobber, never shadow: a value already assigned in any env file Next
+ * loads for the app under `next start` is kept, and no new `.env.local` is
+ * created above it. Never print: no message, log line or return value
+ * carries the secret.
+ *
+ * Pure module: no `import.meta.url`, so jest imports it directly.
+ */
+import { randomBytes as nodeRandomBytes } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { appendLine, writeOwnerOnly } from "./license-key-files.js";
+export const AUTH_SECRET_ENV_VAR = "BETTER_AUTH_SECRET";
+/** The files the writer owns, web first. */
+export const AUTH_SECRET_ENV_FILES = [
+    join("apps", "web", ".env.local"),
+    join("apps", "admin", ".env.local"),
+];
+/**
+ * `.gitignore` lines that already ignore `apps/<app>/.env.local`. An explicit
+ * set, never a glob evaluation; `/.env.local` is absent because, anchored to
+ * the root, it does not cover `apps/web/.env.local`.
+ */
+export const ENV_LOCAL_IGNORE_LINES = new Set([
+    ".env.local",
+    "**/.env.local",
+    ".env*.local",
+    "*.local",
+]);
+/** Env files `next start` loads, highest precedence first. */
+const NEXT_START_ENV_FILES = [
+    ".env.production.local",
+    ".env.local",
+    ".env.production",
+    ".env",
+];
+/** A line assigning the variable, with or without `export`; group 1 is the value. */
+const ENV_LINE = new RegExp(`^\\s*(?:export\\s+)?${AUTH_SECRET_ENV_VAR}\\s*=(.*)$`);
+/**
+ * The value `text` assigns — the LAST assignment, as dotenv reads it — or
+ * `undefined` when it assigns none. An empty value counts as none, exactly as
+ * `auth.ts` treats it.
+ */
+function assignedValue(text) {
+    let value;
+    for (const line of text.split("\n")) {
+        const m = ENV_LINE.exec(line);
+        if (m !== null) {
+            const raw = (m[1] ?? "").trim();
+            const quoted = /^(["'])(.*)\1$/.exec(raw);
+            value = quoted !== null ? (quoted[2] ?? "") : raw;
+        }
+    }
+    return value === "" ? undefined : value;
+}
+/** The effective value for the app at `appDir`, by Next's precedence. */
+function effectiveValue(appDir) {
+    for (const name of NEXT_START_ENV_FILES) {
+        const path = join(appDir, name);
+        if (!existsSync(path))
+            continue;
+        const value = assignedValue(readFileSync(path, "utf8"));
+        if (value !== undefined)
+            return value;
+    }
+    return undefined;
+}
+/**
+ * Give the scaffold at `dir` a `BETTER_AUTH_SECRET` (F1–F4 of the #6107
+ * spec). Generates at most one value, and only when no app already has one.
+ * Idempotent — a second call changes no byte.
+ */
+export function writeAuthSecretFile(dir, opts = {}) {
+    // Web always; Admin only when the scaffold carries `apps/admin`.
+    const apps = AUTH_SECRET_ENV_FILES.map((file) => ({
+        file: join(dir, file),
+        appDir: dirname(join(dir, file)),
+    })).filter(({ appDir }, i) => i === 0 || existsSync(appDir));
+    // An existing value — web's first — is shared; a fresh one is generated
+    // only when no app has one.
+    let secret = apps
+        .map(({ appDir }) => effectiveValue(appDir))
+        .find((v) => v !== undefined);
+    const secretFor = () => {
+        secret ??= (opts.randomBytes ?? nodeRandomBytes)(32).toString("base64url");
+        return secret;
+    };
+    for (const { file, appDir } of apps) {
+        if (effectiveValue(appDir) !== undefined)
+            continue;
+        const existing = existsSync(file) ? readFileSync(file, "utf8") : "";
+        writeOwnerOnly(file, appendLine(existing, `${AUTH_SECRET_ENV_VAR}=${secretFor()}`));
+    }
+    const ignorePath = join(dir, ".gitignore");
+    const ignore = existsSync(ignorePath) ? readFileSync(ignorePath, "utf8") : "";
+    const covered = ignore
+        .split("\n")
+        .some((l) => ENV_LOCAL_IGNORE_LINES.has(l.trim()));
+    if (!covered)
+        writeFileSync(ignorePath, appendLine(ignore, ".env.local"));
+}