@jimhoyd/urlcode 0.4.2 → 0.4.7

package/docs/DEVELOPMENT-PIPELINE.md

@@ -1,304 +0,0 @@
-# Development and release pipeline
-
-The repository uses npm workspaces, independent package versions, and Changesets
-for UI, auth and admin. Core remains at the repository root and is explicitly
-included in the shared release inventory. Moving it is not required to use the
-same release checks and coordinator.
-
-## Pull requests and main pushes
-
-Every PR and every push to main starts `verify`. A complete Git diff selects one
-of two lanes:
-
-- **Prose:** root project Markdown, `docs/**/*.md`, `llms.txt`, `llms-full.txt`,
-  `benchmarks/agent/README.md`, `benchmarks/results/README.md` and each
-  package's `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md` and `GOVERNANCE.md` run
-  guidance/generated-resource checks, runtime audit, and the required container
-  job. CodeQL retains its repository policy.
-- **Full:** all other changes, mixed changes, and empty, unclassifiable or
-  unavailable diffs run static checks once and core and workspace suites
-  separately. Both suites retain Linux on Node 22/24/26. Main adds
-  Windows/macOS on Node 24. PRs add those platform legs for runtime, CLI,
-  SQLite, fixture, dependency, workflow and unknown changes; known UI
-  presentation-only changes omit them. Package, action, cookbook,
-  reproducibility and operational checks retain their coverage.
-
-A pull request is classified against its merge base; a push to main is
-classified tip to tip from the event's `before`/`after` SHAs, so a force-push or
-rewritten history is measured by what actually moved. Classification fails
-closed: a missing, malformed or all-zero SHA (branch creation or deletion), and
-history this checkout cannot read, select full verification. Scheduled and
-manually dispatched runs are never classified from paths at all, so exact-SHA
-release coverage cannot silently become a docs-only run.
-
-The prose allowlist is deliberately narrow, and it is a list of reviewed,
-non-executable contributor prose rather than "every Markdown file". Skills,
-starters, recipes, examples, schemas, manifests, workflows, benchmark prompts,
-tasks, answers and acceptance notes, and any package document that ships inside
-a published tarball or is read by an agent surface (`README.md`, `SECURITY.md`,
-`CONTRACT.md`, `THREAT-MODEL.md`, `IMPLEMENTATION-STATUS.md`, `AGENTS.md`,
-`CHANGELOG.md`) select full checks. Anything feeding a generator stays in the
-code lane. A rename from source into docs also selects full checks, because the
-diff is read without rename detection and shows both paths. Every prose path is
-still covered by the always-run `docs` job, which walks all authored Markdown.
-No required workflow uses `paths-ignore`.
-
-The always-run `docs` job runs `npm run check:docs`; in the full lane the
-`static` job runs `npm run check:code`, which is the rest of `npm run check`.
-The two together are exactly `npm run check`, which stays complete for local
-use. This removes a duplicated dependency install plus seven repeated checks on
-the same commit, not meaningful wall time: the sampled documentation checking
-was about two seconds. Job names, lane selection and `verify-complete`
-dependencies are unchanged.
-
-`verify-complete` accepts only the results specified by the successful plan.
-Failed, canceled, missing or unexpectedly skipped work fails the gate. Required
-check names (`verify-complete`, `container`) and CodeQL enforcement are preserved.
-The repository ruleset currently does not require a branch to be up to date;
-release publication separately requires verification of the exact main commit.
-
-```sh
-npm run check:docs                 # prose checks without the runtime suite
-npm run check:code                 # everything in `check` except the prose checks
-npm run ci:plan -- BASE_SHA HEAD_SHA # previews as a pull request outside Actions
-npm run ci:report -- RUN_ID         # read GitHub job/step durations
-npm run ci:history -- 100 2026-09-19 # group historical timing samples
-npm run verify                    # full local validation remains available
-npm run test:package              # builds and installs a real archive
-```
-
-CI uses `test:package:built` only after building in that same job. Core tests and
-workspace tests run in separate jobs to shorten their serial critical path;
-this increases job setup overhead and needs monitoring for runner queue pressure.
-After building all three extensions, the workspace job also runs the real
-`init --with ui,auth,admin` scaffold integration. Missing workspace outputs fail
-instead of silently skipping an absent external checkout.
-The [audit](CI-RELEASE-AUDIT-2026-09-19.md) records the previous timings.
-The [follow-up measurements](CI-FOLLOWUP-2026-09-19.md) record early compact-main observations; issue #185 contains the later decision
-and current sample sizes.
-
-## Version preparation and release ownership
-
-Core remains at the repository root. Independent extension versions remain
-supported; a coordinated version is an explicit maintainer choice, not a
-permanent fixed-version policy. An explicitly selected stable version exits
-Changesets alpha pre-mode when no package remains on alpha; subsequent stable
-patches stay out of pre-mode. Feature PRs record workspace release intent in
-Changesets; core release notes remain an explicit maintainer responsibility.
-
-`release:check` checks manifest/lock versions and peer ranges, CLI and MCP
-versions, generated plugin metadata, local peer compatibility, and channel policy.
-The preparation helper updates these together, adds release notes and extension
-changelogs, and records the version decision. Pending Changesets must be
-explicitly consumed; they are archived under `.changeset/pre/` and their summaries
-included in the release notes. Review the resulting diff and peer minimums.
-
-```sh
-# Example only: choose the next intended version before executing.
-npm run release:prepare -- --version 0.4.1 --consume-changesets
-# Apply local edits on a clean non-main branch; no remote writes or publication:
-npm run release:prepare -- --version 0.4.1 --consume-changesets --execute
-```
-
-An optional `--notes PATH` adds reviewed maintainer notes. Dry runs do not change
-files. Preparation rejects downgrades, reused local tags, dirty checkouts and
-stale plans. A stable target removes `.changeset/pre.json` once no package
-remains on alpha, publishes to npm `latest`, and leaves the historical `alpha`
-pointer unchanged. Alpha targets
-require existing alpha mode; the helper never silently re-enters prerelease mode.
-It does not invoke a permanent Changesets fixed-version policy.
-
-## GitHub Actions release buttons
-
-The Actions page exposes `release core`, `release UI`, `release auth`, `release
-admin` and `release all packages`. Each manual workflow accepts an exact stable
-or alpha version and whether to consume relevant pending Changesets. The four
-package workflows update and publish only their selected package. `release all
-packages` aligns and publishes the complete train in core → UI → auth → admin
-order. A Changeset spanning selected and unselected packages is rejected; use
-the all-packages workflow or split the change intentionally.
-
-All five buttons call the same serialized reusable workflow. It creates a
-release PR, waits for normal required checks, merges without bypass, runs the
-exact-commit full matrix and signed candidate, publishes the selected immutable
-tag, checks registry installability, and verifies the current four-package
-consumer combination. A core release also updates the standalone starter. The
-workflow is resumable: rerun the same button and version after repairing a
-failure. It reuses matching PRs, tags, candidates and successful publishers.
-
-Configure `RELEASE_AUTOMATION_TOKEN` as a repository Actions secret. Prefer a
-repository-scoped GitHub App token when available. A fine-grained PAT is also
-supported when it is limited to `urlcode` and `urlcode-template` with Contents,
-Pull requests and Actions read/write. The repositories are public, so the
-coordinator can inspect their check runs without an additional token
-permission. The token owner needs ordinary write access. Do not grant ruleset
-bypass, administration, approval or package-registry credentials; npm
-publishers continue to use their workflow OIDC identities. Dispatch from
-`main`.
-
-## One-command local release and resume
-
-Inspect without writing:
-
-```sh
-npm run release:status  # registry channels, peer compatibility, tag SHAs
-npm run release:plan    # manifest-derived inventory
-npm run release:run     # ordered states at this checkout: pending/resume/unchanged
-npm run release:run -- --version 0.4.1 --consume-changesets
-npm run release:run -- --version 0.4.2 --package auth --consume-changesets
-```
-
-For an explicitly authorized coordinated release:
-
-```sh
-npm run release:run -- --version 0.4.1 --consume-changesets --execute
-npm run release:run -- --version 0.4.2 --package auth --consume-changesets --execute
-```
-
-`--execute` authorizes the entire sequence: create the release branch/PR, wait
-for checks and merge, run the release gates, create version tags, publish, verify
-an installed consumer, and create/check/merge the starter update. It never
-approves a review or bypasses a required check. A required human review still
-blocks merging. No write or publication occurs without `--execute`.
-
-The coordinator works in a temporary clone and prints its location. It prepares
-`codex/release-VERSION`, or resumes the existing PR/branch after checking its
-versions and receipt. It checks out the actual merged SHA and reinstalls that
-commit's locked dependencies. Repeating the command discovers existing PRs,
-gates, tags and workflow state rather than creating another version. Temporary
-release clones are retained for diagnosis and can be removed after completion.
-
-For an independently prepared release PR already merged to main, use a clean
-checkout of its exact commit:
-
-```sh
-npm run release:run -- --execute
-```
-
-The coordinator creates `codex/release-validation/SHA` at the already-merged
-commit when gates are missing. An existing validation branch must name that
-exact SHA; it is never moved. This lets main advance without changing the release
-being tested. The branches remain as audit/resume references. It dispatches full
-`ci.yml` and `candidate.yml`, reuses existing successful runs, and waits for
-running ones. A failed gate stops with its run ID; diagnose it and rerun that
-exact run before resuming. Compact PR/main checks cannot replace the full
-OS/Node matrix or CodeQL on the selected commit.
-
-Before creating any version tags, it downloads and verifies the candidate bundle.
-A green run with missing artifacts does not authorize tags. New version tags are
-annotated with the source commit, chosen candidate run ID and the SHA256 of its
-signed manifest. The manifest binds every package and supporting asset by hash. Every package in a
-resumed train must select that same candidate. Neither a later candidate of the
-same source nor a newer main commit can silently replace the chosen bytes.
-A successful rerun of the same candidate ID cannot substitute a changed bundle: its
-manifest must still match the immutable checksum in the release tag.
-After tags exist, rerun package publishers rather than the pinned candidate run.
-If a later attempt of that candidate run fails, the coordinator stops even when
-an earlier attempt succeeded; it does not infer which attempt should be trusted.
-
-Publication is sequential: core → UI → auth → admin, skipping unchanged published
-versions. Each publisher must succeed and its version must be readable through
-npm's abbreviated install metadata, with a downloadable SHA512-verified tarball,
-before dependents begin. Bounded retries handle propagation, transport failures,
-429 and server errors; authentication and integrity failures stop immediately.
-Afterward, an external consumer with a fresh npm cache installs the four exact
-registry versions, checks its peer tree and imports, and generates the combined
-extension scaffold in dependency order (`ui,auth,admin`). The candidate archive
-smoke uses the same scaffold check before any package is published.
-
-The standalone starter helper updates the exact core pin, lockfile, matching
-schema/docs links and guide from the installed published core package, then runs
-validation/tests/audit/benchmark,
-and opens a resumable PR. The coordinator waits for checks and merges it, checking
-for a newer template pin immediately before merge. `--skip-template` explicitly
-leaves this follow-up to the maintainer. To run only that follow-up:
-
-```sh
-npm run release:template -- --version 0.4.1 --execute
-```
-
-That standalone helper opens a PR but does not merge it. All helpers stop on
-errors; rerun after diagnosis. A failed publisher is retried at most once per
-coordinator invocation and must pass the original-byte recovery checks below.
-
-The maintainer identity needs repository Contents, Actions and Pull requests
-write, plus Checks read, on the affected repositories. GitHub App installations
-should be scoped to URLCode and its template. No ruleset bypass or long-lived
-npm token is needed. The workflow `GITHUB_TOKEN` must not create the triggering
-version tags because its push events do not start ordinary push workflows.
-[GitHub App guidance](https://docs.github.com/en/apps/creating-github-apps/about-creating-github-apps/deciding-when-to-build-a-github-app)
-
-## Build once, publish verified bytes
-
-The four publisher filenames remain unchanged for npm trusted-publisher identity.
-The candidate builds in the digest-pinned environment, runs verification,
-packaging and local operational checks, packs all four packages, and tests an
-isolated combined consumer. The signed bundle contains all four archives,
-SBOM, Homebrew formula, source/build manifest, train identity and checksums.
-The manifest binds it to the candidate run as well as the commit.
-
-Publishers verify the selected candidate's workflow provenance, exact source SHA,
-run identity, manifest/package identities and hashes. They publish the selected
-package's existing archive without rebuilding it. Auth/admin still run isolated
-compatibility tests against their actual published peer floors; temporary test
-builds do not replace the promoted archive. This preserves the distinction
-between workspace compatibility and registry compatibility.
-
-Each package's GitHub release stores the complete signed bundle for durable
-recovery. Supporting sibling archives are candidate evidence: an independent
-package release does not imply every sibling archive was published to npm.
-Candidate and release Actions artifacts retain 90 days; retention is not an
-archival guarantee. Keep independent last-good copies for deployment rollback.
-
-## Recovery, immutable tags and channels
-
-A retry restores the original retained bundle, or recovers the complete verified
-bundle from that package's GitHub release. Missing, incomplete or unverifiable
-originals stop the retry. It never rebuilds archives or substitutes a new
-candidate. If publication stopped before a complete durable release existed and
-the retained artifact is gone, a new version may be required.
-
-Existing npm versions must match SHA512 integrity; existing GitHub assets must
-match byte for byte. Partial npm/GitHub/GHCR success is possible and cannot be
-made atomic. Fix registry identity/settings where appropriate and resume the
-original run. A source change requires a new version and tag. Never delete,
-recreate, move or force-push version tags.
-
-These recovery changes apply to releases made with the new workflows. They cannot
-change the immutable workflow source at `0.4.0-alpha.3` or repair that historical
-run by rerunning it. The missing-artifact behavior observed there is recorded in
-[issue #223](https://github.com/jimhoyd-com/urlcode/issues/223).
-
-npm uses OIDC with pinned npm 11.5.1. Alpha versions use npm/GHCR `alpha`, and
-GitHub prerelease classification with `--latest=false`. Existing `latest`
-pointers are not promoted by this flow. Core GHCR publication remains conditional
-on `PUBLISH_CONTAINER=true`; its existing version/channel identity guards remain.
-Historical GHCR verification is still a separate follow-up. Digest promotion of a
-tested image is design only, in [CONTAINER-PROMOTION.md](CONTAINER-PROMOTION.md);
-the publisher still builds from source.
-
-The [Immutable release tags rule](https://github.com/jimhoyd-com/urlcode/rules/23712319)
-blocks updates/deletions of `v*` and `@jimhoyd/urlcode-*@*`, permits creation, and
-has no bypass actors. Main protection is unchanged. Source and artifact checks
-are not an independent security assessment, provider deployment or recovery
-proof. The next explicitly authorized new release must exercise the complete
-new promotion/recovery path. Progress and remaining work are recorded in
-[issue #185](https://github.com/jimhoyd-com/urlcode/issues/185).
-
-### Windows fixture cleanup
-
-Auth/admin tests register resources with their package-local `test/cleanup.ts`.
-Cleanup runs in reverse acquisition order: close servers and SQLite services
-before deleting temporary directories, including services reopened by a test.
-Every registered callback is attempted even if another closer throws, and the
-combined error fails the test. Register each closer as soon as its resource opens.
-The suites use a five-minute test-file timeout so a stuck fixture is diagnosed
-before the CI job limit. Node applies this limit to whole test files too; the
-large auth-core file legitimately exceeds two minutes on Windows Node 22.
-Windows regression coverage runs on Node 24 for platform-sensitive PRs and
-main; nightly/manual runs cover Node 22/24/26.
-
-Failed auth service initialization also waits for its SQLite worker to terminate
-before rejecting. Callers can clean up or retry after a rejected open without
-racing a remaining database handle; configuration identity failures still fail
-closed with the same error code.

package/docs/EGRESS.md

@@ -1,125 +0,0 @@
-# Bounded proxy and webhook transport
-
-Outbound requests use a host-owned HTTPS transport. Guests do not receive a fetch
-API. Project declarations express behavior; an external operator policy, pinned
-to the complete project revision, grants exact HTTPS origins separately to proxy
-and signal operations. A configured destination never grants its own authority.
-Binding injection uses existing explicitly granted secrets, resolved before the
-host transport receives a literal header value. Never log those values.
-
-The transport resolves the destination for each request, refuses any DNS response
-containing a nonpublic address, and pins its connection lookup to one validated
-answer. HTTPS certificate and hostname verification remain enabled. There is no
-connection pool, fallback address, redirect following, or automatic retry. Private,
-loopback, link-local, documentation, multicast, IPv4-mapped IPv6 and transition
-addresses are refused. IPv6 filtering is deliberately conservative: 2001::/16,
-2002::/16 and 3fff::/16 are refused along with addresses outside ordinary global
-unicast. Network-level egress controls remain useful defense in depth.
-
-Default limits per client are 16 simultaneous requests, five seconds including
-DNS, 1 MiB request and response bodies and 16 KiB headers. Excess concurrency is
-refused immediately. Requests use bounded buffering rather than streaming. Abort
-and shutdown destroy active HTTP requests; unresolved system DNS operations may
-finish in the background but cannot open a socket after cancellation. Those DNS
-operations retain a separate concurrency slot until they settle, so repeatedly
-timing out DNS cannot create an unbounded underlying lookup backlog. A shared
-64-operation DNS cap also spans all client instances and runtime reloads in the
-host Node isolate; closing a client does not release an unresolved DNS slot. Closing a
-client refuses future requests and drains its bounded outstanding promises.
-Errors carry only a fixed category, never a destination, request, header or secret.
-
-Proxy destinations have a literal HTTPS authority. Path placeholders are encoded
-as individual components; dot-segment values are refused. Query names and incoming
-and outgoing headers require explicit selection. Host, framing, hop-by-hop and
-proxy-authorization headers cannot be supplied. Ambient authorization, cookies,
-forwarding metadata (the entire `x-forwarded-*` family) and Set-Cookie cannot be selected. Explicit host-resolved
-Authorization injection is supported. Set-Cookie forwarding is deliberately
-unsupported because multiple cookie fields cannot safely be represented by the
-portable scalar header contract. Upstream redirects are returned as responses;
-Location is forwarded only if explicitly selected and is never fetched. Headers
-nominated by an incoming or upstream Connection field are removed even if selected.
-Header names are normalized to lowercase; array-valued upstream fields are omitted.
-An encoded request body requires explicitly selecting its Content-Encoding
-header; literal header injection cannot change or replace that coding. Bodies
-remain raw bytes, including content encoding; select Content-Encoding when
-forwarding compressed responses. No transparent decompression occurs.
-
-Webhook signals are best effort. The broker schedules work after the caller's
-synchronous emit operation, with eight concurrent deliveries by default and no
-queue. Saturation and closed brokers drop new events. Each event contains only
-version, declared route pattern, status and method: never the actual request URL,
-parameters, body, client identity, incoming headers or bindings. The webhook
-receives a POST with JSON. Only 2xx responses count as delivered; all other status
-codes and transport failures count as failed. Delivery order is unspecified,
-there are no retries or durability guarantees, and shutdown aborts outstanding
-work and awaits settlement. Counter snapshots report accepted, delivered, failed
-and dropped events without including destination data. Applications must not use
-these signals for guaranteed billing, audit retention or job execution.
-
-The transport is a new security-sensitive host bridge. Unit tests and CI are not
-an independent assessment or proof of hostile multi-tenant readiness. Public
-provider network deployments require separate operator-owned fixtures and evidence.
-
-## Project declarations and external grants
-
-```yaml
-version: "1"
-routes:
-  /items/{id}:
-    proxy:
-      url: https://api.example.com/items/{id}
-      query: [page]
-      requestHeaders: [accept]
-      responseHeaders: [content-type, content-encoding]
-      headers:
-        authorization: {secret: API_TOKEN}
-    parameters:
-      - {name: id, in: path, required: true, schema: {type: string}}
-    secrets:
-      API_TOKEN: {secret: UPSTREAM_AUTHORIZATION}
-    signals:
-      - url: https://hooks.example.com/events
-```
-
-An injected secret is the complete header value (for example an operator-provided
-Bearer value); interpolation and ambient credentials are not supported. Each
-proxy placeholder must name a declared string path parameter. Proxy routes refuse
-middleware in this initial implementation: middleware cannot safely authorize an
-already materialized upstream request. Use host request policies before egress.
-Proxy routes require cache disabled or `no-store`; explicit cache declarations
-cannot override this. Responses always remove CDN cache directives and receive
-`Cache-Control: no-store`. Compressed upstream bytes are refused if their
-Content-Encoding field was not explicitly selected; it cannot be overridden by
-route response headers.
-
-The external version-1 policy has the existing `projectSha256` and route grants:
-
-```json
-{"version":1,"projectSha256":"<reviewed revision hash>","routes":{"/items/{id}":{"secrets":["UPSTREAM_AUTHORIZATION"],"egress":{"proxy":["https://api.example.com"],"signals":["https://hooks.example.com"]}}}}
-```
-
-Use `permissions` to generate requested grants for review. Exact origin strings
-omit a trailing slash and the default 443 port. Nondefault ports are explicit.
-Proxy and signal purposes are independent even when they share an origin. Every
-route's grant is checked against the current revision before credentials, assets,
-workers or network clients are activated. Each runtime shares one bounded proxy
-client and one bounded signal client, with at most 64 origins per purpose.
-
-Signals emit when route execution and response policies produce a result,
-including guest middleware responses and returned error status codes. Thrown
-handler errors and host request-policy/plugin short circuits (including cache
-hits) do not emit. HEAD requests and generated readiness probes do not emit.
-The response never waits for webhook delivery. Counter events contain only
-accepted/delivered/failed/dropped outcomes and counts and are exposed through
-runtime metrics and the Prometheus `signals_total` series. A closed runtime stops
-new requests, aborts egress and drains bounded pending work. Client disconnects
-are not currently propagated into the runtime transport; the five-second deadline
-still applies. All non-self-hosted targets currently refuse proxy and signals.
-See the [executable example](../examples/egress/README.md).
-
-Revision hashes also include declared project policies, profiles and site
-configuration. Changing an inherited pre-egress restriction invalidates grants
-just like changing a route or function source. Projects with these declarations
-must regenerate and review their operator policy after upgrading to this hash
-coverage; an old grant is intentionally refused rather than silently retaining
-network authority under changed behavior.