@north-light/cli 0.3.483 → 0.3.484

package/dist/core/command-plugins/bundle.js

@@ -1 +1 @@
-var P=Object.defineProperty;var p=(e,r)=>P(e,"name",{value:r,configurable:!0});import{Parser as J}from"tar";import{createHash as I}from"node:crypto";import{chmodSync as W,renameSync as k}from"node:fs";import{dirname as $,join as w,resolve as V,sep as z}from"node:path";import{validateCommandManifest as B}from"../../api/command-manifest/manifest.js";import{ensureScopeInitialized as F,invalidPluginKindsReasons as M,readConfig as R,updateConfig as D,updateState as C}from"../config.js";import{general as x}from"../errors.js";import{atomicWriteJson as T,atomicWriteText as q,ensureDir as j,nowIso as E,pathExists as _,removePath as S,syncDirectory as U,syncTree as H}from"../fs-utils.js";import{invalidPageComponentsReasons as K,normalizePageComponents as G}from"../human/page-catalog.js";import{validateMemoryExtensionDeclarations as X}from"../plugin-extensions.js";import{validateBundleTransport as Z}from"./endpoint.js";const O=/^[A-Za-z0-9_-]{1,64}$/,L=new Set(["id","major","groups"]),Y=new Set(["group","consent_line","rate","who","allowlist"]),Q=new Set(["own","user","allowlist","any"]),ee=new Set(["bundleVersion","kinds","page_components","memory_extensions","version","transport","provider"]);function ne(e,r,n,o,s,a){return{code:e,message:r,received:n,expected:o,next:s,...a!==void 0?{path:a}:{}}}p(ne,"issue");function d(e,r,n,o,s){return ne("plugin_bundle_invalid",e,r,n,o,s)}p(d,"bundleInvalid");function re(e){if(e[0]===31&&e[1]===139)return d("bundle archive must be uncompressed tar data","gzip-compressed archive","an uncompressed tar archive","Serve the archive without compression.");if(e.length===0||e.length%512!==0)return d("bundle archive must be a non-empty whole number of 512-byte tar blocks",`${e.length} bytes`,"a non-empty tar stream with a 512-byte block length","Serve one complete uncompressed tar archive.");if(e.length<1024||!e.subarray(-1024).every(r=>r===0))return d("bundle archive is missing the required two zero-block terminator","archive tail is not 1024 zero bytes","a complete tar stream ending in two 512-byte zero blocks","Serve the complete uncompressed tar archive.")}p(re,"archiveEnvelopeIssue");function oe(e,r){if(e.length===0||e.includes("\0")||e.includes("\\")||e.startsWith("/")||/^[A-Za-z]:($|\/)/.test(e))return d("bundle member path must be a safe relative POSIX path",e,"a relative path without absolute, drive-letter, backslash, or NUL forms","Use a safe relative POSIX member path.",e);if(r==="file"&&e.endsWith("/"))return d("only directory members may have a trailing slash",e,"a regular-file path without a trailing slash","Emit this member as a regular file path.",e);if((r==="directory"&&e.endsWith("/")?e.slice(0,-1):e).split("/").some(o=>o===""||o==="."||o===".."))return d("bundle member path contains an unsafe segment",e,"non-empty segments other than . or ..","Use a safe relative POSIX member path.",e)}p(oe,"validateMemberName");function se(e,r){if(r==="file")return e==="bundle.json"||e==="commands.json"||e==="hooks.json"||e.startsWith("memory/")&&e.endsWith(".md")||e.startsWith("hooks/")?void 0:d("bundle contains an unsupported file member",e,"bundle.json, commands.json, hooks.json, memory/**/*.md, or hooks/**","Remove unsupported members from the archive.",e);if(!(e==="memory"||e.startsWith("memory/")||e==="hooks"||e.startsWith("hooks/")))return d("bundle contains an unsupported directory member",e,"memory or hooks, or a directory below either subtree","Remove unsupported directory members from the archive.",e)}p(se,"validateMemberShape");function te(e){return e.type==="directory"&&e.path.endsWith("/")?e.path.slice(0,-1):e.path}p(te,"materializedPath");function ie(e){const r=new Map;for(const n of e){const o=te(n),s=r.get(o);if(s!==void 0)return d(s===n.type?"bundle contains a duplicate member":"bundle claims one path as both a file and a directory",`${o} (${s} and ${n.type})`,"each materialized path exactly once, with one type","Emit each archive path once, as a single member type.",o);r.set(o,n.type)}for(const[n,o]of r)if(o==="file"){for(const s of r.keys())if(s.startsWith(`${n}/`))return d("bundle nests a member beneath a regular-file path",`${s} beneath file ${n}`,"members nested only beneath directory paths","Emit the parent path as a directory or remove the nested member.",s)}}p(ie,"validateMemberTree");async function ae(e){const r=[],n=new Set;let o;return await new Promise((s,a)=>{const l=new J({strict:!0,maxMetaEntrySize:Number.MAX_SAFE_INTEGER,gzip:!1,brotli:!1,zstd:!1,onReadEntry:p(t=>{const m=t.path,f=t.type==="File"||t.type==="OldFile"?"file":t.type==="Directory"?"directory":void 0;if(f===void 0||t.unsupported||t.ignore||t.linkpath!==void 0){o??=d("bundle member must be a regular file or directory without a link target",`${m} (${t.type})`,"a regular file or directory member without link metadata","Remove links and unsupported member types from the archive.",m),t.resume();return}o??=oe(m,f),o??=se(m,f),n.has(m)&&(o??=d("bundle contains a duplicate member",m,"each member path exactly once","Emit each archive member only once.",m)),n.add(m);const i=[];t.on("data",b=>i.push(b)),t.on("end",()=>{o===void 0&&r.push({path:m,type:f,bytes:new Uint8Array(Buffer.concat(i))})})},"onReadEntry")});l.on("ignoredEntry",t=>{const m=t.path;o??=d("bundle contains an ignored or unsupported archive member",`${m} (${t.type})`,"only supported regular file or directory members","Remove ignored or unsupported members from the archive.",m),t.resume()}),l.once("error",a),l.once("end",s);try{l.end(Buffer.from(e))}catch(t){a(t)}}).catch(s=>{o??=d("bundle archive could not be parsed",s instanceof Error?s.message:String(s),"a valid complete uncompressed tar archive","Fix the archive format and serve it again.")}),o===void 0?{members:r}:{issue:o}}p(ae,"parseArchive");function N(e){return typeof e=="number"&&Number.isInteger(e)&&e>=1}p(N,"isPositiveInt");function de(e){const r=p((t,m,f,i)=>({issue:d(t,m,f,"Fix the provider block in bundle.json.",`bundle.json.${i}`)}),"bad");if(typeof e!="object"||e===null||Array.isArray(e))return r("bundle.json provider must be an object",JSON.stringify(e),"{ id, major, groups }","provider");const n=e,o=Object.keys(n).filter(t=>!L.has(t));if(o.length>0)return r("bundle.json provider has unknown keys",o.join(", "),"only: id, major, groups","provider");if(typeof n.id!="string"||!O.test(n.id))return r("provider id must match [A-Za-z0-9_-]{1,64}",JSON.stringify(n.id),'a provider id of 1-64 letters, digits, "_" or "-"',"provider.id");if(!N(n.major))return r("provider major must be an integer of at least 1",JSON.stringify(n.major),"the served major as an integer >= 1","provider.major");const s=n.groups;if(!Array.isArray(s)||s.length===0)return r("provider groups must be a non-empty array",JSON.stringify(s),"at least one { group, consent_line, rate?, who, allowlist }","provider.groups");const a=[],l=new Set;for(let t=0;t<s.length;t++){const m=`provider.groups[${t}]`,f=s[t];if(typeof f!="object"||f===null||Array.isArray(f))return r("provider group must be an object",JSON.stringify(f),"{ group, consent_line, rate?, who, allowlist }",m);const i=f,b=Object.keys(i).filter(v=>!Y.has(v));if(b.length>0)return r("provider group has unknown keys",b.join(", "),"only: group, consent_line, rate, who, allowlist",m);if(typeof i.group!="string"||!O.test(i.group))return r("provider group id must match [A-Za-z0-9_-]{1,64}",JSON.stringify(i.group),'a group id of 1-64 letters, digits, "_" or "-"',`${m}.group`);if(l.has(i.group))return r("provider group ids must be unique",i.group,"each group declared once",`${m}.group`);if(l.add(i.group),typeof i.consent_line!="string"||i.consent_line.trim().length===0)return r("provider group consent_line must be a non-empty string",JSON.stringify(i.consent_line),"the consent line shown for this group",`${m}.consent_line`);const h=i.rate;if(h!=null&&(typeof h!="number"||!Number.isFinite(h)||h<0))return r("provider group rate must be a non-negative number or null",JSON.stringify(h),"a finite number >= 0, null, or omitted",`${m}.rate`);if(typeof i.who!="string"||!Q.has(i.who))return r("provider group who must be own|user|allowlist|any",JSON.stringify(i.who),"own | user | allowlist | any",`${m}.who`);const c=i.allowlist;if(!Array.isArray(c)||!c.every(v=>typeof v=="string"&&v.length>0))return r("provider group allowlist must be an array of non-empty strings",JSON.stringify(c),"an array of app principals ([] unless who is allowlist)",`${m}.allowlist`);if(c.length>0&&i.who!=="allowlist")return r("provider group allowlist must be empty unless who is allowlist",`who ${i.who}`,'who: "allowlist", or allowlist: []',`${m}.allowlist`);a.push({group:i.group,consent_line:i.consent_line,...h!==void 0?{rate:h}:{},who:i.who,allowlist:c})}return{provider:{id:n.id,major:n.major,groups:a}}}p(de,"parseProviderBlock");function ue(e){const r=[],n=p((o,s)=>{const a=[...s,o.name];if(o.kind==="leaf")r.push({path:a.join(" "),leaf:o});else for(const l of o.children)n(l,a)},"walk");for(const o of e.roots)n(o,[]);for(const o of e.coreMounts)n(o.node,o.parent);return r}p(ue,"collectLeaves");function le(e,r){const n=e.provider;if(n===void 0)return;if(e.transport===void 0)return d("a provider bundle must declare its transport","(missing)",'transport { kind: "http", endpoint } in bundle.json',"Add the provider endpoint as bundle.json transport.","bundle.json.transport");if(e.transport.kind==="http"&&e.transport.authEnv!==void 0)return d("a provider bundle must not declare authEnv",e.transport.authEnv,"no authEnv: the runtime presents its own outbound token","Remove transport.authEnv from bundle.json.","bundle.json.transport.authEnv");const o=new Set(n.groups.map(s=>s.group));for(const{path:s,leaf:a}of ue(r)){const l="group"in a?a.group:void 0;if(l===void 0)return d(`provider leaf "${s}" has no group`,s,"a group on every leaf of a provider bundle",`Add a group to leaf "${s}".`,`commands.json:${s}.group`);if(!o.has(l))return d(`provider leaf "${s}" names undeclared group "${l}"`,l,`one of: ${[...o].join(", ")}`,`Declare group "${l}" in the provider block, or move leaf "${s}" to a declared group.`,`commands.json:${s}.group`);if("rest"in a&&a.rest.streaming===!0)return d(`provider leaf "${s}" streams`,"rest.streaming: true","no streaming leaves in a provider bundle",`Make leaf "${s}" return one response.`,`commands.json:${s}.rest.streaming`)}}p(le,"providerBundleIssue");function me(e){let r;try{r=JSON.parse(Buffer.from(e).toString("utf8"))}catch{return{issue:d("bundle.json is not valid JSON","invalid JSON",'{"bundleVersion":1}',"Write valid bundle metadata.","bundle.json")}}if(typeof r!="object"||r===null||Array.isArray(r))return{issue:d("bundle.json must be a JSON object",JSON.stringify(r),"an object with bundleVersion set to 1 and optionally kinds",'Set bundle.json to {"bundleVersion":1}.',"bundle.json")};const n=r,o=Object.keys(n).filter(t=>!ee.has(t));if(n.bundleVersion!==1||o.length>0)return{issue:d("bundle.json must contain bundleVersion 1 and at most version, transport, provider, kinds, page_components, and memory_extensions",JSON.stringify(r),"an object with bundleVersion set to 1 and optional version, transport, provider, kinds, page_components, and memory_extensions",'Set bundle.json to {"bundleVersion":1} plus optional contribution blocks.',"bundle.json")};if(n.kinds!==void 0){const t=M(n.kinds);if(t.length>0)return{issue:d("bundle.json kinds block is invalid",t.join("; "),"each entry a full KindConfig (whenToUse required) or a sparse patch of launch fields","Fix the kinds entries in bundle.json.","bundle.json")}}if(n.page_components!==void 0){const t=K(n.page_components);if(t.length>0)return{issue:d("bundle.json page_components block is invalid",t.join("; "),"an array of page component registrations, each a kind string or {kind, description?, useWhen?, doc?, display?}","Fix the page_components entries in bundle.json.","bundle.json")}}let s;if(n.memory_extensions!==void 0)try{s=X(n.memory_extensions)}catch(t){return{issue:d("bundle.json memory_extensions block is invalid",t instanceof Error?t.message:String(t),"a valid memory_extensions declaration object","Fix the memory_extensions declarations in bundle.json.","bundle.json")}}if(n.version!==void 0&&!N(n.version))return{issue:d("bundle.json version must be an integer of at least 1",JSON.stringify(n.version),"the plugin major as an integer >= 1, or omitted","Fix version in bundle.json.","bundle.json.version")};let a;if(n.transport!==void 0){const t=Z(n.transport);if(t.transport===void 0)return{issue:d("bundle.json transport is invalid",t.errors.join("; "),'{ kind: "http", endpoint, authEnv? } or { kind: "machine" }',"Fix transport in bundle.json.","bundle.json.transport")};a=t.transport}let l;if(n.provider!==void 0){const t=de(n.provider);if(t.issue!==void 0)return{issue:t.issue};if(l=t.provider,n.version!==void 0&&n.version!==l.major)return{issue:d("bundle.json provider major must equal version",`version ${String(n.version)}, major ${l.major}`,"one major","Set provider.major and version to the same integer.","bundle.json.provider.major")}}return{...n.version!==void 0?{version:n.version}:{},...a!==void 0?{transport:a}:{},...l!==void 0?{provider:l}:{},...n.kinds!==void 0?{kinds:n.kinds}:{},...n.page_components!==void 0?{page_components:G(n.page_components)}:{},...s!==void 0?{memory_extensions:s}:{}}}p(me,"parseBundleMetadata");function pe(e,r,n,o=new Set){let s;try{s=JSON.parse(Buffer.from(e).toString("utf8"))}catch{return{issues:[d("commands.json is not valid JSON","invalid JSON","a valid command-manifest JSON object","Regenerate commands.json.","commands.json")]}}const a=B(s,{transport:"http",reservedCoreNames:r,extensibleCoreBranches:o,...n!==void 0?{coreCommandPaths:n}:{}});return{...a.manifest!==void 0?{commands:a.manifest}:{},issues:a.issues}}p(pe,"parseCommands");async function ce(e,r){const n=re(e);if(n!==void 0)return{issues:[n]};const o=await ae(e);if(o.issue!==void 0||o.members===void 0)return{issues:[o.issue]};const s=ie(o.members);if(s!==void 0)return{issues:[s]};const a=o.members.find(u=>u.path==="bundle.json"&&u.type==="file"),l=o.members.find(u=>u.path==="commands.json"&&u.type==="file");if(a===void 0||l===void 0)return{issues:[d("bundle must contain exactly one bundle.json and one commands.json regular file",`bundle.json=${a!==void 0}, commands.json=${l!==void 0}`,"one regular bundle.json and one regular commands.json member","Add the required metadata members to the archive.")]};const t=o.members.find(u=>u.path==="hooks.json"&&u.type==="file"),m=o.members.filter(u=>u.type==="file"&&u.path.startsWith("hooks/"));if((t!==void 0||o.members.some(u=>u.path==="hooks"||u.path.startsWith("hooks/")))&&(t===void 0||!m.some(u=>u.path==="hooks/dispatch")))return{issues:[d("bundle hook payload must contain both hooks.json and hooks/dispatch regular files",`hooks.json=${t!==void 0}, hooks/dispatch=${m.some(u=>u.path==="hooks/dispatch")}`,"both hooks.json and hooks/dispatch regular files","Add both required hook members or remove the hook payload.")]};const i=me(a.bytes);if(i.issue!==void 0)return{issues:[i.issue]};const b=pe(l.bytes,r.reservedCoreNames,r.coreCommandPaths,r.extensibleCoreBranches);if(b.commands===void 0)return{issues:b.issues};const h=b.commands.version;if(i.version!==void 0&&h!==void 0&&i.version!==h)return{issues:[d("bundle.json version and commands.json version differ",`bundle.json ${i.version}, commands.json ${h}`,"one plugin major","Emit the same version in bundle.json and commands.json.","bundle.json.version")]};const c=i.version??h;if(i.provider!==void 0&&c===void 0)return{issues:[d("a provider bundle requires a plugin version","no version in bundle.json or commands.json",`version ${i.provider.major}, the provider major`,"Emit the provider major as the plugin version.","bundle.json.version")]};if(i.provider!==void 0&&c!==i.provider.major)return{issues:[d("bundle provider major must equal the plugin version",`version ${c}, major ${i.provider.major}`,"one major","Emit the provider major as the plugin version.","bundle.json.provider.major")]};const v=le(i,b.commands);return v!==void 0?{issues:[v]}:{bundle:{bundleVersion:1,...c!==void 0?{version:c}:{},...i.transport!==void 0?{transport:i.transport}:{},...i.provider!==void 0?{provider:i.provider}:{},...i.kinds!==void 0?{kinds:i.kinds}:{},...i.page_components!==void 0?{page_components:i.page_components}:{},...i.memory_extensions!==void 0?{memory_extensions:i.memory_extensions}:{},commands:b.commands,commandsBytes:l.bytes,directories:o.members.filter(u=>u.type==="directory").map(u=>({path:u.path})),memory:o.members.filter(u=>u.type==="file"&&u.path.startsWith("memory/")).map(u=>({path:u.path,bytes:u.bytes})),...t!==void 0?{hooks:{manifest:t.bytes,files:m.map(u=>({path:u.path,bytes:u.bytes}))}}:{}},issues:[]}}p(ce,"validatePluginBundle");function fe(e){return I("sha256").update(e).digest("hex").slice(0,12)}p(fe,"bundleVersion");function Ne(e,r,n,o){return R(r).plugins[e]?.version!==o?!1:_(w(n,"commands.json"))}p(Ne,"isInstalledGeneration");function he(e,r,n,o){C(e,s=>{s.plugins[r]===void 0&&(s.plugins[r]={}),o.swapped&&(s.plugins[r].last_updated=E()),s.plugins[r].checked_at=E(),n===void 0?delete s.plugins[r].etag:s.plugins[r].etag=n})}p(he,"recordCheckedGeneration");function g(e,r){const n=V(e,r);if(n===e||!n.startsWith(e+z))throw x(`bundle member path escapes the staging directory: ${r}`);return n}p(g,"stagedPath");function be(e,r,n){const o=p((s,a,l=420)=>q(s,a,{mode:l,durable:!0}),"write");T(g(e,".crouter-plugin/plugin.json"),r,{durable:!0});for(const s of n.directories)j(g(e,s.path));o(g(e,"commands.json"),n.commandsBytes);for(const s of n.memory)o(g(e,s.path),s.bytes);if(n.hooks!==void 0){o(g(e,"hooks.json"),n.hooks.manifest);for(const s of n.hooks.files)o(g(e,s.path),s.bytes);W(g(e,"hooks/dispatch"),493)}H(e)}p(be,"writeStagedBundle");async function Ae(e,r,n){const{scope:o,scopeRootPath:s,root:a}=n,l=await ce(r,n.validation);if(l.bundle===void 0)throw n.invalid(`HTTP plugin bundle for "${e}" is invalid`,l.issues);const t=l.bundle,m=n.accept?.(t);if(m!==void 0)throw n.invalid(`HTTP plugin bundle for "${e}" is invalid`,[d(m,e,"the bundle this install asked for","Serve the requested bundle.")]);const f=n.version??fe(r),i=t.provider!==void 0&&t.transport!==void 0?t.transport:n.transport,b={name:e,version:f,commands:"commands.json",transport:i,bundle:n.bundle,...t.kinds!==void 0?{kinds:t.kinds}:{},...t.page_components!==void 0?{page_components:t.page_components}:{},...t.memory_extensions!==void 0?{memory_extensions:t.memory_extensions}:{},...t.hooks!==void 0?{hooks:"hooks.json",hookExecutable:"hooks/dispatch"}:{},...t.provider!==void 0?{provider:t.provider}:{}},h=w(s,"tmp"),c=w(h,`${e}.${process.pid}`),v=`${c}.prev`;if(_(v))throw x(`cannot replace plugin "${e}": prior interrupted replacement remains at ${v}`);j(h),j($(a)),S(c);let u;try{j(c),be(c,b,t),u=await n.validateStaged(c,b);let y=!1;_(a)&&(k(a,v),y=!0);try{k(c,a)}catch(A){throw y&&k(v,a),A}U($(a)),y&&S(v)}finally{S(c)}return F(o,s),D(o,y=>{y.plugins[e]={enabled:n.enable?!0:y.plugins[e]?.enabled??!0,version:f}}),he(o,e,n.etag,{swapped:!0}),{manifest:b,validated:t,version:f,root:a,staged:u}}p(Ae,"installBundleArchive");export{fe as bundleVersion,Ae as installBundleArchive,Ne as isInstalledGeneration,he as recordCheckedGeneration,ce as validatePluginBundle,be as writeStagedBundle};
+var P=Object.defineProperty;var c=(e,o)=>P(e,"name",{value:o,configurable:!0});import{Parser as J}from"tar";import{createHash as I}from"node:crypto";import{chmodSync as W,renameSync as k}from"node:fs";import{dirname as $,join as w,resolve as B,sep as V}from"node:path";import{validateCommandManifest as z}from"../../api/command-manifest/manifest.js";import{ensureScopeInitialized as R,invalidPluginKindsReasons as F,readConfig as M,updateConfig as D,updateState as C}from"../config.js";import{general as x}from"../errors.js";import{atomicWriteJson as T,atomicWriteText as q,ensureDir as j,nowIso as E,pathExists as _,removePath as S,syncDirectory as U,syncTree as H}from"../fs-utils.js";import{invalidPageComponentsReasons as K,normalizePageComponents as G}from"../human/page-catalog.js";import{validateMemoryExtensionDeclarations as X}from"../plugin-extensions.js";import{objectBlocksShapeReasons as Z}from"../plugin-objects-manifest.js";import{validateBundleTransport as L}from"./endpoint.js";const O=/^[A-Za-z0-9_-]{1,64}$/,Y=new Set(["id","major","groups"]),Q=new Set(["group","consent_line","rate","who","allowlist"]),ee=new Set(["own","user","allowlist","any"]),ne=new Set(["bundleVersion","kinds","page_components","memory_extensions","version","transport","provider","object_kinds","scopes"]);function oe(e,o,n,r,s,a){return{code:e,message:o,received:n,expected:r,next:s,...a!==void 0?{path:a}:{}}}c(oe,"issue");function u(e,o,n,r,s){return oe("plugin_bundle_invalid",e,o,n,r,s)}c(u,"bundleInvalid");function re(e){if(e[0]===31&&e[1]===139)return u("bundle archive must be uncompressed tar data","gzip-compressed archive","an uncompressed tar archive","Serve the archive without compression.");if(e.length===0||e.length%512!==0)return u("bundle archive must be a non-empty whole number of 512-byte tar blocks",`${e.length} bytes`,"a non-empty tar stream with a 512-byte block length","Serve one complete uncompressed tar archive.");if(e.length<1024||!e.subarray(-1024).every(o=>o===0))return u("bundle archive is missing the required two zero-block terminator","archive tail is not 1024 zero bytes","a complete tar stream ending in two 512-byte zero blocks","Serve the complete uncompressed tar archive.")}c(re,"archiveEnvelopeIssue");function se(e,o){if(e.length===0||e.includes("\0")||e.includes("\\")||e.startsWith("/")||/^[A-Za-z]:($|\/)/.test(e))return u("bundle member path must be a safe relative POSIX path",e,"a relative path without absolute, drive-letter, backslash, or NUL forms","Use a safe relative POSIX member path.",e);if(o==="file"&&e.endsWith("/"))return u("only directory members may have a trailing slash",e,"a regular-file path without a trailing slash","Emit this member as a regular file path.",e);if((o==="directory"&&e.endsWith("/")?e.slice(0,-1):e).split("/").some(r=>r===""||r==="."||r===".."))return u("bundle member path contains an unsafe segment",e,"non-empty segments other than . or ..","Use a safe relative POSIX member path.",e)}c(se,"validateMemberName");function te(e,o){if(o==="file")return e==="bundle.json"||e==="commands.json"||e==="hooks.json"||e.startsWith("memory/")&&e.endsWith(".md")||e.startsWith("hooks/")?void 0:u("bundle contains an unsupported file member",e,"bundle.json, commands.json, hooks.json, memory/**/*.md, or hooks/**","Remove unsupported members from the archive.",e);if(!(e==="memory"||e.startsWith("memory/")||e==="hooks"||e.startsWith("hooks/")))return u("bundle contains an unsupported directory member",e,"memory or hooks, or a directory below either subtree","Remove unsupported directory members from the archive.",e)}c(te,"validateMemberShape");function ie(e){return e.type==="directory"&&e.path.endsWith("/")?e.path.slice(0,-1):e.path}c(ie,"materializedPath");function de(e){const o=new Map;for(const n of e){const r=ie(n),s=o.get(r);if(s!==void 0)return u(s===n.type?"bundle contains a duplicate member":"bundle claims one path as both a file and a directory",`${r} (${s} and ${n.type})`,"each materialized path exactly once, with one type","Emit each archive path once, as a single member type.",r);o.set(r,n.type)}for(const[n,r]of o)if(r==="file"){for(const s of o.keys())if(s.startsWith(`${n}/`))return u("bundle nests a member beneath a regular-file path",`${s} beneath file ${n}`,"members nested only beneath directory paths","Emit the parent path as a directory or remove the nested member.",s)}}c(de,"validateMemberTree");async function ae(e){const o=[],n=new Set;let r;return await new Promise((s,a)=>{const p=new J({strict:!0,maxMetaEntrySize:Number.MAX_SAFE_INTEGER,gzip:!1,brotli:!1,zstd:!1,onReadEntry:c(t=>{const d=t.path,f=t.type==="File"||t.type==="OldFile"?"file":t.type==="Directory"?"directory":void 0;if(f===void 0||t.unsupported||t.ignore||t.linkpath!==void 0){r??=u("bundle member must be a regular file or directory without a link target",`${d} (${t.type})`,"a regular file or directory member without link metadata","Remove links and unsupported member types from the archive.",d),t.resume();return}r??=se(d,f),r??=te(d,f),n.has(d)&&(r??=u("bundle contains a duplicate member",d,"each member path exactly once","Emit each archive member only once.",d)),n.add(d);const i=[];t.on("data",b=>i.push(b)),t.on("end",()=>{r===void 0&&o.push({path:d,type:f,bytes:new Uint8Array(Buffer.concat(i))})})},"onReadEntry")});p.on("ignoredEntry",t=>{const d=t.path;r??=u("bundle contains an ignored or unsupported archive member",`${d} (${t.type})`,"only supported regular file or directory members","Remove ignored or unsupported members from the archive.",d),t.resume()}),p.once("error",a),p.once("end",s);try{p.end(Buffer.from(e))}catch(t){a(t)}}).catch(s=>{r??=u("bundle archive could not be parsed",s instanceof Error?s.message:String(s),"a valid complete uncompressed tar archive","Fix the archive format and serve it again.")}),r===void 0?{members:o}:{issue:r}}c(ae,"parseArchive");function N(e){return typeof e=="number"&&Number.isInteger(e)&&e>=1}c(N,"isPositiveInt");function ue(e){const o=c((t,d,f,i)=>({issue:u(t,d,f,"Fix the provider block in bundle.json.",`bundle.json.${i}`)}),"bad");if(typeof e!="object"||e===null||Array.isArray(e))return o("bundle.json provider must be an object",JSON.stringify(e),"{ id, major, groups }","provider");const n=e,r=Object.keys(n).filter(t=>!Y.has(t));if(r.length>0)return o("bundle.json provider has unknown keys",r.join(", "),"only: id, major, groups","provider");if(typeof n.id!="string"||!O.test(n.id))return o("provider id must match [A-Za-z0-9_-]{1,64}",JSON.stringify(n.id),'a provider id of 1-64 letters, digits, "_" or "-"',"provider.id");if(!N(n.major))return o("provider major must be an integer of at least 1",JSON.stringify(n.major),"the served major as an integer >= 1","provider.major");const s=n.groups;if(!Array.isArray(s)||s.length===0)return o("provider groups must be a non-empty array",JSON.stringify(s),"at least one { group, consent_line, rate?, who, allowlist }","provider.groups");const a=[],p=new Set;for(let t=0;t<s.length;t++){const d=`provider.groups[${t}]`,f=s[t];if(typeof f!="object"||f===null||Array.isArray(f))return o("provider group must be an object",JSON.stringify(f),"{ group, consent_line, rate?, who, allowlist }",d);const i=f,b=Object.keys(i).filter(v=>!Q.has(v));if(b.length>0)return o("provider group has unknown keys",b.join(", "),"only: group, consent_line, rate, who, allowlist",d);if(typeof i.group!="string"||!O.test(i.group))return o("provider group id must match [A-Za-z0-9_-]{1,64}",JSON.stringify(i.group),'a group id of 1-64 letters, digits, "_" or "-"',`${d}.group`);if(p.has(i.group))return o("provider group ids must be unique",i.group,"each group declared once",`${d}.group`);if(p.add(i.group),typeof i.consent_line!="string"||i.consent_line.trim().length===0)return o("provider group consent_line must be a non-empty string",JSON.stringify(i.consent_line),"the consent line shown for this group",`${d}.consent_line`);const h=i.rate;if(h!=null&&(typeof h!="number"||!Number.isFinite(h)||h<0))return o("provider group rate must be a non-negative number or null",JSON.stringify(h),"a finite number >= 0, null, or omitted",`${d}.rate`);if(typeof i.who!="string"||!ee.has(i.who))return o("provider group who must be own|user|allowlist|any",JSON.stringify(i.who),"own | user | allowlist | any",`${d}.who`);const m=i.allowlist;if(!Array.isArray(m)||!m.every(v=>typeof v=="string"&&v.length>0))return o("provider group allowlist must be an array of non-empty strings",JSON.stringify(m),"an array of app principals ([] unless who is allowlist)",`${d}.allowlist`);if(m.length>0&&i.who!=="allowlist")return o("provider group allowlist must be empty unless who is allowlist",`who ${i.who}`,'who: "allowlist", or allowlist: []',`${d}.allowlist`);a.push({group:i.group,consent_line:i.consent_line,...h!==void 0?{rate:h}:{},who:i.who,allowlist:m})}return{provider:{id:n.id,major:n.major,groups:a}}}c(ue,"parseProviderBlock");function le(e){const o=[],n=c((r,s)=>{const a=[...s,r.name];if(r.kind==="leaf")o.push({path:a.join(" "),leaf:r});else for(const p of r.children)n(p,a)},"walk");for(const r of e.roots)n(r,[]);for(const r of e.coreMounts)n(r.node,r.parent);return o}c(le,"collectLeaves");function pe(e,o){const n=e.provider;if(n===void 0)return;if(e.transport===void 0)return u("a provider bundle must declare its transport","(missing)",'transport { kind: "http", endpoint } in bundle.json',"Add the provider endpoint as bundle.json transport.","bundle.json.transport");if(e.transport.kind==="http"&&e.transport.authEnv!==void 0)return u("a provider bundle must not declare authEnv",e.transport.authEnv,"no authEnv: the runtime presents its own outbound token","Remove transport.authEnv from bundle.json.","bundle.json.transport.authEnv");const r=new Set(n.groups.map(s=>s.group));for(const{path:s,leaf:a}of le(o)){const p="group"in a?a.group:void 0;if(p===void 0)return u(`provider leaf "${s}" has no group`,s,"a group on every leaf of a provider bundle",`Add a group to leaf "${s}".`,`commands.json:${s}.group`);if(!r.has(p))return u(`provider leaf "${s}" names undeclared group "${p}"`,p,`one of: ${[...r].join(", ")}`,`Declare group "${p}" in the provider block, or move leaf "${s}" to a declared group.`,`commands.json:${s}.group`);if("rest"in a&&a.rest.streaming===!0)return u(`provider leaf "${s}" streams`,"rest.streaming: true","no streaming leaves in a provider bundle",`Make leaf "${s}" return one response.`,`commands.json:${s}.rest.streaming`)}}c(pe,"providerBundleIssue");function ce(e){let o;try{o=JSON.parse(Buffer.from(e).toString("utf8"))}catch{return{issue:u("bundle.json is not valid JSON","invalid JSON",'{"bundleVersion":1}',"Write valid bundle metadata.","bundle.json")}}if(typeof o!="object"||o===null||Array.isArray(o))return{issue:u("bundle.json must be a JSON object",JSON.stringify(o),"an object with bundleVersion set to 1 and optionally kinds",'Set bundle.json to {"bundleVersion":1}.',"bundle.json")};const n=o,r=Object.keys(n).filter(d=>!ne.has(d));if(n.bundleVersion!==1||r.length>0)return{issue:u("bundle.json must contain bundleVersion 1 and at most version, transport, provider, kinds, page_components, memory_extensions, object_kinds, and scopes",JSON.stringify(o),"an object with bundleVersion set to 1 and optional version, transport, provider, kinds, page_components, memory_extensions, object_kinds, and scopes",'Set bundle.json to {"bundleVersion":1} plus optional contribution blocks.',"bundle.json")};if(n.kinds!==void 0){const d=F(n.kinds);if(d.length>0)return{issue:u("bundle.json kinds block is invalid",d.join("; "),"each entry a full KindConfig (whenToUse required) or a sparse patch of launch fields","Fix the kinds entries in bundle.json.","bundle.json")}}if(n.page_components!==void 0){const d=K(n.page_components);if(d.length>0)return{issue:u("bundle.json page_components block is invalid",d.join("; "),"an array of page component registrations, each a kind string or {kind, description?, useWhen?, doc?, display?}","Fix the page_components entries in bundle.json.","bundle.json")}}const s=Z(n);if(n.provider!==void 0&&n.scopes!==void 0&&s.push("scopes is for local plugins; a provider gets its scopes from directory consent"),s.length>0)return{issue:u("bundle.json object_kinds or scopes block is invalid",s.join("; "),"object_kinds keyed by kind name with description, events and optional read.command; scopes an array of crtr:objects:<verb>:<target> strings (local plugins only)","Fix the object_kinds and scopes blocks in bundle.json.","bundle.json")};let a;if(n.memory_extensions!==void 0)try{a=X(n.memory_extensions)}catch(d){return{issue:u("bundle.json memory_extensions block is invalid",d instanceof Error?d.message:String(d),"a valid memory_extensions declaration object","Fix the memory_extensions declarations in bundle.json.","bundle.json")}}if(n.version!==void 0&&!N(n.version))return{issue:u("bundle.json version must be an integer of at least 1",JSON.stringify(n.version),"the plugin major as an integer >= 1, or omitted","Fix version in bundle.json.","bundle.json.version")};let p;if(n.transport!==void 0){const d=L(n.transport);if(d.transport===void 0)return{issue:u("bundle.json transport is invalid",d.errors.join("; "),'{ kind: "http", endpoint, authEnv? } or { kind: "machine" }',"Fix transport in bundle.json.","bundle.json.transport")};p=d.transport}let t;if(n.provider!==void 0){const d=ue(n.provider);if(d.issue!==void 0)return{issue:d.issue};if(t=d.provider,n.version!==void 0&&n.version!==t.major)return{issue:u("bundle.json provider major must equal version",`version ${String(n.version)}, major ${t.major}`,"one major","Set provider.major and version to the same integer.","bundle.json.provider.major")}}return{...n.version!==void 0?{version:n.version}:{},...p!==void 0?{transport:p}:{},...t!==void 0?{provider:t}:{},...n.kinds!==void 0?{kinds:n.kinds}:{},...n.page_components!==void 0?{page_components:G(n.page_components)}:{},...a!==void 0?{memory_extensions:a}:{},...n.object_kinds!==void 0?{object_kinds:n.object_kinds}:{},...n.scopes!==void 0?{scopes:n.scopes}:{}}}c(ce,"parseBundleMetadata");function me(e,o,n,r=new Set){let s;try{s=JSON.parse(Buffer.from(e).toString("utf8"))}catch{return{issues:[u("commands.json is not valid JSON","invalid JSON","a valid command-manifest JSON object","Regenerate commands.json.","commands.json")]}}const a=z(s,{transport:"http",reservedCoreNames:o,extensibleCoreBranches:r,...n!==void 0?{coreCommandPaths:n}:{}});return{...a.manifest!==void 0?{commands:a.manifest}:{},issues:a.issues}}c(me,"parseCommands");async function fe(e,o){const n=re(e);if(n!==void 0)return{issues:[n]};const r=await ae(e);if(r.issue!==void 0||r.members===void 0)return{issues:[r.issue]};const s=de(r.members);if(s!==void 0)return{issues:[s]};const a=r.members.find(l=>l.path==="bundle.json"&&l.type==="file"),p=r.members.find(l=>l.path==="commands.json"&&l.type==="file");if(a===void 0||p===void 0)return{issues:[u("bundle must contain exactly one bundle.json and one commands.json regular file",`bundle.json=${a!==void 0}, commands.json=${p!==void 0}`,"one regular bundle.json and one regular commands.json member","Add the required metadata members to the archive.")]};const t=r.members.find(l=>l.path==="hooks.json"&&l.type==="file"),d=r.members.filter(l=>l.type==="file"&&l.path.startsWith("hooks/"));if((t!==void 0||r.members.some(l=>l.path==="hooks"||l.path.startsWith("hooks/")))&&(t===void 0||!d.some(l=>l.path==="hooks/dispatch")))return{issues:[u("bundle hook payload must contain both hooks.json and hooks/dispatch regular files",`hooks.json=${t!==void 0}, hooks/dispatch=${d.some(l=>l.path==="hooks/dispatch")}`,"both hooks.json and hooks/dispatch regular files","Add both required hook members or remove the hook payload.")]};const i=ce(a.bytes);if(i.issue!==void 0)return{issues:[i.issue]};const b=me(p.bytes,o.reservedCoreNames,o.coreCommandPaths,o.extensibleCoreBranches);if(b.commands===void 0)return{issues:b.issues};const h=b.commands.version;if(i.version!==void 0&&h!==void 0&&i.version!==h)return{issues:[u("bundle.json version and commands.json version differ",`bundle.json ${i.version}, commands.json ${h}`,"one plugin major","Emit the same version in bundle.json and commands.json.","bundle.json.version")]};const m=i.version??h;if(i.provider!==void 0&&m===void 0)return{issues:[u("a provider bundle requires a plugin version","no version in bundle.json or commands.json",`version ${i.provider.major}, the provider major`,"Emit the provider major as the plugin version.","bundle.json.version")]};if(i.provider!==void 0&&m!==i.provider.major)return{issues:[u("bundle provider major must equal the plugin version",`version ${m}, major ${i.provider.major}`,"one major","Emit the provider major as the plugin version.","bundle.json.provider.major")]};const v=pe(i,b.commands);return v!==void 0?{issues:[v]}:{bundle:{bundleVersion:1,...m!==void 0?{version:m}:{},...i.transport!==void 0?{transport:i.transport}:{},...i.provider!==void 0?{provider:i.provider}:{},...i.kinds!==void 0?{kinds:i.kinds}:{},...i.page_components!==void 0?{page_components:i.page_components}:{},...i.memory_extensions!==void 0?{memory_extensions:i.memory_extensions}:{},...i.object_kinds!==void 0?{object_kinds:i.object_kinds}:{},...i.scopes!==void 0?{scopes:i.scopes}:{},commands:b.commands,commandsBytes:p.bytes,directories:r.members.filter(l=>l.type==="directory").map(l=>({path:l.path})),memory:r.members.filter(l=>l.type==="file"&&l.path.startsWith("memory/")).map(l=>({path:l.path,bytes:l.bytes})),...t!==void 0?{hooks:{manifest:t.bytes,files:d.map(l=>({path:l.path,bytes:l.bytes}))}}:{}},issues:[]}}c(fe,"validatePluginBundle");function he(e){return I("sha256").update(e).digest("hex").slice(0,12)}c(he,"bundleVersion");function Pe(e,o,n,r){return M(o).plugins[e]?.version!==r?!1:_(w(n,"commands.json"))}c(Pe,"isInstalledGeneration");function be(e,o,n,r){C(e,s=>{s.plugins[o]===void 0&&(s.plugins[o]={}),r.swapped&&(s.plugins[o].last_updated=E()),s.plugins[o].checked_at=E(),n===void 0?delete s.plugins[o].etag:s.plugins[o].etag=n})}c(be,"recordCheckedGeneration");function g(e,o){const n=B(e,o);if(n===e||!n.startsWith(e+V))throw x(`bundle member path escapes the staging directory: ${o}`);return n}c(g,"stagedPath");function ve(e,o,n){const r=c((s,a,p=420)=>q(s,a,{mode:p,durable:!0}),"write");T(g(e,".crouter-plugin/plugin.json"),o,{durable:!0});for(const s of n.directories)j(g(e,s.path));r(g(e,"commands.json"),n.commandsBytes);for(const s of n.memory)r(g(e,s.path),s.bytes);if(n.hooks!==void 0){r(g(e,"hooks.json"),n.hooks.manifest);for(const s of n.hooks.files)r(g(e,s.path),s.bytes);W(g(e,"hooks/dispatch"),493)}H(e)}c(ve,"writeStagedBundle");async function Je(e,o,n){const{scope:r,scopeRootPath:s,root:a}=n,p=await fe(o,n.validation);if(p.bundle===void 0)throw n.invalid(`HTTP plugin bundle for "${e}" is invalid`,p.issues);const t=p.bundle,d=n.accept?.(t);if(d!==void 0)throw n.invalid(`HTTP plugin bundle for "${e}" is invalid`,[u(d,e,"the bundle this install asked for","Serve the requested bundle.")]);const f=n.version??he(o),i=t.provider!==void 0&&t.transport!==void 0?t.transport:n.transport,b={name:e,version:f,commands:"commands.json",transport:i,bundle:n.bundle,...t.kinds!==void 0?{kinds:t.kinds}:{},...t.page_components!==void 0?{page_components:t.page_components}:{},...t.memory_extensions!==void 0?{memory_extensions:t.memory_extensions}:{},...t.object_kinds!==void 0?{object_kinds:t.object_kinds}:{},...t.scopes!==void 0?{scopes:t.scopes}:{},...t.hooks!==void 0?{hooks:"hooks.json",hookExecutable:"hooks/dispatch"}:{},...t.provider!==void 0?{provider:t.provider}:{}},h=w(s,"tmp"),m=w(h,`${e}.${process.pid}`),v=`${m}.prev`;if(_(v))throw x(`cannot replace plugin "${e}": prior interrupted replacement remains at ${v}`);j(h),j($(a)),S(m);let l;try{j(m),ve(m,b,t),l=await n.validateStaged(m,b);let y=!1;_(a)&&(k(a,v),y=!0);try{k(m,a)}catch(A){throw y&&k(v,a),A}U($(a)),y&&S(v)}finally{S(m)}return R(r,s),D(r,y=>{y.plugins[e]={enabled:n.enable?!0:y.plugins[e]?.enabled??!0,version:f}}),be(r,e,n.etag,{swapped:!0}),{manifest:b,validated:t,version:f,root:a,staged:l}}c(Je,"installBundleArchive");export{he as bundleVersion,Je as installBundleArchive,Pe as isInstalledGeneration,be as recordCheckedGeneration,fe as validatePluginBundle,ve as writeStagedBundle};

package/dist/core/command-plugins/caller-header.d.ts

@@ -0,0 +1,10 @@
+export interface CrtrCallerFields {
+    node?: string | undefined;
+    machine?: string | undefined;
+    profile?: string | undefined;
+    run?: string | undefined;
+}
+/** `node=<id>; machine=<id>; profile=<id>; run=<id>`, in that order. A field
+ *  that is empty, or whose value holds `;`, `=`, CR or LF, is left out rather
+ *  than injected into the header. Returns '' when no field remains. */
+export declare function formatCrtrCaller(fields: CrtrCallerFields): string;

package/dist/core/command-plugins/caller-header.js

@@ -0,0 +1 @@
+var f=Object.defineProperty;var e=(o,n)=>f(o,"name",{value:n,configurable:!0});function s(o){const n=[];for(const r of["node","machine","profile","run"]){const t=o[r];typeof t!="string"||t===""||/[;=\r\n]/.test(t)||n.push(`${r}=${t}`)}return n.join("; ")}e(s,"formatCrtrCaller");export{s as formatCrtrCaller};

package/dist/core/command-plugins/compose.js

@@ -1 +1 @@
-var k=Object.defineProperty;var u=(n,e)=>k(n,"name",{value:e,configurable:!0});import{resolve as x}from"node:path";import{envNodeId as C}from"../../shared/env.js";import{cliClient as l}from"../../commands/api-client.js";import{apiErrorToCliError as j}from"../io.js";import{ApiError as L}from"../../api/index.js";import{defineBranch as h,defineLeaf as T}from"../command.js";import{resolveCommandRegistry as U}from"../command-manifests/registry.js";import{executeExternalLeaf as M}from"./transport/exec-invoke.js";import{invokeHttpLeaf as A}from"./transport/http-invoke.js";import{readPathParam as S}from"./transport/http-plan.js";async function N(n){const e=await l().request("GET",`/v1/providers/${encodeURIComponent(n)}/tools`);return new Set(e.groups.flatMap(r=>r.leaves.map(a=>a.tool)))}u(N,"allowedProviderTools");function m(n,e,r){return n.children.some(a=>a.kind==="leaf"?r.has([...e,a.name].join(" ")):m(a,[...e,a.name],r))}u(m,"hasAllowedLeaf");function P(n,e,r){return n.children.filter(a=>a.tier!=="hidden"&&(a.kind==="leaf"?r.has([...e,a.name].join(" ")):m(a,[...e,a.name],r))).length}u(P,"visibleChildCount");function _(n,e,r){return async()=>{if(!C())return n.help;const a=await N(e.id);return{...n.help,listing:n.help.listing?.flatMap(t=>{const i=n.children.find(s=>s.name===t.name);if(i?.kind==="leaf")return a.has([...r,i.name].join(" "))?[t]:[];if(i?.kind!=="branch")return[];const o=[...r,i.name];if(!m(i,o,a))return[];const p=P(i,o,a);return[{...t,...t.subCount!==void 0?{subCount:p}:{}}]})}}}u(_,"providerHelp");const $="Runs on one of your devices. Add `--machine <machine_id>` to pick which; without it the call goes to your only device, and with several the answer is `machine_required` listing each one's machine_id. The `runtime:` prefix on the id is optional.";function g(n,e,r,a=!1){return{outputKind:"object",...a?{machineSelector:!0}:{},run:u(async(t,i)=>{const o={...t};for(const p of r.params){if(!("type"in p))continue;const s=p.name.replace(/-([a-z])/g,(c,w)=>w.toUpperCase()),d=o[s];p.type==="file"&&typeof d=="string"?o[s]=x(d):p.type==="path"&&d!==void 0&&(o[s]=S(`provider command \`${n} ${e}\``,p,d))}try{return await l({timeoutMs:0}).request("POST","/v1/provider/call",{provider:n,tool:e,arguments:o,...i?.machine===void 0?{}:{machine:i.machine}},{timeout:0})}catch(p){throw p instanceof L?j(p,void 0,{providerCall:!0}):p}},"run")}}u(g,"providerLeafAdapter");function v(n,e){return/^[A-Za-z0-9_-]{1,64}$/.test(n)&&n!=="crtr"&&!e.has(n)}u(v,"validRootName");function F(n,e){const r=[],a=[];for(const t of n){const{provider:i,commands:o}=t;if(!Array.isArray(o)||t.status!=="available"&&!v(i,e))continue;if(t.status!=="available"){const s=t.error??"bundle installation pending",d=`Unavailable (${t.status}): ${s}`,c=h({name:i,rootEntry:{concept:t.display_name,desc:d,useWhen:d},help:{name:i,summary:d},children:[]});c.unavailable=d,a.push(c);continue}const p=u(s=>s.kind==="branch"?{...s,children:s.children.map(p)}:{...s,rest:{method:"GET",path:"/",params:{}}},"helpNode");for(const s of o)s.kind!=="branch"||!Array.isArray(s.children)||!v(s.name,e)||r.push({contributor:{name:i,scope:"user"},manifestName:s.name,node:p(s),adaptLeaf:u((d,c)=>g(i,c.slice(1).join(" "),d,t.transport==="machine"),"adaptLeaf")})}return[...b(U(r,e)),...a]}u(F,"composeSandboxProviderSubtrees");function y(n,e){return(r,a)=>{const t=n.transport,i=e(a);if(n.provider!==void 0)return g(n.provider.id,i.slice(1).join(" "),r,t.kind==="machine");if(t.kind==="exec"){const p=t.executable;if(p===void 0)throw new Error(`exec plugin "${n.plugin.name}" has an executable leaf without transport.executable`);return{outputKind:"object",run:u(async s=>M({plugin:n.plugin,executable:p,commandPath:i,output:r.output},s),"run")}}if(t.kind==="machine")throw new Error(`machine plugin "${n.plugin.name}" is not a capability provider`);const o=r;return{outputKind:o.rest.streaming===!0?"jsonl":"object",run:u((p,s)=>A({registration:{name:n.plugin.name,endpoint:t.endpoint,...t.authEnv!==void 0?{authEnv:t.authEnv}:{}},...n.manifest?.baseUrl!==void 0?{baseUrl:n.manifest.baseUrl}:{},...n.manifest?.timeouts!==void 0?{timeouts:n.manifest.timeouts}:{},params:o.params,rest:o.rest,output:o.output,commandPath:i},p,s),"run")}}}u(y,"adaptLeaf");function Z(n){return{contributions:n.map(e=>({contributor:{name:e.plugin.name,scope:e.plugin.scope,sourceMarketplace:e.plugin.sourceMarketplace},node:e.node,manifestName:e.manifestName,adaptLeaf:y(e,r=>[e.manifestName,...r.slice(1)]),...e.provider!==void 0?{provider:e.provider}:{}})),coreMounts:[],issues:[]}}u(Z,"adaptPluginContributions");function J(n){return n.map(e=>({parent:e.parent,plugin:e.plugin.name,contributor:{name:e.plugin.name,scope:e.plugin.scope,sourceMarketplace:e.plugin.sourceMarketplace},node:e.node,...e.provider!==void 0?{provider:e.provider}:{},adaptLeaf:y({...e,manifestName:e.node.name},r=>e.provider===void 0?[...r]:[e.provider.id,...r.slice(e.parent.length)])}))}u(J,"adaptPluginCoreMounts");function b(n){return n.contributions.map(e=>f(e,e.node,[e.node.name]))}u(b,"composeExternalSubtrees");function Q(n,e){return n.filter(r=>r.parent.join("\0")===e.join("\0")).map(r=>r.node.kind==="branch"?f(r,r.node,[...e,r.node.name],r.provider===void 0?1:e.length):E(r,r.node,[...e,r.node.name]))}u(Q,"composeCoreBranchMounts");function f(n,e,r,a=1){const t=e.rootEntry===void 0?void 0:{concept:e.rootEntry.concept,desc:e.rootEntry.description,useWhen:e.rootEntry.whenToUse},i=h({name:e.name,description:e.description,whenToUse:e.whenToUse,...e.tier!==void 0?{tier:e.tier}:{},...n.plugin!==void 0?{plugin:n.plugin}:{},...t!==void 0?{rootEntry:t}:{},help:{name:r.join(" "),summary:e.summary,...e.model!==void 0?{model:e.model}:{},...r.length===1&&n.extensionIssue!==void 0?{extensionIssue:n.extensionIssue}:{}},...e.passthrough!==void 0?{passthrough:e.passthrough}:{},children:e.children.map(o=>o.kind==="branch"?f(n,o,[...r,o.name],a):E(n,o,[...r,o.name]))});return n.provider!==void 0&&(i.effectiveHelp=_(i,n.provider,r.slice(a))),i}u(f,"buildBranch");function E(n,e,r){const a=n.adaptLeaf(e,r);return T({name:e.name,description:e.description,whenToUse:e.whenToUse,...e.tier!==void 0?{tier:e.tier}:{},...n.plugin!==void 0?{plugin:n.plugin}:{},...a.machineSelector===!0?{machineSelector:!0}:{},help:{name:r.join(" "),summary:e.summary,...a.machineSelector===!0?{guide:$}:{},params:e.params,output:e.output,outputKind:a.outputKind,effects:[...e.effects]},run:a.run})}u(E,"buildLeaf");export{Z as adaptPluginContributions,J as adaptPluginCoreMounts,Q as composeCoreBranchMounts,b as composeExternalSubtrees,F as composeSandboxProviderSubtrees};
+var x=Object.defineProperty;var o=(n,e)=>x(n,"name",{value:e,configurable:!0});import{resolve as T}from"node:path";import{envNodeId as j}from"../../shared/env.js";import{cliClient as m}from"../../commands/api-client.js";import{apiErrorToCliError as l}from"../io.js";import{ApiError as f}from"../../api/index.js";import{defineBranch as v,defineLeaf as A}from"../command.js";import{resolveCommandRegistry as _}from"../command-manifests/registry.js";import{executeExternalLeaf as L}from"./transport/exec-invoke.js";import{invokeHttpLeaf as M}from"./transport/http-invoke.js";import{readPathParam as U}from"./transport/http-plan.js";import{sha256Hex as N,signedHeaderDigest as P}from"./transport/sign.js";import{needsAppToken as S}from"../plugin-objects-manifest.js";async function R(n){const e=await m().request("GET",`/v1/providers/${encodeURIComponent(n)}/tools`);return new Set(e.groups.flatMap(r=>r.leaves.map(a=>a.tool)))}o(R,"allowedProviderTools");function h(n,e,r){return n.children.some(a=>a.kind==="leaf"?r.has([...e,a.name].join(" ")):h(a,[...e,a.name],r))}o(h,"hasAllowedLeaf");function H(n,e,r){return n.children.filter(a=>a.tier!=="hidden"&&(a.kind==="leaf"?r.has([...e,a.name].join(" ")):h(a,[...e,a.name],r))).length}o(H,"visibleChildCount");function $(n,e,r){return async()=>{if(!j())return n.help;const a=await R(e.id);return{...n.help,listing:n.help.listing?.flatMap(t=>{const i=n.children.find(s=>s.name===t.name);if(i?.kind==="leaf")return a.has([...r,i.name].join(" "))?[t]:[];if(i?.kind!=="branch")return[];const u=[...r,i.name];if(!h(i,u,a))return[];const p=H(i,u,a);return[{...t,...t.subCount!==void 0?{subCount:p}:{}}]})}}}o($,"providerHelp");const I="Runs on one of your devices. Add `--machine <machine_id>` to pick which; without it the call goes to your only device, and with several the answer is `machine_required` listing each one's machine_id. The `runtime:` prefix on the id is optional.";function y(n,e,r,a=!1){return{outputKind:"object",...a?{machineSelector:!0}:{},run:o(async(t,i)=>{const u={...t};for(const p of r.params){if(!("type"in p))continue;const s=p.name.replace(/-([a-z])/g,(c,C)=>C.toUpperCase()),d=u[s];p.type==="file"&&typeof d=="string"?u[s]=T(d):p.type==="path"&&d!==void 0&&(u[s]=U(`provider command \`${n} ${e}\``,p,d))}try{return await m({timeoutMs:0}).request("POST","/v1/provider/call",{provider:n,tool:e,arguments:u,...i?.machine===void 0?{}:{machine:i.machine}},{timeout:0})}catch(p){throw p instanceof f?l(p,void 0,{providerCall:!0}):p}},"run")}}o(y,"providerLeafAdapter");function E(n,e){return/^[A-Za-z0-9_-]{1,64}$/.test(n)&&n!=="crtr"&&!e.has(n)}o(E,"validRootName");function Y(n,e){const r=[],a=[];for(const t of n){const{provider:i,commands:u}=t;if(!Array.isArray(u)||t.status!=="available"&&!E(i,e))continue;if(t.status!=="available"){const s=t.error??"bundle installation pending",d=`Unavailable (${t.status}): ${s}`,c=v({name:i,rootEntry:{concept:t.display_name,desc:d,useWhen:d},help:{name:i,summary:d},children:[]});c.unavailable=d,a.push(c);continue}const p=o(s=>s.kind==="branch"?{...s,children:s.children.map(p)}:{...s,rest:{method:"GET",path:"/",params:{}}},"helpNode");for(const s of u)s.kind!=="branch"||!Array.isArray(s.children)||!E(s.name,e)||r.push({contributor:{name:i,scope:"user"},manifestName:s.name,node:p(s),adaptLeaf:o((d,c)=>y(i,c.slice(1).join(" "),d,t.transport==="machine"),"adaptLeaf")})}return[...b(_(r,e)),...a]}o(Y,"composeSandboxProviderSubtrees");async function K(n){try{const{token:e,socket:r}=await m().plugins.appToken(n);return{CRTR_APP_TOKEN:e,CRTR_DAEMON_SOCKET:r}}catch(e){if(e instanceof f&&(e.status===404||e.status===403))return;throw e instanceof f?l(e):e}}o(K,"appEnvFor");function w(n,e){return(r,a)=>{const t=n.transport,i=e(a);if(n.provider!==void 0)return y(n.provider.id,i.slice(1).join(" "),r,t.kind==="machine");if(t.kind==="exec"){const p=t.executable;if(p===void 0)throw new Error(`exec plugin "${n.plugin.name}" has an executable leaf without transport.executable`);return{outputKind:"object",run:o(async s=>{const d=S(n.plugin.manifest)?await K(n.plugin.name):void 0;return L({plugin:n.plugin,executable:p,commandPath:i,output:r.output,...d!==void 0?{appEnv:d}:{}},s)},"run")}}if(t.kind==="machine")throw new Error(`machine plugin "${n.plugin.name}" is not a capability provider`);const u=r;return{outputKind:u.rest.streaming===!0?"jsonl":"object",run:o((p,s)=>M({registration:{name:n.plugin.name,endpoint:t.endpoint,...t.authEnv!==void 0?{authEnv:t.authEnv}:{}},...n.manifest?.baseUrl!==void 0?{baseUrl:n.manifest.baseUrl}:{},...n.manifest?.timeouts!==void 0?{timeouts:n.manifest.timeouts}:{},params:u.params,rest:u.rest,output:u.output,commandPath:i},p,s,{callHeaders:o(d=>m().plugins.callHeaders(n.plugin.name,{method:d.method,url:d.url.href,body_sha256:N(d.body),...P(d.headers)}).then(c=>c.headers,c=>{throw c instanceof f?l(c):c}),"callHeaders")}),"run")}}}o(w,"adaptLeaf");function ee(n){return{contributions:n.map(e=>({contributor:{name:e.plugin.name,scope:e.plugin.scope,sourceMarketplace:e.plugin.sourceMarketplace},node:e.node,manifestName:e.manifestName,adaptLeaf:w(e,r=>[e.manifestName,...r.slice(1)]),...e.provider!==void 0?{provider:e.provider}:{}})),coreMounts:[],issues:[]}}o(ee,"adaptPluginContributions");function ne(n){return n.map(e=>({parent:e.parent,plugin:e.plugin.name,contributor:{name:e.plugin.name,scope:e.plugin.scope,sourceMarketplace:e.plugin.sourceMarketplace},node:e.node,...e.provider!==void 0?{provider:e.provider}:{},adaptLeaf:w({...e,manifestName:e.node.name},r=>e.provider===void 0?[...r]:[e.provider.id,...r.slice(e.parent.length)])}))}o(ne,"adaptPluginCoreMounts");function b(n){return n.contributions.map(e=>g(e,e.node,[e.node.name]))}o(b,"composeExternalSubtrees");function re(n,e){return n.filter(r=>r.parent.join("\0")===e.join("\0")).map(r=>r.node.kind==="branch"?g(r,r.node,[...e,r.node.name],r.provider===void 0?1:e.length):k(r,r.node,[...e,r.node.name]))}o(re,"composeCoreBranchMounts");function g(n,e,r,a=1){const t=e.rootEntry===void 0?void 0:{concept:e.rootEntry.concept,desc:e.rootEntry.description,useWhen:e.rootEntry.whenToUse},i=v({name:e.name,description:e.description,whenToUse:e.whenToUse,...e.tier!==void 0?{tier:e.tier}:{},...n.plugin!==void 0?{plugin:n.plugin}:{},...t!==void 0?{rootEntry:t}:{},help:{name:r.join(" "),summary:e.summary,...e.model!==void 0?{model:e.model}:{},...r.length===1&&n.extensionIssue!==void 0?{extensionIssue:n.extensionIssue}:{}},...e.passthrough!==void 0?{passthrough:e.passthrough}:{},children:e.children.map(u=>u.kind==="branch"?g(n,u,[...r,u.name],a):k(n,u,[...r,u.name]))});return n.provider!==void 0&&(i.effectiveHelp=$(i,n.provider,r.slice(a))),i}o(g,"buildBranch");function k(n,e,r){const a=n.adaptLeaf(e,r);return A({name:e.name,description:e.description,whenToUse:e.whenToUse,...e.tier!==void 0?{tier:e.tier}:{},...n.plugin!==void 0?{plugin:n.plugin}:{},...a.machineSelector===!0?{machineSelector:!0}:{},help:{name:r.join(" "),summary:e.summary,...a.machineSelector===!0?{guide:I}:{},params:e.params,output:e.output,outputKind:a.outputKind,effects:[...e.effects]},run:a.run})}o(k,"buildLeaf");export{ee as adaptPluginContributions,ne as adaptPluginCoreMounts,re as composeCoreBranchMounts,b as composeExternalSubtrees,Y as composeSandboxProviderSubtrees};

package/dist/core/command-plugins/endpoint.d.ts

@@ -12,6 +12,10 @@ export interface EndpointValidation {
     isValid: boolean;
     errors: string[];
 }
+/** Hosts `http:` is allowed for: loopback, Docker's host alias, and any
+ *  `*.localhost` name (RFC 6761 reserves it for local use; the local
+ *  directory and provider stacks serve `http://<svc>.localhost:<port>`). */
+export declare function isLoopbackHostname(hostname: string): boolean;
 export declare function validateEndpoint(endpoint: unknown): EndpointValidation;
 export declare function normalizeEndpoint(endpoint: string): string;
 export declare function validateHttpPluginTransport(raw: unknown): {

package/dist/core/command-plugins/endpoint.js

@@ -1 +1 @@
-var i=Object.defineProperty;var e=(n,t)=>i(n,"name",{value:t,configurable:!0});import{validateEnvVarName as p}from"../env-name.js";function h(n){return n==="localhost"||n.endsWith(".localhost")||n==="127.0.0.1"||n==="[::1]"||n==="::1"||n==="host.docker.internal"}e(h,"isLoopbackHostname");function l(n){const t=[];if(typeof n!="string")t.push("endpoint must be a string");else try{const o=new URL(n);(o.protocol!=="https:"&&!(o.protocol==="http:"&&h(o.hostname))||o.username||o.password||o.hash)&&t.push("endpoint must be an absolute https:// URL (http:// permitted for loopback and *.localhost hosts only; no credentials or fragment)")}catch{t.push("endpoint must be an absolute https:// URL (http:// permitted for loopback and *.localhost hosts only; no credentials or fragment)")}return{isValid:t.length===0,errors:t}}e(l,"validateEndpoint");function u(n){try{const t=new URL(n),o=t.pathname.length>1&&t.pathname.endsWith("/")?t.pathname.slice(0,-1):t.pathname;return`${t.protocol}//${t.host}${o}${t.search}`}catch{return n}}e(u,"normalizeEndpoint");function c(n){const t=[];if(typeof n!="object"||n===null||Array.isArray(n))return{errors:["transport must be an object"]};const o=n,r=Object.keys(o).filter(a=>!["kind","endpoint","authEnv"].includes(a));r.length&&t.push(`transport has unknown keys: ${r.join(", ")}`),o.kind!=="http"&&t.push('transport.kind must be "http"');const s=l(o.endpoint);return t.push(...s.errors),o.authEnv!==void 0&&t.push(...p(o.authEnv).errors),t.length?{errors:t}:{transport:{kind:"http",endpoint:u(o.endpoint),...o.authEnv!==void 0?{authEnv:o.authEnv}:{}},errors:t}}e(c,"validateHttpPluginTransport");function m(n){if(typeof n=="object"&&n!==null&&!Array.isArray(n)&&n.kind==="machine"){const t=Object.keys(n).filter(o=>o!=="kind");return t.length?{errors:[`transport has unknown keys: ${t.join(", ")}`]}:{transport:{kind:"machine"},errors:[]}}return c(n)}e(m,"validateBundleTransport");export{u as normalizeEndpoint,m as validateBundleTransport,l as validateEndpoint,c as validateHttpPluginTransport};
+var p=Object.defineProperty;var e=(n,t)=>p(n,"name",{value:t,configurable:!0});import{validateEnvVarName as i}from"../env-name.js";function h(n){return n==="localhost"||n.endsWith(".localhost")||n==="127.0.0.1"||n==="[::1]"||n==="::1"||n==="host.docker.internal"}e(h,"isLoopbackHostname");function l(n){const t=[];if(typeof n!="string")t.push("endpoint must be a string");else try{const o=new URL(n);(o.protocol!=="https:"&&!(o.protocol==="http:"&&h(o.hostname))||o.username||o.password||o.hash)&&t.push("endpoint must be an absolute https:// URL (http:// permitted for loopback and *.localhost hosts only; no credentials or fragment)")}catch{t.push("endpoint must be an absolute https:// URL (http:// permitted for loopback and *.localhost hosts only; no credentials or fragment)")}return{isValid:t.length===0,errors:t}}e(l,"validateEndpoint");function u(n){try{const t=new URL(n),o=t.pathname.length>1&&t.pathname.endsWith("/")?t.pathname.slice(0,-1):t.pathname;return`${t.protocol}//${t.host}${o}${t.search}`}catch{return n}}e(u,"normalizeEndpoint");function c(n){const t=[];if(typeof n!="object"||n===null||Array.isArray(n))return{errors:["transport must be an object"]};const o=n,r=Object.keys(o).filter(a=>!["kind","endpoint","authEnv"].includes(a));r.length&&t.push(`transport has unknown keys: ${r.join(", ")}`),o.kind!=="http"&&t.push('transport.kind must be "http"');const s=l(o.endpoint);return t.push(...s.errors),o.authEnv!==void 0&&t.push(...i(o.authEnv).errors),t.length?{errors:t}:{transport:{kind:"http",endpoint:u(o.endpoint),...o.authEnv!==void 0?{authEnv:o.authEnv}:{}},errors:t}}e(c,"validateHttpPluginTransport");function m(n){if(typeof n=="object"&&n!==null&&!Array.isArray(n)&&n.kind==="machine"){const t=Object.keys(n).filter(o=>o!=="kind");return t.length?{errors:[`transport has unknown keys: ${t.join(", ")}`]}:{transport:{kind:"machine"},errors:[]}}return c(n)}e(m,"validateBundleTransport");export{h as isLoopbackHostname,u as normalizeEndpoint,m as validateBundleTransport,l as validateEndpoint,c as validateHttpPluginTransport};

package/dist/core/command-plugins/transport/exec-invoke-async.d.ts

@@ -0,0 +1,11 @@
+import { type ExternalLeafSpec } from './exec-invoke.js';
+export interface AsyncLeafOptions {
+    /** Wall-clock budget; the child is SIGKILLed when it runs out. */
+    deadlineMs: number;
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+}
+/** Run one external leaf without blocking, and return its result object. Rejects
+ *  with `plugin_timeout` at the deadline (child killed), a protocol error on a
+ *  stdout overrun (child killed), or whatever `parseLeafEnvelope` raises. */
+export declare function executeExternalLeafAsync(spec: ExternalLeafSpec, input: Record<string, unknown>, options: AsyncLeafOptions): Promise<Record<string, unknown>>;

package/dist/core/command-plugins/transport/exec-invoke-async.js

@@ -0,0 +1 @@
+var y=Object.defineProperty;var i=(r,s)=>y(r,"name",{value:s,configurable:!0});import{spawn as I}from"node:child_process";import{CrtrError as a}from"../../errors.js";import{ExitCode as p}from"../../../types.js";import{buildLeafRequest as T,label as R,MAX_STDOUT as k,parseLeafEnvelope as A,protocolError as h}from"./exec-invoke.js";const g=64*1024;function v(r,s,o){const w=T(r,s,o.cwd);return new Promise((L,l)=>{const t=I(r.executable,["--crtr-command-protocol","1"],{cwd:o.cwd,env:o.env,stdio:["pipe","pipe","pipe"],detached:!0}),u=[];let f=0,n=Buffer.alloc(0),c=!1;const m=i(()=>{try{t.pid!==void 0?process.kill(-t.pid,"SIGKILL"):t.kill("SIGKILL")}catch{try{t.kill("SIGKILL")}catch{}}},"kill"),d=i(e=>{c||(c=!0,clearTimeout(S),e())},"finish"),E=i(e=>!(e instanceof a)||e.code!=="plugin_protocol_error"||n.length===0?e:new a(e.code,`${e.message} stderr: ${n.toString("utf8").trim()}`,p.GENERAL,e.details),"withStderr"),S=setTimeout(()=>{m(),d(()=>l(new a("plugin_timeout",`${R(r)}: no answer within ${o.deadlineMs} ms; the process was killed`,p.GENERAL,{next:"Retry, or inspect the plugin with `crtr sys doctor`."})))},o.deadlineMs);t.stdout.on("data",e=>{if(!c){if(f+=e.length,f>k){m(),d(()=>l(h(r,"stdout exceeded the 10 MiB cap","one JSON envelope under 10 MiB on stdout")));return}u.push(e)}}),t.stderr.on("data",e=>{n=Buffer.concat([n,e]),n.length>g&&(n=n.subarray(n.length-g))}),t.on("error",e=>{d(()=>l(h(r,`executable could not be run (${e.code??e.message})`,"a runnable command executable")))}),t.on("close",(e,x)=>{d(()=>{try{L(A(r,Buffer.concat(u).toString("utf8"),e,x))}catch(b){l(E(b))}})}),t.stdin.on("error",()=>{}),t.stdin.end(JSON.stringify(w))})}i(v,"executeExternalLeafAsync");export{v as executeExternalLeafAsync};

package/dist/core/command-plugins/transport/exec-invoke.d.ts

@@ -1,5 +1,7 @@
 import type { InstalledPlugin } from '../../../types.js';
 import type { Field } from '../../help.js';
+import { CrtrError } from '../../errors.js';
+export declare const MAX_STDOUT: number;
 export type ExternalLeafSpec = {
     plugin: InstalledPlugin;
     extension?: never;
@@ -9,6 +11,8 @@ export type ExternalLeafSpec = {
     commandPath: string[];
     /** Declared leaf output fields — validated against the result before render. */
     output: Field[];
+    /** Extra environment for this call, layered over the inherited environment. */
+    appEnv?: Record<string, string>;
 } | {
     plugin?: never;
     extension: {
@@ -21,8 +25,18 @@ export type ExternalLeafSpec = {
     commandPath: string[];
     /** Declared leaf output fields — validated against the result before render. */
     output: Field[];
+    /** Extra environment for this call, layered over the inherited environment. */
+    appEnv?: Record<string, string>;
 };
+/** The one JSON request written to the plugin's stdin. */
+export declare function buildLeafRequest(spec: ExternalLeafSpec, input: Record<string, unknown>, cwd: string): Record<string, unknown>;
 /** Execute one external leaf and return its result object (crtr renders it via
  *  the generic renderer; `--json` mirrors it). Throws a CrtrError for any
  *  protocol violation or the plugin's own recoverable error. */
 export declare function executeExternalLeaf(spec: ExternalLeafSpec, input: Record<string, unknown>): Record<string, unknown>;
+/** Turn a finished plugin process (stdout text, exit status, terminating signal)
+ *  into the result object, or throw the plugin's own error or a protocol error.
+ *  Shared by the synchronous and asynchronous runners. */
+export declare function parseLeafEnvelope(spec: ExternalLeafSpec, stdout: string, status: number | null, signal: NodeJS.Signals | null): Record<string, unknown>;
+export declare function protocolError(spec: ExternalLeafSpec, received: string, expected: string): CrtrError;
+export declare function label(spec: ExternalLeafSpec): string;

package/dist/core/command-plugins/transport/exec-invoke.js

@@ -1 +1 @@
-var v=Object.defineProperty;var u=(e,i)=>v(e,"name",{value:i,configurable:!0});import{spawnSync as $}from"node:child_process";import{validateDeclaredResult as b}from"../../../api/command-manifest/result.js";import{CrtrError as m}from"../../errors.js";import{diag as g}from"../../io.js";import{ExitCode as h}from"../../../types.js";import{isRecord as f}from"../../../shared/predicates.js";const E=10*1024*1024,w=new Set(["internal","unknown_path","command_collision","plugin_protocol_error"]),S=/^[a-z][a-z0-9]*(_[a-z0-9]+)*$/,x="Run `crtr pkg plugin show` or `crtr sys doctor` to inspect the plugin.";function j(e,i){const s={protocolVersion:1,command:e.commandPath,input:i,context:{cwd:process.cwd(),...e.plugin!==void 0?{plugin:{name:e.plugin.name,version:e.plugin.version??e.plugin.manifest.version??null,scope:e.plugin.scope,root:e.plugin.root}}:{extension:e.extension}}},o=$(e.executable,["--crtr-command-protocol","1"],{input:JSON.stringify(s),cwd:process.cwd(),env:process.env,maxBuffer:E,stdio:["pipe","pipe","inherit"],encoding:"utf8"});if(o.error!==void 0){const l=o.error;throw l.code==="ENOBUFS"||l.code==="ERR_CHILD_PROCESS_STDIO_MAXBUFFER"?t(e,"stdout exceeded the 10 MiB cap","one JSON envelope under 10 MiB on stdout"):t(e,`executable could not be run (${l.code??l.message})`,"a runnable command executable")}if(o.signal!==null)throw t(e,`executable was killed by signal ${o.signal}`,"a clean exit with one JSON envelope on stdout");const a=o.stdout??"";let n;try{n=JSON.parse(a.trim())}catch{throw t(e,"stdout was not a single JSON envelope","exactly one JSON envelope on stdout")}if(!f(n))throw t(e,"stdout was not a JSON object","a { protocolVersion: 1, ok: boolean, ... } envelope");if(n.protocolVersion!==1)throw t(e,`unsupported protocolVersion ${String(n.protocolVersion)}`,"protocolVersion exactly 1");if(typeof n.ok!="boolean")throw t(e,'envelope is missing a boolean "ok"',"a boolean ok field");const c=n.ok;if(c&&o.status!==0?g(`crtr: ${p(e)} returned ok:true but exited ${o.status} (honoring the envelope)`):!c&&o.status===0&&g(`crtr: ${p(e)} returned ok:false but exited 0 (honoring the envelope)`),c){const l=n.result;if(!f(l))throw t(e,"success envelope has no result object","result: an object matching the declared output");return y(e,l),l}const r=n.error;if(!f(r)||typeof r.code!="string"||typeof r.message!="string")throw t(e,"error envelope is missing a { code, message }","error: { code, message, ... }");const d=r.code;throw!S.test(d)||w.has(d)?t(e,`error code "${d}" is invalid or reserved`,`a lowercase snake_case code not in {${[...w].join(", ")}}`):new m(d,r.message,h.GENERAL,{received:r.received,field:typeof r.field=="string"?r.field:void 0,next:typeof r.next=="string"?r.next:x})}u(j,"executeExternalLeaf");function y(e,i){const s=b(e.output,i);if(s===null)return;const o=s.field,a=e.output.find(n=>n.name===o);throw s.receivedType!==void 0?t(e,`output field "${o}" has the wrong type`,`${o}: ${a?.type??"unknown"}`):t(e,`result is missing required output field "${o}"`,`a "${o}" field of type ${a?.type??"unknown"}`)}u(y,"validateResult");function t(e,i,s){return new m("plugin_protocol_error",`${p(e)}: ${i}. Expected ${s}.`,h.GENERAL,{received:i,next:x})}u(t,"protocolError");function p(e){return e.plugin!==void 0?`plugin "${e.plugin.name}" command \`${e.commandPath.join(" ")}\``:`extension branch "${e.extension.branch}" command \`${e.commandPath.join(" ")}\``}u(p,"label");export{j as executeExternalLeaf};
+var x=Object.defineProperty;var u=(e,r)=>x(e,"name",{value:r,configurable:!0});import{spawnSync as v}from"node:child_process";import{validateDeclaredResult as $}from"../../../api/command-manifest/result.js";import{CrtrError as f}from"../../errors.js";import{diag as m}from"../../io.js";import{ExitCode as g}from"../../../types.js";import{isRecord as c}from"../../../shared/predicates.js";const E=10*1024*1024,h=new Set(["internal","unknown_path","command_collision","plugin_protocol_error"]),b=/^[a-z][a-z0-9]*(_[a-z0-9]+)*$/,w="Run `crtr pkg plugin show` or `crtr sys doctor` to inspect the plugin.";function S(e,r,t){return{protocolVersion:1,command:e.commandPath,input:r,context:{cwd:t,...e.plugin!==void 0?{plugin:{name:e.plugin.name,version:e.plugin.version??e.plugin.manifest.version??null,scope:e.plugin.scope,root:e.plugin.root}}:{extension:e.extension}}}}u(S,"buildLeafRequest");function D(e,r){const t=S(e,r,process.cwd()),n=v(e.executable,["--crtr-command-protocol","1"],{input:JSON.stringify(t),cwd:process.cwd(),env:{...process.env,...e.appEnv},maxBuffer:E,stdio:["pipe","pipe","inherit"],encoding:"utf8"});if(n.error!==void 0){const o=n.error;throw o.code==="ENOBUFS"||o.code==="ERR_CHILD_PROCESS_STDIO_MAXBUFFER"?i(e,"stdout exceeded the 10 MiB cap","one JSON envelope under 10 MiB on stdout"):i(e,`executable could not be run (${o.code??o.message})`,"a runnable command executable")}return y(e,n.stdout??"",n.status,n.signal)}u(D,"executeExternalLeaf");function y(e,r,t,n){if(n!==null)throw i(e,`executable was killed by signal ${n}`,"a clean exit with one JSON envelope on stdout");let o;try{o=JSON.parse(r.trim())}catch{throw i(e,"stdout was not a single JSON envelope","exactly one JSON envelope on stdout")}if(!c(o))throw i(e,"stdout was not a JSON object","a { protocolVersion: 1, ok: boolean, ... } envelope");if(o.protocolVersion!==1)throw i(e,`unsupported protocolVersion ${String(o.protocolVersion)}`,"protocolVersion exactly 1");if(typeof o.ok!="boolean")throw i(e,'envelope is missing a boolean "ok"',"a boolean ok field");const a=o.ok;if(a&&t!==0?m(`crtr: ${p(e)} returned ok:true but exited ${t} (honoring the envelope)`):!a&&t===0&&m(`crtr: ${p(e)} returned ok:false but exited 0 (honoring the envelope)`),a){const s=o.result;if(!c(s))throw i(e,"success envelope has no result object","result: an object matching the declared output");return k(e,s),s}const l=o.error;if(!c(l)||typeof l.code!="string"||typeof l.message!="string")throw i(e,"error envelope is missing a { code, message }","error: { code, message, ... }");const d=l.code;throw!b.test(d)||h.has(d)?i(e,`error code "${d}" is invalid or reserved`,`a lowercase snake_case code not in {${[...h].join(", ")}}`):new f(d,l.message,g.GENERAL,{received:l.received,field:typeof l.field=="string"?l.field:void 0,next:typeof l.next=="string"?l.next:w})}u(y,"parseLeafEnvelope");function k(e,r){const t=$(e.output,r);if(t===null)return;const n=t.field,o=e.output.find(a=>a.name===n);throw t.receivedType!==void 0?i(e,`output field "${n}" has the wrong type`,`${n}: ${o?.type??"unknown"}`):i(e,`result is missing required output field "${n}"`,`a "${n}" field of type ${o?.type??"unknown"}`)}u(k,"validateResult");function i(e,r,t){return new f("plugin_protocol_error",`${p(e)}: ${r}. Expected ${t}.`,g.GENERAL,{received:r,next:w})}u(i,"protocolError");function p(e){return e.plugin!==void 0?`plugin "${e.plugin.name}" command \`${e.commandPath.join(" ")}\``:`extension branch "${e.extension.branch}" command \`${e.commandPath.join(" ")}\``}u(p,"label");export{E as MAX_STDOUT,S as buildLeafRequest,D as executeExternalLeaf,p as label,y as parseLeafEnvelope,i as protocolError};

package/dist/core/command-plugins/transport/http-invoke.d.ts

@@ -1,5 +1,12 @@
 import type { LeafRunContext } from '../../command.js';
-import type { HttpInvokerSpec } from './http-plan.js';
+import type { HttpInvokerSpec, RequestPlan } from './http-plan.js';
+/** Optional hooks around one call. With none, a call behaves exactly as before. */
+export interface InvokeHttpOptions {
+    /** Called once with the final plan; the headers it returns are set last, so a
+     *  connection retry (which reuses the plan) resends the same values. A
+     *  rejection fails the call and nothing is sent. */
+    callHeaders?: (plan: RequestPlan) => Promise<Record<string, string>>;
+}
 /**
  * Execute one HTTP-transport plugin leaf. Unary leaves return the validated response
  * object (crtr's ordinary dispatcher renders it, or mirrors it under --json).
@@ -12,4 +19,4 @@ import type { HttpInvokerSpec } from './http-plan.js';
  * process.exitCode = NETWORK — it never throws into handle() and never writes a
  * second result/error object to stdout.
  */
-export declare function invokeHttpLeaf(spec: HttpInvokerSpec, input: Record<string, unknown>, context?: LeafRunContext): Promise<Record<string, unknown> | void>;
+export declare function invokeHttpLeaf(spec: HttpInvokerSpec, input: Record<string, unknown>, context?: LeafRunContext, options?: InvokeHttpOptions): Promise<Record<string, unknown> | void>;

package/dist/core/command-plugins/transport/http-invoke.js

@@ -1,3 +1,3 @@
-var P=Object.defineProperty;var i=(t,e)=>P(t,"name",{value:e,configurable:!0});import{randomUUID as U}from"node:crypto";import{request as R}from"node:http";import{request as C}from"node:https";import{buildRequestPlan as A,mapUnary2xx as F,throwNon2xx as M}from"./http-plan.js";import{diag as I,recordPreviewError as B,recordPreviewJsonLine as x,writeStdout as q}from"../../io.js";import{ExitCode as b}from"../../../types.js";import{CrtrError as O}from"../../errors.js";const k=1e4,L=3e4,H=6e4,K=250,j=2e3,W=new Set(["ECONNREFUSED","ECONNRESET","EPIPE"]);class v extends Error{static{i(this,"ConnectionError")}detail;constructor(e){super(e),this.detail=e}}class N extends Error{static{i(this,"StreamIdleError")}}async function ot(t,e,o){const u=A(t,e,o,{get authorization(){const c=t.registration.authEnv;if(c===void 0||c==="")return null;const l=process.env[c];if(l===void 0||l==="")throw new O("auth_env_missing",`${S(t)}: environment variable ${c} is not set or empty`,b.USAGE,{field:c,received:c,next:`Export ${c} with the bearer token, then retry.`});return`Bearer ${l}`},requestId:U(),extraHeaders:{},fileMode:"read-local"});if(t.rest.streaming===!0){await J(t,u);return}const{status:m,body:s}=await Y(t,u);if(m>=200&&m<300)return F(t,s);M(t,m,s)}i(ot,"invokeHttpLeaf");async function Y(t,e){const o=t.timeouts?.requestMs??L,u=Date.now()+o;let m=K;for(;;)try{return await z(t,e,u-Date.now())}catch(s){if(!(s instanceof v))throw s;const c=u-Date.now(),l=y(t,e,`${s.detail}; retried with the same request id until the ${o}ms deadline`);if(c<=0||(await new Promise(n=>setTimeout(n,Math.min(m,c))),Date.now()>=u))throw l;m=Math.min(m*2,j)}}i(Y,"requestUnary");function z(t,e,o){const u=Math.min(t.timeouts?.connectMs??k,o),m=e.url.protocol==="https:"?C:R;return new Promise((s,c)=>{let l=!1,n=null,f=null;const $=i(()=>{n!==null&&clearTimeout(n),f!==null&&clearTimeout(f),n=null,f=null},"clearTimers"),E=i(r=>{l||(l=!0,$(),a.destroy(),c(r))},"fail"),h=i(r=>{l||(l=!0,$(),s(r))},"succeed"),a=m(e.url,{method:e.method},r=>{n!==null&&(clearTimeout(n),n=null);const T=[];r.on("data",w=>T.push(w)),r.on("end",()=>h({status:r.statusCode??0,body:Buffer.concat(T).toString("utf8")})),r.on("error",w=>E(y(t,e,`response interrupted (${_(w)})`))),r.on("close",()=>E(y(t,e,"response closed before the full body")))});for(const[r,T]of Object.entries(e.headers))a.setHeader(r,T);n=setTimeout(()=>E(y(t,e,`connection timed out after ${u}ms`)),u),f=setTimeout(()=>E(y(t,e,`request exceeded the ${o}ms timeout`)),o),a.on("socket",r=>{r.connecting?r.once("connect",()=>d()):d()});const d=i(()=>{n!==null&&(clearTimeout(n),n=null)},"clearConnectTimer");a.on("error",r=>E(G(t,e,r,"could not reach the backend"))),e.body!==void 0&&a.write(e.body),a.end()})}i(z,"requestUnaryOnce");function G(t,e,o,u){const m=_(o),s=`${u} (${m})`;return W.has(m)?new v(s):y(t,e,s)}i(G,"transportFailure");async function J(t,e){const o=t.timeouts?.connectMs??k,u=t.timeouts?.streamIdleMs??H,m=e.url.protocol==="https:"?C:R,s=await new Promise((h,a)=>{let d=!1,r=null;const T=i(()=>{r!==null&&(clearTimeout(r),r=null)},"clearConnect"),w=m(e.url,{method:e.method},g=>{d||(d=!0,T(),h(g))});for(const[g,D]of Object.entries(e.headers))w.setHeader(g,D);r=setTimeout(()=>{d||(d=!0,w.destroy(),a(y(t,e,`connection timed out after ${o}ms`)))},o),w.on("socket",g=>{g.connecting?g.once("connect",T):T()}),w.on("error",g=>{d||(d=!0,T(),a(y(t,e,`could not reach the backend (${_(g)})`)))}),e.body!==void 0&&w.write(e.body),w.end()}),c=s.statusCode??0;if(!(c>=200&&c<300)){const h=await Q(s);M(t,c,h)}let l=!1,n="",f=null;const $=i(()=>{f!==null&&clearTimeout(f),f=setTimeout(()=>s.destroy(new N),u)},"armIdle"),E=i(()=>{f!==null&&(clearTimeout(f),f=null)},"clearIdle");try{$();for await(const h of s){$(),n+=h.toString("utf8");let a;for(;(a=n.indexOf(`
-`))!==-1;){const d=n.slice(0,a);if(n=n.slice(a+1),d.trim()==="")continue;if(l=!0,x(d),!await q(d+`
-`)){E(),s.destroy();return}}}E(),n.trim()!==""&&(l=!0,x(n),await q(n));return}catch(h){E();const a=h instanceof N?`stream idle for ${u}ms`:`connection error (${_(h)})`;if(l){const d=`${S(t)}: stream interrupted (${a})`;I(`crtr: ${d}`),B({error:"stream_interrupted",message:d,next:"Retry the command to begin a fresh stream."}),process.exitCode=b.NETWORK;return}throw y(t,e,a)}}i(J,"requestStreaming");function y(t,e,o){return new O("cli_unreachable",`${S(t)}: ${o}`,b.NETWORK,{received:e.url.origin,next:`Check connectivity to ${e.url.host} and retry; run \`crtr pkg plugin update ${t.registration.name}\` if the command surface changed.`})}i(y,"unreachable");function S(t){return`HTTP-transport plugin "${t.registration.name}" command \`${t.commandPath.join(" ")}\``}i(S,"label");function _(t){const e=t;return e?.code??e?.message??String(t)}i(_,"errCode");function Q(t){return new Promise(e=>{const o=[];t.on("data",u=>o.push(u)),t.on("end",()=>e(Buffer.concat(o).toString("utf8"))),t.on("error",()=>e(Buffer.concat(o).toString("utf8")))})}i(Q,"readAll");export{ot as invokeHttpLeaf};
+var P=Object.defineProperty;var s=(e,t)=>P(e,"name",{value:t,configurable:!0});import{randomUUID as U}from"node:crypto";import{request as S}from"node:http";import{request as R}from"node:https";import{buildRequestPlan as A,mapUnary2xx as F,throwNon2xx as M}from"./http-plan.js";import{diag as I,recordPreviewError as L,recordPreviewJsonLine as O,writeStdout as x}from"../../io.js";import{ExitCode as _}from"../../../types.js";import{CrtrError as q}from"../../errors.js";const v=1e4,H=3e4,B=6e4,j=250,K=2e3,W=new Set(["ECONNREFUSED","ECONNRESET","EPIPE"]);class k extends Error{static{s(this,"ConnectionError")}detail;constructor(t){super(t),this.detail=t}}class N extends Error{static{s(this,"StreamIdleError")}}async function oe(e,t,i,a){const u=A(e,t,i,{get authorization(){const n=e.registration.authEnv;if(n===void 0||n==="")return null;const r=process.env[n];if(r===void 0||r==="")throw new q("auth_env_missing",`${C(e)}: environment variable ${n} is not set or empty`,_.USAGE,{field:n,received:n,next:`Export ${n} with the bearer token, then retry.`});return`Bearer ${r}`},requestId:U(),extraHeaders:{},fileMode:"read-local"});if(a?.callHeaders!==void 0)for(const[n,r]of Object.entries(await a.callHeaders(u))){const f=Object.keys(u.headers).find($=>$.toLowerCase()===n.toLowerCase());f!==void 0&&delete u.headers[f],u.headers[n]=r}if(e.rest.streaming===!0){await J(e,u);return}const{status:c,body:m}=await Y(e,u);if(c>=200&&c<300)return F(e,m);M(e,c,m)}s(oe,"invokeHttpLeaf");async function Y(e,t){const i=e.timeouts?.requestMs??H,a=Date.now()+i;let u=j;for(;;)try{return await z(e,t,a-Date.now())}catch(c){if(!(c instanceof k))throw c;const m=a-Date.now(),n=y(e,t,`${c.detail}; retried with the same request id until the ${i}ms deadline`);if(m<=0||(await new Promise(r=>setTimeout(r,Math.min(u,m))),Date.now()>=a))throw n;u=Math.min(u*2,K)}}s(Y,"requestUnary");function z(e,t,i){const a=Math.min(e.timeouts?.connectMs??v,i),u=t.url.protocol==="https:"?R:S;return new Promise((c,m)=>{let n=!1,r=null,f=null;const $=s(()=>{r!==null&&clearTimeout(r),f!==null&&clearTimeout(f),r=null,f=null},"clearTimers"),E=s(o=>{n||(n=!0,$(),d.destroy(),m(o))},"fail"),h=s(o=>{n||(n=!0,$(),c(o))},"succeed"),d=u(t.url,{method:t.method},o=>{r!==null&&(clearTimeout(r),r=null);const T=[];o.on("data",w=>T.push(w)),o.on("end",()=>h({status:o.statusCode??0,body:Buffer.concat(T).toString("utf8")})),o.on("error",w=>E(y(e,t,`response interrupted (${b(w)})`))),o.on("close",()=>E(y(e,t,"response closed before the full body")))});for(const[o,T]of Object.entries(t.headers))d.setHeader(o,T);r=setTimeout(()=>E(y(e,t,`connection timed out after ${a}ms`)),a),f=setTimeout(()=>E(y(e,t,`request exceeded the ${i}ms timeout`)),i),d.on("socket",o=>{o.connecting?o.once("connect",()=>l()):l()});const l=s(()=>{r!==null&&(clearTimeout(r),r=null)},"clearConnectTimer");d.on("error",o=>E(G(e,t,o,"could not reach the backend"))),t.body!==void 0&&d.write(t.body),d.end()})}s(z,"requestUnaryOnce");function G(e,t,i,a){const u=b(i),c=`${a} (${u})`;return W.has(u)?new k(c):y(e,t,c)}s(G,"transportFailure");async function J(e,t){const i=e.timeouts?.connectMs??v,a=e.timeouts?.streamIdleMs??B,u=t.url.protocol==="https:"?R:S,c=await new Promise((h,d)=>{let l=!1,o=null;const T=s(()=>{o!==null&&(clearTimeout(o),o=null)},"clearConnect"),w=u(t.url,{method:t.method},g=>{l||(l=!0,T(),h(g))});for(const[g,D]of Object.entries(t.headers))w.setHeader(g,D);o=setTimeout(()=>{l||(l=!0,w.destroy(),d(y(e,t,`connection timed out after ${i}ms`)))},i),w.on("socket",g=>{g.connecting?g.once("connect",T):T()}),w.on("error",g=>{l||(l=!0,T(),d(y(e,t,`could not reach the backend (${b(g)})`)))}),t.body!==void 0&&w.write(t.body),w.end()}),m=c.statusCode??0;if(!(m>=200&&m<300)){const h=await Q(c);M(e,m,h)}let n=!1,r="",f=null;const $=s(()=>{f!==null&&clearTimeout(f),f=setTimeout(()=>c.destroy(new N),a)},"armIdle"),E=s(()=>{f!==null&&(clearTimeout(f),f=null)},"clearIdle");try{$();for await(const h of c){$(),r+=h.toString("utf8");let d;for(;(d=r.indexOf(`
+`))!==-1;){const l=r.slice(0,d);if(r=r.slice(d+1),l.trim()==="")continue;if(n=!0,O(l),!await x(l+`
+`)){E(),c.destroy();return}}}E(),r.trim()!==""&&(n=!0,O(r),await x(r));return}catch(h){E();const d=h instanceof N?`stream idle for ${a}ms`:`connection error (${b(h)})`;if(n){const l=`${C(e)}: stream interrupted (${d})`;I(`crtr: ${l}`),L({error:"stream_interrupted",message:l,next:"Retry the command to begin a fresh stream."}),process.exitCode=_.NETWORK;return}throw y(e,t,d)}}s(J,"requestStreaming");function y(e,t,i){return new q("cli_unreachable",`${C(e)}: ${i}`,_.NETWORK,{received:t.url.origin,next:`Check connectivity to ${t.url.host} and retry; run \`crtr pkg plugin update ${e.registration.name}\` if the command surface changed.`})}s(y,"unreachable");function C(e){return`HTTP-transport plugin "${e.registration.name}" command \`${e.commandPath.join(" ")}\``}s(C,"label");function b(e){const t=e;return t?.code??t?.message??String(e)}s(b,"errCode");function Q(e){return new Promise(t=>{const i=[];e.on("data",a=>i.push(a)),e.on("end",()=>t(Buffer.concat(i).toString("utf8"))),e.on("error",()=>t(Buffer.concat(i).toString("utf8")))})}s(Q,"readAll");export{oe as invokeHttpLeaf};

package/dist/core/command-plugins/transport/http-plan.js

@@ -1 +1 @@
-var N=Object.defineProperty;var f=(e,t)=>N(e,"name",{value:t,configurable:!0});import{readFileSync as k,statSync as R}from"node:fs";import{resolve as j}from"node:path";import{validateDeclaredResult as C}from"../../../api/command-manifest/result.js";import{CrtrError as g}from"../../errors.js";import{envelopeClaimsStale as z,staleErrorDetails as U}from"../../manifest-stale.js";import{ExitCode as h}from"../../../types.js";import{isRecord as x}from"../../../shared/predicates.js";const P=/^[a-z][a-z0-9]*(_[a-z0-9]+)*$/,q=new Set(["internal","unknown_path","command_collision","cli_protocol_error"]),T=new Set(["authorization","crtr-request-id","crtr-run-id","crtr-approval","crtr-upload-id","crtr-upload-link","accept","content-type"]);function Y(e,t,n,r){const i=new Map;for(const o of e.params)i.set(o.name,o);const c=Object.entries(e.rest.params),u=e.baseUrl??new URL(e.registration.endpoint).origin;let y=e.rest.path;for(const[o,a]of c){if(a.in!=="path")continue;const s=t[w(o)];y=y.split(`{${o}}`).join(M(s))}const b=new URL(y,u);for(const[o,a]of c){if(a.in!=="query")continue;const s=w(o);$(i.get(o),s,t,n)&&b.searchParams.append(a.as??o,String(t[s]))}const m=G(e,c,i,t,n,r.fileMode),p=Object.keys(m).length>0?JSON.stringify(m):void 0,l={},d=f((o,a)=>{const s=Object.keys(l).find(S=>S.toLowerCase()===o.toLowerCase());s!==void 0&&delete l[s],l[o]=a},"setHeader");d("Accept","application/json"),d("Crtr-Request-Id",r.requestId),r.authorization!==null&&d("Authorization",r.authorization);for(const[o,a]of c){if(a.in!=="header")continue;const s=w(o);if(!$(i.get(o),s,t,n))continue;const S=a.as;if(r.fileMode==="pass-through"&&T.has(S.toLowerCase()))throw new g("invalid_type",`${v(e)}: header "${S}" is reserved for the runtime`,h.USAGE,{field:o,next:"Remove the runtime-owned header mapping from the manifest."});const _=String(t[s]);if(/[\r\n]/.test(_))throw new g("invalid_type",`${v(e)}: header "${S}" value must not contain a newline`,h.USAGE,{field:o,received:"(newline in header value)",next:"Remove newline characters from the value."});d(S,_)}p!==void 0&&d("Content-Type","application/json");for(const[o,a]of Object.entries(r.extraHeaders)){if(r.fileMode==="pass-through"&&/[\r\n]/.test(a))throw new g("invalid_type",`${v(e)}: header "${o}" value must not contain a newline`,h.USAGE);d(o,a)}if(r.fileMode==="pass-through"){if(d("Accept","application/json"),p!==void 0)d("Content-Type","application/json");else{const o=Object.keys(l).find(a=>a.toLowerCase()==="content-type");o!==void 0&&delete l[o]}if(d("Crtr-Request-Id",r.requestId),r.authorization!==null)d("Authorization",r.authorization);else{const o=Object.keys(l).find(a=>a.toLowerCase()==="authorization");o!==void 0&&delete l[o]}}return{url:b,method:e.rest.method,headers:l,...p!==void 0?{body:p}:{}}}f(Y,"buildRequestPlan");function G(e,t,n,r,i,c){const u=new Map;for(const[m,p]of t){if(p.in!=="body")continue;const l=p.as??m,d=u.get(l);d!==void 0?d.push(m):u.set(l,[m])}const y={};for(const[m,p]of u){const l=p.map(s=>({name:s,param:n.get(s)})),d=l.find(s=>s.param.kind!=="stdin"),o=l.find(s=>s.param.kind==="stdin");let a;d!==void 0&&$(d.param,w(d.name),r,i)?a={param:d.param,value:r[w(d.name)]}:o!==void 0&&$(o.param,w(o.name),r,i)&&(a={param:o.param,value:r[w(o.name)]}),a!==void 0&&(y[m]=I(e,a.param,a.value,c))}const b={...e.rest.body};return e.rest.bodyRoot!==void 0?b[e.rest.bodyRoot]=y:Object.assign(b,y),b}f(G,"assembleBody");function I(e,t,n,r){return r==="pass-through"||t.kind==="context-file"?n:(t.kind==="positional"||t.kind==="flag")&&t.type==="path"?A(v(e),t,n):n}f(I,"materializeBodyValue");function A(e,t,n){if(Array.isArray(n))return n.map(u=>A(e,t,u));const r=String(n),i=j(process.cwd(),r);let c;try{c=R(i)}catch{throw O(e,t.name,r,"no file exists at that path","an existing local file path")}if(!c.isFile())throw O(e,t.name,r,"the path is not a regular file","a regular local file (not a directory, socket, or device)");try{return"encoding"in t&&t.encoding==="base64"?k(i).toString("base64"):k(i,"utf8")}catch{throw O(e,t.name,r,"the file could not be read","a readable local file path")}}f(A,"readPathParam");function O(e,t,n,r,i){return new g("invalid_type",`${e}: cannot read file for "${t}" \u2014 ${r}: ${n}`,h.USAGE,{field:t,received:n,next:`Pass ${i}, relative to the current directory or absolute.`})}f(O,"fileError");function $(e,t,n,r){return r!==void 0?r.providedParams.has(t):Object.prototype.hasOwnProperty.call(n,t)&&n[t]!==void 0}f($,"isPresent");function M(e){const t=String(e);return t==="."||t===".."?t.replace(/\./g,"%2E"):encodeURIComponent(t)}f(M,"encodePathSegmentValue");function w(e){return e.replace(/-([a-z])/g,(t,n)=>n.toUpperCase())}f(w,"paramKey");function Z(e,t){let n;try{n=JSON.parse(t)}catch{throw E(e,"response body was not valid JSON","a JSON object matching the declared output")}if(!x(n))throw E(e,`response body was not a JSON object (got ${H(n)})`,"a JSON object matching the declared output");const r=C(e.output,n);if(r!==null){const c=e.output.find(u=>u.name===r.field)?.type??"unknown";throw r.receivedType!==void 0?E(e,`output field "${r.field}" has the wrong type`,`${r.field}: ${c}`):E(e,`response is missing required output field "${r.field}"`,`a "${r.field}" field of type ${c}`)}return n}f(Z,"mapUnary2xx");function ee(e,t,n){const r=J(t),i=D(n);if(i!==null){const c=P.test(i.code)&&!q.has(i.code);throw new g(c?i.code:"cli_protocol_error",i.message,r,{...i.received!==void 0?{received:i.received}:{},...i.field!==void 0?{field:i.field}:{},...i.manifestStale?U(e.registration.name):{},http_status:t,next:i.next??"Inspect the backend response, then retry if appropriate."})}throw new g("cli_http_error",`${v(e)}: request failed with HTTP ${t}`,r,{http_status:t,next:"Inspect the backend response, then retry if appropriate."})}f(ee,"throwNon2xx");function D(e){let t;try{t=JSON.parse(e)}catch{return null}if(!x(t)||!x(t.error))return null;const n=t.error;return typeof n.code!="string"||typeof n.message!="string"?null:{code:n.code,message:n.message,...typeof n.field=="string"?{field:n.field}:{},...n.received!==void 0?{received:n.received}:{},...typeof n.next=="string"?{next:n.next}:{},manifestStale:z(n),...n.question!==void 0?{question:n.question}:{}}}f(D,"parseHttpError");function J(e){return e===400||e===401||e===403||e===422?h.USAGE:e===404?h.NOT_FOUND:e===409?h.AMBIGUOUS:h.GENERAL}f(J,"deriveExit");function E(e,t,n){return new g("cli_protocol_error",`${v(e)}: ${t}. Expected ${n}.`,h.GENERAL,{received:t,next:`Run \`crtr pkg plugin update ${e.registration.name}\` or inspect the backend response.`})}f(E,"protocolError");function v(e){return`HTTP-transport plugin "${e.registration.name}" command \`${e.commandPath.join(" ")}\``}f(v,"label");function H(e){return e===null?"null":Array.isArray(e)?"array":typeof e}f(H,"typeName");export{Y as buildRequestPlan,Z as mapUnary2xx,D as parseHttpError,A as readPathParam,ee as throwNon2xx};
+var R=Object.defineProperty;var f=(e,t)=>R(e,"name",{value:t,configurable:!0});import{readFileSync as O,statSync as k}from"node:fs";import{resolve as j}from"node:path";import{validateDeclaredResult as C}from"../../../api/command-manifest/result.js";import{CrtrError as w}from"../../errors.js";import{envelopeClaimsStale as P,staleErrorDetails as z}from"../../manifest-stale.js";import{ExitCode as h}from"../../../types.js";import{isRecord as x}from"../../../shared/predicates.js";import{trimHeaderValue as U}from"./sign.js";const q=/^[a-z][a-z0-9]*(_[a-z0-9]+)*$/,T=new Set(["internal","unknown_path","command_collision","cli_protocol_error"]),D=new Set(["authorization","crtr-request-id","crtr-run-id","crtr-approval","crtr-upload-id","crtr-upload-link","accept","content-type","crtr-caller","crtr-signature"]),M=new Set(["crtr-caller","crtr-signature","crtr-request-id"]);function te(e,t,n,r){const i=new Map;for(const o of e.params)i.set(o.name,o);const c=Object.entries(e.rest.params),u=e.baseUrl??new URL(e.registration.endpoint).origin;let y=e.rest.path;for(const[o,a]of c){if(a.in!=="path")continue;const d=t[S(o)];y=y.split(`{${o}}`).join(I(d))}const b=new URL(y,u);for(const[o,a]of c){if(a.in!=="query")continue;const d=S(o);v(i.get(o),d,t,n)&&b.searchParams.append(a.as??o,String(t[d]))}const m=G(e,c,i,t,n,r.fileMode),p=Object.keys(m).length>0?JSON.stringify(m):void 0,l={},s=f((o,a)=>{const d=Object.keys(l).find(g=>g.toLowerCase()===o.toLowerCase());d!==void 0&&delete l[d],l[o]=U(a)},"setHeader");s("Accept","application/json"),s("Crtr-Request-Id",r.requestId),r.authorization!==null&&s("Authorization",r.authorization);for(const[o,a]of c){if(a.in!=="header")continue;const d=S(o);if(!v(i.get(o),d,t,n))continue;const g=a.as;if(M.has(g.toLowerCase())||r.fileMode==="pass-through"&&D.has(g.toLowerCase()))throw new w("invalid_type",`${E(e)}: header "${g}" is reserved for the runtime`,h.USAGE,{field:o,next:"Remove the runtime-owned header mapping from the manifest."});const A=String(t[d]);if(/[\r\n]/.test(A))throw new w("invalid_type",`${E(e)}: header "${g}" value must not contain a newline`,h.USAGE,{field:o,received:"(newline in header value)",next:"Remove newline characters from the value."});s(g,A)}p!==void 0&&s("Content-Type","application/json");for(const[o,a]of Object.entries(r.extraHeaders)){if(r.fileMode==="pass-through"&&/[\r\n]/.test(a))throw new w("invalid_type",`${E(e)}: header "${o}" value must not contain a newline`,h.USAGE);s(o,a)}if(r.fileMode==="pass-through"){if(s("Accept","application/json"),p!==void 0)s("Content-Type","application/json");else{const o=Object.keys(l).find(a=>a.toLowerCase()==="content-type");o!==void 0&&delete l[o]}if(s("Crtr-Request-Id",r.requestId),r.authorization!==null)s("Authorization",r.authorization);else{const o=Object.keys(l).find(a=>a.toLowerCase()==="authorization");o!==void 0&&delete l[o]}}return{url:b,method:e.rest.method,headers:l,...p!==void 0?{body:p}:{}}}f(te,"buildRequestPlan");function G(e,t,n,r,i,c){const u=new Map;for(const[m,p]of t){if(p.in!=="body")continue;const l=p.as??m,s=u.get(l);s!==void 0?s.push(m):u.set(l,[m])}const y={};for(const[m,p]of u){const l=p.map(d=>({name:d,param:n.get(d)})),s=l.find(d=>d.param.kind!=="stdin"),o=l.find(d=>d.param.kind==="stdin");let a;s!==void 0&&v(s.param,S(s.name),r,i)?a={param:s.param,value:r[S(s.name)]}:o!==void 0&&v(o.param,S(o.name),r,i)&&(a={param:o.param,value:r[S(o.name)]}),a!==void 0&&(y[m]=H(e,a.param,a.value,c))}const b={...e.rest.body};return e.rest.bodyRoot!==void 0?b[e.rest.bodyRoot]=y:Object.assign(b,y),b}f(G,"assembleBody");function H(e,t,n,r){return r==="pass-through"||t.kind==="context-file"?n:(t.kind==="positional"||t.kind==="flag")&&t.type==="path"?N(E(e),t,n):n}f(H,"materializeBodyValue");function N(e,t,n){if(Array.isArray(n))return n.map(u=>N(e,t,u));const r=String(n),i=j(process.cwd(),r);let c;try{c=k(i)}catch{throw _(e,t.name,r,"no file exists at that path","an existing local file path")}if(!c.isFile())throw _(e,t.name,r,"the path is not a regular file","a regular local file (not a directory, socket, or device)");try{return"encoding"in t&&t.encoding==="base64"?O(i).toString("base64"):O(i,"utf8")}catch{throw _(e,t.name,r,"the file could not be read","a readable local file path")}}f(N,"readPathParam");function _(e,t,n,r,i){return new w("invalid_type",`${e}: cannot read file for "${t}" \u2014 ${r}: ${n}`,h.USAGE,{field:t,received:n,next:`Pass ${i}, relative to the current directory or absolute.`})}f(_,"fileError");function v(e,t,n,r){return r!==void 0?r.providedParams.has(t):Object.prototype.hasOwnProperty.call(n,t)&&n[t]!==void 0}f(v,"isPresent");function I(e){const t=String(e);return t==="."||t===".."?t.replace(/\./g,"%2E"):encodeURIComponent(t)}f(I,"encodePathSegmentValue");function S(e){return e.replace(/-([a-z])/g,(t,n)=>n.toUpperCase())}f(S,"paramKey");function ne(e,t){let n;try{n=JSON.parse(t)}catch{throw $(e,"response body was not valid JSON","a JSON object matching the declared output")}if(!x(n))throw $(e,`response body was not a JSON object (got ${V(n)})`,"a JSON object matching the declared output");const r=C(e.output,n);if(r!==null){const c=e.output.find(u=>u.name===r.field)?.type??"unknown";throw r.receivedType!==void 0?$(e,`output field "${r.field}" has the wrong type`,`${r.field}: ${c}`):$(e,`response is missing required output field "${r.field}"`,`a "${r.field}" field of type ${c}`)}return n}f(ne,"mapUnary2xx");function re(e,t,n){const r=L(t),i=J(n);if(i!==null){const c=q.test(i.code)&&!T.has(i.code);throw new w(c?i.code:"cli_protocol_error",i.message,r,{...i.received!==void 0?{received:i.received}:{},...i.field!==void 0?{field:i.field}:{},...i.manifestStale?z(e.registration.name):{},http_status:t,next:i.next??"Inspect the backend response, then retry if appropriate."})}throw new w("cli_http_error",`${E(e)}: request failed with HTTP ${t}`,r,{http_status:t,next:"Inspect the backend response, then retry if appropriate."})}f(re,"throwNon2xx");function J(e){let t;try{t=JSON.parse(e)}catch{return null}if(!x(t)||!x(t.error))return null;const n=t.error;return typeof n.code!="string"||typeof n.message!="string"?null:{code:n.code,message:n.message,...typeof n.field=="string"?{field:n.field}:{},...n.received!==void 0?{received:n.received}:{},...typeof n.next=="string"?{next:n.next}:{},manifestStale:P(n),...n.question!==void 0?{question:n.question}:{}}}f(J,"parseHttpError");function L(e){return e===400||e===401||e===403||e===422?h.USAGE:e===404?h.NOT_FOUND:e===409?h.AMBIGUOUS:h.GENERAL}f(L,"deriveExit");function $(e,t,n){return new w("cli_protocol_error",`${E(e)}: ${t}. Expected ${n}.`,h.GENERAL,{received:t,next:`Run \`crtr pkg plugin update ${e.registration.name}\` or inspect the backend response.`})}f($,"protocolError");function E(e){return`HTTP-transport plugin "${e.registration.name}" command \`${e.commandPath.join(" ")}\``}f(E,"label");function V(e){return e===null?"null":Array.isArray(e)?"array":typeof e}f(V,"typeName");export{te as buildRequestPlan,ne as mapUnary2xx,J as parseHttpError,N as readPathParam,re as throwNon2xx};

package/dist/core/command-plugins/transport/sign.d.ts

@@ -0,0 +1,55 @@
+/** Skew the verifier tolerates between the signature's `t` and its own clock. */
+export declare const SIGNATURE_MAX_SKEW_SECONDS = 300;
+/** How long a verifier must remember a `Crtr-Request-Id`. */
+export declare const SIGNATURE_NONCE_TTL_SECONDS = 600;
+/** A header value without its leading and trailing optional whitespace (spaces and tabs): the form every HTTP receiver
+ *  sees, since parsers drop it. Signing and sending both use this form, so the plugin hashes what crtr signed. */
+export declare function trimHeaderValue(value: string): string;
+export interface SignedHeaderDigest {
+    /** Lowercase names of every signed header, sorted. */
+    header_names: string[];
+    /** Lowercase hex sha256 of `<name>:<value>\n` for each name in `header_names`. */
+    headers_sha256: string;
+}
+export interface CrtrSignatureInput extends SignedHeaderDigest {
+    token: string;
+    method: string;
+    /** The request URL, or its path-with-query. */
+    url: URL | string;
+    /** Lowercase hex sha256 of the exact body bytes sent (of "" when none). */
+    body_sha256: string;
+    /** The `Crtr-Caller` value, or '' when none is sent. */
+    caller: string;
+    /** Epoch milliseconds. */
+    now: number;
+}
+export interface VerifyCrtrSignatureInput {
+    token: string;
+    /** The received `Crtr-Signature` header value. */
+    header: string;
+    method: string;
+    /** The received request target (`/path?query`) or absolute URL. */
+    url: URL | string;
+    /** The exact body bytes received; undefined or empty when none. */
+    body: Uint8Array | string | undefined;
+    /** The received `Crtr-Caller` value, or ''. */
+    caller: string;
+    /** Request headers as received (names in any case). */
+    headers: Record<string, string | string[] | undefined>;
+    /** Epoch milliseconds. */
+    now: number;
+    /** Reports whether the nonce was already seen, and records it. */
+    seen: (requestId: string) => boolean;
+}
+export declare function sha256Hex(data: Uint8Array | string | undefined): string;
+/** Names and digest of the headers a signature covers: every header except
+ *  `Crtr-Caller` and `Crtr-Signature`. Each value is hashed without its leading and trailing spaces and tabs, the form a
+ *  receiver gets after its HTTP parser trims them (the request plan sends the same trimmed value). */
+export declare function signedHeaderDigest(headers: Record<string, string>): SignedHeaderDigest;
+/** The `Crtr-Signature` header value. Refuses a header list that is not sorted
+ *  lowercase names including `crtr-request-id`, so a signature always covers the nonce. */
+export declare function crtrSignature(input: CrtrSignatureInput): string;
+/** Reference verifier for a plugin's service. True only when the version, clock
+ *  window, signed header list, MAC and nonce all hold. The nonce is recorded
+ *  only after the MAC verifies, so a forged request cannot poison the cache. */
+export declare function verifyCrtrSignature(input: VerifyCrtrSignatureInput): boolean;

package/dist/core/command-plugins/transport/sign.js

@@ -0,0 +1,3 @@
+var N=Object.defineProperty;var c=(e,t)=>N(e,"name",{value:t,configurable:!0});import{createHash as _,createHmac as E,timingSafeEqual as y}from"node:crypto";const C=300,D=600,d=new Set(["crtr-caller","crtr-signature"]),f="crtr-request-id";function v(e){return e.replace(/^[ \t]+|[ \t]+$/g,"")}c(v,"trimHeaderValue");function $(e){return _("sha256").update(e??"").digest("hex")}c($,"sha256Hex");function w(e,t){const s=_("sha256");for(const r of e)s.update(`${r}:${t(r)}
+`);return s.digest("hex")}c(w,"headersDigest");function H(e){const t=new Map;for(const[r,i]of Object.entries(e)){const a=r.toLowerCase();d.has(a)||t.set(a,v(i))}const s=[...t.keys()].sort();return{header_names:s,headers_sha256:w(s,r=>t.get(r))}}c(H,"signedHeaderDigest");function S(e){if(typeof e!="string")return e.pathname+e.search;if(e.startsWith("/"))return e;const t=new URL(e);return t.pathname+t.search}c(S,"target");function b(e){return["v1",String(e.t),e.method.toUpperCase(),e.target,e.body_sha256,e.caller,e.h,e.headers_sha256].join(`
+`)}c(b,"canonical");function x(e,t){return E("sha256",e).update(t).digest()}c(x,"mac");function L(e){const t=e.header_names;if(!t.includes(f))throw new Error("signed headers must include crtr-request-id");for(let a=0;a<t.length;a++){const o=t[a];if(o!==o.toLowerCase()||/[;,\s]/.test(o)||d.has(o)||a>0&&t[a-1]>=o)throw new Error("signed header names must be unique, sorted, lowercase, and exclude crtr-caller and crtr-signature")}const s=Math.floor(e.now/1e3),r=t.join(";"),i=x(e.token,b({t:s,method:e.method,target:S(e.url),body_sha256:e.body_sha256,caller:e.caller,h:r,headers_sha256:e.headers_sha256})).toString("base64url");return`v1,t=${s},h=${r},sig=${i}`}c(L,"crtrSignature");function M(e){const t=e.header.split(",");if(t.length!==4||t[0]!=="v1")return!1;const[s,r,i]=[t[1],t[2],t[3]].map((n,h)=>{const m=["t=","h=","sig="][h];return n.startsWith(m)?n.slice(m.length):null});if(s===null||r===null||i===null||!/^\d{1,12}$/.test(s))return!1;const a=Number(s);if(Math.abs(e.now/1e3-a)>C)return!1;const o=r.split(";");if(!o.includes(f))return!1;const l=new Map;for(const[n,h]of Object.entries(e.headers))typeof h=="string"&&l.set(n.toLowerCase(),h);for(let n=0;n<o.length;n++){const h=o[n];if(h===""||d.has(h)||!l.has(h)||n>0&&o[n-1]>=h)return!1}const u=x(e.token,b({t:a,method:e.method,target:S(e.url),body_sha256:$(e.body),caller:e.caller,h:r,headers_sha256:w(o,n=>l.get(n))})),g=Buffer.from(i,"base64url");return g.length!==u.length||!y(g,u)?!1:!e.seen(l.get(f))}c(M,"verifyCrtrSignature");export{C as SIGNATURE_MAX_SKEW_SECONDS,D as SIGNATURE_NONCE_TTL_SECONDS,L as crtrSignature,$ as sha256Hex,H as signedHeaderDigest,v as trimHeaderValue,M as verifyCrtrSignature};

package/dist/core/graph/access.d.ts

@@ -17,6 +17,25 @@ export declare function toolApps(db: DatabaseSync, reader: Reader): ObjectRow[];
 export declare function mayUseTools(_db: DatabaseSync, _reader: Reader, app: ObjectRow): boolean;
 /** Whether this reader may register, publish or watch as an object owned by `owner`. */
 export declare function mayActAs(db: DatabaseSync, reader: Reader, owner: ObjectRow): boolean;
+/** Run confinement for a node acting on a custom object of its app (Silas, 2026-09-30):
+ *  a node reaches an object registered in its own run, or when neither run is isolated.
+ *  An object the person or the app's server registered is reached by nodes outside
+ *  isolation only. Any other reader is unchanged. */
+export declare function customReachable(db: DatabaseSync, reader: Reader, object: ObjectRow): boolean;
+/** The `crtr:objects:*` targets an object belongs to, from its owner chain (rulings R5):
+ *  person space → `user`; under an app's profile → `profile:<id>`; a node of an app or a custom
+ *  object → `app:<x>`; any node (local, or a stub of one of the account's nodes) → `node`.
+ *  App documents and the profile itself stay under the memory scopes; a repo has no target.
+ *  The app's own `app:<x>` is left out: its own objects need no scope. */
+export declare function objectsTargets(db: DatabaseSync, object: ObjectRow, appGrantee: string): string[];
+/** Whether a non-person reader's scopes hold `crtr:objects:<verb>:<t>` for a target t of `object`.
+ *  False for a person and for a revoked grant (`scopes === null`). `covers` is exact equality here. */
+export declare function holdsObjectsScope(db: DatabaseSync, reader: Reader, verb: 'read' | 'watch' | 'link' | 'write', object: ObjectRow): boolean;
+/** Whether the watch `watcher` → `object` that `app` made through `link` still authorizes delivering `object`'s events to `watcher` past the
+ *  watcher's read gate: `app` owns `object` (directly, or through its profile: `mayActAs`) and, when its `scopes` are known, they hold
+ *  `crtr:objects:link:<t>` for the watcher. Null `scopes` (a stub of a remote object: the home already checked the link) skip the scope. It grants
+ *  delivery of this one object's events only; nothing about reading it. */
+export declare function linkAuthorizes(db: DatabaseSync, app: ObjectRow, scopes: readonly string[] | null, object: ObjectRow, watcher: ObjectRow): boolean;
 /** Callers turn `false` into `not_found`. A person reader reads everything. An app's
  *  shipped documents are read by any run that may use that app's tools. */
 export declare function canRead(db: DatabaseSync, reader: Reader, object: ObjectRow): boolean;

package/dist/core/graph/access.js

@@ -1,8 +1,8 @@
-var f=Object.defineProperty;var r=(n,t)=>f(n,"name",{value:t,configurable:!0});import{prepared as s}from"../sqlite-statements.js";import{missingOwnMemoryScope as a}from"./spaces/own-memory.js";import{SPACES as h}from"./spaces/index.js";import{insideRepo as d}from"./spaces/repo.js";function E(n,t){return s(n,`WITH RECURSIVE chain(rowid, depth) AS (
+var O=Object.defineProperty;var s=(e,t)=>O(e,"name",{value:t,configurable:!0});import{prepared as a}from"../sqlite-statements.js";import{covers as R}from"@north-light/identity";import{objectPlace as N,runPlace as L,runsSeeEachOther as g}from"../runs/confinement.js";import{missingOwnMemoryScope as E}from"./spaces/own-memory.js";import{SPACES as x,identityOf as f}from"./spaces/index.js";import{insideRepo as C}from"./spaces/repo.js";function T(e,t){return a(e,`WITH RECURSIVE chain(rowid, depth) AS (
       SELECT owner, 1 FROM objects WHERE rowid = ? AND owner IS NOT NULL
       UNION ALL
       SELECT o.owner, c.depth + 1 FROM objects o JOIN chain c ON o.rowid = c.rowid WHERE o.owner IS NOT NULL
-    ) SELECT o.* FROM chain c CROSS JOIN objects o WHERE o.rowid = c.rowid ORDER BY c.depth`).all(t.rowid)}r(E,"ownerChain");function y(n,t){return c(n,t).space}r(y,"spaceOf");function c(n,t){const o=E(n,t),p=o.length?o[o.length-1]:t,e=h[p.type];if(!e)throw new Error(`${t.type} ${t.id} has no space: its owner chain ends at ${p.type} ${p.id}`);const i=o.length?[...o.slice(0,-1).reverse(),t]:[];return{space:p,path:i,impl:e}}r(c,"locate");function u(n,t){return t.type!=="document"?!1:s(n,"SELECT source_path FROM documents WHERE object = ?").get(t.rowid)?.source_path!=null}r(u,"isShipped");function L(n,t){return s(n,`SELECT a.* FROM objects a WHERE a.type = 'app' AND a.deleted_at IS NULL AND EXISTS (
+    ) SELECT o.* FROM chain c CROSS JOIN objects o WHERE o.rowid = c.rowid ORDER BY c.depth`).all(t.rowid)}s(T,"ownerChain");function v(e,t){return c(e,t).space}s(v,"spaceOf");function c(e,t){const n=T(e,t),p=n.length?n[n.length-1]:t,o=x[p.type];if(!o)throw new Error(`${t.type} ${t.id} has no space: its owner chain ends at ${p.type} ${p.id}`);const r=n.length?[...n.slice(0,-1).reverse(),t]:[];return{space:p,path:r,impl:o}}s(c,"locate");function m(e,t){return t.type!=="document"?!1:a(e,"SELECT source_path FROM documents WHERE object = ?").get(t.rowid)?.source_path!=null}s(m,"isShipped");function J(e,t){return a(e,`SELECT a.* FROM objects a WHERE a.type = 'app' AND a.deleted_at IS NULL AND EXISTS (
       SELECT 1 FROM objects o JOIN documents d ON d.object = o.rowid
       WHERE o.owner = a.rowid AND o.type = 'document' AND o.deleted_at IS NULL AND d.source_path IS NOT NULL)
-    ORDER BY a.name = 'crtr', a.name`).all().filter(p=>l(n,t,p))}r(L,"toolApps");function l(n,t,o){return o.type==="app"}r(l,"mayUseTools");function C(n,t,o){return t.class==="person"?!0:t.class==="object"?t.owner.rowid===o.rowid:t.class==="app"?t.app.rowid===o.rowid||o.type==="profile"&&o.owner===t.app.rowid:t.app.rowid===o.rowid||o.type==="profile"&&t.profile?.rowid===o.rowid||o.type==="repo"&&d(n,t,o,"rw")}r(C,"mayActAs");function A(n,t,o){return w(n,o)(t)}r(A,"canRead");function w(n,t){let o=null,p=null;return e=>e.class==="person"||(o??=c(n,t),o.space.type==="app"&&o.path.length>0&&(p??=u(n,t),p&&l(n,e,o.space)))?!0:o.impl.canRead(n,e,o.space,o.path,t)}r(w,"readCheck");function I(n,t,o){if(u(n,o))return!1;const{space:p,path:e,impl:i}=c(n,o);return i.canChange(n,t,p,e,o)}r(I,"canChange");function T(n,t,o,p){if(t.class==="person")return null;const{space:e,path:i}=c(n,o);return e.type==="app"&&t.app.rowid===e.rowid?a(n,t,e,i,o,p):null}r(T,"missingMemoryScope");function g(n,t,o,p){if(t.class==="person")return null;const e=c(n,o),{space:i}=e;return i.type!=="app"||t.app.rowid!==i.rowid?null:a(n,t,i,e.path.length===0?[o]:[...e.path],null,p)}r(g,"missingMemoryScopeUnder");export{I as canChange,A as canRead,u as isShipped,C as mayActAs,l as mayUseTools,T as missingMemoryScope,g as missingMemoryScopeUnder,E as ownerChain,w as readCheck,y as spaceOf,L as toolApps};
+    ORDER BY a.name = 'crtr', a.name`).all().filter(p=>h(e,t,p))}s(J,"toolApps");function h(e,t,n){return n.type==="app"}s(h,"mayUseTools");function A(e,t,n){return t.class==="person"?!0:t.class==="object"?t.owner.rowid===n.rowid:t.class==="app"?t.app.rowid===n.rowid||n.type==="profile"&&n.owner===t.app.rowid:t.app.rowid===n.rowid||n.type==="profile"&&t.profile?.rowid===n.rowid||n.type==="repo"&&C(e,t,n,"rw")}s(A,"mayActAs");function I(e,t,n){if(t.class!=="node"&&!(t.class==="app"&&t.place!==void 0))return!0;const p=t.class==="app"?t.place:L(t.node.id,e);if(p===null)return!0;const o=N(n.rowid,e);return o===null?!p.isolated:g(p,o)}s(I,"customReachable");const w=s(e=>e.type.includes("."),"isCustom");function P(e,t,n){return y(e,c(e,t),t,n)}s(P,"objectsTargets");function y(e,{space:t,path:n},p,o){const r=[];if(t.type==="person")r.push("user");else if(t.type==="app"&&n.length>0){const i=n[0];if(i.type==="profile")n.length>1&&r.push(`profile:${f(e,i).external_id}`);else if(i.type==="node"||w(i)){const u=f(e,t).external_id;u!==o&&r.push(u)}}return p.type==="node"&&r.push("node"),r}s(y,"targetsOf");function l(e,t,n,p,o){if(t.class==="person"||t.scopes===null)return!1;const r=t.scopes;if(r.length===0||p.space.type==="app"&&t.app.rowid===p.space.rowid)return!1;const i=f(e,t.app).external_id;return y(e,p,o,i).some(u=>{const S=`crtr:objects:${n}:${u}`;return r.some(d=>R(d,S))})}s(l,"holdsInLocated");function M(e,t,n,p){return t.class==="person"||t.scopes===null?!1:l(e,t,n,c(e,p),p)}s(M,"holdsObjectsScope");function B(e,t,n,p,o){const r=p.owner===null?null:e.prepare("SELECT * FROM objects WHERE rowid = ?").get(p.owner)??null;if(r===null)return!1;const i={class:"app",app:t,scopes:n??[]};return A(e,i,r)?n===null||M(e,i,"link",o):!1}s(B,"linkAuthorizes");function Y(e,t,n){return _(e,n)(t)}s(Y,"canRead");function _(e,t){let n=null,p=null;return o=>{if(o.class==="person")return!0;if(n??=c(e,t),n.space.type==="app"&&n.path.length>0){if(p??=m(e,t),p&&h(e,o,n.space))return!0;if(w(t)){if(o.app.rowid===n.space.rowid&&!I(e,o,t))return!1;if(t.privacy==="public"&&o.app.rowid!==n.space.rowid&&o.scopes!==null&&h(e,o,n.space))return!0}}return l(e,o,"read",n,t)||o.class==="object"&&w(o.object)&&l(e,o,"watch",n,t)?!0:n.impl.canRead(e,o,n.space,n.path,t)}}s(_,"readCheck");function z(e,t,n){if(m(e,n))return!1;const p=c(e,n);if(l(e,t,"write",p,n))return!0;const{space:o,path:r,impl:i}=p;return i.canChange(e,t,o,r,n)}s(z,"canChange");function V(e,t,n,p){if(t.class==="person")return null;const{space:o,path:r}=c(e,n);return o.type==="app"&&t.app.rowid===o.rowid?E(e,t,o,r,n,p):null}s(V,"missingMemoryScope");function X(e,t,n,p){if(t.class==="person")return null;const o=c(e,n),{space:r}=o;return r.type!=="app"||t.app.rowid!==r.rowid?null:E(e,t,r,o.path.length===0?[n]:[...o.path],null,p)}s(X,"missingMemoryScopeUnder");export{z as canChange,Y as canRead,I as customReachable,M as holdsObjectsScope,m as isShipped,B as linkAuthorizes,A as mayActAs,h as mayUseTools,V as missingMemoryScope,X as missingMemoryScopeUnder,P as objectsTargets,T as ownerChain,_ as readCheck,v as spaceOf,J as toolApps};

package/dist/core/graph/custom.d.ts

@@ -1,8 +1,8 @@
 import type { DatabaseSync } from 'node:sqlite';
-import type { Level, ObjectRow, Reader } from './types.js';
-import { mayActAs } from './access.js';
+import type { Level, ObjectRow, Privacy, Reader } from './types.js';
+import { customReachable, mayActAs } from './access.js';
 import { onQueueSignal } from './receivers.js';
-export { mayActAs, onQueueSignal };
+export { customReachable, mayActAs, onQueueSignal };
 export type CustomReceiver = 'queue' | {
     url: string;
 } | {
@@ -39,15 +39,40 @@ export declare function registerCustomObject(db: DatabaseSync, reader: Reader, i
     name: string;
     owner: ObjectRow;
     description: string;
-    events: CustomEvents;
+    /** Omitted: create or return only the instance of a kind an installed plugin (or a peer) declares; the catalog is untouched. */
+    events?: CustomEvents;
     receiver?: CustomReceiver | null;
     rotateToken?: boolean;
+    privacy?: Privacy;
 }): {
     object: ObjectRow;
     token?: string;
     created: boolean;
     changed: string[];
 };
+export type KindSource = 'register' | 'manifest' | 'peer';
+export type KindChange = 'events' | 'description' | 'read';
+/**
+ * The only writer of `object_kinds`. `source` says who is writing: an app's `register` call, an installed plugin's
+ * manifest, or a declaration that crossed from another machine (`peer`). Precedence: `manifest` and `register` rows
+ * are never overwritten by `peer`; a `manifest` write takes over a row it already owns and replaces a `peer` row;
+ * a `register` write leaves a `manifest` row alone (`skipped`) and replaces a `peer` row; another owner's
+ * `manifest` or `register` row is `kind_owned`. `read_json` is written only by `manifest`. A catalog is replaced,
+ * never merged. Runs in the caller's write transaction.
+ */
+export declare function upsertKind(db: DatabaseSync, input: {
+    name: string;
+    owner: ObjectRow;
+    description: string;
+    events: CustomEvents;
+    read: {
+        command: string[];
+    } | null;
+    source: KindSource;
+}): {
+    outcome: 'inserted' | 'updated' | 'unchanged' | 'skipped';
+    changed: KindChange[];
+};
 export declare function publishCustom(db: DatabaseSync, object: ObjectRow, actor: ObjectRow | null, input: {
     event: string;
     summary: string;
@@ -67,8 +92,3 @@ export declare function acknowledge(db: DatabaseSync, object: ObjectRow, deliver
     unknown?: string[];
 };
 export declare function verifyPublishToken(db: DatabaseSync, object: ObjectRow, token: string): boolean;
-/** Run confinement for a node acting on a custom object of its app (Silas, 2026-09-30):
- *  a node reaches an object registered in its own run, or when neither run is isolated.
- *  An object the person or the app's server registered is reached by nodes outside
- *  isolation only. Any other reader is unchanged. */
-export declare function customReachable(db: DatabaseSync, reader: Reader, object: ObjectRow): boolean;