@jimhoyd/urlcode 0.3.0 → 0.4.0-alpha.2

package/docs/USABILITY-REVIEW.md

@@ -0,0 +1,129 @@
+# Usability review: URLCode against the tools people reach for instead
+
+Status: an honest assessment written 2026-09-18 against the source in the four
+repositories at that date. It is opinion grounded in the code and docs, not a
+benchmark. Its purpose is to name the friction a first-time user or an AI
+agent meets, compare it with what competing tools do, and rank the changes
+that would matter most. It does not change any contract by itself.
+
+> **Update:** written the day before `0.4.0-alpha.2` reversed the default
+> execution mode. Where the table below credits functions and middleware with
+> isolation, that now describes a route declaring `sandbox: true`; the default
+> is trusted, in-process execution with full Node, npm and filesystem access.
+> See [SPIKE-DEFAULT-TRUST-MODEL.md](SPIKE-DEFAULT-TRUST-MODEL.md).
+
+## 1. Who the competitors are, by rung
+
+URLCode is not one product; it competes with a different tool on each rung
+of [the ladder](FRAMEWORK.md#the-ladder).
+
+| Rung | What people use today | Where URLCode is better | Where it is worse today |
+|---|---|---|---|
+| Redirects, responses | Netlify `_redirects`, Cloudflare `_redirects`/Rules, Vercel `vercel.json`, nginx | One portable file that validates before deploy, tests with fixtures, counts routes, converts from those formats and refuses lossy conversions | Those files are two columns; `urlcode.yaml` needs `version`, a route key and a handler object. Nobody needs a validator for ten redirects |
+| Pages, files | Any static host, Astro, Hugo | Same file, no build step, native ranges/ETags, `site` conventions | No content pipeline, no templating for pages outside the extension kit |
+| Functions, middleware | Cloudflare Workers, Vercel Functions, Hono, Express | Real isolation with a fresh heap per call; typed args from YAML; secrets only by revision-pinned grant; runs the same on a laptop | No `fetch`, no timers, no streaming, no npm packages in guests. Every framework above lets you call an API from a function; here you declare a `proxy` or stop |
+| Live links | Bitly, Dub, Short.io, a Postgres table | Records without reloads, versioned writes, private management API, no account system to run | Single host SQLite that needs a patched Node build; no dashboard until you install admin |
+| Accounts | Clerk, Auth0, Auth.js, Better Auth, Lucia, Supabase Auth, Devise | Everything is operator-owned and reviewable: no vendor, no callback URLs on someone else's dashboard, no per-MAU bill; passkeys, OIDC, TOTP, recovery and an account page in one package | Install is a reviewed-tarball ritual, a host file, a SHA-256 pin and a JSON-on-stdin bootstrap. Clerk is `npm i` and one env var. Better Auth is a config object and a CLI migration |
+| Administration | Django admin, Rails Administrate, Retool, Forest Admin, Supabase Studio | Built on the same service with two-person cases and audited reveal, which none of the generic admins give you | Only manages auth's entities; there is no way to expose the project's own data. Django admin is one line per model |
+| Full app in one place | Rails, Django, Laravel, Next.js + Clerk + Prisma, Supabase | The whole thing is declarative and portable; an agent can generate and validate it without a build; the trust boundary between generated code and the operator is explicit | Everything that is not a route, a function or an account is out of scope: no data model, no ORM, no forms for your own tables, no client bundle, no email templates for your app |
+
+The honest summary: URLCode wins on portability, validation, isolation and
+operator ownership, and loses on the first fifteen minutes and on anything
+that needs application data.
+
+## 2. The first fifteen minutes
+
+What a new person does today, compared with the fastest competitor at each
+step. Times are what the docs imply, not measurements.
+
+| Step | URLCode today | Fastest competitor | Gap |
+|---|---|---|---|
+| Install | `npm i -g @jimhoyd/urlcode` or brew or a checksum script; three channels documented at equal weight | `npx create-next-app` | Too many equal choices on the first screen. Pick one, put the rest in the install guide |
+| First project | `urlcode init` writes a function route, a redirect and fixtures | `wrangler init` | Equal |
+| First redirect | 5 lines of YAML for one redirect | 1 line in `_redirects` | Acceptable once, heavy for 200. `bulk-import` exists but a person starting small never learns it |
+| First function | Must know: `parameters` with `schema`, `args` with `from: path`, the Request/Response subset, that `fetch` is absent | Hono: `app.get('/x', c => c.json(...))` | The typed-args design is right but needs a two-line minimal form. Today the smallest function route is 10 lines |
+| Add accounts | Clone two private repos, build tarballs with `pack-sources.mjs --core --auth --ui --admin --core-revision SHA`, install four tarballs, `urlcode-auth init`, compute `inspectExtensionRevision`, paste the SHA into an env var, `bootstrap` with JSON on stdin, `serve --host-file --origin` | Clerk: `npm i @clerk/nextjs`, one env var, wrap the app | This is the largest gap in the framework. Most of it is a consequence of the packages being unpublished and of the revision pin, and it is the step the README leads with |
+| Add admin | `urlcode-admin init` writes everything | Django `admin.site.register(Model)` | Comparable once installed |
+| Deploy | Container, Node process, or an adapter that refuses functions, links and extensions | `vercel deploy` | The refusals are correct but the person learns them at deploy time. `urlcode capabilities` exists and is not in the quick start |
+
+## 3. What an AI agent meets
+
+The framework's claim is that an agent should build from a handful of
+redirects to a full application without rebuilding the core. Measured
+against that claim:
+
+- **Strong:** one JSON Schema, a generated field reference, fixtures the agent
+  must write, `validate`, `test` and `audit` that give exact failures with the
+  route named, an MCP server for read-only inspection, and a capability
+  matrix that lists what does not exist. Few frameworks tell an agent what it
+  cannot do. This is the right foundation.
+- **Weak:** the documentation was organized by feature history rather than by
+  task. Before this review, `llms.txt` listed 40 documents at equal weight,
+  three of them status logs, and the README opened with release history and
+  "unreleased source" caveats. An agent reading it spent its context on
+  provenance rather than on the shape of a project. The framework page and the
+  reorganized index in this change address that; the remaining cost is the
+  size of the reference documents themselves (the YAML guide, policies and
+  dynamic links are each over 400 lines).
+- **Missing:** an agent cannot yet discover the extension packages' YAML from
+  the core schema. `extensions.auth.config` is validated by auth's schema at
+  activation, but there is no way to ask the installed runtime "what config
+  does `auth` accept" without the host file. A `urlcode extensions --schema`
+  command that reads the host file and prints each extension's configuration
+  and policy schemas would close this, and would let `urlcode mcp` serve them.
+- **Missing:** no single command creates the whole layered project. Today it
+  is `urlcode init`, then `urlcode-auth init`, then `urlcode-admin init`, each
+  with its own directory conventions. One `urlcode init --with auth,admin`
+  that delegates to the installed extension packages' scaffolds would make
+  the ladder real for an agent.
+
+## 4. Ranked recommendations
+
+Ordered by how much each would change the experience per unit of work, and
+whether it touches a contract.
+
+1. **Publish the three extension packages** (even as `0.1.0-alpha` with the
+   caveats their status files carry). Every install step in section 2's
+   "add accounts" row except the revision pin existed because they were
+   unpublished. This was a decision, not code; the repositories already had
+   the release checks. No contract change. Done 2026-09-18: all three are on
+   npm as `0.1.0-alpha.x` (review still pending, issue 58).
+2. **`urlcode init --with auth,admin,ui`.** Delegate to each installed
+   package's existing scaffold; write one host file and one README. No contract
+   change; a CLI addition in core that calls into optional peers.
+3. **Print extension schemas.** `urlcode extensions --host-file … --json`
+   listing each registered extension's name, version, configuration schema and
+   policy schema, and expose it through `urlcode mcp`. No contract change.
+4. **A short form for the common function route.** Allow `function:
+   functions/hello.mjs` as a string with path parameters inferred as required
+   strings of bounded length, expanding to today's long form. This is a schema
+   addition (`version: "1"` stays valid) and the single largest cut in YAML
+   for first-time users and agents. Needs the usual generated-reference and
+   cookbook updates.
+5. **Lead the README with the ladder, not the release history.** Done in this
+   change; keep it that way. Move status caveats to the readiness register.
+6. **One install channel on the first screen.** npm first; brew, script and
+   container in the install guide.
+7. **Fold the `presentation`/`ui` split.** Auth and admin still render through
+   the primitives while the kit is the documented way to restyle. Finishing
+   kit adoption (already listed in the ui status file) removes the one place
+   where the framework's story and its code differ.
+8. **Later, and a real contract question:** application data. The thing every
+   competitor on the last rung has and URLCode does not is a place for the
+   project's own records with an admin view. The runtime already has one
+   bounded store (links) and one admin surface (auth's entities). Whether a
+   declared `collection` handler with operator-owned SQLite and an admin
+   registration belongs in the framework is the next spike worth writing.
+   Without it, "full-fledged application" means "site with accounts".
+
+## 5. What is fine and should stay
+
+- The operator host file. It is the reason the project can be untrusted and
+  portable at the same time; Clerk's convenience is bought with a vendor in
+  the loop. Keep the boundary, make the file generated.
+- The revision pin. It is unusual and it is what makes "an agent changed the
+  YAML" a reviewable event rather than a silent grant. Keep it, print it
+  loudly, and make `init` write it.
+- Refusing instead of degrading on every target. The failure names the route.
+- The capability matrix in the AI guide. Extend it to the extension packages
+  rather than softening it.

package/docs/VERCEL.md

@@ -5,8 +5,8 @@ The Vercel adapter runs a URLCode project as a Node function. The same
 that is the point of the project format.
 
 **This adapter serves native handlers only:** redirects, validated responses,
-pages, static assets and downloads. Isolated functions, middleware and stored
-live links are refused at activation, not per request, so a deployment cannot
+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. See [what is not supported](#what-this-adapter-does-not-do).
 
 A working project is in [`examples/vercel/`](../examples/vercel/).
@@ -71,9 +71,8 @@ and want it in generated URLs.
 
 | Not supported | Why |
 |---|---|
-| Isolated functions | Every cold start would spawn worker threads and load the WASM engine. Correctness is not the issue; predictable latency is, and it is unmeasured. |
-| Middleware | Runs in the same sandbox as functions. |
-| Stored live links | SQLite needs a durable writable file. A serverless filesystem is ephemeral and per-instance, so records would silently diverge between instances. |
+| `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; predictable latency is, and it is unmeasured. |
+| 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

package/docs/VERSION-ALIGNMENT.md

@@ -0,0 +1,205 @@
+# Core version alignment across repositories
+
+Which core version each downstream package supports, how it says so, and the
+order in which a core behavior change reaches downstream repositories. This
+page is a mechanism and an invariant, not a schedule: it states no release
+cadence, no LTS line and no support window. Those are not decided.
+
+It exists because "the current core" had come to mean five different things at
+once, and one of them did not resolve. The `0.4.0-alpha.2` release closes that;
+the table below is where every repository lands, and it is the register to
+change whenever a version changes anywhere.
+
+| Repository | How it names core | Value (read from its own `package.json`/`peers.json`) |
+|---|---|---|
+| `urlcode` | source version | `0.4.0-alpha.2` |
+| `urlcode-auth`, `urlcode-admin` | peer range plus a reviewed SHA | `>=0.4.0-alpha.1 <0.5.0`; `peers.json` `urlcode` = `d5e86017e93b96ec24bfdbf840692b95fc323151` in both |
+| `urlcode-dynamic-link` | peer range | `>=0.4.0-alpha.1 <0.5.0` |
+| `urlcode-middleware` | peer range | `>=0.4.0-alpha.2 <0.5.0` |
+| `urlcode-short`, `urlcode-template`, `urlcode-docs` | exact dependency pin | `0.4.0-alpha.2` |
+
+Only `urlcode-middleware` requires `0.4.0-alpha.2` specifically: it uses the
+`middleware()` extension hook, `ExtensionActivation.root` and
+`RuntimeExtension.cacheSensitive`, none of which exist in `0.4.0-alpha.1`. The
+other extension packages work against either alpha and keep the wider floor,
+which is what the supported-floor definition below requires of them.
+
+The npm dist-tags for `@jimhoyd/urlcode` are `latest` = `0.3.0` and `alpha` =
+`0.4.0-alpha.2`. `latest` deliberately stays on the `0.3.0` Apache-2.0
+self-hosted baseline: the `0.4.0` line is a prerelease and must not become the
+default install. Every release workflow derives its dist-tag from the version
+rather than defaulting, so a prerelease can only publish under `alpha`.
+
+The sibling packages are `@jimhoyd/urlcode-ui` `0.1.0-alpha.5`,
+`@jimhoyd/urlcode-auth` and `@jimhoyd/urlcode-admin` `0.1.0-alpha.3`, and
+`@jimhoyd/urlcode-dynamic-link`, `@jimhoyd/urlcode-middleware` and
+`@jimhoyd/urlcode-short` `0.1.0-alpha.2`. For the extension line, `latest` and
+`alpha` point at the same version — see the second invariant below.
+
+Every one of those is a new version in this release. Each package's previous
+release sat at the same version number as a source tree that had moved well
+past it — 43 merged commits in `urlcode-auth`, 40 in `urlcode-ui`, 28 in
+`urlcode-admin` — so the published version number identified nothing. A
+version number that does not change when the source does is the same class of
+defect as a peer range that cannot resolve, and the rule is the same: change
+the version in the pull request that changes the source.
+
+## The supported floor
+
+The supported core floor for an extension package is the **lowest core version
+published to npm that contains every core API the extension calls**. It is a
+property of the code, not of a calendar: raise it when the extension starts
+using a core API that older published cores do not have, and not otherwise.
+
+Everything below follows from that one definition.
+
+## How a package expresses its core requirement
+
+Three forms are in use. They are not interchangeable.
+
+**Peer range (`peerDependencies`), for an extension package.** An extension is
+installed alongside core by the operator, so it must not carry its own copy;
+`peerDependencies` is the correct field. Write it as a floor plus the next
+breaking bound — `">=<floor> <0.5.0"` — where the floor is the supported floor
+above. `urlcode-auth` and `urlcode-admin` use this form.
+
+**Exact pin (`dependencies`), for an application or a starter.** A project that
+is deployed or cloned rather than composed — `urlcode-short`, `urlcode-template`,
+`urlcode-docs` — depends on one core version and pins it exactly. This is the
+right form when the repository's tests, generated files and documentation were
+all produced against one runtime and are only claimed to hold for that runtime.
+
+**Reviewed SHA (`peers.json`), for source CI on top of a range.** A reviewed
+commit is not a substitute for the peer range; it is an addition to it, used
+where the repository must build and test against an exact reviewed core
+checkout rather than whatever the registry resolves. `urlcode-auth` and
+`urlcode-admin` each keep one `peers.json` naming the reviewed core commit;
+each file states in its own `$comment` that published releases do not use those
+SHAs and resolve peers from the registry by the `package.json` range instead.
+Use a reviewed SHA when source CI needs reproducibility; do not use it to
+express what an installing operator will get.
+
+## The invariant: a published peer range must be satisfiable
+
+**A package published to npm must never declare a peer range that no published
+core version satisfies.** At publish time, at least one version on the registry
+must fall inside the range. A range that points at an unpublished core is not a
+forward-looking declaration — it is an install failure for everyone who takes
+the package from the registry.
+
+The worked example came from this project. `@jimhoyd/urlcode-middleware`
+`0.1.0-alpha.1` was published declaring `peerDependencies`
+`{"@jimhoyd/urlcode": ">=0.4.0-alpha.2"}` at a time when the registry held only
+`0.3.0` and `0.4.0-alpha.1`, so nothing satisfied it. The range was correct —
+the package genuinely needs APIs that first appear in `0.4.0-alpha.2` — so the
+fix was never to widen the range. The publication order was wrong: the package
+was published before the core it requires, and it could be installed only from
+source against a vendored core tarball carried for exactly that reason.
+
+Publishing core `0.4.0-alpha.2` resolves it without any change to the already
+published package: the range becomes satisfiable the moment core is on the
+registry. The vendored tarball and the source-only install path go away with
+it.
+
+That is what the invariant prevents, and it is the only ordering rule that
+cannot be relaxed.
+
+## The second invariant: `latest` must not fall below a sibling's floor
+
+**Where a package line publishes under a prerelease dist-tag, `latest` must
+still resolve to a version that satisfies every peer floor its siblings
+declare.** `latest` is what a plain `npm install <package>` resolves, so a
+`latest` left behind hands the installing operator a build that another
+package in the same install refuses.
+
+The worked example, again live in this project: `@jimhoyd/urlcode-auth`
+published `alpha` = `0.1.0-alpha.2` while leaving `latest` = `0.1.0-alpha.1`.
+`@jimhoyd/urlcode-admin` declares a peer floor of `>=0.1.0-alpha.2` on auth, so
+`npm install @jimhoyd/urlcode-auth` resolved a build below the floor admin
+requires. Nothing in the source is wrong; the dist-tag is.
+
+The fix is a registry operation rather than a source change:
+
+```sh
+npm dist-tag add @jimhoyd/urlcode-auth@0.1.0-alpha.2 latest
+```
+
+Core is the deliberate exception. Its `latest` stays on `0.3.0` because no
+sibling declares a floor above it — the extension packages name core through
+`peerDependencies`, which resolve by range and never by dist-tag.
+
+## A deliberate older pin is a position, not drift
+
+`urlcode-template`, `urlcode-docs` and `urlcode-short` now all pin
+`0.4.0-alpha.2`, so no downstream repository is currently behind. An older pin
+remains a legitimate position, and the rule for it does not change: it is
+recorded where a reader will meet it. The repository's README says which core
+version it pins, and every statement about runtime behavior in that repository
+is read against that version. Where a statement is only true for the pinned version, it
+says so and names the version, rather than being silently corrected to match
+core's unreleased `main`.
+
+This matters most for the trust model. Core `0.4.0-alpha.2` runs `function` and
+`middleware` routes trusted and unsandboxed by default, with `sandbox: true` as
+a per-route opt-in ([decision record](SPIKE-DEFAULT-TRUST-MODEL.md)).
+`0.4.0-alpha.1` and earlier sandbox all such code unconditionally and have no
+`sandbox` field in the schema. This is why moving a pin to `0.4.0-alpha.2` is
+a behavior change even when no YAML changes: every `function`/`middleware`
+route that does not declare `sandbox` becomes trusted on upgrade. Review those
+routes before raising a pin, and add `sandbox: true` to the ones that handle
+input or code you would not trust with full Node/filesystem/network access.
+A repository still pinned to `0.4.0-alpha.1` or `0.3.0` that documents
+sandbox-by-default is **describing its pin correctly**. Its
+generated files — field references, schemas, scaffolding output, vendored agent
+skills — are likewise correct for that pin. Divergence from core's current
+`main` is not by itself staleness, and it is not a defect to be "fixed" by
+importing behavior the pinned runtime does not have. The same point is made
+about the advisory `npm run check:downstream-skills` report in
+[release readiness](RELEASE-READINESS.md).
+
+What is a defect: a repository that does not say which core version it pins, or
+that states pin-dependent behavior as an unconditional property of URLCode.
+
+## Order of operations when core changes behavior
+
+A core behavior change reaches downstream repositories in this order. Each step
+depends on the one before it; skipping ahead is what produced the
+`urlcode-middleware` breakage above.
+
+1. **Publish core.** The version carrying the change goes to npm first. Until it
+   is on the registry, no downstream peer range may reference it (the invariant
+   above).
+2. **Raise downstream floors.** Extension packages move their peer range floor
+   to the published version; applications and starters move their exact pin.
+   A repository that chooses to stay on the older core does nothing here — that
+   is a valid outcome, and step 3 does not apply to it.
+3. **Regenerate downstream generated files.** Field references, schemas,
+   scaffolding output and vendored agent skills are regenerated *after* the
+   floor moves, against the version now pinned — never before, or they describe
+   a runtime the repository does not depend on.
+
+Reviewed-SHA repositories take the same three steps, and additionally update
+`peers.json` to the reviewed commit for the new core when source CI is expected
+to build against it. The SHA and the published floor answer different questions
+and are updated independently.
+
+## Open: two publishing conventions
+
+The repositories publish under two different conventions, and the maintainer has
+not settled which one the project uses. Both are recorded here neutrally; this
+page does not pick one.
+
+- **Private until release.** `urlcode-dynamic-link` and `urlcode-middleware`
+  keep `"private": true` in their `package.json` on `main` and drop it in the
+  release commit. Publication is an explicit, visible act in the release diff,
+  and an accidental `npm publish` from `main` fails closed. Both packages are
+  nonetheless published on npm, so the convention has been exercised.
+- **Publishable on main.** `urlcode-auth`, `urlcode-admin` and `urlcode-ui`
+  carry no `private` field and declare `publishConfig.access = "public"`
+  instead. The committed manifest is
+  the manifest that publishes, so what is on the registry can be diffed against
+  `main` without accounting for a release-only edit.
+
+The split is currently by repository, not by package kind, and nothing records
+why. Settling it is a maintainer decision; no `package.json` is changed on the
+strength of this page.