create-raredays-app 0.1.0

package/README.md

@@ -0,0 +1,89 @@
+# create-raredays-app
+
+Scaffold a new RareDays Next.js app. Runs as an interactive TUI or non-interactively with flags.
+
+## Usage
+
+```sh
+# interactive mode (prompts for everything)
+pnpm create raredays-app
+
+# non-interactive with a preset
+pnpm create raredays-app my-app --preset courseware
+
+# non-interactive with explicit options
+pnpm create raredays-app my-app --template full-stack --modules billing,jobs
+
+# from a checkout of this repo
+node workspaces/app/cli/create-raredays-app/bin/index.js my-app
+```
+
+## Presets
+
+Pre-configured app types offered in interactive mode and via `--preset`:
+
+- **courseware** -- Full course platform (full-stack template + billing module, violet brand).
+- **internal-tool** -- Admin dashboard (full-stack template + jobs module, slate brand).
+- **demo** -- Lightweight demo (static template, no modules, emerald brand).
+
+Presets set the template, modules, and brand color. You can still customise display name and git settings.
+
+## Templates
+
+- **full-stack** -- Next.js + Drizzle + the full module system. Supports identity, billing, jobs, notifications, email, telemetry. Composition root at `app/lib/runtime.ts`.
+- **client** -- Next.js BFF + SPA, proxies to an external backend. Supports modules but no database layer.
+- **static** -- Truly static, deployable to CDN/edge. Core + design system only, no SSR or API routes.
+
+## Options
+
+- `--template <name>` -- `full-stack` (default), `client`, or `static`.
+- `--preset <name>` -- `courseware`, `internal-tool`, or `demo`. Overrides `--template` and `--modules`.
+- `--modules <list>` -- comma-separated modules to wire: `billing`, `jobs`, `notifications`, `email`, `telemetry`, `feature-flags`.
+- `--vendors <list>` -- comma-separated vendor preconfiguration: `stripe`, `resend`, `sentry`, `axiom`.
+- `--remote-url <url>` -- set git remote origin after scaffolding.
+- `--no-git` -- skip `git init`.
+- `--no-install` -- skip `pnpm install`.
+- `--dev` -- rewrite every `@raredays/*` dependency to `workspace:*` (for in-repo dogfooding).
+- `-h`, `--help` -- show usage.
+
+## What it does
+
+1. Copies `templates/<name>/` into the target directory.
+2. Renames stub files (`_gitignore` -> `.gitignore`, `_npmrc` -> `.npmrc`).
+3. Sets `package.json:name` to the project slug.
+4. Substitutes `__SLUG__` in `site.spec.ts` and applies display name, domain, and brand color.
+5. Loads scaffold fragments for selected modules (imports, config, ports, file overlays).
+6. Composes `app/lib/runtime.ts` with module wiring and `mocks/handlers.ts` with vendor mocks.
+7. Merges fragment dependencies into `package.json`.
+8. Writes `.env.example` if any vendor env vars are needed.
+9. Optionally runs `git init` and `pnpm install`.
+
+## Scaffold fragments
+
+The `scaffold-fragments/` directory contains per-module overlays:
+
+- `billing/` -- Stripe billing integration (checkout, portal, webhooks)
+- `email/` -- Resend email provider
+- `feature-flags/` -- Vercel Flags SDK wiring
+- `jobs/` -- Background job processing
+- `notifications/` -- Multi-channel notification delivery
+- `telemetry/` -- Sentry + Axiom telemetry
+
+Each fragment has a `module.json` manifest, runtime slot injections, and optional file overlays.
+
+## How it fits in the ecosystem
+
+`create-raredays-app` is the primary entry point for new RareDays projects. It produces a fully configured Next.js app that depends on `@raredays/core`, `@raredays/style`, `@raredays/lint`, and `@raredays/typescript`, plus any domain modules the user selects. The generated app follows the same hexagonal architecture used internally: port contracts from `@raredays/core`, in-memory dev providers, and vendor adapters swapped in for production.
+
+## Development
+
+```sh
+# run the scaffolder interactively in a sandbox
+pnpm --filter create-raredays-app dev
+
+# clean the sandbox
+pnpm --filter create-raredays-app clean
+
+# lint
+pnpm --filter create-raredays-app lint
+```