create-ailk 0.1.0

package/templates/apps/web/CLAUDE.md

@@ -0,0 +1,81 @@
+# apps/web — Next.js Site
+
+> **NOT the production marketing site.** The production AI Launch Kit marketing site at https://ailaunchkit.ai deploys from `apps-paid/marketing-web/`, NOT this app. `apps/web` is the OSS customer-facing template that downstream forks build on. See `project.yaml.deployments` for the canonical URL → app mapping.
+
+Inherits root `CLAUDE.md`. This file adds web-specific rules.
+
+## Stack
+
+- Next.js (App Router), React, TypeScript
+- Styling: Tailwind via `@working-theory/theme` tokens
+- Content: MDX via `@working-theory/content-adapters`
+- JSON-LD: emitted via `@working-theory/schema` builders
+- UI primitives: `@working-theory/ui`
+
+## Always do first
+
+- For any UI work: invoke the `frontend-design` skill before writing code.
+- For any page-rendering or schema-emission work: read `packages/schema/README.md` (catalog) and `packages/schema/CLAUDE.md` (operational layer + component map) if you haven't this session.
+- For content authoring questions: read `content/CLAUDE.md` first.
+- For a full page build, follow the per-page loop (Content intent → Layout → Author content → Visual iterate). The visual-iterate step uses `screenshots/` as scratch (see § Iterate visually).
+
+## The render path (don't reinvent it)
+
+MDX file → content adapter parses frontmatter → adapter emits `ContentPage` → `@working-theory/page-renderer`'s `renderPage(input)` composes the populated/empty-state output, calls `@working-theory/schema`'s `buildJsonLd(page)`, and emits `<script type="application/ld+json">` inside the rendered tree.
+
+- Never hand-roll JSON-LD in a React component.
+- Never read MDX directly — go through `@working-theory/content-adapters`.
+- Never modify `@working-theory/schema` from `apps/web`. Schema changes happen in `packages/schema`.
+
+## Component vocabulary
+
+Use `@working-theory/ui` components for content patterns. See `content/CLAUDE.md` for the full vocabulary — it's identical across page types because the rule is about the component, not the page. For the per-page-type editorial map, see `packages/schema/CLAUDE.md` § `@working-theory/ui` component map.
+
+Raw HTML is allowed only when no `@working-theory/ui` component fits. Flag it in PR review when you add raw HTML.
+
+## Theme & styling
+
+- Colors and tokens come from `@working-theory/theme`. Never hardcode hex values.
+- Tailwind utilities are fine; **Tailwind defaults are not** — no `indigo-500`, `blue-600`, etc. Use theme tokens.
+- Mobile-first responsive. Test at 320px, 768px, 1024px, and 1440px before marking a page done. Touch targets must be ≥44×44px (use `min-h-11 min-w-11`). Every interactive element needs a visible `focus-visible:` state. Wrap animations in `motion-safe:` so `prefers-reduced-motion` is honored.
+- Animations: only `transform` and `opacity`. Never `transition-all`.
+- Every interactive element needs hover, focus-visible, and active states.
+
+For the full responsive contract (path-scoped to UI files), see `.claude/rules/responsive.md`. For brand-asset discovery (logos, colors, photos), see `.claude/rules/brand.md`.
+
+## Local dev
+
+- `pnpm dev` from repo root runs all apps.
+- Web-only: `turbo run dev --filter=./apps/web` → `http://localhost:3000`.
+- Content root: `src/lib/content/index.ts` resolves content via `AILK_CONTENT_ROOT` env var (if set) or `process.cwd()/../../content` (default for dev/build). In production (Vercel standalone container), set `AILK_CONTENT_ROOT` in Vercel project settings to the absolute path where `outputFileTracingIncludes` copied `content/` — typically `/var/task/content`. See `docs/runbooks/page-renderer-deploy-verification.md` §1 Cause 3.
+
+## Iterate visually
+
+Don't ship a page after one render. The expected per-page loop:
+
+1. **Content intent.** Decide what the page is about — key facts, target citation phrases, who's reading. Pull from `brand_assets/brand-brief.md` (positioning, messaging, target citation phrases).
+2. **Layout design.** Given intent + the global theme in `brand_assets/brand-guide.md`, choose `@working-theory/ui` components and their arrangement.
+3. **Author content.** Fill components with AEO-optimized copy per `content/CLAUDE.md` § AEO editorial craft.
+4. **Visual iterate.**
+   - Check `brand_assets/` before designing. If logos, color values, or a brand guide exist there, use them — don't invent brand colors or placeholder logos when real assets are present.
+   - Save working screenshots to `screenshots/` (gitignored — contents not committed; the directory itself is tracked via `.gitkeep`). Don't commit screenshot images.
+   - Render the page locally; switch DevTools to responsive mode and verify at 320 / 768 / 1024 / 1440.
+   - Compare against the reference (designer mockup, `brand_assets/reference/` if present, or the design intent).
+   - Fix mismatches. Be specific in self-review: "heading is 32px, reference shows 24px", not "looks off."
+   - Repeat until no visible differences and no responsive issues at any of the four breakpoints.
+
+## AEO & performance
+
+- Static rendering is the default. Don't introduce client rendering without a reason.
+- Every page must emit valid JSON-LD. If `buildJsonLd` throws, fix the page, not the builder.
+- After non-trivial page changes, run `ailk audit` and address Layer 1 findings before merging.
+- Don't break `/llms.txt`, raw-MDX URLs, or stealth-by-default `robots.txt`.
+
+## What NOT to do
+
+- Don't emit JSON-LD inline in MDX or components.
+- Don't add a new page type by hand-rolling schema. Add to `packages/schema` first.
+- Don't use default Tailwind colors as brand colors.
+- Don't use `transition-all`.
+- Don't reach into `apps/api` or `apps/mcp` from `apps/web`. They're peer apps — talk via HTTP/MCP.
+- Don't commit images to `screenshots/` — only the `.gitkeep` is tracked.

package/templates/apps/web/__tests__/auth/adversarial/cookie-attributes.test.ts

@@ -0,0 +1,94 @@
+/**
+ * @file cookie-attributes.test.ts (S13 adversarial)
+ *
+ * Verifies that `apps/web/auth.ts` does NOT weaken Better Auth's secure-cookie
+ * defaults. Better Auth's `nextCookies()` plugin emits session cookies with
+ * `HttpOnly`, `Secure` (in non-dev environments), `SameSite=Lax`, and
+ * `Path=/`. The configuration in `auth.ts` must not override any of those.
+ *
+ * Strategy: mock `better-auth` so its real ESM-only module never loads in the
+ * Jest CJS preset. The mock's `betterAuth(options)` returns `{ options }` so
+ * the test can inspect the raw config object the AILK code passed in. The
+ * assertions guard the AILK-owned surface, not Better Auth's emission
+ * (that's the library's contract).
+ */
+
+jest.mock("better-auth", () => ({
+  betterAuth: (options: unknown) => ({ options }),
+}));
+
+jest.mock("better-auth/adapters/prisma", () => ({
+  prismaAdapter: () => ({ id: "mock-prisma-adapter" }),
+}));
+
+jest.mock("better-auth/next-js", () => ({
+  nextCookies: () => ({ id: "next-cookies" }),
+}));
+
+import { createAuth } from "../../../auth";
+
+// Stub PrismaClient — avoids a real DB connection at module-load time.
+// Injected via createAuth({ prisma }) instead of jest.mock("../../../lib/prisma-for-auth").
+// Pattern mirrors apps-paid/dashboard-web/auth.ts DI.
+const stubPrisma = {} as NonNullable<NonNullable<Parameters<typeof createAuth>[0]>["prisma"]>;
+const auth = createAuth({ prisma: stubPrisma });
+
+type CookieAttrs = {
+  httpOnly?: boolean;
+  secure?: boolean;
+  sameSite?: "lax" | "strict" | "none";
+  path?: string;
+};
+
+type AdvancedCookies = {
+  session_token?: { attributes?: CookieAttrs };
+  session_data?: { attributes?: CookieAttrs };
+};
+
+type AuthOptions = {
+  advanced?: {
+    useSecureCookies?: boolean;
+    cookies?: AdvancedCookies;
+    defaultCookieAttributes?: CookieAttrs;
+  };
+  plugins?: Array<{ id?: string }>;
+  session?: { expiresIn?: number; updateAge?: number };
+};
+
+// eslint-disable-next-line no-restricted-syntax -- the mocked betterAuth returns { options: <unknown> }; the real type carries no public options shape, so a double assertion is the narrow path to inspect the AILK-owned config object.
+const options = (auth as unknown as { options: AuthOptions }).options;
+
+describe("S13 adversarial — cookie attributes (config surface)", () => {
+  it("does NOT disable useSecureCookies (Better Auth secure default preserved)", () => {
+    expect(options.advanced?.useSecureCookies).not.toBe(false);
+  });
+
+  it("does NOT override session_token cookie to drop HttpOnly", () => {
+    const sessionAttrs = options.advanced?.cookies?.session_token?.attributes;
+    expect(sessionAttrs?.httpOnly).not.toBe(false);
+  });
+
+  it("does NOT override session_token cookie to drop Secure", () => {
+    const sessionAttrs = options.advanced?.cookies?.session_token?.attributes;
+    expect(sessionAttrs?.secure).not.toBe(false);
+  });
+
+  it("does NOT relax sameSite to 'none' (CSRF protection preserved)", () => {
+    expect(
+      options.advanced?.cookies?.session_token?.attributes?.sameSite,
+    ).not.toBe("none");
+    expect(options.advanced?.defaultCookieAttributes?.sameSite).not.toBe(
+      "none",
+    );
+  });
+
+  it("includes the nextCookies() plugin so Next.js sets cookies via Response", () => {
+    const pluginIds = (options.plugins ?? []).map((p) => p.id);
+    expect(pluginIds).toContain("next-cookies");
+  });
+
+  it("persists sessions in the database (admin-revocable model)", () => {
+    expect(options.session).toBeDefined();
+    expect(options.session?.expiresIn).toBeGreaterThan(0);
+  });
+});

package/templates/apps/web/__tests__/auth/adversarial/oauth-state-parameter.test.ts

@@ -0,0 +1,75 @@
+/**
+ * @file oauth-state-parameter.test.ts (S13 adversarial)
+ *
+ * OAuth `state` parameter protection. Better Auth's social-signin flow
+ * generates an opaque `state` value on every OAuth handshake; the callback
+ * route validates it. The AILK-owned surface that could disable this is
+ * `auth.options` — there is no documented Better Auth knob to turn state
+ * generation off, but a future migration to a custom plugin (e.g.
+ * `genericOAuth`) could weaken it. This file pins the AILK config so a
+ * regression that introduces a state-disabling override is caught.
+ *
+ * Strategy: mock `better-auth` so the real ESM-only module never loads;
+ * inspect the options object the AILK code constructed.
+ */
+
+jest.mock("better-auth", () => ({
+  betterAuth: (options: unknown) => ({ options }),
+}));
+
+jest.mock("better-auth/adapters/prisma", () => ({
+  prismaAdapter: () => ({ id: "mock-prisma-adapter" }),
+}));
+
+jest.mock("better-auth/next-js", () => ({
+  nextCookies: () => ({ id: "next-cookies" }),
+}));
+
+import { createAuth } from "../../../auth";
+
+// Stub PrismaClient — avoids a real DB connection at module-load time.
+// Injected via createAuth({ prisma }) instead of jest.mock("../../../lib/prisma-for-auth").
+// Pattern mirrors apps-paid/dashboard-web/auth.ts DI.
+const stubPrisma = {} as NonNullable<NonNullable<Parameters<typeof createAuth>[0]>["prisma"]>;
+const auth = createAuth({ prisma: stubPrisma });
+
+type SocialProviderOpts = {
+  skipStateCheck?: boolean;
+  disableState?: boolean;
+};
+
+type AuthOptions = {
+  plugins?: Array<{ id?: string }>;
+  socialProviders?: Record<string, SocialProviderOpts>;
+};
+
+// eslint-disable-next-line no-restricted-syntax -- the mocked betterAuth returns { options: <unknown> }; the real type carries no public options shape, so a double assertion is the narrow path to inspect the AILK-owned config object.
+const options = (auth as unknown as { options: AuthOptions }).options;
+
+describe("S13 adversarial — OAuth state parameter", () => {
+  it("auth config does NOT register a generic-oauth plugin (which would need explicit state config review)", () => {
+    const plugins = options.plugins ?? [];
+    const generic = plugins.find((p) => p.id === "generic-oauth");
+    expect(generic).toBeUndefined();
+  });
+
+  it("active social providers do NOT carry a skipStateCheck override", () => {
+    const providers = options.socialProviders ?? {};
+    for (const [, opts] of Object.entries(providers)) {
+      // No Better Auth option named skipStateCheck/disableState exists today.
+      // The assertion guards against a custom wrapper that adds one.
+      expect(opts.skipStateCheck).toBeFalsy();
+      expect(opts.disableState).toBeFalsy();
+    }
+  });
+
+  it("social provider entries are syntactically valid (each has an id-shaped key)", () => {
+    const providers = options.socialProviders ?? {};
+    // When env vars are unset (OSS standalone default) the map is empty.
+    // Test passes vacuously. When wired, each provider has a non-empty key
+    // which Better Auth uses to route state into the right cookie namespace.
+    for (const name of Object.keys(providers)) {
+      expect(name.length).toBeGreaterThan(0);
+    }
+  });
+});

package/templates/apps/web/__tests__/auth/adversarial/redirect-uri-allowlist.test.ts

@@ -0,0 +1,82 @@
+/**
+ * @file redirect-uri-allowlist.test.ts (S13 adversarial)
+ *
+ * Redirect-URI allow-listing. Better Auth uses `trustedOrigins` (option on
+ * the betterAuth() config) to gate which origins may receive callback /
+ * redirect responses. The OAuth-provider-side `redirect_uri` registration
+ * is handled at the provider (e.g. Google Cloud Console); Better Auth's
+ * defence-in-depth layer is `trustedOrigins`.
+ *
+ * Asserted on the AILK-owned config surface:
+ *   - `auth.options.trustedOrigins` is either undefined (Better Auth
+ *     defaults to baseURL only) or a non-empty list / function. NEVER
+ *     `["*"]` or an empty list.
+ *   - If the config sets `trustedOrigins` as an array, every entry is a
+ *     concrete origin (not a wildcard).
+ *   - `baseURL` (Better Auth's primary callback origin) is sourced from
+ *     `BETTER_AUTH_URL`, not hardcoded.
+ *
+ * Strategy: mock `better-auth` so the real ESM module never loads.
+ */
+
+jest.mock("better-auth", () => ({
+  betterAuth: (options: unknown) => ({ options }),
+}));
+
+jest.mock("better-auth/adapters/prisma", () => ({
+  prismaAdapter: () => ({ id: "mock-prisma-adapter" }),
+}));
+
+jest.mock("better-auth/next-js", () => ({
+  nextCookies: () => ({ id: "next-cookies" }),
+}));
+
+import { createAuth } from "../../../auth";
+
+// Stub PrismaClient — avoids a real DB connection at module-load time.
+// Injected via createAuth({ prisma }) instead of jest.mock("../../../lib/prisma-for-auth").
+// Pattern mirrors apps-paid/dashboard-web/auth.ts DI.
+const stubPrisma = {} as NonNullable<NonNullable<Parameters<typeof createAuth>[0]>["prisma"]>;
+const auth = createAuth({ prisma: stubPrisma });
+
+type TrustedOriginsOption =
+  | string[]
+  | ((req: unknown) => string[] | Promise<string[]>)
+  | undefined;
+
+type AuthOptions = {
+  trustedOrigins?: TrustedOriginsOption;
+  baseURL?: string;
+};
+
+// eslint-disable-next-line no-restricted-syntax -- the mocked betterAuth returns { options: <unknown> }; the real type carries no public options shape, so a double assertion is the narrow path to inspect the AILK-owned config object.
+const options = (auth as unknown as { options: AuthOptions }).options;
+
+function isWildcardEntry(origin: string): boolean {
+  return origin === "*" || origin.includes("*");
+}
+
+describe("S13 adversarial — redirect URI allow-list", () => {
+  it("does NOT configure trustedOrigins as an empty array (would block all callbacks)", () => {
+    const trusted = options.trustedOrigins;
+    if (Array.isArray(trusted)) {
+      expect(trusted.length).toBeGreaterThan(0);
+    }
+  });
+
+  it("does NOT include a wildcard entry in trustedOrigins", () => {
+    const trusted = options.trustedOrigins;
+    if (Array.isArray(trusted)) {
+      for (const origin of trusted) {
+        expect(isWildcardEntry(origin)).toBe(false);
+      }
+    }
+  });
+
+  it("sources baseURL from the BETTER_AUTH_URL env var (no hardcoded production origin)", () => {
+    const baseURL = options.baseURL;
+    if (baseURL !== undefined) {
+      expect(baseURL).toBe(process.env.BETTER_AUTH_URL);
+    }
+  });
+});

package/templates/apps/web/__tests__/auth/env-helpers.test.ts

@@ -0,0 +1,168 @@
+/**
+ * Tests for auth env-introspection helpers.
+ *
+ * Covers:
+ * 1. isAuthRequired — AILK_AUTH_REQUIRED flag behavior
+ * 2. getActiveProviders — provider list derived from env var presence
+ *
+ * Both helpers must be importable without next-auth being configured,
+ * so they live in apps/web/lib/auth-env.ts (no next-auth import).
+ */
+
+const ORIGINAL_ENV = process.env;
+
+beforeEach(() => {
+  // Fresh env copy before each test; prevents cross-test leakage.
+  process.env = { ...ORIGINAL_ENV };
+  // Clear all auth-related vars to ensure clean isolation.
+  delete process.env.AILK_AUTH_REQUIRED;
+  delete process.env.GOOGLE_CLIENT_ID;
+  delete process.env.GOOGLE_CLIENT_SECRET;
+  delete process.env.GITHUB_CLIENT_ID;
+  delete process.env.GITHUB_CLIENT_SECRET;
+  delete process.env.AUTH_EMAIL_SERVER;
+  delete process.env.AUTH_EMAIL_FROM;
+});
+
+afterAll(() => {
+  process.env = ORIGINAL_ENV;
+});
+
+// ── isAuthRequired ────────────────────────────────────────────────────────────
+
+describe("isAuthRequired", () => {
+  let isAuthRequired: () => boolean;
+
+  beforeEach(() => {
+    jest.resetModules();
+     
+    ({ isAuthRequired } = require("../../lib/auth-env"));
+  });
+
+  it("returns false when AILK_AUTH_REQUIRED is unset (OSS default)", () => {
+    expect(isAuthRequired()).toBe(false);
+  });
+
+  it("returns false when AILK_AUTH_REQUIRED=0", () => {
+    process.env.AILK_AUTH_REQUIRED = "0";
+    expect(isAuthRequired()).toBe(false);
+  });
+
+  it("returns false when AILK_AUTH_REQUIRED=false", () => {
+    process.env.AILK_AUTH_REQUIRED = "false";
+    expect(isAuthRequired()).toBe(false);
+  });
+
+  it("returns true when AILK_AUTH_REQUIRED=1", () => {
+    process.env.AILK_AUTH_REQUIRED = "1";
+    expect(isAuthRequired()).toBe(true);
+  });
+
+  it("returns true when AILK_AUTH_REQUIRED=true", () => {
+    process.env.AILK_AUTH_REQUIRED = "true";
+    expect(isAuthRequired()).toBe(true);
+  });
+});
+
+// ── getActiveProviderIds ──────────────────────────────────────────────────────
+
+describe("getActiveProviderIds", () => {
+  let getActiveProviderIds: () => string[];
+
+  beforeEach(() => {
+    jest.resetModules();
+     
+    ({ getActiveProviderIds } = require("../../lib/auth-env"));
+  });
+
+  it("returns an empty array when no auth env vars are set", () => {
+    expect(getActiveProviderIds()).toEqual([]);
+  });
+
+  it("activates 'google' only when both GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET are set", () => {
+    process.env.GOOGLE_CLIENT_ID = "gid";
+    process.env.GOOGLE_CLIENT_SECRET = "gsecret";
+    expect(getActiveProviderIds()).toEqual(["google"]);
+  });
+
+  it("does NOT activate 'google' when only GOOGLE_CLIENT_ID is set", () => {
+    process.env.GOOGLE_CLIENT_ID = "gid";
+    expect(getActiveProviderIds()).not.toContain("google");
+  });
+
+  it("does NOT activate 'google' when only GOOGLE_CLIENT_SECRET is set", () => {
+    process.env.GOOGLE_CLIENT_SECRET = "gsecret";
+    expect(getActiveProviderIds()).not.toContain("google");
+  });
+
+  it("activates 'github' only when both GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET are set", () => {
+    process.env.GITHUB_CLIENT_ID = "ghid";
+    process.env.GITHUB_CLIENT_SECRET = "ghsecret";
+    expect(getActiveProviderIds()).toEqual(["github"]);
+  });
+
+  it("does NOT activate 'github' when only one GitHub var is set", () => {
+    process.env.GITHUB_CLIENT_ID = "ghid";
+    expect(getActiveProviderIds()).not.toContain("github");
+  });
+
+  it("activates 'email' only when both AUTH_EMAIL_SERVER and AUTH_EMAIL_FROM are set", () => {
+    process.env.AUTH_EMAIL_SERVER = "smtp://localhost";
+    process.env.AUTH_EMAIL_FROM = "noreply@example.com";
+    expect(getActiveProviderIds()).toEqual(["email"]);
+  });
+
+  it("does NOT activate 'email' when only AUTH_EMAIL_SERVER is set", () => {
+    process.env.AUTH_EMAIL_SERVER = "smtp://localhost";
+    expect(getActiveProviderIds()).not.toContain("email");
+  });
+
+  it("activates all three providers when all env vars are set", () => {
+    process.env.GOOGLE_CLIENT_ID = "gid";
+    process.env.GOOGLE_CLIENT_SECRET = "gsecret";
+    process.env.GITHUB_CLIENT_ID = "ghid";
+    process.env.GITHUB_CLIENT_SECRET = "ghsecret";
+    process.env.AUTH_EMAIL_SERVER = "smtp://localhost";
+    process.env.AUTH_EMAIL_FROM = "noreply@example.com";
+    expect(getActiveProviderIds()).toEqual(
+      expect.arrayContaining(["google", "github", "email"]),
+    );
+    expect(getActiveProviderIds()).toHaveLength(3);
+  });
+
+  it("activates only the providers whose vars are complete (mixed partial env)", () => {
+    // Google: complete; GitHub: partial (missing secret); Email: complete
+    process.env.GOOGLE_CLIENT_ID = "gid";
+    process.env.GOOGLE_CLIENT_SECRET = "gsecret";
+    process.env.GITHUB_CLIENT_ID = "ghid";
+    // GITHUB_CLIENT_SECRET intentionally omitted
+    process.env.AUTH_EMAIL_SERVER = "smtp://localhost";
+    process.env.AUTH_EMAIL_FROM = "noreply@example.com";
+    const active = getActiveProviderIds();
+    expect(active).toContain("google");
+    expect(active).toContain("email");
+    expect(active).not.toContain("github");
+  });
+});
+
+// ── Zero-auth boot (no env vars at all) ─────────────────────────────────────
+
+describe("zero-env auth boot", () => {
+  beforeEach(() => {
+    jest.resetModules();
+  });
+
+  it("getActiveProviderIds returns empty array — site boots without throwing", () => {
+     
+    const { getActiveProviderIds } = require("../../lib/auth-env");
+    expect(() => getActiveProviderIds()).not.toThrow();
+    expect(getActiveProviderIds()).toEqual([]);
+  });
+
+  it("isAuthRequired returns false — site boots without throwing", () => {
+     
+    const { isAuthRequired } = require("../../lib/auth-env");
+    expect(() => isAuthRequired()).not.toThrow();
+    expect(isAuthRequired()).toBe(false);
+  });
+});