create-koppajs 1.1.0 → 1.2.1

package/CHANGELOG.md

@@ -16,6 +16,46 @@ _No unreleased changes yet._
 
 ---
 
+## [1.2.1] — Starter Source Of Truth Cleanup
+
+**2026-03-26**
+
+Patch release to make the bundled templates the only starter source of truth and
+to refresh the generated starter dependency baseline.
+
+### Changed
+
+- documented `template/` and `template-overlays/` as the only maintained source
+  of truth for generated starters
+- removed active ecosystem references to the retired `koppajs-example` starter
+  repository
+- updated generated starter dependencies to `@koppajs/koppajs-core@^3.0.3` and
+  `@koppajs/koppajs-vite-plugin@^1.0.1`
+
+---
+
+## [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,92 @@
-<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 and is the single
+  source of truth for that starter.
+- `template-overlays/` owns the files that differ for opt-in starter variants.
+  Together with `template/`, they define the only source of truth for
+  generated starter output.
+- `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 +95,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 +107,64 @@ 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. `template/` plus the supported overlays are the only source of truth
+for starter behavior.
 
----
+## 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.1",
   "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/package.json

@@ -42,13 +42,13 @@
     "prepare": "husky"
   },
   "dependencies": {
-    "@koppajs/koppajs-core": "^3.0.2"
+    "@koppajs/koppajs-core": "^3.0.3"
   },
   "devDependencies": {
     "@commitlint/cli": "^20.1.0",
     "@commitlint/config-conventional": "^20.0.0",
     "@eslint/js": "^10.0.1",
-    "@koppajs/koppajs-vite-plugin": "^1.0.0",
+    "@koppajs/koppajs-vite-plugin": "^1.0.1",
     "@playwright/test": "^1.58.2",
     "@types/node": "^25.4.0",
     "@vitest/coverage-v8": "^4.0.18",