@jimhoyd/urlcode 0.3.0

package/examples/prerender/prerender.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+// Prerender recipe: render this project's function/middleware routes once, at
+// build time, into a native page project that serves the same bytes with no
+// guest execution on the request path.
+//
+// The orchestration that is easy to get wrong — runtime lifecycle, response
+// validation, budgets, byte fidelity and output-path safety — lives in the
+// runtime's build helper. What is left here is the part every site does
+// differently: assembling a project from the rendered pages. In your own
+// project, import the helper from the package:
+//
+//   import {prerenderPages, assertNativeProject} from '@jimhoyd/urlcode/prerender';
+//
+import {mkdir, writeFile, rm} from 'node:fs/promises';
+import {realpathSync} from 'node:fs';
+import {join, resolve} from 'node:path';
+import {fileURLToPath, pathToFileURL} from 'node:url';
+import {stringify} from 'yaml';
+import {prerenderPages, assertNativeProject} from '@jimhoyd/urlcode/prerender';
+
+export async function prerender(project, output, {log = () => {}} = {}) {
+  const out = resolve(output);
+  // Pages are rendered and written first; nothing below runs unless every one
+  // of them produced a complete HTML response.
+  const rendered = await prerenderPages(project, join(out, 'public'), {log});
+
+  // Assemble the serving project. A larger site does this differently: it adds
+  // static and download routes, response security headers and its own entry
+  // point, and may write a generated include instead of a whole project.
+  await writeFile(join(out, 'urlcode.yaml'), stringify({
+    version: '1',
+    routes: Object.fromEntries(rendered.pages.map(page =>
+      [page.path, {page: {file: `public/${page.file}`, cacheControl: 'no-cache'}}])),
+  }));
+  await mkdir(join(out, 'tests'), {recursive: true});
+  await writeFile(join(out, 'tests/requests.json'), JSON.stringify(rendered.fixtures, null, 2) + '\n');
+
+  // Prove the artifact is inert before anyone deploys it.
+  await assertNativeProject(out, {allow: ['page'], log});
+  return {pages: rendered.count, bytes: rendered.bytes, output: out};
+}
+
+// Node resolves a module's own URL through symlinks, so comparing it to a raw
+// argv[1] misses when this file is reached through one — as it is under macOS's
+// /var -> /private/var temporary directories, where the script would otherwise
+// exit 0 having silently done nothing.
+const invokedDirectly = () => {
+  try { return import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href; }
+  catch { return false; }
+};
+if (process.argv[1] && invokedDirectly()) {
+  const [project = fileURLToPath(new URL('.', import.meta.url)), output = 'dist'] = process.argv.slice(2);
+  const print = value => process.stdout.write(JSON.stringify(value) + '\n');
+  try {
+    // The helper refuses to write into an existing directory, so a repeated
+    // build clears its own output rather than merging into a stale one.
+    await rm(resolve(output), {recursive: true, force: true});
+    print({event: 'prerendered-project', ...await prerender(project, output, {log: print})});
+  } catch (error) {
+    process.stderr.write(JSON.stringify({event: 'error', message: error.message}) + '\n');
+    process.exitCode = 1;
+  }
+}

package/examples/prerender/tests/requests.json

@@ -0,0 +1,39 @@
+[
+  {
+    "path": "/",
+    "status": 200,
+    "expectHeaders": {"content-type": "text/html; charset=utf-8"}
+  },
+  {
+    "path": "/",
+    "method": "HEAD",
+    "status": 200,
+    "expectBody": ""
+  },
+  {
+    "path": "/guide",
+    "status": 200,
+    "expectHeaders": {"content-type": "text/html; charset=utf-8"}
+  },
+  {
+    "path": "/guide",
+    "method": "HEAD",
+    "status": 200,
+    "expectBody": ""
+  },
+  {
+    "path": "/about",
+    "status": 200,
+    "expectHeaders": {"content-type": "text/html; charset=utf-8"}
+  },
+  {
+    "path": "/about",
+    "method": "HEAD",
+    "status": 200,
+    "expectBody": ""
+  },
+  {
+    "path": "/missing",
+    "status": 404
+  }
+]

package/examples/prerender/urlcode.yaml

@@ -0,0 +1,50 @@
+version: "1"
+# The dynamic source of the site. Every page is a function response wrapped by
+# one shared template middleware, so `dev` serves it live while you edit. The
+# prerender recipe renders these routes once and emits a native page project.
+routes:
+  /:
+    description: Home page rendered by a function and the shared template
+    middleware:
+      - source: middleware/template.mjs
+        export: template
+    function:
+      source: functions/page.mjs
+      export: page
+      args:
+        title: URLCode prerender
+        body: |
+          <p>This page is generated by a function and wrapped by shared template
+          middleware. Running the prerender recipe turns it into a native page
+          route that serves the same bytes with no sandbox on the request path.</p>
+          <ul>
+            <li><a href="/guide">Guide</a></li>
+            <li><a href="/about">About</a></li>
+          </ul>
+  /guide:
+    description: A second page reusing the same function and template
+    middleware:
+      - source: middleware/template.mjs
+        export: template
+    function:
+      source: functions/page.mjs
+      export: page
+      args:
+        title: Guide
+        body: |
+          <p>Content is reviewed literal input in YAML. Guest code never reads the
+          filesystem, so a larger site generates this project from host-prepared
+          content before rendering.</p>
+  /about:
+    description: A third page proving the template is shared, not copied
+    middleware:
+      - source: middleware/template.mjs
+        export: template
+    function:
+      source: functions/page.mjs
+      export: page
+      args:
+        title: About & "quoting"
+        body: |
+          <p>The title above is escaped by the template, so page data cannot inject
+          markup into the surrounding document.</p>

package/examples/tunnel/dev-with-ngrok.sh

@@ -0,0 +1,61 @@
+#!/bin/sh
+# Start `urlcode dev` with the public origin of an ngrok tunnel that is already
+# running, so functions, redirects and absolute URLs see the address a visitor
+# actually used rather than 127.0.0.1.
+#
+#   Terminal 1:  ngrok http 3000
+#   Terminal 2:  PROJECT=. ./dev-with-ngrok.sh
+#
+# This script discovers a tunnel; it does not start, stop or configure ngrok.
+# That keeps it honest about what it controls and leaves the tunnel's own
+# authentication and access policy where it belongs: in ngrok.
+set -eu
+
+PROJECT=${PROJECT:-.}
+PORT=${PORT:-3000}
+URLCODE=${URLCODE:-urlcode}
+# The ngrok agent's local inspection API. Overridable for a different agent port
+# or for this repository's test, which serves a recorded response.
+NGROK_API=${URLCODE_NGROK_API:-http://127.0.0.1:4040/api/tunnels}
+PRINT_ONLY=0
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --print) PRINT_ONLY=1; shift ;;
+    --help|-h) sed -n '2,11p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    *) echo "dev-with-ngrok: unknown option $1" >&2; exit 2 ;;
+  esac
+done
+
+command -v node >/dev/null 2>&1 || { echo "dev-with-ngrok: node is required" >&2; exit 1; }
+
+# Select the HTTPS tunnel that forwards to this port. Anything else is a
+# different tunnel on the same agent and must not be guessed at.
+ORIGIN=$(NGROK_API="$NGROK_API" PORT="$PORT" node -e '
+  const api = process.env.NGROK_API, port = process.env.PORT;
+  fetch(api, {headers:{accept:"application/json"}})
+    .then(r => r.ok ? r.json() : Promise.reject(new Error("HTTP " + r.status)))
+    .then(body => {
+      const tunnels = Array.isArray(body?.tunnels) ? body.tunnels : [];
+      const match = tunnels.find(t =>
+        typeof t?.public_url === "string" && t.public_url.startsWith("https://") &&
+        typeof t?.config?.addr === "string" && new RegExp(`(^|[^0-9])${port}$`).test(t.config.addr));
+      if (!match) throw new Error(`no https tunnel forwarding to port ${port}`);
+      const url = new URL(match.public_url);
+      if (url.origin !== match.public_url.replace(/\/$/,"")) throw new Error("tunnel URL is not a bare origin");
+      process.stdout.write(url.origin);
+    })
+    .catch(e => { console.error("dev-with-ngrok: " + e.message); process.exit(1); });
+') || {
+  echo "dev-with-ngrok: could not read a tunnel from $NGROK_API" >&2
+  echo "  start one first, e.g.  ngrok http $PORT" >&2
+  exit 1
+}
+
+echo "dev-with-ngrok: public origin $ORIGIN"
+if [ "$PRINT_ONLY" -eq 1 ]; then exit 0; fi
+
+# dev loads .env.local and watches files. A tunnel makes that reachable from the
+# internet: expose a development project only deliberately, and never tunnel the
+# separate link-management API.
+exec "$URLCODE" dev --project "$PROJECT" --port "$PORT" --origin "$ORIGIN"

package/examples/vercel/README.md

@@ -0,0 +1,13 @@
+# URLCode on Vercel
+
+A native-handler project deployed as a Vercel Node function. See
+[the adapter guide](../../docs/VERCEL.md) for what is and is not supported.
+
+```sh
+urlcode test --project .     # the same assertions run locally
+vercel deploy
+```
+
+`vercel.json` rewrites every path to `api/index.js`, which serves the project
+with `createVercelHandler`. `includeFiles` must list every file the project
+reads; add to it when you add a page, download or static directory.

package/examples/vercel/api/index.js

@@ -0,0 +1,5 @@
+// Every request is rewritten here by vercel.json. The handler is created once
+// per instance and reused across warm invocations.
+import { createVercelHandler } from '@jimhoyd/urlcode/vercel';
+
+export default createVercelHandler({ project: process.cwd() });

package/examples/vercel/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "urlcode-vercel-example",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "@jimhoyd/urlcode": "^0.3.0"
+  }
+}

package/examples/vercel/public/index.html

@@ -0,0 +1,3 @@
+<!doctype html>
+<html lang="en"><meta charset="utf-8"><title>URLCode on Vercel</title>
+<body><h1>URLCode on Vercel</h1><p>Native handlers served by the runtime adapter.</p></body>

package/examples/vercel/public/notes.txt

@@ -0,0 +1 @@
+Served by the static handler through the Vercel adapter.

package/examples/vercel/tests/requests.json

@@ -0,0 +1,48 @@
+[
+  {
+    "path": "/go",
+    "status": 302,
+    "expectHeaders": {
+      "location": "https://example.com/target"
+    }
+  },
+  {
+    "path": "/u/42",
+    "status": 302,
+    "expectHeaders": {
+      "location": "https://example.com/users/42"
+    }
+  },
+  {
+    "path": "/health",
+    "status": 200,
+    "expectBody": "{\"ok\":true}"
+  },
+  {
+    "path": "/",
+    "status": 200,
+    "expectHeaders": {
+      "content-type": "text/html; charset=utf-8"
+    }
+  },
+  {
+    "path": "/files/notes.txt",
+    "status": 200,
+    "expectHeaders": {
+      "content-type": "text/plain; charset=utf-8"
+    }
+  },
+  {
+    "path": "/nothing-here",
+    "status": 404
+  },
+  {
+    "path": "/u/42",
+    "method": "HEAD",
+    "status": 302,
+    "expectHeaders": {
+      "location": "https://example.com/users/42"
+    },
+    "expectBody": ""
+  }
+]

package/examples/vercel/urlcode.yaml

@@ -0,0 +1,19 @@
+version: "1"
+routes:
+  /go:
+    redirect:
+      url: https://example.com/target
+  /u/{id}:
+    parameters:
+      - {name: id, in: path, required: true, schema: {type: string}}
+    redirect:
+      url: https://example.com/users/{id}
+  /health:
+    respond:
+      json: {ok: true}
+  /:
+    page:
+      file: public/index.html
+  /files/*:
+    static:
+      directory: public

package/examples/vercel/vercel.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://openapi.vercel.sh/vercel.json",
+  "functions": {
+    "api/index.js": {
+      "runtime": "nodejs22.x",
+      "includeFiles": "{urlcode.yaml,routes/**,public/**}"
+    }
+  },
+  "rewrites": [{ "source": "/(.*)", "destination": "/api" }]
+}

package/llms.txt

@@ -0,0 +1,46 @@
+# URLCode
+
+> Portable YAML-defined URLs that run code. Current contract: 0.1.0,
+> stable project format version "1". Local/self-hosted first; provider adapters are future.
+
+Use the schema and docs from the same runtime revision. Do not assume Node/fetch,
+regex routes, database access, global middleware or arbitrary YAML interpolation.
+The runtime is licensed under Apache-2.0. Secrets require external revision-pinned grants.
+
+## Authoring
+- [AI authoring contract](docs/AI-AUTHORING.md): workflow, capability matrix, checks.
+- [YAML guide](docs/YAML-GUIDE.md): recipes for all handlers and common options.
+- [JSON Schema](schemas/urlcode.schema.json): accepted fields and types.
+- [Field reference](docs/YAML-REFERENCE.md): generated exhaustive field inventory.
+- [Semantics](docs/SPECIFICATION.md): validation, defaults and sandbox API.
+- [Runnable cookbook](examples/cookbook/README.md): 25 routes with HTTP fixtures.
+- [Dynamic links](docs/DYNAMIC-LINKS.md): optional SQLite, live mutations, management API and limits.
+- [Route matching](docs/ROUTING.md): precedence, non-greedy parameters, updates.
+- [Middleware](docs/MIDDLEWARE.md): next(), state, ordering and native body limits.
+- [Policies](docs/POLICIES.md): optional host-enforced `policies`/`profiles` keys, all off by default: `throttle`, `agents`, `security`, `compression`, `cache`; merge rules and per-target support.
+- [Plugins](docs/PLUGINS.md): host hook API operators pass in code; never named in YAML.
+- [TypeScript](docs/TYPESCRIPT.md): the package ships declarations for every export (`urlcode`, `@jimhoyd/urlcode/plugins`, `@jimhoyd/urlcode/policies`, `@jimhoyd/urlcode/observability`, `@jimhoyd/urlcode/compliance`, `@jimhoyd/urlcode/prerender`, `@jimhoyd/urlcode/aws`, `@jimhoyd/urlcode/vercel`, `@jimhoyd/urlcode/cloudflare`); the runtime source is TypeScript, `dist/` is its stripped JavaScript.
+- [HTTP](docs/HTTP.md): methods, request bodies and response headers.
+- [Assets](docs/ASSETS.md): pages, MIME, downloads, cache and ranges.
+- [Site conventions](docs/SITE.md): optional top-level `site` key, all off by default: `robots`, `sitemap`, `favicon`, `securityTxt`, `llms` generate native routes; declared routes win; absolute URLs need `--origin`.
+- [Prerendering](docs/PRERENDER.md): `@jimhoyd/urlcode/prerender` build helper and recipe; render function/middleware routes once into native page routes, no request-time guest code.
+- [Organization](docs/ORGANIZATION.md): entry point and included files.
+
+- [Best practices](docs/BEST-PRACTICES.md): layouts, readable YAML/code, testing and refactoring.
+
+## Operations
+- [Security](docs/FUNCTION-SECURITY.md): untrusted code and external binding policy.
+- [Readiness](docs/READINESS.md): fixture coverage and count checks.
+- [Capacity](docs/CAPACITY.md): concurrency, limits and theoretical sizing.
+- [Resilience](docs/RESILIENCE.md): DDoS, overload, incident and recovery plans.
+- [Operations](docs/OPERATIONS.md): deploy, observe, rotate and roll back.
+- [Performance](docs/PERFORMANCE.md): measured results and their limitations.
+- [Roadmap](ROADMAP.md): clearly separates implemented and planned features.
+
+- [Release readiness](docs/RELEASE-READINESS.md): verified safeguards, open gates and supported deployment scope.
+
+- [Scaffolding](docs/SCAFFOLDING.md): generate missing placeholders from YAML, preserve existing files, fail-closed code stubs.
+
+Security hardening: docs/MANAGEMENT-SECURITY.md, docs/SANDBOX-REVIEW.md,
+docs/OPERATIONAL-PROOF.md and docs/RELEASE-SECURITY.md describe private operator
+management, resource limits, acceptance evidence and signed alpha candidates.

package/package.json

@@ -0,0 +1,123 @@
+{
+  "name": "@jimhoyd/urlcode",
+  "version": "0.3.0",
+  "description": "Portable runtime for programmable URL behavior",
+  "type": "module",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "devEngines": {
+    "runtime": {
+      "name": "node",
+      "version": ">=22.18.0",
+      "onFail": "error"
+    }
+  },
+  "bin": {
+    "urlcode": "./dist/cli.js"
+  },
+  "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"
+    }
+  },
+  "files": [
+    "dist",
+    "schemas",
+    "data",
+    "starters",
+    "README.md",
+    "docs",
+    "SECURITY.md",
+    "ROADMAP.md",
+    "CONTRIBUTING.md",
+    "examples",
+    "llms.txt",
+    "NOTICE"
+  ],
+  "scripts": {
+    "build": "node --disable-warning=ExperimentalWarning scripts/build.ts",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "node --conditions=development --test test/*.test.ts",
+    "lint": "eslint .",
+    "check": "node scripts/check.ts && node scripts/generate-yaml-reference.ts --check",
+    "verify": "npm run lint && npm run typecheck && npm run check && npm run build && npm test",
+    "benchmark": "node benchmarks/routing.ts",
+    "test:package": "npm run build && node scripts/package-smoke.ts",
+    "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",
+    "test:project": "node src/cli.ts test --project starters/default",
+    "init": "node src/cli.ts init",
+    "doctor": "node src/cli.ts doctor",
+    "routes": "node src/cli.ts routes --project starters/default",
+    "audit:routes": "node src/cli.ts audit --project starters/default",
+    "benchmark:project": "node src/cli.ts benchmark --project starters/default",
+    "docs:reference": "node scripts/generate-yaml-reference.ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jimhoyd-com/urlcode.git"
+  },
+  "dependencies": {
+    "ajv": "8.20.0",
+    "content-disposition": "3.0.0",
+    "es-module-lexer": "3.0.2",
+    "mime-types": "3.0.2",
+    "quickjs-emscripten": "0.32.0",
+    "yaml": "2.9.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "10.0.1",
+    "@types/mime-types": "3.0.1",
+    "@types/node": "22.20.3",
+    "eslint": "10.10.0",
+    "globals": "17.12.0",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.70.0"
+  }
+}