@jimhoyd/urlcode 0.3.0 → 0.4.0-alpha.2

package/skills/urlcode/SKILL.md

@@ -0,0 +1,119 @@
+---
+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, 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.
+
+## 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.
+
+## 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. Choose the highest-level supported abstraction
+
+1. If a native handler expresses the behavior (`redirect`, `respond`, `page`,
+   `static`, `download`, `proxy`, `conditional`), write YAML only.
+2. Check supported extensions and their configuration before custom code. 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`. `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 (untrusted input, an unreviewed contribution, a
+   particularly sensitive secret) — a `sandbox: true` route then has no
+   `fetch`, Node, npm, filesystem, WebSocket, streaming, crypto API or timers;
+   a need for those in a sandboxed route is a `proxy` route, a binding, or a
+   report.
+4. Declare routing, validation, middleware chains, policies, static serving,
+   caching, throttling and authentication wherever the runtime or a supported
+   extension provides them. Use custom code only for the unmet requirement.
+   Where a short form exists, it is the highest-level form: `auth: true` or
+   `auth: { role: admin }` on a route whose project declares an `auth`
+   extension, and `cache: { … }` for `policies.cache`. Each expands to the long
+   form; declaring both is refused.
+
+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. 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
+
+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.
+
+## 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.
+- 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; a missing one is a report, not an
+invitation to reimplement it.
+
+## Functions and middleware are trusted by default; sandbox is opt-in
+
+A route's `function`/`middleware` code runs trusted, in-process, with full
+Node/filesystem/`fetch` access, receiving only the declared/granted `args`
+and `env`/`secrets`. Add `sandbox: true` when code warrants isolation
+(untrusted input, an unreviewed contribution, an especially sensitive
+secret): that route then gets a text/JSON subset only, no Node/filesystem/
+outside imports — use `proxy`/a binding instead, and say why in `description`.
+
+## Checks that count as evidence
+
+```sh
+urlcode validate --local
+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`.
+
+## 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.
+- 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.
+
+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`).

package/starters/default/urlcode.yaml

@@ -1,7 +1,6 @@
 # yaml-language-server: $schema=https://raw.githubusercontent.com/jimhoyd-com/urlcode/669632fb4f188f293a0f622847f87ee019c0627f/schemas/urlcode.schema.json
 # Organize files however you like; list their paths from this project root.
 version: "1"
-dynamicLinks: false
 includes:
   - routes/functions.yaml
   - routes/marketing/links.yaml

package/dist/link-api.js

@@ -1,136 +0,0 @@
-import http from 'node:http';
-import {createHash,timingSafeEqual,randomUUID} from 'node:crypto';
-import {readFile,lstat} from 'node:fs/promises';
-                                          
-import {outsideProject} from './link-store.js';
-                                                                       
-                                                                                     
-import {linkCollection,linkCode} from './link-records.js';
-import {assert,HttpError} from './errors.js';
-import {createJsonLogger} from './logging.js';
-                                      
-/** The store surface management needs: the pooled link store, or anything with the same contract. */
-                                  
-                                 
-                                                              
-                                                                     
-                                                                                                            
-                                                                                                                                   
-                                                                                                                     
- 
-                                 
-                                                                                                                   
-                                                                                                                                                      
- 
-                                                                         
-export async function loadLinkToken(file         ,project        )                  {
-  const path=await outsideProject(file,project);const info=await lstat(path);
-  assert(info.isFile()&&!info.isSymbolicLink()&&info.nlink===1&&info.size<=1024,'Invalid management token file');
-  assert(process.platform==='win32'||(info.mode&0o077)===0,'Management token file must be private (mode 600)');
-  const token=(await readFile(path,'utf8')).trim();
-  assert(/^[A-Za-z0-9_-]{43,256}$/.test(token),'Management token must contain at least 43 base64url characters');return token;
-}
-function body(req                      )                   {
-  return new Promise((resolve,reject)=>{
-    let bytes=0;const chunks          =[];
-    const cleanup=()=>{req.off('data',data);req.off('end',end);req.off('error',failed);req.off('aborted',failed);};
-    const failed=()=>{cleanup();reject(new HttpError(400,'Incomplete management body'));};
-    const data=(chunk        )=>{
-      bytes+=chunk.length;
-      if(bytes>16384){cleanup();req.resume();reject(new HttpError(413,'Management body too large'));return;}
-      chunks.push(chunk);
-    };
-    const end=()=>{
-      cleanup();
-      if(!bytes){reject(new HttpError(400,'JSON body required'));return;}
-      try{resolve(JSON.parse(new TextDecoder('utf-8',{fatal:true}).decode(Buffer.concat(chunks))));}
-      catch{reject(new HttpError(400,'Invalid JSON body'));}
-    };
-    req.on('data',data);req.once('end',end);req.once('error',failed);req.once('aborted',failed);
-  });
-}
-const isRecord=(value         )                                 =>value!==null && typeof value==='object' && !Array.isArray(value);
-const mutations                                 ={POST:'create',PUT:'update',DELETE:'delete'};
-export async function startLinkApi({store,collection,token,authorize,host='127.0.0.1',port=3001,maxInFlightRequests=32,socketTimeoutMs=10000,log=createJsonLogger()}                )                   {
-  linkCollection(collection);assert(['127.0.0.1','::1'].includes(host),'Management must bind a literal loopback address; use a private authenticated tunnel');
-  assert(!authorize || store.atomicAudit===true,'Scoped management requires a store with atomic audit support');
-  assert(authorize===undefined || typeof authorize==='function','Invalid management authorizer');
-  assert(authorize || typeof token==='string'&&/^[A-Za-z0-9_-]{43,256}$/.test(token),'Invalid management token');
-  assert(Number.isInteger(maxInFlightRequests)&&maxInFlightRequests>=1&&maxInFlightRequests<=64,'Management admission must be 1–64');
-  assert(Number.isInteger(socketTimeoutMs)&&socketTimeoutMs>=100&&socketTimeoutMs<=60000,'Management socket timeout must be 100–60000 ms');
-  let inFlight=0,shuttingDown=false,closing                         ;
-  const digest=(value        )=>createHash('sha256').update(value).digest();const expected=digest('Bearer '+token);
-  const server=http.createServer({maxHeaderSize:8192,headersTimeout:5000,requestTimeout:10000,keepAliveTimeout:5000},async(req,res)=>{
-    req.on('error',()=>{});res.on('error',()=>{});
-    const requestId=randomUUID(),started=performance.now();let principal                               ;let authenticated=false,action='request',admitted=false,reported=false;
-    const target=req.url??'',method=req.method??'';
-    const report=()=>{
-      if(reported)return;reported=true;if(admitted)inFlight--;
-      try{log({event:'management_request',timestamp:new Date().toISOString(),requestId,collection,action,authenticated,principal:principal?.id,status:res.headersSent?res.statusCode:0,outcome:res.writableFinished?'finished':'aborted',durationMs:Math.round((performance.now()-started)*100)/100});}catch{/* Logging must not fail requests. */}
-    };
-    res.once('finish',report);res.once('close',report);
-    const send=(status        ,value          ,headers                          ={})=>{const payload=value===undefined?undefined:JSON.stringify(value);res.writeHead(status,{'content-type':'application/json','cache-control':'no-store','x-content-type-options':'nosniff','x-request-id':requestId,...headers});res.end(payload);};
-    try {
-      if(shuttingDown || inFlight>=maxInFlightRequests)throw new HttpError(503,'Management capacity unavailable');
-      inFlight++;admitted=true;
-      let authCount=0;for(let i=0;i<req.rawHeaders.length;i+=2)if(req.rawHeaders[i]?.toLowerCase()==='authorization')authCount++;
-      if(authCount===1){
-        if(authorize){
-          const bearer=/^Bearer ([A-Za-z0-9_-]{43,256})$/.exec(req.headers.authorization||'');
-          if(bearer?.[1]!==undefined)principal=await authorize(bearer[1]);
-        }else if(timingSafeEqual(expected,digest(req.headers.authorization||'')))principal={id:'legacy-shared',collections:[collection],actions:['get','list','create','update','delete']};
-      }
-      if(!principal) {req.resume();send(401,{error:'Unauthorized'},{'www-authenticate':'Bearer',connection:'close'});return;}
-      authenticated=true;
-      if(req.headers.origin!==undefined)throw new HttpError(403,'Browser-origin management requests are unsupported');
-      if(!target.startsWith('/')||target.startsWith('//')||target.length>2048)throw new HttpError(400,'Invalid management target');
-      const url=new URL(target,'http://localhost');
-      if(target.split('?')[0]!==url.pathname)throw new HttpError(400,'Noncanonical management path');
-      const match=/^\/v1\/links(?:\/([A-Za-z0-9_-]{1,128}))?$/.exec(url.pathname);
-      if(!match)throw new HttpError(404,'Not found');
-      const code=match[1];if(code)linkCode(code);
-      if([...url.searchParams.keys()].some(k=>!['limit','after'].includes(k)) || (code && url.search))throw new HttpError(400,'Unsupported query');
-      const allowed=code?['GET','PUT','DELETE']:['GET','POST'];
-      if(!allowed.includes(method)){req.resume();send(405,{error:'Method not allowed'},{allow:allowed.join(', '),connection:'close'});return;}
-      action=method==='GET'?(code?'get':'list'):mutations[method]??'request';
-      if(!principal.collections.includes(collection) || !principal.actions.includes(action))throw new HttpError(403,'Management permission denied');
-      const audit               ={actor:principal.id,requestId};
-      if(method==='GET'){
-        req.resume();
-        if(code){const value=await store.get(collection,code);if(!value)throw new HttpError(404,'Link not found');send(200,value,{etag:`"${value.version}"`});}
-        else {
-          if([...url.searchParams.keys()].some(k=>url.searchParams.getAll(k).length!==1))throw new HttpError(400,'Duplicate query');
-          const raw=url.searchParams.get('limit')??'100';if(!/^\d{1,3}$/.test(raw))throw new HttpError(400,'Invalid limit');
-          const items=await store.list(collection,{limit:Number(raw),after:url.searchParams.get('after')||''});
-          send(200,{items,nextAfter:items.length===Number(raw)?items.at(-1)?.code??null:null});
-        }
-        return;
-      }
-      if(url.search)throw new HttpError(400,'Query unsupported for mutations');
-      let expectedVersion                  ;
-      if(method!=='POST'){
-        const etag=req.headers['if-match'];if(!etag)throw new HttpError(428,'If-Match is required');
-        if(!/^"[1-9]\d{0,15}"$/.test(etag))throw new HttpError(400,'Invalid If-Match');expectedVersion=Number(etag.slice(1,-1));
-      }
-      if(method==='DELETE'){req.resume();await store.delete(collection,code??'',expectedVersion,audit);send(204);return;}
-      if(req.headers['content-encoding'] && req.headers['content-encoding']!=='identity')throw new HttpError(415,'Encoding unsupported');
-      if(req.headers['content-type']?.split(';')[0]?.trim().toLowerCase()!=='application/json')throw new HttpError(415,'Expected application/json');
-      const data=await body(req);
-      if(!isRecord(data))throw new HttpError(400,'Invalid record');
-      let value         ;
-      if(method==='POST'){const {code:assigned,...record}=data;value=await store.create(collection,record,assigned,audit);}
-      else value=await store.update(collection,code??'',data,expectedVersion,audit);
-      send(method==='POST'?201:200,value,{etag:`"${value.version}"`});
-    }catch(e){req.resume();if(res.headersSent){res.destroy();return;}if(!res.destroyed){const status=e instanceof HttpError?e.status:503;send(status,{error:e instanceof HttpError?e.message:'Management service unavailable'},{connection:'close'});}}
-  });
-  server.setTimeout(socketTimeoutMs,socket=>socket.destroy());
-  server.maxConnections=64;server.maxRequestsPerSocket=100;
-  server.on('clientError',(_error,socket)=>{if(socket.writable)socket.end('HTTP/1.1 400 Bad Request\r\nConnection: close\r\nContent-Length: 0\r\n\r\n');});
-  await new Promise      ((resolve,reject)=>{server.once('error',reject);server.listen(port,host,()=>{server.off('error',reject);resolve();});});
-  const address=server.address();
-  assert(address!==null && typeof address==='object','Management server has no address');
-  return {address,close(){
-    if(closing)return closing;shuttingDown=true;
-    closing=(async()=>{const timeout=setTimeout(()=>server.closeAllConnections(),10000);timeout.unref();try{await new Promise      (resolve=>server.close(()=>resolve()));}finally{clearTimeout(timeout);}})();return closing;
-  }};
-}

package/dist/link-cli.js

@@ -1,141 +0,0 @@
-import {createHash} from 'node:crypto';
-import {createReadStream} from 'node:fs';
-import {createInterface} from 'node:readline';
-import {isAbsolute} from 'node:path';
-import {managementPolicy} from './management-policy.js';
-import {openLinkStore} from './link-store.js';
-                                                                
-import {startLinkApi,loadLinkToken} from './link-api.js';
-import {linkCollection,linkCode,linkData} from './link-records.js';
-import {assert} from './errors.js';
-/** The parsed command-line values the links commands read; every flag is a string or absent. */
-                                    
-                                                                                                               
-                                                                                                                    
-                                                                                                                                                
-                                                                                                                    
-                                                                                                                 
- 
-                                            
-                                                                                            
-                                                                                         
-const poolFlags=[['link-readers','readers',8],['link-read-limit','maxReads',32],['link-write-limit','maxWrites',32]]         ;
-export function linkPoolOptions(values                   )                  {
-  const result                 ={};
-  for(const [flag,key,max] of poolFlags){
-    const value=values[flag];
-    if(value===undefined)continue;
-    assert(/^\d+$/.test(value)&&Number(value)>=1&&Number(value)<=max,`Invalid --${flag}`);result[key]=Number(value);
-  }
-  return result;
-}
-export function parseLinkBinding(value                  ,options                 ={})                        {
-  if(value===undefined)return undefined;
-  const index=value.indexOf('=');assert(index>0,'Use --link-store collection=/absolute/path.sqlite');
-  return {collection:linkCollection(value.slice(0,index)),file:value.slice(index+1),...options};
-}
-const isRecord=(value         )                                 =>value!==null && typeof value==='object' && !Array.isArray(value);
-export async function runLinkCommand(action                  ,values                   ,print       )                {
-  assert(action!==undefined && ['init','create','get','list','update','delete','export','import','api'].includes(action),'Use links init/create/get/list/update/delete/export/import/api');
-  assert(values.store,'Links commands require --store with an absolute database path');
-  const collection=linkCollection(values.collection||'links');
-  const poolOptions=linkPoolOptions(values);
-  // Authentication material is checked before creating or opening a writable store.
-  if(values['auth-file'] && values['token-file'])throw new Error('Use either --auth-file or --token-file');
-  const project=values.project??'.';
-  const authorize=action==='api' && values['auth-file']?await managementPolicy(values['auth-file'],project):undefined;
-  if(authorize)await authorize('');
-  const token=action==='api' && !authorize?await loadLinkToken(values['token-file'],project):undefined;
-  const storeOptions                  ={file:values.store,project:values.project,readOnly:['get','list','export'].includes(action),...poolOptions};
-  const store=await openLinkStore(storeOptions);
-  try {
-    if(action==='api'){
-      const port=Number(values.port);assert(values.port!==undefined&&/^\d+$/.test(values.port)&&port>=0&&port<=65535,'Invalid port');
-      const api=await startLinkApi({store,collection,token,authorize,host:values.host,port});
-      print({event:'link-management-listening',address:api.address.address,port:api.address.port,collection});
-      await new Promise      (resolve=>{
-        const stop=()=>{process.off('SIGINT',stop);process.off('SIGTERM',stop);resolve();};
-        process.once('SIGINT',stop);process.once('SIGTERM',stop);
-      });
-      await api.close();return;
-    }
-    let value         ;
-    if(action==='init')value={event:'link-store-initialized'};
-    if(action==='get'){value=await store.get(collection,values.code??'');assert(value,'Link not found');}
-    if(action==='list')value=await store.list(collection,{limit:values.limit===undefined?100:Number(values.limit),after:values.after||''});
-    if(action==='create'||action==='update'){
-      assert(values.destination,'Use --destination with an HTTP(S) URL');
-      assert(values.enabled===undefined||['true','false'].includes(values.enabled),'Enabled must be true or false');
-      const data={url:values.destination,status:values.status===undefined?302:Number(values.status),enabled:values.enabled!=='false',expires:values.expires||null};
-      value=action==='create'?await store.create(collection,data,values.code):await store.update(collection,values.code??'',data,Number(values['if-version']));
-    }
-    if(action==='delete')value={deleted:await store.delete(collection,values.code??'',Number(values['if-version']))};
-    // Export and import stream their own NDJSON; they never buffer the store.
-    if(action==='export'){await exportLinks(store,values,print);return;}
-    if(action==='import'){print(await importLinks(store,values));return;}
-    print(value);
-  }finally{await store.close();}
-}
-
-// A restorable point-in-time snapshot: a header line carrying format, schema and
-// snapshot identity, one line per record, and a completion line with the record
-// count and a digest over every preceding line. Operator data goes to stdout
-// deliberately; redirect it to a file only operators can read.
-async function exportLinks(store           ,values                   ,print       )                {
-  const pageSize=values['page-size']===undefined?100:Number(values['page-size']);
-  assert(Number.isInteger(pageSize)&&pageSize>=1&&pageSize<=100,'Use --page-size 1–100');
-  const hash=createHash('sha256');
-  const line=(value         )=>{hash.update(JSON.stringify(value)+'\n');print(value);};
-  const summary=await store.exportSnapshot(
-    {collection:values.collection===undefined?undefined:linkCollection(values.collection),pageSize},
-    {
-      onHeader:header=>line({event:'link-export-begin',format:header.format,schemaVersion:header.schemaVersion,
-        applicationId:header.applicationId,collection:header.collection,revision:header.revision,
-        records:header.records,generatedAt:header.generatedAt}),
-      onRecords:records=>{for(const record of records)line({record});},
-    });
-  print({event:'link-export-complete',exported:summary.exported,sha256:hash.digest('hex')});
-}
-async function importLinks(store           ,values                   )                  {
-  assert(typeof values.input==='string' && isAbsolute(values.input),'Use --input with an absolute export file path');
-  const hash=createHash('sha256');
-  const counts=new Map               ();let imported=0,header                                  ,complete                                  ;
-  const stream=createReadStream(values.input,{encoding:'utf8'});
-  try {
-    for await (const text of createInterface({input:stream,crlfDelay:Infinity})) {
-      if(text==='')continue;
-      assert(Buffer.byteLength(text)<=65536,'Export line exceeds 65536 bytes');
-      assert(!complete,'Export file has content after its completion line');
-      let parsed         ;try{parsed=JSON.parse(text);}catch{throw new Error('Export file is not valid NDJSON');}
-      const line                        =isRecord(parsed)?parsed:{};
-      if(line.event==='link-export-complete'){
-        assert(header,'Export file has no header line');
-        assert(hash.copy().digest('hex')===line.sha256,'Export digest does not match its content');
-        assert(line.exported===imported,'Export record count does not match its record lines');
-        complete=line;continue;
-      }
-      hash.update(text+'\n');
-      if(line.event==='link-export-begin'){
-        assert(!header && !imported,'Export file has more than one header line');
-        assert(line.format==='urlcode.links.v1' && line.schemaVersion===1 && line.applicationId===1431456835,
-          'Unsupported export format, schema version or store identity');
-        header=line;continue;
-      }
-      assert(header,'Export records precede the header line');
-      assert(isRecord(line.record),'Unsupported export line');
-      const collection=linkCollection(line.record.collection),code=linkCode(line.record.code);
-      // Restore into empty collections only: this never overwrites live records.
-      if(!counts.has(collection)){
-        assert((await store.list(collection,{limit:1})).length===0,'Target collection already contains records');
-        counts.set(collection,0);
-      }
-      await store.create(collection,linkData({url:line.record.url,status:line.record.status,enabled:line.record.enabled,expires:line.record.expires}),code);
-      counts.set(collection,(counts.get(collection)??0)+1);imported++;
-    }
-  } finally { stream.destroy(); }
-  assert(complete,'Export file has no completion line; it is truncated');
-  // Versions and audit revisions are reassigned by this store, so management
-  // ETags taken against the exported database do not survive a restore.
-  return {event:'link-import-complete',imported,collections:Object.fromEntries(counts),
-    source:{revision:header?.revision,generatedAt:header?.generatedAt,sha256:complete.sha256},versionsReassigned:true};
-}

package/dist/link-events.js

@@ -1,76 +0,0 @@
-import {assert} from './errors.js';
-
-                                                                                              
-                                                                                                                                             
-                                                                                                                                            
-                                                                                                                               
-                                                    
-
-// Trusted-operator observation of finished link requests. The observer is
-// supplied by the embedding operator process, never by route YAML or guest
-// code, and it runs after the response is over: it can never change, delay or
-// fail a redirect. Work is bounded by an explicit queue; overload drops events
-// and counts the drops rather than growing memory behind the operator's back.
-const outcomes=new Set(['completed','aborted','missing','disabled','expired','invalid_code','invalid_record','unavailable']);
-export function createLinkObserver(options         , log      = () => {})                           {
-  if(options===undefined)return undefined;
-  assert(options && typeof options==='object' && !Array.isArray(options),'Link events must be an options object');
-  const {observe,includeCode=false,maxQueue=256,timeoutMs=1000}=options                                ;
-  assert(Object.keys(options).every(key=>['observe','includeCode','maxQueue','timeoutMs'].includes(key)),'Unsupported link event option');
-  assert(typeof observe==='function','Link events require an observe(event) function');
-  assert(typeof includeCode==='boolean','Link event code disclosure must be a boolean');
-  assert(Number.isInteger(maxQueue)&&maxQueue>=1&&maxQueue<=4096,'Link event queue must be 1–4096');
-  assert(Number.isInteger(timeoutMs)&&timeoutMs>=1&&timeoutMs<=10000,'Link event timeout must be 1–10000 ms');
-  const queue             =[];
-  let delivered=0,dropped=0,failed=0,timedOut=0,closed=false,draining                         ;
-  const report     =event=>{try{log(event);}catch{/* Logging cannot fail the observer. */}};
-  async function deliver(event           )                {
-    let timer                                         ;
-    try {
-      // A slow collector must not pin the queue: the budget is per event and the
-      // observer keeps running afterwards, whatever the abandoned call does.
-      await Promise.race([
-        Promise.resolve(observe (event)),
-        new Promise((_resolve,reject)=>{timer=setTimeout(()=>reject(new Error('timeout')),timeoutMs);timer.unref?.();}),
-      ]);
-      delivered++;
-    } catch(error) {
-      failed++;
-      const timeout=(error                                      )?.message==='timeout';
-      if(timeout)timedOut++;
-      report({event:'link_observer',status:'failed',reason:timeout?'timeout':'error'});
-    } finally { clearTimeout(timer); }
-  }
-  async function pump()                {
-    if(draining)return;
-    draining=(async()=>{while(queue.length)await deliver(queue.shift() );})();
-    try{await draining;}finally{draining=undefined;}
-  }
-  return {
-    // Called from the request path. It must stay synchronous and total.
-    emit(event           )       {
-      try {
-        if(closed||!outcomes.has(event.outcome)){dropped++;return;}
-        if(queue.length>=maxQueue){
-          dropped++;
-          if(dropped===1||dropped%maxQueue===0)report({event:'link_observer',status:'dropped',dropped});
-          return;
-        }
-        const {code:_code,...redacted}=event;
-        queue.push(includeCode?{...event}:redacted);
-        void pump();
-      } catch { dropped++; }
-    },
-    stats:()=>({queued:queue.length,delivered,dropped,failed,timedOut,closed}),
-    async close()                             {
-      closed=true;
-      // Drain what was already accepted, then stop; a stuck collector cannot
-      // hold shutdown open past its own per-event budget plus this deadline.
-      void pump();
-      const deadline=new Promise         (resolve=>{const timer=setTimeout(()=>resolve(false),timeoutMs*2+1000);timer.unref?.();});
-      while(draining)if(!await Promise.race([draining.then(()=>true,()=>true),deadline]))break;
-      dropped+=queue.length;queue.length=0;
-      return this.stats();
-    },
-  };
-}

package/dist/link-records.js

@@ -1,31 +0,0 @@
-import {randomBytes} from 'node:crypto';
-import {HttpError} from './errors.js';
-                                                                                                     
-const check                                                     = (value,message) => { if(!value)throw new HttpError(400,message); };
-export function linkCollection(value         )         {
-  check(typeof value==='string' && /^[A-Za-z][A-Za-z0-9_-]{0,63}$/.test(value),'Invalid link collection');return value;
-}
-export function linkCode(value         )         {
-  check(typeof value==='string' && /^[A-Za-z0-9_-]{1,128}$/.test(value),'Invalid short code');return value;
-}
-export function linkVersion(value         )         {
-  check(typeof value==='number' && Number.isSafeInteger(value) && value>0,'A positive expected version is required');return value;
-}
-export function linkData(value         )             {
-  check(value && typeof value==='object' && !Array.isArray(value),'Invalid link record');
-  check(Object.keys(value).every(k=>['url','status','enabled','expires'].includes(k)),'Unsupported link field');
-  const record=value                                                                           ;
-  check(typeof record.url==='string' && record.url.length<=8192 && !/[\s\u0000-\u001f\u007f\\]/u.test(record.url),'Invalid destination');
-  let url     ;try{url=new URL(record.url);}catch{throw new HttpError(400,'Invalid destination');}
-  check(['http:','https:'].includes(url.protocol) && !url.username && !url.password,'Destination must be HTTP(S) without credentials');
-  check(Buffer.byteLength(url.href)<=8192,'Destination exceeds 8192 bytes');
-  const status=record.status??302,enabled=record.enabled??true,expires=record.expires??null;
-  check(typeof status==='number' && [301,302,303,307,308].includes(status),'Invalid redirect status');
-  check(typeof enabled==='boolean','Invalid enabled flag');
-  if(expires!==null){
-    check(typeof expires==='string' && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/.test(expires) && Number.isFinite(Date.parse(expires)),'Invalid expiry');
-    check(new Date(expires).toISOString().replace('.000Z','Z')===expires.replace('.000Z','Z'),'Invalid expiry');
-  }
-  return {url:url.href,status,enabled,expires};
-}
-export const randomLinkCode=()        =>randomBytes(12).toString('base64url');