create-koppajs 1.0.1 → 1.1.0

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