create-raredays-app 0.1.0

package/templates/client/_github/workflows/ci.yml

@@ -0,0 +1,104 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+# Mirrors the RareDays framework's CI discipline for consumer apps.
+# Client template has no backend / db steps; otherwise identical
+# verification chain to the full-stack template.
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 24, cache: pnpm }
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm lint
+
+  format-check:
+    name: Format check
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 24, cache: pnpm }
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm format:check
+
+  style:
+    name: Style
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 24, cache: pnpm }
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm style
+
+  typecheck:
+    name: Typecheck
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 24, cache: pnpm }
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm theme:build
+      - run: pnpm typecheck
+
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 24, cache: pnpm }
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm theme:build
+      - run: pnpm test
+
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 24, cache: pnpm }
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm build
+
+  storybook:
+    name: Storybook build
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    if: hashFiles('.storybook/main.ts', '.storybook/main.js') != ''
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 24, cache: pnpm }
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm theme:build
+      - run: pnpm storybook:build

package/templates/client/_gitignore

@@ -0,0 +1,15 @@
+node_modules/
+.next/
+out/
+dist/
+*.tsbuildinfo
+next-env.d.ts
+
+.env
+.env.local
+.env.*.local
+
+.skillex/
+
+.DS_Store
+*.log

package/templates/client/_npmrc

@@ -0,0 +1 @@
+@raredays:registry=http://localhost:4873

package/templates/client/app/(app)/layout.tsx

@@ -0,0 +1,49 @@
+import {
+  AppLayout,
+  AppTopBar,
+  Sidebar,
+  SidebarContent,
+  SidebarGroup,
+  SidebarGroupLabel,
+  SidebarGroupContent,
+  SidebarMenu,
+  SidebarMenuItem,
+  SidebarMenuButton,
+  SidebarHeader,
+} from "@raredays/components";
+import { ShieldIcon } from "lucide-react";
+import type { ReactNode } from "react";
+
+export default function AppGroupLayout({ children }: { children: ReactNode }) {
+  return (
+    <AppLayout
+      sidebar={
+        <Sidebar>
+          <SidebarHeader>
+            <span className="px-2 text-lg font-bold">RareDays</span>
+          </SidebarHeader>
+          <SidebarContent>
+            <SidebarGroup>
+              <SidebarGroupLabel>App</SidebarGroupLabel>
+              <SidebarGroupContent>
+                <SidebarMenu>
+                  <SidebarMenuItem>
+                    <SidebarMenuButton asChild>
+                      <a href="/protected">
+                        <ShieldIcon />
+                        <span>Protected</span>
+                      </a>
+                    </SidebarMenuButton>
+                  </SidebarMenuItem>
+                </SidebarMenu>
+              </SidebarGroupContent>
+            </SidebarGroup>
+          </SidebarContent>
+        </Sidebar>
+      }
+      topbar={<AppTopBar />}
+    >
+      {children}
+    </AppLayout>
+  );
+}

package/templates/client/app/(marketing)/layout.tsx

@@ -0,0 +1,21 @@
+import { MarketingLayout, MarketingHeader, MarketingFooter } from "@raredays/components";
+import type { ReactNode } from "react";
+
+export default function MarketingGroupLayout({ children }: { children: ReactNode }) {
+  return (
+    <MarketingLayout
+      header={
+        <MarketingHeader
+          logo={<span className="text-lg font-bold">RareDays</span>}
+          navigation={[
+            { label: "Features", href: "/#features" },
+            { label: "Pricing", href: "/#pricing" },
+          ]}
+        />
+      }
+      footer={<MarketingFooter copyright={`© ${new Date().getFullYear()} RareDays`} />}
+    >
+      {children}
+    </MarketingLayout>
+  );
+}

package/templates/client/app/(marketing)/page.tsx

@@ -0,0 +1,34 @@
+import { HomeAuthControls } from "../home-auth-controls";
+
+export default function HomePage(): React.ReactElement {
+  return (
+    <main className="mx-auto max-w-2xl p-8 font-sans">
+      <h1 className="text-3xl font-bold">RareDays — BFF + Client</h1>
+      <p className="mt-4 text-neutral-600">
+        Next.js BFF that authenticates users and proxies API calls to an external backend. Identity
+        lives here; data lives in the backend. Configure <code>BACKEND_URL</code> in your env to
+        point at the upstream service.
+      </p>
+      <HomeAuthControls />
+      <h2 className="mt-10 text-lg font-semibold">Next steps</h2>
+      <ul className="mt-3 list-disc space-y-1 pl-5 text-sm text-neutral-700">
+        <li>
+          Edit <code>app/lib/backend-client.ts</code> to customise headers, retries, observability.
+        </li>
+        <li>
+          Edit <code>app/api/backend/[...path]/route.ts</code> if your backend needs different
+          request shaping or response filtering.
+        </li>
+        <li>
+          The proxy forwards <code>x-rd-user-id</code>, <code>x-rd-organization-id</code>, and{" "}
+          <code>x-rd-roles</code> headers — your backend reads these instead of resolving auth
+          itself.
+        </li>
+        <li>
+          Run <code>pnpm test</code> to execute the sample test that exercises the in-memory
+          identity provider.
+        </li>
+      </ul>
+    </main>
+  );
+}

package/templates/client/app/api/backend/[...path]/route.ts

@@ -0,0 +1,37 @@
+// BFF proxy. Any request the SPA makes to /api/backend/<path> is forwarded
+// to the configured backend with the authenticated user's context attached.
+//
+// Customise: pull session via `app.require("identityProvider").getSession(req)`
+// and inject headers (user id, roles, tenant) before forwarding. Treat the
+// backend as the source of truth; this layer is just routing + identity.
+
+import { proxyToBackend } from "@/lib/backend-client";
+import { app } from "@/lib/runtime";
+
+async function forward(req: Request, { params }: { params: Promise<{ path: string[] }> }) {
+  const { path } = await params;
+  const session = await app.require("identityProvider").getSession(req);
+
+  // Strip hop-by-hop headers + the host header (would point at the BFF, not
+  // the backend); pass everything else through.
+  const outboundHeaders = new Headers(req.headers);
+  outboundHeaders.delete("host");
+  outboundHeaders.delete("connection");
+  if (session) {
+    outboundHeaders.set("x-rd-user-id", session.user.id);
+    outboundHeaders.set("x-rd-organization-id", session.user.organizationId);
+    outboundHeaders.set("x-rd-roles", session.user.roles.join(","));
+  }
+
+  return proxyToBackend(path.join("/"), {
+    method: req.method,
+    headers: outboundHeaders,
+    body: req.method === "GET" || req.method === "HEAD" ? undefined : await req.arrayBuffer(),
+  });
+}
+
+export const GET = forward;
+export const POST = forward;
+export const PUT = forward;
+export const PATCH = forward;
+export const DELETE = forward;

package/templates/client/app/api/dev/login/route.ts

@@ -0,0 +1,14 @@
+import { NextResponse } from "next/server";
+import { SEEDED } from "@/lib/runtime";
+
+// Dev-only: drop a cookie matching the seeded session. In production this is
+// replaced by Better Auth's sign-in flow at /api/auth/*.
+export async function POST(): Promise<NextResponse> {
+  const res = NextResponse.json({ ok: true, userId: SEEDED.user.id });
+  res.cookies.set("rd-dev-session", SEEDED.sessionId, {
+    httpOnly: true,
+    sameSite: "lax",
+    path: "/",
+  });
+  return res;
+}

package/templates/client/app/api/dev/logout/route.ts

@@ -0,0 +1,18 @@
+import { NextResponse, type NextRequest } from "next/server";
+
+export async function POST(request: NextRequest): Promise<NextResponse> {
+  // Progressive enhancement: an HTML form post (Accept: text/html) gets a
+  // 303 redirect back to /sign-in; a fetch() call (Accept: application/json)
+  // gets the original JSON response.
+  const wantsHtml = request.headers.get("accept")?.includes("text/html") ?? false;
+
+  if (wantsHtml) {
+    const res = NextResponse.redirect(new URL("/sign-in", request.url), 303);
+    res.cookies.delete("rd-dev-session");
+    return res;
+  }
+
+  const res = NextResponse.json({ ok: true });
+  res.cookies.delete("rd-dev-session");
+  return res;
+}

package/templates/client/app/globals.css

@@ -0,0 +1,22 @@
+/* CSS @import lines must precede all other rules. If you add a remote-font
+ * import (e.g. @import url("https://rsms.me/inter/inter.css")), it MUST go
+ * BEFORE the lines below — @raredays/style inlines ~6800 lines of CSS,
+ * after which any further @import is mid-document and rejected by Lightning
+ * CSS / PostCSS / browsers per the CSS spec. */
+@import "@raredays/style";
+@import "./theme.override.css";
+
+/* Scan compiled output from @raredays/* packages so Tailwind emits
+ * the arbitrary utilities used inside their components (e.g. underline
+ * positions, data-attribute variants). The relative `@source` paths in
+ * @raredays/style/index.css don't resolve under pnpm's strict
+ * node_modules layout — each @raredays/* package gets its own
+ * .pnpm/<pkg>/node_modules/<pkg>/ directory, so style's
+ * `../components/dist` points nowhere. These directives are relative
+ * to THIS file (`app/globals.css`), which is the consumer's cwd —
+ * resolves correctly.
+ *
+ * Add `@source "../node_modules/@raredays/<pkg>/dist"` for any
+ * additional @raredays/* package whose component utilities you use. */
+@source "../node_modules/@raredays/components/dist";
+@source "../node_modules/@raredays/core/dist";

package/templates/client/app/home-auth-controls.tsx

@@ -0,0 +1,28 @@
+"use client";
+
+export function HomeAuthControls(): React.ReactElement {
+  return (
+    <div className="mt-6 flex flex-wrap gap-2">
+      <button
+        type="button"
+        onClick={async () => {
+          await fetch("/api/dev/login", { method: "POST" });
+          window.location.href = "/protected";
+        }}
+        className="rounded-md bg-brand-primary px-4 py-2 text-white hover:bg-brand-secondary"
+      >
+        Sign in as Alice → /protected
+      </button>
+      <button
+        type="button"
+        onClick={async () => {
+          await fetch("/api/dev/logout", { method: "POST" });
+          window.location.reload();
+        }}
+        className="rounded-md border border-neutral-300 px-4 py-2 hover:bg-neutral-50"
+      >
+        Sign out
+      </button>
+    </div>
+  );
+}

package/templates/client/app/layout.tsx

@@ -0,0 +1,38 @@
+import { ThemeProvider, Toaster } from "@raredays/components";
+import { RaredaysProvider } from "@raredays/core";
+import type { Metadata, Viewport } from "next";
+import type { ReactNode } from "react";
+import { StartMocks } from "../mocks/browser";
+import "./globals.css";
+
+export const metadata: Metadata = {
+  title: "RareDays App",
+  description: "A RareDays Next.js application.",
+};
+
+export const viewport: Viewport = {
+  width: "device-width",
+  initialScale: 1,
+};
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body>
+        <StartMocks>
+          <RaredaysProvider>
+            <ThemeProvider
+              attribute="class"
+              defaultTheme="system"
+              enableSystem
+              disableTransitionOnChange
+            >
+              {children}
+              <Toaster position="bottom-center" />
+            </ThemeProvider>
+          </RaredaysProvider>
+        </StartMocks>
+      </body>
+    </html>
+  );
+}

package/templates/client/app/lib/backend-client.ts

@@ -0,0 +1,55 @@
+// BFF → external backend wiring. Two surfaces, one upstream:
+//
+//   • `backend`  — typed JSON client (`backend.get<T>("/widgets")`). Use
+//     this from server components, route handlers, and any code that
+//     calls the backend with a typed response.
+//
+//   • `proxyToBackend` — raw `Response` passthrough used by the
+//     `app/api/backend/[...path]/route.ts` proxy. Necessary because the
+//     proxy streams the body untouched; the typed client buffers it.
+//
+// Configure `BACKEND_URL` in your env. Tokens, retry/timeout, and auth
+// header injection live in this file — that's the one place that talks
+// to the upstream service.
+
+import { createFetchHttpClient, type HttpClient } from "@raredays/core";
+
+const BACKEND_URL = process.env.BACKEND_URL ?? "";
+
+// Lazy-initialized: warn once, on first actual use of the backend client,
+// rather than at module-import time. This keeps `next build` quiet for
+// apps that don't (yet) use backend calls, while still surfacing a clear
+// signal the first time a missing config bites.
+let warnedMissingBackendUrl = false;
+function warnIfMissingBackendUrl(): void {
+  if (warnedMissingBackendUrl) return;
+  if (BACKEND_URL) return;
+  if (process.env.NODE_ENV !== "production") return;
+  warnedMissingBackendUrl = true;
+  // eslint-disable-next-line no-console
+  console.warn("[backend-client] BACKEND_URL is not set — backend calls will fail.");
+}
+
+export const backend: HttpClient = createFetchHttpClient({
+  // `baseUrl` is read at call time by the underlying client, so the lazy
+  // warning above is sufficient — no module-load side effect needed.
+  baseUrl: BACKEND_URL,
+  // Default retry: 2 attempts on 5xx/network errors with 100ms backoff.
+  // Tune per-call via `backend.get(path, { retry: { ... } })` when you need
+  // different semantics (e.g. webhooks shouldn't retry, batch jobs should).
+  retry: { maxAttempts: 2 },
+});
+
+/**
+ * Raw passthrough for the `[...path]` proxy route. Keeps the streaming
+ * semantics that `fetch` provides — the typed `backend` client buffers
+ * the body and isn't appropriate for proxying.
+ */
+export async function proxyToBackend(path: string, init: RequestInit): Promise<Response> {
+  warnIfMissingBackendUrl();
+  if (!BACKEND_URL) {
+    return new Response("BACKEND_URL not configured", { status: 502 });
+  }
+  const url = `${BACKEND_URL.replace(/\/$/, "")}/${path.replace(/^\//, "")}`;
+  return fetch(url, init);
+}

package/templates/client/app/lib/runtime.test.ts

@@ -0,0 +1,38 @@
+// @vitest-environment node
+// Runs in the Node environment (not happy-dom) because the WHATWG `Request`
+// in happy-dom strips the `cookie` header on construction (browsers forbid
+// setting it from script). Server-side identity tests need the real Node
+// `Request`, which preserves arbitrary headers.
+
+import { describe, expect, it } from "vitest";
+import { app, SEEDED } from "./runtime.js";
+
+// Sample test demonstrating how to test app code against the framework's
+// port contracts. The composition root provides the wired ports; tests
+// drive them directly. For deeper testing of your own custom adapters,
+// import the framework's conformance harnesses (e.g.
+// `identityProviderConformance` from `@raredays/identity/testing`) and
+// pass your factory.
+
+describe("identity flow (in-memory provider)", () => {
+  it("resolves the seeded session when the dev cookie is present", async () => {
+    const provider = app.require("identityProvider");
+    const req = new Request("https://example.com/", {
+      headers: { cookie: `rd-dev-session=${SEEDED.sessionId}` },
+    });
+    const session = await provider.getSession(req);
+    expect(session).not.toBeNull();
+    expect(session?.user.id).toBe(SEEDED.user.id);
+  });
+
+  it("returns null when no session cookie is present", async () => {
+    const provider = app.require("identityProvider");
+    const session = await provider.getSession(new Request("https://example.com/"));
+    expect(session).toBeNull();
+  });
+
+  it("seeded user has content.read but not content.manage", () => {
+    expect(SEEDED.user.hasPermission("content.read")).toBe(true);
+    expect(SEEDED.user.hasPermission("content.manage")).toBe(false);
+  });
+});

package/templates/client/app/lib/runtime.ts

@@ -0,0 +1,54 @@
+// Composition root for the BFF layer. This Next.js app sits in front of
+// your real backend (Rails, Django, Go, Java, etc.) and handles:
+//   - authentication / session resolution
+//   - request proxying with auth context attached (see app/api/backend/[...path])
+//   - any client-side state / SSR shell the SPA needs
+//
+// Business logic (billing, persistence, notifications) lives in the backend.
+// Identity is the one port the BFF owns. Default uses the in-memory provider
+// so `pnpm dev` runs out of the box; swap to `@raredays/identity-better-auth`
+// in production (and mount its handler at `app/api/auth/[...all]/route.ts`).
+
+import { createRaredaysApp, definePermissions, Session, User } from "@raredays/core";
+import { createInMemoryProvider } from "@raredays/identity/testing";
+// CRDA:imports
+
+// — Authorization (what each role can do) ─────────────────────────────────
+definePermissions({
+  rolePermissions: {
+    member: ["content.read"],
+    admin: ["content.read", "content.manage"],
+  },
+});
+
+// — Seeded dev user (replace with Better Auth in production) ──────────────
+const ALICE = User.from({
+  id: "u_alice",
+  email: "alice@example.com",
+  organizationId: "default",
+  roles: ["member"],
+  emailVerifiedAt: new Date("2026-01-01T00:00:00Z"),
+});
+
+const ALICE_SESSION = Session.from({
+  id: "s_alice",
+  userId: ALICE.id,
+  user: ALICE.toJSON(),
+  expiresAt: new Date(Date.now() + 1000 * 60 * 60 * 24),
+});
+
+const identityProvider = createInMemoryProvider({
+  users: [ALICE],
+  sessions: [ALICE_SESSION],
+});
+
+export const SEEDED = { user: ALICE, sessionId: ALICE_SESSION.id };
+
+// CRDA:config
+
+export const app = createRaredaysApp({
+  identityProvider,
+  // CRDA:ports
+});
+
+// CRDA:exports

package/templates/client/app/protected/page.tsx

@@ -0,0 +1,31 @@
+import { redirect } from "next/navigation";
+import { UnauthenticatedError } from "@raredays/core";
+import { getServerSession } from "@raredays/identity/server";
+import { app } from "@/lib/runtime";
+
+export default async function ProtectedPage(): Promise<React.ReactElement> {
+  const session = await getServerSession(app);
+  if (!session) {
+    redirect("/");
+  }
+
+  try {
+    // Framework-owned authz: gate on a permission, not a role string.
+    session.user.requirePermission("content.read");
+  } catch (err) {
+    if (err instanceof UnauthenticatedError) redirect("/");
+    throw err;
+  }
+
+  return (
+    <main data-testid="protected" className="p-8 font-sans">
+      <h1 className="text-2xl font-bold">Protected</h1>
+      <p className="mt-3" data-testid="signed-in-as">
+        Signed in as {session.user.email}
+      </p>
+      <p className="mt-1 text-sm text-neutral-600" data-testid="user-id">
+        User id: {session.user.id}
+      </p>
+    </main>
+  );
+}

package/templates/client/app/theme.override.css

@@ -0,0 +1,9 @@
+/*
+ * Auto-generated by @raredays/theme-build. Do not edit by hand.
+ * Source: site.spec.ts
+ * To regenerate: pnpm theme:build
+ */
+
+@theme {
+  /* No spec overrides — defaults from @raredays/tokens apply. */
+}

package/templates/client/instrumentation.ts

@@ -0,0 +1,10 @@
+// Next.js calls `register()` early in the server boot, before any route
+// handler runs. The Node-runtime guard avoids starting MSW in edge
+// runtimes where setupServer isn't compatible.
+
+export async function register(): Promise<void> {
+  if (process.env.NEXT_RUNTIME !== "nodejs") return;
+  if (process.env.MOCKS !== "on") return;
+  const { mockServer } = await import("./mocks/node");
+  mockServer.start();
+}

package/templates/client/mocks/browser.tsx

@@ -0,0 +1,28 @@
+"use client";
+
+// Browser-side mock worker. Wraps the app so that no in-page fetch fires
+// until the Service Worker has claimed the page — otherwise the very
+// first request races the SW registration and slips through unmocked.
+//
+// When `NEXT_PUBLIC_MOCKS` is unset (production), the wrapper renders
+// children synchronously with zero overhead. Requires
+// `public/mockServiceWorker.js` — shipped by the scaffold and pinned
+// to the same `msw` version as this template. Regenerate with
+// `npx msw init public/ --save` only if you bump the `msw` dep.
+
+import { useEffect, useState, type ReactNode } from "react";
+import { enableMockWorker } from "@raredays/mocks/browser";
+import { handlers } from "./handlers";
+
+const ENABLED = process.env.NEXT_PUBLIC_MOCKS === "on";
+const worker = ENABLED ? enableMockWorker(handlers) : null;
+
+export function StartMocks({ children }: { children: ReactNode }): ReactNode {
+  const [ready, setReady] = useState(!ENABLED);
+  useEffect(() => {
+    if (!worker) return;
+    void worker.start().then(() => setReady(true));
+    return () => worker.stop();
+  }, []);
+  return ready ? children : null;
+}

package/templates/client/mocks/handlers.ts

@@ -0,0 +1,20 @@
+// Mock composition root. Imported by `mocks/node.ts`, `mocks/browser.tsx`,
+// and the vitest setup file — same handlers, three environments.
+//
+// In a client/BFF app, the most common pattern is intercepting fetches to
+// the upstream backend (proxied through `/api/backend/*`). Add those
+// handlers to the trailing array below.
+
+import { defineMocks, type RequestHandler } from "@raredays/mocks";
+// import { http, HttpResponse } from "msw";
+// CRDA:mocks-imports
+
+// Explicit annotation — TS2742 otherwise points at MSW's internal
+// HttpResponse-*.mjs path which isn't portable across consumer apps.
+export const handlers: RequestHandler[] = defineMocks(
+  // CRDA:mocks-spread
+  [
+    // App-local handlers, e.g.:
+    // http.get("/api/backend/products", () => HttpResponse.json({ products: [] })),
+  ],
+);

package/templates/client/mocks/node.ts

@@ -0,0 +1,7 @@
+// Node-side mock server. Activated by `instrumentation.ts` when
+// `MOCKS=on`, and by `vitest.setup.ts` during tests.
+
+import { setupMockServer } from "@raredays/mocks/node";
+import { handlers } from "./handlers";
+
+export const mockServer = setupMockServer(handlers);

package/templates/client/next.config.ts

@@ -0,0 +1,8 @@
+import { withRaredays } from "@raredays/core";
+import type { NextConfig } from "next";
+
+const config: NextConfig = withRaredays({
+  // Project-specific Next.js config goes here.
+});
+
+export default config;