create-koppajs 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -16,6 +16,28 @@ _No unreleased changes yet._
 
 ---
 
+## [1.2.0] — Starter Variants And Router Overlay
+
+**2026-03-26**
+
+### Added
+
+- added an opt-in `router` starter that layers `@koppajs/koppajs-router`, a
+  two-page navigation flow, and an explicit fallback route on top of the
+  minimal baseline
+- added overlay-based starter support through `template-overlays/` so future
+  starter variants can replace only the files that actually differ
+
+### Changed
+
+- extended the CLI contract with `--template` and `--router`, plus interactive
+  starter selection in TTY runs when no template flag is provided
+- expanded smoke, unit, and generated-template build coverage to validate both
+  the default minimal starter and the opt-in router starter
+- updated architecture docs, specs, and ADRs to reflect multi-starter support
+
+---
+
 ## [1.1.0] — Starter & Release Baseline Upgrade
 
 **2026-03-17**

package/README.md

@@ -1,71 +1,89 @@
-<a id="readme-top"></a>
+# create-koppajs
+
+`create-koppajs` is the official KoppaJS CLI scaffolder. It creates a new
+project by copying the versioned base starter in `template/`, optionally
+applying a supported starter overlay from `template-overlays/`, and patching a
+small, explicit set of identity files.
+
+## Purpose
+
+This repository exists to do one job well:
+
+- create a fresh project directory
+- copy the current supported KoppaJS starter baseline
+- optionally add a supported starter variant such as `router`
+- preserve a stable, inspectable bootstrap path for new KoppaJS applications
+
+It is not a runtime package and it does not own application behavior after
+generation.
+
+## Repository Classification
+
+- Repo type: CLI scaffolding package with a bundled starter family
+- Runtime responsibility: one-shot filesystem scaffolding through
+  `bin/create-koppajs.js`
+- Build-time responsibility: publish the starter assets, protect the contract,
+  and validate tagged releases
+- UI surface: none at the repository root; the generated starter owns the UI
+- Maturity level: stable, contract-governed, maintenance-first
+
+## Ownership Boundaries
+
+- `bin/create-koppajs.js` owns argument parsing, prompting, validation, starter
+  selection, template copy, placeholder patching, and next-step output.
+- `template/` owns the default `minimal` starter baseline.
+- `template-overlays/` owns the files that differ for opt-in starter variants.
+- `scripts/` and `.github/workflows/` own repository-quality and release
+  verification.
+- Root governance files own the repository doctrine and must stay aligned with
+  code and workflows.
+
+The root package must not take on runtime concerns that belong in generated
+applications, and generated applications must not depend on unpublished root
+files after scaffold completion.
+
+## Public Contract
+
+The stable public contract of this repository is:
+
+- the `create-koppajs` command and its `--help` / `--version` flags
+- the optional project-name argument and prompt fallback when omitted
+- the optional `--template <name>` and `--router` starter-selection flags
+- the interactive starter-template prompt when no template flag is provided in
+  an interactive terminal
+- rejection of invalid project names, invalid template names, and non-empty
+  target directories
+- recursive copying of the bundled `template/` directory plus any selected
+  overlay
+- restoration of publish-safe dotfiles and dotdirectories during copy
+- patching of generated `package.json`, `README.md`, `CHANGELOG.md`, and
+  `RELEASE.md`
+- the generated starter baselines defined by `template/` and
+  `template-overlays/`
+- the npm package payload: `bin/`, `template/`, `template-overlays/`,
+  `README.md`, `CHANGELOG.md`, and `LICENSE`
+
+The governing specs for that contract are:
+
+- [docs/specs/cli-scaffolding.md](./docs/specs/cli-scaffolding.md)
+- [docs/specs/template-starter-contract.md](./docs/specs/template-starter-contract.md)
 
-<div align="center">
-	<img src="https://public-assets-1b57ca06-687a-4142-a525-0635f7649a5c.s3.eu-central-1.amazonaws.com/koppajs/koppajs-logo-text-900x226.png" width="500" alt="KoppaJS Logo">
-</div>
-
-<br>
-
-<div align="center">
-	<a href="https://www.npmjs.com/package/create-koppajs"><img src="https://img.shields.io/npm/v/create-koppajs?style=flat-square" alt="npm version"></a>
-	<a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue?style=flat-square" alt="License"></a>
-</div>
-
-<br>
-
-<div align="center">
-	<h1 align="center">create-koppajs</h1>
-	<h3 align="center">Scaffold a new KoppaJS project in seconds</h3>
-	<p align="center">
-		<i>The fastest way to start building with KoppaJS.</i>
-	</p>
-</div>
-
-<br>
-
-<div align="center">
-	<p align="center">
-		<a href="https://github.com/koppajs/koppajs-documentation">Documentation</a>
-		&middot;
-		<a href="https://github.com/koppajs/koppajs-core">KoppaJS Core</a>
-		&middot;
-		<a href="https://github.com/koppajs/koppajs-vite-plugin">Vite Plugin</a>
-		&middot;
-		<a href="https://github.com/koppajs/create-koppajs/issues">Issues</a>
-	</p>
-</div>
-
-<br>
-
-<details>
-<summary>Table of Contents</summary>
-	<ol>
-		<li><a href="#what-is-this">What is this?</a></li>
-		<li><a href="#usage">Usage</a></li>
-		<li><a href="#what-gets-generated">What gets generated</a></li>
-		<li><a href="#requirements">Requirements</a></li>
-		<li><a href="#release--governance">Release & Governance</a></li>
-		<li><a href="#community--contribution">Community & Contribution</a></li>
-		<li><a href="#license">License</a></li>
-	</ol>
-</details>
-
----
-
-## What is this?
-
-`create-koppajs` is the **official project scaffolder** for KoppaJS.
+## Usage
 
-It creates a ready-to-run starter project with a single command — no configuration, no dependencies to install first, no boilerplate to write by hand.
+Default starter:
 
----
+```bash
+pnpm create koppajs my-app
+```
 
-## Usage
+Router starter:
 
 ```bash
-pnpm create koppajs my-app
+pnpm create koppajs my-app --template router
 ```
 
+Alternative entrypoints:
+
 ```bash
 npm create koppajs my-app
 ```
@@ -74,7 +92,11 @@ npm create koppajs my-app
 npx create-koppajs my-app
 ```
 
-Then:
+If the target directory name is omitted, the CLI prompts for one. If no
+template flag is provided in an interactive terminal, the CLI also prompts for
+starter selection. Non-interactive runs default to `minimal`.
+
+After generation:
 
 ```bash
 cd my-app
@@ -82,88 +104,63 @@ pnpm install
 pnpm dev
 ```
 
-If you omit the project name, the CLI will prompt you for one.
-
----
-
-## What gets generated
-
-```
-my-app/
-├── .github/
-├── .husky/
-├── docs/
-├── tests/
-├── CHANGELOG.md
-├── RELEASE.md
-├── AI_CONSTITUTION.md
-├── ARCHITECTURE.md
-├── package.json
-├── .gitignore
-├── README.md
-├── vite.config.mjs
-├── vitest.config.mjs
-├── playwright.config.ts
-├── tsconfig.json
-├── pnpm-lock.yaml
-├── LICENSE
-├── public/
-│   └── favicon.svg
-└── src/
-    ├── main.ts
-    ├── style.css
-    ├── app-view.kpa
-    └── counter-component.kpa
-```
-
-- **Vite** as dev server and bundler
-- **TypeScript**, **ESLint**, **Prettier**, **Vitest**, and **Playwright**
-- **GitHub workflows**, **Husky**, **lint-staged**, and **Conventional Commits**
-- **Meta-layer docs**, ADRs, specs, and a release baseline
-- **Two sample components** (app view + counter) aligned with the current
-  `koppajs-example` starter
+## Requirements
 
----
+- for `create-koppajs`: Node.js `>=20`
+- for generated starter projects: pnpm `>=10` and a starter-supported Node.js
+  line, currently `20.19+`, `22.13+`, or `24+`
 
-## Requirements
+## Generated Starters
 
-- `create-koppajs`: Node.js >= 20
-- Generated starter workflow: pnpm >= 10 plus a starter-supported Node.js line
-  (currently 20.19+, 22.13+, or 24+)
+The generated project includes one of two supported starters:
 
----
+- `minimal` by default: a small KoppaJS application built on Vite and
+  TypeScript
+- `router` as opt-in: the same baseline plus `@koppajs/koppajs-router`, a
+  simple two-page navigation flow, and an explicit fallback route
 
-## Release & Governance
+Every starter also includes:
 
-The scaffolded starter now ships with the same quality and governance baseline
-as the current official `koppajs-example`, adapted for generated projects:
+- quality tooling through ESLint, Prettier, Vitest, and Playwright
+- local workflow guards through Husky, lint-staged, and commitlint
+- starter governance files, ADR/spec structure, and release-process documents
+- GitHub workflows for CI and tagged releases
 
-- explicit meta docs and ADR/spec structure
-- tag-driven `CHANGELOG.md` plus `RELEASE.md`
-- Conventional Commit enforcement via `commitlint`
-- a generated-project CI/release baseline under `.github/workflows`
+The root repository treats those starters as versioned product surface, not
+test data.
 
----
+## Ecosystem Fit
 
-## Community & Contribution
+`create-koppajs` is the canonical entry point for starting a new KoppaJS
+application. It complements:
 
-Issues and pull requests are welcome:
+- `@koppajs/koppajs-core` for runtime behavior
+- `@koppajs/koppajs-router` for optional route orchestration in scaffolded apps
+- `@koppajs/koppajs-vite-plugin` for build integration
+- the maintained KoppaJS starter conventions reflected in `template/` and
+  `template-overlays/`
 
-https://github.com/koppajs/create-koppajs/issues
+The repository stays intentionally narrow so the CLI, starter contract, and
+governance baseline can evolve together without hidden behavior.
 
-## Governance & Architecture
+## Governance
 
-Repository design and maintenance rules live in the meta layer:
+The root meta layer defines how this repository changes:
 
 - [AI_CONSTITUTION.md](./AI_CONSTITUTION.md)
 - [ARCHITECTURE.md](./ARCHITECTURE.md)
+- [DECISION_HIERARCHY.md](./DECISION_HIERARCHY.md)
 - [DEVELOPMENT_RULES.md](./DEVELOPMENT_RULES.md)
 - [TESTING_STRATEGY.md](./TESTING_STRATEGY.md)
 - [RELEASE.md](./RELEASE.md)
+- [ROADMAP.md](./ROADMAP.md)
 - [docs/meta/README.md](./docs/meta/README.md)
+- [docs/architecture/README.md](./docs/architecture/README.md)
+- [docs/quality/README.md](./docs/quality/README.md)
 
----
+Tagged releases are documented in [CHANGELOG.md](./CHANGELOG.md). Contributor
+workflow rules live in [CONTRIBUTING.md](./CONTRIBUTING.md).
 
 ## License
 
-Apache-2.0 — © 2026 KoppaJS, Bastian Bensch
+Apache License 2.0 — © 2026 KoppaJS, Bastian Bensch

package/bin/create-koppajs.js

@@ -8,17 +8,90 @@ import { createInterface } from "node:readline";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 export const TEMPLATE_DIR = join(__dirname, "..", "template");
+export const TEMPLATE_OVERLAY_DIRS = Object.freeze({
+  minimal: null,
+  router: join(__dirname, "..", "template-overlays", "router"),
+});
+export const DEFAULT_TEMPLATE = "minimal";
 const CLI_PKG = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
 
 // ── Args ────────────────────────────────────────────────────────────
 
 export function parseArgs(argv) {
   const raw = argv.slice(2);
-  return {
+  const parsed = {
     help: raw.includes("--help") || raw.includes("-h"),
     version: raw.includes("--version") || raw.includes("-v"),
-    projectName: raw.find((a) => !a.startsWith("-")) || null,
+    projectName: null,
+    templateName: null,
+    optionError: null,
   };
+
+  const setTemplateName = (templateName) => {
+    if (!templateName) {
+      parsed.optionError = "Option --template requires a value.";
+      return false;
+    }
+
+    if (parsed.templateName && parsed.templateName !== templateName) {
+      parsed.optionError = "Choose either --router or one --template value.";
+      return false;
+    }
+
+    parsed.templateName = templateName;
+    return true;
+  };
+
+  for (let index = 0; index < raw.length; index++) {
+    const arg = raw[index];
+
+    if (arg === "--help" || arg === "-h" || arg === "--version" || arg === "-v") {
+      continue;
+    }
+
+    if (arg === "--router") {
+      if (!setTemplateName("router")) {
+        break;
+      }
+      continue;
+    }
+
+    if (arg === "--template" || arg === "-t") {
+      const templateName = raw[index + 1];
+
+      if (!templateName || templateName.startsWith("-")) {
+        parsed.optionError = "Option --template requires a value.";
+        break;
+      }
+
+      if (!setTemplateName(templateName)) {
+        break;
+      }
+
+      index++;
+      continue;
+    }
+
+    if (arg.startsWith("--template=")) {
+      if (!setTemplateName(arg.slice("--template=".length))) {
+        break;
+      }
+      continue;
+    }
+
+    if (arg.startsWith("-t=")) {
+      if (!setTemplateName(arg.slice("-t=".length))) {
+        break;
+      }
+      continue;
+    }
+
+    if (!arg.startsWith("-") && parsed.projectName === null) {
+      parsed.projectName = arg;
+    }
+  }
+
+  return parsed;
 }
 
 // ── Help / Version ──────────────────────────────────────────────────
@@ -35,11 +108,14 @@ export function printHelp() {
     npx create-koppajs [project-name]
 
   Options:
-    --help, -h       Show this help message
-    --version, -v    Show version number
+    --help, -h                Show this help message
+    --version, -v             Show version number
+    --template, -t <name>     Starter template: minimal | router
+    --router                  Shortcut for --template router
 
   Example:
     pnpm create koppajs my-app
+    pnpm create koppajs my-app --template router
 `);
 }
 
@@ -49,14 +125,14 @@ export function printVersion() {
 
 // ── Prompt ──────────────────────────────────────────────────────────
 
-export function promptProjectName() {
+function promptLine(question, closeErrorMessage, input = process.stdin, output = process.stdout) {
   return new Promise((res, rej) => {
-    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const rl = createInterface({ input, output });
     let answered = false;
     rl.on("close", () => {
-      if (!answered) rej(new Error("Input closed before a project name was provided."));
+      if (!answered) rej(new Error(closeErrorMessage));
     });
-    rl.question("  Project name: ", (answer) => {
+    rl.question(question, (answer) => {
       answered = true;
       rl.close();
       res(answer.trim());
@@ -64,6 +140,34 @@ export function promptProjectName() {
   });
 }
 
+export function promptProjectName(input = process.stdin, output = process.stdout) {
+  return promptLine(
+    "  Project name: ",
+    "Input closed before a project name was provided.",
+    input,
+    output,
+  );
+}
+
+export async function promptStarterTemplate(input = process.stdin, output = process.stdout) {
+  const answer = (await promptLine(
+    `  Starter template (minimal/router) [${DEFAULT_TEMPLATE}]: `,
+    "Input closed before a starter template was provided.",
+    input,
+    output,
+  )).toLowerCase();
+
+  if (answer === "" || answer === "m") {
+    return DEFAULT_TEMPLATE;
+  }
+
+  if (answer === "r") {
+    return "router";
+  }
+
+  return answer;
+}
+
 // ── Validation ──────────────────────────────────────────────────────
 
 export function validateProjectName(name) {
@@ -78,6 +182,16 @@ export function validateProjectName(name) {
   }
 }
 
+export function validateStarterTemplate(templateName) {
+  if (Object.hasOwn(TEMPLATE_OVERLAY_DIRS, templateName)) {
+    return;
+  }
+
+  throw new Error(
+    `Unknown starter template "${templateName}". Supported templates: ${Object.keys(TEMPLATE_OVERLAY_DIRS).join(", ")}.`,
+  );
+}
+
 // ── Target directory ────────────────────────────────────────────────
 
 export function ensureTargetDir(targetPath) {
@@ -115,6 +229,16 @@ export function copyDirRecursive(src, dest) {
   }
 }
 
+export function copyStarterTemplate(templateName, dest) {
+  copyDirRecursive(TEMPLATE_DIR, dest);
+
+  const overlayDir = TEMPLATE_OVERLAY_DIRS[templateName];
+
+  if (overlayDir) {
+    copyDirRecursive(overlayDir, dest);
+  }
+}
+
 // ── Patch package.json ──────────────────────────────────────────────
 
 export function patchPackageJson(destDir, projectName) {
@@ -156,8 +280,17 @@ export function printNextSteps(projectName) {
 
 // ── Main ────────────────────────────────────────────────────────────
 
-export async function runCli(argv = process.argv, cwd = process.cwd()) {
-  const { help, version, projectName: argName } = parseArgs(argv);
+export function shouldPromptForTemplateSelection(input = process.stdin, output = process.stdout) {
+  return Boolean(input.isTTY && output.isTTY);
+}
+
+export async function runCli(
+  argv = process.argv,
+  cwd = process.cwd(),
+  io = { input: process.stdin, output: process.stdout },
+) {
+  const { help, version, projectName: argName, templateName: argTemplateName, optionError } =
+    parseArgs(argv);
 
   if (help) {
     printHelp();
@@ -169,17 +302,29 @@ export async function runCli(argv = process.argv, cwd = process.cwd()) {
     return 0;
   }
 
-  const projectName = argName || (await promptProjectName());
+  if (optionError) {
+    throw new Error(optionError);
+  }
+
+  const projectName = argName || (await promptProjectName(io.input, io.output));
 
   validateProjectName(projectName);
 
+  const templateName =
+    argTemplateName ||
+    (shouldPromptForTemplateSelection(io.input, io.output)
+      ? await promptStarterTemplate(io.input, io.output)
+      : DEFAULT_TEMPLATE);
+
+  validateStarterTemplate(templateName);
+
   const targetDir = resolve(cwd, projectName);
 
   ensureTargetDir(targetDir);
 
-  console.log(`\n  Scaffolding KoppaJS project: ${projectName}\n`);
+  console.log(`\n  Scaffolding KoppaJS project: ${projectName} (${templateName} starter)\n`);
 
-  copyDirRecursive(TEMPLATE_DIR, targetDir);
+  copyStarterTemplate(templateName, targetDir);
   patchPackageJson(targetDir, projectName);
   patchReadme(targetDir, projectName);
   patchChangelog(targetDir, projectName);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-koppajs",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "private": false,
   "type": "module",
   "description": "Scaffold a new KoppaJS project in seconds.",
@@ -10,6 +10,7 @@
   "files": [
     "bin",
     "template",
+    "template-overlays",
     "CHANGELOG.md",
     "README.md",
     "LICENSE"

package/template-overlays/router/ARCHITECTURE.md

@@ -0,0 +1,86 @@
+# Architecture
+
+This repository is a small KoppaJS router starter. It demonstrates a clear
+bootstrap path: HTML shell, TypeScript entrypoint, one root app shell
+component, one router instance, two primary routes, and one explicit not-found
+route. The repository also carries the same quality and release automation
+baseline as the minimal starter so the example remains production-like.
+
+## System overview
+
+- `index.html` provides the document shell, loads global CSS, declares the
+  `<app-view>` root element, and imports the TypeScript entrypoint.
+- `src/main.ts` registers local components with `Core.take(...)`, calls
+  `Core()` once, waits for the route outlet to exist, and initializes one
+  `KoppajsRouter` instance.
+- `src/app-view.kpa` is the root shell. It renders the hero area, the primary
+  navigation, and the `#app-outlet` container that receives route content.
+- `src/home-page.kpa` is the default route and composes `counter-component`.
+- `src/router-page.kpa` is the second route and explains the router wiring.
+- `src/not-found-page.kpa` is the explicit catch-all route.
+- `src/counter-component.kpa` remains the example local-state component.
+- `src/style.css` defines global tokens, base layout, and the background.
+- `tests/integration/` verifies bootstrap wiring and router startup.
+- `tests/e2e/` verifies the user-visible route flow and counter behavior.
+
+More detailed boundaries live in [docs/architecture/module-boundaries.md](./docs/architecture/module-boundaries.md).
+
+## Runtime flow
+
+1. The browser loads [`index.html`](./index.html).
+2. The document loads [`src/style.css`](./src/style.css) and [`src/main.ts`](./src/main.ts).
+3. [`src/main.ts`](./src/main.ts) registers `app-view`, `home-page`,
+   `router-page`, `not-found-page`, and `counter-component`, then calls
+   `Core()`.
+4. KoppaJS instantiates `<app-view>`.
+5. [`src/app-view.kpa`](./src/app-view.kpa) renders the app shell, navigation,
+   and `#app-outlet`.
+6. `src/main.ts` initializes `KoppajsRouter` with the route table and outlet.
+7. The router renders the matching route component into `#app-outlet`,
+   synchronizes active links, and updates the current browser URL.
+
+## Quality automation layer
+
+- `eslint.config.mjs` lint-checks TypeScript source plus tooling files.
+- `prettier.config.mjs` and `.editorconfig` keep supported text files consistent.
+- `.npmrc` enforces the declared engine floor during installs.
+- `.husky/pre-commit` runs `lint-staged`.
+- `.husky/commit-msg` validates commit headers with `commitlint`.
+- `.github/workflows/ci.yml` runs the full repository validation flow on GitHub.
+- `.github/workflows/release.yml` runs tagged release validation and creates GitHub Releases.
+
+## Module responsibilities
+
+| Module                      | Responsibility                                                   | Must not do                                            |
+| --------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------ |
+| `index.html`                | Declare the root tag and static assets                           | Hold feature logic or router setup                     |
+| `src/main.ts`               | Bootstrap the app, register components, and start one router     | Accumulate page copy or unrelated UI state             |
+| `src/app-view.kpa`          | Render the shared shell, nav, and router outlet                  | Own route resolution or register components            |
+| `src/home-page.kpa`         | Render the landing route and compose the counter example         | Reach into router internals or mutate global DOM state |
+| `src/router-page.kpa`       | Render the second route and explain the router baseline          | Own bootstrap logic or global navigation state         |
+| `src/not-found-page.kpa`    | Render the explicit fallback route                               | Replace route matching or bootstrap responsibilities   |
+| `src/counter-component.kpa` | Demonstrate local interactive state                              | Reach into route orchestration or app-shell concerns   |
+| `src/style.css`             | Hold global tokens and truly global base styles                  | Duplicate component-local visuals                      |
+| `tests/integration/`        | Verify bootstrap and router-start boundaries                     | Duplicate full browser smoke expectations              |
+| `tests/e2e/`                | Verify visible navigation and counter behavior in a real browser | Assert brittle implementation details                  |
+
+## Invariants
+
+- There is exactly one bootstrap entrypoint.
+- The root tag in `index.html` must match a component registered in `src/main.ts`.
+- `Core()` is called once from `src/main.ts`.
+- The starter owns exactly one router instance.
+- The route table contains an explicit `*` fallback route.
+- Route rendering happens through `#app-outlet`.
+- Official releases require matching versions across `package.json`,
+  `CHANGELOG.md`, and `vX.Y.Z` tags.
+
+## Extension guidance
+
+- Add new route components under `src/` and register them from `src/main.ts`.
+- Keep route definitions in one obvious place.
+- Extract reusable route helpers into `.ts` modules only when logic becomes
+  shared or branch-heavy.
+- Add a spec before changing visible navigation behavior.
+- Add an ADR before changing the routing model, adding data fetching,
+  persistence, or another major subsystem.