create-raredays-app 0.1.0

package/templates/full-stack/.storybook/main.ts

@@ -0,0 +1,77 @@
+import { dirname, resolve } from "node:path";
+import { createRequire } from "node:module";
+import type { StorybookConfig } from "@storybook/react-vite";
+import react from "@vitejs/plugin-react";
+import tailwindcss from "@tailwindcss/vite";
+
+// Storybook config for the scaffolded app.
+//
+// Loads stories from two sources, namespaced separately:
+//
+//   App/<...>                  → ../app/**/*.stories.@(ts|tsx)
+//                                ../src/**/*.stories.@(ts|tsx)
+//
+//   @raredays/components/<...> → resolved-package-root/dist/**/*.stories.js
+//
+// Framework stories are pre-compiled by the framework's build (vite
+// `preserveModules: true`) — `@/` aliases are already resolved, so
+// the consumer's Vite doesn't need any path-alias config to load
+// them. To add more framework packages with stories, add a matching
+// stories[] entry pointing at their dist/.
+//
+// We resolve `@raredays/components` via Node's module resolver rather
+// than a literal `../node_modules/...` path because pnpm hoists
+// workspace dependencies to the workspace root — under a workspace
+// install the package may not exist in the app's own node_modules at
+// all, and the literal path silently matches zero stories.
+//
+// `require.resolve("@raredays/components")` returns the package's
+// main entry (`dist/index.js`); we walk up to the package root so the
+// glob can target `dist/**/*.stories.js`. We avoid resolving
+// `@raredays/components/package.json` directly because the package's
+// `exports` map does not expose `./package.json`.
+//
+// Stories render in THIS Storybook's iframe — they inherit the
+// consumer's theme.override.css, RaredaysProvider, fonts, and any
+// other context loaded in .storybook/preview.ts. That's the whole
+// point: see how framework components look with YOUR theme applied,
+// not a generic one.
+const require = createRequire(import.meta.url);
+const componentsRoot = dirname(dirname(require.resolve("@raredays/components")));
+
+const config: StorybookConfig = {
+  framework: "@storybook/react-vite",
+  stories: [
+    {
+      directory: "../app",
+      files: "**/*.stories.@(ts|tsx)",
+      titlePrefix: "App",
+    },
+    {
+      directory: "../src",
+      files: "**/*.stories.@(ts|tsx)",
+      titlePrefix: "App",
+    },
+    {
+      directory: `${componentsRoot}/dist`,
+      files: "**/*.stories.js",
+      titlePrefix: "@raredays/components",
+    },
+  ],
+  addons: [],
+  typescript: {
+    check: false,
+    reactDocgen: "react-docgen-typescript",
+  },
+  viteFinal: async (viteConfig) => {
+    viteConfig.plugins = [...(viteConfig.plugins ?? []), react(), tailwindcss()];
+    viteConfig.resolve ??= {};
+    viteConfig.resolve.alias = {
+      ...(viteConfig.resolve.alias as Record<string, string>),
+      "@": resolve(import.meta.dirname, "../app"),
+    };
+    return viteConfig;
+  },
+};
+
+export default config;

package/templates/full-stack/.storybook/preview.ts

@@ -0,0 +1,12 @@
+import type { Preview } from "@storybook/react-vite";
+import "../app/globals.css";
+
+const preview: Preview = {
+  parameters: {
+    controls: {
+      matchers: { color: /(background|color)$/i, date: /Date$/i },
+    },
+  },
+};
+
+export default preview;

package/templates/full-stack/CLAUDE.md

@@ -0,0 +1,50 @@
+# Project conventions
+
+Always read `AGENTS.md` first — it lists every skill available via `@raredays/*`
+packages. Use them before authoring components, modules, or providers from
+scratch.
+
+## Quick orientation
+
+This app was scaffolded with `create-raredays-app` and consumes the RareDays
+framework via `@raredays/*` workspace deps. Conventions:
+
+- **Components**: prefer composing from `@raredays/components` (shadcn-flavored,
+  Tailwind v4, browser-tested with vitest+playwright). When you do author new
+  components, follow the patterns documented in
+  `pnpm exec skillex query --package @raredays/components`.
+- **Server logic**: use `@raredays/core`'s provider/port pattern. Identity,
+  billing, notifications, CMS, etc. are wired in `app/lib/runtime.ts` —
+  edit there to swap providers, don't sprinkle SDK calls through the codebase.
+- **Tests**: vitest. Browser-mode tests use the `.browser.test.tsx` suffix and
+  run separately from node-mode tests. Conformance harnesses live in each
+  module's `src/testing/` directory and exercise every provider against the
+  same invariants.
+- **Lint/format**: `pnpm check` runs lint + format-check + style + typecheck.
+  Pre-commit hook (if you add one) should call this.
+
+## Don't
+
+- Re-implement primitives that already exist in `@raredays/*`. Always query
+  skillex first.
+- Edit code in `node_modules/@raredays/*` directly. If a provider needs
+  changing, file a framework issue or PR upstream.
+- Commit code with failing lint/format/style/test. `pnpm check` should be
+  green before every commit.
+
+## Skillex
+
+Skills from installed `@raredays/*` packages are auto-discovered. To refresh
+the index after adding a new dependency:
+
+```sh
+pnpm exec skillex refresh
+```
+
+Query patterns:
+
+```sh
+pnpm exec skillex query --search "<concepts>"
+pnpm exec skillex query --package "@raredays/components"
+pnpm exec skillex query --topic identity
+```

package/templates/full-stack/_claude/settings.json

@@ -0,0 +1,107 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "_comment": "Permissive defaults — agents can iterate without prompting on routine dev actions. Anything that mutates shared/remote state still requires explicit approval.",
+  "permissions": {
+    "allow": [
+      "Bash(pnpm install*)",
+      "Bash(pnpm run *)",
+      "Bash(pnpm exec *)",
+      "Bash(pnpm dev*)",
+      "Bash(pnpm build*)",
+      "Bash(pnpm test*)",
+      "Bash(pnpm lint*)",
+      "Bash(pnpm format*)",
+      "Bash(pnpm style*)",
+      "Bash(pnpm check*)",
+      "Bash(pnpm typecheck*)",
+      "Bash(pnpm db:*)",
+      "Bash(pnpm theme:build*)",
+      "Bash(pnpm dlx *)",
+      "Bash(pnpm --filter *)",
+      "Bash(pnpm -w *)",
+      "Bash(node *)",
+      "Bash(npx *)",
+      "Bash(git status*)",
+      "Bash(git diff*)",
+      "Bash(git log*)",
+      "Bash(git show*)",
+      "Bash(git branch*)",
+      "Bash(git ls-files*)",
+      "Bash(git ls-tree*)",
+      "Bash(git stash*)",
+      "Bash(git add*)",
+      "Bash(git checkout *)",
+      "Bash(git switch *)",
+      "Bash(git restore *)",
+      "Bash(git rev-parse*)",
+      "Bash(git remote -v)",
+      "Bash(git fetch*)",
+      "Bash(git pull --ff-only*)",
+      "Bash(mkdir *)",
+      "Bash(touch *)",
+      "Bash(ls *)",
+      "Bash(find *)",
+      "Bash(grep *)",
+      "Bash(rg *)",
+      "Bash(cat *)",
+      "Bash(head *)",
+      "Bash(tail *)",
+      "Bash(wc *)",
+      "Bash(sort *)",
+      "Bash(uniq *)",
+      "Bash(jq *)",
+      "Bash(curl http://localhost*)",
+      "Bash(curl http://127.0.0.1*)",
+      "Bash(pnpm exec skillex*)",
+      "Bash(pnpm exec playwright *)",
+      "Bash(pnpm exec vitest*)",
+      "Bash(pnpm exec drizzle-kit*)",
+      "Bash(pnpm exec next *)",
+      "Bash(pnpm exec tsc*)",
+      "Bash(pnpm exec oxlint*)",
+      "Bash(pnpm exec oxfmt*)",
+      "Bash(pnpm exec stylelint*)",
+      "Read",
+      "Edit",
+      "Write",
+      "Glob",
+      "Grep",
+      "WebFetch"
+    ],
+    "ask": [
+      "Bash(git commit*)",
+      "Bash(git push*)",
+      "Bash(git merge*)",
+      "Bash(git rebase*)",
+      "Bash(git reset*)",
+      "Bash(gh issue*)",
+      "Bash(gh pr*)",
+      "Bash(gh release*)",
+      "Bash(gh workflow*)",
+      "Bash(pnpm publish*)",
+      "Bash(pnpm nx release*)",
+      "Bash(npm publish*)"
+    ],
+    "deny": [
+      "Bash(git push --force*)",
+      "Bash(git push -f *)",
+      "Bash(git push * --force*)",
+      "Bash(rm -rf /*)",
+      "Bash(rm -rf ~)",
+      "Bash(rm -rf $HOME*)",
+      "Bash(cat .env*)",
+      "Bash(cat *.env)",
+      "Bash(cat *.env.local)",
+      "Bash(cat *.env.production)",
+      "Bash(printenv)",
+      "Bash(env)",
+      "Read(./.env)",
+      "Read(./.env.local)",
+      "Read(./.env.production)",
+      "Read(./.env.*)",
+      "Read(./**/.env)",
+      "Read(./**/.env.local)",
+      "Read(./**/.env.production)"
+    ]
+  }
+}

package/templates/full-stack/_github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,19 @@
+<!-- Brief description of what this PR does and why. -->
+
+## Summary
+
+-
+-
+
+## Verification
+
+- [ ] `pnpm lint` passes
+- [ ] `pnpm format:check` passes
+- [ ] `pnpm style` passes
+- [ ] `pnpm typecheck` passes
+- [ ] `pnpm test` passes
+- [ ] `pnpm build` succeeds
+
+## Notes
+
+<!-- Anything reviewers should know — migrations, env changes, follow-ups. -->

package/templates/full-stack/_github/dependabot.yml

@@ -0,0 +1,57 @@
+version: 2
+
+# Dependabot for consumer apps scaffolded from create-raredays-app.
+# Weekly cadence with grouped PRs to minimise noise — RareDays
+# packages move together, and dev tooling churns enough that grouped
+# updates are easier to review than per-package.
+
+updates:
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    groups:
+      raredays:
+        patterns:
+          - "@raredays/*"
+      react:
+        patterns:
+          - react
+          - react-dom
+          - "@types/react"
+          - "@types/react-dom"
+      next:
+        patterns:
+          - next
+      tailwind:
+        patterns:
+          - tailwindcss
+          - "@tailwindcss/*"
+      storybook:
+        patterns:
+          - storybook
+          - "@storybook/*"
+      vitest:
+        patterns:
+          - vitest
+          - "@vitejs/*"
+          - happy-dom
+      drizzle:
+        patterns:
+          - drizzle-kit
+          - drizzle-orm
+      dev-tooling:
+        dependency-type: development
+        patterns:
+          - "*"
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 3
+    groups:
+      gha:
+        patterns:
+          - "*"

package/templates/full-stack/_github/workflows/ci.yml

@@ -0,0 +1,109 @@
+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.
+# Each verification target runs as its own job so they execute in
+# parallel — wall-clock equals the slowest target, not the sum.
+#
+# Shared setup (checkout + pnpm + node + install) is duplicated across
+# jobs by design: it's cheap (~30s with pnpm cache) and avoids needing
+# an upload-artifact dance between jobs.
+
+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
+    # Only run if storybook is configured.
+    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/full-stack/_github/workflows/db-check.yml

@@ -0,0 +1,36 @@
+# Validates Drizzle migrations on every pull request.
+#
+# Runs `pnpm db:check`, which redirects Drizzle's bookkeeping table to a
+# scratch schema, applies all pending migrations, then drops the schema.
+# If the migrations don't parse or the bookkeeping plumbing fails, the
+# job blocks the PR.
+#
+# Uses in-process PGlite when DATABASE_URL is not configured as a repo
+# secret — that's usually fine for structural validation. To run against
+# a real Postgres on PR (catches data-dependent issues), add a
+# `DATABASE_URL` secret pointing at a clone of production.
+name: db-check
+
+on:
+  pull_request:
+    paths:
+      - "db/**"
+      - "drizzle.config.ts"
+      - "package.json"
+      - ".github/workflows/db-check.yml"
+
+jobs:
+  db-check:
+    runs-on: ubuntu-latest
+    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
+      - name: Validate migrations
+        env:
+          DATABASE_URL: ${{ secrets.DATABASE_URL_STAGING }}
+        run: pnpm db:check

package/templates/full-stack/_github/workflows/db-migrate.yml

@@ -0,0 +1,39 @@
+# Applies Drizzle migrations to the production database after a merge
+# to `main`. Gated on a GitHub Environment named `production` — configure
+# required reviewers there to enforce manual approval.
+#
+# Also runnable manually via workflow_dispatch (e.g. to re-run a failed
+# migrate after a transient outage).
+name: db-migrate
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "db/migrations/**"
+      - "db/migrate.ts"
+      - ".github/workflows/db-migrate.yml"
+  workflow_dispatch:
+
+concurrency:
+  # Advisory lock at the workflow layer too — defense in depth alongside
+  # safeMigrate's per-database advisory lock.
+  group: db-migrate-production
+  cancel-in-progress: false
+
+jobs:
+  migrate:
+    runs-on: ubuntu-latest
+    environment: production
+    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
+      - name: Apply migrations
+        env:
+          DATABASE_URL: ${{ secrets.DATABASE_URL }}
+        run: pnpm db:migrate

package/templates/full-stack/_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/full-stack/_npmrc

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

package/templates/full-stack/app/(app)/layout.tsx

@@ -0,0 +1,53 @@
+import {
+  AppLayout,
+  AppTopBar,
+  Sidebar,
+  SidebarContent,
+  SidebarGroup,
+  SidebarGroupLabel,
+  SidebarGroupContent,
+  SidebarMenu,
+  SidebarMenuItem,
+  SidebarMenuButton,
+  SidebarHeader,
+} from "@raredays/components";
+import type { NavItem } from "@raredays/site-config";
+import type { ReactNode } from "react";
+import siteSpec from "../../site.spec";
+
+export default function AppGroupLayout({ children }: { children: ReactNode }) {
+  const primaryNav = (siteSpec.navigation?.primary ?? []) as readonly NavItem[];
+
+  return (
+    <AppLayout
+      sidebar={
+        <Sidebar>
+          <SidebarHeader>
+            <span className="px-2 text-lg font-bold">RareDays</span>
+          </SidebarHeader>
+          <SidebarContent>
+            <SidebarGroup>
+              <SidebarGroupLabel>App</SidebarGroupLabel>
+              <SidebarGroupContent>
+                <SidebarMenu>
+                  {primaryNav.map((item) => (
+                    <SidebarMenuItem key={item.href}>
+                      <SidebarMenuButton asChild>
+                        <a href={item.href}>
+                          <span>{item.label}</span>
+                        </a>
+                      </SidebarMenuButton>
+                    </SidebarMenuItem>
+                  ))}
+                </SidebarMenu>
+              </SidebarGroupContent>
+            </SidebarGroup>
+          </SidebarContent>
+        </Sidebar>
+      }
+      topbar={<AppTopBar />}
+    >
+      {children}
+    </AppLayout>
+  );
+}

package/templates/full-stack/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/full-stack/app/(marketing)/page.tsx

@@ -0,0 +1,38 @@
+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</h1>
+      <p className="mt-4 text-neutral-600">
+        Scaffolded with <code>create-raredays-app</code>. Identity is wired through{" "}
+        <code>app/lib/runtime.ts</code> using the in-memory provider — swap it for{" "}
+        <code>@raredays/identity-better-auth</code> in production.
+      </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>site.spec.ts</code> to brand your site; <code>pnpm theme:build</code>{" "}
+          regenerates the override CSS.
+        </li>
+        <li>
+          Edit <code>app/lib/runtime.ts</code> to wire billing, jobs, notifications, email, or
+          telemetry. The composition root holds every port; modules read from it.
+        </li>
+        <li>
+          Run <code>pnpm test</code> to execute the sample test that exercises the protected page
+          using the in-memory provider.
+        </li>
+        <li>
+          Visit{" "}
+          <a className="underline" href="/demo/widgets">
+            /demo/widgets
+          </a>{" "}
+          for a <code>defineAsyncLoad</code> example — run <code>pnpm dev:mocks</code> to see it
+          backed by canned MSW data.
+        </li>
+      </ul>
+    </main>
+  );
+}

package/templates/full-stack/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/full-stack/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;
+}