@alfredmouelle/create-stack 0.1.0 → 0.1.1

package/README.md

@@ -1,56 +1,122 @@
 # create-stack
 
-Interactive, **deterministic** installer for the reference stack — the non-LLM
-counterpart of the `bootstrap` skill's CREATE mode. It forks a base app
-(`apps/tanstack-base` or `apps/next-base`) and strips it down to your selection.
+> `@alfredmouelle/create-stack`
 
-## Usage
+Interactive, **deterministic** project installer. It forks a fully-wired base app
+(**Next.js App Router** or **TanStack Start**) and strips it down to exactly the
+foundations and provider you pick — Drizzle, tRPC, better-auth, data tables and a
+mailer — then stamps identity, generates `.env`, initializes git and verifies the
+result (typecheck + Biome).
+
+No template guesswork: the output is a real, buildable app from day one.
+
+## Quick start
 
 ```bash
-# from anywhere
-node /path/to/stack/cli/index.mjs my-app
+pnpm dlx @alfredmouelle/create-stack my-app
+# or, using the create-* convention:
+pnpm create @alfredmouelle/stack my-app
+# npm / yarn:
+npm create @alfredmouelle/stack my-app
+yarn create @alfredmouelle/stack my-app
+```
+
+Run with no extra flags → an **interactive wizard** asks every question. Pass any
+selection flag → **non-interactive** mode (scriptable / CI).
+
+## Requirements
+
+- **Node** ≥ 22
+- **pnpm** (the generated project is a pnpm project)
+- **git** and **rsync** available on `PATH` (macOS/Linux ship both)
+
+## Usage
 
-# from the stack repo
-pnpm create-stack my-app
 ```
+create-stack [project] [flags]
+```
+
+`project` is the target directory (and default package name). It must be empty or
+not exist yet. In non-interactive mode it is required.
 
-The wizard asks for:
+### Flags
 
-- **Framework** — TanStack Start or Next.js (App Router)
-- **Foundations** — Drizzle, tRPC, better-auth, data-table (hard deps resolved:
-  tRPC/better-auth ⇒ Drizzle; better-auth ⇒ mailer)
-- **Mailer provider** — Resend, Brevo, Amazon SES (or none, if no better-auth)
-- **Extra capabilities** — storage, jobs, cache, … (added afterwards via the
-  `add-capability` skill; not baked into the base)
+| Flag | Values | Default | Description |
+| --- | --- | --- | --- |
+| `--framework` | `tanstack` \| `next` | `tanstack` | Base app to fork. |
+| `--foundations` | csv of `drizzle,trpc,better-auth,data-table` | all | Foundations to keep; the rest are stripped. |
+| `--mailer` | `resend` \| `brevo` \| `ses` \| `none` | `resend` | Mailer provider. `none` is rejected when `better-auth` is kept. |
+| `--caps` | csv of capability names | — | Extra capabilities to add afterwards via `add-capability` (see below). |
+| `--no-install` | — | install on | Skip `pnpm install` + verification. |
+| `--yes`, `-y` | — | — | Non-interactive with all defaults. |
 
-Then it forks, strips unselected foundations, swaps the mailer adapter, stamps
-identity, generates `.env(.example)`, and optionally installs + verifies
-(typecheck + Biome).
+Passing any of `--framework`, `--foundations`, `--mailer`, `--caps` or
+`--no-install` (or `--yes`) switches the CLI to non-interactive mode; missing
+values fall back to the defaults above.
 
-## How it works
+### Dependency resolution
 
-- **Single source of truth**: the base apps (`apps/*-base`) hold the real code;
-  the `patterns/*/pattern.json` manifests drive deps/scripts/env/file lists.
-- **Deterministic strip**: whole-directory deletes + dep/env/script diffs from the
-  manifests, plus a few hardcoded code *seams* (tRPC↔auth context, root provider
-  wiring) handled via shipped reduced variants in `templates/`.
-- If you edit a seam file in a base app (`server/api/trpc.ts`, the root
-  `router.tsx` / `__root.tsx` / `layout.tsx`, the schema barrel), update the
-  matching transform in `lib/strip.mjs` or the `templates/` variant.
+Selections are normalized for you:
 
-## Layout
+- `trpc` ⇒ pulls in `drizzle`
+- `better-auth` ⇒ pulls in `drizzle` **and** forces a real mailer (not `none`)
+
+### Examples
+
+```bash
+# Full interactive wizard
+pnpm dlx @alfredmouelle/create-stack my-app
 
+# Everything, defaults (TanStack Start + all foundations + Resend), no questions
+pnpm dlx @alfredmouelle/create-stack my-app --yes
+
+# Next.js with just Drizzle + tRPC, Amazon SES mailer, don't install
+pnpm dlx @alfredmouelle/create-stack api --framework next \
+  --foundations drizzle,trpc --mailer ses --no-install
+
+# Minimal: Drizzle only, no mailer
+pnpm dlx @alfredmouelle/create-stack db-svc --foundations drizzle --mailer none
+
+# TanStack + auth, and queue up extra capabilities for later
+pnpm dlx @alfredmouelle/create-stack app --foundations drizzle,trpc,better-auth \
+  --caps storage,jobs
 ```
-cli/
-  index.mjs          wizard (prompts) + install/verify + report
-  lib/
-    build.mjs        pure build phase (fork → strip → mailer → env → identity)
-    manifests.mjs    load patterns + capabilities; logical→manifest mapping
-    scaffold.mjs     fork base app, make it standalone
-    strip.mjs        reverse-strip unselected foundations + code seams
-    mailer.mjs       mailer provider swap
-    env.mjs          rebuild src/env.ts blocks + generate .env files
-    identity.mjs     title/meta + README with the # Author footer
-    util.mjs         fs / exec / package.json helpers
-  templates/         reduced "no-trpc" root-wiring variants
+
+## What you get
+
+- **Framework** — Next.js App Router *or* TanStack Start, fully wired (SSR, routing).
+- **Drizzle ORM** — Postgres client, schema barrel, keyset pagination, seed harness.
+- **tRPC v11** — typed API, SSR/RSC integration, health router.
+- **better-auth** — email+password + verification, optional Google OAuth, session
+  guards, auth UI pages.
+- **Mailer** — Resend / Brevo / SES behind one port; React Email templates.
+- **Data tables** — TanStack Table primitives (DataTable, InfiniteDataTable, …).
+- **Baseline** — Tailwind v4 + shadcn, Geist, theme toggle, strict Biome, typed
+  env (`src/env.ts`), Dockerfile, a generated `.gitignore` and `.env`/`.env.example`.
+
+Unselected foundations are removed cleanly (files, deps, env vars and wiring),
+and the project is left **bootable and green** (typecheck + Biome).
+
+## Extra capabilities
+
+`--caps` lists capabilities that aren't baked into the base (storage, jobs, cache,
+logger, analytics, error-tracking, http). They are **not** scaffolded by this CLI;
+the final report prints the follow-up to add them with the `add-capability` skill.
+Mailer is the exception — it's built in and chosen via `--mailer`.
+
+## After scaffolding
+
+```bash
+cd my-app
+pnpm install            # only if you passed --no-install
+cp .env.example .env    # fill in the values
+pnpm dev
 ```
+
+## Notes
+
+- The published package is **self-contained**: the base apps, pattern manifests
+  and mailer adapters are bundled at publish time, so `pnpm dlx` needs nothing but
+  this package.
+- The generated project is a fresh git repo (`git init`, files staged) — make your
+  first commit when ready.

package/_stack/apps/next-base/src/emails/components/components.tsx

@@ -1,3 +1,5 @@
+'use client'
+
 import { Body, Container, Head, Html, Link, Preview, Section, Tailwind, Text } from 'react-email'
 import { EmailThemeProvider, useEmailTheme } from './context'
 import { createEmailTheme, type EmailTheme, type EmailThemeOverride } from './theme'

package/_stack/apps/next-base/src/emails/components/context.tsx

@@ -1,3 +1,5 @@
+'use client'
+
 import { createContext, useContext } from 'react'
 import { defaultTheme, type EmailTheme } from './theme'
 

package/_stack/apps/tanstack-base/src/server/better-auth/session.ts

@@ -2,8 +2,16 @@ import { createServerFn } from '@tanstack/react-start'
 import { getRequest } from '@tanstack/react-start/server'
 import { auth } from '.'
 
-/** Raw session lookup from the current request headers (server-side). */
-export const getSession = async () => auth.api.getSession({ headers: getRequest().headers })
-
-/** Server-function wrapper for route loaders / `beforeLoad`. */
-export const getServerSession = createServerFn({ method: 'GET' }).handler(() => getSession())
+/**
+ * Server-function: resolves the better-auth session from the current request
+ * headers. Use it in route loaders / `beforeLoad`.
+ *
+ * The server-only `getRequest` call lives INSIDE the handler on purpose: the
+ * TanStack Start plugin extracts the handler server-side and strips this import
+ * from the client bundle. A standalone module-scope helper that calls
+ * `getRequest` would leak `@tanstack/react-start/server` into client code (it's
+ * imported transitively by routes) and trip the import-protection plugin.
+ */
+export const getServerSession = createServerFn({ method: 'GET' }).handler(() =>
+  auth.api.getSession({ headers: getRequest().headers }),
+)

package/index.mjs

@@ -173,6 +173,12 @@ function execute(a, patterns) {
     )
   }
 
+  // Initialize a fresh repo (also satisfies Biome's vcs.useIgnoreFile).
+  if (run('git', ['init', '-q'], { cwd: projectDir })) {
+    run('git', ['-C', projectDir, 'add', '-A'])
+    p.log.step('git initialized')
+  }
+
   const keptMailer = a.mailerProvider !== 'none'
   const lines = [
     `Framework: ${a.framework === 'next' ? 'Next.js' : 'TanStack Start'}`,

package/lib/build.mjs

@@ -30,7 +30,7 @@ export function buildProject({
   const keptMailer = mailerProvider !== 'none'
 
   forkBase(framework, projectDir)
-  makeStandalone(projectDir, projectName)
+  makeStandalone(projectDir, projectName, framework)
 
   const strip = stripFoundations({ projectDir, framework, kept, keptMailer, patterns })
   const mailer = keptMailer

package/lib/scaffold.mjs

@@ -22,6 +22,58 @@ const PNPM_WORKSPACE = `allowBuilds:
   lightningcss: true
 `
 
+// Generated explicitly: npm strips `.gitignore` from published tarballs, so we
+// can't rely on the bundled base app's copy surviving. Both keep `.env.example`.
+const GITIGNORE = {
+  tanstack: `node_modules
+.DS_Store
+dist
+dist-ssr
+*.local
+.env
+.nitro
+.tanstack
+.wrangler
+.output
+.vinxi
+__unconfig*
+`,
+  next: `# dependencies
+/node_modules
+/.pnp
+.pnp.*
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+.pnpm-debug.log*
+
+# env files (keep .env.example committed)
+.env
+.env*.local
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+`,
+}
+
 /** Copy the base app into projectDir, minus build output & generated files. */
 export function forkBase(framework, projectDir) {
   const base = join(STACK_ROOT, 'apps', framework === 'next' ? 'next-base' : 'tanstack-base')
@@ -32,11 +84,14 @@ export function forkBase(framework, projectDir) {
   if (!run('rsync', args)) throw new Error('rsync failed while forking the base app')
 }
 
-/** Make the fork standalone (Biome, pnpm workspace, package.json identity). */
-export function makeStandalone(projectDir, projectName) {
+/** Make the fork standalone (Biome, pnpm workspace, .gitignore, identity). */
+export function makeStandalone(projectDir, projectName, framework) {
   // A fork needs its own Biome config (the base inherits the monorepo root's).
   copy(join(STACK_ROOT, 'patterns/_baseline/biome.jsonc'), join(projectDir, 'biome.jsonc'))
 
+  // Biome's vcs.useIgnoreFile needs a .gitignore; also good project hygiene.
+  write(join(projectDir, '.gitignore'), GITIGNORE[framework === 'next' ? 'next' : 'tanstack'])
+
   // Avoid ERR_PNPM_IGNORED_BUILDS on a fresh install (native build scripts).
   write(join(projectDir, 'pnpm-workspace.yaml'), PNPM_WORKSPACE)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alfredmouelle/create-stack",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "description": "Interactive, deterministic installer for the personal reference stack — forks a base app (Next.js / TanStack Start) and strips it to your selection.",
   "author": {