@jimhoyd/urlcode 0.4.2 → 0.4.6

package/docs/CI-RELEASE-AUDIT-2026-09-19.md

@@ -1,322 +0,0 @@
-# CI and monorepo release audit — 2026-09-19
-
-Status: historical findings and recommendation. The accompanying implementation
-and current commands are documented in [the development pipeline](DEVELOPMENT-PIPELINE.md).
-The proposed helper table below records the audit design, not the installed command list. Source inspected:
-`3a3d9adf6f0ec53faa078c93dfb977aa5ac416f7`; GitHub settings, runs, tags,
-releases and npm dist-tags were read on September 19. Concurrent PRs may change
-this snapshot. This review does not authorize publishing or changing protections.
-
-## Recommendation
-
-Keep npm workspaces and Changesets, independent package versions, and the
-existing public package names. Add an explicit change classifier for CI and one
-release coordinator for all four packages. Preserve the existing required gate
-and CodeQL policy. Stop using tag pushes as the place to discover whether a
-release is buildable. Prepare and validate an immutable release plan first;
-create tags from that plan once; resume partial publication without moving them.
-
-Do this incrementally. A repository layout migration, Nx, Turborepo, remote
-caching, or fewer security assertions is not a prerequisite for faster PRs.
-
-## Measured bottleneck
-
-[PR #181](https://github.com/jimhoyd-com/urlcode/pull/181) changed only
-`AGENTS.md` (9 additions, 4 deletions). Its
-[verify run](https://github.com/jimhoyd-com/urlcode/actions/runs/35475753912)
-took **9m08s** from creation to completion.
-
-| Job | Execution time |
-| --- | ---: |
-| verify, Linux / Node 22 | 8m24s, after 39s from workflow creation to job start |
-| verify, Linux / Node 24 | 5m49s |
-| verify, Linux / Node 26 | 5m36s |
-| build-fidelity | 27s |
-| action | 25s |
-| container | 22s |
-| audit | 19s |
-| verify-complete | 2s |
-
-Within Node 22, `npm run verify` took 7m33s. Its core tests took 281.7s,
-auth tests 92.9s, admin tests 23.6s, and UI tests 2.7s. These suites run
-**serially**. Lint, typecheck and source checks took roughly 29s combined.
-Package verification subsequently took 28s; drills took 7s. This is chiefly
-execution time, not queueing, in this example.
-
-The same pattern appears in
-[PR #180's run](https://github.com/jimhoyd-com/urlcode/actions/runs/35475563183):
-8m38s overall, with Node 22 the longest job. These are sampled runs, not a
-long-term percentile study or a demonstrated performance gain.
-
-Conversely, the
-[UI alpha.6 release](https://github.com/jimhoyd-com/urlcode/actions/runs/35475220590)
-took 19m23s: approximately 11m24s before the job started, then 7m37s in the
-whole-repository verify step. Both queue pressure and unnecessarily broad
-release verification matter there; the API does not establish the queue's cause.
-
-The workflow already avoids branch-push plus PR duplication and cancels stale
-PR runs. Its three PR matrix legs repeat lint, types, generated-file checks,
-builds, every package's tests, package smoke tests and drills. Main expands this
-to nine OS/Node combinations. `test:package` builds again after `verify` has
-built; candidate/core release explicitly build before calling `verify`, which
-builds again, and then `test:package`, which builds a third time.
-
-## What the checks buy
-
-| Check | Purpose | Proposed placement |
-| --- | --- | --- |
-| Documentation and generated resources | Prevent stale references, guidance and authoring resources | Every PR; standalone fast lane for prose changes |
-| Lint and typecheck | Source and contract errors | Once per relevant change on a canonical Node version |
-| Core and extension regressions | Behavioral, integration and isolation invariants | Affected packages and downstream consumers on PRs; full validation for releases |
-| Supported Node versions | Detect runtime compatibility failures | Retain all three versions for runtime changes initially; avoid repeating static checks |
-| Windows/macOS | Path, process, filesystem and platform differences | Targeted PR coverage plus full main coverage initially |
-| Package install smoke | Prove shipped archives and declarations work | Relevant package/CLI/starter changes and releases; lightweight pack inventory for shipped-doc changes |
-| Container | Validate the shipped execution environment | Keep existing required job; early optimization can leave this cheap job alone |
-| Action smoke | Exercise the consumer-facing composite action | Runtime/action/starter/build changes |
-| Build fidelity | Detect nondeterministic emitted files and packs | Build/package/toolchain changes and releases |
-| Runtime dependency audit | Detect known advisories | Keep initially: measured cost is small; also run on a schedule and before release |
-| CodeQL | Static security analysis | Preserve current enforced policy; not the observed critical path |
-| Operational drills | Local lifecycle/recovery regression signal | Relevant runtime changes, main and release validation |
-| Real-model evals | Authoring quality regression | Existing weekly/manual workflow; no need to put it on ordinary PRs |
-
-Do not remove timeout, worker replacement, sandbox or authentication tests to
-save time. Profile and change their scheduling or fixtures while preserving the
-behavior they establish. The longest sampled core subtests included explain
-versus runtime agreement (~35s), a slim-image installer test (~21s), and sitemap
-limits (~21s). Investigate repeated CLI startups and repeated project loading;
-these measurements do not yet establish which internal operation dominates.
-Auth's ~93s warrants separate profiling, including password hashing, without
-changing production security parameters to speed up tests.
-
-## PR workflow shape
-
-Always start the workflow. A small, tested classifier compares the complete PR
-diff against its base, including renamed/deleted paths, and emits an explicit
-job plan. Missing history, unknown paths, classifier errors and workflow/shared
-toolchain changes select full verification. Do not infer safety just from a
-`.md` extension: starter, recipe and executable authoring inputs need their
-own categories. Core changes affect all consumers; UI affects auth/admin; auth
-affects admin; admin-only changes need not retest all of core.
-
-For a prose-only PR, run guidance and generated-resource checks, local link and
-reference checks, and applicable package file-inclusion assertions. Extract this
-from today's `check` rather than calling the full source/test syntax walk.
-Changes to generator code, manifests, lockfiles, schemas, executable examples or
-CI configuration must leave the prose-only lane.
-
-For code PRs, run static checks once, build required outputs/styles in dependency
-order, and schedule core/UI/auth/admin tests independently. Start by preserving
-the current Node coverage. Pilot two balanced core-test shards on the slowest
-leg, measure runner-minutes and wall time, and increase only if the gains justify
-the extra jobs. Keep the full local `npm run verify` entry point.
-
-The `verify-complete` gate must know which jobs the classifier required. It must
-reject failure, cancellation, missing results and unexpected skips; accept a
-skip only when the validated plan explicitly marks that job unnecessary. Test
-the gate's failure paths. The present gate rejects every skipped dependency, so
-adding `if:` conditions without updating its contract will break merging.
-
-Do not add workflow-level `paths-ignore` to a required workflow: GitHub documents
-that such skipped workflows can leave required checks pending. Use job selection
-inside an always-triggered workflow instead.
-[GitHub documentation](https://docs.github.com/en/actions/how-tos/manage-workflow-runs/skip-workflow-runs)
-
-The live main ruleset requires `container` and `verify-complete`, and separately
-enforces CodeQL findings. It has no bypass actors. Its strict up-to-date setting
-is **false**, contrary to CONTRIBUTING's claim that an up-to-date branch is
-required. Preserve protections in the first implementation; reconcile that
-documentation. A later policy change needs a deliberate review, not an implicit
-side effect of renaming jobs.
-
-Windows failures are real: the
-[main run at cc582f2](https://github.com/jimhoyd-com/urlcode/actions/runs/35475923267)
-failed on `spawnSync npm.cmd EINVAL` in UI packaging. PR
-[#182](https://github.com/jimhoyd-com/urlcode/pull/182) already addresses this.
-Linux-only PR tests let this reach main. Add a focused Windows packaging/process
-smoke for relevant changes before considering a smaller main matrix. Keep the
-existing full main matrix during rollout; moving exhaustive coverage to nightly
-is a later tradeoff, and release candidates must still pass full validation.
-
-Initial goals: prose PRs under 90 seconds excluding runner queueing; ordinary
-code PRs under 5 minutes. These are targets, not measured promises. Report queue
-time separately from execution, and compare p50/p95 over at least 20 runs per
-change class before deciding the optimization succeeded.
-
-## Release and tag findings
-
-1. **Tags have actually moved across source revisions.** Release history for
-   `v0.4.0-alpha.1` records five distinct commits: `b5cd619`, `871dd87`,
-   `bb0f9e6`, `84e45ea`, then successful `8dabc7e`. The sampled history also
-   shows multiple commits for `v0.3.0`, `v0.2.0`, and `v0.1.0`. This establishes
-   reuse of tag names across commits, not who changed them or whether every
-   failed attempt published an artifact. The live ruleset inventory contained
-   only a branch ruleset, not tag protection.
-2. **An ancestor of main is not necessarily a validated release commit.** All
-   four release workflows check main ancestry, but do not require the exact
-   commit's main CI result. UI alpha.6 published from `8fa7f8b` while that
-   commit's main verify run failed on Windows. Release validation was Linux-only.
-3. **Core alphas are classified as normal GitHub releases.** Both alpha.1 and
-   alpha.2 had `prerelease: false`; GitHub's latest-release endpoint returned
-   alpha.2. Core's release creation omits the prerelease flag. npm correctly
-   separates its `alpha` channel; this is a distinct GitHub-channel defect.
-4. **Core container publication always updates `latest`.** `release.yml` tags
-   and pushes `latest` even for prereleases when `PUBLISH_CONTAINER` is enabled.
-   The code path is confirmed; this audit did not establish whether an alpha
-   actually overwrote the live GHCR tag.
-5. **Candidate and release have already diverged.** Candidate reads Dockerfile
-   into two shell variables, swallowing `AS build` into the image variable and
-   failing the digest regex. The same parse was fixed only in release. Running
-   candidate's parser locally against the current Dockerfile reproduced failure.
-   The last listed candidate successes predate this snapshot; no new candidate
-   was dispatched during this audit. Existing release tests check release's parser,
-   not both paths.
-6. **Existence is treated as sufficient for retry.** Publish steps skip an
-   existing npm version without checking its integrity against the candidate;
-   GitHub release uploads use `--clobber`. The fidelity job tests repeated packing
-   in one checkout, not equality to a prior publication. Extension builds use
-   floating Node 22 and registry-installed peers, so same-commit reproducibility
-   across days is not established. Preserve and compare the original artifact.
-7. **Concurrency is scoped to a tag.** Two different versions of one package can
-   publish concurrently; there is no shared release-train order or monotonic
-   channel guard. A late old release could update a channel after a newer one.
-8. **Changesets is only partially in charge.** Version 3.0.3 is installed and
-   pre-mode is enabled, with independent versions. Core is outside its workspace
-   package set. The tag checker checks trigger disjointness, not remote tag SHA,
-   registry integrity, missing changesets, peer compatibility or channel state.
-   PR [#183](https://github.com/jimhoyd-com/urlcode/pull/183) already tackles a
-   Changesets peer-range rewrite and stale channel documentation; build on it.
-9. **Release documentation contains competing snapshots.** VERSION-ALIGNMENT
-   still describes old repository pins, and the Changesets README says only UI
-   is covered and publishing is not wired up, despite a successful monorepo UI
-   release. RELEASE-SECURITY describes candidate/release as sharing a path that
-   has demonstrably diverged. Generate the live inventory; retain policy in prose.
-
-The actual npm channels at audit time were:
-
-| Package | `latest` | `alpha` |
-| --- | --- | --- |
-| core | 0.3.0 | 0.4.0-alpha.2 |
-| ui | 0.1.0-alpha.5 | 0.1.0-alpha.6 |
-| auth | 0.1.0-alpha.3 | 0.1.0-alpha.3 |
-| admin | 0.1.0-alpha.3 | 0.1.0-alpha.3 |
-
-Different channel values are not inherently drift. Historical extension `latest`
-values are already alphas; do not silently move them. Define channel intent,
-test the documented install combinations against peer ranges, and report
-deviations. An old core release tag also should not follow current main:
-unreleased development is normal; silently relabeling a published version is not.
-
-## One release process for four independently versioned packages
-
-Use Changesets for reviewed release intent and changelogs, with `fixed` and
-`linked` remaining empty. Require a changeset or a reviewed no-release reason
-for changes to publishable behavior. A routine feature PR need not manually
-bump versions: an accumulated release PR owns version changes, lockfile updates,
-peer-range changes and changelogs together. This replaces VERSION-ALIGNMENT's
-instruction to bump on every source-changing PR once the new flow is implemented.
-[Changesets configuration](https://github.com/changesets/changesets/blob/main/docs/config-file-options.md)
-
-Near term, keep root core where it is and include it explicitly in the common
-release inventory and plan, with its existing version update reviewed in the
-same release PR. Do not pretend `changeset version` covers it. Longer term,
-evaluate moving core to `packages/core` with a private tooling root so Changesets
-can own all four uniformly. That is a separate migration with CLI/container/
-starter/package tests, not part of the urgent CI fix. Preserve existing tag
-formats during this transition; any future new core tag format needs an explicit
-compatibility decision for install.sh, Homebrew, action consumers and old links.
-
-Proposed lifecycle:
-
-1. A protected release PR produces versions and a plan listing package name,
-   directory, version, tag, channel and dependency order. Manifests supply the
-   versions; the plan does not become a second hand-maintained version database.
-2. After merge, select and freeze its exact main SHA. Require that SHA's main
-   checks and release-specific validation; never substitute the newest passing
-   run from another commit. A canceled/missing full check must be run for the
-   selected SHA. Run without publication credentials during preparation.
-3. Build once with locked tooling, pack the proposed packages, and install the
-   actual tarballs together in a clean consumer project without development
-   export conditions. Separately test declared published peer floors. Where a
-   new floor belongs to this release, test its candidate tarball before publishing
-   and confirm registry resolution after its predecessor publishes.
-4. Sign and retain artifacts and a manifest binding source SHA, package versions,
-   dependency versions, lock hash and artifact hashes. Exercise this same prepare
-   path for a manual candidate; candidate must not be a second copied implementation.
-5. Create each expected tag once at that SHA. Refuse a remote tag at a different
-   SHA. Publish the prepared bytes in dependency order: core/UI before auth, auth
-   before admin, including only packages that need a release. Serialize publication
-   across the release train. Keep write/OIDC permissions confined to publication.
-6. On retry, reconcile each artifact with npm integrity, tags, GitHub assets and
-   container digests. Identical means complete; a mismatch stops. A registry
-   timeout is not proof a version is absent. Never clobber a different asset or
-   move a version tag. Reuse retained bytes; if unavailable, require a rebuild
-   that matches recorded hashes. A source fix needs a new version and release PR.
-7. Mark prereleases consistently on GitHub/npm/GHCR, and update mutable channels
-   only according to explicit policy with a guard against regressions. Summarize
-   partial success clearly; separate registries cannot form an atomic transaction.
-
-Protect release tag namespaces against update/deletion, with a narrowly defined
-creation path. This is a proposed strengthening, not a settings change made by
-the audit. Avoid a token-created-tag event chain: coordinate preparation and
-publication explicitly in workflow jobs/dispatch, rather than depending on
-another push workflow being triggered by a workflow-created tag.
-
-Initially retain the existing four trusted-publisher workflow filenames as thin
-wrappers around shared checked-in helpers. Consolidating to a new filename is a
-registry trust migration: verify each package's npm publisher identity and direct
-publish permission first. A dry run cannot prove the OIDC exchange works.
-[npm trusted publishing](https://docs.npmjs.com/trusted-publishers/)
-
-## Small helper surface
-
-These names describe proposed commands, not commands implemented by this audit.
-
-| Command | Contract |
-| --- | --- |
-| `npm run ci:plan -- --base SHA --head SHA` | Print change class, affected package closure, required jobs and why; deterministic and fail closed |
-| `npm run ci:report -- --run ID` | Read GitHub job/step timings, separate queue and execution, show failed checks and run links |
-| `npm run release:status` | Read manifests, Changesets state, Git tags, GitHub releases, npm versions/channels/integrity and peer compatibility; no mutations |
-| `npm run release:plan -- --sha SHA` | Produce the exact package/version/tag/channel/order plan, including root core |
-| `npm run release:prepare -- --plan FILE` | Validate, build, pack, smoke-test and write immutable artifact manifest; no publication |
-| `npm run release:publish -- --plan FILE` | CI-only mutation path; validate commit/checks/tags/artifacts, publish or resume idempotently |
-
-Use structured JSON outputs plus a short human summary. Share the version/tag/
-channel parser, manifest inventory, Docker image parser and integrity comparison
-between candidate and release. Test those contracts by execution, not only by
-regex checks that particular shell snippets exist in YAML. Add workflow syntax
-validation and fixtures for wrong tag, wrong SHA, mismatched version, prerelease,
-partial publish, existing unequal artifact, registry outage and peer-floor failure.
-
-## Rollout order and acceptance
-
-1. **Release correctness:** shared candidate parser, correct GitHub/GHCR alpha
-   handling, read-only status/preflight, immutable retry checks and exact-SHA
-   main-CI gate. Coordinate with #183; preserve the current publisher identities.
-2. **Immediate PR speed:** prose lane and tested classifier/gate. Keep existing
-   required check names, audit, CodeQL and container. Demonstrate a docs-only PR
-   finishing quickly and a deliberately failed required job blocking the gate.
-3. **Code throughput:** split static/core/workspace checks, remove redundant
-   builds, profile and shard the slow suites, add targeted Windows coverage.
-   Verify equivalent test coverage and measure queue/cost as well as latency.
-4. **Release coordination:** one Changesets release PR and package inventory,
-   one preparation path, serialized dependency-aware publication and immutable
-   reconciliation. Prove partial-failure recovery on a future authorized release.
-5. **Optional structural work:** core workspace migration and reconsideration of
-   the nine-leg main matrix after measured coverage/performance evidence.
-
-This audit made no release, tag, registry-channel or branch-protection changes.
-It inspected live evidence and reproduced the candidate parser failure locally;
-it did not execute a new full matrix, deploy containers, change npm trust, or
-prove end-to-end recovery. Passing CI is not an independent security assessment.
-
-## Implementation follow-through
-
-The user subsequently authorized implementation. The accompanying PR installs
-the conservative prose lane, separate core/workspace jobs, shared release
-helpers, live inventory and an explicit sequential tag coordinator. Root core
-remains outside Changesets; whole-train preparation before any tag and finer
-package selection are tracked in [#185](https://github.com/jimhoyd-com/urlcode/issues/185).
-The user explicitly approved the immutable-tag rule, now active as
-[23712319](https://github.com/jimhoyd-com/urlcode/rules/23712319), without bypass.
-The two historical core alpha release flags were corrected and GitHub latest
-restored to stable v0.3.0. No tags or artifact bytes were rewritten.

package/docs/CI.md

@@ -1,147 +0,0 @@
-# Checking a project on GitHub
-
-For this repository's own PR checks and releases, see the
-[development pipeline](DEVELOPMENT-PIPELINE.md). This page describes the action
-used by applications built with URLCode.
-
-`jimhoyd-com/urlcode/action` is a composite GitHub Action for a URLCode
-*project*: a repository with a `urlcode.yaml`. It runs the same local checks
-you run by hand and, on pull requests, keeps one comment up to date with the
-route-inventory diff against the base branch. It needs no cloud credentials;
-the only token it touches is the workflow's own `GITHUB_TOKEN`.
-
-The starter ships it as `.github/workflows/urlcode.yml` (`urlcode init` copies
-it; the [template repository](https://github.com/jimhoyd-com/urlcode-template)
-carries the same file):
-
-```yaml
-name: urlcode
-on:
-  push:
-  pull_request:
-permissions:
-  contents: read
-  pull-requests: write # the sticky route-diff comment; drop it to only log the diff
-jobs:
-  check:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          persist-credentials: false
-      - uses: jimhoyd-com/urlcode/action@main # pin a release tag or commit
-        with:
-          expect-routes: 2
-```
-
-The action lives at `action/action.yml` in the runtime repository, so the
-reference is `jimhoyd-com/urlcode/action@<ref>`. Pin `<ref>` the way you pin
-the runtime: a release tag or a commit SHA, not `main`, once the project is
-past its first commit.
-
-## What it runs
-
-| Step | Command | Fails the job when |
-|---|---|---|
-| Install | `npm ci` in the project (see below) | Dependencies do not install |
-| Validate | `urlcode validate --project <project>` | The YAML, includes, functions or bindings do not load |
-| Test | `urlcode test --project <project>` | A `tests/requests.json` fixture fails |
-| Audit | `urlcode audit --project <project> --expect-routes N --compliance <profile>` | Count mismatch, failed generated check, uncovered active route/method, or a `high` compliance finding without `compliance-warn` |
-| Route diff | `urlcode routes --compare base.json --format markdown` | Never; it reports |
-
-Every command is the CLI documented in [readiness](READINESS.md) and
-[compliance](COMPLIANCE.md); the action adds no check of its own. `--origin`
-is passed to validate, test and audit when set. Steps run with `bash`, so the
-action works on the Linux, macOS and Windows runners.
-
-The project's runtime comes from the project. With a `package.json` the action
-runs `npm ci` (or `npm install` without a lockfile) and uses the
-`@jimhoyd/urlcode` that resolves from there, hoisted or not. A project without
-`package.json`, such as a fresh `urlcode init`, gets the `runtime` input
-installed into a private prefix under the runner's temp directory:
-`@jimhoyd/urlcode` (the latest release) by default, or a version
-(`@jimhoyd/urlcode@0.3.0`) or an absolute tarball path.
-
-## Inputs
-
-| Input | Default | Meaning |
-|---|---|---|
-| `project` | `.` | Directory containing `urlcode.yaml`, relative to the workspace |
-| `node-version` | `26` | Passed to `actions/setup-node` |
-| `runtime` | `@jimhoyd/urlcode` | npm spec installed when the project has no `package.json` |
-| `expect-routes` | empty | `audit --expect-routes N`; empty skips the count check |
-| `compliance` | `baseline` | `baseline`, `strict`, `privacy` or `none` |
-| `compliance-rules` | empty | Absolute path to an operator rules module outside the project |
-| `compliance-warn` | `false` | Report findings without failing (`--compliance-warn`) |
-| `origin` | empty | Public origin of the deployment under review |
-| `route-diff` | `true` | Post the route diff on pull requests |
-
-Output `route-diff` is the path of the Markdown diff on a pull request, empty
-otherwise, for a later step that wants to upload or reuse it.
-
-## The sticky comment
-
-On `pull_request` events the action fetches the base commit, checks it out into
-a temporary git worktree, runs `urlcode routes` there and on the head with the
-head's runtime, and renders `routes --compare` as Markdown: one table each for
-added, removed and changed routes, or "No route changes". A changed route lists
-each differing field (handler, methods, state, `sandbox`, `sandboxReason`,
-middleware count, policies, generated marker or policy description) with its
-before and after value.
-
-`action/comment.mjs` then finds the pull request's comments for the marker
-`<!-- urlcode-route-diff project="<project>" -->` and updates that comment,
-or creates it on the first run. The key is the project directory, so a
-repository with several projects gets one comment per project and never a
-pile of stale ones. Updating comments needs `pull-requests: write`; on a
-fork's pull request or without that permission the API answers 403 or 404 and
-the step logs a notice and exits 0, leaving the diff in the job log. The same
-happens when the base commit is not reachable or its YAML does not load with
-the head runtime. The diff is generic: only the action knows about GitHub.
-
-## Custom compliance rules
-
-Write a rules module as [compliance](COMPLIANCE.md#writing-custom-rules)
-describes and keep it outside the audited project, because it runs as trusted
-host code. In a repository with the project at the root, put it in a sibling
-directory and pass the absolute path:
-
-```yaml
-      - uses: jimhoyd-com/urlcode/action@main
-        with:
-          expect-routes: 25
-          compliance: strict
-          compliance-rules: ${{ github.workspace }}/ci/rules.mjs
-          compliance-warn: true
-```
-
-`ci/rules.mjs` is inside the checkout but not inside the project only when
-`project` is a subdirectory; with `project: .` keep the rules in a second
-checkout or under `${{ runner.temp }}`. `compliance-rules` alone implies
-`compliance: baseline`; `compliance: none` without rules skips the compliance
-section entirely.
-
-## Exit codes
-
-The job fails when any of validate, test or audit exits nonzero; the
-[audit exit codes](COMPLIANCE.md#exit-codes) apply unchanged. The route diff
-and the comment never fail the job. A failing install (missing `@jimhoyd/urlcode`
-dependency, unavailable `runtime` spec) fails the job before any check runs.
-
-## The same checks locally
-
-```sh
-urlcode validate --project .
-urlcode test --project .
-urlcode audit --project . --expect-routes 2 --compliance baseline
-git stash && urlcode routes --project . > /tmp/base.json && git stash pop
-urlcode routes --project . --compare /tmp/base.json --format markdown
-```
-
-Or `make validate`, `make test` and `make audit ARGS='--expect-routes 2'`
-from the starter Makefile. The runtime repository exercises the action on
-full-lane pull requests against `examples/cookbook` (`.github/workflows/ci.yml`,
-job `action`) with the packed tarball as `runtime`, and `test/action.test.ts`
-checks that `action.yml` is a composite action with the inputs above and that
-every third-party action it or the starter workflow uses is pinned to a
-commit.

package/docs/CLOUDFLARE.md

@@ -1,109 +0,0 @@
-# Deploying to Cloudflare Workers
-
-Cloudflare Workers is not a Node host. There is no `worker_threads`, no
-filesystem, and code generation at runtime is forbidden. So this target does not
-adapt the runtime the way [Vercel](VERCEL.md) and [AWS](AWS.md) do — it
-**compiles the project ahead of time** and ships a Worker that reads the result.
-
-```sh
-urlcode build --target cloudflare --project . --out dist
-npx wrangler deploy
-```
-
-A working project is in [`examples/cloudflare/`](../examples/cloudflare/).
-
-## Declarative routes only
-
-This target serves **redirects** and **declared responses** (`respond:`), with
-path, query and header parameters, defaults, validation, response headers,
-`enabled` and `expires`. Everything else is refused **at build time**, with the
-route pattern and the reason named:
-
-| Handler | Why it is refused |
-| --- | --- |
-| `function`, `middleware` | need the self-hosted Node lifecycle, and worker threads and the QuickJS WASM engine when a route declares `sandbox: true` |
-| `page`, `static`, `download` | need a platform static-asset binding, not an inline copy |
-| `env`, `secrets` | would have to be baked into the artifact |
-
-Generated [site conventions](SITE.md) follow the same table: `robots`,
-`sitemap` and `securityTxt` are `respond` routes and compile into the artifact
-(pass `--origin` to `build` for the absolute URLs they contain); `favicon` and
-`llms` are `page` routes and are refused.
-
-A build artifact is a file that gets copied, cached and committed by mistake, so
-it never carries a secret. That is why `env` and `secrets` are refused even when
-the value is a literal in the YAML.
-
-Refusing at build time rather than at runtime is the point: a project that
-cannot be served fails `urlcode build`, so it never reaches a deployment.
-
-## What the build emits
-
-`--out` receives three generated files. None of them are edited by hand, and
-`dist/` belongs in `.gitignore`:
-
-- `artifact.js` — the compiled routes. **This is an internal build output, not a
-  published contract.** Its `format` may change in any release, and the runtime
-  refuses a format it does not recognise rather than guessing. Always rebuild
-  with the same version of URLCode that the Worker imports.
-- `validators.js` — the parameter schemas, precompiled by Ajv into standalone ES
-  modules. The platform forbids runtime code generation, so a validator cannot
-  be compiled on the Worker; it has to be compiled by the build.
-- `index.js` — the Worker entry, which is three lines over
-  `createFetchHandler` from `@jimhoyd/urlcode/cloudflare`. That import resolves to the
-  package's built `dist/cloudflare.js` (and its declarations, for a TypeScript
-  Worker); the artifact never depends on the TypeScript sources or on type
-  stripping.
-
-Ajv's standalone output hardcodes a CommonJS `require` for its runtime helpers
-even in ESM mode, which an ES module cannot evaluate. The build inlines each
-helper from the installed Ajv — the real function, not a copy that could drift —
-and fails if it meets a `require` it does not recognise, rather than emitting a
-Worker that cannot start.
-
-`wrangler.toml` needs no `nodejs_compat` flag. The runtime and the generated
-validators use Web standards only.
-
-## Portability, and where it stops
-
-The Worker shares its route matching, request policy and response policy with
-the self-hosted server: `src/match.ts`, `src/http-policy.ts` and
-`src/http-response.ts` are the same modules, with no Node imports. Two checks
-keep it that way: an ESLint rule forbids `node:` imports in the modules that
-ship to the Worker, and `scripts/check.ts` (part of `npm run verify`) walks the
-import closure of `src/cloudflare.ts` and fails on any `node:` specifier that
-is not an `import type`. `test/cloudflare.test.ts` builds a project, runs the same project on the
-self-hosted server, and asserts both return the same status, body and headers
-(everything but the per-request identifier) — including the example in this
-repository, replayed through the compiled Worker.
-
-[Policies](POLICIES.md) follow the same rule: `agents` and `security` are
-compiled into the artifact with project list files embedded as entries,
-`compression` is delegated to the edge, and `throttle` and `cache` are refused
-at build time with the route named. The artifact also carries the project-level
-`security` policy, so the Worker's own 404 and thrown-error responses get the
-same security headers the self-hosted server gives them.
-
-Two differences are real and deliberate:
-
-- **Duplicate request headers.** The platform joins repeated headers into one
-  value before the Worker runs, so per-header counts do not exist. The
-  self-hosted server rejects a duplicated scalar header parameter with 400. Here
-  that check cannot fire: the parameter sees the joined value (`a, b`) and is
-  validated against its schema like any other. A constrained schema still
-  rejects it; an unconstrained `type: string` accepts it where the self-hosted
-  server would not. Constrain header parameters you care about. The duplicate
-  `Content-Type` check on a declared request body is unavailable for the same
-  reason; a joined value fails the media-type check instead.
-- **The request target.** The self-hosted server inspects the request line
-  verbatim. The Worker only ever sees a parsed `Request`, so the target is
-  reconstructed from `URL`, and a malformed target the self-hosted server would
-  refuse may have been normalised or rejected by the platform before this code
-  runs. Path traversal, control characters, over-long targets and ambiguous `%`
-  sequences that do survive are still refused by the shared `parseTarget`.
-
-**This has never been deployed to Cloudflare.** Everything above is verified
-against the runtime's own test suite and a local build, not against the
-platform. A first real deployment is the next thing that would change that, and
-until it happens, treat compatibility with a specific `compatibility_date` and
-with Wrangler's bundler as unproven.