create-koppajs 1.0.1 → 1.2.0

package/template/ARCHITECTURE.md

@@ -0,0 +1,86 @@
+# Architecture
+
+This repository is a minimal KoppaJS application starter. It intentionally demonstrates a small end-to-end path: HTML shell, TypeScript bootstrap, a root KoppaJS view, and a single interactive child component. The repository also carries a small quality and release automation layer so the starter stays runnable, trustworthy, and maintainable as it evolves.
+
+## 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` imports `@koppajs/koppajs-core`, registers local components with `Core.take(...)`, and invokes `Core()` exactly once to bootstrap the app.
+- `src/app-view.kpa` is the root UI shell. It arranges the page and composes the interactive example component.
+- `src/counter-component.kpa` is the example stateful leaf component. It owns its own `count` state and button event handlers.
+- `src/style.css` contains the global reset only.
+- `public/` contains static assets referenced by the HTML shell or components.
+- `vite.config.mjs` wires the KoppaJS Vite plugin into the build and applies a small repo-local compatibility transform so `.kpa` files are emitted as valid ES modules.
+- `vitest.config.mjs` reuses the Vite config so unit and integration tests exercise the same `.kpa` loading path as the application.
+- `playwright.config.ts` runs a Chromium smoke test against `vite preview`, which keeps the minimal UI starter covered by one real browser path.
+- `CHANGELOG.md` records official tagged milestones for the repository.
+- `RELEASE.md` documents the maintainer release path across `develop`, `release/*`, and `main`.
+- `commitlint.config.mjs` defines the repository's commit message convention.
+- `.github/workflows/release.yml` reruns validation for `vX.Y.Z` tags, checks version alignment, and creates GitHub Releases.
+- `tests/unit/` covers isolated logic such as the `.kpa` module export normalization helper.
+- `tests/integration/` covers application bootstrap wiring without requiring a full browser run.
+- `tests/e2e/` covers the observable starter flow in a real browser.
+- `tsconfig.json` enforces strict TypeScript rules for source, tests, and TypeScript config files. `.kpa` compilation is still handled by the KoppaJS Vite plugin.
+
+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` and `counter-component` with KoppaJS Core, then calls `Core()`.
+4. KoppaJS instantiates `<app-view>`.
+5. [`src/app-view.kpa`](./src/app-view.kpa) renders the starter shell and nests `<counter-component>`.
+6. [`src/counter-component.kpa`](./src/counter-component.kpa) handles button clicks, mutates local state, and re-renders the displayed value.
+
+## Quality automation layer
+
+- `eslint.config.mjs` lint-checks TypeScript source plus the TypeScript- and JavaScript-based tooling files.
+- `prettier.config.mjs` and `.editorconfig` keep supported text files consistent without introducing formatter-specific rules into ESLint.
+- `.npmrc` enforces the declared engine floor during installs.
+- `.husky/pre-commit` runs `lint-staged` so staged files get a fast local quality pass before commit.
+- `.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 for matching versions.
+- Stylelint is intentionally absent for now because the important styles live inside `.kpa` blocks and the repository does not yet have a low-friction, first-class way to lint those embedded blocks without giving a misleading sense of coverage.
+
+## Module responsibilities
+
+| Module                          | Responsibility                                                                             | Must not do                                                           |
+| ------------------------------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- |
+| `index.html`                    | Declare root tag and static assets                                                         | Hold business logic or feature wiring                                 |
+| `CHANGELOG.md`                  | Record official tagged release notes                                                       | Become a scratchpad for speculative work or duplicate repository docs |
+| `RELEASE.md`                    | Define the maintainer release procedure                                                    | Drift away from actual branch, tag, or workflow behavior              |
+| `commitlint.config.mjs`         | Define commit message validation rules                                                     | Expand into unrelated repository lint policy                          |
+| `src/main.ts`                   | Bootstrap and component registration                                                       | Accumulate feature logic, state, or DOM manipulation                  |
+| `src/app-view.kpa`              | Root layout and composition                                                                | Own unrelated business workflows or register components               |
+| `src/counter-component.kpa`     | Local interactive example state                                                            | Reach into global DOM or mutate app shell concerns                    |
+| `src/style.css`                 | Global reset/base rules                                                                    | Contain feature-specific visuals that belong to components            |
+| `public/`                       | Static assets                                                                              | Store generated build output or source code                           |
+| `tests/unit/`                   | Isolated tests for helper or tooling logic                                                 | Production runtime side effects or browser-only expectations          |
+| `tests/integration/`            | Wiring tests across bootstrap boundaries                                                   | Full browser assertions already covered by Playwright                 |
+| `tests/e2e/`                    | Real browser smoke coverage of the starter UI                                              | Deep implementation-detail assertions or brittle CSS-driven flows     |
+| `vite.config.mjs`               | Build and dev server integration, including the `.kpa` module export compatibility wrapper | Application runtime logic                                             |
+| `vitest.config.mjs`             | Unit and integration test runner configuration                                             | Runtime feature code                                                  |
+| `playwright.config.ts`          | Browser smoke-test orchestration against preview output                                    | Application runtime logic                                             |
+| `.github/workflows/release.yml` | Tagged release validation and GitHub Release creation                                      | Publish to npm while the repository remains private                   |
+
+## Invariants
+
+- There is exactly one application bootstrap path.
+- The root tag in `index.html` must match a component registered in `src/main.ts`.
+- `Core()` is called once from `src/main.ts`.
+- Official releases require matching versions across `package.json`, `CHANGELOG.md`, and `vX.Y.Z` tags.
+- Maintainer commits are expected to follow Conventional Commits.
+- No routing, persistence, network calls, or global client-side state are part of the baseline starter.
+- Stateful behavior remains local unless a documented new subsystem justifies centralization.
+- `pnpm check` remains fast enough for routine local use.
+- Playwright coverage stays focused on critical smoke coverage unless the UI grows into a broader workflow surface.
+- The repository remains `private` until an explicit decision changes the release target.
+
+## Extension guidance
+
+- Add new components under `src/` and compose them from `app-view.kpa` or other components.
+- Extract shared logic into `.ts` modules when it becomes reusable or deserves focused testing.
+- Add a spec before introducing new user-visible behavior.
+- Add an ADR before introducing architecture-changing capabilities such as routing, data fetching, persistence, state containers, SSR, or a new testing stack.

package/template/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Change Log
+
+All notable changes to **__PROJECT_NAME__** are documented in this file.
+
+This project uses a manual, tag-driven release process.
+Only tagged versions represent official releases.
+
+---
+
+## [Unreleased]
+
+This section is intentionally empty.
+
+Changes will only appear here when they:
+
+- alter the project's observable behavior,
+- change contributor or maintainer workflow,
+- or modify documented repository guarantees.
+
+---
+
+## [1.0.0] — Initial Scaffold Baseline
+
+**2026-03-17**
+
+Initial scaffold created from the current official KoppaJS starter baseline.
+
+### Included
+
+- a minimal KoppaJS app shell with `app-view` and `counter-component`
+- bootstrap through `Core.take(...)` and `Core()`
+- ESLint, Prettier, Vitest, Playwright, Husky, and GitHub Actions CI
+- explicit architecture, ADR, spec, testing, and contributor documentation
+- a tag-driven GitHub release workflow for repository snapshots

package/template/CONTRIBUTING.md

@@ -0,0 +1,92 @@
+# Contributing
+
+## Setup
+
+Requirements:
+
+- Node.js 20.19+, 22.13+, or 24+
+- pnpm 10 or newer
+
+Node 23 is intentionally not part of the supported range because the current
+upstream frontend tooling excludes it.
+
+Install and run:
+
+```bash
+pnpm install
+pnpm dev
+```
+
+Install the Playwright browser once if you plan to run browser smoke tests locally:
+
+```bash
+pnpm exec playwright install chromium
+```
+
+Useful commands:
+
+```bash
+pnpm lint
+pnpm format:check
+pnpm typecheck
+pnpm test:run
+pnpm test:coverage
+pnpm test:e2e
+pnpm check
+pnpm validate
+pnpm release:check
+pnpm build
+pnpm serve
+```
+
+Commit messages use Conventional Commits.
+Examples:
+
+```text
+feat: add release baseline
+docs: update contributing guide
+fix: align bootstrap docs
+```
+
+## Workflow
+
+1. Read [DECISION_HIERARCHY.md](./DECISION_HIERARCHY.md), [ARCHITECTURE.md](./ARCHITECTURE.md), and any relevant spec or ADR before changing source files.
+2. For non-trivial work, update or create the relevant spec in [docs/specs](./docs/specs) first.
+3. If the change alters architecture, tooling, public tags, or repository workflow, add or update an ADR in [docs/adr](./docs/adr).
+4. Implement the smallest change that satisfies the spec.
+5. Run the applicable quality gates from [TESTING_STRATEGY.md](./TESTING_STRATEGY.md). Use `pnpm check` for the local baseline and `pnpm validate` before merge when the UI, bootstrap, or tooling changed.
+6. If the change touches versioning, changelog, or release automation, update `CHANGELOG.md`, `RELEASE.md`, and the affected workflow in the same change.
+7. Update architecture, development, testing, and README docs when the actual project state changes.
+
+## Releases
+
+- Release notes live in [`CHANGELOG.md`](./CHANGELOG.md).
+- The maintainer release procedure lives in [`RELEASE.md`](./RELEASE.md).
+- Releases are prepared on `develop`, moved through `release/*`, merged into `main`, and tagged as `vX.Y.Z`.
+- The release workflow creates GitHub Releases only. The repository starts
+  `private`, so no npm publish step is configured by default.
+- Run `pnpm release:check` before cutting a release tag.
+
+## Commit policy
+
+- Commit messages are validated by `.husky/commit-msg` using `commitlint`.
+- Use Conventional Commits such as `feat: ...`, `fix: ...`, `docs: ...`, `test: ...`, `ci: ...`, or `chore: ...`.
+- Keep the commit header at 72 characters or fewer.
+- Merge, revert, `fixup!`, and `squash!` commits may bypass validation when Git creates them automatically.
+
+## Pull request expectations
+
+- Keep the starter minimal unless expansion is explicitly approved.
+- Explain user-visible behavior changes and architecture-impacting decisions.
+- Do not silently swap dependency sources, add build tools, or introduce new subsystems.
+- Keep docs and code aligned in the same change.
+- Keep hooks fast; heavy validation belongs in `pnpm validate` and CI, not in `pre-commit`.
+
+## AI-assisted contributions
+
+AI contributors follow the same rules as humans:
+
+- read governing docs before editing,
+- prefer existing patterns,
+- do not invent architecture casually,
+- update the meta layer whenever structure or rules change.

package/template/DECISION_HIERARCHY.md

@@ -0,0 +1,32 @@
+# Decision Hierarchy
+
+When repository documents conflict, use this order of precedence.
+
+1. Approved specifications in [`docs/specs/`](./docs/specs)
+2. Architecture Decision Records in [`docs/adr/`](./docs/adr)
+3. [`AI_CONSTITUTION.md`](./AI_CONSTITUTION.md)
+4. [`ARCHITECTURE.md`](./ARCHITECTURE.md) and supporting architecture docs in [`docs/architecture/`](./docs/architecture)
+5. [`DEVELOPMENT_RULES.md`](./DEVELOPMENT_RULES.md) and [`TESTING_STRATEGY.md`](./TESTING_STRATEGY.md)
+6. Quality and maintenance guidance in [`docs/quality/`](./docs/quality) and [`docs/meta/`](./docs/meta)
+7. Contributor guidance and examples in [`CONTRIBUTING.md`](./CONTRIBUTING.md), [`README.md`](./README.md), and inline comments
+
+## Interpretation rules
+
+- The most specific document wins when two documents have the same rank.
+- A newer document does not override a higher-ranked document by default.
+- If a lower-ranked document is wrong, fix it instead of following it.
+- If no applicable spec exists for a non-trivial change, create or update one before implementation.
+- If a change would invalidate an ADR, create a superseding ADR instead of silently drifting away from it.
+
+## Required reading order for non-trivial changes
+
+1. This file
+2. [AI_CONSTITUTION.md](./AI_CONSTITUTION.md)
+3. [ARCHITECTURE.md](./ARCHITECTURE.md)
+4. Relevant spec in [docs/specs](./docs/specs)
+5. Relevant ADR in [docs/adr](./docs/adr)
+6. [DEVELOPMENT_RULES.md](./DEVELOPMENT_RULES.md) and [TESTING_STRATEGY.md](./TESTING_STRATEGY.md)
+
+## Escalation rule
+
+When a change creates a new lasting rule, boundary, or tradeoff, encode it as a spec or ADR rather than relying on chat history or commit messages.

package/template/DEVELOPMENT_RULES.md

@@ -0,0 +1,57 @@
+# Development Rules
+
+## Scope
+
+These rules describe how code and documentation are expected to evolve in this repository.
+
+## Source layout rules
+
+- Keep `index.html` as a static shell with asset references and the single root element.
+- Keep `src/main.ts` limited to bootstrap concerns: imports, `Core.take(...)` registrations, and the single public bootstrap call via `Core()`.
+- Use `.kpa` files for UI composition, local component state, and component-scoped CSS.
+- If logic becomes reusable, asynchronous, or branch-heavy, move it into `.ts` modules under `src/`.
+- Keep `public/` for static assets only.
+- Keep automated tests under `tests/`, split by `unit`, `integration`, and `e2e` only when each level is meaningfully used.
+
+## Naming conventions
+
+- Custom element names must be kebab-case.
+- Root-level application components should use `app-` prefixes when they represent app shells or app-wide structure.
+- Component filenames should match their primary exported or registered concept.
+- New files and folders should use descriptive names over abbreviations.
+
+## Dependency rules
+
+- Runtime dependencies must be justified by a concrete need in a spec or ADR.
+- Prefer browser APIs and KoppaJS primitives before adding helper libraries.
+- Keep this repository wired to published npm packages unless there is an explicit ADR stating otherwise.
+- Build tooling changes must update contributor docs and architecture docs in the same change.
+- Quality tooling must stay proportionate to the starter. Prefer one clear tool per job over overlapping stacks.
+
+## Coding patterns
+
+- Favor simple, local state over premature abstraction.
+- Keep methods short and named by behavior.
+- Avoid hidden side effects during import.
+- Keep CSS local to components unless the style truly applies application-wide.
+- Preserve strict TypeScript settings; do not weaken `tsconfig.json` to work around errors.
+- Give interactive controls stable accessible names when feasible so smoke tests can target public semantics instead of brittle selectors.
+- Keep Playwright assertions user-facing. Implementation-detail checks belong in Vitest, not in browser tests.
+
+## Forbidden without a spec and ADR
+
+- Introducing routing
+- Adding global state containers
+- Adding network or persistence layers
+- Introducing SSR, multi-page bootstraps, or multiple root entries
+- Switching dependency sourcing from npm packages to local monorepo links
+- Expanding the starter into a multi-feature demo application
+- Adding heavyweight hooks that run the entire suite on every commit
+
+## Documentation obligations
+
+- Update [ARCHITECTURE.md](./ARCHITECTURE.md) when source layout or runtime flow changes.
+- Update [TESTING_STRATEGY.md](./TESTING_STRATEGY.md) when quality gates or tooling change.
+- Update or create a spec in [docs/specs](./docs/specs) for user-visible changes.
+- Add an ADR in [docs/adr](./docs/adr) for durable technical decisions.
+- Update [docs/quality/quality-gates.md](./docs/quality/quality-gates.md) when scripts, hooks, CI checks, or browser-smoke expectations change.

package/template/LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [yyyy] [name of copyright owner]
+   Copyright 2026 Bastian Bensch
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/template/README.md

@@ -1,49 +1,241 @@
-# __PROJECT_NAME__
-
-A [KoppaJS](https://github.com/koppajs/koppajs-core) project.
-
-## Getting Started
-
-**Install dependencies:**
-
-```bash
-pnpm install
-```
-
-**Start the dev server:**
-
-```bash
-pnpm dev
-```
-
-**Build for production:**
-
-```bash
-pnpm build
-```
-
-**Preview the production build:**
-
-```bash
-pnpm serve
-```
-
-## Project Structure
-
-```
-src/
-├── main.ts                 Entry point — registers components, boots KoppaJS
-├── style.css               Global styles
-├── app-view.kpa            Root application view
-└── counter-component.kpa   Sample counter component
-```
-
-## Learn More
-
-- [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)
-
-## License
-
-Apache-2.0
+<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="./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`.
+
+---
+
+## 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.
+
+---
+
+## Getting Started
+
+```bash
+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:
+
+```bash
+pnpm lint
+pnpm format:check
+pnpm typecheck
+pnpm test:run
+pnpm test:coverage
+pnpm build
+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/
+├── .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
+├── 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/
+```
+
+---
+
+## 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
+
+Apache License 2.0 — © 2026 KoppaJS, Bastian Bensch