@jimhoyd/urlcode 0.4.2 → 0.4.7

package/llms.txt

@@ -1,13 +1,14 @@
+<!-- urlcode-current-version:start -->
 # URLCode
 
 > A portable runtime for programmable URL behavior, and the framework that grows
 > from it: routes in YAML, functions and middleware, then accounts, administration and
 > stored links as operator-installed extensions. Stable project format
-> `version: "1"`. Core is Apache-2.0; this revision is `0.4.0-alpha.2`, which makes
-> `function`/`middleware` routes trusted by default with `sandbox: true` as the
-> per-route opt-in; `0.4.0-alpha.1` is the newest alpha published to npm, on top of
-> the `0.3.0` release. The auth, admin and ui extension packages are on npm as
-> `0.1.0-alpha.x`, source-complete, review pending.
+> `version: "1"`. Core is Apache-2.0; this revision is `0.4.7`. `function`/`middleware`
+> routes are trusted by default with `sandbox: true` as the per-route opt-in. The
+> auth, admin and ui extension packages in this repository are versioned at the same
+> revision; confirm what is published with `npm run release:status`.
+<!-- urlcode-current-version:end -->
 
 Use the schema and docs from the runtime revision you run. Do not assume Node
 or fetch inside a `sandbox: true` function, regex routes, database access,
@@ -26,6 +27,43 @@ extensions and recipes/templates before writing a custom function or middleware.
 Keep necessary custom code focused and report the capability gap; never invent
 fields or bypass target limits or operator grants. See [the design principle](docs/PROJECT-DIRECTION.md#design-principle-declarative-first).
 
+## Need X? Use this built-in first
+
+Route a task to the feature before writing code. Every row is off unless declared.
+
+| I need | Use | Where |
+|---|---|---|
+| Security headers (CSP, HSTS, nosniff, frame and referrer policy) | `policies.security` (`headers: oshp`, or `profile: hardened`) | [security](docs/policies/security.md), [policies](docs/POLICIES.md) |
+| Cache headers for a page, download or static folder | `cacheControl`, exactly one of `no-cache` (default), `no-store`, `public, max-age=3600`, `public, max-age=31536000, immutable` | [assets](docs/yaml/assets.md) |
+| Cache strategy or origin cache for any route | `policies.cache` | [cache](docs/policies/cache.md) |
+| Request body size, required body, content type, JSON syntax check | `request.body` (`maxBytes`, `required`, `contentTypes`, `format`); 413/415/400 | [HTTP](docs/HTTP.md) |
+| Restrict or allow HTTP methods | `methods` (default GET/HEAD); 405 with `Allow` | [HTTP](docs/HTTP.md) |
+| Rate limiting | `policies.throttle` | [throttle](docs/policies/throttle.md) |
+| Block bots or AI crawlers | `policies.agents`; `robots` via `site` | [agents](docs/policies/agents.md), [site](docs/SITE.md) |
+| Compression | `policies.compression` | [compression](docs/policies/compression.md) |
+| Fixed JSON, text or headers with no code | `respond` and `response.headers` | [HTTP](docs/HTTP.md) |
+| robots.txt, sitemap, favicon, security.txt | top-level `site` | [site](docs/SITE.md) |
+| Sign-in, roles, protected routes | `extensions.auth`, then `auth: true` on the route | [extensions](docs/EXTENSIONS.md) |
+
+Which handler serves the response:
+
+| The response is | Handler | Recipe |
+|---|---|---|
+| Fixed text or JSON | `respond` | `health-page` |
+| A short HTML snippet | `respond` `text` plus `response.headers` `Content-Type: text/html; charset=utf-8` | `docs/HTTP.md` |
+| One HTML file | `page` | `static-page` |
+| A directory of files | `static` | `static-plus-api` |
+| An attachment | `download` | `protected-download` |
+
+Persistence: core has no storage handler, but the operator-installed store extension serves declared collections as a CRUD API; `urlcode recipes search "crud store persist"` finds the `store-crud` recipe (operator installs the package; `init --with store` is not yet available from npm, #323). Gaps to report rather than invent: a database, filtering or per-record ownership beyond that recipe, CORS, and a native link store. `urlcode context`
+prints the same pointer for the project in front of you.
+
+After a real authoring attempt, draft feedback only for a capability gap,
+repeated workaround, documentation/discovery gap or suspected defect. Include
+the runtime/target, sanitized YAML, observed validation/test evidence, expected
+behavior and a proposed fixture. Search existing URLCode issues first. Never
+publish or comment on an issue without the user's explicit approval.
+
 ## Authoring
 - [AI authoring contract](docs/AI-AUTHORING.md): workflow, capability matrix, checks.
 - [Authoring skill](.claude/skills/urlcode-authoring/SKILL.md): loadable authoring skill shipped with this revision; see [distribution](docs/AI-AUTHORING.md#agent-skills).
@@ -82,7 +120,7 @@ fields or bypass target limits or operator grants. See [the design principle](do
 
 ## Operations
 - [Operations](docs/OPERATIONS.md), [install](docs/INSTALL.md), [deployment checks](docs/DEPLOYMENT-CHECKS.md), [CI action](docs/CI.md).
-- [Readiness](docs/READINESS.md), [capacity](docs/CAPACITY.md), [performance](docs/PERFORMANCE.md), [resilience](docs/RESILIENCE.md), [observability](docs/OBSERVABILITY.md).
+- [Readiness](docs/READINESS.md), [capacity](docs/CAPACITY.md), [resilience](docs/RESILIENCE.md), [observability](docs/OBSERVABILITY.md).
 - [Vercel](docs/VERCEL.md), [AWS](docs/AWS.md), [Cloudflare](docs/CLOUDFLARE.md): adapters with local conformance tests; no provider deployment verified yet.
 - [Static hosting](docs/STATIC.md): `urlcode build --target static` compiles redirects/pages/static/downloads to S3 + CloudFront objects and redirect metadata; no server, so function/middleware/extension/proxy/signals/conditions/parameters/bindings/policies are all refused; GitHub Pages is explicitly out of scope.
 - [Release readiness](docs/RELEASE-READINESS.md), [roadmap](ROADMAP.md): what is proven, what is planned.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jimhoyd/urlcode",
-  "version": "0.4.2",
+  "version": "0.4.7",
   "description": "Portable runtime for programmable URL behavior",
   "type": "module",
   "workspaces": [
@@ -23,75 +23,59 @@
   "exports": {
     ".": {
       "types": "./dist/types/index.d.ts",
-      "development": "./src/index.ts",
       "default": "./dist/index.js"
     },
     "./aws": {
       "types": "./dist/types/aws.d.ts",
-      "development": "./src/aws.ts",
       "default": "./dist/aws.js"
     },
     "./cloudflare": {
       "types": "./dist/types/cloudflare.d.ts",
-      "development": "./src/cloudflare.ts",
       "default": "./dist/cloudflare.js"
     },
     "./prerender": {
       "types": "./dist/types/prerender.d.ts",
-      "development": "./src/prerender.ts",
       "default": "./dist/prerender.js"
     },
     "./schema": "./schemas/urlcode.schema.json",
     "./vercel": {
       "types": "./dist/types/vercel.d.ts",
-      "development": "./src/vercel.ts",
       "default": "./dist/vercel.js"
     },
     "./plugins": {
       "types": "./dist/types/plugins.d.ts",
-      "development": "./src/plugins.ts",
       "default": "./dist/plugins.js"
     },
     "./policies": {
       "types": "./dist/types/policies.d.ts",
-      "development": "./src/policies.ts",
       "default": "./dist/policies.js"
     },
     "./compliance": {
       "types": "./dist/types/compliance.d.ts",
-      "development": "./src/compliance.ts",
       "default": "./dist/compliance.js"
     },
     "./observability": {
       "types": "./dist/types/observability.d.ts",
-      "development": "./src/observability.ts",
       "default": "./dist/observability.js"
     },
     "./extensions": {
       "types": "./dist/types/extensions.d.ts",
-      "development": "./src/extensions.ts",
       "default": "./dist/extensions.js"
     },
     "./sandbox": {
       "types": "./dist/types/sandbox.d.ts",
-      "development": "./src/sandbox.ts",
       "default": "./dist/sandbox.js"
     },
     "./package.json": "./package.json"
   },
   "files": [
     ".claude",
-    ".claude-plugin",
-    "packaging/claude-plugin",
     "dist",
     "schemas",
     "data",
     "starters",
     "README.md",
-    "docs",
     "SECURITY.md",
-    "ROADMAP.md",
-    "CONTRIBUTING.md",
     "examples",
     "llms.txt",
     "llms-full.txt",
@@ -108,9 +92,9 @@
     "check:code": "node scripts/check.ts && node scripts/check-release-tags.ts && node scripts/check-workspace-links.ts && npm run release:check",
     "verify": "npm run lint && npm run typecheck && npm run check && npm run build && npm test && npm run verify:workspaces",
     "workspace:styles": "npm run styles --workspace @jimhoyd/urlcode-ui",
-    "verify:workspaces": "npm run verify --workspace @jimhoyd/urlcode-ui && npm run verify --workspace @jimhoyd/urlcode-auth && npm run verify --workspace @jimhoyd/urlcode-admin && npm run test:workspace-integration",
-    "benchmark": "node benchmarks/routing.ts",
-    "test:package": "npm run build && node scripts/package-smoke.ts",
+    "verify:workspaces": "npm run verify --workspace @jimhoyd/urlcode-ui && npm run verify --workspace @jimhoyd/urlcode-auth && npm run verify --workspace @jimhoyd/urlcode-admin && npm run verify --workspace @jimhoyd/urlcode-store && npm run audit:packages && npm run test:workspace-integration",
+    "audit:packages": "node scripts/package-audit.ts --all",
+    "test:package": "npm run build && npm run test:package:built",
     "dev": "node src/cli.ts dev --project starters/default",
     "serve": "node src/cli.ts serve --project starters/default",
     "validate": "node src/cli.ts validate --local --project starters/default",
@@ -125,13 +109,10 @@
     "docs:llms": "node scripts/build-llms-full.ts",
     "docs:cookbook-index": "node scripts/build-cookbook-index.ts",
     "check:downstream-skills": "node scripts/check-downstream-skill-drift.ts",
-    "benchmark:bulk": "node benchmarks/bulk.ts",
-    "benchmark:sandbox-vs-trusted": "node benchmarks/sandbox-vs-trusted.ts",
-    "benchmark:agent": "node benchmarks/agent/run.ts",
     "sync:agents": "node scripts/sync-agent-lists.ts",
-    "check:docs": "node scripts/check-trust-model-prose.ts && node scripts/check-local-links.ts && node scripts/check-guidance-claims.ts && node scripts/generate-yaml-reference.ts --check && node scripts/build-llms-full.ts --check && node scripts/build-cookbook-index.ts --check && node scripts/generate-claude-plugin.ts --check",
+    "check:docs": "node scripts/check-trust-model-prose.ts && node scripts/check-version-statements.ts && node scripts/check-local-links.ts && node scripts/check-guidance-claims.ts && node scripts/generate-yaml-reference.ts --check && node scripts/build-llms-full.ts --check && node scripts/build-cookbook-index.ts --check && node scripts/generate-claude-plugin.ts --check",
     "ci:plan": "node scripts/ci-plan.ts",
-    "test:package:built": "node scripts/package-smoke.ts",
+    "test:package:built": "node scripts/package-audit.ts . && node scripts/package-smoke.ts",
     "release:status": "node scripts/release.ts status",
     "release:plan": "node scripts/release.ts plan",
     "release:publish": "node scripts/release.ts publish",
@@ -154,7 +135,6 @@
     "es-module-lexer": "3.0.2",
     "mime-types": "3.0.2",
     "quickjs-emscripten": "0.32.0",
-    "typescript": "6.0.3",
     "yaml": "2.9.1"
   },
   "devDependencies": {
@@ -166,8 +146,17 @@
     "eslint": "10.10.0",
     "globals": "17.12.0",
     "semver": "7.8.5",
+    "typescript": "6.0.3",
     "typescript-eslint": "8.70.0"
   },
+  "peerDependencies": {
+    "typescript": ">=6.0.3 <7.0.0"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  },
   "homepage": "https://github.com/jimhoyd-com/urlcode#readme",
   "bugs": {
     "url": "https://github.com/jimhoyd-com/urlcode/issues"

package/recipes/static-page/README.md

@@ -0,0 +1,9 @@
+# Static page
+
+Run `urlcode validate --local --project .`, `urlcode test --project .` and
+`urlcode audit --project . --expect-routes 1`.
+
+`/` serves `public/index.html` with the native `page` handler, so no project
+code runs. Edit the file to change the page. For a whole directory of assets use
+`static`; for fixed text or JSON use `respond`; for an attachment use
+`download`. The `static-plus-api` recipe combines a page with a directory.

package/recipes/static-page/public/index.html

@@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Hello, World</title>
+</head>
+<body>
+  <h1>Hello, World</h1>
+</body>
+</html>

package/recipes/static-page/recipe.yaml

@@ -0,0 +1,21 @@
+id: static-page
+description: One HTML file served natively as a page, with no code and no directory mount.
+tags: [page, html, hello, world,static, site, landing, native, cache-control]
+complexity: starter
+capabilities: [enabled, methods, page]
+targets: {self-hosted: compatible, aws: compatible, vercel: compatible, cloudflare: refused, static: compatible}
+routes: 1
+inputs:
+  - name: page
+    file: public/index.html
+    description: The HTML document served at /.
+files: [urlcode.yaml, public/index.html, tests/requests.json, README.md]
+tests:
+  fixtures: tests/requests.json
+  commands:
+    - urlcode validate --local --project .
+    - urlcode test --project .
+    - urlcode audit --project . --expect-routes 1
+behavior:
+  - GET / answers 200 with the file as text/html and Cache-Control no-cache
+  - HEAD answers an empty body; POST answers 405

package/recipes/static-page/tests/requests.json

@@ -0,0 +1,22 @@
+[
+  {
+    "path": "/",
+    "status": 200,
+    "expectBody": "<!doctype html>\n<html lang=\"en\">\n<head>\n  <meta charset=\"utf-8\">\n  <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n  <title>Hello, World</title>\n</head>\n<body>\n  <h1>Hello, World</h1>\n</body>\n</html>\n",
+    "expectHeaders": {
+      "content-type": "text/html; charset=utf-8",
+      "cache-control": "no-cache"
+    }
+  },
+  {
+    "path": "/",
+    "method": "HEAD",
+    "status": 200,
+    "expectBody": ""
+  },
+  {
+    "path": "/",
+    "method": "POST",
+    "status": 405
+  }
+]

package/recipes/static-page/urlcode.yaml

@@ -0,0 +1,7 @@
+version: "1"
+routes:
+  /:
+    description: One HTML file served natively as the site's home page.
+    page:
+      file: public/index.html
+      cacheControl: no-cache

package/recipes/static-plus-api/README.md

@@ -13,3 +13,9 @@ activation, so new files need a reload. Edit the HTML, add files under
 The function needs the self-hosted runtime; drop `/api/info` to deploy the
 static part on a serverless target. Static mounts cannot escape their
 directory, and the recipe sets explicit caching so nothing is guessed.
+
+Adding a function that writes files or accepts a POST body? Filesystem access
+only exists in trusted (default) routes, since `sandbox: true` has no
+filesystem, so keep the route trusted and state why with `sandboxReason`, as
+`/api/info` does. `audit` advises when a POST route with a body policy has
+neither `sandbox: true` nor `sandboxReason`.

package/recipes/static-plus-api/urlcode.yaml

@@ -18,6 +18,10 @@ routes:
       args:
         name: Example site
         version: "1"
+    # Why this route runs trusted. Keep it when you add a function that
+    # touches the filesystem: that needs a trusted route, and a body policy
+    # makes `audit` ask for this line.
+    sandboxReason: Reviewed first-party code; trusted deliberately.
     response:
       headers:
         Cache-Control: no-store

package/recipes/store-crud/README.md

@@ -0,0 +1,53 @@
+# Store CRUD
+
+`/api/todos/*` is a persistent JSON CRUD API. The project declares one
+collection and its mount; the operator-installed `store` extension
+(`@jimhoyd/urlcode-store`) serves it and keeps the data in the operator's
+directory. There is no handler code. Full contract, limits and guarantees:
+[docs/STORE.md](../../docs/STORE.md).
+
+## Operator prerequisites
+
+The store is not core and does not activate on its own.
+
+- The operator installs `@jimhoyd/urlcode-store` next to `@jimhoyd/urlcode`
+  and registers it in a host file kept outside the project.
+- The package is on npm (`@jimhoyd/urlcode-store`).
+  `urlcode init --with ui,auth,store` scaffolds a protected site from the
+  published packages. A no-auth `init --with store` needs `--ack store:public-write`,
+  which the core published at the store's first release does not have, so write the host file below by hand until a
+  newer core is released.
+- The data directory must be outside the project. It is single-writer: one
+  server process per directory.
+
+```js
+// /operator/host.mjs -- trusted operator code, never part of the project
+import {inspectExtensionRevision} from '@jimhoyd/urlcode/extensions';
+import {storeExtension} from '@jimhoyd/urlcode-store';
+const projectSha256 = await inspectExtensionRevision(process.env.URLCODE_PROJECT);
+export default {extensions: [storeExtension({directory: '/operator/data/store', projectSha256})]};
+```
+
+```sh
+urlcode validate --local --project . --host-file /operator/host.mjs --origin https://api.example.com
+urlcode test --project . --host-file /operator/host.mjs --origin https://api.example.com
+urlcode audit --project . --expect-routes 1 --host-file /operator/host.mjs --origin https://api.example.com
+```
+
+The bundled fixtures run one ordered create, read, update, delete lifecycle
+that captures the new record's id and deletes it again, so they need an empty
+collection and leave it empty. Point them at a scratch data directory, not one
+holding real records. Try the write path by hand after serving:
+
+```sh
+curl -X POST -H 'Content-Type: application/json' -d '{"title":"first"}' https://api.example.com/api/todos
+```
+
+## Before exposing it
+
+The mount is public unless you protect it: add `auth: true` (with the auth
+extension) or another policy before any writable collection is reachable. Every
+caller sees the whole collection; there is no per-user ownership. Changing
+`urlcode.yaml` changes the revision and needs a new pin. Cloudflare and static
+targets refuse extensions, and the store writes local files, so run it on the
+self-hosted runtime with a persistent disk.

package/recipes/store-crud/recipe.yaml

@@ -0,0 +1,31 @@
+id: store-crud
+description: Persistent JSON CRUD API for a declared collection (create, read, update, delete, list) served by the operator-installed store extension, with no handler code.
+tags: [crud, store, persist, persistence, database, storage, todo, records, collection, json, api, rest, extension, "201", "404"]
+complexity: advanced
+capabilities: [enabled, extension, methods]
+targets: {self-hosted: conditional, cloudflare: refused, aws: conditional, vercel: conditional, static: refused}
+routes: 1
+services:
+  - name: store extension
+    description: An operator host file registering storeExtension from @jimhoyd/urlcode-store, with a data directory outside the project. The operator installs the package; `urlcode init --with ui,auth,store` scaffolds a protected host, and the README shows a hand-written one.
+grants:
+  - kind: extension
+    description: The registration pins projectSha256 to this exact revision; editing a collection or the mount needs operator review and a new pin.
+  - kind: origin
+    description: The canonical origin passed as --origin at every command that activates the project; cross-origin writes are refused.
+inputs:
+  - name: collection
+    file: urlcode.yaml
+    description: The collection name, mount path, typed fields, defaults and record limits.
+files: [urlcode.yaml, tests/requests.json, README.md]
+tests:
+  fixtures: tests/requests.json
+  commands:
+    - urlcode validate --local --project . --host-file /operator/host.mjs --origin https://api.example.com
+    - urlcode test --project . --host-file /operator/host.mjs --origin https://api.example.com
+    - urlcode audit --project . --expect-routes 1 --host-file /operator/host.mjs --origin https://api.example.com
+behavior:
+  - GET /api/todos on an empty collection answers 200 {"items":[],"total":0} with Cache-Control no-store
+  - POST /api/todos with a valid JSON record answers 201, the record with a server-assigned id, and a Location header
+  - invalid or unknown fields answer 400, a non-JSON Content-Type answers 415, a missing id answers 404, an unsupported method answers 405
+  - PUT replaces the record, PATCH updates supplied fields, DELETE answers 204; records survive a restart

package/recipes/store-crud/tests/requests.json

@@ -0,0 +1,18 @@
+[
+  {"path": "/api/todos", "status": 200, "expectBody": "{\"items\":[],\"total\":0}", "expectHeaders": {"cache-control": "no-store"}},
+  {"steps": [
+    {"path": "/api/todos", "method": "POST", "headers": {"content-type": "application/json"}, "body": "{\"title\":\"first\"}", "status": 201, "expectHeaders": {"cache-control": "no-store"}, "capture": {"id": {"json": "id"}}},
+    {"path": "/api/todos/{{id}}", "status": 200, "expectHeaders": {"cache-control": "no-store"}},
+    {"path": "/api/todos/{{id}}", "method": "HEAD", "status": 200, "expectBody": ""},
+    {"path": "/api/todos/{{id}}", "method": "PATCH", "headers": {"content-type": "application/json"}, "body": "{\"done\":true}", "status": 200, "expectHeaders": {"cache-control": "no-store"}},
+    {"path": "/api/todos/{{id}}", "method": "PUT", "headers": {"content-type": "application/json"}, "body": "{\"title\":\"second\"}", "status": 200, "expectHeaders": {"cache-control": "no-store"}},
+    {"path": "/api/todos", "status": 200, "expectHeaders": {"cache-control": "no-store"}},
+    {"path": "/api/todos/{{id}}", "method": "DELETE", "status": 204, "expectBody": ""},
+    {"path": "/api/todos/{{id}}", "status": 404}
+  ]},
+  {"path": "/api/todos", "method": "POST", "headers": {"content-type": "application/json"}, "body": "{\"done\":true}", "status": 400},
+  {"path": "/api/todos", "method": "POST", "headers": {"content-type": "application/json"}, "body": "{\"title\":\"x\",\"owner\":\"me\"}", "status": 400},
+  {"path": "/api/todos", "method": "POST", "headers": {"content-type": "text/plain"}, "body": "title=x", "status": 415},
+  {"path": "/api/todos/00000000-0000-4000-8000-000000000000", "status": 404},
+  {"path": "/api/todos", "method": "DELETE", "status": 405}
+]

package/recipes/store-crud/urlcode.yaml

@@ -0,0 +1,18 @@
+version: "1"
+extensions:
+  store:
+    version: "1"
+    config:
+      collections:
+        todos:
+          mount: /api/todos
+          fields:
+            title: {type: string, required: true, minLength: 1, maxLength: 200}
+            done: {type: boolean, default: false}
+          maxRecords: 1000
+          maxRecordBytes: 4096
+routes:
+  /api/todos/*:
+    description: Create, read, update, delete and list todo records persisted by the operator-installed store extension.
+    extension: store
+    methods: [GET, HEAD, POST, PUT, PATCH, DELETE]