create-koppajs 1.2.1 → 1.2.3

package/CHANGELOG.md

@@ -16,6 +16,61 @@ _No unreleased changes yet._
 
 ---
 
+## [1.2.3] — Lean Starter Maintenance
+
+**2026-04-24**
+
+Patch release to keep generated projects focused on runnable KoppaJS app code.
+This is a maintainer-approved patch exception to the versioning policy because
+the CLI invocation contract stays unchanged while the generated starter tree is
+intentionally reduced.
+
+### Changed
+
+- trimmed generated starters to app source, README, and Vite/TypeScript build
+  files
+- switched generated starter views from the remote KoppaJS logo URL to a local
+  `public/koppajs-logo.png` asset
+- switched generated starter favicon output from `public/favicon.svg` to
+  `public/favicon.png`
+- stopped patching generated `CHANGELOG.md` and `RELEASE.md`; those files are
+  no longer included in new apps
+- refreshed the compatible generated-starter toolchain to `vite@7.3.2` and
+  `@types/node@25.6.0` while keeping `typescript@5.9.3` within the current
+  `@koppajs/koppajs-vite-plugin` peer range
+- raised repository and generated-starter pnpm metadata to `pnpm@10.33.2`,
+  with a declared minimum of `>=10.24.0`
+- raised repository and generated-starter Node.js metadata to `>=22.12.0`
+
+### Removed
+
+- removed governance, ADR/spec docs, GitHub workflows, Husky hooks, commitlint,
+  lint-staged, release files, changelog files, license files, and starter
+  lockfiles from generated projects
+- removed generated-starter lint, format, and test tooling, including ESLint,
+  Prettier, Vitest, Playwright, their configs, scripts, dependencies, and test
+  files
+
+---
+
+## [1.2.2] — Node & Validation Baseline Alignment
+
+**2026-03-27**
+
+### Changed
+
+- raised the repository and bundled starter minimum Node.js version to `>=22`
+  and expanded CI coverage to Node 24
+- aligned CI and release validation around `pnpm validate`, added a packed-CLI
+  smoke test, and switched release automation to the maintainer default from
+  `.nvmrc`
+- refreshed bundled starter dependencies to the current `@koppajs/koppajs-core`,
+  `@koppajs/koppajs-vite-plugin`, and `@koppajs/koppajs-router` baselines
+- removed the obsolete starter-local `.kpa` export wrapper now that the Vite
+  plugin emits valid ES modules itself
+
+---
+
 ## [1.2.1] — Starter Source Of Truth Cleanup
 
 **2026-03-26**

package/README.md

@@ -1,9 +1,63 @@
-# 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.
+<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="https://github.com/koppajs/create-koppajs/actions"><img src="https://img.shields.io/github/actions/workflow/status/koppajs/create-koppajs/ci.yml?branch=main&style=flat-square" alt="CI Status"></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">Official project scaffolder for KoppaJS</h3>
+  <p align="center">
+    <i>Generate a ready-to-run KoppaJS starter in one command.</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/koppajs-router">Router</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="#purpose">Purpose</a></li>
+    <li><a href="#repository-classification">Repository Classification</a></li>
+    <li><a href="#ownership-boundaries">Ownership Boundaries</a></li>
+    <li><a href="#public-contract">Public Contract</a></li>
+    <li><a href="#usage">Usage</a></li>
+    <li><a href="#requirements">Requirements</a></li>
+    <li><a href="#generated-starters">Generated Starters</a></li>
+    <li><a href="#ecosystem-fit">Ecosystem Fit</a></li>
+    <li><a href="#architecture-governance">Architecture & Governance</a></li>
+    <li><a href="#community-contribution">Community & Contribution</a></li>
+    <li><a href="#license">License</a></li>
+  </ol>
+</details>
+
+---
 
 ## Purpose
 
@@ -17,6 +71,8 @@ This repository exists to do one job well:
 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
@@ -27,6 +83,8 @@ generation.
 - 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
@@ -45,6 +103,8 @@ 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:
@@ -58,9 +118,8 @@ The stable public contract of this repository is:
   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`
+- restoration of publish-safe dotfiles during copy
+- patching of generated `package.json` and `README.md`
 - the generated starter baselines defined by `template/` and
   `template-overlays/`
 - the npm package payload: `bin/`, `template/`, `template-overlays/`,
@@ -71,6 +130,8 @@ 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:
@@ -107,11 +168,14 @@ 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+`
+- for `create-koppajs`: Node.js `>=22.12.0` and pnpm `>=10.24.0`
+- for generated starter projects: Node.js `>=22.12.0` and pnpm `>=10.24.0`
+
+---
 
 ## Generated Starters
 
@@ -124,15 +188,20 @@ The generated project includes one of two supported starters:
 
 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
+- a focused README with setup, scripts, and project structure
+
+The generated project intentionally excludes repository governance files,
+release automation, GitHub workflows, Git hooks, changelog files, lockfiles,
+and lint/format/test tooling. Those files belong to this scaffolder repository
+or to project-specific app decisions, not to every new application created from
+it.
 
 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
 
 `create-koppajs` is the canonical entry point for starting a new KoppaJS
@@ -147,9 +216,11 @@ application. It complements:
 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:
+## Architecture & Governance
+
+Project intent, contributor rules, and documentation contracts live in the local repo meta layer:
 
 - [AI_CONSTITUTION.md](./AI_CONSTITUTION.md)
 - [ARCHITECTURE.md](./ARCHITECTURE.md)
@@ -158,12 +229,36 @@ The root meta layer defines how this repository changes:
 - [TESTING_STRATEGY.md](./TESTING_STRATEGY.md)
 - [RELEASE.md](./RELEASE.md)
 - [ROADMAP.md](./ROADMAP.md)
-- [docs/meta/README.md](./docs/meta/README.md)
+- [CHANGELOG.md](./CHANGELOG.md)
+- [CONTRIBUTING.md](./CONTRIBUTING.md)
+- [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)
+- [docs/specs/README.md](./docs/specs/README.md)
+- [docs/specs/repository-documentation-contract.md](./docs/specs/repository-documentation-contract.md)
 - [docs/architecture/README.md](./docs/architecture/README.md)
+- [docs/meta/README.md](./docs/meta/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).
+The file-shape contract for `README.md`, `CHANGELOG.md`, `CODE_OF_CONDUCT.md`, and `CONTRIBUTING.md` is defined in [docs/specs/repository-documentation-contract.md](./docs/specs/repository-documentation-contract.md).
+
+Run the local document guard before committing:
+
+```bash
+pnpm run check:docs
+```
+
+---
+
+## Community & Contribution
+
+Issues and pull requests are welcome:
+
+https://github.com/koppajs/create-koppajs/issues
+
+Contributor workflow details live in [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+Community expectations live in [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md).
+
+---
 
 ## License
 

package/bin/create-koppajs.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, copyFileSync, statSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, copyFileSync, statSync, realpathSync } from "node:fs";
 import { basename, join, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createInterface } from "node:readline";
@@ -206,13 +206,9 @@ export function ensureTargetDir(targetPath) {
 // npm excludes .gitignore from published packages — ship as _gitignore
 // and rename during scaffolding (same approach as create-vite).
 const RENAME_FILES = {
-  _editorconfig: ".editorconfig",
   _gitattributes: ".gitattributes",
-  _github: ".github",
   _gitignore: ".gitignore",
-  _husky: ".husky",
   _npmrc: ".npmrc",
-  _prettierignore: ".prettierignore",
 };
 
 export function copyDirRecursive(src, dest) {
@@ -261,14 +257,6 @@ export function patchReadme(destDir, projectName) {
   patchTextFile(destDir, "README.md", projectName);
 }
 
-export function patchChangelog(destDir, projectName) {
-  patchTextFile(destDir, "CHANGELOG.md", projectName);
-}
-
-export function patchReleaseNotes(destDir, projectName) {
-  patchTextFile(destDir, "RELEASE.md", projectName);
-}
-
 // ── Final output ────────────────────────────────────────────────────
 
 export function printNextSteps(projectName) {
@@ -327,15 +315,21 @@ export async function runCli(
   copyStarterTemplate(templateName, targetDir);
   patchPackageJson(targetDir, projectName);
   patchReadme(targetDir, projectName);
-  patchChangelog(targetDir, projectName);
-  patchReleaseNotes(targetDir, projectName);
   printNextSteps(projectName);
 
   return 0;
 }
 
 function isDirectExecution() {
-  return Boolean(process.argv[1]) && resolve(process.argv[1]) === __filename;
+  if (!process.argv[1]) {
+    return false;
+  }
+
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(__filename);
+  } catch {
+    return resolve(process.argv[1]) === __filename;
+  }
 }
 
 if (isDirectExecution()) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-koppajs",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "private": false,
   "type": "module",
   "description": "Scaffold a new KoppaJS project in seconds.",
@@ -15,10 +15,10 @@
     "README.md",
     "LICENSE"
   ],
-  "packageManager": "pnpm@10.12.1",
+  "packageManager": "pnpm@10.33.2",
   "engines": {
-    "node": ">=20",
-    "pnpm": ">=10"
+    "node": ">=22.12.0",
+    "pnpm": ">=10.24.0"
   },
   "scripts": {
     "check:meta": "node scripts/check-meta-layer.mjs",
@@ -29,12 +29,15 @@
     "test:watch": "node scripts/run-unit-tests.mjs --watch",
     "test:smoke": "node scripts/smoke-test.mjs",
     "test:template-build": "node scripts/template-build-test.mjs",
+    "test:package": "node scripts/test-package-smoke.mjs",
     "test": "npm run test:unit && npm run test:smoke",
     "pack:dry-run": "npm pack --dry-run",
-    "check": "npm run check:meta && npm run lint && npm run format:check && npm run check:cli && npm test && npm run pack:dry-run",
-    "release:check": "npm run check && npm run test:template-build",
+    "check": "pnpm run check:docs && npm run check:meta && npm run lint && npm run format:check && npm run check:cli && npm test && npm run pack:dry-run",
+    "validate": "pnpm run check && pnpm run test:template-build && pnpm run test:package",
+    "release:check": "pnpm run validate",
     "prepare": "husky",
-    "clean": "node scripts/clean.mjs"
+    "clean": "node scripts/clean.mjs",
+    "check:docs": "node scripts/check-doc-contract.mjs"
   },
   "author": "Bastian Bensch",
   "license": "Apache-2.0",

package/template/README.md

@@ -1,93 +1,11 @@
-<a id="readme-top"></a>
+# __PROJECT_NAME__
 
-<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="./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">__PROJECT_NAME__</h1>
-  <h3 align="center">KoppaJS starter project</h3>
-  <p align="center">
-    <i>Scaffolded from the current official KoppaJS starter baseline.</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>
-  </p>
-</div>
-
-<br>
-
-<details>
-<summary>Table of Contents</summary>
-  <ol>
-    <li><a href="#what-is-this">What is this?</a></li>
-    <li><a href="#requirements">Requirements</a></li>
-    <li><a href="#getting-started">Getting Started</a></li>
-    <li><a href="#quality-workflow">Quality Workflow</a></li>
-    <li><a href="#release-workflow">Release Workflow</a></li>
-    <li><a href="#project-structure">Project Structure</a></li>
-    <li><a href="#meta-layer">Meta Layer</a></li>
-    <li><a href="#community--contribution">Community & Contribution</a></li>
-    <li><a href="#license">License</a></li>
-  </ol>
-</details>
-
----
-
-## What is this?
-
-This project was scaffolded from the current official minimal starter baseline
-for KoppaJS.
-
-It keeps the runtime intentionally small:
-
-- one HTML shell
-- one TypeScript bootstrap file
-- one root view
-- one stateful child component
-
-It also carries a small quality baseline so the starter stays runnable and trustworthy:
-
-- ESLint for source and tooling files
-- Prettier plus `.editorconfig` for supported text formats
-- Vitest for local unit and integration coverage
-- Playwright for a real-browser smoke test
-- Husky plus lint-staged for fast staged-file checks
-- Conventional Commits enforcement via `commitlint`
-- a tag-driven GitHub release baseline with `CHANGELOG.md` and `RELEASE.md`
-
-Use it as a starting point for new KoppaJS projects or as a reference for how components are registered, composed, and validated.
-
-> **Note:** This repository uses published npm packages, so it works as a standalone starter after `pnpm install`.
-
----
+KoppaJS starter project scaffolded with `create-koppajs`.
 
 ## Requirements
 
-- Node.js 20.19+, 22.13+, or 24+
-- pnpm >= 10
-
-Node 23 is intentionally not treated as supported here because the current
-upstream frontend toolchain excludes it.
-
----
+- Node.js >= 22.12.0
+- pnpm >= 10.24.0
 
 ## Getting Started
 
@@ -96,146 +14,38 @@ pnpm install
 pnpm dev
 ```
 
-Install the Playwright browser once if you want to run the browser smoke test locally:
-
-```bash
-pnpm exec playwright install chromium
-```
-
-Useful commands:
+## Scripts
 
 ```bash
-pnpm lint
-pnpm format:check
-pnpm typecheck
-pnpm test:run
-pnpm test:coverage
 pnpm build
+pnpm typecheck
 pnpm serve
-pnpm release:check
-```
-
-Commit messages follow Conventional Commits, for example:
-
-```text
-feat: add release workflow
-docs: update starter governance
-fix: align counter button labels
-```
-
----
-
-## Quality Workflow
-
-Fast local baseline:
-
-```bash
-pnpm check
-```
-
-Full validation, including Playwright:
-
-```bash
-pnpm validate
-```
-
-Standalone browser smoke test:
-
-```bash
-pnpm test:e2e
 ```
 
----
-
-## Release Workflow
-
-Tagged releases are documented in `CHANGELOG.md`.
-The maintainer procedure lives in `RELEASE.md`.
-
-Release tags must use the form `vX.Y.Z` and match `package.json`.
-The included automation creates GitHub Releases only. If your project later
-needs npm publishing or deployment-specific release steps, update `RELEASE.md`
-and `.github/workflows/release.yml` together.
-
----
-
 ## Project Structure
 
 ```text
 __PROJECT_NAME__/
-├── .editorconfig
-├── .github/
+├── .gitattributes
 ├── .gitignore
-├── .husky/
 ├── .npmrc
-├── .prettierignore
-├── CHANGELOG.md
-├── commitlint.config.mjs
-├── AI_CONSTITUTION.md
-├── ARCHITECTURE.md
-├── CONTRIBUTING.md
-├── DECISION_HIERARCHY.md
-├── DEVELOPMENT_RULES.md
-├── RELEASE.md
-├── ROADMAP.md
-├── TESTING_STRATEGY.md
-├── eslint.config.mjs
+├── README.md
 ├── index.html
 ├── package.json
-├── playwright.config.ts
-├── pnpm-lock.yaml
-├── prettier.config.mjs
 ├── tsconfig.json
 ├── vite.config.mjs
-├── vitest.config.mjs
-├── docs/
-│   ├── adr/
-│   ├── architecture/
-│   ├── meta/
-│   ├── quality/
-│   └── specs/
 ├── public/
-│   └── favicon.svg
-├── src/
-│   ├── main.ts
-│   ├── style.css
-│   ├── app-view.kpa
-│   └── counter-component.kpa
-└── tests/
-    ├── e2e/
-    ├── integration/
-    └── unit/
+│   ├── favicon.png
+│   └── koppajs-logo.png
+└── src/
+    ├── app-view.kpa
+    ├── counter-component.kpa
+    ├── main.ts
+    └── style.css
 ```
 
----
-
-## Meta Layer
-
-The repository includes an explicit meta layer so architecture, testing, and contributor rules evolve together with the codebase.
-
-Start here:
-
-- `DECISION_HIERARCHY.md`
-- `AI_CONSTITUTION.md`
-- `ARCHITECTURE.md`
-- `DEVELOPMENT_RULES.md`
-- `TESTING_STRATEGY.md`
-- `CHANGELOG.md`
-- `RELEASE.md`
-- `docs/quality/quality-gates.md`
-- `docs/adr/`
-- `docs/specs/`
-
----
-
-## Community & Contribution
-
-Contribution workflow details live in `CONTRIBUTING.md`.
-Update this section with your own repository links once the project has a
-canonical home.
-
----
-
-## License
+## Useful Links
 
-Apache License 2.0 — © 2026 KoppaJS, Bastian Bensch
+- [KoppaJS documentation](https://github.com/koppajs/koppajs-documentation)
+- [KoppaJS core](https://github.com/koppajs/koppajs-core)
+- [KoppaJS Vite plugin](https://github.com/koppajs/koppajs-vite-plugin)

package/template/_gitignore

@@ -1,9 +1,6 @@
 node_modules
-coverage
 dist
 .ai
-playwright-report
-test-results
 pnpm-debug.log*
 *.log
 *.local

package/template/index.html

@@ -4,7 +4,7 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>KoppaJS Minimal Starter</title>
-    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <link rel="icon" type="image/png" href="/favicon.png" />
     <link rel="stylesheet" href="/src/style.css" />
   </head>
   <body>