@jimhoyd/urlcode 0.4.0-alpha.1 → 0.4.0-alpha.2

package/skills/urlcode/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+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
@@ -10,6 +10,15 @@ 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
@@ -52,18 +61,30 @@ 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
+## 3. Choose the highest-level supported abstraction
 
 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`
+   `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`. 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.
+   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.

package/starters/default/AGENTS.md

@@ -16,11 +16,11 @@ authentication; the runtime provides them. Read this file before changing anythi
 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.
+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.json` registers the read-only `urlcode mcp` server. When it is
+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`,
@@ -29,24 +29,25 @@ The CLI equivalents are the fallback: `urlcode context`, `urlcode capabilities N
 
 ## 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.
+- 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. If a requirement seems to need one
-of them and it is missing, that is a report, not an invitation to reimplement.
+Never recreate any of these in a function; a missing one is a report, not an
+invitation to reimplement it.
 
-## Functions and middleware are sandboxed
+## Functions and middleware are trusted by default; sandbox is opt-in
 
-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.
+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
 
@@ -56,10 +57,9 @@ 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`.
+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
 
@@ -69,8 +69,8 @@ Without a global install, invoke `node /path/to/urlcode/src/cli.ts` instead of `
   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.
+- 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.
 

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');