@jimhoyd/urlcode 0.3.0 → 0.4.0-alpha.2

package/dist/authoring-files.js

@@ -0,0 +1,60 @@
+import {lstat,realpath,open,mkdir,rm,rename} from 'node:fs/promises';
+import {resolve,join,dirname,basename,parse} from 'node:path';
+import {assert} from './errors.js';
+
+/** Authoring output never copies hidden state, package hooks, or credential files. */
+export function authoringPath(path        )         {
+  const parts=path.split('/');
+  assert(path.length>0 && path.length<=1024 && parts.length<=32 && parts.every(part=>
+    part && !part.startsWith('.') && !/[. ]$/.test(part) && !/^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(part) && !/[\\:*?"<>|\u0000-\u001f\u007f]/u.test(part) &&
+    !/^(?:node_modules|package(?:-lock)?\.json|.*\.(?:pem|key|p12|pfx|env))$/i.test(part)), 'Authoring paths must be safe non-sensitive project-relative paths');
+  return path;
+}
+export async function authoringFile(root        ,path        ,directory=false)                  {
+  authoringPath(path);let file=root;
+  for(const [index,part] of path.split('/').entries()){
+    file=join(file,part);const info=await lstat(file);
+    assert(!info.isSymbolicLink(),'Authoring through symlinks is forbidden');
+    assert(index<path.split('/').length-1 || directory ? info.isDirectory() : info.isFile() && info.nlink===1,'Authoring requires ordinary files and directories');
+  }
+  return file;
+}
+export async function readAuthoringFile(root        ,path        ,limit        )                  {
+  const file=await authoringFile(root,path),handle=await open(file,'r');
+  try {
+    const info=await handle.stat();assert(info.isFile() && info.nlink===1 && info.size<=limit,'Authoring source size limit exceeded');
+    const bytes=Buffer.alloc(info.size+1);let offset=0;
+    while(offset<bytes.length){const read=await handle.read(bytes,offset,bytes.length-offset,null);if(!read.bytesRead)break;offset+=read.bytesRead;}
+    assert(offset<=info.size,'Authoring source changed during read');return bytes.subarray(0,offset);
+  }finally{await handle.close();}
+}
+/** Reserve a fresh directory exclusively, then publish the entry config last.
+ * Failed writes remove only the directory created by this invocation. No existing
+ * directory (even an empty one) is accepted; consumers see no activatable project
+ * until every dependency has been written. Callers must own the output parent.
+ */
+export async function publishAuthoringProject(output        ,files                                   ,dryRun=false)                  {
+  assert(files.has('urlcode.yaml'),'Authoring output requires urlcode.yaml');
+  assert(files.size<=10000,'Authoring file limit exceeded');
+  const paths=new Set        ();
+  for(const path of files.keys()){
+    authoringPath(path);const key=path.toLowerCase();assert(!paths.has(key),'Conflicting authoring output paths');paths.add(key);
+  }
+  for(const path of paths){let parent=dirname(path);while(parent!=='.'){assert(!paths.has(parent),'Authoring file/directory conflict');parent=dirname(parent);}}
+  const target=resolve(output),parent=dirname(target);assert(target!==parse(target).root,'Invalid authoring output');
+  assert(!(await lstat(parent)).isSymbolicLink(),'Authoring output parent must not be a symlink');
+  const destination=join(await realpath(parent),basename(target));
+  let exists=false;try{await lstat(destination);exists=true;}catch(error){if(!(error instanceof Error && 'code' in error && error.code==='ENOENT'))throw error;}
+  assert(!exists,'Authoring output already exists');
+  if(dryRun)return destination;
+  await mkdir(destination,{mode:0o700});
+  try {
+    const entries=[...files].sort(([a],[b])=>a==='urlcode.yaml'?1:b==='urlcode.yaml'?-1:a.localeCompare(b));
+    for(const [path,content] of entries){
+      const file=join(destination,path==='urlcode.yaml'?'.urlcode.yaml.pending':path);await mkdir(dirname(file),{recursive:true,mode:0o700});
+      const handle=await open(file,'wx',0o600);try{await handle.writeFile(content);await handle.sync();}finally{await handle.close();}
+      if(path==='urlcode.yaml')await rename(file,join(destination,'urlcode.yaml'));
+    }
+    return destination;
+  }catch(error){await rm(destination,{recursive:true,force:true});throw error;}
+}

package/dist/authoring.js

@@ -4,6 +4,7 @@ import { fileURLToPath } from 'node:url';
 import { randomBytes } from 'node:crypto';
 import { parseDocument } from 'yaml';
 import { loadDocument, validateDocument } from './config.js';
+import { renderAgentsGuide, renderMcpConfig, mcpConfigFile } from './agents-guide.js';
 import { compileRoutes } from './router.js';
 import { prepareFunctionSnapshot, requestedPermissions } from './policy.js';
 import { assert } from './errors.js';
@@ -17,9 +18,18 @@ export async function initProject(destination        )                  {
   try {
     const source = fileURLToPath(new URL('../starters/default/', import.meta.url));
     for (const file of await readdir(source)) {
-      if (file === '.gitignore') continue;
+      if (file === '.gitignore' || file === 'AGENTS.md' || file === mcpConfigFile) continue;
       await cp(join(source,file), join(target,file === 'gitignore.template' ? '.gitignore' : file), { recursive: true, force: false, errorOnExist: true });
     }
+    // AGENTS.md is generated from the installed runtime's capability catalog so
+    // it names only what this version implements; the starter carries a
+    // committed copy for clones, kept identical by test.
+    const routes = Object.keys((await loadDocument(target)).routes).length;
+    const guide = await open(join(target,'AGENTS.md'), 'wx', 0o644);
+    try { await guide.writeFile(renderAgentsGuide({ routes })); } finally { await guide.close(); }
+    // .mcp.json registers the read-only server for repository-aware agents; the starter carries the same bytes.
+    const mcp = await open(join(target,mcpConfigFile), 'wx', 0o644);
+    try { await mcp.writeFile(renderMcpConfig('.')); } finally { await mcp.close(); }
   } catch (error) { await rm(target, { recursive: true, force: true }); throw error; }
   return target;
 }

package/dist/aws.js

@@ -1,3 +1,4 @@
+                                                        
 import { randomUUID } from 'node:crypto';
 import { activateNativeOnly, lazyRuntime, resolveOrigin } from './adapters.js';
                                                  
@@ -6,7 +7,7 @@ import { prepareResponse, errorResponse } from './http-response.js';
                                                      
 import { assert, ConfigError, HttpError } from './errors.js';
 
-                                                                                                                                                                                                                 
+                                                                                                                                                                                                                                                           
 /** A Lambda payload format 2.0 event, as far as this adapter reads it. */
                               
                                                                                    
@@ -64,9 +65,9 @@ function requestBody(event             , limit        )         {
 // Builds a Lambda handler for payload format 2.0. The runtime is created once
 // per execution environment and reused across warm invocations.
 export function createLambdaHandler({ project = process.cwd(), origin, environment = process.env,
-  maxBodyBytes = 1048576, plugins }                       = {})                {
+  maxBodyBytes = 1048576, plugins, extensions }                       = {})                {
   assert(Number.isInteger(maxBodyBytes) && maxBodyBytes >= 1 && maxBodyBytes <= 16777216, 'Request limit must be 1–16777216 bytes');
-  const ready = lazyRuntime(() => activateNativeOnly(project, environment, { target: 'aws', plugins }));
+  const ready = lazyRuntime(() => activateNativeOnly(project, environment, { target: 'aws', plugins, extensions, origin:resolveOrigin(origin,environment,platformOrigins) }));
 
   return async function handler(raw) {
     const requestId = randomUUID();

package/dist/build-cloudflare.js

@@ -1,3 +1,4 @@
+import { analyzeProjectCapabilities, analyzeCompiledCapabilities, assertTargetCompatibility } from './capabilities.js';
 import { mkdir, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import Ajv from 'ajv/dist/2020.js';
@@ -8,23 +9,12 @@ import { assert } from './errors.js';
 import { effectivePolicies, registry } from './policies.js';
 import { resolveLists } from './agent-lists.js';
 import { applySite } from './site.js';
+import { buildManifest, renderManifest, manifestPath } from './manifest.js';
                                                                                   
                                                                                      
 
                                                                                                                 
-                                                                                                                 
-
-// Handlers this target cannot serve, and why. Declarative routes only in this
-// slice: assets need a platform binding rather than an inline copy, and the
-// sandbox needs facilities the platform does not provide.
-const unsupported = {
-  function:'isolated functions need worker threads and the WASM engine',
-  link:'stored live links need a durable writable store',
-  page:'pages need a static-asset binding',
-  static:'static directories need a static-asset binding',
-  download:'downloads need a static-asset binding',
-}         ;
-const unsupportedHandlers = ['function','link','page','static','download']                                                         ;
+                                                                                                                                   
 
 // The artifact is this runtime's build output, not a published contract: the
 // format may change with any release, and the runtime refuses a version it does
@@ -80,24 +70,21 @@ export async function buildCloudflare(project        , { out = 'dist/cloudflare'
   // Generated site routes are built like declared ones; the ones that need
   // an origin get it from --origin, exactly as the server does.
   await applySite(loaded, { origin, log });
+  assertTargetCompatibility(analyzeProjectCapabilities(loaded, 'cloudflare'));
   // No bindings are resolved: a build artifact must never carry a secret, and
   // this target has no per-request operator policy to pin one to.
   const compiled = await compileRoutes(loaded, {}, {}, undefined);
   const routes = [...compiled.exact.values(), ...[...compiled.byLength.values()].flat(), ...compiled.mounts];
 
-  const refused           = [];
+  assertTargetCompatibility(analyzeCompiledCapabilities(loaded.document, compiled, 'cloudflare'));
   for (const route of routes) {
-    for (const handler of unsupportedHandlers) {
-      if (route[handler]) refused.push(`${route.pattern}: ${unsupported[handler]}`);
-    }
-    if (route.middleware?.length) refused.push(`${route.pattern}: middleware needs the sandbox`);
     const policies                    = effectivePolicies(loaded.document, route);
     for (const name of Object.keys(policies)) {
       assert(isPolicyName(name), `Unknown policy "${name}"`);
       const support = policyModule(name).targets(policies[name]).cloudflare;
       // The platform provides it: accepted and dropped, never carried.
       if (support === 'delegated') { delete policies[name]; continue; }
-      if (!compilablePolicies.has(name) || support !== 'compiled') refused.push(`${route.pattern}: policies.${name} cannot be compiled for this target`);
+      assert(compilablePolicies.has(name) && support === 'compiled', `${route.pattern}: policies.${name} cannot be compiled for this target`);
     }
     // Project-relative agent lists are read here, once, so the artifact
     // carries the patterns and the Worker never needs a filesystem.
@@ -109,11 +96,7 @@ export async function buildCloudflare(project        , { out = 'dist/cloudflare'
     // evaluates a configuration the runtime would have rejected.
     for (const name of Object.keys(policies)) if (isPolicyName(name) && compilablePolicies.has(name)) await policyModule(name).compile(policies[name], { route, shared: {}, target: 'cloudflare', document: loaded.document, root: loaded.root });
     if (Object.keys(policies).length) route.compiledPolicies = policies; else delete route.compiledPolicies;
-    if (Object.keys(route.env).length || Object.keys(route.secrets).length) {
-      refused.push(`${route.pattern}: env and secret bindings would have to be baked into the artifact`);
-    }
   }
-  assert(!refused.length, `This target serves declarative routes only:\n  ${refused.join('\n  ')}`);
   assert(routes.length, 'No routes to build');
 
   const ajv = new Ajv.default({ code:{ source:true, esm:true }, strict:false, allErrors:false });
@@ -159,6 +142,10 @@ import * as validators from './validators.js';
 
 export default { fetch: createFetchHandler(artifact, validators) };
 `);
+  // The semantic manifest travels with the artifact so a reviewer can read
+  // what was built without the project checkout (docs/TOOLING.md).
+  const manifest = manifestPath(out);
+  await writeFile(manifest, renderManifest(await buildManifest(project, origin === undefined ? {} : { origin })));
   return { out, format:FORMAT, version:loaded.version, routes:serialised.length,
-    validators:Object.keys(validators).length };
+    validators:Object.keys(validators).length, manifest };
 }

package/dist/build-static.js

@@ -0,0 +1,134 @@
+import { analyzeProjectCapabilities, analyzeCompiledCapabilities, assertTargetCompatibility } from './capabilities.js';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { loadDocument } from './config.js';
+import { compileRoutes } from './router.js';
+import { compileAssets } from './assets.js';
+import { assert, ConfigError } from './errors.js';
+import { applySite } from './site.js';
+import { buildManifest, renderManifest, manifestPath } from './manifest.js';
+                                        
+
+                                                                                                                
+                                                                                                                                                 
+
+// The manifests below are this target's own build output, not a published
+// contract: their shape may change with any release.
+const FORMAT = 1;
+
+/** One S3 per-object website redirect: a zero-byte object at `key` carrying
+ * `x-amz-website-redirect-location: location`, which S3 always answers with a
+ * 301 regardless of the object's own metadata. */
+                                                                              
+/** One served file: the bytes are written under `out/objects/<key>`; the
+ * metadata here is what a deploy step sets as the S3 object's own headers. */
+                                                                                                                      
+                                                                                 
+                                                                           
+
+// S3 static-website object keys never start with a slash; the bucket's own
+// "Index document" suffix (conventionally index.html) is what answers a
+// request for a folder path or the site root, exactly the same convention
+// used here for pattern '/'.
+function objectKey(pattern        )         {
+  const trimmed = pattern.slice(1);
+  return trimmed === '' ? 'index.html' : trimmed;
+}
+
+export async function buildStatic(project        , { out = 'dist/static', origin, log = () => {} }               = {})                       {
+  const loaded = await loadDocument(project);
+  // Generated site routes are built like declared ones; the ones that need
+  // an origin get it from --origin, exactly as the server does.
+  await applySite(loaded, { origin, log });
+  assertTargetCompatibility(analyzeProjectCapabilities(loaded, 'static'));
+  const compiled = await compileRoutes(loaded, {}, {}, undefined);
+  const routes = [...compiled.exact.values(), ...[...compiled.byLength.values()].flat(), ...compiled.mounts];
+
+  assertTargetCompatibility(analyzeCompiledCapabilities(loaded.document, compiled, 'static'));
+  assert(routes.length, 'No routes to build');
+
+  // Capability analysis already refused function/middleware/extension,
+  // parameters, request.body, response.headers, bindings, proxy/signals,
+  // conditional/conditions and every policy for this target, so every
+  // surviving route is a plain redirect/respond/page/static/download with no
+  // path placeholders. What is left below are shapes capability analysis
+  // cannot see because they are configuration, not capability, distinctions:
+  // a redirect that needs request-time logic (query passthrough/mapping, a
+  // non-301 status), and a route that needs request-time lifecycle checks
+  // (`enabled: false`, `expires`) or a method other than GET/HEAD.
+  const defaultMethods = new Set(['GET', 'HEAD']);
+  for (const route of routes) {
+    assert(route.enabled !== false, `${route.pattern}: static hosting has no server to answer a disabled route with 404; remove the route instead of disabling it`);
+    assert(route.expiresAt === undefined, `${route.pattern}: static hosting has no server to answer an expired route with 410; remove the route when it expires`);
+    assert(route.methods.every(method => defaultMethods.has(method)), `${route.pattern}: static hosting only ever answers GET/HEAD; this target refuses declared methods ${route.methods.join(', ')}`);
+    if (route.redirect) {
+      assert(!route.names.length, `${route.pattern}: static hosting cannot redirect a path pattern; only an exact literal path can carry an S3 per-object redirect`);
+      const query = route.redirect.query;
+      assert(!query?.pass?.length && !(query?.map && Object.keys(query.map).length), `${route.pattern}: static hosting cannot pass or map query parameters into a redirect target; this needs request-time logic S3 does not have`);
+      assert(!route.redirect.status || route.redirect.status === 301, `${route.pattern}: S3's per-object website redirect always answers 301; this route declares ${route.redirect.status}, which would silently change on this target`);
+    }
+  }
+
+  await compileAssets(loaded.root, routes);
+
+  const objectsDir = join(out, 'objects');
+  await mkdir(objectsDir, { recursive: true });
+  const redirects                   = [];
+  const objects                 = [];
+  const writeObject = async (key        , body            )                => {
+    const target = join(objectsDir, ...key.split('/'));
+    await mkdir(dirname(target), { recursive: true });
+    await writeFile(target, body);
+  };
+
+  for (const route of routes) {
+    if (route.redirect) {
+      const key = objectKey(route.pattern);
+      redirects.push({ key, location: route.redirect.url, status: 301 });
+      await writeObject(key, new Uint8Array());
+      continue;
+    }
+    if (route.static) {
+      const asset = route.asset;
+      assert(asset instanceof Map, `${route.pattern}: static mount has no compiled asset snapshot`);
+      const prefix = route.prefix .slice(1);
+      for (const [name, file] of asset) {
+        const key = prefix + name;
+        objects.push({ key, contentType: file.type, cacheControl: file.cache });
+        await writeObject(key, file.body);
+      }
+      continue;
+    }
+    if (route.page || route.download) {
+      const asset = route.asset;
+      assert(asset && !(asset instanceof Map), `${route.pattern}: route has no compiled asset snapshot`);
+      const key = objectKey(route.pattern);
+      objects.push({ key, contentType: asset.type, cacheControl: asset.cache, ...(asset.attachment ? { contentDisposition: asset.attachment } : {}) });
+      await writeObject(key, asset.body);
+      continue;
+    }
+    if (route.reply) {
+      const key = objectKey(route.pattern);
+      const contentType = route.reply.headers.find(([name]) => name === 'content-type')?.[1] ?? 'application/octet-stream';
+      objects.push({ key, contentType });
+      await writeObject(key, route.reply.body);
+      continue;
+    }
+    // Unreachable: capability analysis already refuses every other handler for this target.
+    throw new ConfigError(`${route.pattern}: static target has no compiler for this route`);
+  }
+
+  const redirectManifest                   = { format: FORMAT, redirects };
+  const objectManifest                 = { format: FORMAT, objects };
+  await writeFile(join(out, 'redirects.json'), JSON.stringify(redirectManifest, null, 2) + '\n');
+  await writeFile(join(out, 'objects.json'), JSON.stringify(objectManifest, null, 2) + '\n');
+  // The semantic manifest travels with the artifact so a reviewer can read
+  // what was built without the project checkout (docs/TOOLING.md).
+  const manifest = manifestPath(out);
+  await writeFile(manifest, renderManifest(await buildManifest(project, origin === undefined ? {} : { origin })));
+  return { out, format: FORMAT, version: loaded.version, routes: routes.length, redirects: redirects.length, files: objects.length, manifest };
+}
+
+// Exported for tests that need the exact key a route compiles to without
+// duplicating the mapping rule.
+export const staticObjectKey = objectKey;

package/dist/bulk.js

@@ -0,0 +1,37 @@
+import {createHash} from 'node:crypto';
+import {stringify} from 'yaml';
+import {importRoutes} from './interchange.js';
+                                                           
+import {publishAuthoringProject} from './authoring-files.js';
+import {assert} from './errors.js';
+
+                                           
+                                                                                                    
+                                   
+                                                                                                     
+                                                                                 
+ 
+/** Import ordinary redirect rows into small, portable include files. There is no
+ * merge mode: duplicate rules and existing output directories are refused. */
+export async function importBulkProject(text        ,format            ,output        ,{dryRun=false,source='<input>'}                                                        ={})                            {
+  assert(['csv','json','yaml'].includes(format),'Bulk input must be csv, json or yaml');
+  assert(source.length<=1024 && !/[\u0000-\u001f\u007f]/u.test(source),'Invalid bulk provenance source name');
+  const provenance={name:source,format,sha256:createHash('sha256').update(text).digest('hex')};
+  const converted=await importRoutes({text,format,source});
+  const report                  ={ok:converted.ok,dryRun,routeCount:converted.routeCount,diagnostics:converted.diagnostics,files:[],source:provenance};
+  if(!converted.ok || !converted.document)return report;
+  const files=new Map               (),entries=Object.entries(converted.document.routes),includes          =[];
+  // 100 includes at the 100,000-route cap; each parser AST stays small without
+  // changing the configuration worker heap, wall deadline or include limits.
+  for(let offset=0;offset<entries.length;offset+=1000){
+    const group=entries.slice(offset,offset+1000),path=`routes/redirects-${String(includes.length+1).padStart(3,'0')}.yaml`;
+    includes.push(path);files.set(path,stringify({version:'1',routes:Object.fromEntries(group)}));
+    report.files.push({path,routeCount:group.length,firstPath:group[0] [0],lastPath:group.at(-1) [0]});
+  }
+  files.set('urlcode.yaml',stringify({version:'1',...(includes.length?{includes}:{}),routes:{}}));
+  report.files.unshift({path:'urlcode.yaml',routeCount:0});
+  const metadata={version:1,source:provenance,routeCount:report.routeCount,files:report.files};
+  files.set('provenance.json',JSON.stringify(metadata,null,2)+'\n');report.files.push({path:'provenance.json',routeCount:0});
+  report.output=await publishAuthoringProject(output,files,dryRun);
+  return report;
+}