@clubedge/create-clubedge-app 0.4.0 → 0.5.0

package/dist/core/plan.js

@@ -1,7 +1,10 @@
-import { customizeAppManifest, customizeLegacySource, customizeLockfile, customizeReadme, customizeRootManifest, customizeSiteConfig, legacyBrandedFiles, } from "./customize.js";
+import { applyConditionals, customizeAppManifest, customizeLegacySource, customizeLockfile, customizeReadme, customizeRootManifest, customizeSiteConfig, legacyBrandedFiles, removePackageDependencies, } from "./customize.js";
 export class FrameworkError extends Error {
     name = "FrameworkError";
 }
+export class ModuleError extends Error {
+    name = "ModuleError";
+}
 const LOCKFILE = "pnpm-lock.yaml";
 const isWithin = (path, directory) => path === directory || path.startsWith(`${directory.replace(/\/$/, "")}/`);
 function isExcluded(path, exclude) {
@@ -17,6 +20,39 @@ export function selectFramework(manifest, requested) {
     }
     return { id, ...framework };
 }
+/**
+ * Resolves one option per module from the request and the defaults, then checks every
+ * option's requirements, so an invalid combination fails before anything is written.
+ */
+export function selectModules(manifest, requested = {}) {
+    const unknownModule = Object.keys(requested).find((id) => !manifest.modules[id]);
+    if (unknownModule !== undefined) {
+        const offered = Object.keys(manifest.modules);
+        throw new ModuleError(offered.length
+            ? `Unknown module "${unknownModule}". This Starter offers: ${offered.join(", ")}.`
+            : `This Starter does not offer module choices; remove --${unknownModule}.`);
+    }
+    const selection = {};
+    for (const [id, module] of Object.entries(manifest.modules)) {
+        const option = requested[id] ?? module.default;
+        if (!module.options[option]) {
+            throw new ModuleError(`Unknown ${id} option "${option}". Choose one of: ${Object.keys(module.options).join(", ")}.`);
+        }
+        selection[id] = option;
+    }
+    for (const [id, option] of Object.entries(selection)) {
+        const { name, requires } = manifest.modules[id].options[option];
+        for (const [requiredModule, allowed] of Object.entries(requires)) {
+            if (!allowed.includes(selection[requiredModule])) {
+                const needed = allowed
+                    .map((value) => `${manifest.modules[requiredModule].options[value].name} (--${requiredModule} ${value})`)
+                    .join(" or ");
+                throw new ModuleError(`${name} needs ${needed}.`);
+            }
+        }
+    }
+    return selection;
+}
 /**
  * Where a Starter file lands in the generated project, or null when it belongs to a framework
  * that was not selected. The selected app moves to `manifest.app`, and its environment example
@@ -32,27 +68,96 @@ function relocate(path, manifest, selected, others) {
     const belongsToOther = others.some((other) => isWithin(path, other.app) || path === other.envExample || path === other.dockerfile);
     return belongsToOther ? null : path;
 }
+/** Works out which files, packages, and variants the selected module options keep. */
+function resolveModuleFiles(manifest, selection) {
+    const ownedPaths = new Set();
+    const keptPaths = new Set();
+    const usedPackages = new Map();
+    const offeredPackages = new Map();
+    const variantSources = new Set();
+    /** Variant source path to the default file it replaces. */
+    const replacements = new Map();
+    for (const [id, module] of Object.entries(manifest.modules)) {
+        for (const [optionId, option] of Object.entries(module.options)) {
+            const selected = selection[id] === optionId;
+            for (const path of option.files) {
+                ownedPaths.add(path);
+                if (selected)
+                    keptPaths.add(path);
+            }
+            for (const [name, directory] of Object.entries(option.packages)) {
+                offeredPackages.set(name, directory);
+                if (selected)
+                    usedPackages.set(name, directory);
+            }
+            for (const [target, variant] of Object.entries(option.replace)) {
+                variantSources.add(variant);
+                if (selected)
+                    replacements.set(variant, target);
+            }
+        }
+    }
+    const removedPackages = [...offeredPackages].filter(([name]) => !usedPackages.has(name));
+    return {
+        removedPackageNames: removedPackages.map(([name]) => name),
+        removedPackageDirectories: removedPackages.map(([, directory]) => directory),
+        replacedTargets: new Set(replacements.values()),
+        replacements,
+        variantSources,
+        isDroppedOwnedPath: (path) => [...ownedPaths].some((owned) => isWithin(path, owned)) &&
+            ![...keptPaths].some((kept) => isWithin(path, kept)),
+    };
+}
 export function createPlan(input) {
     const { manifest, identity, source } = input;
     const framework = selectFramework(manifest, input.framework);
+    const selection = selectModules(manifest, input.modules);
     const others = Object.entries(manifest.frameworks)
         .filter(([id]) => id !== framework.id)
         .map(([, other]) => other);
     const multipleFrameworks = others.length > 0;
+    const moduleFiles = resolveModuleFiles(manifest, selection);
+    const modules = Object.entries(selection).map(([id, option]) => ({
+        id,
+        name: manifest.modules[id].name,
+        option,
+        optionName: manifest.modules[id].options[option].name,
+    }));
     const provenance = {
         cliVersion: input.cliVersion,
         starterRepository: source.repository,
         starterRef: source.ref,
         ...(source.commit ? { starterCommit: source.commit } : {}),
         ...(multipleFrameworks ? { framework: framework.id, frameworkName: framework.name } : {}),
+        ...(modules.length
+            ? {
+                modules: Object.fromEntries(modules.map(({ id, option }) => [id, option])),
+                moduleSummary: modules.map(({ name, optionName }) => `${name}: ${optionName}`),
+            }
+            : {}),
     };
+    const place = (path) => relocate(path, manifest, framework, others);
     const files = [];
     for (const file of source.files) {
-        if (isExcluded(file.to, manifest.exclude))
+        const path = file.to;
+        if (isExcluded(path, manifest.exclude))
             continue;
-        const to = relocate(file.to, manifest, framework, others);
-        if (to !== null && to !== manifest.env.target)
-            files.push({ from: file.from, to });
+        let target = path;
+        if (moduleFiles.variantSources.has(path)) {
+            // A variant is only ever copied over the default file it replaces.
+            const replaced = moduleFiles.replacements.get(path);
+            target = replaced === undefined ? null : place(replaced);
+        }
+        else if (moduleFiles.replacedTargets.has(path) ||
+            moduleFiles.isDroppedOwnedPath(path) ||
+            moduleFiles.removedPackageDirectories.some((directory) => isWithin(path, directory))) {
+            target = null;
+        }
+        else {
+            target = place(path);
+        }
+        if (target !== null && target !== manifest.env.target)
+            files.push({ from: file.from, to: target });
     }
     const has = (path) => files.some(({ to }) => to === path);
     const edits = [];
@@ -72,17 +177,43 @@ export function createPlan(input) {
             apply: (text) => customizeAppManifest(text, appPackage),
         });
     }
-    if (multipleFrameworks && has(LOCKFILE)) {
+    const { removedPackageNames, removedPackageDirectories } = moduleFiles;
+    if (removedPackageNames.length) {
+        for (const { to } of files) {
+            if (to === "package.json" || !to.endsWith("/package.json"))
+                continue;
+            edits.push({
+                path: to,
+                description: `Drop dependencies on left-out packages`,
+                apply: (text) => removePackageDependencies(text, removedPackageNames),
+            });
+        }
+    }
+    if ((multipleFrameworks || removedPackageNames.length) && has(LOCKFILE)) {
         const changes = {
-            remove: others.map((other) => other.app).filter((app) => app !== framework.app),
+            remove: [...others.map((other) => other.app).filter((app) => app !== framework.app), ...removedPackageDirectories],
             ...(framework.app !== manifest.app ? { rename: { from: framework.app, to: manifest.app } } : {}),
+            removeDependencies: removedPackageNames,
         };
         edits.push({
             path: LOCKFILE,
-            description: `Keep only the ${framework.name} app in the lockfile`,
+            description: removedPackageNames.length
+                ? `Keep only the ${framework.name} app and the selected modules in the lockfile`
+                : `Keep only the ${framework.name} app in the lockfile`,
             apply: (text) => customizeLockfile(text, changes),
         });
     }
+    const context = { framework: framework.id, ...selection };
+    for (const path of manifest.conditional) {
+        const target = moduleFiles.replacedTargets.has(path) ? null : place(path);
+        if (target === null || !has(target))
+            continue;
+        edits.push({
+            path: target,
+            description: "Keep the sections for the selected framework and modules",
+            apply: (text) => applyConditionals(text, context, target),
+        });
+    }
     if (has("README.md")) {
         edits.push({
             path: "README.md",
@@ -111,6 +242,7 @@ export function createPlan(input) {
         identity,
         provenance,
         framework: { id: framework.id, name: framework.name },
+        modules,
         files,
         edits,
         envFile: has(manifest.env.example) ? { from: manifest.env.example, to: manifest.env.target } : null,
@@ -122,6 +254,9 @@ export function describePlan(plan) {
     return [
         `Create ${plan.targetDirectory}`,
         ...(plan.provenance.framework ? [`Use ${plan.framework.name}`] : []),
+        ...(plan.modules.length
+            ? [`Use ${plan.modules.map(({ name, optionName }) => `${name}: ${optionName}`).join(", ")}`]
+            : []),
         `Copy ${plan.files.length} files from ${plan.provenance.starterRepository}@${plan.provenance.starterRef}` +
             (plan.provenance.starterCommit ? ` (${plan.provenance.starterCommit.slice(0, 8)})` : ""),
         ...plan.edits.map((edit) => `Edit ${edit.path}: ${edit.description}`),

package/dist/index.js

@@ -1,4 +1,4 @@
-import { cancel, intro, isCancel, log, outro, select, spinner, text } from "@clack/prompts";
+import { cancel, confirm, intro, isCancel, log, outro, select, spinner, text } from "@clack/prompts";
 import { relative, resolve } from "node:path";
 import process from "node:process";
 import { parseCliArgs, UsageError } from "./cli/args.js";
@@ -51,6 +51,49 @@ async function chooseFramework(manifest, requested, interactive) {
     });
     return isCancel(value) ? null : value;
 }
+/**
+ * Module options from flags, plus prompts for the rest when the visitor wants to customize.
+ * Options whose requirements are not met by earlier answers are not offered. Returns null
+ * when a prompt is cancelled.
+ */
+async function chooseModules(manifest, requested, interactive) {
+    const unasked = Object.keys(manifest.modules).filter((id) => requested[id] === undefined);
+    if (!interactive || unasked.length === 0)
+        return requested;
+    const customize = await confirm({
+        message: "Customize the included services (auth, storage, cache)?",
+        initialValue: false,
+    });
+    if (isCancel(customize))
+        return null;
+    if (!customize)
+        return requested;
+    const chosen = { ...requested };
+    for (const [id, module] of Object.entries(manifest.modules)) {
+        if (chosen[id] !== undefined)
+            continue;
+        const available = Object.entries(module.options).filter(([, option]) => Object.entries(option.requires).every(([other, allowed]) => {
+            const value = chosen[other] ?? requested[other];
+            // Modules answered later are checked when the plan is created.
+            return value === undefined || allowed.includes(value);
+        }));
+        const value = await select({
+            message: module.name,
+            initialValue: available.some(([optionId]) => optionId === module.default)
+                ? module.default
+                : available[0][0],
+            options: available.map(([optionId, option]) => ({
+                value: optionId,
+                label: option.name,
+                ...(optionId === module.default ? { hint: "default" } : {}),
+            })),
+        });
+        if (isCancel(value))
+            return null;
+        chosen[id] = value;
+    }
+    return chosen;
+}
 async function createProject(args) {
     const interactive = Boolean(process.stdin.isTTY) && !args.yes;
     const requested = args.projectDirectory ?? (interactive ? await askProjectDirectory() : "my-app");
@@ -75,12 +118,18 @@ async function createProject(args) {
             cancel("Operation cancelled.");
             return;
         }
+        const modules = await chooseModules(manifest, args.modules, interactive);
+        if (modules === null) {
+            cancel("Operation cancelled.");
+            return;
+        }
         const plan = createPlan({
             targetDirectory,
             identity,
             source,
             manifest,
             framework,
+            modules,
             cliVersion,
             git: args.git,
             install: args.install,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/create-clubedge-app",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Create a Next.js or TanStack Start application from the Clubedge Starter reference implementation.",
   "type": "module",
   "packageManager": "pnpm@10.9.0",
@@ -22,8 +22,8 @@
   },
   "clubedge": {
     "starterRepository": "Clubedge/clubedge-starter",
-    "starterRef": "v0.4.0",
-    "starterCommit": "fc01d33bb1a3944e099a1750679be87a96ff9a22"
+    "starterRef": "v0.5.0",
+    "starterCommit": "d9375c2c3b520323ff0255ef8ec65da19251c3c1"
   },
   "license": "Apache-2.0",
   "repository": {

package/template/.env.example

@@ -1,25 +1,38 @@
 NODE_ENV=development
 NEXT_PUBLIC_APP_URL=http://localhost:3000
 
-# Supabase PostgreSQL: use the transaction pooler with prepare disabled (configured in src/db).
+# Supabase PostgreSQL: use the transaction pooler with prepare disabled (configured in packages/db).
 DATABASE_URL=postgresql://postgres.[project-ref]:[password]@aws-0-[region].pooler.supabase.com:6543/postgres
 
+# clubedge:if auth=supabase
 # Supabase Auth (publishable key only; never put a service role key in the browser)
 NEXT_PUBLIC_SUPABASE_URL=
 NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=
+# clubedge:end
 
-# Optional cache and rate limits (Redis protocol; rediss:// enables TLS)
-# Upstash example: rediss://default:YOUR_PASSWORD@your-database.upstash.io:6379
+# clubedge:if auth=better-auth
+# Better Auth keeps users and sessions in DATABASE_URL (run pnpm db:migrate first).
+# Generate a secret with: openssl rand -base64 32
+BETTER_AUTH_SECRET=
+# clubedge:end
+
+# clubedge:if cache=redis
+# Optional cache and rate limits (Redis protocol; rediss:// enables TLS). Without it, both use
+# process memory. Upstash example: rediss://default:YOUR_PASSWORD@your-database.upstash.io:6379
 REDIS_URL=
+# clubedge:end
 
-# Storage adapter: s3 (works with AWS S3 and Cloudflare R2) or supabase
-STORAGE_PROVIDER=s3
+# clubedge:if storage=s3
+# S3-compatible storage (AWS S3, Cloudflare R2, MinIO)
 STORAGE_BUCKET=
 STORAGE_REGION=auto
 STORAGE_ENDPOINT=
 STORAGE_ACCESS_KEY_ID=
 STORAGE_SECRET_ACCESS_KEY=
 STORAGE_PUBLIC_URL=
+# clubedge:end
 
-# Supabase Storage adapter
+# clubedge:if storage=supabase
+# Supabase Storage bucket, accessed with the signed-in user's Supabase session
 SUPABASE_STORAGE_BUCKET=
+# clubedge:end

package/template/.github/workflows/ci.yml

@@ -23,35 +23,28 @@ jobs:
       - run: pnpm lint
       - run: pnpm typecheck
       - run: pnpm test
-      # Generated projects build with the env example copied into place; build the same way.
-      - run: cp .env.example apps/web/.env.local && cp apps/start/.env.example apps/start/.env.local
+      # Build the way the app is developed: with the env example copied into place.
+      - run: cp .env.example apps/web/.env.local
       - run: pnpm build
-      - name: Serve both production builds
+      - name: Serve the production build
         run: |
           set -euo pipefail
-          PORT=3001 pnpm --filter @clubedge/web start > "$RUNNER_TEMP/web.log" 2>&1 &
-          PORT=3002 pnpm --filter @clubedge/start start > "$RUNNER_TEMP/start.log" 2>&1 &
-          trap 'tail -n 50 "$RUNNER_TEMP/web.log" "$RUNNER_TEMP/start.log"' EXIT
-          for port in 3001 3002; do
-            for attempt in $(seq 1 30); do
-              curl --fail --silent --output /dev/null "http://127.0.0.1:$port/api/health" && break
-              sleep 1
-            done
-            for path in / /login /dashboard /api/health; do
-              curl --fail --silent --show-error --output /dev/null "http://127.0.0.1:$port$path"
-            done
+          pnpm start > "$RUNNER_TEMP/app.log" 2>&1 &
+          trap 'tail -n 50 "$RUNNER_TEMP/app.log"' EXIT
+          for attempt in $(seq 1 30); do
+            curl --fail --silent --output /dev/null http://127.0.0.1:3000/api/health && break
+            sleep 1
+          done
+          for path in / /dashboard /api/health; do
+            curl --fail --silent --show-error --output /dev/null "http://127.0.0.1:3000$path"
           done
+          # clubedge:if auth!=none
+          curl --fail --silent --show-error --output /dev/null http://127.0.0.1:3000/login
+          # clubedge:end
       - run: pnpm audit --audit-level high
 
-  # The same browser suite runs against every framework.
   e2e:
     runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        app: [web, start]
-    env:
-      E2E_APP: ${{ matrix.app }}
     steps:
       - uses: actions/checkout@v4
       - uses: pnpm/action-setup@v4
@@ -65,26 +58,16 @@ jobs:
 
   docker:
     runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - app: web
-            build: docker build --tag clubedge-starter:ci .
-          - app: start
-            build: >-
-              docker build --tag clubedge-starter:ci --file apps/start/Dockerfile
-              --build-arg APP_DIR=apps/start --build-arg APP_PACKAGE=@clubedge/start .
     steps:
       - uses: actions/checkout@v4
       - name: Build the production image
-        run: ${{ matrix.build }}
+        run: docker build --tag app:ci .
       - name: Start the image and check health
         run: |
           set -euo pipefail
           docker run --detach --name app --publish 3000:3000 \
             --env DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:5432/postgres \
-            clubedge-starter:ci
+            app:ci
           trap 'docker logs app; docker rm --force app' EXIT
           for attempt in $(seq 1 30); do
             if curl --fail --silent http://127.0.0.1:3000/api/health; then

package/template/AGENTS.md

@@ -2,14 +2,19 @@
 
 ## Architecture rules
 
-- `packages/{core,auth,cache,db,storage}` are framework-agnostic. Never import `next`, `react`, `server-only`, `@tanstack/*`, or app code (`@/…`) there. Accept configuration, clients, and cookies as function arguments.
+- Every package except `packages/ui` is framework-agnostic. Never import `next`, `react`, `server-only`, `@tanstack/*`, or app code (`@/…`) there. Accept configuration, clients, and cookies as function arguments.
+- Interfaces live in `packages/{auth,storage,cache}`; each provider is its own package holding that provider's SDK, so replacing a provider means swapping one package. Keep provider SDKs out of the interface packages.
+- Each provider module in `src/server/` validates its own environment variables with `parseEnv`; `src/env/server.ts` holds only the core variables.
 - `packages/core` depends on no other workspace package.
-- Each app's `src/server/` is its composition root: the only place that reads environment variables, bridges the framework's cookies to `CookieStore`, and picks providers. Routes, server actions, server functions, and components import from `@/server/*`, never from `@supabase/*`, `@aws-sdk/*`, `redis`, or `postgres`.
-- `apps/web` (Next.js) and `apps/start` (TanStack Start) are the same product. Make user-facing changes in both, keep their markup and redirects identical, and run the shared browser suite against each (`E2E_APP=start pnpm test:e2e`).
+- The app's `src/server/` is its composition root: the only place that reads environment variables, bridges the framework's cookies to `CookieStore`, and picks providers. Routes, server actions, server functions, and components import from `@/server/*`, never from a provider SDK such as `@supabase/*`, `@aws-sdk/*`, `redis`, or `postgres`.
+- `apps/web` (Next.js) and `apps/start` (TanStack Start) are the same product. Make user-facing changes in both, keep their markup and redirects identical, and run the shared browser suite against each (`E2E_APP=start pnpm test:e2e`). <!-- clubedge:only starter-repository -->
+- Files listed under `conditional` in `clubedge.template.json` contain `clubedge:if` blocks and `clubedge:only` lines that create-clubedge-app keeps or drops per framework and module. Keep every block present for the default selection, and use a file under `variants/` when two options need different code. <!-- clubedge:only starter-repository -->
 - Expected failures (bad credentials, invalid codes) are returned as `Result` values from `@clubedge/core`; exceptions are for unexpected errors.
-- Project identity (name, description, links) lives in each app's `src/config/site.json` (keep them identical); `create-clubedge-app` rewrites that file, so do not hard-code the project name elsewhere.
+- Project identity (name, description, links) lives in `src/config/site.json`, so do not hard-code the project name elsewhere.
 - `pnpm lint` enforces these boundaries. Run `pnpm lint`, `pnpm typecheck`, and `pnpm test` before finishing a change.
 
+<!-- clubedge:if framework=next -->
+
 <!-- BEGIN:nextjs-agent-rules -->
 
 ## This is NOT the Next.js you know
@@ -20,6 +25,8 @@ This block is written and re-added by `next dev` — verify at `node_modules/nex
 
 <!-- END:nextjs-agent-rules -->
 
+<!-- clubedge:end -->
+
 <!-- BEGIN:turborepo-agent-rules -->
 
 # This is NOT the Turborepo you know

package/template/CONTRIBUTING.md

@@ -33,7 +33,7 @@ Run `pnpm test:e2e` for changes that affect browser behavior. It requires a loca
 
 ## Project conventions
 
-- Keep application code in `apps/web` (Next.js) and `apps/start` (TanStack Start), reusable shadcn/ui code in `packages/ui`, and framework-agnostic infrastructure in `packages/{core,auth,db,storage,cache}`. A user-facing change belongs in both apps.
+- Keep application code in `apps/web` (Next.js) and `apps/start` (TanStack Start), reusable shadcn/ui code in `packages/ui`, and framework-agnostic interfaces in `packages/{core,auth,db,storage,cache}` with each provider in its own package (`auth-supabase`, `storage-s3`, `storage-supabase`, `cache-redis`). A user-facing change belongs in both apps.
 - Reach providers through each app's `src/server` rather than scattering provider SDK calls through routes and components. `pnpm lint` enforces these boundaries.
 - Keep server secrets out of client code and out of committed files. Update `.env.example` when adding configuration, using placeholders only.
 - For database changes, update the Drizzle schema and generate, review, and commit the migration. Do not maintain a second migration history for the same application tables.