@jimhoyd/urlcode 0.4.2 → 0.4.7

package/docs/VERCEL.md

@@ -1,114 +0,0 @@
-# Deploying to Vercel
-
-The Vercel adapter runs a URLCode project as a Node function. The same
-`urlcode.yaml` that runs locally or in a container serves the deployment —
-that is the point of the project format.
-
-**This adapter serves native handlers only:** redirects, validated responses,
-pages, static assets and downloads. `function` and `middleware` routes are
-refused at activation, trusted or sandboxed alike, not per request, so a deployment cannot
-half-work, and that is a settled position rather than a pending limitation. See
-[what is not supported](#what-this-adapter-does-not-do).
-
-A working project is in [`examples/vercel/`](../examples/vercel/).
-
-## Set it up
-
-```js
-// api/index.js
-import { createVercelHandler } from '@jimhoyd/urlcode/vercel';
-
-export default createVercelHandler({ project: process.cwd() });
-```
-
-```json
-{
-  "functions": {
-    "api/index.js": {
-      "runtime": "nodejs22.x",
-      "includeFiles": "{urlcode.yaml,routes/**,public/**}"
-    }
-  },
-  "rewrites": [{ "source": "/(.*)", "destination": "/api" }]
-}
-```
-
-Two details decide whether this works:
-
-- **`includeFiles`** must cover every file the project reads: the entry YAML,
-  any `includes`, and every page, download and static directory. They are read
-  at activation, so a missing one fails the whole deployment rather than one
-  route. Node 22.13 or newer is required.
-- **The rewrite** sends every path to the handler, because URLCode owns routing.
-  Anything you leave outside it is served by Vercel, not by your project.
-
-## Bindings
-
-A self-hosted deployment grants `env` and `secrets` through an operator policy
-file outside the project. Vercel has no such place, so the adapter reads the
-same document from the **`URLCODE_POLICY`** environment variable:
-
-```sh
-urlcode permissions --project .        # prints the grant document
-vercel env add URLCODE_POLICY          # paste it
-```
-
-It is validated exactly as the file is, including the `projectSha256` pin — so a
-policy issued for one revision does not activate another. Change a route or a
-binding and the grant must be reissued, which is the intended friction. The
-values themselves are ordinary Vercel environment variables; the policy decides
-which routes may read them.
-
-## Origin
-
-Functions and absolute URLs see the origin the adapter resolves, in order:
-the `origin` option, `URLCODE_ORIGIN`, then Vercel's own
-`VERCEL_PROJECT_PRODUCTION_URL`, `VERCEL_URL` or `VERCEL_BRANCH_URL`. Those are
-platform-set, not client-supplied — forwarded headers stay untrusted here as
-everywhere else. Set `URLCODE_ORIGIN` explicitly when you serve a custom domain
-and want it in generated URLs.
-
-## What this adapter does not do
-
-| Not supported | Why |
-|---|---|
-| `function` routes | They need the self-hosted Node lifecycle; a `sandbox: true` route would additionally spawn worker threads and load the WASM engine on every cold start. Correctness is not the issue; the execution model is — per-route compilation was considered and declined. |
-| Middleware | Runs in the same execution mode as the route's function, and is refused with it. |
-| `urlcode serve` operational endpoints | `/_urlcode/health` and `/_urlcode/ready` describe a long-lived process. Use Vercel's own observability. |
-
-Each refusal happens at activation with a message naming the route, so you find
-out on deploy rather than on a request.
-
-`function` and `middleware` are not coming to this adapter. The supported answer
-is to deploy the project as one trusted Node process — a container or a VM
-running the project as it runs locally — which supports every route type today,
-on any host you like including AWS (ECS, EC2, App Runner). See
-[the decision](OPEN-DECISIONS.md#accepted-one-node-deployment-per-project) and
-[the analysis behind it](archive/2026-09-19/SPIKE-LAMBDA-COMPILE.md).
-
-## Operating it
-
-Every instance activates the project independently: parsing YAML, snapshotting
-assets and compiling routes on each cold start. Keep asset snapshots small — the
-[capacity limits](CAPACITY.md) apply per instance, and a 64 MiB snapshot is 64
-MiB in every concurrent instance.
-
-There is no reload: a deployment serves the revision it was built from, which is
-what you want from immutable deployments. Ship a change by deploying.
-
-Logs go to Vercel's collector rather than to a stdout stream you control, so the
-[monitoring recipes](MONITORING.md) that parse JSON records need adapting;
-the record fields are the same.
-
-## Verification status
-
-The adapter is tested against the self-hosted runtime for byte-identical status,
-body and headers across redirects, parameters, responses, pages, static files
-and misses, and for refusing unsupported handlers, enforcing the policy pin and
-bounding request bodies.
-
-**It has not been deployed to Vercel.** Those tests drive the real handler over
-a real Node request, which is the shape Vercel invokes, but no run on the
-platform has happened. Treat `includeFiles` coverage, cold-start latency and
-custom-domain behaviour as unverified until you deploy the example and see it
-work.

package/docs/VERSION-ALIGNMENT.md

@@ -1,88 +0,0 @@
-# Package and channel alignment
-
-The package manifests and root lockfile are the version authority. Read live
-registry and Git tag state with `npm run release:status`; do not maintain a
-second table of changing version numbers in documentation.
-
-| Package | Manifest | Version owner | Release tag |
-| --- | --- | --- | --- |
-| `@jimhoyd/urlcode` | `package.json` | Explicit core release PR | `v<version>` |
-| `@jimhoyd/urlcode-ui` | `packages/ui/package.json` | Changesets | `@jimhoyd/urlcode-ui@<version>` |
-| `@jimhoyd/urlcode-auth` | `packages/auth/package.json` | Changesets | `@jimhoyd/urlcode-auth@<version>` |
-| `@jimhoyd/urlcode-admin` | `packages/admin/package.json` | Changesets | `@jimhoyd/urlcode-admin@<version>` |
-
-Development uses workspace source. Auth and admin's `file:../..` development
-links resolve core to this checkout, enforced by `check-workspace-links.ts`.
-Core never imports extension packages. Release verification instead installs the
-published lower bound of each declared peer range and checks resolution. A peer
-floor rises when code requires a newly introduced API, not just because a sibling
-published another version. Preserve the declared upper bound during Changesets
-versioning; `.changeset/config.json` limits unnecessary peer rewrites.
-
-Publishable workspace changes carry Changesets; the release PR applies them and
-updates versions, changelogs and the lockfile together. Core stays an explicit
-entry in that PR until a separately reviewed workspace migration. Its CLI banner
-must match its manifest. `npm run release:check` rejects stale lockfile versions.
-Unreleased source changes do not require moving a published tag or pretending a
-new package has already shipped.
-
-Manual GitHub Actions releases can select `core`, `ui`, `auth`, `admin`, or
-`all`. A single-package release updates only that package's manifest, lock entry,
-changelog and relevant Changesets; core also owns its duplicated CLI/MCP/plugin
-version metadata and downstream starter update. The all-packages action aligns
-every manifest and advances internal peer floors together. Changesets that name
-packages across the selected boundary must be released together rather than
-partially consumed.
-
-The `0.4.1` release is an explicit stable release decision for core, UI, auth
-and admin. Publication moves each package's npm `latest` channel to `0.4.1`, in
-core → UI → auth → admin order, after its release checks pass. A prepared
-manifest or merged release PR does not prove registry publication: use
-`npm run release:status` to inspect the live result before installing the set.
-This alignment does not permanently couple package versions; subsequent
-releases can still select only the packages that changed.
-
-Alpha releases publish under `alpha`; they never automatically move npm
-`latest`. Stable publication does not move `alpha`, so the two channels can
-legitimately show different versions. Test the install combination you recommend
-against peer ranges. `release:status` reports each declared peer floor and
-whether its current `latest` and `alpha` satisfy the range.
-
-After all four `0.4.1` versions are published, install the aligned set with:
-
-```sh
-npm install --save-exact @jimhoyd/urlcode@0.4.1 @jimhoyd/urlcode-ui@0.4.1 @jimhoyd/urlcode-auth@0.4.1 @jimhoyd/urlcode-admin@0.4.1
-```
-
-Bare package names resolve npm's current `latest`; exact application pins and a
-committed lockfile keep an existing application from changing on a new release.
-
-## Generated applications
-
-A generated application records its own versions. `urlcode init --with` writes a
-`package.json` pinning the running runtime, the named extensions and their
-declared peers at the exact versions resolved at generation time, after checking
-that set against every declared peer range; `urlcode init --manifest` does the
-same for a route-only project with the runtime alone; `urlcode-auth init` pins
-this package and its peers. Plain `urlcode init` stays route-only and writes no
-manifest, for projects whose runtime is managed elsewhere. Generation never runs
-a package manager: `package-lock.json` exists only after the operator runs
-`npm install` in the generated directory, and a pin taken from a local path or
-tarball reproduces only where that path exists.
-
-No upgrade command exists. A generated project moves to new versions by an
-operator editing its manifest and re-installing. The issue that asked for this
-(#212) describes a future command that would choose a tested compatible set,
-show the changes and require explicit alpha selection; nothing here implements
-that, and the pins above are only the groundwork it would need.
-
-The standalone `urlcode-template` is an external exact-version consumer: after a
-runtime release, update its dependency and starter through its own reviewed PR.
-The coordinator prepares and checks that PR after registry installation succeeds;
-the template is a consumer update, not a fifth npm package. The retired
-`urlcode-docs`, `urlcode-middleware`, `urlcode-dynamic-link` and `urlcode-short`
-repositories are not release targets.
-
-See [the development pipeline](DEVELOPMENT-PIPELINE.md) for preparation,
-publication order, immutable retries and credential scope, and
-[release security](RELEASE-SECURITY.md) for provenance and limitations.

package/docs/YAML-GUIDE.md

@@ -1,57 +0,0 @@
-# YAML guide and recipe book
-
-This guide targets URLCode 0.3.0. Start with the function example below,
-then add only the fields your route needs. The authoritative machine-readable
-shape is [JSON Schema](../schemas/urlcode.schema.json); semantic rules are in the
-[specification](SPECIFICATION.md). Unsupported fields fail validation.
-
-## Run all the examples
-
-The [cookbook project](../examples/cookbook/urlcode.yaml) includes the six stateless handler
-types, middleware, typed/defaulted inputs, methods, response headers, body checks,
-expiry and file organization. Its referenced JavaScript and assets are included.
-From the runtime checkout:
-
-```sh
-npm ci
-node src/cli.ts validate --project examples/cookbook
-node src/cli.ts test --project examples/cookbook
-node src/cli.ts audit --project examples/cookbook --expect-routes 40
-node src/cli.ts dev --project examples/cookbook
-```
-
-The cookbook is a larger learning project. The normal `urlcode init ../my-links`
-remains a small two-route starter. For an independent application with a pinned
-runtime dependency, clone [urlcode-template](https://github.com/jimhoyd-com/urlcode-template).
-
-## Pages
-
-Each page holds the recipes for one task; the section numbers continue across pages.
-
-| Page | Sections |
-|---|---|
-| [Functions, inputs and methods](yaml/functions.md) | 1. A URL that runs code; 4. Input types and constraints; 5. Methods and body validation; 6. All function argument sources |
-| [Redirects](yaml/redirects.md) | 2. Ordinary and permanent redirects; 3. Parameterized redirects and explicit query forwarding |
-| [Middleware](yaml/middleware.md) | 7. Middleware before and after a handler |
-| [Declared responses, headers and cookies](yaml/responses.md) | 8. Native responses, headers and cookies; 9. Explicit OPTIONS response (not automatic CORS) |
-| [Pages, static folders and downloads](yaml/assets.md) | 10. Pages, static folders, downloads and MIME |
-| [Enable, disable and expire](yaml/conditions.md) | 11. Enable, disable and expire |
-| [Bindings, split files and tests](yaml/organization.md) | 12. Environment and secret references; 13. Split files and folders; 14. Assert inputs and outputs |
-| [Policies and profiles](yaml/policies.md) | 16. Hardened profile and per-route overrides |
-| [Site conventions](yaml/site.md) | 17. Site conventions |
-
-## Common mistakes
-
-| Mistake | Correction |
-|---|---|
-| Two handlers on one route | Choose exactly one; put reusable logic in middleware |
-| `/r/:id`, `/r/{id:.*}` or a regex | Use `/r/{id}` plus a required path input; no regex/greedy matching |
-| `${TOKEN}` or `process.env` | Use declared binding references and an external operator grant |
-| `fetch`, npm or Node imports | Unsupported in the guest; do not claim a network/storage integration |
-| Asset MIME/header overrides in `response.headers` | Configure `contentType`, `cacheControl`, `filename` on the asset handler |
-| `methods: [GET]` expecting HEAD | Declare HEAD too or omit methods for default GET/HEAD |
-| YAML fields for rate limits/workers/DNS/TLS | Deployment controls live outside portable route YAML |
-| YAML aliases, anchors or implicit date objects | Use plain JSON-compatible YAML and quoted timestamps |
-| Automatic hot updates in `serve` | Deploy/restart or use the embedding reload API deliberately |
-| “All examples are production-ready” | Validate your security, load and deployment requirements separately |
-