@jimhoyd/urlcode 0.3.0 → 0.4.0-alpha.1

package/skills/urlcode/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: urlcode
+description: Work on a URLCode project, recognized by a urlcode.yaml file with version "1" and served by the @jimhoyd/urlcode runtime. Use this skill whenever a task touches urlcode.yaml, its included route files, functions or middleware under a URLCode project, or asks to add, change, test or deploy URL behavior (redirects, responses, pages, files, functions, live links, policies) in such a project. It teaches the authoring loop and how to retrieve the minimum reference from the installed runtime instead of guessing fields.
+---
+
+# 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 guest code it names,
+then prove the change with the runtime's own checks. Never reimplement what the
+runtime provides, and never invent fields.
+
+## 1. Recognize the project
+
+- The root has `urlcode.yaml` with `version: "1"`. Included route files are
+  listed under `includes`; functions, middleware and assets are referenced from
+  the project root.
+- Read the project's `AGENTS.md` first if present; it lists the handlers,
+  policies and commands this runtime version supports.
+- Find the runtime: `urlcode` on the PATH, or
+  `node node_modules/@jimhoyd/urlcode/dist/cli.js`, or
+  `node /path/to/urlcode/src/cli.ts` for a source checkout. Use one form for
+  every command below.
+
+## 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.
+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 --target NAME   # before promising a provider deployment
+urlcode capabilities NAME            # get_capability: one capability's contract
+urlcode schema PATH                  # get_schema: one YAML fragment
+urlcode recipes search TEXT          # search_recipes
+urlcode explain PATH --project DIR   # explain: a route's effective behavior
+urlcode manifest --project DIR       # get_manifest
+urlcode recipes list                 # bundled starting points
+urlcode recipes show NAME            # one recipe's files, inline
+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.
+
+## 3. Prefer YAML, then a recipe, then a function
+
+1. If a native handler expresses the behavior (`redirect`, `respond`, `page`,
+   `static`, `download`, `link`, `proxy`, `conditional`), write YAML only.
+2. 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, relative
+   ES-module imports inside the project only, inputs from validated `args`,
+   output as a `Response`. The sandbox has no `fetch`, Node, filesystem or
+   timers; a need for them is a `proxy` route, a binding, or a report.
+4. Never build routing, validation, middleware chains, policies, static
+   serving, caching, throttling or authentication in code. Declare them.
+
+Keep every route you were not asked to change. Match the file organization the
+project already uses.
+
+## 4. Prove it
+
+```sh
+urlcode validate --local --project DIR
+urlcode test --project DIR
+urlcode audit --project DIR --expect-routes N
+```
+
+Add fixtures to `tests/requests.json` for each new route: positive and negative
+cases, every active method, `HEAD`. Update `N` deliberately when routes are
+added or removed, and update any `--expect-routes` in the project's README,
+Makefile or CI workflow to match. A failing validation names the route; fix
+the declaration rather than working around it.
+
+## 5. Grants, secrets and what to report
+
+- A function that needs a secret or environment value declares a named `env`
+  or `secrets` binding in YAML and stops there. The operator grants it outside
+  the project, pinned to the project revision. Never create, edit or approve a
+  grant, policy file or host file, and never put a value in the project.
+- Secrets stay out of YAML, functions, fixtures, unignored `.env` files and
+  commit messages.
+- When the runtime cannot express a requirement (the validator rejects it,
+  `capabilities` marks it refused for the target, or it needs guest network
+  or persistence), report exactly that with the route and capability named.
+  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.

package/starters/default/.github/workflows/urlcode.yml

@@ -0,0 +1,23 @@
+# Validates, tests and audits this project on every push and pull request, and
+# comments a route-inventory diff on pull requests. See
+# https://github.com/jimhoyd-com/urlcode/blob/main/docs/CI.md
+name: urlcode
+on:
+  push:
+  pull_request:
+permissions:
+  contents: read
+  pull-requests: write # the sticky route-diff comment; drop it to only log the diff
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      # Pin to a release tag or commit of the runtime you depend on.
+      - uses: jimhoyd-com/urlcode/action@main
+        with:
+          expect-routes: 2 # update when adding or removing routes
+          compliance: baseline

package/starters/default/.mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "urlcode": {
+      "command": "urlcode",
+      "args": [
+        "mcp",
+        "--project",
+        "."
+      ]
+    }
+  }
+}

package/starters/default/AGENTS.md

@@ -0,0 +1,79 @@
+# 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.
+
+## 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.
+4. Prefer YAML over code. Prefer native handlers over functions.
+
+## Ask the runtime through MCP first
+
+`.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.
+
+## What the runtime provides (this version)
+
+- Handlers, exactly one per route: `redirect`, `respond`, `page`, `static`, `download`, `function`, `link`, `proxy`, `conditional`, `extension`.
+- Ordered `middleware` around any handler, declared in YAML, run in the sandbox.
+- Validated inputs: `parameters`, `request.body` and `methods` on the route;
+  functions receive validated `args`, never raw user input.
+- 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).
+- Bindings: named `env` and `secrets` references resolved by the operator, never values in YAML.
+
+Never recreate any of these in a function. If a requirement seems to need one
+of them and it is missing, that is a report, not an invitation to reimplement.
+
+## Functions and middleware are sandboxed
+
+Guest code runs in an isolated JavaScript engine with a fresh heap per call.
+It sees a text/JSON `Request`/`Response` subset, validated `args` and granted
+`env`. There is no `fetch`, no Node API, no filesystem, no timers and no
+imports outside the project. Do not write code that needs them; declare a
+`proxy` route or a binding instead and say why.
+
+## Checks that count as evidence
+
+```sh
+urlcode validate --local
+urlcode test
+urlcode audit --expect-routes 2
+```
+
+Run all three after every change. Update the expected route count deliberately
+when you add or remove a route, and add fixtures to `tests/requests.json` for
+every new route (positive and negative cases, every active method, HEAD).
+Without a global install, invoke `node /path/to/urlcode/src/cli.ts` instead of `urlcode`.
+
+## 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.
+- Authentication is host processing: declare `auth` on the route, never build
+  login forms, sessions or password checks in functions.
+- 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.
+
+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`).