create-stackrjs 1.4.0

package/README.md

@@ -0,0 +1,154 @@
+# Stackr
+
+Scaffold a **runnable** full-stack Next.js project in one command. Stackr assembles
+a base Next.js app and composes feature "installers" (database, ORM, auth, styling,
+pre-built interfaces) into a coherent, immediately bootable project.
+
+```bash
+npm create stackrjs@latest my-app
+```
+
+Published on npm as [`create-stackrjs`](https://www.npmjs.com/package/create-stackrjs). A
+[web configurator](#web-configurator) lets you pick a stack and copy the exact command.
+
+## What you get
+
+Stackr composes a single coherent, runnable stack from your choices:
+
+| Dimension | Options |
+| --------- | ------- |
+| Architecture | Monolith (single Next.js App Router app, TypeScript strict) — or **microservices** (web + Hono API + nginx gateway, npm workspaces) |
+| Database | PostgreSQL, MySQL or MongoDB (via bundled `docker-compose.yml`) |
+| ORM | Prisma 7 or Drizzle (SQL), or Mongoose (MongoDB) |
+| Auth | NextAuth / Auth.js v5, Better Auth, Clerk or Supabase Auth |
+| Styling | Tailwind CSS or shadcn/ui |
+| Interfaces | Auth portal (login / register / forgot / reset + `/account`), user dashboard, admin / back-office, landing page |
+
+The generated app boots with:
+
+```bash
+docker compose up -d
+npm install
+npx prisma migrate dev --name init
+npm run dev
+```
+
+## Usage
+
+```bash
+npm create stackrjs@latest [name] -- [options]
+# or:  npx create-stackrjs [name] [options]
+
+  --architecture <a>   monolith   | microservices
+  --database <db>      postgres   | mysql | mongodb
+  --orm <orm>          prisma     | drizzle | mongoose
+  --auth <auth>        nextauth   | better-auth | clerk | supabase
+  --styling <s>        tailwind   | shadcn   (shadcn ships the full Tailwind stack)
+  --interfaces <list>  auth-pages,dashboard,admin,landing
+  -y, --yes            skip the wizard, use flags + defaults
+  --ci                 non-interactive: implies --yes --no-install --no-git
+  --no-install         skip npm install
+  --no-git             skip git init
+```
+
+Run with no options for an interactive wizard (`@clack/prompts`).
+
+### Compatible by construction
+
+The dimensions are linked, so you can't assemble an incompatible stack. Picking a
+technology constrains the rest (MongoDB rules out Drizzle; Supabase Auth needs
+Postgres; shadcn implies Tailwind). Incompatible flag combinations are rejected
+with a clear message, and both the wizard and the [web configurator](#web-configurator)
+grey out options that clash with your current choices or aren't generatable yet.
+The catalogue + rules live in one place — `src/shared/registry.ts` — consumed by the
+CLI and mirrored into the web app.
+
+## How it works
+
+Stackr is **composition over templating**. A `template/base` Next.js app is copied,
+then each selected installer (`src/installers/*`) contributes:
+
+1. files copied from `template/extras/<feature>` into the project,
+2. dependencies / scripts pushed onto a shared `package.json` draft,
+3. environment variables pushed onto a shared `.env` accumulator.
+
+The orchestrator (`src/helpers/scaffoldProject.ts`) merges and writes everything once
+at the end. Adding a new option = add a `template/extras/<x>` folder + an
+`installers/<x>.ts` and register it — no engine changes. This is the
+[create-t3-app](https://create.t3.gg/) model.
+
+## Web configurator
+
+`web/` is a Next.js app (deployable to Vercel) that lets users pick a stack and copy the
+matching `create-stackrjs` command (npm / pnpm / yarn / bun).
+
+```bash
+cd web
+npm install
+npm run dev      # http://localhost:3000
+```
+
+The configurator reads the same option catalogue + compatibility rules as the CLI.
+`web/src/lib/stack.ts` is a mirror of `src/shared/registry.ts` (the deployable Next
+app imports no TypeScript from the engine); the `test/registry-sync.test.ts` suite
+fails if the two ever drift, so the registry stays the single source of truth.
+
+## Develop Stackr
+
+```bash
+npm install
+npm run build      # bundle the CLI with tsup -> dist/
+npm run typecheck  # type-check the engine
+npm run smoke      # generate every stack and verify each installs + builds
+node dist/index.js demo --ci   # try it locally
+```
+
+## Testing
+
+[Vitest](https://vitest.dev) suites live in `test/` (engine) and `web/test/` (configurator):
+
+```bash
+npm test            # engine: flags, selections, package.json/env merge, installers,
+                    # plus an integration test that scaffolds a project to a temp dir
+npm run smoke       # heavier: generate each stack (monolith, shadcn, microservices),
+                    # then npm install, tsc and build the output
+cd web && npm test  # the command builder
+```
+
+## CI/CD & automated releases
+
+Two GitHub Actions workflows:
+
+- **`.github/workflows/ci.yml`** — on every push/PR: typecheck, test and build the CLI
+  (Node 18/20/22) and the web app.
+- **`.github/workflows/release.yml`** — on push to `main`: runs the checks, then
+  [`semantic-release`](https://semantic-release.gitbook.io) versions, publishes to npm
+  (with provenance), tags, writes `CHANGELOG.md` and creates a GitHub Release —
+  **fully automatic, no manual version bumps**.
+
+The version is derived from your **commit messages** ([Conventional Commits](https://www.conventionalcommits.org)):
+
+| Commit prefix | Release |
+| ------------- | ------- |
+| `fix: ...` | patch (1.2.**3**) |
+| `feat: ...` | minor (1.**3**.0) |
+| `feat!: ...` or `BREAKING CHANGE:` in body | major (**2**.0.0) |
+| `chore:`, `docs:`, `test:`, `refactor:` ... | no release |
+
+### One-time setup
+
+1. Create the repo on GitHub and push `main`.
+2. Add an **`NPM_TOKEN`** secret (npm → Access Tokens → *Automation* token) under
+   *Settings → Secrets and variables → Actions*. `GITHUB_TOKEN` is provided automatically.
+
+That's it — from then on, just commit with the right prefix and merge to `main`. The
+published tarball is limited to `dist/` + `template/` (`files` in `package.json`; verify
+with `npm pack --dry-run`).
+
+## Roadmap
+
+Every dimension above ships at least two generatable options today. Next up:
+OAuth providers for the credentials stacks, third-party services (Stripe, Resend,
+…), more API styles and additional architectures. Each new option is a
+`template/extras/<x>` folder plus an `installers/<x>.ts` registered in
+`src/shared/registry.ts` — the installer engine absorbs them without a rewrite.