@north-light/cli 0.0.0 → 0.3.413

package/dist/api/command-manifest/manifest.js

@@ -0,0 +1 @@
+var U=Object.defineProperty;var h=(e,n)=>U(e,"name",{value:n,configurable:!0});import{validateCommandNode as $}from"./schema.js";import{isRecord as _}from"../../shared/predicates.js";const k=/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/,L=new Set(["GET","POST","PUT","PATCH","DELETE"]);function f(e){return e===null?"null":Array.isArray(e)?"array":typeof e}h(f,"typeName");function K(e,n){const a=[],o=h((t,v,A,j,x,g)=>{a.push({code:t,message:v,received:A,expected:j,next:x,...g?{path:g}:{}})},"issue");if(!_(e))return o("command_manifest_invalid","manifest must be an object",f(e),n.extensionFragment===!0?"{ schemaVersion, transport, mounts }":n.transport==="http"?"{ schemaVersion, version?, baseUrl?, timeouts?, mounts, helpAddenda? }":"{ schemaVersion, mounts, helpAddenda? }","Provide a valid JSON manifest object."),{issues:a};const s=Object.keys(e),r=n.extensionFragment===!0?new Set(["schemaVersion","transport","mounts"]):n.transport==="http"?new Set(["schemaVersion","version","baseUrl","timeouts","mounts","helpAddenda"]):new Set(["schemaVersion","mounts","helpAddenda"]),l=s.filter(t=>!r.has(t));if(l.length>0)return o("command_manifest_invalid","unknown top-level keys",l.join(", "),n.extensionFragment===!0?"only: schemaVersion, transport, mounts":n.transport==="http"?"only: schemaVersion, version, baseUrl, timeouts, mounts, helpAddenda":"only: schemaVersion, mounts, helpAddenda","Remove the unknown keys."),{issues:a};if(e.schemaVersion!==1)return o("command_schema_version","schemaVersion must be exactly 1",String(e.schemaVersion),"1","Update the manifest schema version to 1.","schemaVersion"),{issues:a};let d;if(n.transport==="http"&&n.extensionFragment!==!0&&e.version!==void 0){const t=e.version;if(typeof t!="number"||!Number.isInteger(t)||t<1)return o("command_manifest_invalid","version must be an integer of at least 1",f(t)==="number"?String(t):f(t),"the plugin major version as an integer >= 1, or omitted","Set version to the plugin's integer major.","version"),{issues:a};d=t}let m;if(n.transport==="http"&&e.baseUrl!==void 0){if(typeof e.baseUrl!="string")return o("command_manifest_invalid","baseUrl must be a string",f(e.baseUrl),"an absolute HTTP(S) URL or omitted","Provide a valid baseUrl or remove it.","baseUrl"),{issues:a};try{const t=new URL(e.baseUrl);if(!["http:","https:"].includes(t.protocol))return o("command_manifest_invalid","baseUrl must be http: or https:",t.protocol,"http: or https:","Use an HTTP(S) URL.","baseUrl"),{issues:a};m=e.baseUrl}catch{return o("command_manifest_invalid","baseUrl must be a valid absolute URL",e.baseUrl,"a valid URL","Fix the baseUrl.","baseUrl"),{issues:a}}}let i;if(n.transport==="http"&&e.timeouts!==void 0){const t=M(e.timeouts,o);if(t===null)return{issues:a};i=t}let p;if(e.helpAddenda!==void 0){const t=F(e.helpAddenda,n.coreCommandPaths,o);if(t===null)return{issues:a};Object.keys(t).length>0&&(p=t)}const c=e.mounts;if(!Array.isArray(c))return o("command_manifest_invalid","mounts must be an array",f(c),"a non-empty array of { parent, node } contributions","Provide at least one mount.","mounts"),{issues:a};if(c.length===0)return o("command_manifest_invalid","mounts must be a non-empty array","empty array","at least one contribution","Add at least one mount.","mounts"),{issues:a};const b=[];for(let t=0;t<c.length;t++){const v=R(c[t],t,n.transport,o,n.extensionFragment===!0?{topLevelRootEntry:"forbidden",allowPassthrough:!1,allowExtensible:!1}:void 0);if(v===null)return{issues:a};b.push(v)}const u=b.filter(t=>t.parent.length>0&&n.extensibleCoreBranches?.has(t.parent.join(" "))===!0);for(const t of u){const v=t.parent.join(" ");if(n.coreCommandPaths?.has(`${v} ${t.node.name}`)===!0)return o("command_collision",`contributed command "${t.node.name}" conflicts with a child the extensible core branch already owns`,t.node.name,`a name not already owned by the ${v} core branch`,"Rename the contributed command or remove this mount.",`${t.parent.join(".")}.${t.node.name}`),{issues:a}}const y=S(b.filter(t=>!u.includes(t)),n.reservedCoreNames,n.extensibleCoreBranches,o);return y===null?{issues:a}:a.length===0?{manifest:{schemaVersion:1,...d!==void 0?{version:d}:{},...m!==void 0?{baseUrl:m}:{},...i!==void 0?{timeouts:i}:{},...p!==void 0?{helpAddenda:p}:{},roots:y,coreMounts:u},issues:[]}:{issues:a}}h(K,"validateCommandManifest");function M(e,n){if(!_(e))return n("command_manifest_invalid","timeouts must be an object",f(e),"{ connectMs?, requestMs?, streamIdleMs? }","Fix timeouts.","timeouts"),null;const a=new Set(["connectMs","requestMs","streamIdleMs"]),o=Object.keys(e).filter(r=>!a.has(r));if(o.length>0)return n("command_manifest_invalid","unknown timeouts keys",o.join(", "),"only: connectMs, requestMs, streamIdleMs","Remove the unknown keys.","timeouts"),null;const s={};for(const r of["connectMs","requestMs","streamIdleMs"])if(e[r]!==void 0){if(typeof e[r]!="number"||!Number.isInteger(e[r])||e[r]<=0)return n("command_manifest_invalid",`${r} must be a positive integer`,String(e[r]),"a positive integer",`Fix ${r}.`,`timeouts.${r}`),null;s[r]=e[r]}return s}h(M,"validateTimeouts");function F(e,n,a){if(!_(e))return a("command_manifest_invalid","helpAddenda must be an object",f(e),"a map of core command path \u2192 addendum text","Fix helpAddenda.","helpAddenda"),null;const o={};for(const[s,r]of Object.entries(e)){if(s.split(" ").some(l=>!k.test(l)))return a("command_help_addendum_invalid","helpAddenda key must be a space-separated core command path",s,'kebab tokens separated by single spaces (e.g. "cron" or "cron add")',"Fix the helpAddenda key.",`helpAddenda.${s}`),null;if(typeof r!="string"||r.length===0)return a("command_manifest_invalid","helpAddenda value must be a non-empty string",typeof r=="string"?"empty string":f(r),"non-empty addendum text","Fix the helpAddenda value.",`helpAddenda.${s}`),null;if(n!==void 0&&!n.has(s))return a("command_help_addendum_invalid","helpAddenda key names no crtr core command path",s,'an existing core command path (e.g. "cron", "cron add")',"Fix the key or remove the addendum.",`helpAddenda.${s}`),null;o[s]=r}return o}h(F,"validateHelpAddenda");function R(e,n,a,o,s){const r=`mounts[${n}]`;if(!_(e))return o("command_manifest_invalid","mount must be an object",f(e),"{ parent, node }","Fix the mount.",r),null;const l=new Set(["parent","node"]),d=Object.keys(e).filter(u=>!l.has(u));if(d.length>0)return o("command_manifest_invalid","unknown mount keys",d.join(", "),"only: parent, node","Remove the unknown keys.",r),null;const m=e.parent;if(!Array.isArray(m))return o("command_manifest_invalid","mount parent must be an array",f(m),"an array of kebab tokens, or [] for a top-level mount","Fix parent.",`${r}.parent`),null;for(let u=0;u<m.length;u++){const y=m[u];if(typeof y!="string"||!k.test(y))return o("command_manifest_invalid","parent token must be a kebab token",String(y),"a kebab-case identifier","Fix the parent path.",`${r}.parent[${u}]`),null}const i=m,p=e.node,c=i.length===0,b=$(p,[`${r}.node`],c,a,o,s);return b===null?null:{parent:i,node:b}}h(R,"validateMount");function S(e,n,a,o){const s=e.filter(i=>i.parent.length===0),r=e.filter(i=>i.parent.length>0);for(const i of s)if(n.has(i.node.name))return o("command_collision","node name conflicts with a crtr core command",i.node.name,`a name not in core (not one of: ${[...n].join(", ")})`,"Rename the node or remove this mount.",`${i.node.name}`),null;const l=s.map(i=>i.node.kind==="branch"?{...i.node,children:[...i.node.children]}:{...i.node});for(const i of r)if(n.has(i.parent[0]))return o("command_parent_invalid","parent path starts with a core branch that is not extensible",i.parent[0],`an extensible core branch (one of: ${[...a??[]].join(", ")})`,`Mount below one of the extensible core branches: ${[...a??[]].join(", ")}.`,i.parent.join(".")),null;for(const i of r)if(!V(l,i,o))return null;const d=new Set,m=h((i,p)=>{const c=p.join(".");return d.has(c)?(o("command_node_invalid","duplicate node path",c,"unique paths within the manifest","Remove the duplicate node.",c),!1):(d.add(c),i.kind==="branch"?i.children.every(b=>m(b,[...p,b.name])):!0)},"indexPaths");for(const i of l)if(!m(i,[i.name]))return null;return l}h(S,"materializeForest");function V(e,n,a){const[o,...s]=n.parent,r=e.find(d=>d.name===o);if(!r)return a("command_parent_invalid","parent path starts with unknown branch",o,"a branch this manifest contributes","Fix the parent path or add the parent branch.",n.parent.join(".")),!1;if(r.kind==="leaf")return a("command_parent_invalid","parent path resolves to a leaf",o,"a branch","Change the parent to point to a branch.",n.parent.join(".")),!1;let l=r;for(const d of s){const m=l.children.find(i=>i.name===d);if(!m)return a("command_parent_invalid","parent path contains unknown branch",d,"a branch this manifest contributes","Fix the parent path or add the intermediate branch.",n.parent.join(".")),!1;if(m.kind==="leaf")return a("command_parent_invalid","parent path resolves to a leaf",d,"a branch","Change the parent to point to a branch.",n.parent.join(".")),!1;l=m}return l.passthrough!==void 0?(a("command_parent_invalid","parent path resolves to a passthrough branch",n.parent.join("."),"a branch without passthrough","Remove the nested mount or remove passthrough from its parent branch.",n.parent.join(".")),!1):l.children.some(d=>d.name===n.node.name)?(a("command_node_invalid","duplicate child name",n.node.name,"unique child names within a branch","Rename the node or remove the duplicate.",`${n.parent.join(".")}.${n.node.name}`),!1):(l.children.push(n.node),!0)}h(V,"resolveAndAttachMount");export{K as validateCommandManifest};

package/dist/api/command-manifest/result.d.ts

@@ -0,0 +1,25 @@
+export interface DeclaredOutputShape {
+    type: string;
+    constraint: string;
+    /** Named members of an `object` value. */
+    children?: DeclaredOutputField[];
+    /** Element shape of an `array` value. */
+    items?: DeclaredOutputShape;
+    /** Allowed values of an `enum` value. */
+    values?: string[];
+}
+export interface DeclaredOutputField extends DeclaredOutputShape {
+    name: string;
+    required: boolean;
+}
+/** Validates a result object against declared output field descriptors.
+ *  Returns null if valid; otherwise returns a { field, receivedType } error. */
+export declare function validateDeclaredResult(output: DeclaredOutputField[], result: Record<string, unknown>): {
+    field: string;
+    receivedType?: string;
+} | null;
+/** Core leaf declarations may explicitly require a nullable field. */
+export declare function validateCoreDeclaredResult(output: DeclaredOutputField[], result: Record<string, unknown>): {
+    field: string;
+    receivedType?: string;
+} | null;

package/dist/api/command-manifest/result.js

@@ -0,0 +1 @@
+var c=Object.defineProperty;var i=(n,e)=>c(n,"name",{value:e,configurable:!0});import{isRecord as u}from"../../shared/predicates.js";function g(n,e){return f(n,e,!0)}i(g,"validateDeclaredResult");function h(n,e){return f(n,e,!0)}i(h,"validateCoreDeclaredResult");function f(n,e,r){for(const t of n){const o=e[t.name],a=Object.prototype.hasOwnProperty.call(e,t.name)&&o!==void 0&&(r||o!==null);if(t.required&&!a)return{field:t.name};const s=r?p(t,o):y(t.type,o);if(a&&!s)return{field:t.name,receivedType:o===null?"null":typeof o}}return null}i(f,"validateFields");function y(n,e){const r=n.toLowerCase();return r==="string"||r==="path"?typeof e=="string":r==="int"||r==="integer"?typeof e=="number"&&Number.isInteger(e):r==="number"||r==="float"?typeof e=="number":r==="bool"||r==="boolean"?typeof e=="boolean":r==="array"||r.endsWith("[]")?Array.isArray(e):r==="object"?u(e):!0}i(y,"typeMatches");function p(n,e){const r=n.type.split("|").map(o=>o.trim()).filter(Boolean);return r.length===1&&!l(r[0])||!r.every(o=>l(o)||/^[a-z][a-z0-9_-]*$/.test(o))?!0:r.some(o=>m(o,e,n))}i(p,"coreTypeMatches");function l(n){const e=n.toLowerCase();return e==="null"||e==="string"||e==="path"||e==="markdown"||e==="int"||e==="integer"||e==="number"||e==="float"||e==="bool"||e==="boolean"||e==="array"||e.endsWith("[]")||e==="object"||e==="enum"||e==="file"}i(l,"knownType");function m(n,e,r){const t=n.toLowerCase();return t==="null"?e===null:t==="enum"?r.values===void 0||typeof e=="string"&&r.values.includes(e):t==="file"?u(e)||typeof e=="string":t==="string"||t==="path"||t==="markdown"?typeof e=="string":t==="int"||t==="integer"?typeof e=="number"&&Number.isInteger(e):t==="number"||t==="float"?typeof e=="number":t==="bool"||t==="boolean"?typeof e=="boolean":t==="array"||t.endsWith("[]")?Array.isArray(e):t==="object"?u(e):typeof e=="string"&&e===n}i(m,"atomMatches");export{h as validateCoreDeclaredResult,g as validateDeclaredResult};

package/dist/api/command-manifest/schema.d.ts

@@ -0,0 +1,28 @@
+import type { ManifestRootEntry as DeclRootEntry, ManifestPassthrough as DeclPassthrough, ManifestLeafBase as DeclLeafBase, ManifestExecLeaf as ExecDeclLeaf, ManifestHttpLeaf as HttpDeclLeaf, ManifestLeaf as DeclLeaf, ManifestBranch as DeclBranch, ManifestNode as DeclNode, RestMethod, RestParamPlacement, RestParamMapping, RestMapping, ManifestTimeouts } from '../plugin-manifest-schema.js';
+export type { DeclRootEntry, DeclPassthrough, DeclLeafBase, ExecDeclLeaf, HttpDeclLeaf, DeclLeaf, DeclBranch, DeclNode, RestMethod, RestParamPlacement, RestParamMapping, RestMapping, ManifestTimeouts, };
+export interface CommandManifestIssue {
+    code: CommandIssueCode;
+    path?: string;
+    message: string;
+    received: string;
+    expected: string;
+    next: string;
+}
+export type CommandIssueCode = 'command_manifest_unreadable' | 'command_manifest_invalid' | 'command_schema_version' | 'command_path_unsafe' | 'command_not_executable' | 'command_parent_invalid' | 'command_node_invalid' | 'command_collision' | 'command_help_addendum_invalid' | 'command_rest_invalid' | 'command_extension_invalid';
+type IssueFn = (code: CommandIssueCode, message: string, received: string, expected: string, next: string, path?: string) => void;
+/** Base type of a declared output type: the union with every `null` part
+ *  dropped, lower-cased. It decides which structural keys the shape may carry. */
+export declare function outputBaseType(type: string): string;
+/** Whether a declared output type names `file` anywhere: as a union part or
+ *  as the element of an array type. */
+export declare function mentionsFile(type: string): boolean;
+export type TransportKind = 'exec' | 'http';
+export interface CommandNodeValidationOptions {
+    /** Plugin roots need rootEntry; repository-fragment roots attach under an existing branch and forbid it. */
+    topLevelRootEntry?: 'required' | 'forbidden';
+    /** Repository fragments have no passthrough escape hatch. */
+    allowPassthrough?: boolean;
+    /** Only plugin manifests may mark their own top-level branch extensible. */
+    allowExtensible?: boolean;
+}
+export declare function validateCommandNode(raw: unknown, path: string[], topLevel: boolean, transport: TransportKind, issue: IssueFn, options?: CommandNodeValidationOptions): DeclBranch<DeclLeaf> | DeclLeaf | null;

package/dist/api/command-manifest/schema.js

@@ -0,0 +1 @@
+var V=Object.defineProperty;var _=(e,t)=>V(e,"name",{value:t,configurable:!0});import{isRecord as x}from"../../shared/predicates.js";const Z=new Set(["normal","common","important"]),W=new Set(["string","int","bool","path","enum","file"]),X=/^[A-Za-z0-9_-]{1,64}$/,O=/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/,U=new Set(["kind","name","description","whenToUse","tier","rootEntry","extensible","summary","model","children"]),J=new Set([...U,"passthrough"]),L=new Set(["bin","installHint"]),N=new Set(["kind","name","description","whenToUse","tier","summary","params","output","effects"]),Q=new Set([...N,"outputKind"]),w=new Set([...N,"rest","group"]),ee=new Set(["concept","description","whenToUse"]),ne=new Set(["text","base64"]),C={positional:new Set(["kind","name","type","required","constraint","repeatable","encoding","defaultFromEnv"]),flag:new Set(["kind","name","type","choices","required","constraint","default","repeatable","encoding","defaultFromEnv"]),stdin:new Set(["kind","name","required","constraint"]),"context-file":new Set(["kind","name","required","constraint","shape"])},te=new Set(["name","type","required","constraint","children","items","values"]),ae=new Set(["type","constraint","children","items","values"]),oe=/^[A-Z][A-Z0-9_]*$/;function m(e){return e===null?"null":Array.isArray(e)?"array":typeof e}_(m,"typeName");function T(e,t,a,n){const o=Object.keys(e).filter(p=>!t.has(p));return o.length>0?(n("command_node_invalid","unknown keys",o.join(", "),`only: ${[...t].join(", ")}`,"Remove the unknown keys.",a),!1):!0}_(T,"checkKeys");function re(e,t,a){if(!x(e))return a("command_node_invalid","rootEntry must be an object",m(e),"a { concept, description, whenToUse } object","Fix rootEntry.",t),null;if(!T(e,ee,t,a))return null;for(const n of["concept","description","whenToUse"])if(typeof e[n]!="string"||e[n].length===0)return a("command_node_invalid",`rootEntry.${n} must be a non-empty string`,m(e[n]),"a non-empty string",`Add rootEntry.${n}.`,`${t}.${n}`),null;return{concept:e.concept,description:e.description,whenToUse:e.whenToUse}}_(re,"validateRootEntry");function ie(e,t,a){if(e===void 0)return[];if(!Array.isArray(e))return a("command_node_invalid","params must be an array",m(e),"an array of params (or omitted)","Fix params.",t),null;const n=[],o=new Set;let p=0;for(let c=0;c<e.length;c++){const r=e[c],i=`${t}[${c}]`;if(!x(r))return a("command_node_invalid","param must be an object",m(r),"a param object","Fix the param.",i),null;const u=r.kind;if(typeof u!="string"||!(u in C))return a("command_node_invalid","param kind must be positional|flag|stdin|context-file",String(u),"positional | flag | stdin | context-file","Fix the param kind.",`${i}.kind`),null;if(!T(r,C[u],i,a))return null;const d=r.name;if(typeof d!="string"||!O.test(d))return a("command_node_invalid","param name must be a kebab-case token",String(d),"a kebab-case token","Rename the param.",`${i}.name`),null;if(o.has(d))return a("command_node_invalid","duplicate param name",d,"unique param names","Rename the duplicate param.",`${i}.name`),null;if(o.add(d),typeof r.required!="boolean")return a("command_node_invalid","param required must be a boolean",m(r.required),"true | false","Set required.",`${i}.required`),null;if(typeof r.constraint!="string")return a("command_node_invalid","param constraint must be a string",m(r.constraint),"an inline constraint string","Add a constraint.",`${i}.constraint`),null;if(u==="positional"){if(p++,p>1)return a("command_node_invalid","a leaf may declare at most one positional","multiple positionals","at most one positional param","Convert extra positionals to flags.",i),null;if(r.type!==void 0&&r.type!=="string"&&r.type!=="path"&&r.type!=="file")return a("command_node_invalid","positional type must be string|path|file",String(r.type),"string | path | file | omitted","Fix the positional type.",`${i}.type`),null;let s=!1;if(r.repeatable!==void 0){if(typeof r.repeatable!="boolean")return a("command_node_invalid","repeatable must be a boolean",m(r.repeatable),"true | false | omitted","Fix repeatable.",`${i}.repeatable`),null;s=r.repeatable}if(s&&r.type==="file")return a("command_node_invalid","repeatable is not valid on a file positional",`${d}: file`,"one file per file param","Remove repeatable, or declare one file param per file.",`${i}.repeatable`),null;const g=H(r,i,a);if(g===null)return null;const y=M(r,i,a);if(y===null)return null;if(s&&y!==void 0)return a("command_node_invalid","repeatable positional must not declare defaultFromEnv",d,"no defaultFromEnv on a repeatable positional (values accumulate into an array)","Remove defaultFromEnv, or drop repeatable.",`${i}.defaultFromEnv`),null;n.push({kind:"positional",name:d,...r.type!==void 0?{type:r.type}:{},required:r.required,constraint:r.constraint,...s?{repeatable:!0}:{},...g!==void 0?{encoding:g}:{},...y!==void 0?{defaultFromEnv:y}:{}})}else if(u==="stdin")n.push({kind:"stdin",name:d,required:r.required,constraint:r.constraint});else if(u==="context-file")n.push({kind:"context-file",name:d,required:r.required,constraint:r.constraint,...typeof r.shape=="string"?{shape:r.shape}:{}});else if(u==="flag"){const s=r.type;if(typeof s!="string"||!W.has(s))return a("command_node_invalid","flag type must be string|int|bool|path|enum|file",String(s),"string | int | bool | path | enum | file","Fix the flag type.",`${i}.type`),null;let g;if(s==="enum"){const h=r.choices;if(!Array.isArray(h)||h.length===0||!h.every(k=>typeof k=="string"))return a("command_node_invalid","enum flag requires a non-empty string choices array",m(h),"a non-empty array of strings","Declare choices for the enum flag.",`${i}.choices`),null;g=h}else if(r.choices!==void 0)return a("command_node_invalid","choices is only valid on an enum flag","choices","no choices unless type is enum","Remove choices.",`${i}.choices`),null;let y=!1;if(r.repeatable!==void 0){if(typeof r.repeatable!="boolean")return a("command_node_invalid","repeatable must be a boolean",m(r.repeatable),"true | false | omitted","Fix repeatable.",`${i}.repeatable`),null;y=r.repeatable}if(y&&(s==="bool"||s==="path"||s==="file"))return a("command_node_invalid",`repeatable is not valid on a ${s} flag`,`${d}: ${s}`,"repeatable only on string | int | enum flags","Remove repeatable or change the flag type.",`${i}.repeatable`),null;if(y&&r.default!==void 0)return a("command_node_invalid","repeatable flag must not declare a default",d,"no default on a repeatable flag (values accumulate into an array)","Remove the default.",`${i}.default`),null;const $=H(r,i,a);if($===null)return null;const E=M(r,i,a);if(E===null)return null;if(y&&E!==void 0)return a("command_node_invalid","repeatable flag must not declare defaultFromEnv",d,"no defaultFromEnv on a repeatable flag (values accumulate into an array)","Remove defaultFromEnv, or drop repeatable.",`${i}.defaultFromEnv`),null;n.push({kind:"flag",name:d,type:s,...g!==void 0?{choices:g}:{},...$!==void 0?{encoding:$}:{},required:r.required,constraint:r.constraint,...r.default!==void 0?{default:r.default}:{},...y?{repeatable:!0}:{},...E!==void 0?{defaultFromEnv:E}:{}})}}return n}_(ie,"validateParams");function H(e,t,a){const n=e.encoding;if(n!==void 0)return typeof n!="string"||!ne.has(n)?(a("command_node_invalid","param encoding must be text|base64",String(n),"text | base64 | omitted","Fix the encoding.",`${t}.encoding`),null):e.type!=="path"?(a("command_node_invalid",'encoding is only valid on a type:"path" param',`type ${String(e.type)}`,'type: "path"','Set the param type to "path", or remove encoding.',`${t}.encoding`),null):n}_(H,"validateFileEncoding");function M(e,t,a){const n=e.defaultFromEnv;if(n===void 0)return;if(typeof n!="string"||!oe.test(n))return a("command_node_invalid","defaultFromEnv must name an environment variable in UPPER_SNAKE_CASE",String(n),'e.g. "CRTR_NODE_ID"',"Fix the environment variable name.",`${t}.defaultFromEnv`),null;const o=e.type===void 0&&e.kind==="positional"?"string":e.type;return o!=="string"&&o!=="path"?(a("command_node_invalid","defaultFromEnv is only valid on a string|path param",`type ${String(e.type)}`,'type: "string" | "path"',"Change the param type, or remove defaultFromEnv.",`${t}.defaultFromEnv`),null):e.default!==void 0?(a("command_node_invalid","a param must not declare both default and defaultFromEnv",`${String(e.name)}: default + defaultFromEnv`,"exactly one default source","Remove one \u2014 defaultFromEnv counts as supplied, a static default does not.",`${t}.defaultFromEnv`),null):n}_(M,"validateDefaultFromEnv");function D(e){return e.split("|").map(t=>t.trim().toLowerCase()).filter(t=>t.length>0&&t!=="null").join(" | ")}_(D,"outputBaseType");function le(e){return e.split("|").some(t=>/^file(\[\])*$/i.test(t.trim()))}_(le,"mentionsFile");function G(e,t,a,n){if(typeof e.type!="string"||e.type.length===0)return n("command_node_invalid","output field type must be a non-empty string",m(e.type),"a type name","Add a type.",`${t}.type`),null;if(typeof e.constraint!="string")return n("command_node_invalid","output field constraint must be a string",m(e.constraint),"a constraint string","Add a constraint.",`${t}.constraint`),null;const o=e.type,p=D(o);if(le(o)&&p!=="file")return n("command_node_invalid","a file output is one file, optionally nullable",o,'type "file" or "file | null"','Return one file per leaf; declare it as "file" or "file | null".',`${t}.type`),null;if(p==="file"&&!a)return n("command_node_invalid","a file output must be a top-level output field",o,`type "file" only on a leaf's own output fields, never inside children or items`,"Move the file field to the top level of the leaf output.",`${t}.type`),null;const c=[["children","object"],["items","array"],["values","enum"]];for(const[d,s]of c)if(e[d]!==void 0&&p!==s)return n("command_node_invalid",`output ${d} is only valid on an ${s} field`,`type ${o}`,`type "${s}" (optionally "${s} | null")`,`Remove ${d}, or change the type to ${s}.`,`${t}.${d}`),null;let r;if(e.children!==void 0){const d=Y(e.children,`${t}.children`,!1,n);if(d===null)return null;r=d}let i;if(e.items!==void 0){const d=e.items,s=`${t}.items`;if(!x(d))return n("command_node_invalid","output items must be an object",m(d),"a { type, constraint, children?, items?, values? } object","Fix the items shape.",s),null;if(!T(d,ae,s,n))return null;const g=G(d,s,!1,n);if(g===null)return null;i=g}let u;if(e.values!==void 0){const d=e.values;if(!Array.isArray(d)||d.length===0||!d.every(s=>typeof s=="string"&&s.length>0))return n("command_node_invalid","enum output values must be a non-empty array of strings",m(d),"a non-empty array of non-empty strings","Declare the values the field may take.",`${t}.values`),null;if(new Set(d).size!==d.length)return n("command_node_invalid","enum output values must be unique",d.join(", "),"distinct values","Remove the duplicate value.",`${t}.values`),null;u=d}return{type:o,constraint:e.constraint,...r!==void 0?{children:r}:{},...i!==void 0?{items:i}:{},...u!==void 0?{values:u}:{}}}_(G,"validateOutputShape");function de(e,t,a){return Y(e,t,!0,a)}_(de,"validateOutput");function Y(e,t,a,n){if(!Array.isArray(e))return n("command_node_invalid",a?"output must be an array":"output children must be an array",m(e),"an array of output fields",a?"Declare the leaf output fields.":"Declare the object's member fields.",t),null;const o=[],p=new Set;let c;for(let r=0;r<e.length;r++){const i=e[r],u=`${t}[${r}]`;if(!x(i))return n("command_node_invalid","output field must be an object",m(i),"a { name, type, required, constraint } object","Fix the output field.",u),null;if(!T(i,te,u,n))return null;if(typeof i.name!="string"||i.name.length===0)return n("command_node_invalid","output field name must be a non-empty string",m(i.name),"a field name","Add a name.",`${u}.name`),null;if(!a&&p.has(i.name))return n("command_node_invalid","duplicate output child name",i.name,"unique member names within one object","Rename the duplicate member.",`${u}.name`),null;if(p.add(i.name),typeof i.required!="boolean")return n("command_node_invalid","output field required must be a boolean",m(i.required),"true | false","Set required.",`${u}.required`),null;const d=G(i,u,a,n);if(d===null)return null;if(D(d.type)==="file"){if(c!==void 0)return n("command_node_invalid","a leaf declares at most one file output",`${c}, ${i.name}`,'one top-level output field of type "file"',"Return the extra files through a separate leaf, or drop the extra file field.",`${u}.type`),null;c=i.name}o.push({name:i.name,...d,required:i.required})}return o}_(Y,"validateOutputFields");function z(e,t,a){const n=e.name;return typeof n!="string"||!O.test(n)?(a("command_node_invalid","node name must be a lowercase kebab-case token",String(n),'a kebab-case token like "app" or "list-all"',"Rename the node.",`${t}.name`),!1):typeof e.description!="string"||e.description.length===0?(a("command_node_invalid","node description must be a non-empty string",m(e.description),"a short parent-listing description","Add a description.",`${t}.description`),!1):typeof e.whenToUse!="string"||e.whenToUse.length===0?(a("command_node_invalid","node whenToUse must be a non-empty string",m(e.whenToUse),"a parent selection rubric","Add a whenToUse rubric.",`${t}.whenToUse`),!1):e.tier!==void 0&&!Z.has(String(e.tier))?(a("command_node_invalid","node tier must be normal|common|important",String(e.tier),"normal | common | important","Fix or omit tier (external plugins cannot declare hidden commands).",`${t}.tier`),!1):!0}_(z,"checkCommon");function me(e,t,a,n,o,p={}){const c=t.join(".");if(!x(e))return o("command_node_invalid","node must be an object",m(e),"a branch or leaf node object","Fix the node.",c),null;const r=e.kind;return r==="branch"?se(e,c,a,n,o,p):r==="leaf"?a&&p.topLevelRootEntry!=="forbidden"?(o("command_node_invalid","top-level node must be a branch","leaf","a branch node with a rootEntry","Wrap the command in a top-level branch (noun) with a rootEntry.",`${c}.kind`),null):ce(e,c,n,o):(o("command_node_invalid",'node kind must be "branch" or "leaf"',String(r),"branch | leaf","Set kind to branch or leaf.",`${c}.kind`),null)}_(me,"validateCommandNode");function se(e,t,a,n,o,p){const c=p.allowPassthrough!==!1;if(!T(e,n==="exec"&&c?J:U,t,o)||!z(e,t,o))return null;const i=e.rootEntry!==void 0,u=p.topLevelRootEntry??"required";if(a&&u==="required"&&!i)return o("command_node_invalid","top-level branch requires a rootEntry","(missing)","a rootEntry { concept, description, whenToUse }","Add a rootEntry to the top-level branch.",`${t}.rootEntry`),null;if((!a||u==="forbidden")&&i)return o("command_node_invalid",a?"repository fragment root must not declare a rootEntry":"nested branch must not declare a rootEntry","rootEntry",a?"no rootEntry (the owning plugin branch already has one)":"no rootEntry (only top-level branches carry one)",a?"Remove rootEntry from the repository fragment root.":"Remove rootEntry from the nested branch.",`${t}.rootEntry`),null;const d=e.extensible!==void 0;if(d&&(!a||p.allowExtensible===!1||e.extensible!==!0))return o("command_node_invalid",a?"extensible must be exactly true on a plugin top-level branch":"extensible is valid only on a top-level branch mount",String(e.extensible),a?"extensible: true":"no extensible marker on nested branches",a?"Set extensible to true or remove it.":"Move the marker to the plugin top-level branch or remove it.",`${t}.extensible`),null;let s;if(i){const h=re(e.rootEntry,`${t}.rootEntry`,o);if(h===null)return null;s=h}if(typeof e.summary!="string"||e.summary.length===0)return o("command_node_invalid","branch summary must be a non-empty string",m(e.summary),"a one-line summary string","Add a summary.",`${t}.summary`),null;if(e.model!==void 0&&typeof e.model!="string")return o("command_node_invalid","branch model must be a string",m(e.model),"a string or omitted","Fix or remove model.",`${t}.model`),null;let g;if(n==="exec"&&e.passthrough!==void 0){const h=ue(e.passthrough,`${t}.passthrough`,o);if(h===null)return null;g=h}if(d&&g!==void 0)return o("command_node_invalid","an extensible branch cannot declare passthrough","extensible and passthrough","one branch mode: extensible or passthrough","Remove passthrough or remove extensible.",t),null;const y=e.children;if(g!==void 0){if(!Array.isArray(y)||y.length!==0)return o("command_node_invalid","a passthrough branch must declare children: []",Array.isArray(y)?`${y.length} children`:m(y),"an empty children array","Set children to [] \u2014 a passthrough branch forwards all argv and can own no subcommands.",`${t}.children`),null}else if(!Array.isArray(y))return o("command_node_invalid","branch children must be an array",m(y),"an array of branch/leaf nodes (may be empty for populated by mounts)","Fix children.",`${t}.children`),null;const $=[],E=new Set;for(let h=0;h<y.length;h++){const k=me(y[h],[...t.split("."),`children[${h}]`],!1,n,o,p);if(k===null)return null;if(E.has(k.name))return o("command_node_invalid","duplicate child name",k.name,"unique child names within a branch","Rename the duplicate child.",`${t}.children[${h}].name`),null;E.add(k.name),$.push(k)}return{kind:"branch",name:e.name,description:e.description,whenToUse:e.whenToUse,...e.tier!==void 0?{tier:e.tier}:{},...s!==void 0?{rootEntry:s}:{},...d?{extensible:!0}:{},summary:e.summary,...e.model!==void 0?{model:e.model}:{},...g!==void 0?{passthrough:g}:{},children:$}}_(se,"validateBranch");function ue(e,t,a){if(!x(e))return a("command_node_invalid","passthrough must be an object",m(e),"an object { bin, installHint }","Fix or remove passthrough.",t),null;if(!T(e,L,t,a))return null;for(const n of["bin","installHint"])if(typeof e[n]!="string"||e[n].length===0)return a("command_node_invalid",`passthrough ${n} must be a non-empty string`,m(e[n]),n==="bin"?"the external binary name":"a one-line install hint",`Set passthrough.${n}.`,`${t}.${n}`),null;return{bin:e.bin,installHint:e.installHint}}_(ue,"validatePassthrough");function ce(e,t,a,n){if(!T(e,a==="exec"?Q:w,t,n)||!z(e,t,n))return null;if(typeof e.summary!="string"||e.summary.length===0)return n("command_node_invalid","leaf summary must be a non-empty string",m(e.summary),"a one-line summary string","Add a summary.",`${t}.summary`),null;if(a==="exec"&&e.outputKind!=="object")return n("command_node_invalid",'leaf outputKind must be "object" in v1',String(e.outputKind),'exactly "object"','Set outputKind to "object".',`${t}.outputKind`),null;if(a==="http"&&e.rest===void 0)return n("command_node_invalid","HTTP leaf requires a rest mapping","(missing)","a rest object with method, path, and params","Add a rest mapping.",`${t}.rest`),null;const o=ie(e.params,`${t}.params`,n);if(o===null)return null;const p=de(e.output,`${t}.output`,n);if(p===null)return null;const c=e.effects;if(!Array.isArray(c)||c.length===0||!c.every(d=>typeof d=="string"))return n("command_node_invalid","leaf effects must be a non-empty string array",m(c),'a non-empty array of strings (["None. Read-only."] for read-only leaves)',"Declare every persistent effect.",`${t}.effects`),null;const r={kind:"leaf",name:e.name,description:e.description,whenToUse:e.whenToUse,...e.tier!==void 0?{tier:e.tier}:{},summary:e.summary,params:o,output:p,effects:c};if(a==="exec")return{...r,outputKind:"object"};const i=e.group;if(i!==void 0&&(typeof i!="string"||!X.test(i)))return n("command_node_invalid","leaf group must match [A-Za-z0-9_-]{1,64}",typeof i=="string"?i:m(i),'a group id of 1-64 letters, digits, "_" or "-" (no ":" or whitespace)',`Rename the group on leaf ${t}.`,`${t}.group`),null;const u=he(e.rest,t,o,n);return u===null?null:{...r,rest:u,...i!==void 0?{group:i}:{}}}_(ce,"validateLeaf");const fe=new Set(["GET","POST","PUT","PATCH","DELETE"]),pe=/^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/,ye=new Set(["path","query","body","header"]);function he(e,t,a,n){const o=`${t}.rest`;if(!x(e))return n("command_rest_invalid","rest must be an object",m(e),"{ method, path, streaming?, params }","Provide a valid rest mapping.",o),null;const p=new Set(["method","path","streaming","body","bodyRoot","params"]),c=Object.keys(e).filter(l=>!p.has(l));if(c.length>0)return n("command_rest_invalid","unknown rest keys",c.join(", "),"only: method, path, streaming, body, bodyRoot, params","Remove the unknown keys.",o),null;const r=e.method;if(typeof r!="string"||!fe.has(r))return n("command_rest_invalid","method must be GET|POST|PUT|PATCH|DELETE",String(r),"one of the HTTP methods","Set method to a valid HTTP verb.",`${o}.method`),null;const i=e.path;if(typeof i!="string"||!i.startsWith("/"))return n("command_rest_invalid","path must be an absolute path starting with /",String(i),'an absolute path like "/v1/devices/{id}"',"Fix the path.",`${o}.path`),null;const u=new Set,d=/\{([a-z][a-z0-9]*(?:-[a-z0-9]+)*)\}/g;let s;for(;(s=d.exec(i))!==null;)u.add(s[1]);let g=!1;if(e.streaming!==void 0){if(typeof e.streaming!="boolean")return n("command_rest_invalid","streaming must be a boolean",m(e.streaming),"true | false | omitted","Fix streaming.",`${o}.streaming`),null;g=e.streaming}const y=e.params;if(!x(y))return n("command_rest_invalid","params must be an object",m(y),"a mapping of param names to placement specs","Provide params.",`${o}.params`),null;const $=new Map;for(const l of a)$.set(l.name,l);const E={},h=[],k=new Set;for(const[l,v]of Object.entries(y)){if(!$.has(l))return n("command_rest_invalid","rest params key has no matching declared param",l,"a name from the leaf params array","Remove this rest params entry or declare the param.",`${o}.params.${l}`),null;if(k.add(l),!x(v))return n("command_rest_invalid","param mapping must be an object",m(v),"{ in, as? }","Fix the param mapping.",`${o}.params.${l}`),null;const S=new Set(["in","as"]),R=Object.keys(v).filter(F=>!S.has(F));if(R.length>0)return n("command_rest_invalid","unknown param mapping keys",R.join(", "),"only: in, as","Remove the unknown keys.",`${o}.params.${l}`),null;const f=v.in;if(typeof f!="string"||!ye.has(f))return n("command_rest_invalid","param placement must be path|query|body|header",String(f),"path | query | body | header","Set in to a valid placement.",`${o}.params.${l}.in`),null;const b=v.as;if(b!==void 0&&(typeof b!="string"||b.length===0))return n("command_rest_invalid","as must be a non-empty string",String(b),"a non-empty string","Fix the as value.",`${o}.params.${l}.as`),null;if(f==="header"){if(typeof b!="string"||b.length===0)return n("command_rest_invalid","header placement requires a non-empty as",String(b),"a header name","Provide an as value for the header name.",`${o}.params.${l}.as`),null;if(!pe.test(b))return n("command_rest_invalid",'header "as" must be a legal HTTP header field name',b,"an HTTP token (letters, digits, and !#$%&'*+-.^_`|~)","Fix the header name.",`${o}.params.${l}.as`),null;if(b.toLowerCase()==="crtr-request-id")return n("command_rest_invalid","Crtr-Request-Id is assigned by crtr for each leaf call",b,"a header name other than Crtr-Request-Id","Remove this header mapping.",`${o}.params.${l}.as`),null}else if(f==="path"){if(b!==void 0)return n("command_rest_invalid","path placement must not have as","as","no as (placeholder name governs)","Remove as.",`${o}.params.${l}.as`),null;const F=$.get(l);if(F.required!==!0)return n("command_rest_invalid",'in:"path" param must be declared required',`${l}: required ${String(F.required)}`,"required: true",`Set "required": true on the "${l}" param.`,`${o}.params.${l}`),null}const K=$.get(l);if((K.kind==="flag"||K.kind==="positional")&&K.repeatable===!0&&f!=="body")return n("command_rest_invalid","repeatable param must use body placement",`${l}: in "${f}"`,'in: "body" (array values ship as a JSON array)',`Map "${l}" to body placement.`,`${o}.params.${l}.in`),null;if(f==="body"){const B=$.get(l).kind==="stdin",I=b||l;h.push({name:l,isStdin:B,as:I})}E[l]={in:f,...b!==void 0?{as:b}:{}}}for(const l of a)if(!k.has(l.name))return n("command_rest_invalid","declared param not in rest mapping",l.name,"an entry in rest.params","Add a rest mapping for this param.",`${o}.params`),null;const A=new Set;for(const[l,v]of Object.entries(E))v.in==="path"&&A.add(l);if(A.size!==u.size||![...u].every(l=>A.has(l)))return n("command_rest_invalid","mismatch between path placeholders and path params",`placeholders: ${[...u].join(", ")} | params: ${[...A].join(", ")}`,'exact bijection between {placeholders} and in:"path" params',"Ensure every placeholder has a matching path param, and vice versa.",`${o}.path and ${o}.params`),null;if(r==="GET"&&h.length>0)return n("command_rest_invalid","GET method cannot have body params",h.map(l=>l.name).join(", "),"no body placement for GET","Move body params to query, or change the method.",`${o}.method or ${o}.params`),null;let j;if(e.body!==void 0){if(r==="GET")return n("command_rest_invalid","GET method cannot have body constants","body","no body for GET","Remove body, or change the method.",`${o}.body`),null;const l=e.body;if(!x(l))return n("command_rest_invalid","body must be an object",m(l),"a map of constant literal body fields (string | number | boolean)","Fix body.",`${o}.body`),null;const v={};for(const[f,b]of Object.entries(l)){if(typeof b!="string"&&typeof b!="number"&&typeof b!="boolean")return n("command_rest_invalid",`body.${f} must be a string, number, or boolean`,m(b),"string | number | boolean",`Fix body.${f}.`,`${o}.body.${f}`),null;v[f]=b}const S=new Set(h.map(f=>f.as)),R=Object.keys(v).filter(f=>S.has(f));if(R.length>0)return n("command_rest_invalid","body constant key collides with a param's body key",R.join(", "),"body constant keys distinct from every param's body key (its as or name)","Rename the colliding body constant or param.",`${o}.body`),null;j=v}let P;if(e.bodyRoot!==void 0){if(r==="GET")return n("command_rest_invalid","GET method cannot have bodyRoot","bodyRoot","no bodyRoot for GET","Remove bodyRoot, or change the method.",`${o}.bodyRoot`),null;const l=e.bodyRoot;if(typeof l!="string"||l.length===0)return n("command_rest_invalid","bodyRoot must be a non-empty string",m(l),"a non-empty string key","Fix bodyRoot.",`${o}.bodyRoot`),null;P=l}for(const[l,v]of Object.entries(E)){const S=$.get(l);if((S.kind==="context-file"||(S.kind==="positional"||S.kind==="flag")&&S.type==="path")&&v.in!=="body"){const f=S.kind==="context-file"?"context-file":`path ${S.kind}`;return n("command_rest_invalid",`file param (${f}) must be placed in body`,`${l}: in "${v.in}"`,'in: "body"',"Move the file param to body.",`${o}.params.${l}.in`),null}}const q=new Map;for(const l of h)q.has(l.as)||q.set(l.as,[]),q.get(l.as).push({name:l.name,isStdin:l.isStdin});for(const[l,v]of q.entries())if(v.length>1){const S=v.filter(f=>f.isStdin).length,R=v.filter(f=>!f.isStdin).length;if(!(S===1&&R===1))return n("command_rest_invalid","invalid body as grouping",v.map(f=>f.name).join(", "),"exactly one stdin param and one non-stdin param may share a body as (for coalesced sources)","Fix the body grouping.",`${o}.params (as: "${l}")`),null}return{method:r,path:i,...g!==!1?{streaming:g}:{},...j!==void 0?{body:j}:{},...P!==void 0?{bodyRoot:P}:{},params:E}}_(he,"validateRestMapping");export{le as mentionsFile,D as outputBaseType,me as validateCommandNode};

package/dist/api/dto/analytics.d.ts

@@ -0,0 +1,184 @@
+export type AnalyticsWindow = '24h' | '7d';
+export interface AnalyticsQuery {
+    as_of: string;
+    window: AnalyticsWindow;
+    project?: string;
+}
+export type MeasureDTO<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    reason: string;
+};
+export interface AnalyticsDTO {
+    as_of: string;
+    window_start: string;
+    window: AnalyticsWindow;
+    project: string | null;
+    projects: Array<{
+        cwd: string;
+        api_price_estimate: number;
+    }>;
+    transcripts: {
+        total: number;
+        read: number;
+        unreadable: Array<{
+            node_id: string;
+            reason: 'file missing' | 'unreadable' | 'parse error';
+        }>;
+    } | null;
+    unknown_responses: number | null;
+    oldest_agent_created: string | null;
+    memory_log_started_at: string | null;
+    agents: AgentRowDTO[];
+    graphs: MeasureDTO<GraphsDTO>;
+    time: MeasureDTO<TimeDTO>;
+    usage: MeasureDTO<UsageDTO>;
+    memory: MeasureDTO<{
+        read: MemoryViewDTO;
+        loaded: MemoryViewDTO;
+    }>;
+}
+export interface AgentRowDTO {
+    node_id: string;
+    name: string;
+    kind: string;
+    graph_id: string;
+    in_graph_detail: boolean;
+    parent: string | null;
+    depth: number;
+    created: string;
+    finalized_at: string | null;
+    lifecycle: 'resident' | 'terminal';
+    active: boolean;
+    spawned_in_window: boolean;
+    finished_in_window: boolean;
+    agent_time_ms: number | null;
+    api_price_estimate: number;
+    tokens: number;
+    responses: number;
+    response_times_ms: number[];
+    final_report_ref: string | null;
+}
+export interface GraphRowDTO {
+    graph_id: string;
+    name: string;
+    root_deleted: boolean;
+    cwd: string;
+    root_kind: string;
+    root_lifecycle: 'resident' | 'terminal';
+    root_created: string;
+    active_agents: number;
+    depth: number;
+    api_price_estimate: number;
+    tokens: number;
+    spawned_kinds: string[];
+}
+export interface GraphsDTO {
+    count: number;
+    spawned: number;
+    deepest: number;
+    graphs: GraphRowDTO[];
+    size_buckets: Array<{
+        label: '1' | '2–5' | '6–10' | '11–20' | '21+';
+        graphs: number;
+    }>;
+    spawned_by_kind: Array<{
+        kind: string;
+        agents: number;
+    }>;
+}
+export interface DurationStatsDTO {
+    count: number;
+    p10_ms: number;
+    median_ms: number;
+    p90_ms: number;
+    max_ms: number;
+}
+export interface TimeDTO {
+    all: DurationStatsDTO | null;
+    by_kind: Array<{
+        kind: string;
+    } & DurationStatsDTO>;
+    activity: {
+        bucket_ms: number;
+        buckets: Array<{
+            start: string;
+            agents: number;
+        }>;
+        max: number;
+    };
+}
+export interface ModelKeyDTO {
+    provider: string;
+    model: string;
+}
+export interface ModelRowDTO extends ModelKeyDTO {
+    responses: number;
+    api_price_estimate: number;
+    tokens: number;
+    tokens_by_type: {
+        cache_read: number;
+        cache_write: number;
+        input: number;
+        output: number;
+    };
+    cache_read_share: number;
+    context: {
+        median: number;
+        p90: number;
+        max: number;
+        buckets: [number, number, number, number, number];
+    };
+}
+export interface UsageDTO {
+    api_price_estimate: number;
+    tokens: number;
+    median_context: number | null;
+    models: ModelRowDTO[];
+    legend: ModelKeyDTO[];
+    kinds: Array<{
+        kind: string;
+        api_price_estimate: number;
+        tokens: number;
+        responses_by_model: Array<ModelKeyDTO & {
+            responses: number;
+        }>;
+    }>;
+}
+export interface MemoryDocRowDTO {
+    name: string;
+    scope: string;
+    reads: number;
+    agents: number;
+    graphs: number;
+    readers_by_kind: Array<{
+        kind: string;
+        agents: number;
+    }>;
+    readers: Array<{
+        node_id: string;
+        kind: string;
+        name: string;
+        graph_id: string;
+        reads: number;
+        first_at: string;
+    }>;
+}
+export interface MemoryViewDTO {
+    entries: number;
+    documents: number;
+    agents_with_entry: number;
+    active_agents: number;
+    rows: MemoryDocRowDTO[];
+}
+export interface MemoryReadEventDTO {
+    name: string;
+    scope: string;
+    at: string;
+    type: 'read' | 'loaded';
+}
+export interface MemoryReadsRequestDTO {
+    events: MemoryReadEventDTO[];
+}

package/dist/api/dto/attach.d.ts

@@ -0,0 +1,22 @@
+import type { NodeIdDTO } from './common.js';
+/** `POST /v1/nodes/{id}/attach` body (local ensure). */
+export interface AttachEnsureRequest {
+    /** Resume saved history on revive (default true). */
+    resume?: boolean;
+    /** Revive if dormant (default true); false returns a possibly-dead socket. */
+    revive?: boolean;
+    /** Wake an exact unfinalized parked resident (default true). Focus/navigation
+     * sets false so it can open the saved conversation without launching. */
+    wakeParked?: boolean;
+}
+/** Result of a local attach-ensure. */
+export interface AttachEnsureResultDTO {
+    node_id: NodeIdDTO;
+    /** Host-local path to the node's broker `view.sock`. */
+    socket_path: string;
+    revived: boolean;
+    resumed: boolean;
+    /** True when a non-waking focus ensure found an exact parked resident with no
+     * live broker. `socket_path` is then the target the viewer will later redial. */
+    parked: boolean;
+}

package/dist/api/dto/bash-jobs.d.ts

@@ -0,0 +1,24 @@
+import type { IsoTime, NodeIdDTO } from './common.js';
+/** A still-live background bash job owned by one node. */
+export interface BashJobStatusDTO {
+    job_id: string;
+    command: string;
+    /** Human-readable label supplied with the bash call, or null when absent. */
+    purpose: string | null;
+    started_at: IsoTime;
+    elapsed_ms: number;
+    /** Persisted supervisor process group, or null for legacy jobs. */
+    pgid: number | null;
+    /** Whether the persisted process group currently exists. */
+    pgid_alive: boolean;
+}
+/** Result of stopping one background bash job. `signaled` is false when the
+ * process group had already exited, but the job is still retired via its exit
+ * sentinel. */
+export interface BashJobStopResultDTO {
+    node_id: NodeIdDTO;
+    job_id: string;
+    signaled: boolean;
+}
+/** Whether a job id is safe to interpolate as one API/filesystem segment. */
+export declare function isSafeBashJobId(jobId: string): boolean;

package/dist/api/dto/bash-jobs.js

@@ -0,0 +1 @@
+var n=Object.defineProperty;var e=(t,f)=>n(t,"name",{value:f,configurable:!0});function u(t){return typeof t=="string"&&t!==""&&t!=="."&&t!==".."&&/^[A-Za-z0-9._~-]+$/u.test(t)&&Buffer.byteLength(t,"utf8")<=128}e(u,"isSafeBashJobId");export{u as isSafeBashJobId};

package/dist/api/dto/bash.d.ts

@@ -0,0 +1,17 @@
+export interface BashRunParams {
+    command: string;
+    cwd: string;
+    timeout_s?: number;
+    env?: Record<string, string>;
+    profile?: string;
+}
+export interface BashRunDTO {
+    exit_code: number | null;
+    signal: string | null;
+    stdout: string;
+    stdout_truncated: boolean;
+    stderr: string;
+    stderr_truncated: boolean;
+    timed_out: boolean;
+    duration_ms: number;
+}

package/dist/api/dto/broker-ops.d.ts

@@ -0,0 +1,187 @@
+import type { ExitIntentDTO, NodeStatusDTO } from './common.js';
+import type { NodeSubjectDTO } from './nodes.js';
+/** `POST /v1/nodes/{id}/broker/session-bound` body. Pi's session-start reason
+ * distinguishes an ordinary boot/resume from `/new`, whose child-side session
+ * reset is a different durable operation. `reviewBoundaryIds` reports only the
+ * review markers visible in Pi's current branch; crtrd owns the node binding
+ * used to decide whether that branch is valid. */
+export interface BrokerSessionBoundRequest {
+    executionId: string;
+    piSessionId: string;
+    sessionFile: string | null;
+    pid: number;
+    reason: string | null;
+    reviewBoundaryIds: string[];
+}
+/** Pi-side consequence selected by crtrd after binding the session. The
+ * handler itself never calls back into the broker while servicing the request. */
+export interface BrokerSessionBoundResultDTO {
+    action: 'none' | 'relaunch_root' | 'shutdown';
+}
+/** `POST /v1/nodes/{id}/broker/settle` body. These are the facts only Pi can
+ * know at its settlement boundary; crtrd reads all current canvas state and
+ * selects the durable consequence. */
+export interface BrokerExecutionRequest {
+    expected_execution_id: string;
+}
+export interface BrokerSettleRequest extends BrokerExecutionRequest {
+    stopReason: string;
+    backgroundJobsRunning: boolean;
+    pushedFinal: boolean;
+}
+/** `POST /v1/nodes/{id}/broker/telemetry` body. Tokens are cumulative within
+ * the broker's current Pi session; null context/activity values preserve the
+ * last usable value in the daemon projection, matching telemetry.json. */
+export interface BrokerTelemetryRequest extends BrokerExecutionRequest {
+    tokens_in: number;
+    tokens_out: number;
+    model: string;
+    context_tokens: number | null;
+    last_activity: string | null;
+    updated_at: string;
+}
+/** The only consequence a settle caller may enact. crtrd has already committed
+ * every canvas and placement effect before returning this directive. */
+export type BrokerSettleDirective = {
+    action: 'reprompt';
+    prompt: string;
+} | {
+    action: 'stay_dormant';
+} | {
+    action: 'shutdown';
+};
+/** A main-engine input has won broker admission while a parking summary may be
+ * in flight. crtrd records it against the process-local pending marker before
+ * Pi begins the input, making parking completion and input admission atomic. */
+export interface BrokerParkActivityResultDTO {
+    activity: 'recorded' | 'none';
+}
+/** `POST /v1/nodes/{id}/broker/park-complete` body. The isolated parking turn
+ * has ended; crtrd alone decides whether its pending park still applies. */
+export interface BrokerParkCompleteRequest extends BrokerExecutionRequest {
+    outcome: 'completed' | 'failed';
+}
+/** Durable model recipe selected by the live broker after Pi accepts a model or thinking change. */
+export interface BrokerModelCommitRequest extends BrokerExecutionRequest {
+    spec: string;
+    /** Portable routing contract for a user-selected change; absent means exact. */
+    intent?: {
+        family: string;
+        strength: 'ultra' | 'strong' | 'medium' | 'light';
+    };
+    userSelected: boolean;
+}
+export interface BrokerModelCommitResultDTO {
+    modelOverride: string;
+}
+/** The dependency-light identity/runtime projection broker extensions need to
+ * render their local Pi hooks without reading canvas.db themselves. */
+export interface BrokerExtensionNodeDTO {
+    node_id: string;
+    grantee: string;
+    name: string;
+    description?: string;
+    title?: string;
+    icon?: string;
+    kind: string;
+    mode: 'base' | 'orchestrator';
+    lifecycle: 'terminal' | 'resident';
+    status: NodeStatusDTO;
+    cwd: string;
+    parent: string | null;
+    fork_from: string | null;
+    profile_id: string | null;
+    managed_worktree?: {
+        state: 'open' | 'closed' | 'abandoned';
+        cleanup?: 'pending' | 'complete';
+        path: string;
+        branch: string;
+        base_ref: string;
+        base_sha: string;
+    } | null;
+    review_binding?: {
+        kind?: 'review' | 'page_feedback';
+        review_id: string;
+        origin_node_id: string;
+        branch_file: string;
+        target_file: string;
+    } | null;
+    intent: ExitIntentDTO;
+    /** `kind` is absent on rows written before kind joined the drift key; a read
+     *  resolves it to the node's current kind. */
+    persona_ack?: {
+        kind?: string;
+        mode: 'base' | 'orchestrator';
+        lifecycle: 'terminal' | 'resident';
+    };
+    created: string;
+}
+export type BrokerExtensionSubjectDTO = NodeSubjectDTO;
+/** One resolved report sender. Report contents stay broker-local filesystem
+ * data; this daemon projection supplies only existence and display metadata. */
+export interface BrokerReportNodeDTO {
+    node_id: string;
+    grantee: string;
+    name: string;
+    created: string;
+}
+/** `GET /v1/nodes/{id}/broker/extension-state`. This is deliberately a fixed
+ * extension rendering projection, not a generic node/state read API. */
+export interface BrokerExtensionStateDTO {
+    node: BrokerExtensionNodeDTO;
+    warm_spare: boolean;
+    ancestors: BrokerExtensionNodeDTO[];
+    children: BrokerExtensionNodeDTO[];
+    fork_source: BrokerExtensionNodeDTO | null;
+    subject: BrokerExtensionSubjectDTO;
+    report_nodes: BrokerReportNodeDTO[];
+    /** The head body of the node's `roadmap` document, or null when it has none. */
+    roadmap: string | null;
+}
+/** Guarded generated-label update. `initial` can only fill a blank generated
+ * description; `recap` additionally compares the exact automatic-name snapshot
+ * captured before the headless naming call. */
+export type BrokerGeneratedNameRequest = BrokerExecutionRequest & ({
+    kind: 'initial';
+    description: string;
+    title: string;
+    icon: string;
+} | {
+    kind: 'recap';
+    description: string;
+    title: string;
+    icon: string;
+    expected: {
+        name: string;
+        description: string;
+        title: string;
+        icon: string;
+        kind: string;
+    };
+});
+/** A daemon-selected Pi editor-label directive. No handler calls a broker.
+ * `description`/`title`/`icon` are the values as STORED (an empty title or icon
+ * is left unset), so the broker announces what the node now carries rather than
+ * what it asked for. All four are present exactly when `applied`. */
+export interface BrokerGeneratedNameResultDTO {
+    applied: boolean;
+    editorLabel?: string;
+    description?: string;
+    title?: string;
+    icon?: string;
+}
+export interface BrokerPersonaAckRequest extends BrokerExecutionRequest {
+    from: {
+        kind: string;
+        mode: 'base' | 'orchestrator';
+        lifecycle: 'terminal' | 'resident';
+    };
+    to: {
+        kind: string;
+        mode: 'base' | 'orchestrator';
+        lifecycle: 'terminal' | 'resident';
+    };
+}
+export interface BrokerPersonaAckResultDTO {
+    applied: boolean;
+}

package/dist/api/dto/broker-signals.d.ts

@@ -0,0 +1,25 @@
+import type { BrokerExtensionNodeDTO } from './broker-ops.js';
+/** Ephemeral hints only; consumers resync from durable rows on every hello. */
+export type BrokerSignalLineDTO = {
+    type: 'hello';
+    epoch: string;
+    execution_id: string;
+    node: BrokerExtensionNodeDTO;
+    at: number;
+} | {
+    type: 'mail';
+    channel: 'wake';
+    at: number;
+} | {
+    type: 'node';
+    node: BrokerExtensionNodeDTO;
+    at: number;
+}
+/** The daemon found a pending provider retry with no live timer: re-run the broker's own retry scheduling. */
+ | {
+    type: 'fault-retry';
+    at: number;
+} | {
+    type: 'ping';
+    at: number;
+};