create-raredays-app 0.1.0

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

package/templates/full-stack/oxfmt.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig, mergeConfig, base } from "@raredays/lint/oxfmt";
+
+// Explicit return-type annotation avoids TS2742 ("inferred type cannot be
+// named without a reference to ..."). `defineConfig` is re-exported from the
+// upstream `oxfmt` package, so the inferred default-export type would
+// otherwise reference a non-portable path.
+const config: ReturnType<typeof defineConfig> = defineConfig(mergeConfig(base));
+export default config;

package/templates/full-stack/oxlint.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig, mergeConfig, base } from "@raredays/lint/oxlint";
+
+// Explicit return-type annotation avoids TS2742 ("inferred type cannot be
+// named without a reference to ..."). `defineConfig` is re-exported from the
+// upstream `oxlint` package, so the inferred default-export type would
+// otherwise reference a non-portable path.
+const config: ReturnType<typeof defineConfig> = defineConfig(mergeConfig(base));
+export default config;

package/templates/full-stack/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "raredays-app",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "postinstall": "skillex refresh -q || true",
+    "dev": "pnpm theme:build && next dev -p ${PORT:-3000}",
+    "dev:mocks": "MOCKS=on NEXT_PUBLIC_MOCKS=on pnpm dev",
+    "build": "pnpm theme:build && next build",
+    "start": "next start -p ${PORT:-3000}",
+    "theme:build": "node ./scripts/build-theme.mjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "storybook": "storybook dev -p 6006",
+    "storybook:build": "storybook build -o storybook-static",
+    "db:generate": "drizzle-kit generate",
+    "db:migrate": "node db/migrate.ts",
+    "db:check": "node db/check.ts",
+    "db:push": "drizzle-kit push",
+    "db:studio": "drizzle-kit studio",
+    "db:drop": "drizzle-kit drop",
+    "lint": "raredays lint",
+    "lint:fix": "raredays lint:fix",
+    "format": "raredays format",
+    "format:check": "raredays format:check",
+    "style": "raredays style",
+    "style:fix": "raredays style:fix",
+    "fix": "raredays fix",
+    "typecheck": "tsc --noEmit",
+    "check": "raredays check && tsc --noEmit"
+  },
+  "dependencies": {
+    "@raredays/components": "0.0.1",
+    "@raredays/core": "0.0.1",
+    "@raredays/identity": "0.0.1",
+    "@raredays/mocks": "0.0.1",
+    "@raredays/postgres": "0.0.1",
+    "@raredays/postgres-neon": "0.0.1",
+    "@raredays/postgres-pglite": "0.0.1",
+    "@raredays/style": "0.0.1",
+    "drizzle-orm": "0.45.2",
+    "lucide-react": "1.14.0",
+    "msw": "2.11.5",
+    "next": "16.2.4",
+    "react": "19.2.5",
+    "react-dom": "19.2.5"
+  },
+  "devDependencies": {
+    "@raredays/lint": "0.0.1",
+    "@raredays/site-config": "0.0.1",
+    "@raredays/theme-build": "0.0.1",
+    "@raredays/typescript": "0.0.1",
+    "@tailwindcss/postcss": "4.2.4",
+    "@types/node": "22.19.17",
+    "@types/react": "19.2.14",
+    "@types/react-dom": "19.2.3",
+    "@storybook/react-vite": "10.3.6",
+    "@tailwindcss/vite": "4.2.4",
+    "@vitejs/plugin-react": "6.0.1",
+    "drizzle-kit": "0.31.10",
+    "happy-dom": "15.11.7",
+    "storybook": "10.3.6",
+    "tailwindcss": "4.2.4",
+    "typescript": "5.9.3",
+    "vite": "8.0.10",
+    "vitest": "4.1.5"
+  },
+  "engines": {
+    "node": ">=24"
+  }
+}

package/templates/full-stack/postcss.config.mjs

@@ -0,0 +1 @@
+export { default } from "@raredays/style/postcss";

package/templates/full-stack/public/mockServiceWorker.js

@@ -0,0 +1,349 @@
+/* eslint-disable */
+/* tslint:disable */
+
+/**
+ * Mock Service Worker.
+ * @see https://github.com/mswjs/msw
+ * - Please do NOT modify this file.
+ */
+
+const PACKAGE_VERSION = '2.11.5'
+const INTEGRITY_CHECKSUM = '4db4a41e972cec1b64cc569c66952d82'
+const IS_MOCKED_RESPONSE = Symbol('isMockedResponse')
+const activeClientIds = new Set()
+
+addEventListener('install', function () {
+  self.skipWaiting()
+})
+
+addEventListener('activate', function (event) {
+  event.waitUntil(self.clients.claim())
+})
+
+addEventListener('message', async function (event) {
+  const clientId = Reflect.get(event.source || {}, 'id')
+
+  if (!clientId || !self.clients) {
+    return
+  }
+
+  const client = await self.clients.get(clientId)
+
+  if (!client) {
+    return
+  }
+
+  const allClients = await self.clients.matchAll({
+    type: 'window',
+  })
+
+  switch (event.data) {
+    case 'KEEPALIVE_REQUEST': {
+      sendToClient(client, {
+        type: 'KEEPALIVE_RESPONSE',
+      })
+      break
+    }
+
+    case 'INTEGRITY_CHECK_REQUEST': {
+      sendToClient(client, {
+        type: 'INTEGRITY_CHECK_RESPONSE',
+        payload: {
+          packageVersion: PACKAGE_VERSION,
+          checksum: INTEGRITY_CHECKSUM,
+        },
+      })
+      break
+    }
+
+    case 'MOCK_ACTIVATE': {
+      activeClientIds.add(clientId)
+
+      sendToClient(client, {
+        type: 'MOCKING_ENABLED',
+        payload: {
+          client: {
+            id: client.id,
+            frameType: client.frameType,
+          },
+        },
+      })
+      break
+    }
+
+    case 'CLIENT_CLOSED': {
+      activeClientIds.delete(clientId)
+
+      const remainingClients = allClients.filter((client) => {
+        return client.id !== clientId
+      })
+
+      // Unregister itself when there are no more clients
+      if (remainingClients.length === 0) {
+        self.registration.unregister()
+      }
+
+      break
+    }
+  }
+})
+
+addEventListener('fetch', function (event) {
+  const requestInterceptedAt = Date.now()
+
+  // Bypass navigation requests.
+  if (event.request.mode === 'navigate') {
+    return
+  }
+
+  // Opening the DevTools triggers the "only-if-cached" request
+  // that cannot be handled by the worker. Bypass such requests.
+  if (
+    event.request.cache === 'only-if-cached' &&
+    event.request.mode !== 'same-origin'
+  ) {
+    return
+  }
+
+  // Bypass all requests when there are no active clients.
+  // Prevents the self-unregistered worked from handling requests
+  // after it's been terminated (still remains active until the next reload).
+  if (activeClientIds.size === 0) {
+    return
+  }
+
+  const requestId = crypto.randomUUID()
+  event.respondWith(handleRequest(event, requestId, requestInterceptedAt))
+})
+
+/**
+ * @param {FetchEvent} event
+ * @param {string} requestId
+ * @param {number} requestInterceptedAt
+ */
+async function handleRequest(event, requestId, requestInterceptedAt) {
+  const client = await resolveMainClient(event)
+  const requestCloneForEvents = event.request.clone()
+  const response = await getResponse(
+    event,
+    client,
+    requestId,
+    requestInterceptedAt,
+  )
+
+  // Send back the response clone for the "response:*" life-cycle events.
+  // Ensure MSW is active and ready to handle the message, otherwise
+  // this message will pend indefinitely.
+  if (client && activeClientIds.has(client.id)) {
+    const serializedRequest = await serializeRequest(requestCloneForEvents)
+
+    // Clone the response so both the client and the library could consume it.
+    const responseClone = response.clone()
+
+    sendToClient(
+      client,
+      {
+        type: 'RESPONSE',
+        payload: {
+          isMockedResponse: IS_MOCKED_RESPONSE in response,
+          request: {
+            id: requestId,
+            ...serializedRequest,
+          },
+          response: {
+            type: responseClone.type,
+            status: responseClone.status,
+            statusText: responseClone.statusText,
+            headers: Object.fromEntries(responseClone.headers.entries()),
+            body: responseClone.body,
+          },
+        },
+      },
+      responseClone.body ? [serializedRequest.body, responseClone.body] : [],
+    )
+  }
+
+  return response
+}
+
+/**
+ * Resolve the main client for the given event.
+ * Client that issues a request doesn't necessarily equal the client
+ * that registered the worker. It's with the latter the worker should
+ * communicate with during the response resolving phase.
+ * @param {FetchEvent} event
+ * @returns {Promise<Client | undefined>}
+ */
+async function resolveMainClient(event) {
+  const client = await self.clients.get(event.clientId)
+
+  if (activeClientIds.has(event.clientId)) {
+    return client
+  }
+
+  if (client?.frameType === 'top-level') {
+    return client
+  }
+
+  const allClients = await self.clients.matchAll({
+    type: 'window',
+  })
+
+  return allClients
+    .filter((client) => {
+      // Get only those clients that are currently visible.
+      return client.visibilityState === 'visible'
+    })
+    .find((client) => {
+      // Find the client ID that's recorded in the
+      // set of clients that have registered the worker.
+      return activeClientIds.has(client.id)
+    })
+}
+
+/**
+ * @param {FetchEvent} event
+ * @param {Client | undefined} client
+ * @param {string} requestId
+ * @param {number} requestInterceptedAt
+ * @returns {Promise<Response>}
+ */
+async function getResponse(event, client, requestId, requestInterceptedAt) {
+  // Clone the request because it might've been already used
+  // (i.e. its body has been read and sent to the client).
+  const requestClone = event.request.clone()
+
+  function passthrough() {
+    // Cast the request headers to a new Headers instance
+    // so the headers can be manipulated with.
+    const headers = new Headers(requestClone.headers)
+
+    // Remove the "accept" header value that marked this request as passthrough.
+    // This prevents request alteration and also keeps it compliant with the
+    // user-defined CORS policies.
+    const acceptHeader = headers.get('accept')
+    if (acceptHeader) {
+      const values = acceptHeader.split(',').map((value) => value.trim())
+      const filteredValues = values.filter(
+        (value) => value !== 'msw/passthrough',
+      )
+
+      if (filteredValues.length > 0) {
+        headers.set('accept', filteredValues.join(', '))
+      } else {
+        headers.delete('accept')
+      }
+    }
+
+    return fetch(requestClone, { headers })
+  }
+
+  // Bypass mocking when the client is not active.
+  if (!client) {
+    return passthrough()
+  }
+
+  // Bypass initial page load requests (i.e. static assets).
+  // The absence of the immediate/parent client in the map of the active clients
+  // means that MSW hasn't dispatched the "MOCK_ACTIVATE" event yet
+  // and is not ready to handle requests.
+  if (!activeClientIds.has(client.id)) {
+    return passthrough()
+  }
+
+  // Notify the client that a request has been intercepted.
+  const serializedRequest = await serializeRequest(event.request)
+  const clientMessage = await sendToClient(
+    client,
+    {
+      type: 'REQUEST',
+      payload: {
+        id: requestId,
+        interceptedAt: requestInterceptedAt,
+        ...serializedRequest,
+      },
+    },
+    [serializedRequest.body],
+  )
+
+  switch (clientMessage.type) {
+    case 'MOCK_RESPONSE': {
+      return respondWithMock(clientMessage.data)
+    }
+
+    case 'PASSTHROUGH': {
+      return passthrough()
+    }
+  }
+
+  return passthrough()
+}
+
+/**
+ * @param {Client} client
+ * @param {any} message
+ * @param {Array<Transferable>} transferrables
+ * @returns {Promise<any>}
+ */
+function sendToClient(client, message, transferrables = []) {
+  return new Promise((resolve, reject) => {
+    const channel = new MessageChannel()
+
+    channel.port1.onmessage = (event) => {
+      if (event.data && event.data.error) {
+        return reject(event.data.error)
+      }
+
+      resolve(event.data)
+    }
+
+    client.postMessage(message, [
+      channel.port2,
+      ...transferrables.filter(Boolean),
+    ])
+  })
+}
+
+/**
+ * @param {Response} response
+ * @returns {Response}
+ */
+function respondWithMock(response) {
+  // Setting response status code to 0 is a no-op.
+  // However, when responding with a "Response.error()", the produced Response
+  // instance will have status code set to 0. Since it's not possible to create
+  // a Response instance with status code 0, handle that use-case separately.
+  if (response.status === 0) {
+    return Response.error()
+  }
+
+  const mockedResponse = new Response(response.body, response)
+
+  Reflect.defineProperty(mockedResponse, IS_MOCKED_RESPONSE, {
+    value: true,
+    enumerable: true,
+  })
+
+  return mockedResponse
+}
+
+/**
+ * @param {Request} request
+ */
+async function serializeRequest(request) {
+  return {
+    url: request.url,
+    mode: request.mode,
+    method: request.method,
+    headers: Object.fromEntries(request.headers.entries()),
+    cache: request.cache,
+    credentials: request.credentials,
+    destination: request.destination,
+    integrity: request.integrity,
+    redirect: request.redirect,
+    referrer: request.referrer,
+    referrerPolicy: request.referrerPolicy,
+    body: await request.arrayBuffer(),
+    keepalive: request.keepalive,
+  }
+}

package/templates/full-stack/scripts/build-theme.mjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadSiteSpec } from "@raredays/site-config";
+import { writeThemeOverride } from "@raredays/theme-build";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const projectRoot = resolve(__dirname, "..");
+
+const spec = await loadSiteSpec(resolve(projectRoot, "site.spec.ts"));
+const outPath = resolve(projectRoot, "app/theme.override.css");
+
+await writeThemeOverride(spec, outPath, {
+  regenCommand: "pnpm theme:build",
+  source: "site.spec.ts",
+});
+
+console.log(`✓ wrote ${outPath}`);

package/templates/full-stack/site.spec.ts

@@ -0,0 +1,58 @@
+import { defineSiteSpec } from "@raredays/site-config";
+
+/**
+ * The site specification for this app.
+ *
+ * Edit this file to brand your site, configure navigation, declare integrations,
+ * and enable modules. The Tailwind theme override stylesheet at
+ * `app/theme.override.css` is regenerated from this file by `pnpm theme:build`
+ * (which is chained into `pnpm dev` and `pnpm build`).
+ */
+export default defineSiteSpec({
+  framework: "0.x",
+  runtime: "full-stack",
+  identity: {
+    name: "__SLUG__",
+    slug: "__SLUG__",
+    canonicalDomain: "example.com",
+    locales: ["en-US"],
+  },
+  branding: {
+    // Token overrides flow into Tailwind's @theme layer at build time.
+    // Anything in @raredays/tokens can be overridden here; unset keys keep
+    // the framework defaults. Examples:
+    //
+    // tokens: {
+    //   color: { brand: { primary: "#0070f3", secondary: "#111111" } },
+    //   font: { sans: "'Inter Variable', ui-sans-serif, system-ui, sans-serif" },
+    //   radius: { md: "0.5rem" },
+    // },
+    assets: {
+      logo: "/logo.svg",
+      favicon: "/favicon.ico",
+    },
+  },
+  navigation: {
+    primary: [{ label: "Home", href: "/" }],
+    footer: [{ label: "About", href: "/about" }],
+  },
+  // Module configurations live here, keyed by module id. Each enabled module
+  // package validates its own slice. Example:
+  //
+  // modules: {
+  //   billing: { plans: [...] },
+  // },
+  integrations: {
+    // Each integration's credential slots reference SHOUTING_SNAKE_CASE env
+    // var names — never literal secret values. Example:
+    //
+    // stripe: {
+    //   secretKey: "STRIPE_SECRET_KEY",
+    //   webhookSecret: "STRIPE_WEBHOOK_SECRET",
+    // },
+  },
+  deploy: {
+    vercel: { projectId: "prj_replace_me" },
+    database: { provider: "neon", urlRef: "DATABASE_URL" },
+  },
+});

package/templates/full-stack/skillex.json

@@ -0,0 +1,12 @@
+{
+  "Version": 4,
+  "Rules": [
+    {
+      "Scope": "**",
+      "Skills": [
+        "skills/repo.md"
+      ],
+      "DependencyBoundary": "."
+    }
+  ]
+}

package/templates/full-stack/skills/repo.md

@@ -0,0 +1,56 @@
+---
+title: Repository conventions
+topic: repo-conventions
+tags: [getting-started]
+---
+
+# Repository conventions
+
+This app was scaffolded with `create-raredays-app`. The framework's
+`@raredays/*` packages are workspace deps and ship their own skills, all
+auto-discovered via the `DependencyBoundary` in `skillex.json`.
+
+## Layout
+
+```
+app/
+├── (auth)/         # Sign-in / sign-up routes (when identity:better-auth is wired)
+├── (subscribed)/   # Routes gated behind an active subscription
+├── api/            # API route handlers
+├── demo/           # Sample pages (delete or replace)
+├── lib/
+│   └── runtime.ts  # Provider composition root — edit here to swap providers
+├── globals.css     # Tailwind v4 entry; scans @raredays/* dists for utilities
+├── layout.tsx      # Root layout — wraps app in RaredaysProvider
+└── theme.override.css  # Generated by `pnpm theme:build` from site.spec.ts
+db/                 # Drizzle schema + migrations
+mocks/              # MSW handlers (node + browser setups)
+public/             # Static assets + mockServiceWorker.js
+site.spec.ts        # Single source of truth for site config — feeds theme:build
+```
+
+## Always-on workflow
+
+```sh
+pnpm install           # auto-runs skillex refresh via postinstall
+pnpm dev               # Next dev server
+pnpm dev:mocks         # Dev with MSW intercepting fetch
+pnpm test              # vitest run (node-mode tests)
+pnpm check             # lint + format:check + style + typecheck (gate before commit)
+```
+
+## Where things live in the framework
+
+- `@raredays/core` — provider/port pattern, `RaredaysProvider`, env-config, ports
+- `@raredays/components` — design system components (Tailwind v4, shadcn-flavored)
+- `@raredays/identity` (+ `identity-better-auth`) — auth, sessions, organizations
+- `@raredays/billing` (+ `billing-stripe`) — subscriptions, webhooks → events
+- `@raredays/notifications` — in-app + email notification port
+- `@raredays/cms` (+ `cms-hygraph`, `cms-bridge`) — headless CMS port + canonical-id bridge
+- `@raredays/engagement` — declarative engagement tables (bookmarks, history, tags)
+- `@raredays/state-machine` — typed state machine primitive
+- `@raredays/i18n` — locale-aware translations + formatters
+- `@raredays/mocks` — MSW setup for node + browser
+
+Run `pnpm exec skillex query --package "@raredays/<name>"` for any of them
+to see canonical usage patterns.

package/templates/full-stack/stylelint.config.mjs

@@ -0,0 +1,4 @@
+/** @type {import("stylelint").Config} */
+export default {
+  extends: ["@raredays/lint/stylelint"],
+};

package/templates/full-stack/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "@raredays/typescript/tsconfig.next.json",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./app/*"]
+    }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}

package/templates/full-stack/vitest.config.ts

@@ -0,0 +1,42 @@
+import path from "node:path";
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  plugins: [react()],
+  resolve: {
+    // Mirror tsconfig.json `paths` so tests can import via `@/*`.
+    alias: {
+      "@": path.resolve(__dirname, "./app"),
+    },
+  },
+  test: {
+    // happy-dom is required for any test that mounts a React tree —
+    // node leaves `document`/`window` undefined. Server-only tests still
+    // pass because happy-dom is a superset of node's globals.
+    environment: "happy-dom",
+    // Inline @raredays/* sources so vitest doesn't choke on ESM-internal
+    // package paths when components import from sibling subpath exports.
+    server: {
+      deps: {
+        inline: [/@raredays\//],
+      },
+    },
+    include: ["app/**/*.test.ts", "app/**/*.test.tsx", "lib/**/*.test.ts"],
+    setupFiles: ["./vitest.setup.ts"],
+    // Env stubs for module-load-time provider construction.
+    //
+    // Some `@raredays/*` providers eagerly read env at import time
+    // (e.g. `cms.ts` reading `HYGRAPH_ENDPOINT`). Without stubs here,
+    // any test that transitively imports such a module fails to LOAD.
+    // Real values via `.env.local` override these in real dev runs.
+    //
+    // Add stubs for any integration declared in `site.spec.ts` whose
+    // provider constructs at import time. Defect D11 (T010 turn 0229).
+    env: {
+      MOCKS: "on",
+      HYGRAPH_ENDPOINT: "http://localhost:test",
+      HYGRAPH_TOKEN: "test",
+    },
+  },
+});

package/templates/full-stack/vitest.setup.ts

@@ -0,0 +1,18 @@
+// Boot the MSW Node server for the duration of the test run. Tests can
+// override handlers per-suite via `mockServer.use(...)` and the after-each
+// reset cleans them up.
+
+import { afterAll, afterEach, beforeAll } from "vitest";
+import { mockServer } from "./mocks/node";
+
+beforeAll(() => {
+  mockServer.start();
+});
+
+afterEach(() => {
+  mockServer.resetHandlers();
+});
+
+afterAll(() => {
+  mockServer.stop();
+});