@clubedge/create-clubedge-app 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to `create-clubedge-app` are documented here.
 
+## 0.4.0
+
+- Default to Starter `v0.4.0`, which adds the TanStack Start app and template schema 2.
+- Add `--framework next|tanstack-start`, and ask which framework to use when the Starter offers several. Next.js stays the default.
+- Read template schema 2, which describes each framework's app, environment example, and Dockerfile. The selected app is moved to `apps/web`, the others are left out, and `pnpm-lock.yaml` is kept in step so frozen installs work.
+- Record the chosen framework in the generated `package.json` and `README.md`.
+- Test generated projects for both frameworks in CI and in the release smoke test.
+
+## 0.3.0
+
+- Default to Starter `v0.3.0`, which adds the `clubedge.template.json` template manifest.
+- Rewrite the CLI in TypeScript, organized into argument parsing, planning, execution, and steps.
+- Bundle the pinned Starter release into the package. The default scaffold no longer downloads from GitHub or requires Git.
+- Read the Starter's `clubedge.template.json` manifest and refuse Starters with a newer template schema.
+- Add `--dry-run`, `--yes`, and `--template-dir`.
+- Remove everything written when scaffolding fails, instead of leaving a partial project.
+- Check the Node.js version before starting, and fall back to `corepack pnpm` when `pnpm` is not on the path.
+- Never copy local environment files, dependencies, or build output from a template directory, even when it sits inside another Git repository.
+
 ## 0.2.1
 
 - Publish the default Starter pin in the `clubedge` field of `package.json`. The CLI and release workflow read it from there, and the npm registry exposes it so the website always shows the Starter each CLI version scaffolds.

package/README.md

@@ -3,7 +3,7 @@
 [![CI](https://github.com/Clubedge/create-clubedge-app/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Clubedge/create-clubedge-app/actions/workflows/ci.yml)
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)
 
-Create a Next.js application from the [Clubedge Starter](https://github.com/Clubedge/clubedge-starter) reference implementation.
+Create a Next.js or TanStack Start application from the [Clubedge Starter](https://github.com/Clubedge/clubedge-starter) reference implementation.
 
 The CLI downloads a tested Starter release, names the generated project, creates `apps/web/.env.local` from the example, initializes Git, and installs dependencies. The Starter remains the source of truth for the generated architecture.
 
@@ -12,34 +12,34 @@ The CLI downloads a tested Starter release, names the generated project, creates
 Each CLI release is tested against one specific Starter release:
 
 ```text
-create-clubedge-app v0.2.1
+create-clubedge-app v0.4.0
         |
         v
-Clubedge Starter v0.2.0
-commit db15901da90d8d8a190d158c895dfe76c172b415
+Clubedge Starter v0.4.0
+commit fc01d33bb1a3944e099a1750679be87a96ff9a22
 ```
 
 The current relationship is:
 
 | CLI release | Default Starter release | Meaning |
 | --- | --- | --- |
-| `create-clubedge-app@0.2.1` | `clubedge-starter@v0.2.0` | The CLI's required, tested default |
+| `create-clubedge-app@0.4.0` | `clubedge-starter@v0.4.0` | The CLI's required, tested default |
 
 This means the same CLI version always scaffolds the same Starter revision by default. The CLI does not silently follow Starter `main`.
 
-The `v0.2.0` tag is expected to resolve to commit
-`db15901da90d8d8a190d158c895dfe76c172b415`. The CLI verifies this before
+The `v0.4.0` tag is expected to resolve to commit
+`fc01d33bb1a3944e099a1750679be87a96ff9a22`. The CLI verifies this before
 scaffolding with the default reference and fails rather than silently using a
 moved tag.
 
-When the Starter changes, its maintainers first publish a new versioned release, such as `v0.2.0`. The CLI is then updated to use that release, all generated-project checks must pass, and a new CLI version is published. This keeps Starter and CLI releases independently versioned while preserving a tested compatibility relationship.
+When the Starter changes, its maintainers first publish a new versioned release, such as `v0.4.0`. The CLI is then updated to use that release, all generated-project checks must pass, and a new CLI version is published. This keeps Starter and CLI releases independently versioned while preserving a tested compatibility relationship.
 
 ## Requirements
 
 - Node.js 22.12 or newer.
-- pnpm 10.9.0 or newer (the generated starter uses Corepack and pnpm).
+- pnpm 10.9.0 or newer. The generated project is a pnpm workspace, so dependencies are installed with pnpm even when you start the CLI with `npx`; the CLI falls back to `corepack pnpm` when `pnpm` is not on your path.
 - Git, when using the default Git initialization.
-- Internet access to download the starter from GitHub and install dependencies.
+- Internet access to install dependencies. The default Starter release ships inside the CLI package, so GitHub is only contacted for `--ref`.
 
 ## Usage
 
@@ -68,58 +68,89 @@ When no destination is provided, the CLI asks where to create the project:
 pnpm dlx @clubedge/create-clubedge-app
 ```
 
-## Options
+### Choosing a framework
 
-```text
-Usage: pnpm dlx @clubedge/create-clubedge-app [project-directory] [options]
+The Starter ships the same application for two React frameworks. Next.js is the default; pick TanStack Start with `--framework`, or choose interactively when the Starter offers more than one:
 
---ref <ref>            Select a starter tag, branch, or commit (default: v0.2.0)
---no-install           Skip pnpm install
---no-git               Skip Git initialization
--h, --help             Show help
--v, --version          Show the CLI version
+```sh
+pnpm dlx @clubedge/create-clubedge-app my-app --framework tanstack-start
 ```
 
-Examples:
+| `--framework`    | App                         | Production output             |
+| ---------------- | --------------------------- | ----------------------------- |
+| `next`           | Next.js App Router          | Next.js standalone build      |
+| `tanstack-start` | TanStack Start with Vite    | Nitro `.output` server bundle |
 
-```sh
-pnpm dlx @clubedge/create-clubedge-app my-app --ref <starter-tag-or-commit>
-pnpm dlx @clubedge/create-clubedge-app my-app --no-install
-```
+Either way, the app lives in `apps/web` and uses the same shared packages, so the project layout, root scripts, and Docker commands are identical.
 
-The target directory must be empty or not exist. The CLI will not delete or overwrite files in a non-empty target directory. The default is the tested `v0.2.0` Starter release, so the same CLI version produces the same Starter revision. Use `--ref` to explicitly select a tag, branch, or commit.
+## Options
 
-The default is the tested Starter release tag `v0.2.0`. Every generated project records its CLI version, Starter repository, exact Starter ref, and resolved Starter commit in `package.json` and `README.md`.
+```text
+Usage: pnpm dlx @clubedge/create-clubedge-app [project-directory] [options]
+
+--framework <id>        App framework: next (default) or tanstack-start
+--ref <ref>             Download this Starter tag, branch, or commit from GitHub instead
+--template-dir <path>   Scaffold from a local Starter checkout (for Starter development)
+--dry-run               Show what would be created without writing anything
+-y, --yes               Accept defaults and never prompt (default directory: my-app)
+--no-install            Skip dependency installation
+--no-git                Skip Git initialization
+-h, --help              Show help
+-v, --version           Show the CLI version
+```
 
-Use `--ref` only when you intentionally want a different Starter revision:
+The target directory must be empty or not exist. The CLI never deletes or overwrites existing files, and if scaffolding fails it removes whatever it wrote, so a failed run leaves nothing behind.
+
+Every generated project records its CLI version, Starter repository, Starter ref, Starter commit, and framework in `package.json` and `README.md`.
 
 ```sh
-# Reproduce the supported default
-pnpm dlx @clubedge/create-clubedge-app my-app
+# Preview the files and edits without writing anything
+pnpm dlx @clubedge/create-clubedge-app my-app --dry-run
+
+# Non-interactive, for scripts and CI
+pnpm dlx @clubedge/create-clubedge-app my-app --yes --no-git --framework tanstack-start
 
 # Try an unreleased Starter change
 pnpm dlx @clubedge/create-clubedge-app my-app --ref main
 
 # Reproduce a specific Starter release or commit
-pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.2.0
+pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.4.0
 pnpm dlx @clubedge/create-clubedge-app my-app --ref <commit-sha>
+
+# Test local Starter changes before releasing them
+pnpm dlx @clubedge/create-clubedge-app my-app --template-dir ../clubedge-starter
 ```
 
 ## How it works
 
-This CLI scaffolds the complete reference Starter. It does not yet offer selectable SaaS, dashboard, or minimal feature presets; those should be added once each preset has a distinct, maintained template. This keeps CLI output aligned with the Starter repository instead of creating a second, drifting copy of its source.
+Each CLI release bundles one Starter release. When the release is built, `scripts/bundle-template.mjs` clones the pinned Starter tag, verifies that it resolves to the pinned commit, and copies its tracked files into the package (`template/` and `template.lock.json`). Running the CLI then needs no GitHub access for the default Starter.
+
+The Starter describes itself in `clubedge.template.json`: its app directory, site config, environment files, Docker image name, and files that stay out of generated projects. Schema 2 manifests also list each framework's app directory, environment example, and Dockerfile. The CLI moves the selected framework's app to `apps/web` (renaming its package to `@clubedge/web`), moves its environment example and Dockerfile to the project root, leaves the other frameworks out, and removes their entries from `pnpm-lock.yaml` so `pnpm install --frozen-lockfile` keeps working. The CLI refuses a Starter whose manifest schema is newer than it understands and asks you to update. Starters before v0.3.0 have no manifest and use the previous layout.
+
+The CLI first builds a plan (the files to copy and the edits to make), which `--dry-run` prints, and then applies it. The source is organized the same way:
+
+```text
+src/
+  cli/      argument parsing and terminal output
+  core/     manifest, template sources, customizations, planning, and execution
+  steps/    Git initialization and dependency installation
+  utils/    file listing and copying, processes, and naming
+```
 
 ## Development
 
 ```sh
 corepack enable
 pnpm install
-node ./bin/create.mjs --help
-pnpm check
-pnpm test
+pnpm check            # type-check sources and tests
+pnpm test             # unit and scaffolding tests
+pnpm build            # compile src/ to dist/
+node ./bin/create.mjs my-app --template-dir ../clubedge-starter --dry-run
 ```
 
-CI scaffolds a clean project from the pinned Starter release, installs its dependencies, runs linting, typechecking, unit tests, browser checks, and a production build, then starts the generated app and checks the landing page, sign-up page, dashboard, health endpoint, logo, and favicon. A scheduled, non-blocking compatibility job also checks Starter `main`.
+Without a bundled template, a local build downloads the pinned Starter release from GitHub and verifies its commit. Run `pnpm bundle-template` to bundle it, or `pnpm bundle-template --from ../clubedge-starter` to bundle a local checkout.
+
+CI packs the CLI with `npm pack`, scaffolds a clean project from the packed tarball, installs its dependencies, runs linting, typechecking, unit tests, browser checks, and a production build, then starts the generated app and checks the landing page, sign-up page, dashboard, health endpoint, logo, and favicon. A scheduled, non-blocking compatibility job also checks Starter `main`.
 
 ## Release workflow
 
@@ -128,11 +159,11 @@ CI scaffolds a clean project from the pinned Starter release, installs its depen
 1. Make and validate changes in `clubedge-starter`.
 2. Run lint, typecheck, unit tests, browser tests, and production build.
 3. Update the Starter package versions.
-4. Commit `main`, create a release tag such as `v0.2.0`, and publish the Starter release.
+4. Commit `main`, create a release tag such as `v0.4.0`, and publish the Starter release.
 
 ### CLI maintainers
 
-1. Change `defaultStarterRef` in [`bin/create.mjs`](bin/create.mjs) to the new tested Starter tag.
+1. Set `clubedge.starterRef` and `clubedge.starterCommit` in [`package.json`](package.json) to the new tested Starter tag, and bump `version`.
 2. Update the version relationship table and changelog.
 3. Generate a clean project from that exact tag.
 4. Run install, lint, typecheck, unit tests, browser tests, production build, and runtime smoke checks.