@jimhoyd/urlcode 0.4.2 → 0.4.7

package/schemas/urlcode.schema.json

@@ -116,7 +116,7 @@
     },
     "site": {
       "type": "object",
-      "description": "Site conventions. Each declared key generates one native route (robots.txt, sitemap.xml, favicon.ico, .well-known/security.txt, llms.txt); a declared route at the same path wins. Entry urlcode.yaml only.",
+      "description": "Site conventions. Each declared key generates one native route (robots.txt, sitemap.xml, favicon.ico, .well-known/security.txt, llms.txt, 404.html); a declared route at the same path wins. Entry urlcode.yaml only.",
       "properties": {
         "robots": {
           "type": "object",
@@ -279,6 +279,13 @@
           "minLength": 1,
           "maxLength": 1024,
           "description": "Project-relative text file served at /llms.txt."
+        },
+        "notFound": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1024,
+          "pattern": "\\.[hH][tT][mM][lL]?$",
+          "description": "Project-relative .html file served with status 404 and text/html for a GET or HEAD that matches no route. Generated as a page route at /404.html, which is also the object name static hosting uses."
         }
       },
       "additionalProperties": false
@@ -307,6 +314,26 @@
         "additionalProperties": false
       },
       "description": "Versioned logical extension configurations. Requires explicit external operator registrations pinned to the project revision; never loads project code."
+    },
+    "shared": {
+      "type": "object",
+      "description": "Reusable named request and response.headers blocks a route selects with use. Resolved at load time; the route hash, audit and routes output show the resolved route. Entry urlcode.yaml only. Response headers the runtime owns are refused.",
+      "maxProperties": 32,
+      "propertyNames": {
+        "pattern": "^[a-z][a-z0-9-]{0,63}$"
+      },
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "request": {
+            "$ref": "#/$defs/requestBlock"
+          },
+          "response": {
+            "$ref": "#/$defs/responseBlock"
+          }
+        },
+        "additionalProperties": false
+      }
     }
   },
   "required": [
@@ -351,6 +378,20 @@
           "maxLength": 500,
           "description": "Optional justification for this route's sandbox decision, whether sandbox is true or false: why it needs isolation, or why it is safe to trust. Never inferred or enforced; surfaced verbatim by explain/context/manifest."
         },
+        "coveredElsewhere": {
+          "type": "object",
+          "minProperties": 1,
+          "propertyNames": {
+            "enum": ["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"]
+          },
+          "additionalProperties": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 500,
+            "description": "Why this method is tested elsewhere."
+          },
+          "description": "Audit-only waiver: methods of this route whose normal-response fixture is provided by other tests (for example stateful create/update/delete). Each method needs a non-empty reason and must be one of the route's methods. audit lists waived pairs with their reasons under waivedRouteMethods and still requires the route to have another normally covered method; it never hides a function route that only serves errors. Project file only: there is no CLI flag."
+        },
         "expires": {
           "type": "string"
         },
@@ -432,6 +473,16 @@
                   "maximum": {
                     "type": "number"
                   },
+                  "pattern": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 128
+                  },
+                  "format": {
+                    "enum": [
+                      "uuid"
+                    ]
+                  },
                   "items": {
                     "type": "object",
                     "properties": {
@@ -773,67 +824,10 @@
           "additionalProperties": false
         },
         "request": {
-          "type": "object",
-          "properties": {
-            "body": {
-              "type": "object",
-              "properties": {
-                "required": {
-                  "type": "boolean"
-                },
-                "maxBytes": {
-                  "type": "integer",
-                  "minimum": 0,
-                  "maximum": 1048576
-                },
-                "contentTypes": {
-                  "type": "array",
-                  "minItems": 1,
-                  "maxItems": 16,
-                  "uniqueItems": true,
-                  "items": {
-                    "type": "string",
-                    "pattern": "^[a-z0-9!#$&^_.+-]+/[a-z0-9!#$&^_.+-]+$"
-                  }
-                },
-                "format": {
-                  "enum": [
-                    "text",
-                    "json"
-                  ]
-                }
-              },
-              "additionalProperties": false
-            }
-          },
-          "additionalProperties": false
+          "$ref": "#/$defs/requestBlock"
         },
         "response": {
-          "type": "object",
-          "properties": {
-            "headers": {
-              "type": "object",
-              "maxProperties": 64,
-              "additionalProperties": {
-                "oneOf": [
-                  {
-                    "type": "string",
-                    "maxLength": 4096
-                  },
-                  {
-                    "type": "array",
-                    "minItems": 1,
-                    "maxItems": 16,
-                    "items": {
-                      "type": "string",
-                      "maxLength": 4096
-                    }
-                  }
-                ]
-              }
-            }
-          },
-          "additionalProperties": false
+          "$ref": "#/$defs/responseBlock"
         },
         "respond": {
           "type": "object",
@@ -942,6 +936,11 @@
         "cache": {
           "description": "Short form for policies.cache: the same object, expanded to policies.cache before anything else reads the project. Refused alongside policies.cache; use one form.",
           "$ref": "#/$defs/policyCache"
+        },
+        "use": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]{0,63}$",
+          "description": "Name of a top-level shared block whose request and response.headers this route inherits. A key the route declares itself replaces the shared block as a whole; there is no deep merge."
         }
       },
       "required": [],
@@ -1774,6 +1773,72 @@
         "url"
       ],
       "additionalProperties": false
+    },
+    "requestBlock": {
+      "type": "object",
+      "properties": {
+        "body": {
+          "type": "object",
+          "properties": {
+            "required": {
+              "type": "boolean"
+            },
+            "maxBytes": {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 1048576
+            },
+            "contentTypes": {
+              "type": "array",
+              "minItems": 1,
+              "maxItems": 16,
+              "uniqueItems": true,
+              "items": {
+                "type": "string",
+                "pattern": "^[a-z0-9!#$&^_.+-]+/[a-z0-9!#$&^_.+-]+$"
+              }
+            },
+            "format": {
+              "enum": [
+                "text",
+                "json"
+              ]
+            },
+            "schema": {
+              "type": "object"
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "responseBlock": {
+      "type": "object",
+      "properties": {
+        "headers": {
+          "type": "object",
+          "maxProperties": 64,
+          "additionalProperties": {
+            "oneOf": [
+              {
+                "type": "string",
+                "maxLength": 4096
+              },
+              {
+                "type": "array",
+                "minItems": 1,
+                "maxItems": 16,
+                "items": {
+                  "type": "string",
+                  "maxLength": 4096
+                }
+              }
+            ]
+          }
+        }
+      },
+      "additionalProperties": false
     }
   }
 }

package/skills/urlcode/SKILL.md

@@ -5,19 +5,13 @@ description: Work on a URLCode project, recognized by a urlcode.yaml file with v
 
 # URLCode authoring loop
 
-A URLCode project declares URL behavior in YAML; the installed runtime serves
-it. Your job is to change the declaration and the minimal application code it names,
-then prove the change with the runtime's own checks. Never reimplement what the
-runtime provides, and never invent fields.
+A URLCode project declares URL behavior in YAML; the installed runtime serves it. Change the declaration and minimal application code it names, then prove it with the runtime's own checks. Never reimplement what the runtime provides or invent fields.
 
 ## Declarative-first default
 
 > Use URLCode's highest-level declarative features whenever possible. Generate custom code only when the framework cannot express the requirement.
 
-Check the installed version's primitives, YAML configuration, policies, supported
-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 `docs/PROJECT-DIRECTION.md` in the installed runtime.
+Check installed primitives, YAML configuration, policies, extensions and recipes/templates before writing custom code. Keep it focused and report the gap; never invent fields or bypass target limits or operator grants. Source checkouts have `docs/PROJECT-DIRECTION.md`; npm installations have it in `llms-full.txt`.
 
 ## 1. Recognize the project
 
@@ -33,21 +27,18 @@ fields or bypass target limits or operator grants. See `docs/PROJECT-DIRECTION.m
 
 ## 2. Retrieve the minimum, do not read everything
 
-If the project carries `.mcp.json` (written by `urlcode init`) and your client
-has registered the `urlcode` server, prefer its tools over reading documents:
-`get_context` (project summary, constraints, exact commands), `get_capability`
-and `get_schema` (one capability or YAML fragment), `search_recipes`,
-`explain` (a route's effective behavior) and `get_manifest`. The server is
-read-only; `--allow-authoring` is an operator opt-in you never add yourself.
+**First step: one bounded query.** MCP `get_context` when the `urlcode` server is registered, otherwise `urlcode context --project DIR` (add `--budget N` to cap it). It returns a compact summary, constraints and exact commands, never a schema dump. Then retrieve only what the task needs: `capabilities NAME`/`get_capability` (its limits), `get_schema`, `recipes search`/`search_recipes`, `explain`, and `get_extensions` when an operator host file exists. The bare `urlcode capabilities` and `recipes list` catalogs, `llms.txt` and `llms-full.txt` are deliberate fallback/reference, not the opening move.
+
+If the project carries `.mcp.json` (written by `urlcode init`) and your client has the `urlcode` server, prefer its tools: `get_context` (project summary, constraints, exact commands), `get_capability` and `get_schema` (one capability or YAML fragment), `search_recipes`, `search_examples`, `explain` (a route's effective behavior) and `get_manifest`. For framework discovery, use `list_skills` before `get_skill`, `search_docs` for a short package-owned excerpt, and `get_example` for one runnable example. Use `validate_yaml` for pasted YAML syntax/schema feedback only; use `validate` for the actual project. The server is read-only; `--allow-authoring` is an operator opt-in you never add yourself.
 When the MCP server was started with an operator host file, `get_extensions`
-returns installed extension configuration/policy schemas and declared project
-hook contracts. Otherwise use `urlcode extensions --project DIR --host-file
+returns installed extension configuration/policy schemas, declared project
+hook contracts, supported authoring surfaces and fast checks. Otherwise use `urlcode extensions --project DIR --host-file
 ABSOLUTE_HOST --json` when the operator has supplied that host file.
 Without the server, run the CLI equivalents and read only the output:
 
 ```sh
 urlcode context --project DIR        # get_context: summary, constraints, commands
-urlcode capabilities                 # what this version implements, per target
+urlcode capabilities                 # complete catalog (fallback, not step one)
 urlcode capabilities --target NAME   # before promising a provider deployment
 urlcode capabilities NAME            # get_capability: one capability's contract
 urlcode schema PATH                  # get_schema: one YAML fragment
@@ -61,9 +52,8 @@ urlcode routes --project DIR         # the routes the project already has
 
 When a field or handler is unclear, ask the runtime, not memory:
 `urlcode validate --local` names the rejected field and the route. The
-installed package also ships `docs/YAML-REFERENCE.md` (generated field
-inventory) and `schemas/urlcode.schema.json`; search them for the one key you
-need rather than reading them whole.
+installed package also ships `schemas/urlcode.schema.json` and the generated
+field inventory in `llms-full.txt`; search only for the key you need.
 
 ## 3. Choose the highest-level supported abstraction
 
@@ -75,13 +65,12 @@ need rather than reading them whole.
    contract v1 runs trusted in-process and rejects `sandbox: true`. If a
    recipe from `recipes list` is close, `urlcode recipes add NAME --out DIR`
    and adapt the copy into the project's layout.
-3. Only then write a function or middleware: one exported handler, inputs from validated `args`,
-   output as a `Response`. `function`/`middleware` routes run trusted and
-   unsandboxed by default: full Node, npm, filesystem and `fetch` access, like
-   any other project code. Add `sandbox: true` only when that route's own code
-   warrants isolation (unreviewed or third-party code, a secret whose blast
-   radius matters, complex logic — never merely because it handles request
-   data, which is untrusted in both modes) — a `sandbox: true` route then has no
+3. Only then write a function or middleware: one exported handler, validated `args`,
+   and a `Response`. They run trusted and unsandboxed by default with Node, npm,
+   filesystem and `fetch` access. Use `sandbox: true` only when that route's own
+   code warrants isolation (unreviewed or third-party code, a secret whose blast
+   radius matters, complex logic — not merely request data, which is untrusted in
+   both modes) — a sandboxed route then has no
    `fetch`, Node, npm, filesystem, WebSocket, streaming or crypto APIs (bounded timers are supported);
    a need for those in a sandboxed route is a `proxy` route, a binding, or a
    report.
@@ -96,6 +85,28 @@ need rather than reading them whole.
 Keep every route you were not asked to change. Match the file organization the
 project already uses.
 
+## Build one application
+
+Treat core routes, installed extensions and product UI as one application with
+different owners. Core owns routing and policy mechanics; auth/admin own their
+security and workflow behavior; the project owns its product pages, brand and
+the smallest set of overrides that make it distinct.
+
+For an installed extension, follow its `authoring` surfaces from
+`get_extensions` in this order: configuration; theme and copy; component or
+template override; project CSS; declared trusted hook. Build a new extension
+only for a reusable capability the installed contracts do not provide. A visual
+change is not a reason to fork core or copy an auth/admin flow.
+
+For a React frontend with `components.json`, load the official shadcn/ui skill,
+run `shadcn info --json`, then use its docs/search or MCP registry before
+generating components. The URLCode skill still owns routing, extension and trust;
+do not put React components in its shadcn-compatible server template renderer.
+
+Use published `fastChecks` while iterating, then the full project checks before
+handoff. Theme/copy should not rebuild framework packages; full workspace checks
+may take several minutes, so let them finish instead of repeatedly rebuilding.
+
 ## 4. Prove it
 
 ```sh
@@ -124,3 +135,12 @@ the declaration rather than working around it.
   Do not invent fields, degrade silently or claim a workaround is equivalent.
 - Report the three commands' results as the evidence. They are not a
   deployment, a soak test or a security review.
+
+## 6. Leave evidence-backed feedback
+
+After a real attempt, draft feedback only for a capability gap, repeated workaround,
+documentation/discovery gap or suspected defect. Include the runtime/target, a
+sanitized route/YAML fragment, exact validation or test observation, smallest expected
+behavior and a proposed fixture. Exclude secrets, customer URLs, raw source and
+one-off product logic; search existing issues for likely duplicates. A draft never
+authorizes publishing: do not create or comment on a GitHub issue without explicit approval.

package/starters/default/AGENTS.md

@@ -1,53 +1,55 @@
 # Working on this project
 
 This project uses URLCode: URL behavior is declared in `urlcode.yaml`, and the
-installed `@jimhoyd/urlcode` runtime serves it. There is no framework code to
-write for routing, validation, middleware wiring, policies, static serving or
-authentication; the runtime provides them. Read this file before changing anything.
+installed runtime supplies routing, validation, middleware wiring, policies,
+static serving and authentication. Read this file before changing anything.
 
 ## Before writing code
 
 1. Inspect `urlcode.yaml` first, then every file its `includes` list names,
-   the referenced functions, middleware and `tests/requests.json`. Preserve the
-   existing organization and every route you were not asked to change.
-2. Run `urlcode capabilities` to see what this runtime version implements and
-   which targets support it; `urlcode capabilities --target NAME` before
-   promising any provider deployment.
-3. Run `urlcode recipes list` and `urlcode recipes show NAME` before writing a
-   route from scratch. If a recipe covers the need, add it with
-   `urlcode recipes add NAME --out DIR` and adapt the copy.
+   referenced code and `tests/requests.json`. Preserve unrelated routes.
+2. Make one bounded query first: MCP `get_context` when the `urlcode` server is
+   registered, else `urlcode context --project DIR` (add `--budget N` to cap
+   it). It returns a compact summary, constraints and exact commands.
+3. Then retrieve only what the task needs: `capabilities NAME`/`get_capability`
+   (limits; `--target NAME` before promising a provider), `get_schema`,
+   `recipes search TEXT`/`search_recipes` then `recipes add NAME --out DIR`,
+   `explain` and, with an operator host file, `get_extensions`. Bare
+   `capabilities` and `recipes list` are complete catalogs: fallback, not step one.
 4. Use URLCode's highest-level declarative features whenever possible. Generate custom code only when the framework cannot express the requirement. Check supported extensions and recipes first; explain any capability gap.
 
-## Ask the runtime through MCP first
+## MCP
 
-When present, `.mcp.json` registers the read-only `urlcode mcp` server. When it is
-available, prefer its tools over reading documents: `get_context`,
-`get_capability`, `get_schema`, `search_recipes`, `explain`, `get_manifest`.
-The CLI equivalents are the fallback: `urlcode context`, `urlcode capabilities NAME`,
-`urlcode schema PATH`, `urlcode recipes search TEXT`, `urlcode explain PATH`,
-`urlcode manifest`. `--allow-authoring` is an operator opt-in; never add it yourself.
+When present, `.mcp.json` registers the read-only `urlcode mcp` server; prefer its
+tools (also `get_manifest`) to reading documents. Inspect `get_extensions` before
+replacing extension behavior. `--allow-authoring` is an operator opt-in; never add it.
 
 ## What the runtime provides (this version)
 
 - Handlers, exactly one per route: `redirect`, `respond`, `page`, `static`, `download`, `function`, `proxy`, `conditional`.
 - Ordered `middleware` around any handler, declared in YAML, trusted by default.
-- Validated inputs: `parameters`, `request.body` and `methods` on the route;
-  functions receive validated `args`, never raw user input.
+- Validated route `parameters`, `request.body`, `methods` and function `args`.
 - Policies, host-enforced and off by default: `agents`, `throttle`, `cache`, `security`, `compression`.
-- Site conventions under `site`, each generating one native route: `robots` (/robots.txt), `sitemap` (/sitemap.xml), `favicon` (/favicon.ico), `securityTxt` (/.well-known/security.txt), `llms` (/llms.txt).
+- Site conventions under `site`, each generating one native route: `robots` (/robots.txt), `sitemap` (/sitemap.xml), `favicon` (/favicon.ico), `securityTxt` (/.well-known/security.txt), `llms` (/llms.txt), `notFound` (/404.html).
 - Bindings: named `env` and `secrets` references resolved by the operator, never values in YAML.
 
-Never recreate any of these in a function; a missing one is a report, not an
-invitation to reimplement it.
+Never recreate these in a function; report a missing capability.
+
+## Build one application
+
+Treat routes, extensions and UI as one application with different owners. Use
+published surfaces in order: configuration/theme/copy, smallest template, CSS,
+then a declared hook. Keep auth/admin security and workflows package-owned; add
+an extension only for a reusable missing capability. Use the official shadcn/ui
+skill only in a React frontend with `components.json`; start with `shadcn info
+--json`. Do not put React components in the server renderer.
 
 ## Functions and middleware are trusted by default; sandbox is opt-in
 
-A route's `function`/`middleware` runs trusted, in-process, with full
-Node/filesystem/`fetch` access, given only declared `args`/`env`/`secrets`. Add
-`sandbox: true` when that code warrants isolation (unreviewed code, a sensitive
-secret, complex logic) — not merely for untrusted input, which both modes share.
-A `sandbox: true` route gets a text/JSON subset only: use `proxy`/a binding, and
-say why in `sandboxReason`.
+A `function`/`middleware` is trusted, in-process Node with only declared
+`args`/`env`/`secrets`. Add `sandbox: true` for code needing isolation, not
+merely untrusted input. The sandbox is text/JSON-only; use `proxy`/a binding and
+record the reason in `sandboxReason`.
 
 ## Checks that count as evidence
 
@@ -57,23 +59,21 @@ urlcode test
 urlcode audit --expect-routes 2
 ```
 
-Run all three after every change, updating the route count deliberately and
-adding `tests/requests.json` fixtures for every new route (positive/negative,
-every active method, HEAD). No global install: use `node /path/to/urlcode/src/cli.ts`.
+Run all three after every change, updating the route count deliberately and adding `tests/requests.json` fixtures for every new route (positive/negative, every active method, HEAD). No global install: use `node /path/to/urlcode/src/cli.ts`.
+
+## Feedback
+
+After a real attempt, draft evidence-backed feedback: category, sanitized YAML, observed validation/test result, expected behavior and fixture. Ignore one-off product logic; search existing URLCode issues first; never publish or comment without the user's explicit approval.
 
 ## Rules
 
-- Report unsupported requirements instead of inventing fields. The schema is
-  exact; a field the validator rejects does not exist. Say what is missing.
-- Never create or approve operator grants. Request a named binding in YAML and
-  stop; the operator grants it outside this project, pinned to the revision.
-- Secrets stay out of the project: no keys, tokens or credentials in YAML,
-  functions, fixtures, `.env` files that are not ignored, or commit messages.
+- Report unsupported requirements; a field the exact schema rejects does not exist.
+- Never create operator grants. Request a named binding; the operator grants it
+  outside the project, pinned to the revision.
+- Keep keys, tokens and credentials out of project files and commit messages.
 - Protect a route with `auth: true`/`auth: { role: admin }` where an `auth`
   extension is declared; `cache` likewise expands to `policies.cache`.
-- Validation, tests and the audit are the evidence. Local checks are not a
-  deployment, a soak test or a security review; do not claim otherwise.
+- Local checks are not deployment, soak or independent security evidence.
 
-The installed package ships an agent skill with the same loop at
-`skills/urlcode/SKILL.md` inside `@jimhoyd/urlcode` (for example
-`node_modules/@jimhoyd/urlcode/skills/urlcode/SKILL.md`).
+The installed package ships the same loop at `skills/urlcode/SKILL.md` inside
+`@jimhoyd/urlcode` (for example `node_modules/@jimhoyd/urlcode/skills/urlcode/SKILL.md`).

package/starters/page/README.md

@@ -0,0 +1,14 @@
+# Your URLCode page
+
+The smallest project: one route that serves `public/index.html`.
+Created with `urlcode init <dir> --template page`.
+
+```sh
+urlcode validate --local
+urlcode test
+urlcode dev   # http://127.0.0.1:3000/
+```
+
+Edit `public/index.html`. Add more pages, a `static` directory, downloads,
+redirects or functions as routes in `urlcode.yaml` (see docs/ASSETS.md in the
+URLCode repository). Keep `tests/requests.json` in step with the routes.

package/starters/page/public/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Hello, URLCode</title>
+</head>
+<body>
+<h1>Hello, URLCode</h1>
+<p>This page is served by a page route in urlcode.yaml.</p>
+</body>
+</html>

package/starters/page/tests/requests.json

@@ -0,0 +1,17 @@
+[
+  {
+    "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, URLCode</title>\n</head>\n<body>\n<h1>Hello, URLCode</h1>\n<p>This page is served by a page route in urlcode.yaml.</p>\n</body>\n</html>\n"
+  },
+  {
+    "path": "/",
+    "method": "HEAD",
+    "status": 200,
+    "expectBody": ""
+  },
+  {
+    "path": "/missing",
+    "status": 404
+  }
+]

package/starters/page/urlcode.yaml

@@ -0,0 +1,6 @@
+version: "1"
+routes:
+  /:
+    description: The home page, served from a file. Add routes beside it as the project grows.
+    page:
+      file: public/index.html

package/.claude-plugin/marketplace.json

@@ -1,18 +0,0 @@
-{
-  "name": "urlcode",
-  "owner": {
-    "name": "jimhoyd-com",
-    "url": "https://github.com/jimhoyd-com"
-  },
-  "metadata": {
-    "description": "Claude plugins published from the URLCode repository.",
-    "version": "0.4.2"
-  },
-  "plugins": [
-    {
-      "name": "urlcode",
-      "source": "./packaging/claude-plugin",
-      "description": "Authoring and operating URLCode projects: the implemented YAML contract, capability limits, deployment and verification commands for the pinned runtime revision."
-    }
-  ]
-}