🚀 Release 0.1.4

Latest releases of the two oxc tools; both minor bumps within 0.x/1.x
semver ranges. check-outdated now reports zero outdated dependencies
and npm run verify passes with no rule or format fallout.

.gitea/workflows/ci.yml

@@ -0,0 +1,191 @@
+name: CI
+
+on:
+    push:
+        branches: [main]
+        # Releases are tag pushes (`scripts/release.sh` tags bare `x.y.z`). A
+        # `branches` filter alone matches no tag ref, so without this both the
+        # tag-gated `publish` job and the coverage publish step never fire.
+        tags: ["*"]
+    pull_request:
+        branches: [main]
+    workflow_dispatch: {}
+
+jobs:
+    # Cheap gate that collapses the release double-run. `scripts/release.sh`
+    # pushes `main` and the tag seconds apart, and the tag points at exactly
+    # the HEAD commit that push delivers — so the branch run would verify the
+    # identical tree the tag run verifies anyway (plus `publish`). When a push
+    # to `main` is headed by a release commit (`:rocket: Release x.y.z`, the
+    # single commit release.sh creates), the full CI is skipped here and the
+    # tag run becomes the authoritative one for that SHA. All other pushes —
+    # PRs, tags, ordinary `main` merges — see `skip=false` and run as before.
+    #
+    # Coupling: the pattern below MUST stay in sync with the release commit
+    # message in `scripts/release.sh`. Failure mode if the tag push ever fails
+    # after `main` accepted the release commit: no CI fires; fix by re-running
+    # `git push --tags`.
+    release-gate:
+        runs-on: ubuntu-latest
+        outputs:
+            skip: ${{ steps.decide.outputs.skip }}
+        steps:
+            - uses: actions/checkout@v4
+            - id: decide
+              env:
+                  REF: ${{ gitea.ref }}
+              run: |
+                  # Keyed on the ref, not just the message: a tag run checks out
+                  # the same release commit, and `publish` needs its `build`.
+                  if [ "${REF}" = "refs/heads/main" ] &&
+                      git log -1 --format=%s | grep -qE '^:rocket: Release [0-9]+\.[0-9]+\.[0-9]+$'; then
+                      echo 'Release commit on main — the tag run covers this SHA; skipping full CI.'
+                      echo 'skip=true' >>"${GITHUB_OUTPUT}"
+                  else
+                      echo 'skip=false' >>"${GITHUB_OUTPUT}"
+                  fi
+
+    build:
+        needs: release-gate
+        if: needs.release-gate.outputs.skip != 'true'
+        runs-on: ubuntu-latest
+        # `image` extends the runner's default job image (catthehacker/act)
+        # with Node 26 pre-planted in the tool cache layout, so setup-node's
+        # version probe hits and never downloads (see docker/Dockerfile). The
+        # tag MUST equal the exact version pinned in `.node-version`; the bump
+        # ritual is documented in CONTRIBUTING.md § CI runner image. The volume
+        # bind-mounts the shared pages tree so the
+        # coverage step below can write into it; the runner whitelists this
+        # path via `container.valid_volumes` (docker-space `setup/gitea.sh`).
+        container:
+            image: gitea.e1nsnull.de/tmu/act-ci:26.8.2
+            volumes:
+                - /data/gitea-pages:/data/gitea-pages
+        steps:
+            - uses: actions/checkout@v4
+            # Fail fast when the job container is not the baked image: a stale
+            # tag on the runner (`forcePull=false` in its pull log) silently
+            # reintroduces the per-job download. Mirrors the publish job's
+            # NPM_TOKEN assert — cheap, and it names the invariant.
+            - name: Assert the baked tool cache is present
+              run: |
+                  test -f "/opt/hostedtoolcache/node/$(tr -d '[:space:]' < .node-version)/x64.complete"
+            - uses: actions/setup-node@v4
+              with:
+                  node-version-file: .node-version
+                  cache: "npm"
+            - run: npm ci
+            - run: npm run build
+            - run: npm run check
+            - run: npm run test:ci
+            # Publish this tag's coverage to the self-hosted pages server,
+            # served read-only at
+            # https://pages.e1nsnull.de/<owner>/<repo>/<tag>/coverage/. Wipe only
+            # this tag's `coverage/`, so sibling docs/landing trees and older
+            # tags survive; pruning stale tags is a manual chore. The
+            # precompress pass emits `.br` / `.gz` / `.zst` sidecars next to
+            # every text asset, so `static-web-server` can serve the precompressed
+            # variant and keep the original as fallback.
+            - name: Publish coverage to the pages server
+              if: startsWith(gitea.ref, 'refs/tags/')
+              env:
+                  REPO: ${{ github.repository }}
+                  REF: ${{ gitea.ref }}
+              run: |
+                  TAG="${REF#refs/tags/}"
+                  DEST="/data/gitea-pages/${REPO}/${TAG}/coverage"
+                  rm -rf "${DEST}"
+                  mkdir -p "${DEST}"
+                  cp -R coverage/. "${DEST}/"
+                  node --strip-types scripts/precompress.ts "${DEST}"
+                  echo "Coverage: https://pages.e1nsnull.de/${REPO}/${TAG}/coverage/"
+            # Fast, offline packaging gate. `attw` stays in `publish` (it needs
+            # a pack + full resolution matrix); `publint` packs too but is cheap
+            # enough to run on every push so a packaging break fails here, not
+            # at release time.
+            - run: npm run publish:publint
+            # Persist the exact dist/ that `check`, `test:ci` and `publint` were
+            # run against, so `publish` ships those bytes instead of rebuilding
+            # (which could in principle differ and would pay the build twice).
+            - uses: actions/upload-artifact@v4
+              with:
+                  name: dist
+                  path: dist/
+
+    # Advisory scans (dead code, dependency freshness). Non-blocking: surfaced in
+    # the Actions tab for visibility, but must never gate a merge — so
+    # continue-on-error and intentionally NOT in `publish`'s `needs`.
+    maintain:
+        needs: release-gate
+        if: needs.release-gate.outputs.skip != 'true'
+        runs-on: ubuntu-latest
+        continue-on-error: true
+        # Same baked image as `build` — without it this job re-downloads Node
+        # per run (see docker/Dockerfile).
+        container:
+            image: gitea.e1nsnull.de/tmu/act-ci:26.8.2
+        steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-node@v4
+              with:
+                  node-version-file: .node-version
+                  cache: "npm"
+            - run: npm ci
+            - run: npm run maintain
+
+    publish:
+        if: startsWith(gitea.ref, 'refs/tags/')
+        needs: build
+        runs-on: ubuntu-latest
+        # Same baked image as `build` — setup-node still owns the registry-url
+        # `.npmrc` rewrite here; only the Node download is skipped.
+        container:
+            image: gitea.e1nsnull.de/tmu/act-ci:26.8.2
+        # The release page is created with the run's automatic Gitea token
+        # (`github.token`), not `NPM_TOKEN`, so it needs `contents: write`.
+        permissions:
+            contents: write
+        steps:
+            # Double-gate: publish only runs on a tag *and* aborts here if NPM_TOKEN
+            # is unset, so a tag push never silently no-ops (or half-publishes). Set
+            # NPM_TOKEN in the Gitea repo: Settings → Actions → Secrets.
+            - name: Assert NPM_TOKEN is configured
+              run: |
+                  if [ -z "${{ secrets.NPM_TOKEN }}" ]; then
+                      echo "::error::NPM_TOKEN secret is not set — refusing to publish."
+                      exit 1
+                  fi
+            - uses: actions/checkout@v4
+            - uses: actions/setup-node@v4
+              with:
+                  node-version-file: .node-version
+                  # Same lockfile/key as `build`, and tag runs can read caches
+                  # saved on `main` — without this, every release pays a cold
+                  # `npm ci` despite the warm shared npm cache.
+                  cache: "npm"
+                  registry-url: "https://registry.npmjs.org/"
+            - run: npm ci
+            # Consume the dist/ that `build` produced and gated, instead of
+            # rebuilding here — `publish` must ship the tested artifact.
+            - uses: actions/download-artifact@v4
+              with:
+                  name: dist
+                  path: dist/
+            - run: npm run publish:publint
+            - run: npm run publish:attw
+            # The Gitea release page is created *before* `npm publish` on
+            # purpose: a broken page then fails CI without burning an npm
+            # version. The page is cheap to retry, a published version is not.
+            # The body is the matching Keep-a-Changelog section; an unknown tag
+            # makes the extractor exit non-zero, so the page can never go up
+            # empty.
+            - name: Extract release notes from CHANGELOG.md
+              env:
+                  TAG_REF: ${{ gitea.ref }}
+              run: ./scripts/release-notes.sh "${TAG_REF#refs/tags/}" > release-notes.md
+            - uses: https://gitea.com/actions/gitea-release-action@v1
+              with:
+                  body_path: release-notes.md
+            - run: npm publish --access public
+              env:
+                  NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.github/workflows/ci.yml

@@ -1,43 +0,0 @@
-name: CI
-
-on:
-    push:
-        branches: [main]
-    pull_request:
-        branches: [main]
-    workflow_dispatch: {}
-
-jobs:
-    build:
-        runs-on: ubuntu-latest
-        steps:
-            - uses: actions/checkout@v4
-            - uses: actions/setup-node@v4
-              with:
-                  node-version-file: .node-version
-                  cache: "npm"
-            - run: npm ci
-            - run: npm run build
-            - run: npm run check
-            - run: npm run test:ci
-            - name: Upload coverage
-              uses: actions/upload-artifact@v4
-              with:
-                  name: coverage
-                  path: coverage
-
-    publish:
-        if: startsWith(github.ref, 'refs/tags/')
-        needs: build
-        runs-on: ubuntu-latest
-        steps:
-            - uses: actions/checkout@v4
-            - uses: actions/setup-node@v4
-              with:
-                  node-version-file: .node-version
-                  registry-url: "https://registry.npmjs.org/"
-            - run: npm ci
-            - run: npm run build
-            - run: npm publish --access public
-              env:
-                  NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.gitignore

@@ -1,16 +1,8 @@
-# Logs
-logs
-*.log
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
-pnpm-debug.log*
-lerna-debug.log*
-
-coverage
 node_modules
 dist
-dist-ssr
+coverage
+*.log
+*.tsbuildinfo
 *.local
 
 # Editor directories and files
@@ -20,8 +12,3 @@ dist-ssr
 !.vscode/tasks.json
 .idea
 .DS_Store
-*.suo
-*.ntvs*
-*.njsproj
-*.sln
-*.sw?

.node-version

@@ -1 +1 @@
-26
+26.8.2

.npmignore

@@ -1,14 +0,0 @@
-node_modules/
-coverage/
-*.log
-*.tsbuildinfo
-src/
-.vscode/
-.editorconfig
-.oxfmtrc.json
-.oxlintrc.json
-.node-version
-cspell.json
-lefthook.yml
-LICENSE
-commit-message-template

.npmrc

@@ -0,0 +1,5 @@
+# Turn the `engines` field from a warning into a gate. By default a Node
+# version mismatch is only reported as a notice, so an install run under an
+# unpinned Node still succeeds and silently rewrites package-lock.json using
+# that older npm's resolution rules. Refuse the install instead.
+engine-strict=true

.oxlintrc.json

@@ -13,13 +13,17 @@
         "eslint/no-undefined": "off",
         "eslint/sort-keys": "off",
         "eslint/id-length": "off",
-        "import/no-named-export": "off"
+        "import/no-named-export": "off",
-    },
+        "eslint/one-var": "off",
-    "env": {
+        "import/group-exports": "off",
-        "builtin": true,
+        "import/exports-last": "off",
-        "es2024": true,
+        "eslint/sort-imports": "off",
-        "node": true
+        "import/consistent-type-specifier-style": "off",
+        "unicorn/prefer-export-from": "off",
+        "typescript/method-signature-style": "off"
     },
+    "options": { "typeAware": true },
+    "env": { "builtin": true, "es2024": true, "node": true },
     "overrides": [
         {
             "files": ["**/*.test.ts"],
@@ -29,6 +33,12 @@
                 "import/no-nodejs-modules": "off",
                 "eslint/no-magic-numbers": "off"
             }
+        },
+        {
+            "files": ["scripts/**/*.ts"],
+            "rules": {
+                "import/no-nodejs-modules": "off"
+            }
         }
     ],
     "ignorePatterns": ["dist", "node_modules", "coverage"]

.pi/npm/.gitignore

@@ -0,0 +1,2 @@
+*
+!.gitignore

.pi/settings.json

@@ -0,0 +1,3 @@
+{
+    "packages": ["npm:@spences10/pi-lsp@0.0.46"]
+}

.vscode/extensions.json

@@ -2,6 +2,8 @@
     "recommendations": [
         "oxc.oxc-vscode",
         "streetsidesoftware.code-spell-checker",
-        "typescriptteam.native-preview"
+        "typescriptteam.native-preview",
+        "sandy081.todotasks",
+        "EditorConfig.EditorConfig"
     ]
 }

.vscode/settings.json

@@ -3,10 +3,18 @@
         "editor.defaultFormatter": "oxc.oxc-vscode",
         "editor.formatOnSave": true
     },
+    "[typescriptreact]": {
+        "editor.defaultFormatter": "oxc.oxc-vscode",
+        "editor.formatOnSave": true
+    },
     "[javascript]": {
         "editor.defaultFormatter": "oxc.oxc-vscode",
         "editor.formatOnSave": true
     },
+    "[javascriptreact]": {
+        "editor.defaultFormatter": "oxc.oxc-vscode",
+        "editor.formatOnSave": true
+    },
     "[json]": {
         "editor.defaultFormatter": "oxc.oxc-vscode",
         "editor.formatOnSave": true

AGENTS.md

@@ -0,0 +1,68 @@
+# AGENTS.md
+
+Machine entry point for AI coding agents working in this repo. The authoritative
+guidance for humans lives in [CONTRIBUTING.md](./CONTRIBUTING.md) and
+[README.md](./README.md); this file only points at it and states the stable
+first-action facts. Do not restate evolving prose here — it will drift.
+
+## First action
+
+- Project: F#-style pattern matching for TypeScript/ESM. Node `>=26` (pinned via `.node-version`), ESM-only (no CommonJS shim).
+- **While iterating:** `npm run test` (`check:tsc` + the unit suite) for fast feedback on the files you changed.
+- **Optional code intelligence:** this repo installs `@spences10/pi-lsp` (pinned in `.pi/settings.json`) as a project-local pi extension. It talks to the repo's own TypeScript 7 via `tsc --lsp --stdio` and exposes **read-only** tools — `lsp_hover`, `lsp_definition`, `lsp_references`, `lsp_find_symbol`, `lsp_document_symbols`, `lsp_diagnostics(_many)`. Prefer `lsp_references` over `grep -w` for widely-colliding identifiers (`matches`, `type`, …); use `lsp_hover` to read inferred types on generic-heavy code. It has no rename / code-action / apply-edit surface — the write side is pi's `edit` tool + `check:tsc`. Treat empty LSP output as _inconclusive_, not success: **`npm run test` / `npm run verify` remain the sole authoritative gate** (see the next bullet). The server keeps running across that gate with a ~5 min idle timeout and registers no file watchers, so if you change `tsconfig.json` / `package.json` mid-session its diagnostics can be stale — when LSP output disagrees with `check:tsc`, trust `check:tsc` and restart pi (or wait out the idle timeout) before concluding the LSP is wrong.
+- **Definition of done — run this before you call the work finished:** `npm run verify`. If all green, commit. If red, look at the output, fix the root cause, and re-run.
+- **On commit:** write a good message (see [CONTRIBUTING.md § Commit messages](./CONTRIBUTING.md#commit-messages)). Lefthook's pre-commit hook already runs the fast, offline, staged-file checks — don't run them by hand. If the hook fails on style, `npm run fix`, restage, recommit.
+- **`npm run maintain` is NOT part of the feature loop.** Its scans are advisory, never a gate; run them only on an explicit maintenance / update-deps branch.
+
+    ```sh
+    npm run test    # while iterating (fast feedback)
+    npm run verify  # definition of done: whole-project correctness, one shot
+    ```
+
+## Never do
+
+Don't silence the type system to force a green run. As an agent these are forbidden:
+
+- `// @ts-nocheck`, `// @ts-ignore`, `// @ts-expect-error`
+- `// oxlint-disable` / `// oxlint-disable-next-line`
+- `as` casts used to push an expression through (type-aware oxlint already flags unsafe assertions)
+
+Fix the root cause with the type system instead — narrowing, generics, `satisfies`, conditional / mapped types, utility types (`NonNullable`, `Exclude`, …). TypeScript can express it; that's the intended tool. The `oxlint-disable`-location rule in [CONTRIBUTING.md § Rules the tools don't enforce](./CONTRIBUTING.md#rules-the-tools-dont-enforce) is a **human** last-resort convention (so a reviewer can spot a deliberate suppression) — it is not permission for you to add one. If the types genuinely cannot express something, stop and surface the conflict (commit message / handover) rather than suppress it.
+
+The same applies to the checks themselves: **never `git commit --no-verify`** (or otherwise skip a pre-commit / pre-push hook). The checks are fast and offline, so a redundant run is fine — bypassing a hook to get green is the identical anti-pattern. If a commit already skipped a hook, redo it through one: `git reset --soft HEAD~1 && git commit -C <skipped-sha>`.
+
+Never start a long-lived / blocking process such as `npm run watch`. It runs until a human stops it with Ctrl-C, so in an agent turn it hangs forever and floods the context with continuous output. Reach for a one-shot command instead — `npm run test` (or `npm run check`) — to get feedback.
+
+## Backlog
+
+`backlog.tasks` uses the vscode-todotasks format (not Markdown). A line ending in `:` is a project; every other line is a task. Status glyphs: `☐` open, `✔` done, `✘` cancelled; subtasks nest by indentation. Inline `@tags` carry metadata — `@done` / `@cancelled` mark completion, `@critical` / `@high` / `@low` / `@today` set priority. The `(…)` timestamp after `@done` is editor-generated: omit it when checking off by hand.
+
+**Required coupling:** a `✔` line _must_ also carry `@done`, and a `✘` line _must_ carry `@cancelled`. The `sandy081.todotasks` extension treats the glyph as the completion signal, then unconditionally searches for the matching tag to decorate; a bare `✔`/`✘` with no tag makes it compute an illegal `Range` (negative character offset) that throws and kills all highlighting/decoration for the document. A `☐` may stand alone. So check off by hand as `✔ … @done` (optionally `@done (timestamp)`), never a lone `✔`.
+
+### Working on tasks
+
+- **Task with subtasks** (a task that has indented children): create the branch with `npm run create:branch -- <prefix>/<desc>`, inferring the prefix from the task content (`feature/…` / `fix/…` / `chore/…`) — do not hand-write `git switch -c`, the command enforces the clean-tree / current-`main` / green-baseline precondition. Work on each subtask with commits, then present a concise handover for the user to review. Use this fixed shape:
+
+    ```md
+    ## Handover — <branch>
+
+    **Implemented:** <what was built, and how>
+    **Judgement calls:** <where the task was unclear, and what you assumed>
+    **Known problems:** <open issues, caveats, follow-ups>
+    ```
+
+    Once the user has no further objections, merge back: `npm run create:finish` (on the branch — it merges `--no-ff`, runs `npm run verify`, and deletes the branch). The branching model is documented in [CONTRIBUTING.md § Branching model](./CONTRIBUTING.md#branching-model).
+
+- **Leaf task** (no indented children): implement on the current branch and commit.
+
+In both cases, follow [CONTRIBUTING.md § Testing discipline (type-driven)](./CONTRIBUTING.md#testing-discipline-type-driven). Each subtask gets one or more commits.
+
+## Read these
+
+- [CONTRIBUTING.md § Rules the tools don't enforce](./CONTRIBUTING.md#rules-the-tools-dont-enforce) — the constraints the linters don't catch; CI/review bounce these. **The most important section.**
+- [CONTRIBUTING.md § Testing discipline (type-driven)](./CONTRIBUTING.md#testing-discipline-type-driven) — write the `expectTypeOf` (type) before the `assert` (red); the types are the feature.
+- [CONTRIBUTING.md § Script prefix convention](./CONTRIBUTING.md#script-prefix-convention) — adding an `npm run` script? reuse an existing prefix or it doesn't belong.
+- [CONTRIBUTING.md § Commit messages](./CONTRIBUTING.md#commit-messages) — gitmoji + imperative + 50/72.
+- [CONTRIBUTING.md § Feedback tiers](./CONTRIBUTING.md#feedback-tiers) — what runs when and at what cost (`watch` / pre-commit / pre-push / `check` / `verify` / `fix` / `maintain` / CI).
+- [README.md § Tooling decisions](./README.md#tooling-decisions) — the rationale behind each tool choice; read before changing tooling.
+- [package.json `#scripts`](./package.json) — the source of truth for every command (the `LEFTHOOK_FILES` convention scopes them to staged files vs. the whole project).

CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0/).
+
+## [Unreleased]
+
+## [0.1.4] - 2026-09-14
+
+- fix CI to node from custom image
+- upgrade dependencies
+
+## [0.1.3] - 2026-09-14
+
+- change to custom image for CI
+
+## [0.1.2] - 2026-09-14
+
+- upgrade dependencies
+
+## [0.1.1] - 2026-09-14
+
+- upgrade dependencies
+
+## [0.1.0] - 2026-09-14
+
+- basic setup
+
+[Unreleased]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.4...main
+[0.1.4]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.3...0.1.4
+[0.1.3]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.2...0.1.3
+[0.1.2]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.1...0.1.2
+[0.1.1]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.0...0.1.1
+[0.1.0]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/20308c5a6d8cccfb09b02ac2ebebd8055e91cd11...0.1.0

CONTRIBUTING.md

@@ -0,0 +1,117 @@
+# Contributing
+
+This document is for maintainers and contributors working on the project itself. End-user documentation is in [README.md](./README.md). The machine entry point for AI coding agents is [AGENTS.md](./AGENTS.md); keep this file as the prose home for the rules below so agents and humans don't diverge.
+
+## Rules the tools don't enforce
+
+CI and review will bounce these even though `npm run check` and the linters don't catch them. They're the high-frequency things a contributor (or an agent) reaches for by default:
+
+- **Source imports use `.ts` extensions, never `.js`.** `node --strip-types` only resolves the `.ts` form at test time; "Pre-fixing" an import to `.js` breaks the inner loop. (rationale: README § Tooling decisions)
+- **A new `npm run` script must reuse an existing prefix** (`create:` / `check:` / `fix:` / `test:` / `watch:` / `maintain:` / `publish:` / `setup:`). If none fits, that's a signal the script doesn't belong in the pipeline — not a reason to invent a new prefix. If it genuinely does belong, add the prefix to both lists here in the same commit; an undocumented prefix becomes invisible and quietly accrues members. (see [Script prefix convention](#script-prefix-convention))
+- **`oxlint-disable` directives live in source, not `.oxlintrc.json`.** The trade-off must sit next to the code it silences. This is a _human_ last-resort convention; agents must not add these — see [AGENTS.md § Never do](./AGENTS.md#never-do). (rationale: README § Tooling decisions)
+- **Don't put slow / network / whole-project scans in `check` or pre-commit.** Advisory scans are not correctness gates; they belong under `maintain:`. (see [Feedback tiers](#feedback-tiers) and [Script prefix convention](#script-prefix-convention))
+- **New work starts with `npm run create:branch`, never a hand-written `git switch -c`/`git checkout -b`.** The command carries the branch precondition; branching around it skips the clean-tree, current-`main` and green-baseline checks, and the skip is invisible until a failure can no longer be attributed. (see [Branching model](#branching-model))
+- **Work is merged back with `npm run create:finish`, never a hand-written `git merge`.** The command carries the merge-side preconditions (clean tree, current `main`, a `feature/`/`fix/`/`chore/` branch) and runs `npm run verify` after the merge, so a merge cannot land unverified. (see [Branching model](#branching-model))
+- **There is no local `npm run publish`, and `publish:publint` / `publish:attw` don't go in `check`.** (see [Publishing workflow](#publishing-workflow))
+
+## Editor configuration
+
+`.editorconfig` is for editor compatibility, not a gate — it is a sane fallback for the files oxfmt does not format (shell scripts, dotfiles, `LICENSE`, the commit-message template, and git's `COMMIT_EDITMSG` buffer). Where both apply, `.oxfmtrc.json` is authoritative: oxfmt is the formatter, and the overlapping `.editorconfig` keys only keep non-oxfmt editors close to the formatted result.
+
+## Commit messages
+
+Gitmoji subject, imperative mood, 50/72 wrapping. The template is `commit-message-template`; run `npm run setup:git-commit-message` once after cloning to register it as git's `commit.template` (or `npm run setup` to run every one-time clone step).
+
+Examples from history: `:sparkles: Add watch tier with watch:test child`, `:recycle: Move type-aware config to .oxlintrc.json; use source-level disable directives`, `:memo: Restore unique maintainer content as CONTRIBUTING.md`. The body explains _what and why_, not _how_; link issues with `Resolves #...`.
+
+## Script prefix convention
+
+Script names in `package.json` use a prefix that signals _when_ the script is intended to run. A `<prefix>:<name>` script is implicitly aggregated by a `<prefix>` script (if one exists) and run by the corresponding lefthook hook or CI step. Picking the right prefix documents the script's intended lifecycle:
+
+- `create:*` — front doors of the repo's own workflow; these mutate git state rather than the source. `create:branch` opens a unit of work (asserts a clean tree, a current `main` and a green baseline before it branches), `create:finish` closes the branch half (merges the current unit of work into `main` and verifies the result), `create:release` closes the release half (maintainer-only). No bare `create` aggregator on purpose — see `publish:*` for the precedent.
+- `check:*` — read-only verification; never modifies files. Aggregated by `npm run check`.
+- `fix:*` — mutating counterpart of a `check:*` script. Aggregated by `npm run fix`; the diff is the review surface.
+- `test:*` — test scripts. `test` is the canonical entry point (`check:tsc` + unit tests); `test:unit` skips the typecheck for fast local iteration; `test:ci` adds c8 coverage.
+- `watch:*` — long-running watchers for the manual inner dev loop. Aggregated by `watch`; currently a single child (`watch:test`), and a future `watch:oxlint` / `watch:tsc` would run concurrently under that umbrella.
+- `maintain:*` — advisory repo-maintenance scans: read-only, but whole-project and/or network-bound, so never a correctness gate. Aggregated by `npm run maintain`.
+- `publish:*` — validates the _publishable artifact_ (e.g. `dist/`) rather than the source, so it needs a fresh build. (see [Rules the tools don't enforce](#rules-the-tools-dont-enforce) and [Publishing workflow](#publishing-workflow))
+- `setup:*` — one-time configuration of a fresh clone; mutates the local environment (git config, editor settings) rather than the repo source, so it is never part of a hook or CI step. Aggregated by `npm run setup` (the umbrella), run once after cloning.
+
+A new script should pick the prefix that matches its lifecycle, not invent a new one. If no existing prefix fits, that's a signal the script doesn't belong in the standard pipeline. When it genuinely does belong, a new prefix is allowed — but it enters both lists in this file in the same commit as its first member, otherwise the rule "reuse an existing prefix" silently develops an exception (the old `use:` prefix was exactly that; it is now retired into `setup:`).
+
+Separately, some top-level scripts are **bare** (no prefix): the entry points that either run a single tool (`build`, `clean`) or aggregate a `prefix:*` family (`check`, `fix`, `test`, `watch`, `maintain`, `setup`), plus one convenience that composes across tiers: `verify` — composing `check` + `test:unit` into one whole-project correctness gate (it deliberately uses `test:unit` rather than `test` because `check` already runs `check:tsc`, so the type checker runs exactly once). Bare commands are how you invoke a tier; the `prefix:*` scripts are what those tiers are made of.
+
+## Feedback tiers
+
+The tools are organized into a feedback ladder. Each tier catches different things at different costs; the rule of thumb is "earlier tiers fire more often, faster tiers catch less, slower tiers are more thorough":
+
+| Tier                             | When                    | What it runs                                                                                             | Time  |
+| -------------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------- | ----- |
+| `npm run watch`                  | manual                  | `watch:test` — re-runs tests on file save                                                                | ~0.1s |
+| Pre-commit (auto)                | on stage                | tsc + oxlint + oxfmt + cspell (staged files only)                                                        | ~1.3s |
+| Pre-push (auto)                  | on push                 | `npm test` (full tsc + unit tests)                                                                       | ~3.5s |
+| `npm run check`                  | manual                  | Correctness gates: tsc + oxlint + oxfmt + cspell (whole project)                                         | ~3s   |
+| `npm run verify`                 | manual                  | Definition of done: `npm run check` + unit tests, one shot                                               | ~6s   |
+| `npm run fix`                    | manual                  | Auto-resolve fixable issues (lint, format)                                                               | ~3s   |
+| `npm run maintain`               | manual / CI (advisory)  | `maintain:knip` + `maintain:outdated` (whole-project + network scans)                                    | ~10s  |
+| CI build (auto)                  | on push to `main` / tag | `build` job (build + correctness + packaging) — see [.gitea/workflows/ci.yml](./.gitea/workflows/ci.yml) | ~30s+ |
+| CI maintain (auto, non-blocking) | on push to `main`       | `npm run maintain` — reports, never fails the build                                                      | ~10s  |
+| CI publish (auto)                | on tag                  | Gitea release page (body from CHANGELOG) + `publish:publint` + `publish:attw`, then `npm publish`        | ~15s  |
+
+### Why these splits?
+
+- **`watch:*` is a manual tier, not a hook.** The developer starts it on demand (it has to be killed with Ctrl-C) and it runs in a dedicated terminal pane. It sits as the earliest tier in the feedback ladder, catching failures the moment a file is saved — before staging, before commit.
+- **`check:tsc`, `check:oxlint`, `check:oxfmt`, `check:cspell`** are in pre-commit because they are fast (~0.2–0.5s each), fully offline, and naturally scope to staged files via the `LEFTHOOK_FILES` env var convention. They give instant feedback on what you typed.
+- **`test` (and the `tsc` it includes) is in pre-push** because it runs the whole test suite across the whole project. The pre-commit `LEFTHOOK_FILES` convention doesn't apply to the test runner, so pre-commit isn't the right home. Pre-push runs after all commits are made but before the push leaves the machine, catching regressions that span multiple commits.
+
+### Before pushing
+
+Run `npm run verify` — the one-shot correctness gate in the table above. Run `npm run maintain` only on a maintenance / update-deps branch.
+
+## Testing discipline (type-driven)
+
+For this library the types _are_ the feature — narrowing, `exhaustive()` returns, the `Matcher<T>` contract — so a runtime-only test loop would verify the wrong thing. New behavior follows **type-driven development** (in Edwin Brady's sense): _treat the type as the plan for a program, and use the compiler and type checker as your assistant, guiding you to a complete program that satisfies the type_ ([idris-lang.org](https://www.idris-lang.org/)). Here that plan is the `expectTypeOf` assertion, written first. The loop is **type → red → green → refactor**:
+
+1. **Type** — write the compile-time expectation first (`expectTypeOf(...).toEqualTypeOf<…>()`) and let `npm run check:tsc` fail on the _type_. The type error is the spec you want to hit before the runtime logic exists.
+2. **Red** — add the matching runtime assertion (`assert.*`) so `npm run test:unit` now fails on behavior.
+3. **Green** — implement in `src/*.ts` until both the type check and the test pass.
+4. **Refactor** — with the type system and the tests as the safety net, then `npm run verify` as the definition-of-done gate.
+
+This is why every test in the suite pairs an `expectTypeOf(...)` with an `assert.*` — keep them together. Type-first is also enforced structurally: `npm test` runs `check:tsc` before the test runner, so a wrong type can never be papered over by a passing assertion. Per [AGENTS.md § Never do](./AGENTS.md#never-do), reach green honestly — fix the types so both the type check and the runtime assertion pass, never suppress the ones you can't make pass.
+
+## Branching model
+
+**GitHub Flow (single-developer).** Every change — feature, fix, refactor — branches off `main` and is merged back via a local commit (no PR workflow on Gitea yet). Collaborative review via Gitea UI is not in place — Gitea is the lab; when something is tested and ready for production it will be promoted to GitHub.
+
+- **Base branch:** `main`
+- **Branch naming:** `feature/<desc>` / `fix/<desc>` / `chore/<desc>`
+- **Starting work:** `npm run create:branch -- <prefix>/<desc>`. It refuses, without changing anything, unless the working tree is clean (untracked files included), no merge/rebase/cherry-pick is in progress, `main` matches its upstream, and `npm run test` is green on `main` — so a later failure is always attributable to your edits. The prefix is still _your_ call, inferred from the task; the script validates it rather than guessing it.
+- **Merging:** `npm run create:finish` (on the branch). It asserts the same clean-tree / no-operation / current-`main` preconditions, fast-forwards a stale `main` (a true divergence is refused), merges the branch `--no-ff`, runs `npm run verify`, and deletes the branch only after the merge is green. The push is deliberately left to `create:release`, so the merge stays local and reviewable — read the diff yourself before finishing.
+- CI runs `npm run check` + `npm run test:ci` on every push to `main` — this is the authoritative gate. The one exception: a push headed by a release commit (`:rocket: Release x.y.z`) skips the full `build`/`maintain` jobs, because `create:release` pushes the tag for that exact commit right after and the tag run is the authoritative one (see `release-gate` in [.gitea/workflows/ci.yml](./.gitea/workflows/ci.yml)).
+- **Releases are NOT triggered by pushes.** Only the maintainer triggers a release (see [Publishing workflow](#publishing-workflow)).
+
+## CI runner image
+
+The `build` / `maintain` / `publish` jobs run in `gitea.e1nsnull.de/tmu/act-ci:<version>` ([docker/Dockerfile](./docker/Dockerfile)) — the runner's default act image with the Node distribution overlaid at the exact `/opt/hostedtoolcache` layout `actions/setup-node` probes before downloading, so no job pays the ~50 MB fetch. The image tag MUST equal the exact version pinned in `.node-version`; `release-gate` uses no Node and stays on the default image. The script is deliberately NOT an `npm run` script: building requires a docker daemon and registry credentials, so it belongs to no feedback tier — per [Script prefix convention](#script-prefix-convention), no existing prefix fits and that is the signal.
+
+Bumping Node is one coordinated change, committed as a unit:
+
+1. Edit `.node-version` to the new exact `x.y.z` — floats like `26` resolve to the latest patch at runtime and silently bust the baked entry; `scripts/runner-image.sh` refuses them.
+2. `docker login gitea.e1nsnull.de` (user + package/access token), then `./scripts/runner-image.sh --push` — it reads the version from `.node-version` and builds/pushes `<IMAGE_REPO>:<version>`.
+3. Repoint the three `container.image` tags in [.gitea/workflows/ci.yml](./.gitea/workflows/ci.yml) to the same version.
+
+Skipping step 2 fails CI at image pull; skipping step 3 silently reverts to the per-job download.
+
+Two invariants the image must satisfy for the probe to hit, both easy to break:
+
+- **The `x64.complete` marker.** `actions/tool-cache` accepts a cached tool only when `<version>/<arch>.complete` exists next to the directory (`tc.find()` checks it); a plausible-looking `node/<version>/x64/` alone is ignored and the download happens anyway. See the comment in [docker/Dockerfile](./docker/Dockerfile).
+- **Tag freshness.** The tag encodes only the Node version, so a Dockerfile change (like the marker above) produces _new content under an unchanged tag_. `act_runner` skips the pull when a tag of that name already exists locally (`forcePull=false` in the job log), so the runner must either force-pull (`force_pull` under `container:` in its `config.yaml`, if the installed version has it) or have the tag removed on the runner host (`docker rmi gitea.e1nsnull.de/tmu/act-ci:<version>`) after any image change. Symptom of getting this wrong: CI keeps running the previous image while the registry shows the new digest.
+
+## Publishing workflow
+
+Publishing is CI-only by policy. Local `npm publish` is not supported. The maintainer triggers releases from `main`:
+
+1. All intended changes are merged to `main` and passing CI.
+2. The maintainer runs `npm run create:release`. VS Code opens `CHANGELOG.md` to finalize the `[Unreleased]` notes; because pubv refuses a dirty tree, any edit is committed first (then folded into the release commit), and pubv's interactive prompt suggests a version from those notes — the maintainer confirms or edits it.
+3. `scripts/release.sh` creates a single release commit (graduated changelog + package.json bump, amended into one commit), tags it, and pushes everything to Gitea.
+4. CI fires on both pushes: the `publish` job runs on the tag (`build` + publish-tier checks + release page + `npm publish`), while the branch run's `release-gate` job recognizes the release commit and skips `build`/`maintain` — the tag verifies the identical SHA, so no work is duplicated. The job graph lives in [.gitea/workflows/ci.yml](./.gitea/workflows/ci.yml) — keep that file, not this list, as the source of truth. The publish-tier checks must pass before the artifact is published. The `publish` job also creates the Gitea release page from the matching Keep-a-Changelog section (`scripts/release-notes.sh`); it runs _before_ `npm publish` so a broken page fails CI without consuming a version, and `npm publish` stays the last step.

README.md

@@ -6,37 +6,64 @@ Pattern matching for TypeScript/ESM environments (F#-style, not regex).
 
 - **Build:** `npm run build`
 - **Test:** `npm run test`, `npm run test:ci`
+- **Watch:** `npm run watch`
 - **Checks:** `npm run check`, `npm run fix`
-- **Format/Fix:** `npm run fix:oxfmt`, `npm run fix:oxlint`
+- **Verify:** `npm run verify` — the definition of done
+- **Maintenance:** `npm run maintain` — advisory only
+- **Individual fixes:** `npm run fix:oxfmt`, `npm run fix:oxlint`
+
+What each tier runs, when it fires and what it costs:
+[CONTRIBUTING.md § Feedback tiers](./CONTRIBUTING.md#feedback-tiers). How the
+`prefix:` in a script name is chosen:
+[§ Script prefix convention](./CONTRIBUTING.md#script-prefix-convention).
 
 ### Tooling
 
 - **TypeScript 7** — type checker and build (`tsc`).
-- **node --test** + `--experimental-strip-types` — test runner (Node 22.6+, flag dropped on Node 24).
+- **node --test** + `--strip-types` — test runner.
 - **c8** — code coverage for `test:ci`.
-- **oxlint** — Rust-based linter.
+- **oxlint** — Rust-based linter, with type-aware rules powered by **oxlint-tsgolint** (typescript-go).
 - **oxfmt** — Rust-based formatter (Prettier-compatible). Formats JS/TS, JSON/JSONC, YAML, Markdown, MDX, and more; built-in `package.json` key sorting replaces `sort-package-json`.
 - **cspell** — spell checking.
-- **lefthook** — git pre-commit hooks.
+- **knip** — finds unused dependencies, exports, and files.
+- **check-outdated** — reports dependencies behind the registry; it exits non-zero whenever _any_ dependency is outdated.
+- **publint** — validates `package.json` for ESM publishing correctness.
+- **@arethetypeswrong/cli** (`attw`) — validates `.d.ts` declarations against multiple module-resolution scenarios.
+- **lefthook** — git hooks.
+- **@spences10/pi-lsp** — read-only LSP code intelligence for AI coding agents (project-local `.pi/settings.json`). Talks to this repo's TypeScript 7 via `tsc --lsp --stdio`.
+
+Each tool's configuration trade-off is recorded in [Tooling decisions](#tooling-decisions); when it runs is in [CONTRIBUTING.md § Feedback tiers](./CONTRIBUTING.md#feedback-tiers).
+
+### Tooling decisions
+
+The choice and configuration of each tool above is the result of deliberate trade-offs, not defaults. The non-obvious ones:
+
+- **`tsconfig.json` extends `@tsconfig/strictest` + `@tsconfig/node26`**; `tsconfig.build.json` extends it to add the emit-only options (`declaration`, `sourceMap`, `inlineSources`, `outDir`, `target: es2024`, `rewriteRelativeImportExtensions: true`) and to exclude test files. `inlineSources` embeds the original TypeScript in `dist/*.js.map`, so debuggers can map into `src/` without it being shipped; `declarationMap` is intentionally off because a `.d.ts.map` cannot embed source and would dangle. This separation lets the editor and CI type-check from one config while the build emits from the other.
+- **`npm run build` first runs a `prebuild` hook that empties `dist/`.** `tsc` does not prune orphaned emit output — dropping `declarationMap`, for example, left stale `*.d.ts.map` files behind — so the build must start from an empty `dist/` to be reproducible. `prebuild` removes only `dist`; the manual `clean` still resets `dist` + `coverage`, so a local coverage report survives a build.
+- **Source imports use `.ts` extensions** so `node --strip-types` resolves them at test time. `rewriteRelativeImportExtensions: true` in `tsconfig.build.json` rewrites them to `.js` in the emitted JavaScript; the emitted `.d.ts` keep the `.ts` specifier, which TypeScript >= 5.0 resolves (see [Requirements](#requirements)), so no post-processing step is needed.
+- **Type-aware oxlint is enabled declaratively** via `options.typeAware: true` in `.oxlintrc.json` (powered by `oxlint-tsgolint`). The script commands stay clean — no CLI flag — and type-aware mode is a property of the config, not the invocation.
+- **Source-level `oxlint-disable` directives** are used for known type-aware false positives (see `src/pattern.ts`, `src/match.ts`, `src/index.test.ts`). The disable lives next to the code it silences, not in `.oxlintrc.json`, so the trade-off is visible to anyone reading the source.
+- **`knip --include dependencies,exports,files`** intentionally omits the `types` category, which produces systematic false positives for libraries whose exported types are part of the public API. The targeted scope keeps the signal high without config-file boilerplate.
+- **`attw --profile esm-only`** is semantically correct: this package is intentionally ESM-only (no CommonJS shim), so CJS resolution scenarios are out of scope by design, not a bug.
+- **`check:tsc` runs first** in the `npm run check` chain so a type error short-circuits the rest (faster feedback than letting oxlint/oxfmt run and then failing on tsc at the end).
+- **The pre-commit hook sets the `LEFTHOOK_FILES` env var** to the staged-files list, and the affected scripts use `${LEFTHOOK_FILES:-<default>}` to default to the whole project when invoked manually. This keeps `package.json#scripts` as the single source of truth for the underlying commands — `lefthook.yml` only describes _what to run on which files_.
+- **`tslib` and `type-fest` are deliberately not used.** `tslib` is a runtime helper for old ES3/ES5 targets (the project targets ES2024); `type-fest` was never imported. knip caught both.
+- **`@spences10/pi-lsp` is pinned to `0.0.46` and is read-only by design.** The package inspects `node_modules/typescript`, sees major ≥ 7 with no `lib/tsserver.js` (true of the `typescript-go` / `tsgo` port), and spawns the repo's own `tsc --lsp --stdio` binary — no `typescript-language-server` dependency is required. Earlier releases (`≤ 0.0.10`) hard-wire to `typescript-language-server --stdio` and are TS6-only. The tool is _intermediate_ agent feedback (hover, references, definition, symbols, diagnostics); it has no rename / code-action / apply-edit surface, and never a correctness gate — `npm run check` / `verify` remain that. `.pi/settings.json` is the shared, committed declaration; `.pi/npm/` is a gitignored install cache that pi recreates automatically on a trusted startup (it runs `npm install` for any missing project package), so the cache is deliberately not tracked.
 
 ### Requirements
 
-- Node.js >= 22.6 (>= 24 recommended; `--experimental-strip-types` is unflagged on 24).
+- Node.js >= 26 (engines field; pinned via `.node-version`).
+- TypeScript >= 5.0 to consume the published declarations. The emitted `.d.ts` use `const` type parameters (TS 5.0) and keep their relative `.ts` specifiers; both resolve on TS >= 5.0 in `node10`/`node16`/`nodenext`/`bundler`.
 
 ## VSCode integration
 
-- Recommended extensions: see `.vscode/extensions.json` (oxc, cspell).
+- Recommended extensions: see `.vscode/extensions.json` (oxc, cspell, TypeScript native-preview, EditorConfig, todo-tasks).
-- TypeScript 7 is used via `typescript.tsdk` pointing at `node_modules/typescript/lib`.
+- TypeScript 7 is used via the `typescriptteam.native-preview` extension.
-- oxc extension provides oxlint squiggles and oxfmt format-on-save.
+- oxc extension provides oxlint squiggles and oxfmt format-on-save; `.vscode/settings.json` pins it per language so a user's local `[language]` formatter settings cannot override the project's choice.
 
-## Workflows
+## Contributing
 
-- Version updates via `npm version`.
+For maintainer and contributor docs — the script prefix convention, the feedback-tier system, the rules the tools don't enforce, and the publishing workflow — see [CONTRIBUTING.md](./CONTRIBUTING.md). AI coding agents: your entry point is [AGENTS.md](./AGENTS.md), which points back to CONTRIBUTING.md.
-- Publishing via GitHub Actions on tagged commits (see `.github/workflows/ci.yml`).
-
-## Contribution guidelines
 
 - Commit signing (GPG).
-- Set up commit message template: `npm run use:git-commit-message`.
-- See `commit-message-template`.
 - Type-only tests use `expect-type`'s `expectTypeOf(...)` inside `node --test` cases.

backlog.tasks

@@ -0,0 +1,56 @@
+Tasks
+
+Backlog and tracking for tiny-pattern-ts. Managed in vscode-todotasks format.
+
+---
+
+Setup:
+✔ Add gitea release page in CI @high @done
+☐ Manually verify the Gitea release page on a real tag push (needs main) @high
+☐ Split off template into separate package => pi --session 01a07dde-7050-7054-bb36-1606d7eb2bc3 @high
+
+v1.0:
+☐ API surface is stable and fully typed
+    ☐ Finalize public exports in `src/index.ts`
+    ☐ Document all exported types and functions
+    ☐ Add JSDoc for public APIs
+☐ Test coverage meets threshold
+    ☐ Achieve 100% branch coverage on `src/pattern.ts`
+    ☐ Achieve 100% branch coverage on `src/match.ts`
+    ☐ Achieve 100% branch coverage on `src/index.ts`
+
+Bugs:
+
+Enhancements:
+
+Documentation:
+☐ Add usage examples to README.md
+☐ Create `examples/` directory with runnable snippets
+☐ Add comparison section vs. other TS pattern-matching libs
+☐ Write migration guide for users coming from discriminated unions
+☐ Create backlog tasks for implementation
+
+Maintenance:
+☐ Serve CI coverage over a tiny self-hosted webserver (replace the zip artifact) @low
+    ✔ Add a minimal dir-listing webserver to the gitea docker setup (e.g. caddy `file_server browse` reusing the existing reverse proxy, or any single-binary static server, lipanski/docker-static-website) @done (9/13/2026, 9:02:37 PM)
+    ✔ drop the `actions/upload-artifact` coverage step in favour of the shared-dir layout @done (9/13/2026, 10:37:22 PM)
+    ☐ Explore serving coverage for non-tag pushes (e.g. `main/coverage`, PR previews) @low
+    ✔ Manually verify the coverage was created on a real tag push (needs main) @low @done (9/14/2026, 1:55:03 PM)
+    → design: no deploy step in CI; the webserver just exposes the shared directory (decided over Gitea Pages / Codecov — neither confirmed available/ wanted)
+☐ serve docs over self hosted server @low
+    ☐ Add a minimal dir-listing webserver to the gitea docker setup for serving docs (reuse existing reverse proxy)
+    ☐ CI writes docs to a shared volume keyed by project + tag (e.g. `/docs/tiny-pattern-ts/<tag>/`)
+    ☐ Browse to `…/docs/<repo>/<tag>/index.html` in the browser
+☐ serve landing page over self hosted server @low
+    ☐ Add a minimal dir-listing webserver to the gitea docker setup for serving landing page (reuse existing reverse proxy)
+    ☐ CI writes landing page to a shared volume keyed by project + tag (e.g. `/landing/tiny-pattern-ts/<tag>/`)
+    ☐ Browse to `…/tiny-pattern-ts/index.html` in the browser
+✔ Stop Gitea CI re-downloading Node on every job @done
+    ✔ Share the warm npm cache with the publish job @done
+    ✔ Bake Node into the CI job image (docker/Dockerfile, container.image in ci.yml) @done
+    ✔ Build/push gitea.e1nsnull.de/tmu/act-ci:26.8.2 and confirm setup-node skips the download @done
+    ✔ Write the `<version>/x64.complete` marker — actions/tool-cache ignores a bare directory, so the probe missed and the download continued @done
+    ✔ Log tool-cache state from the job container to find it (temporary, removed once understood) @done
+    ✔ Guard the invariant in CI (`Assert the baked tool cache is present`) @done
+☐ Enable force-pull for the runner so a changed act-ci image is never missed @low
+    → the tag encodes only the Node version, so a Dockerfile change yields new content under an unchanged tag; with `forcePull=false` the runner keeps the old image (see CONTRIBUTING § CI runner image)

cspell.json

@@ -2,8 +2,6 @@
     "version": "0.2",
     "language": "en",
     "words": [
-        "tslib",
-        "typefest",
         "lefthook",
         "oxlint",
         "oxfmt",
@@ -15,14 +13,36 @@
         "typescriptteam",
         "gitmoji",
         "dbaeumer",
-        "msvc"
+        "msvc",
+        "publint",
+        "attw",
+        "arethetypeswrong",
+        "knip",
+        "tsgolint",
+        "tsgo",
+        "tsserver",
+        "gitea",
+        "lipanski",
+        "pubv",
+        "knope",
+        "runwisp",
+        "glab",
+        "hostedtoolcache",
+        "nodebase",
+        "frontends",
+        "catthehacker",
+        "nsnull",
+        "dedup",
+        "dedupe",
+        "repoint",
+        "postversion",
+        "prebuild",
+        "Zilla",
+        "kacl",
+        "bestikk",
+        "silverwind",
+        "idris",
+        "todotasks"
     ],
-    "ignorePaths": [
+    "ignorePaths": ["dist", "node_modules", "coverage", "*.svg", ".gitignore"]
-        "dist",
-        "node_modules",
-        "public",
-        "coverage",
-        "*.svg",
-        ".gitignore"
-    ]
 }

docker/Dockerfile

@@ -0,0 +1,51 @@
+# CI job image for the Gitea act_runner: the runner's default job image with
+# Node pre-planted where actions/setup-node looks first.
+#
+# Why this layout: setup-node ignores `node` on PATH; its only fast path is a
+# probe of /opt/hostedtoolcache/node/<version>/<arch>. Without an entry there
+# it downloads the ~50 MB distribution on EVERY job (the runner's job
+# containers are ephemeral, so its tool cache never survives a job). The
+# official node images keep exactly the layout setup-node expects under
+# /usr/local, so this layer is a pure file overlay — no scripts, no env.
+#
+# Why not a host bind of /opt/hostedtoolcache: binds never self-prune. Docker
+# images are content-addressed: the base layers dedupe against the act image
+# the host already has, and `docker image prune` / re-pulls are the cleanup
+# story.
+#
+# NODE_VERSION must match `.node-version` exactly. setup-node resolves a float
+# like `26` to the latest known patch at runtime, so a bump silently busts the
+# baked entry; `.node-version` is pinned to x.y.z and scripts/runner-image.sh
+# guards the coupling. Rebuild + repoint `container.image` in
+# .gitea/workflows/ci.yml on every bump.
+#
+# The extra `nodebase` stage is load-bearing: `COPY --from=` resolves its value
+# as a *stage name* at parse time, before build args exist, so
+# `COPY --from=node:${NODE_VERSION}` collapses to the invalid `node:` on
+# frontends that do not expand args there. ARGs declared before the first FROM
+# *are* expanded in FROM, so routing through a named stage works everywhere.
+
+# Global scope: only visible to FROM lines, but that is exactly where we need it.
+ARG NODE_VERSION=26.8.2
+FROM node:${NODE_VERSION} AS nodebase
+
+FROM catthehacker/ubuntu:act-latest
+
+# ARGs do not cross stage boundaries; redeclare (with the same default, so a
+# bare `docker build -f docker/Dockerfile .` still works) for the paths below.
+# Keep this default in sync with the global one above.
+ARG NODE_VERSION=26.8.2
+
+# node image: bin/ + lib/ under /usr/local → tool cache: bin/ + lib/ under <ver>/x64.
+COPY --from=nodebase /usr/local /opt/hostedtoolcache/node/${NODE_VERSION}/x64
+
+# actions/tool-cache only accepts a cached tool when the sibling marker file
+# "<version>/<arch>.complete" exists — tc.find() checks it and falls back to
+# downloading otherwise, however complete the directory is. The marker is what
+# tc.cacheDir() writes after *it* installs a tool, so a pre-baked entry has to
+# reproduce it explicitly.
+RUN touch "/opt/hostedtoolcache/node/${NODE_VERSION}/x64.complete"
+
+# Fail the build (not CI) if the overlay or the version arg were wrong.
+# Shell form on purpose: exec form (`RUN [...]`) does not expand ARG values.
+RUN "/opt/hostedtoolcache/node/${NODE_VERSION}/x64/bin/node" --version

knip.json

@@ -0,0 +1,5 @@
+{
+    "$schema": "./node_modules/knip/schema.json",
+    "entry": ["scripts/*.ts"],
+    "ignoreDependencies": ["@runwisp/pubv"]
+}

lefthook.yml

@@ -5,11 +5,17 @@ pre-commit:
     commands:
         oxlint:
             glob: "*.{ts,tsx,js,jsx,mjs,cjs}"
-            run: sh -c 'LEFTHOOK_FILES="$0" npm run check:oxlint' {staged_files}
+            run: sh -c 'LEFTHOOK_FILES="$*" npm run check:oxlint' sh {staged_files}
         oxfmt:
             glob: "*.{ts,tsx,js,jsx,mjs,cjs,json,jsonc,yaml,yml,md,mdx}"
-            run: sh -c 'LEFTHOOK_FILES="$0" npm run check:oxfmt' {staged_files}
+            run: sh -c 'LEFTHOOK_FILES="$*" npm run check:oxfmt' sh {staged_files}
         cspell:
-            run: sh -c 'LEFTHOOK_FILES="$0" npm run check:cspell' {staged_files}
+            run: sh -c 'LEFTHOOK_FILES="$*" npm run check:cspell' sh {staged_files}
         typecheck:
             run: npm run check:tsc
+
+pre-push:
+    parallel: false
+    commands:
+        test:
+            run: npm test

package.json

@@ -1,6 +1,6 @@
 {
     "name": "tiny-pattern-ts",
-    "version": "0.0.0",
+    "version": "0.1.4",
     "description": "Pattern matching for TypeScript/ESM environments (F#-style, not regex)",
     "keywords": [
         "adt",
@@ -10,20 +10,23 @@
         "pattern-matching",
         "typescript"
     ],
+    "homepage": "https://gitea.e1nsnull.de/tmu/tiny-pattern-ts#readme",
+    "bugs": {
+        "url": "https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/issues"
+    },
     "license": "MIT",
     "repository": {
         "type": "git",
-        "url": "https://github.com/tmueller/tiny-pattern-ts.git"
+        "url": "git+https://gitea.e1nsnull.de/tmu/tiny-pattern-ts.git"
     },
     "files": [
         "dist",
+        "CHANGELOG.md",
         "README.md",
         "LICENSE"
     ],
     "type": "module",
     "sideEffects": false,
-    "main": "./dist/index.js",
-    "types": "./dist/index.d.ts",
     "exports": {
         ".": {
             "types": "./dist/index.d.ts",
@@ -35,50 +38,55 @@
     },
     "scripts": {
         "build": "tsc -p tsconfig.build.json",
-        "check": "npm run check:oxlint && npm run check:oxfmt && npm run check:tsc && npm run check:cspell && npm run check:outdated",
+        "prebuild": "rm -rf dist",
+        "check": "npm run check:tsc && npm run check:oxlint && npm run check:oxfmt && npm run check:cspell",
         "check:cspell": "cspell lint ${LEFTHOOK_FILES:-.}",
-        "check:outdated": "check-outdated --ignore-pre-releases --ignore-packages @oxfmt/binding-darwin-arm64,@oxfmt/binding-darwin-x64,@oxfmt/binding-linux-arm64-gnu,@oxfmt/binding-linux-arm64-musl,@oxfmt/binding-linux-x64-gnu,@oxfmt/binding-linux-x64-musl,@oxfmt/binding-win32-x64-msvc,@oxlint/binding-darwin-arm64,@oxlint/binding-darwin-x64,@oxlint/binding-linux-arm64-gnu,@oxlint/binding-linux-arm64-musl,@oxlint/binding-linux-x64-gnu,@oxlint/binding-linux-x64-musl,@oxlint/binding-win32-x64-msvc",
         "check:oxfmt": "oxfmt --check ${LEFTHOOK_FILES:-.}",
-        "check:oxlint": "oxlint ${LEFTHOOK_FILES:-src}",
+        "check:oxlint": "oxlint ${LEFTHOOK_FILES:-src scripts}",
         "check:tsc": "tsc",
-        "clean": "node -e \"fs.rmSync('dist', { recursive: true, force: true })\"",
+        "clean": "rm -rf dist coverage",
+        "fix": "npm run fix:oxlint && npm run fix:oxfmt",
         "fix:oxfmt": "oxfmt ${LEFTHOOK_FILES:-.}",
-        "fix:oxlint": "oxlint --fix src",
+        "fix:oxlint": "oxlint --fix src scripts",
-        "test": "npm run check:tsc && node --test --strip-types src/",
+        "create:branch": "./scripts/branch.sh",
-        "test:ci": "c8 --reporter=text --reporter=lcov --reporter=html node --test --strip-types src/",
+        "create:finish": "./scripts/finish.sh",
-        "test:unit": "node --test --strip-types src/",
+        "create:release": "./scripts/release.sh",
-        "use:git-commit-message": "cp commit-message-template .git/COMMIT_EDITMSG || true"
+        "maintain": "npm run maintain:knip; npm run maintain:outdated",
+        "maintain:knip": "knip --include dependencies,exports,files",
+        "maintain:outdated": "check-outdated --ignore-pre-releases",
+        "test": "npm run check:tsc && node --test --strip-types \"src/**/*.test.ts\"",
+        "test:ci": "c8 --reporter=text --reporter=lcov --reporter=html node --test --strip-types \"src/**/*.test.ts\"",
+        "test:unit": "node --test --strip-types \"src/**/*.test.ts\"",
+        "verify": "npm run check && npm run test:unit",
+        "watch": "npm run watch:test",
+        "watch:test": "node --test --watch --strip-types \"src/**/*.test.ts\"",
+        "publish:attw": "attw . --pack --profile esm-only",
+        "publish:publint": "publint",
+        "setup": "npm run setup:git-commit-message",
+        "setup:git-commit-message": "git config commit.template commit-message-template"
     },
     "devDependencies": {
+        "@arethetypeswrong/cli": "^0.18.5",
+        "@runwisp/pubv": "^1.5.1",
+        "@tsconfig/node26": "^26.0.1",
+        "@tsconfig/strictest": "^2.0.8",
         "@types/node": "^26.4.1",
         "c8": "^12.0.0",
         "check-outdated": "^3.0.0",
-        "cspell": "^10.2.1",
+        "cspell": "^10.2.2",
         "expect-type": "1.4.0",
+        "knip": "^6.34.0",
         "lefthook": "^2.1.12",
-        "oxfmt": "^0.66.0",
+        "oxfmt": "^0.68.0",
-        "oxlint": "^1.81.0",
+        "oxlint": "^1.83.0",
-        "tslib": "^2.8.1",
+        "oxlint-tsgolint": "^7.0.2001",
-        "type-fest": "^5.9.0",
+        "publint": "^0.3.24",
         "typescript": "^7.0.2"
     },
-    "optionalDependencies": {
-        "@oxfmt/binding-darwin-arm64": "^0.66.0",
-        "@oxfmt/binding-darwin-x64": "^0.66.0",
-        "@oxfmt/binding-linux-arm64-gnu": "^0.66.0",
-        "@oxfmt/binding-linux-arm64-musl": "^0.66.0",
-        "@oxfmt/binding-linux-x64-gnu": "^0.66.0",
-        "@oxfmt/binding-linux-x64-musl": "^0.66.0",
-        "@oxfmt/binding-win32-x64-msvc": "^0.66.0",
-        "@oxlint/binding-darwin-arm64": "^1.81.0",
-        "@oxlint/binding-darwin-x64": "^1.81.0",
-        "@oxlint/binding-linux-arm64-gnu": "^1.81.0",
-        "@oxlint/binding-linux-arm64-musl": "^1.81.0",
-        "@oxlint/binding-linux-x64-gnu": "^1.81.0",
-        "@oxlint/binding-linux-x64-musl": "^1.81.0",
-        "@oxlint/binding-win32-x64-msvc": "^1.81.0"
-    },
     "engines": {
         "node": ">=26"
+    },
+    "allowScripts": {
+        "lefthook@2.1.14": true
     }
 }

project-specs.md

@@ -1,463 +0,0 @@
-# Project Specifications for TypeScript NPM Module
-
-- name of package: tiny-pattern-ts
-
-## 0. References
-
-typescript-lib-starter-tiny => https://github.com/tmueller/typescript-lib-starter-tiny/
-
-## 1. Development Environment
-
-- **TypeScript**: Use strictest practical rules. Inline in `tsconfig.json` (not
-  via `@tsconfig/strictest`). The rule set is: `strict`, `noImplicitAny`,
-  `noImplicitThis`, `alwaysStrict`, `strictNullChecks`, `strictFunctionTypes`,
-  `strictBindCallApply`, `strictPropertyInitialization`, `noImplicitReturns`,
-  `noFallthroughCasesInSwitch`, `noUncheckedIndexedAccess`, `noImplicitOverride`,
-  `noUnusedLocals`, `noUnusedParameters`, `forceConsistentCasingInFileNames`,
-  `isolatedModules`, `verbatimModuleSyntax`.
-- **EditorConfig**: Use `.editorconfig` from typescript-lib-starter-tiny.
-- **oxfmt**: Rust-based formatter, Prettier-compatible. Replaces Prettier.
-  Config in `.oxfmtrc.json` (same shape as `.prettierrc`).
-- **oxlint**: Rust-based linter. Replaces ESLint. Config in `.oxlintrc.json`
-  with `typescript`, `unicorn`, `oxc`, `import` plugins. Categories enabled
-  as errors: `correctness`, `suspicious`, `restriction`. As warnings: `perf`,
-  `style`. `nursery` is off.
-- **oxlint rules disabled by design** (in `.oxlintrc.json`):
-    - `eslint/no-undefined` — we use `undefined` as the no-match sentinel.
-    - `eslint/sort-keys` — handler/case order is semantic, not alphabetical.
-    - `eslint/id-length` — `T`, `R`, `U`, `V` are standard TS generics.
-    - `import/no-named-export` — false positive on library entry re-exports.
-      For `*.test.ts` files additionally: `no-unused-expressions` (for
-      `expectTypeOf(...)` calls), `no-empty-file` (we have a single import
-      per test file in some cases), `import/no-nodejs-modules` (we use
-      `node:test`/`node:assert`/`node:fs` intentionally), `eslint/no-magic-numbers`
-      (literals in tests are fine).
-- **Import sorting**: built into oxfmt (no separate plugin).
-- **cspell**: Basic spelling configuration. Words dictionary in `cspell.json`
-  covers tooling names (`oxlint`, `oxfmt`, `oxc`, `nodenext`,
-  `oxfmtrc`, `oxlintrc`, `EDITMSG`, `typescriptteam`,
-  `gitmoji`, `dbaeumer`, `msvc`) and a few library names (`tslib`,
-  `typefest`, `lefthook`).
-- **Lefthook**: Pre-commit checks (run in parallel, lefthook v2 schema).
-  Single source of truth for the underlying commands is in
-  `package.json#scripts`; the lefthook config only describes _what to
-  run on which files_. Hooks that should run on staged files
-  (`oxlint`, `oxfmt`, `cspell`) set the `LEFTHOOK_FILES` env var to
-  the staged-files list via a `sh -c` wrapper, and the npm script
-  uses `${LEFTHOOK_FILES:-<default>}` to default to the full project
-  when invoked manually:
-    - `pre-commit.commands.oxlint` (glob `*.{ts,tsx,js,jsx,mjs,cjs}`):
-      `sh -c 'LEFTHOOK_FILES="$0" npm run check:oxlint' {staged_files}`
-    - `pre-commit.commands.oxfmt` (glob `*.{ts,tsx,js,jsx,mjs,cjs}`):
-      `sh -c 'LEFTHOOK_FILES="$0" npm run check:oxfmt' {staged_files}`
-    - `pre-commit.commands.cspell`:
-      `sh -c 'LEFTHOOK_FILES="$0" npm run check:cspell' {staged_files}`
-    - `pre-commit.commands.typecheck`:
-      `npm run check:tsc` (no file args needed)
-      `outdated` is intentionally NOT a pre-commit check (it can flag
-      upstream patch releases that aren't actionable locally); it runs in
-      CI and via the explicit `lefthook run outdated` command.
-
-- **Additional Dev Dependencies**:
-    - lefthook
-    - check-outdated
-    - c8 (coverage for `node --test`)
-    - expect-type (type-level assertions in tests)
-    - oxfmt, oxlint (with their native bindings as `optionalDependencies`
-      so the correct binding is selected per platform automatically)
-    - typescript (TS 7)
-    - @types/node
-    - tslib (available for future runtime helper imports)
-    - type-fest (utility types)
-
-## 2. Build & Test
-
-- **Build Tool**: TypeScript 7 (`tsc`) — no bundler, no Vite. The build
-  is a plain `tsc -p tsconfig.build.json` invocation that emits ESM
-  JavaScript and `.d.ts` declarations to `dist/`. ESM only, no CJS.
-- **Testing**: Node's built-in `node --test` with `--strip-types` (Node
-  22.6+, unflagged on Node 24/26). Test files are co-located with
-  source as `*.test.ts`. No Vitest.
-- **TypeScript Build Output**: `dist` directory (set in
-  `tsconfig.build.json#outDir`; `tsconfig.json` keeps `outDir` for
-  editor tooling but excludes tests from emission via
-  `tsconfig.build.json#exclude`).
-- **Import extensions**: Source uses `.ts` extensions in imports
-  (e.g. `from "./match.ts"`) so `node --strip-types` resolves them
-  at test time. TypeScript's `rewriteRelativeImportExtensions` (in
-  `tsconfig.build.json`) rewrites these to `.js` in the emitted
-  `dist/*` output, so consumers see conventional ESM imports.
-- **TypeScript Compiler Options Notes**:
-    - `allowImportingTsExtensions: true` is set in the root
-      `tsconfig.json` (works because the root config has `noEmit: true`).
-    - `rewriteRelativeImportExtensions: true` is set in
-      `tsconfig.build.json` to rewrite `.ts` to `.js` on emit.
-    - `module: nodenext`, `moduleResolution: nodenext` for ESM-first
-      Node packages.
-    - `verbatimModuleSyntax: true` enforces explicit `import type`.
-    - `target: es2024`, `lib: ["es2024"]` (Node 26 supports all ES2024
-      features natively).
-- **Additional Dev Dependencies** (for types and tests):
-    - `tslib` — available for runtime helper imports; not currently
-      used by source (kept for future use per the original spec).
-    - `type-fest` — utility types; not currently used by source
-      (kept for future use per the original spec).
-    - `@types/node` — types for `node:test`, `node:assert`, `node:fs`.
-- **Node Version**: `>=26` (engines field). Pinned via `.node-version`
-  for fnm/nvm/volta/mise auto-switching and CI
-  (`actions/setup-node@v4` with `node-version-file: .node-version`).
-
-## 3. Project Structure & Files
-
-- **.gitignore**: Ignore `dist`, `node_modules`, `coverage`, and other
-  common files.
-- **.node-version**: Single line containing the Node major version
-  (currently `26`). Used by version managers and CI.
-- **.npmignore**: Ignore `node_modules/`, `coverage/`, `*.log`,
-  `*.tsbuildinfo`, `src/`, `.vscode/`, `.editorconfig`,
-  `.oxfmtrc.json`, `.oxlintrc.json`, `.node-version`, `cspell.json`,
-  `lefthook.yml`, `commit-message-template`.
-  (Note: `dist/` is included via `package.json#files`, not by absence
-  from `.npmignore`.)
-- **.oxfmtrc.json**: oxfmt configuration (Prettier-shaped).
-- **.oxlintrc.json**: oxlint configuration.
-- **.oxlintrc.json + .oxfmtrc.json** replace the old `.eslintrc.cjs`
-  and `.prettierrc`.
-- **LICENSE**: MIT.
-- **README.md**: Scaffolded.
-- **commit-message-template**: From typescript-lib-starter-tiny.
-- **Target Environments**: Node 26 LTS only (no browser target; this
-  is a pure Node library, no DOM, no DOM lib in tsconfig).
-- **No React, No CJS, ESM only**.
-
-## 4. Automation & Quality
-
-- **Version Automation**: Use standard `npm version` for versioning.
-- **Unused Dependency Check**: Use `check-outdated` (devDep, runs in CI
-  and via the explicit `lefthook run outdated` command).
-- **No commitlint, no conventional commits**. Commits use gitmoji
-  prefixes (e.g. `:sparkles:`, `:wrench:`, `:bug:`, `:fire:`,
-  `:white_check_mark:`, `:tada:`) for at-a-glance categorization.
-
-## 5. Scripts
-
-### SETUP
-
-- `use:git-commit-message`: Set up commit message template (if needed).
-
-### TEST
-
-- `test`: Run `tsc --noEmit` then `node --test --strip-types src/`.
-- `test:unit`: Run unit tests with `node --test --strip-types src/`
-  (no preceding typecheck).
-- `test:ci`: Run tests in CI mode with c8 coverage (text + lcov + html
-  reporters), uploading `coverage/` as an artifact.
-
-### BUILD
-
-- `build`: Build the project using `tsc -p tsconfig.build.json`
-  (emits `dist/*.js` + `dist/*.d.ts` + sourcemaps, with `.ts`
-  imports rewritten to `.js`).
-
-### CLEAN
-
-- `clean`: Remove `dist/` via `node -e "fs.rmSync('dist', {recursive:true, force:true})"`.
-  (Replaces `clean:build` from the original spec — same effect,
-  no `rimraf` dep needed.)
-
-### CHECK
-
-- `check`: Run all checks in order — `check:oxlint`, `check:oxfmt`,
-  `check:tsc`, `check:cspell`, `check:outdated`.
-- `check:oxlint`: `oxlint ${LEFTHOOK_FILES:-src}` — lints `src/`
-  by default; when invoked from the lefthook pre-commit hook with
-  `LEFTHOOK_FILES` set to the staged-files list, lints only those
-  files. This is the single source of truth for the oxlint command
-  and is shared between the manual `npm run check` and the pre-commit
-  hook. oxlint only understands JS/TS-family languages, so config
-  files (JSON/YAML/Markdown) are intentionally outside its scope;
-  they are checked only by oxfmt.
-- `check:oxfmt`: `oxfmt --check ${LEFTHOOK_FILES:-.}` — formats the
-  whole project (`.`) by default, including JS/TS, JSON/JSONC,
-  YAML, Markdown, MDX and other supported file types. From lefthook
-  pre-commit, the `LEFTHOOK_FILES` env var scopes to the staged
-  files matching `*.{ts,tsx,js,jsx,mjs,cjs,json,jsonc,yaml,yml,md,mdx}`.
-  Built-in `sortPackageJson: true` keeps `package.json` keys
-  alphabetized (replaces the former `sort-package-json` tool).
-  Built-in import sorting (enabled via `sortImports: true`) replaces
-  any external import-sort plugin.
-- `check:tsc`: `tsc --noEmit`.
-- `check:cspell`: `cspell lint ${LEFTHOOK_FILES:-.}` — walks the
-  project root by default; from lefthook, only the staged files.
-- `check:outdated`: `check-outdated --ignore-pre-releases --ignore-packages @oxfmt/binding-*,@oxlint/binding-*`. The oxc native bindings are declared as `optionalDependencies` so the correct one is selected per platform automatically; the `*`-platform bindings show as "not installed" on the current platform and are explicitly ignored here.
-
-### FIX
-
-- `fix:oxlint`: `oxlint --fix src`.
-- `fix:oxfmt`: `oxfmt ${LEFTHOOK_FILES:-.}` — same scoping as
-  `check:oxfmt` (whole project by default, staged files from
-  lefthook). Writes changes in place.
-  (There is no `fix` aggregator in the scripts; run the `fix:*` scripts
-  individually.)
-
-### HOOKS
-
-- Lefthook runs the relevant `check:*` scripts on staged files in
-  parallel for pre-commit. See `lefthook.yml`.
-
----
-
-## 6. Repository & CI/CD
-
-- **Repository**: Hosted on GitHub.
-- **Build Pipeline**: GitHub Actions (`.github/workflows/ci.yml`).
-    - `build` job on push and pull_request to `main` and on
-      `workflow_dispatch`. Steps: `actions/checkout@v4`,
-      `actions/setup-node@v4` (with `node-version-file: .node-version`,
-      `cache: npm`), `npm ci`, `npm run build`, `npm run check`,
-      `npm run test:ci`, then upload `coverage/` as an artifact.
-    - `publish` job: only on `refs/tags/*`, depends on `build`. Steps:
-      `actions/checkout@v4`, `actions/setup-node@v4` (with
-      `node-version-file: .node-version` and `registry-url`),
-      `npm ci`, `npm run build`, `npm publish --access public`
-      with `NODE_AUTH_TOKEN` from secrets.
-
-## 7. Versioning & Publishing
-
-- **Version Update**: Use `npm version` to bump version after merging
-  to main and before publishing.
-- **Publishing to npm**: Only publish from CI on tagged commits.
-- **Recommended Workflow**:
-    1. Develop and merge PRs to main
-    2. Run all checks via CI
-    3. Bump version with `npm version <patch|minor|major>`
-    4. Push tag to GitHub
-    5. CI builds and publishes to npm on tag
-
-## 8. NPM Keywords
-
-- pattern-matching
-- pattern
-- match
-- algebraic-data-types
-- adt
-- typescript
-
-> The library is for pattern matching (not regex), similar to F#'s
-> pattern matching, for TypeScript/ESM environments.
-
-## 9. Code Coverage
-
-- **Tool**: c8 (V8-native coverage, no instrumentation step).
-- **Configuration**: c8 has no project config; the report shape is
-  pinned in the `test:ci` script:
-
-```jsonc
-"test:ci": "c8 --reporter=text --reporter=lcov --reporter=html node --test --strip-types src/"
-```
-
-- **Reporters**: text summary, HTML, and lcov (matching the original
-  spec).
-- **CI**: `coverage/` is uploaded as a workflow artifact via
-  `actions/upload-artifact@v4` (see `.github/workflows/ci.yml`).
-- **Optional**: Coverage thresholds can be added in c8 config when the
-  library surface stabilizes.
-
-## 10. Source Structure & Tree Shaking
-
-- **Source Directory**: All source code resides in `src/` and is
-  exported via `src/index.ts`.
-- **Configuration**:
-    - `sideEffects: false` in `package.json` (set).
-    - ESM-only exports; `package.json#exports` field maps `.` to
-      `{"types": "./dist/index.d.ts", "import": "./dist/index.js"}`.
-    - Avoid top-level side effects in modules.
-    - Explicit re-exports in `index.ts` for best results.
-- Source structure (current):
-    - `src/index.ts` — public barrel.
-    - `src/match.ts` — `match(value).with(...).exhaustive() / .otherwise(...)` builder.
-    - `src/pattern.ts` — `P.literal`, `P.type`, `P.when`, `P.any`, `P.shape` constructors and the `Matcher<T>` interface.
-    - `src/index.test.ts` — runtime + type-level tests using `node --test` + `expect-type`.
-- The human will implement the source code.
-
-## 11. Included Templates from typescript-lib-starter-tiny
-
-### .editorconfig
-
-```plaintext
-# Editor configuration, see http://editorconfig.org
-root = true
-
-[*]
-charset = utf-8
-indent_style = space
-indent_size = 4
-insert_final_newline = true
-max_line_length = 80
-trim_trailing_whitespace = true
-quote_type = double
-
-[*.md]
-max_line_length = 0
-trim_trailing_whitespace = false
-
-[COMMIT_EDITMSG]
-max_line_length = 0
-```
-
-### commit-message-template
-
-```plaintext
-# If applied, this commit will... (Max 50 char)
-
-
-# Explain why this change is being made (Max 72 Char) [WHAT and WHY vs HOW]
-
-
-# Provide links or keys to any relevant tickets, articles or other resources
-Resolves #...
-
-# --- COMMIT END ---
-# Remember to
-#    Use the imperative mood in the subject line
-#    Capitalize the subject line
-#    Do not end the subject line with a period
-#    Separate subject from body with a blank line
-#    Use the body to explain what and why vs. how
-#    Can use multiple lines with "-" for bullet points in body
-```
-
-### README.md Structure (scaffolded)
-
-- Project title and description
-- Development
-    - Build: `npm run build`
-    - Test: `npm run test`, `npm run test:ci`
-    - Checks: `npm run check`, `npm run fix:oxfmt`, `npm run fix:oxlint`
-- Tooling section listing TypeScript 7, node --test, c8, oxlint, oxfmt,
-  cspell, lefthook
-- Requirements: Node.js >= 26
-- VSCode integration
-    - Debugging
-    - Running tests
-    - oxc.oxc-vscode provides oxlint and oxfmt in-editor
-- Workflows
-    - Version updates via `npm version`
-    - Publishing via GitHub Actions on tagged commits
-- Contribution guidelines
-    - Commit signing (GPG)
-    - How to set up commit message template (`npm run use:git-commit-message`)
-    - Reference to commit-message-template
-    - Type-level tests use `expect-type`'s `expectTypeOf(...)` inside
-      `node --test` cases
-
-## 12. Project Initialization & Commit Strategy
-
-- Start by initializing git with a `main` branch.
-- Initial commit: empty README + LICENSE.
-- Create a feature branch: `feature/setup`.
-- For each technology or tool added (and its configuration), create a
-  separate commit:
-    - Prepend each commit message with a matching gitmoji (e.g.
-      `:sparkles:` for new features, `:wrench:` for config,
-      `:bug:` for fixes, `:fire:` for removals,
-      `:white_check_mark:` for tests, `:tada:` for initial commit).
-    - Example commit messages used in this project:
-        - `:tada: Initial commit with empty README`
-        - `:wrench: Track .vscode/settings.json for workspace settings`
-        - `:construction_worker: Added GitHub Actions workflow for CI/CD`
-        - `:test_tube: Added Vitest configuration with coverage` (later removed)
-        - `:sparkles: Scaffolded src/index.ts entry point for library code`
-        - `:wrench: Replace Vite/Vitest with TypeScript 7 and node --test`
-        - `:wrench: Replace ESLint and Prettier with oxlint and oxfmt`
-        - `:fire: Remove Vite scaffold leftovers`
-        - `:sparkles: Add initial pattern-matching API`
-        - `:white_check_mark: Add expect-type for type-level tests`
-        - `:wrench: Declare Node 26 as the supported runtime`
-        - `:bug: Use .ts extensions in imports for node --strip-types`
-        - `:wrench: Remove Prettier from editor formatter config`
-- Each commit should include only the relevant files and configuration
-  for that technology/tool. This approach ensures a clean, understandable
-  project history and makes it easy to review or revert specific setup
-  steps.
-
-## 13. Changelog Automation
-
-- Not currently configured. The intended workflow, when adopted, is a
-  changesets-driven release process: feature PRs include a changeset,
-  which gets consumed by a release workflow, producing a `CHANGELOG.md`
-  and a version bump on merge to main.
-- The changelog should be updated as part of the release process.
-
-## 14. Publishing Public
-
-- npm publishing is configured to be public by default.
-- `publishConfig: { "access": "public" }` is set in `package.json`.
-- The CI/CD pipeline publishes with `--access public` on tagged commits.
-
-## 15. VSCode Integration
-
-- `.vscode/settings.json` uses `oxc.oxc-vscode` as the default
-  formatter for `[typescript]`, `[javascript]`, `[json]`, `[jsonc]`,
-  `[markdown]`, `[mdx]`, and `[yaml]` (oxfmt under the hood).
-
-```json
-{
-    "typescript.tsdk": "node_modules/typescript/lib",
-    "js/ts.tsdk.path": "node_modules/typescript/lib",
-    "[typescript]": {
-        "editor.defaultFormatter": "oxc.oxc-vscode",
-        "editor.formatOnSave": true
-    },
-    "[javascript]": {
-        "editor.defaultFormatter": "oxc.oxc-vscode",
-        "editor.formatOnSave": true
-    },
-    "[json]": {
-        "editor.defaultFormatter": "oxc.oxc-vscode",
-        "editor.formatOnSave": true
-    },
-    "[jsonc]": {
-        "editor.defaultFormatter": "oxc.oxc-vscode",
-        "editor.formatOnSave": true
-    },
-    "[markdown]": {
-        "editor.defaultFormatter": "oxc.oxc-vscode",
-        "editor.formatOnSave": true
-    },
-    "[mdx]": {
-        "editor.defaultFormatter": "oxc.oxc-vscode",
-        "editor.formatOnSave": true
-    },
-    "[yaml]": {
-        "editor.defaultFormatter": "oxc.oxc-vscode",
-        "editor.formatOnSave": true
-    },
-    "editor.defaultFormatter": "oxc.oxc-vscode",
-    "editor.formatOnSave": true
-}
-```
-
-- `.vscode/extensions.json` recommends:
-    - `oxc.oxc-vscode` (oxlint + oxfmt, replaces eslint/prettier/vitest)
-    - `streetsidesoftware.code-spell-checker` (cspell)
-    - `typescriptteam.native-preview` (TypeScript 7 nightly support;
-      replaces the older `ms-vscode.vscode-typescript-next`)
-
-```json
-{
-    "recommendations": [
-        "oxc.oxc-vscode",
-        "streetsidesoftware.code-spell-checker",
-        "typescriptteam.native-preview"
-    ]
-}
-```
-
-- `.vscode/tasks.json` is not currently provided; common tasks
-  (build, test, lint, typecheck, format, spell, check:outdated) are
-  run via the npm scripts in `package.json` from the integrated
-  terminal.
-- VSCode uses the workspace TypeScript version via
-  `typescript.tsdk` (and the explicit `js/ts.tsdk.path`), with
-  `oxc.oxc-vscode` for formatting and linting.

scripts/branch.sh

@@ -0,0 +1,152 @@
+#!/bin/sh
+
+set -eu
+
+# Branch front-door. Run as `npm run create:branch -- <prefix>/<desc>`.
+#
+# How we got here (short): the branching model says every change starts from a
+# clean, current `main`, and the type-driven loop only produces trustworthy
+# results if the baseline was green *before* the first edit. Both facts were
+# prose. Prose rots silently — a rule nobody checks is a suggestion — so the
+# precondition became this script: it asserts, then branches, and the branch
+# only appears if the assertions passed. Cheap checks run first, `npm run test`
+# runs last: the expensive gate is not paid on a tree that was never eligible.
+#
+# Rejected for the prefix name: `run:` / `perform:` (both mean only "do the
+# thing named after them", so every script in the repo would fit under them and
+# the taxonomy collapses); `git:` (names the tool, not the lifecycle moment, and
+# advertises passthrough aliases); `start:` (describes this half, not the
+# release); `cut:` (idiomatic for both, but it needs VCS slang to decode, and a
+# signpost that has to be explained is not one); `flow:` (overloaded in a library
+# about type-level matching); and the existing families — `check:*` is read-only
+# and aggregated by `check`, so CI would run a command that mutates repo state;
+# `fix:*`'s review surface is a file diff, not a branch; `maintain:*` is advisory
+# and explicitly never a gate.
+#
+# `create:` was kept because both members really do create something: a branch,
+# a release. It was added to both prefix lists in CONTRIBUTING.md in the same
+# commit as its first members, because a prefix missing from those lists is
+# invisible — which was the `use:` mistake this repo carried in backlog.tasks (since retired into `setup:`).
+# There is deliberately no bare `create` aggregator: "run all the workflows"
+# describes nothing anyone wants, and `publish:*` already sets the precedent for
+# a prefix without one.
+#
+# Also rejected here: reusing `pubv`'s preflight (release-shaped, third-party,
+# and it would make branch start pay a build + pack it has no use for). The
+# merge half was originally rejected too ("review the diff yourself" is
+# judgment), but it now has its own front door — `create:finish` — which owns
+# the merge-side preconditions and the post-merge `verify`, so the start half
+# does not have to carry that burden.
+#
+# Every refusal is non-mutating except the baseline test, which runs on `main`
+# after we switch there — so a red `main` restores the branch you started on
+# rather than stranding you on it.
+
+BASE="main"
+PREFIXES="feature fix chore"
+NAME="${1:-}"
+
+if [ -z "${NAME}" ]; then
+    echo "usage: npm run create:branch -- <prefix>/<desc>    (prefix: ${PREFIXES})" >&2
+    exit 2
+fi
+
+git rev-parse --is-inside-work-tree >/dev/null 2>&1 || {
+    echo "error: not inside a git work tree." >&2
+    exit 1
+}
+
+MATCH=0
+for p in ${PREFIXES}; do
+    case "${NAME}" in
+    "${p}/"*) MATCH=1 ;;
+    esac
+done
+if [ "${MATCH}" -ne 1 ]; then
+    echo "error: '${NAME}' must start with one of: ${PREFIXES}." >&2
+    echo "       the prefix is inferred from the task, not defaulted here." >&2
+    exit 1
+fi
+git check-ref-format --branch "${NAME}" >/dev/null 2>&1 || {
+    echo "error: '${NAME}' is not a valid branch name." >&2
+    exit 1
+}
+git show-ref --verify --quiet "refs/heads/${NAME}" && {
+    echo "error: branch '${NAME}' already exists; switch to it instead." >&2
+    exit 1
+}
+
+START_REF=$(git symbolic-ref --quiet --short HEAD || true)
+if [ -z "${START_REF}" ]; then
+    echo "error: detached HEAD; switch to a branch first." >&2
+    exit 1
+fi
+
+STATE_ROOT=$(git rev-parse --absolute-git-dir)
+for state in MERGE_HEAD rebase-merge rebase-apply CHERRY_PICK_HEAD BISECT_LOG; do
+    [ -e "${STATE_ROOT}/${state}" ] && {
+        echo "error: a '${state}' operation is in progress; finish or abort it first." >&2
+        exit 1
+    }
+done
+# `--porcelain` is deliberately stricter than `git diff --quiet`: it also reports
+# untracked files, which would otherwise ride silently onto the new branch.
+DIRTY=$(git status --porcelain)
+if [ -n "${DIRTY}" ]; then
+    echo "error: working tree is not clean:" >&2
+    echo "${DIRTY}" | sed 's/^/         /' >&2
+    exit 1
+fi
+
+git show-ref --verify --quiet "refs/heads/${BASE}" || {
+    echo "error: no local '${BASE}' to branch from." >&2
+    exit 1
+}
+
+# Derive the remote rather than hardcoding it: this repo has `origin` (ssh) and
+# `origin_https`, and `main` tracks the latter — `git fetch origin main` would
+# check currency against a ref that is never updated here.
+# `--quiet` echoes the unresolved `main@{upstream}` literal to stdout on
+# failure, so it cannot be paired with a `$(...) || fallback`; the non-quiet
+# form prints nothing on failure and the fallback runs.
+UPSTREAM=$(git rev-parse --abbrev-ref --symbolic-full-name "${BASE}@{upstream}" 2>/dev/null) || UPSTREAM=""
+if [ -n "${UPSTREAM}" ]; then
+    git fetch --quiet "${UPSTREAM%/*}" "${UPSTREAM#*/}" || {
+        echo "error: '${UPSTREAM}' check failed: could not reach '${UPSTREAM%/*}'." >&2
+        echo "       refusing to branch on a possibly stale '${BASE}'." >&2
+        exit 1
+    }
+    BEHIND=$(git rev-list --count "${BASE}..${UPSTREAM}")
+    AHEAD=$(git rev-list --count "${UPSTREAM}..${BASE}")
+    if [ "${BEHIND}" -ne 0 ] || [ "${AHEAD}" -ne 0 ]; then
+        echo "error: '${BASE}' has diverged from '${UPSTREAM}' (ahead ${AHEAD}, behind ${BEHIND})." >&2
+        [ "${AHEAD}" -ne 0 ] && echo "       not yet pushed commits on '${BASE}': push them, or rebase this work onto them." >&2
+        [ "${BEHIND}" -ne 0 ] && echo "       update it: git switch ${BASE} && git pull --ff-only" >&2
+        exit 1
+    fi
+else
+    echo "warning: '${BASE}' has no upstream; freshness against the remote is unchecked." >&2
+fi
+
+restore() {
+    git switch --quiet "${START_REF}" 2>/dev/null || true
+}
+trap 'restore' EXIT HUP INT TERM
+
+if [ "${START_REF}" != "${BASE}" ]; then
+    git switch --quiet "${BASE}"
+fi
+
+echo "Baseline: npm run test"
+if ! npm run --silent test; then
+    echo "error: baseline is red on '${BASE}'; fix that first so later failures stay attributable." >&2
+    exit 1
+fi
+
+git switch --quiet --no-track -c "${NAME}"
+trap - EXIT HUP INT TERM
+
+# push.default=upstream is set here, so an inherited upstream would make a bare
+# `git push` target main. Branching local-from-local does not set one anyway;
+# --no-track says so out loud.
+echo "Created ${NAME} from ${BASE} $(git rev-parse --short "${BASE}")."

scripts/finish.sh

@@ -0,0 +1,136 @@
+#!/bin/sh
+
+set -eu
+
+# Feature-finish front door. Run as `npm run create:finish`.
+#
+# Why this exists: `create:branch` opens a unit of work, but the close half
+# (`git checkout main && git merge --no-ff <branch>`) stayed prose in the
+# branching model, so it drifted per contributor and per session. This is the
+# mirror image of `create:branch`: it asserts the same preconditions (clean
+# tree, no in-progress operation, `main` matching its upstream), merges the
+# current `feature/`/`fix/`/`chore/` branch into `main`, proves the result with
+# `npm run verify`, and only then deletes the branch.
+#
+# `create:branch`'s comment argued against wrapping the merge as "judgment —
+# review the diff yourself". That judgment still lives here, just moved: the
+# maintainer reviews the handover *before* invoking this, and the script only
+# commits the merge, never the push. The push is owned by `create:release`, so
+# the release commit and its tag leave together and a local merge stays
+# reviewable (and can be reverted with `git revert -m 1`) until then. `--no-ff`
+# keeps the unit of work visible in `git log`.
+#
+# Unlike `create:branch` a stale `main` is fast-forwarded instead of refused:
+# the tree is clean (checked above) and `main` is not the checked-out branch
+# yet, so there is no local state to lose. True divergence (local commits *and*
+# upstream commits) is still refused — that needs a human.
+#
+# On a merge conflict we abort and return to the feature branch, so a failed
+# finish never strands you on a half-merged `main`.
+
+BASE="main"
+PREFIXES="feature fix chore"
+
+git rev-parse --is-inside-work-tree >/dev/null 2>&1 || {
+    echo "error: not inside a git work tree." >&2
+    exit 1
+}
+
+STATE_ROOT=$(git rev-parse --absolute-git-dir)
+for state in MERGE_HEAD rebase-merge rebase-apply CHERRY_PICK_HEAD BISECT_LOG; do
+    [ -e "${STATE_ROOT}/${state}" ] && {
+        echo "error: a '${state}' operation is in progress; finish or abort it first." >&2
+        exit 1
+    }
+done
+
+# `--porcelain` is deliberately stricter than `git diff --quiet`: it also
+# reports untracked files, which would otherwise not be part of the merge and
+# silently outlive the branch deletion.
+DIRTY=$(git status --porcelain)
+if [ -n "${DIRTY}" ]; then
+    echo "error: working tree is not clean:" >&2
+    echo "${DIRTY}" | sed 's/^/         /' >&2
+    exit 1
+fi
+
+START_REF=$(git symbolic-ref --quiet --short HEAD || true)
+if [ -z "${START_REF}" ]; then
+    echo "error: detached HEAD; switch to the branch you want to finish." >&2
+    exit 1
+fi
+
+if [ "${START_REF}" = "${BASE}" ]; then
+    echo "error: already on '${BASE}'; switch to the branch to finish." >&2
+    exit 1
+fi
+
+MATCH=0
+for p in ${PREFIXES}; do
+    case "${START_REF}" in
+    "${p}/"*) MATCH=1 ;;
+    esac
+done
+if [ "${MATCH}" -ne 1 ]; then
+    echo "error: '${START_REF}' must start with one of: ${PREFIXES}." >&2
+    echo "       refusing to merge a branch that is not a unit of work." >&2
+    exit 1
+fi
+
+git show-ref --verify --quiet "refs/heads/${BASE}" || {
+    echo "error: no local '${BASE}' to merge into." >&2
+    exit 1
+}
+
+# Derive the remote rather than hardcoding it: this repo has `origin` (ssh) and
+# `origin_https`, and `main` tracks the latter — `git fetch origin main` would
+# check currency against a ref that is never updated here.
+# `--quiet` echoes the unresolved `main@{upstream}` literal to stdout on
+# failure, so it cannot be paired with a `$(...) || fallback`; the non-quiet
+# form prints nothing on failure and the fallback runs.
+UPSTREAM=$(git rev-parse --abbrev-ref --symbolic-full-name "${BASE}@{upstream}" 2>/dev/null) || UPSTREAM=""
+BEHIND=0
+if [ -n "${UPSTREAM}" ]; then
+    git fetch --quiet "${UPSTREAM%/*}" "${UPSTREAM#*/}" || {
+        echo "error: '${UPSTREAM}' check failed: could not reach '${UPSTREAM%/*}'." >&2
+        echo "       refusing to merge onto a possibly stale '${BASE}'." >&2
+        exit 1
+    }
+    BEHIND=$(git rev-list --count "${BASE}..${UPSTREAM}")
+    AHEAD=$(git rev-list --count "${UPSTREAM}..${BASE}")
+    if [ "${AHEAD}" -ne 0 ] && [ "${BEHIND}" -ne 0 ]; then
+        echo "error: '${BASE}' has diverged from '${UPSTREAM}' (ahead ${AHEAD}, behind ${BEHIND})." >&2
+        echo "       reconcile '${BASE}' with '${UPSTREAM}' before finishing." >&2
+        exit 1
+    fi
+else
+    echo "warning: '${BASE}' has no upstream; freshness against the remote is unchecked." >&2
+fi
+
+echo "Finishing into ${BASE}:"
+git --no-pager log --oneline --no-decorate "${BASE}..${START_REF}" | sed 's/^/  /'
+
+git switch --quiet "${BASE}"
+if [ "${BEHIND}" -ne 0 ]; then
+    echo "Fast-forwarding ${BASE} to ${UPSTREAM} (${BEHIND} commit(s))."
+    git merge --quiet --ff-only "${UPSTREAM}"
+fi
+
+if ! git merge --quiet --no-ff -m ":twisted_rightwards_arrows: Merge ${START_REF} into ${BASE}" "${START_REF}"; then
+    echo "error: merge of '${START_REF}' failed; aborting and returning to it." >&2
+    git merge --abort 2>/dev/null || true
+    git switch --quiet "${START_REF}"
+    exit 1
+fi
+
+echo "Verify: npm run verify"
+if ! npm run --silent verify; then
+    echo "error: 'npm run verify' is red after the merge." >&2
+    echo "       the merge is local and not yet pushed; fix it on '${BASE}' and commit," >&2
+    echo "       then drop the now-merged branch with 'git branch -d ${START_REF}'." >&2
+    exit 1
+fi
+
+git branch --delete "${START_REF}" >/dev/null
+echo "Merged ${START_REF} into ${BASE} and deleted the branch."
+echo "Next: npm run create:release (or git push, for a merge with no release)."

scripts/precompress.ts

@@ -0,0 +1,144 @@
+import fs from "node:fs";
+import path from "node:path";
+import zlib from "node:zlib";
+
+/**
+ * Emit precompressed `.br` / `.gz` / `.zst` sidecars next to every text asset
+ * under the given directories, keeping the originals. The Gitea pages service
+ * (`static-web-server` with `SERVER_COMPRESSION_STATIC=true`) serves the sidecar
+ * matching `Accept-Encoding` and falls back to the original for the rest.
+ *
+ * Usage: node --strip-types scripts/precompress.ts <dir> [<dir>...]
+ */
+
+/**
+ * Only extensions worth compressing. Images, fonts and archives are already
+ * compressed, so a sidecar would only make them bigger.
+ */
+const TEXT_EXTENSIONS: ReadonlySet<string> = new Set([
+    ".css",
+    ".htm",
+    ".html",
+    ".info",
+    ".js",
+    ".json",
+    ".map",
+    ".md",
+    ".mjs",
+    ".svg",
+    ".txt",
+    ".xml",
+    ".yaml",
+    ".yml",
+]);
+
+const GZIP_LEVEL = 9;
+const ZSTD_LEVEL = 19;
+const INITIAL_COUNT = 0;
+/** `process.argv` is `[node, script, ...args]`; drop the first two entries. */
+const ARGV_PREFIX_LENGTH = 2;
+const FAILURE_EXIT_CODE = 1;
+
+interface Encoder {
+    readonly suffix: string;
+    readonly encode: (input: Buffer) => Buffer;
+}
+
+const ENCODERS: readonly Encoder[] = [
+    {
+        suffix: ".br",
+        encode: (input) =>
+            zlib.brotliCompressSync(input, {
+                params: {
+                    [zlib.constants.BROTLI_PARAM_QUALITY]:
+                        zlib.constants.BROTLI_MAX_QUALITY,
+                },
+            }),
+    },
+    {
+        suffix: ".gz",
+        encode: (input) => zlib.gzipSync(input, { level: GZIP_LEVEL }),
+    },
+    {
+        suffix: ".zst",
+        encode: (input) =>
+            zlib.zstdCompressSync(input, {
+                params: {
+                    [zlib.constants.ZSTD_c_compressionLevel]: ZSTD_LEVEL,
+                },
+            }),
+    },
+];
+
+interface Totals {
+    assets: number;
+    sidecars: number;
+    savedBytes: number;
+}
+
+/** Depth-first list of every regular file under `directory`, recursively. */
+const listFiles = (directory: string): string[] => {
+    const files: string[] = [];
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+        const entryPath = path.join(directory, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...listFiles(entryPath));
+        } else if (entry.isFile()) {
+            files.push(entryPath);
+        }
+    }
+    return files;
+};
+
+const writeSidecar = (
+    target: string,
+    input: Buffer,
+    encoder: Encoder,
+): number => {
+    const compressed = encoder.encode(input);
+    if (compressed.byteLength < input.byteLength) {
+        fs.writeFileSync(target, compressed);
+        return input.byteLength - compressed.byteLength;
+    }
+    // Drop a stale sidecar: it would still win at the server.
+    fs.rmSync(target, { force: true });
+    return INITIAL_COUNT;
+};
+
+const precompress = (file: string, totals: Totals): void => {
+    if (!TEXT_EXTENSIONS.has(path.extname(file).toLowerCase())) {
+        return;
+    }
+    totals.assets += 1;
+    const input = fs.readFileSync(file);
+    for (const encoder of ENCODERS) {
+        const saved = writeSidecar(`${file}${encoder.suffix}`, input, encoder);
+        if (saved > INITIAL_COUNT) {
+            totals.sidecars += 1;
+            totals.savedBytes += saved;
+        }
+    }
+};
+
+const main = (directories: readonly string[]): void => {
+    if (directories.length === INITIAL_COUNT) {
+        process.stderr.write("usage: precompress.ts <dir> [<dir>...]\n");
+        process.exitCode = FAILURE_EXIT_CODE;
+        return;
+    }
+    const totals: Totals = {
+        assets: INITIAL_COUNT,
+        sidecars: INITIAL_COUNT,
+        savedBytes: INITIAL_COUNT,
+    };
+    for (const directory of directories) {
+        for (const file of listFiles(directory)) {
+            precompress(file, totals);
+        }
+    }
+    process.stdout.write(
+        `precompressed ${totals.assets} text assets into ${totals.sidecars} sidecars (saved ${totals.savedBytes} bytes)\n`,
+    );
+};
+
+main(process.argv.slice(ARGV_PREFIX_LENGTH));

scripts/release-notes.sh

@@ -0,0 +1,64 @@
+#!/bin/sh
+
+set -eu
+
+# Print the Keep-a-Changelog section for a release tag, so CI can use it as the
+# body of the Gitea release page without re-implementing CHANGELOG parsing.
+#
+# Run as `scripts/release-notes.sh <tag>`. A leading `v` is tolerated so both
+# `v1.2.3` and `1.2.3` match the `## [1.2.3]` heading. Prints to stdout and
+# exits non-zero when the tag has no section, so a release can never publish
+# with an empty body.
+
+TAG="${1:-}"
+CHANGELOG="${CHANGELOG:-CHANGELOG.md}"
+
+if [ -z "${TAG}" ]; then
+    echo "Error: usage: $0 <tag>" >&2
+    exit 1
+fi
+
+if [ ! -f "${CHANGELOG}" ]; then
+    echo "Error: ${CHANGELOG} not found." >&2
+    exit 1
+fi
+
+# `v1.2.3` and `1.2.3` are the same release; the heading only ever uses the
+# bare version.
+VERSION="${TAG#v}"
+
+awk -v version="${VERSION}" '
+    # A new section ends the one we are printing (or is the one we want).
+    /^## \[/ {
+        if (found) exit
+        heading = $0
+        sub(/^## \[/, "", heading)
+        sub(/\].*$/, "", heading)
+        if (heading == version) found = 1
+        next
+    }
+
+    # Link-reference definitions live at the bottom of the file and are never
+    # part of the section body. Stopping here keeps the last release notes
+    # from picking them up (there is no following heading to stop at).
+    /^\[[^]]+\]:/ { exit }
+
+    found {
+        if ($0 ~ /^[[:space:]]*$/) {
+            # Buffer blank lines so trailing ones at the end of the section
+            # are dropped instead of leaking into the release body.
+            if (started) pending = pending $0 "\n"
+        } else {
+            printf "%s%s\n", pending, $0
+            pending = ""
+            started = 1
+        }
+    }
+
+    END {
+        if (!found) {
+            printf "Error: no CHANGELOG section for [%s].\n", version > "/dev/stderr"
+            exit 1
+        }
+    }
+' "${CHANGELOG}"

scripts/release.sh

@@ -0,0 +1,118 @@
+#!/bin/sh
+
+set -eu
+
+# Release front-door. Run as `npm run create:release`.
+#
+# How we got here (short): we want hand-written Keep-a-Changelog notes, an
+# [Unreleased] -> "## [x.y.z] - DATE" graduation, and a tag that marks the exact
+# commit on main that gets published. No single tool did BOTH the [Unreleased]
+# graduation AND the package.json bump. So split by strength: `pubv` (tiny,
+# changelog-driven) owns preflight + the interactive major/minor/patch heuristic
+# + graduating/committing CHANGELOG.md (no tag, no push); `npm version` syncs
+# package.json + the lockfile; `--amend` folds them into pubv's single commit;
+# tag AFTER the amend (so the tag is never orphaned) and push.
+#
+# The notes are finalized in VS Code *before* pubv: the [Unreleased] body is
+# what pubv's bump heuristic reads, so editing afterwards would inform the
+# changelog only, not the version choice. pubv refuses a dirty tree, so that
+# edit is committed as a staging commit and folded back into the single release
+# commit below.
+#
+# Rejected: the conventional-commits family (our history is gitmoji, not
+# Conventional; and we want hand-written notes); changesets/rtk (config + a
+# heavier version/publish flow that fights our CI-only publish); knope/kacl/
+# bestikk (changelog-only — don't bump package.json; plus 5yr/2yr/brand-new
+# maintenance); pubv alone (verified it never writes package.json). We also
+# tried `versions` (silverwind) — great Gitea support — but pairing it with a
+# hand-rolled promote became a ~180-line script we'd have to maintain, which is
+# exactly what this ~30-line version replaces.
+
+CHANGELOG="CHANGELOG.md"
+BASE="main"
+
+if ! command -v code >/dev/null 2>&1; then
+    echo "Error: 'code' (VS Code CLI) not found; install it or remove the editor step." >&2
+    exit 1
+fi
+
+# Releases are cut from `main` (see CONTRIBUTING § Publishing workflow). Make
+# that explicit rather than relying on pubv's default-branch check, so the
+# error names `main` even when the remote's default is configured differently.
+CURRENT=$(git symbolic-ref --quiet --short HEAD || true)
+if [ "${CURRENT}" != "${BASE}" ]; then
+    echo "Error: releases are cut from '${BASE}', but HEAD is '${CURRENT:-detached}'." >&2
+    exit 1
+fi
+
+# pubv decides the "default branch" by reading the *local*
+# `refs/remotes/origin/HEAD`, not by asking the remote, and `git fetch` never
+# updates that ref. After a default-branch change — or a clone from when the
+# default was different — it goes stale and pubv warns/fails because the
+# current branch (main) does not match it, even though main *is* the remote
+# default. Refresh it from the remote first, so pubv's branch preflight
+# compares against reality. (Without a network this fails, but so would the
+# push pubv is about to do, so it is a real error rather than one to swallow.)
+if ! git remote set-head origin --auto >/dev/null 2>&1; then
+    echo "Error: could not refresh origin/HEAD; check connectivity to origin." >&2
+    exit 1
+fi
+
+# The [Unreleased] body drives pubv's bump heuristic, so finalize it first.
+echo "Opening ${CHANGELOG} in VS Code to finalize the release notes..."
+code --wait "${CHANGELOG}"
+
+# pubv refuses a dirty tree (its "continue with a dirty tree?" prompt defaults
+# to No), so a changed changelog must be committed before it runs. That commit
+# is staging only — the fold below rewrites it into the single release commit.
+NOTES_MSG=":memo: Finalize release notes"
+if [ -n "$(git status --porcelain -- "${CHANGELOG}")" ]; then
+    echo "Committing finalized release notes..."
+    git add "${CHANGELOG}"
+    git commit -m "${NOTES_MSG}"
+fi
+
+echo "Running pubv..."
+pubv --no-tag --no-push --tag-prefix=none
+
+echo "Reading version from ${CHANGELOG}..."
+
+VERSION=$(
+    sed -nE 's/^## \[([0-9]+\.[0-9]+\.[0-9]+)\].*/\1/p' "${CHANGELOG}" |
+        head -n 1
+)
+
+if [ -z "${VERSION}" ]; then
+    echo "Error: Could not determine release version from ${CHANGELOG}." >&2
+    exit 1
+fi
+
+echo "Release version: ${VERSION}"
+
+echo "Updating package.json and package-lock.json..."
+npm version "${VERSION}" --no-git-tag-version
+
+# If pubv's graduation commit sits on top of our staging notes commit, drop it
+# back into the index so the amend below rewrites the notes commit into the one
+# release commit. A message check, not a flag, so a re-run after pubv aborted
+# still folds a notes commit left behind by the earlier attempt.
+if [ "$(git log -1 --format=%s HEAD~1 2>/dev/null || true)" = "${NOTES_MSG}" ]; then
+    git reset --soft HEAD~1
+fi
+
+echo "Amending release commit..."
+git add package.json package-lock.json "${CHANGELOG}"
+# The exact message format is load-bearing: the `release-gate` job in
+# .gitea/workflows/ci.yml recognizes `:rocket: Release x.y.z` on main and
+# skips the full CI run, since the tag push immediately after verifies the
+# identical SHA (and publishes). Keep the two in sync.
+git commit --amend -m ":rocket: Release ${VERSION}"
+
+echo "Creating tag ${VERSION}..."
+git tag "${VERSION}"
+
+echo "Pushing release..."
+git push
+git push --tags
+
+echo "Release ${VERSION} completed."

scripts/runner-image.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Build (and optionally push) the CI job image from docker/Dockerfile.
+# Run wherever docker + registry credentials live (the runner host, or any
+# machine that can reach the registry). The registry/repo below MUST match
+# the `container.image` references in .gitea/workflows/ci.yml — the runner
+# pulls the image by name.
+#
+# Usage: scripts/runner-image.sh [--push]
+
+IMAGE_REPO="gitea.e1nsnull.de/tmu/act-ci"
+
+NODE_VERSION="$(tr -d '[:space:]' < .node-version)"
+if [[ ! "${NODE_VERSION}" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+    echo "error: .node-version must be pinned to an exact x.y.z, got '${NODE_VERSION}'." >&2
+    echo "       setup-node resolves floats like '26' to the latest patch at runtime," >&2
+    echo "       which silently busts the tool-cache entry baked into the image." >&2
+    exit 1
+fi
+
+IMAGE="${IMAGE_REPO}:${NODE_VERSION}"
+
+# --pull: refresh the act base layer so the derivative does not float on an
+# aging default image forever (layer dedup keeps this cheap).
+docker build --pull --build-arg "NODE_VERSION=${NODE_VERSION}" -t "${IMAGE}" -f docker/Dockerfile .
+
+if [[ "${1:-}" == "--push" ]]; then
+    docker push "${IMAGE}"
+fi
+
+echo "built ${IMAGE}"
+echo "reminder: bump container.image in .gitea/workflows/ci.yml to this tag"

src/index.test.ts

@@ -1,9 +1,10 @@
+/* oxlint-disable typescript/no-floating-promises -- expectTypeOf() is a sync type-assertion library that the type-aware linter misidentifies as a promise */
 import { strict as assert } from "node:assert";
 import { test } from "node:test";
 
 import { expectTypeOf } from "expect-type";
 
-import { match, P, type Matcher } from "./index.ts";
+import { type Matcher, P, match } from "./index.ts";
 
 test("match returns a builder", () => {
     const builder = match("x");
@@ -27,7 +28,7 @@ test("P.type narrows to the typeof target", () => {
 });
 
 test("exhaustive() returns the union of handler return types", () => {
-    const result = match<"a" | "b">("a" as "a" | "b")
+    const result = match<"a" | "b">("a")
         .with(P.literal("a"), () => 1 as const)
         .with(P.literal("b"), () => "two" as const)
         .exhaustive();
@@ -37,7 +38,7 @@ test("exhaustive() returns the union of handler return types", () => {
 });
 
 test("otherwise() falls back when no case matches", () => {
-    const result = match<"x" | "y" | "z">("z" as "x" | "y" | "z")
+    const result = match<"x" | "y" | "z">("z")
         .with(P.literal("x"), (v): string => `got ${v}`)
         .otherwise((v): string => `fallback ${v}`);
     assert.equal(result, "fallback z");
@@ -46,7 +47,7 @@ test("otherwise() falls back when no case matches", () => {
 test("exhaustive throws when no case matches", () => {
     assert.throws(
         () =>
-            match<"a" | "b" | "c">("c" as "a" | "b" | "c")
+            match<"a" | "b" | "c">("c")
                 .with(P.literal("a"), () => "A")
                 .with(P.literal("b"), () => "B")
                 .exhaustive(),

src/match.ts

@@ -1,8 +1,6 @@
 import { P, type Matcher, type Pattern } from "./pattern.ts";
 
-type Cases<R> = ReadonlyArray<
+type Cases<R> = readonly (readonly [Matcher<unknown>, (value: unknown) => R])[];
-    readonly [Matcher<unknown>, (value: unknown) => R]
->;
 
 interface MatchBuilder<T, R> {
     with<U extends T, V>(
@@ -16,7 +14,7 @@ interface MatchBuilder<T, R> {
 const buildMatch = <T, R>(value: T, cases: Cases<R>): MatchBuilder<T, R> => {
     const apply = (): R | undefined => {
         for (const [matcher, handler] of cases) {
-            if (matcher.matches(value as unknown)) {
+            if (matcher.matches(value)) {
                 return handler(value);
             }
         }
@@ -30,6 +28,7 @@ const buildMatch = <T, R>(value: T, cases: Cases<R>): MatchBuilder<T, R> => {
         ): MatchBuilder<T, R | V> {
             const nextCases: Cases<R | V> = [
                 ...cases,
+                // oxlint-disable-next-line typescript/no-unsafe-type-assertion
                 [pattern, handler as (value: unknown) => R | V],
             ];
             return buildMatch(value, nextCases);
@@ -45,8 +44,8 @@ const buildMatch = <T, R>(value: T, cases: Cases<R>): MatchBuilder<T, R> => {
         },
         otherwise(handler: (value: T) => R): R {
             for (const [matcher, run] of cases) {
-                if (matcher.matches(value as unknown)) {
+                if (matcher.matches(value)) {
-                    return run(value) as R;
+                    return run(value);
                 }
             }
             return handler(value);

src/pattern.ts

@@ -14,7 +14,6 @@ const literalMatcher = <
 ): Matcher<L> => ({
     matches: (candidate): candidate is L => candidate === value,
 });
-
 const typeMatcher = <T>(
         type:
             | "string"
@@ -25,58 +24,75 @@ const typeMatcher = <T>(
             | "undefined"
             | "object"
             | "function",
-): Matcher<T> => {
+    ): Matcher<T> => {
         const matches = (value: unknown): value is T => {
-        if (type === "undefined") return value === undefined;
+            if (type === "undefined") {
-        if (type === "object")
+                return value === undefined;
+            }
+            if (type === "object") {
                 return (
                     (typeof value === "object" && value !== null) ||
                     typeof value === "function"
                 );
+            }
             return typeof value === type;
         };
         return { matches };
-};
+    },
-
+    whenMatcher = <T>(
-const whenMatcher = <T>(
         predicate: (value: unknown) => value is T,
-): Matcher<T> => ({
+    ): Matcher<T> => ({
         matches: predicate,
-});
+    }),
-
+    whenMatcherAny = <T>(
-const whenMatcherAny = <T>(
         predicate: (value: unknown) => boolean,
-): Matcher<T> => ({
+    ): Matcher<T> => ({
         matches: (value: unknown): value is T => predicate(value),
-});
+    }),
-
+    isNestedMatcher = (expected: unknown): expected is Matcher<unknown> =>
-const structuralMatcher = <S extends object, T extends S>(
-    shape: S,
-    refine?: (value: S) => value is T,
-): Matcher<T> => ({
-    matches: (value: unknown): value is T => {
-        if (typeof value !== "object" || value === null) return false;
-        const candidate = value as S;
-        for (const key of Object.keys(shape) as Array<keyof S>) {
-            if (!(key in candidate)) return false;
-            const expected = shape[key];
-            const actual = candidate[key];
-            if (
         typeof expected === "object" &&
         expected !== null &&
-                "matches" in expected
+        "matches" in expected,
-            ) {
+    // oxlint-disable-next-line typescript/no-unnecessary-type-parameters
-                const nested = expected as unknown as Matcher<unknown>;
+    keysMatch = <S extends object>(shape: S, candidate: object): boolean => {
-                if (!nested.matches(actual)) return false;
+        // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+        for (const key of Object.keys(shape) as (keyof S)[]) {
+            if (!(key in candidate)) {
+                return false;
+            }
+            // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+            const expected = shape[key],
+                // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+                actual = candidate[key as keyof object];
+            if (isNestedMatcher(expected)) {
+                if (!expected.matches(actual)) {
+                    return false;
+                }
             } else if (actual !== expected) {
                 return false;
             }
         }
-        return refine
+        return true;
-            ? refine(candidate)
-            : (true as T extends S ? true : never);
     },
-});
+    structuralMatcher = <S extends object, T extends S>(
+        shape: S,
+        refine?: (value: S) => value is T,
+    ): Matcher<T> => ({
+        matches: (value: unknown): value is T => {
+            if (typeof value !== "object" || value === null) {
+                return false;
+            }
+            // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+            const candidate = value as S;
+            if (!keysMatch(shape, candidate)) {
+                return false;
+            }
+            if (refine && !refine(candidate)) {
+                return false;
+            }
+            return true;
+        },
+    });
 
 export const P = {
     literal: literalMatcher,

tsconfig.build.json

@@ -2,9 +2,14 @@
     "extends": "./tsconfig.json",
     "compilerOptions": {
         "noEmit": false,
+        "target": "es2024",
+        "declaration": true,
+        "sourceMap": true,
+        "inlineSources": true,
+        "outDir": "dist",
         "rewriteRelativeImportExtensions": true,
-        "rootDir": "src",
+        "rootDir": "src"
-        "outDir": "dist"
     },
+    "include": ["src"],
     "exclude": ["src/**/*.test.ts", "src/**/__tests__/**"]
 }

tsconfig.json

@@ -1,39 +1,12 @@
 {
+    "extends": [
+        "@tsconfig/node26/tsconfig.json",
+        "@tsconfig/strictest/tsconfig.json"
+    ],
     "compilerOptions": {
         "noEmit": true,
-        "target": "es2024",
-        "module": "nodenext",
-        "moduleResolution": "nodenext",
-        "moduleDetection": "force",
-        "lib": ["es2024"],
-        "skipLibCheck": true,
-        "strict": true,
-        "noImplicitAny": true,
-        "noImplicitThis": true,
-        "alwaysStrict": true,
-        "strictNullChecks": true,
-        "strictFunctionTypes": true,
-        "strictBindCallApply": true,
-        "strictPropertyInitialization": true,
-        "noImplicitReturns": true,
-        "noFallthroughCasesInSwitch": true,
-        "noUncheckedIndexedAccess": true,
-        "noImplicitOverride": true,
-        "forceConsistentCasingInFileNames": true,
-        "noUnusedLocals": true,
-        "noUnusedParameters": true,
-        "isolatedModules": true,
-        "verbatimModuleSyntax": true,
         "allowImportingTsExtensions": true,
-        "declaration": true,
+        "verbatimModuleSyntax": true
-        "declarationMap": true,
-        "sourceMap": true,
-        "outDir": "dist",
-        "esModuleInterop": true,
-        "allowSyntheticDefaultImports": true,
-        "resolveJsonModule": true,
-        "composite": false,
-        "types": ["node"]
     },
-    "include": ["src"]
+    "include": ["src", "scripts"]
 }