create-koppajs 1.0.1 → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,127 @@
+# Change Log
+
+All notable changes to **create-koppajs** are documented in this file.
+
+This project uses a **manual, tag-driven release process**.
+Only tagged versions represent official releases.
+
+This changelog documents **intentional milestones and guarantees**,
+not every internal refactor.
+
+---
+
+## [Unreleased]
+
+_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**
+
+### Added
+
+- Added a repository meta layer covering architecture, decision hierarchy,
+  testing strategy, specs, ADRs, quality gates, and AI collaboration rules
+- Added a repository-specific `RELEASE.md` aligned with the `koppajs-core`
+  release model and this package's npm publish path
+- Added Conventional Commit enforcement with `commitlint`, Husky, and
+  `lint-staged`
+- Added repository-level quality scripts for meta checks, syntax checks,
+  formatting hygiene, cleanup, and package dry-run validation
+- Added generated-template build verification and wired it into CI and releases
+
+### Changed
+
+- Updated contributing guidance to match the actual scripts, workflows, and
+  repository responsibilities
+- Expanded smoke coverage for README patching, invalid project names, and
+  scaffolding into an existing empty directory
+- Documented the CI meta-layer presence guard in the quality and architecture
+  docs
+- Added importable CLI helper coverage with the Node.js built-in test runner
+- Synced the bundled starter template to the current `koppajs-example`
+  technical baseline, including quality tooling, meta docs, tests, and release
+  files
+- Switched root CI and release workflows to pnpm-based dependency installation
+  so the new hook and commit tooling actually runs in automation
+- Isolated the root pre-commit `lint-staged` config from the generated
+  starter's own hook tooling so root commits stay reliable
+- Clarified the starter's supported Node.js lines and added an explicit
+  validation guard for unsupported runtimes such as Node 23
+
+---
+
+## [1.0.1] — License & Metadata Fix
+
+**2026-03-01**
+
+Patch release to align license with the rest of the KoppaJS ecosystem.
+No CLI or template changes.
+
+### Changed
+
+- License changed from MIT to Apache License 2.0 (consistent with all KoppaJS projects)
+- Static license badge updated in README
+- Copyright year updated to 2026
+
+---
+
+## [1.0.0] — Initial Stable Release
+
+**2026-03-01**
+
+First stable release of the official KoppaJS project scaffolder.
+
+### Features
+
+- CLI scaffolder: `pnpm create koppajs my-app`
+- Interactive project name prompt when omitted
+- Complete starter template with Vite, TypeScript, and sample `.kpa` components
+- Supports `pnpm`, `npm`, and `npx`
+- Smoke test suite for generated project validation
+
+### Tooling
+
+- CI workflow for syntax check and smoke test
+- Tag-driven release workflow for npm publication
+- Code of Conduct and Contributing guidelines
+
+---
+
+## Versioning Policy
+
+- Semantic Versioning (SemVer) is followed pragmatically
+- **Breaking changes** include:
+  - CLI behavior changes
+  - template structure changes
+- Internal refactors without observable behavior change
+  do **not** require a major version bump
+
+---
+
+_This changelog documents intent.
+If something is not written here, it is not guaranteed._

package/README.md

@@ -1,131 +1,166 @@
-<a id="readme-top"></a>
-
-<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="#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.
-
-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.
-
----
-
-## Usage
-
-```bash
-pnpm create koppajs my-app
-```
-
-```bash
-npm create koppajs my-app
-```
-
-```bash
-npx create-koppajs my-app
-```
-
-Then:
-
-```bash
-cd my-app
-pnpm install
-pnpm dev
-```
-
-If you omit the project name, the CLI will prompt you for one.
-
----
-
-## What gets generated
-
-```
-my-app/
-├── index.html
-├── package.json
-├── tsconfig.json
-├── vite.config.mjs
-├── .gitignore
-├── LICENSE
-├── README.md
-├── public/
-│   └── favicon.svg
-└── src/
-    ├── main.ts
-    ├── style.css
-    ├── app-view.kpa
-    └── counter-component.kpa
-```
-
-- **Vite** as dev server and bundler
-- **TypeScript** support out of the box
-- **Two sample components** (app view + counter) to get started
-- **Zero unnecessary dependencies**
-
----
-
-## Requirements
-
-- Node.js >= 20
-
----
-
-## Community & Contribution
-
-Issues and pull requests are welcome:
-
-https://github.com/koppajs/create-koppajs/issues
-
----
-
-## License
-
-Apache-2.0 — © 2026 KoppaJS, Bastian Bensch
+# 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)
+
+## Usage
+
+Default starter:
+
+```bash
+pnpm create koppajs my-app
+```
+
+Router starter:
+
+```bash
+pnpm create koppajs my-app --template router
+```
+
+Alternative entrypoints:
+
+```bash
+npm create koppajs my-app
+```
+
+```bash
+npx create-koppajs my-app
+```
+
+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
+pnpm install
+pnpm dev
+```
+
+## 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+`
+
+## Generated Starters
+
+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
+
+Every starter also includes:
+
+- 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
+
+The root repository treats those starters as versioned product surface, not
+test data.
+
+## Ecosystem Fit
+
+`create-koppajs` is the canonical entry point for starting a new KoppaJS
+application. It complements:
+
+- `@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/`
+
+The repository stays intentionally narrow so the CLI, starter contract, and
+governance baseline can evolve together without hidden behavior.
+
+## Governance
+
+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 License 2.0 — © 2026 KoppaJS, Bastian Bensch