create-koppajs 1.0.1 → 1.2.0

package/template/RELEASE.md

@@ -0,0 +1,230 @@
+# Release Process for `__PROJECT_NAME__`
+
+This document describes the repository-specific release workflow for
+`__PROJECT_NAME__`.
+
+The project uses a manual, tag-driven release process.
+Only tagged versions are official releases.
+
+The effective flow is:
+
+1. Finalize the release content on `develop`
+2. Update `package.json` and `CHANGELOG.md`
+3. Validate the release candidate locally
+4. Create a `release/*` branch from that state
+5. Merge the release branch into `main`
+6. Tag the release commit on `main` as `vX.Y.Z`
+7. Push the tag
+8. Let GitHub Actions validate and create the GitHub Release
+9. Merge the updated `main` back into `develop`
+
+---
+
+## Release Model
+
+This repository does not use automated versioning tools such as Changesets or
+semantic-release.
+
+The release is controlled by:
+
+- the version in `package.json`
+- the release entry in `CHANGELOG.md`
+- the merge of the release-ready state into `main`
+- the Git tag in the form `vX.Y.Z`
+- the GitHub Actions workflow in `.github/workflows/release.yml`
+
+Important consequences:
+
+- A merge to `main` alone does not create a release
+- A tag triggers the release workflow
+- The tag version must exactly match `package.json`
+- The tag must point to the release commit on `main`
+- After a successful release, `main` should be merged back into `develop`
+
+The included release workflow creates GitHub Releases only and does not publish
+to npm by default.
+
+If this project later needs npm publishing or another release target, update
+this file, `package.json`, and `.github/workflows/release.yml` in the same
+change.
+
+Do not tag `develop`.
+Do not tag the `release/*` branch.
+Tag only the release commit that is already on `main`.
+
+---
+
+## Preconditions
+
+Before cutting a release, ensure all of the following are true:
+
+- The intended release scope is already complete on `develop`
+- `package.json` contains the target version
+- `CHANGELOG.md` contains the corresponding release notes
+- The lockfile is up to date
+- The release content has been reviewed
+
+Tooling expectations for local verification:
+
+- Node.js 20.19+, 22.13+, or 24+
+- pnpm 10 or newer
+
+Node 23 is intentionally not treated as supported here because the current
+upstream frontend toolchain excludes it.
+
+This repository also enforces `engine-strict=true` in `.npmrc`, so incompatible
+Node.js or pnpm versions should be treated as a release blocker.
+
+---
+
+## Local Validation Before Branching
+
+Before creating the release branch, validate the exact release candidate
+locally.
+
+Recommended commands:
+
+```bash
+pnpm install
+pnpm release:check
+```
+
+`pnpm release:check` runs the same full validation path used by the release
+workflow, including Playwright.
+
+If Chromium is not installed locally yet, install it once:
+
+```bash
+pnpm exec playwright install chromium
+```
+
+---
+
+## Step-by-Step Release Workflow
+
+### 1. Finalize the release on `develop`
+
+Ensure `develop` already contains the exact release content.
+
+Typical release preparation includes:
+
+- updating `package.json` from the previous version to the next release version
+- moving the relevant notes into the final section in `CHANGELOG.md`
+- committing any last release fixes
+
+Make sure the release-ready state is committed before creating `release/*`.
+
+### 2. Create the `release/*` branch
+
+Create a release branch from the validated `develop` state.
+
+Example:
+
+```bash
+git checkout develop
+git pull
+git checkout -b release/X.Y.Z
+```
+
+### 3. Merge the release branch into `main`
+
+Merge `release/*` into `main` using the repository's normal process.
+
+The critical requirement is:
+
+- `main` must contain the final release commit before tagging
+
+Conceptually:
+
+```bash
+git checkout main
+git pull
+git merge --no-ff release/X.Y.Z
+```
+
+### 4. Tag the release commit on `main`
+
+After the release branch has been merged, create the Git tag on the release
+commit that is now on `main`.
+
+Example:
+
+```bash
+git checkout main
+git pull
+git tag vX.Y.Z
+```
+
+The tag format is mandatory:
+
+- `vX.Y.Z` is valid
+- `X.Y.Z` is not valid for this workflow
+
+### 5. Push `main` and the tag
+
+Push the merged `main` branch and then the tag.
+
+Example:
+
+```bash
+git push origin main
+git push origin vX.Y.Z
+```
+
+### 6. Wait for the release workflow to finish
+
+Verify that:
+
+- the GitHub Actions release workflow passed
+- the GitHub Release was created
+- the version-check step confirmed tag and `package.json` alignment
+
+### 7. Merge `main` back into `develop`
+
+After the release has completed successfully, merge the updated `main` back
+into `develop`.
+
+Conceptually:
+
+```bash
+git checkout develop
+git pull
+git merge --no-ff main
+```
+
+---
+
+## GitHub Workflow Behavior
+
+The workflow `.github/workflows/release.yml` runs on pushed tags matching
+`vX.Y.Z`.
+
+For each matching tag it will:
+
+1. install dependencies
+2. install the Playwright Chromium browser
+3. run `pnpm validate`
+4. verify that the tag version matches `package.json`
+5. create a GitHub Release with generated release notes
+
+If any step fails, the release job stops immediately.
+
+---
+
+## Maintainer Checklist
+
+Use this as the maintainer checklist for every release:
+
+1. Verify the release scope on `develop`
+2. Update `package.json`
+3. Update `CHANGELOG.md`
+4. Run `pnpm release:check`
+5. Create `release/*` from `develop`
+6. Merge `release/*` into `main`
+7. Confirm the merged commit on `main` has the correct version and changelog
+8. Create the `vX.Y.Z` tag on `main`
+9. Push `main`
+10. Push the tag
+11. Watch the GitHub Actions release workflow
+12. Verify the GitHub Release exists
+13. Merge `main` back into `develop`

package/template/ROADMAP.md

@@ -0,0 +1,34 @@
+# Roadmap
+
+This roadmap describes intended directions, not guaranteed delivery dates.
+
+## Current priorities
+
+- Keep the starter minimal and production-like.
+- Preserve a clear bootstrap path for new KoppaJS users.
+- Keep the meta layer synchronized with the actual repository.
+
+## Near-term opportunities
+
+- Add a lightweight automated test runner when the repository gains logic that warrants it.
+- Replace or harden any documentation that still assumes old monorepo-linked dependencies.
+- Add more feature specs only when new starter capabilities are intentionally introduced.
+
+## Longer-term expansion triggers
+
+These should happen only with a spec and ADR:
+
+- routing
+- async data fetching
+- persistence
+- richer component examples
+- CI automation
+
+## Meta-layer maintenance
+
+Every release or architecture-changing change should answer:
+
+- Does the architecture document still match the code?
+- Did any new decision deserve an ADR?
+- Did testing expectations change?
+- Did contributor instructions stay accurate?

package/template/TESTING_STRATEGY.md

@@ -0,0 +1,93 @@
+# Testing Strategy
+
+## Current state
+
+This repository now has a small automated testing stack aligned with the actual starter risk profile:
+
+- `pnpm test:run` for unit and integration tests in Vitest
+- `pnpm test:coverage` for local coverage reporting
+- `pnpm test:e2e` for a Playwright smoke test against `vite preview`
+- `pnpm check` for the fast repository baseline
+- `pnpm validate` for the full local and CI validation path
+- `pnpm release:check` for tagged release candidates
+- `commitlint` through `.husky/commit-msg` for commit message validation
+- `pnpm typecheck`
+- `pnpm build`
+
+## Philosophy
+
+- Test the smallest meaningful unit that gives confidence.
+- Prefer extracting logic into `.ts` modules when it becomes complex enough to warrant focused unit tests.
+- Add test infrastructure only when the repository's behavior justifies it; do not add tools for ceremony alone.
+- Avoid brittle tests that mirror implementation details instead of observable behavior.
+- Reuse the real Vite loading path in automated tests whenever `.kpa` handling is part of the risk surface.
+
+## Test pyramid for this repository
+
+### Unit tests
+
+Use unit tests for isolated logic that can fail independently of the browser runtime. Today that includes the repo-local `.kpa` export normalization helper in `vite.config.mjs`.
+
+Typical triggers:
+
+- value transformations
+- branching business rules
+- reusable helpers
+- local tooling helpers
+
+### Integration or component tests
+
+Use integration tests when multiple local boundaries must be verified together but a full browser run would be disproportionate.
+
+Typical triggers:
+
+- bootstrap registration in `src/main.ts`
+- build-time behavior that depends on the Vite plugin
+- shared state or lifecycle interactions that are not yet broad enough for end-to-end coverage
+
+### End-to-end tests
+
+This repository has a real interactive UI, so it carries one Playwright smoke test already. Keep that layer intentionally small and user-facing.
+
+Typical triggers:
+
+- root UI rendering
+- critical starter interactions such as the counter behavior
+- preview/build regressions that would not be caught by Vitest alone
+
+Escalate E2E coverage beyond smoke scope only when the starter gains broader workflows such as routing, async data flows, persistence, or deployment-sensitive behavior.
+
+## Mocking policy
+
+- Prefer testing pure extracted logic without mocks.
+- Mock only at external boundaries such as HTTP, storage, or browser APIs that are expensive or nondeterministic.
+- Use selective mocks in integration tests only to observe bootstrap boundaries that would otherwise be opaque.
+
+## Coverage expectations
+
+- There is no blanket repository percentage target right now.
+- New non-trivial logic should come with focused tests.
+- When a subsystem introduces branching logic, asynchronous behavior, or state shared across components, test automation stops being optional.
+- Coverage reports are a decision aid, not a target game. Raise thresholds only when the code surface justifies them.
+
+## Quality gates by change size
+
+- Documentation-only change: verify links and document consistency.
+- Small style or copy change: run `pnpm check`.
+- Source or config change: run `pnpm check`.
+- UI, bootstrap, or browser-sensitive change: run `pnpm validate`.
+- Version, changelog, or release workflow change: run `pnpm release:check`.
+- Commit convention change: validate `commitlint.config.mjs` and `.husky/commit-msg` together.
+- New subsystem or new state model: add tests appropriate to the risk level and update this strategy.
+
+## Style linting position
+
+Stylelint is intentionally not part of the current baseline.
+
+- The meaningful styling surface lives inside `.kpa` files.
+- Adding Stylelint only for `src/style.css` would mostly lint the global reset and miss the component-local styles that matter.
+- Revisit this decision only when KoppaJS gains a low-friction way to lint embedded `.kpa` CSS blocks or when the repository starts moving substantial styles into standalone CSS files.
+
+## Maintenance rule
+
+Whenever test tooling, quality gates, or expected confidence levels change, update this file and [docs/quality/quality-gates.md](./docs/quality/quality-gates.md) in the same change.

package/template/_editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_size = 2
+indent_style = space
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false

package/template/_gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

package/template/_github/instructions/ai-workflow.md

@@ -0,0 +1,33 @@
+# AI Workflow Instructions
+
+## Read before editing
+
+For any non-trivial change, read these documents in order:
+
+1. `DECISION_HIERARCHY.md`
+2. `AI_CONSTITUTION.md`
+3. `ARCHITECTURE.md`
+4. the relevant spec in `docs/specs/`
+5. the relevant ADR in `docs/adr/`
+6. `DEVELOPMENT_RULES.md`
+7. `TESTING_STRATEGY.md`
+
+For release-related work also read `CHANGELOG.md` and `RELEASE.md`.
+
+## Required behavior
+
+- Prefer existing repository patterns over new abstractions.
+- Do not silently change public component tags, startup flow, or dependency sourcing.
+- Use `spec -> quality plan -> implementation -> documentation`.
+- Update the meta layer in the same change when architecture, rules, or workflows change.
+- Record durable technical decisions in ADRs.
+- Keep hooks fast and put heavier validation into `pnpm validate` and CI.
+- If versioning, changelog, or release automation changes, update `CHANGELOG.md`, `RELEASE.md`, and the affected workflow in the same change.
+- If you create commits, use Conventional Commits that satisfy `commitlint`.
+
+## Required validation
+
+- Run `pnpm check` for source, config, test, or tooling changes.
+- Run `pnpm validate` when UI behavior, bootstrap wiring, browser-facing assets, or quality tooling changes.
+- Run `pnpm release:check` when versioning, changelog, or release workflow behavior changes.
+- If a local browser check cannot be run, say so explicitly instead of implying it passed.

package/template/_github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  pull_request:
+    branches:
+      - develop
+      - main
+  push:
+    branches:
+      - main
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10.12.1
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Install Playwright browser
+        run: pnpm exec playwright install --with-deps chromium
+
+      - name: Run repository validation
+        run: pnpm validate

package/template/_github/workflows/release.yml

@@ -0,0 +1,58 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  release:
+    name: Create GitHub Release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10.12.1
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Install Playwright browser
+        run: pnpm exec playwright install --with-deps chromium
+
+      - name: Validate repository
+        run: pnpm validate
+
+      - name: Verify tag matches package.json version
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          PKG_VERSION=$(node -p "require('./package.json').version")
+          echo "Tag version: $TAG_VERSION"
+          echo "Package.json version: $PKG_VERSION"
+          if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
+            echo "::error::Version mismatch! Tag ($TAG_VERSION) does not match package.json ($PKG_VERSION)"
+            exit 1
+          fi
+          echo "Versions match: $TAG_VERSION"
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/template/_gitignore

@@ -1,5 +1,10 @@
 node_modules
+coverage
 dist
+.ai
+playwright-report
+test-results
+pnpm-debug.log*
 *.log
 *.local
 .DS_Store

package/template/_husky/commit-msg

@@ -0,0 +1,8 @@
+commit_msg_file="$1"
+commit_msg_content=$(cat "$commit_msg_file")
+
+if echo "$commit_msg_content" | grep -qE "^(Merge|Revert|fixup!|squash!)"; then
+  exit 0
+fi
+
+pnpm exec commitlint --config commitlint.config.mjs --edit "$commit_msg_file"

package/template/_husky/pre-commit

@@ -0,0 +1 @@
+pnpm exec lint-staged

package/template/_npmrc

@@ -0,0 +1 @@
+engine-strict=true

package/template/_prettierignore

@@ -0,0 +1,7 @@
+.ai
+coverage
+dist
+node_modules
+playwright-report
+pnpm-lock.yaml
+test-results

package/template/commitlint.config.mjs

@@ -0,0 +1,6 @@
+export default {
+  extends: ["@commitlint/config-conventional"],
+  rules: {
+    "header-max-length": [2, "always", 72],
+  },
+};

package/template/docs/adr/0001-keep-the-starter-minimal.md

@@ -0,0 +1,32 @@
+# ADR 0001: Keep the starter minimal
+
+## Context
+
+This repository starts from the maintained minimal starter baseline for KoppaJS
+applications. Its primary audience needs a runnable reference with as little
+incidental complexity as possible.
+
+## Decision
+
+The starter remains intentionally small:
+
+- one HTML shell,
+- one TypeScript bootstrap file,
+- one root KoppaJS view,
+- one stateful child component,
+- published npm packages instead of local monorepo `file:` dependencies,
+- no routing, persistence, shared state, or extra demo subsystems by default.
+
+Any expansion beyond that baseline requires a spec and ADR.
+
+## Consequences
+
+- New users get a fast, low-noise example.
+- The repository stays easy to audit and maintain.
+- More advanced features must be introduced deliberately rather than accumulating ad hoc.
+- Some capabilities are intentionally absent until justified.
+
+## Alternatives considered
+
+- A feature-rich demo app that showcases many KoppaJS patterns at once
+- A monorepo-linked starter that depends on local sibling packages

package/template/docs/adr/0002-adopt-a-living-meta-layer.md

@@ -0,0 +1,30 @@
+# ADR 0002: Adopt a living meta layer
+
+## Context
+
+The repository previously lacked a formal architecture memory, contributor governance, testing philosophy, decision hierarchy, and AI workflow guidance. That made it easy for the implementation and the documentation to drift apart.
+
+## Decision
+
+The project will maintain an in-repository meta layer consisting of:
+
+- root governance documents,
+- architecture support documents under `docs/architecture/`,
+- ADRs under `docs/adr/`,
+- specs under `docs/specs/`,
+- quality and maintenance guidance under `docs/quality/` and `docs/meta/`,
+- AI-specific workflow guidance under `.github/instructions/`.
+
+Whenever architecture, module boundaries, workflow, or quality expectations change, the relevant meta documents must be updated in the same change.
+
+## Consequences
+
+- Contributors and AI agents have a single source of truth inside the repository.
+- Architectural drift becomes easier to detect.
+- Every meaningful change carries a small documentation obligation.
+- The repository gains governance overhead, but the overhead is intentionally light and local.
+
+## Alternatives considered
+
+- Relying on README-only guidance
+- Keeping architectural decisions in issues or chat history instead of versioned documents

package/template/docs/adr/0003-normalize-kpa-plugin-output.md

@@ -0,0 +1,24 @@
+# ADR 0003: Normalize KPA plugin output
+
+## Context
+
+The installed `@koppajs/koppajs-vite-plugin` currently transforms `.kpa` files into raw object literals during Vite loading. Rollup expects valid ES module syntax, so production builds fail unless the transformed output is wrapped in an export.
+
+## Decision
+
+Keep using the upstream KoppaJS Vite plugin, but add a small repo-local post-transform in `vite.config.mjs` that converts raw `.kpa` object literals into `export default ...` modules.
+
+This workaround remains in place until the upstream plugin emits valid module syntax on its own.
+
+## Consequences
+
+- The repository builds successfully without changing application source files.
+- The workaround is isolated to build configuration.
+- Future maintainers must remove or revise the wrapper if the upstream plugin behavior changes.
+- Architecture documentation must reflect that the build stack includes this compatibility layer.
+
+## Alternatives considered
+
+- Patching `node_modules` directly
+- Rewriting application imports around the plugin defect
+- Leaving the repository in a state where `pnpm build` fails

package/template/docs/adr/0004-adopt-an-automated-quality-baseline.md

@@ -0,0 +1,31 @@
+# ADR 0004: Adopt an automated quality baseline
+
+## Context
+
+The repository already had a living meta layer and a real interactive UI, but its practical quality gates were still limited to `pnpm typecheck`, `pnpm build`, and manual smoke testing. That left the repo-local `.kpa` build workaround, bootstrap wiring, and browser-visible starter behavior exposed to easy regression.
+
+## Decision
+
+Adopt a proportional automated quality baseline for the starter:
+
+- ESLint for TypeScript source and tooling files,
+- Prettier and `.editorconfig` for supported text formats,
+- Vitest for unit and integration coverage of local tooling and bootstrap behavior,
+- Playwright for one Chromium smoke path against `vite preview`,
+- Husky and lint-staged for fast staged-file checks,
+- GitHub Actions CI that runs the same validation flow as local contributors.
+
+Do not add Stylelint yet. The meaningful styles live inside `.kpa` blocks, and a CSS-file-only lint setup would give false confidence while adding maintenance overhead.
+
+## Consequences
+
+- The starter gets repeatable local and CI validation without inflating the runtime architecture.
+- Browser-visible regressions are caught automatically instead of relying only on manual smoke tests.
+- Contributors have a clearer script contract: `check` for the fast baseline and `validate` for the full suite.
+- Future maintainers must keep the test, hook, CI, and documentation layers aligned when the quality stack changes.
+- Stylelint remains an explicit future decision instead of an accidental omission.
+
+## Alternatives considered
+
+- Staying on `typecheck + build + manual smoke test`
+- Adding a heavier test and lint stack, including Stylelint, before the repository has enough surface area to justify it