@north-light/plugin 0.3.461 → 0.3.463

package/dist/bundle.js

@@ -1,8 +1,8 @@
-var y=Object.defineProperty;var o=(n,t)=>y(n,"name",{value:t,configurable:!0});import{PluginDefinitionError as m}from"./define.js";import{buildCommandManifest as w}from"./manifest.js";const c=512,b=100,d=new TextEncoder;async function D(n,t){const e=w(n,{...t,mountPath:t.mountPath===""?"/":t.mountPath}),r=`${JSON.stringify(e,null,2)}
-`,a=`${JSON.stringify({bundleVersion:1,...n.version!==void 0?{version:n.version}:{}})}
-`,s=p(n.memory),f=[{path:"bundle.json",contents:a},{path:"commands.json",contents:r},...s],h=A(f),l=await B(h);return{commandsJson:r,bundleJson:a,memory:s,tar:h,etag:l}}o(D,"buildBundle");function p(n){const t=new Set;return n.map(e=>{const r=g(e);if(t.has(r))throw new m(`memory document "${e.name}" produces a duplicate tar member path ${r}`);return t.add(r),{path:r,contents:$(e)}})}o(p,"buildMemoryMembers");function g(n){if(n.name.includes("\0"))throw new m(`memory document "${n.name}" must not contain a NUL character`);const t=`memory/${n.name}.md`;if(d.encode(t).length>b)throw new m(`memory document "${n.name}" produces a tar member path longer than 100 bytes (${t}); shorten its name`);return t}o(g,"memoryMemberPath");function $(n){const t=[`kind: ${n.kind}`,`when-and-why-to-read: ${S(n.whenAndWhyToRead)}`];return n.unlisted===!0&&t.push("unlisted: true"),`---
-${t.join(`
+var y=Object.defineProperty;var o=(t,n)=>y(t,"name",{value:n,configurable:!0});import{PluginDefinitionError as u}from"./define.js";import{buildCommandManifest as p}from"./manifest.js";const c=512,b=100,d=new TextEncoder;async function P(t,n){const e=p(t,{...n,mountPath:n.mountPath===""?"/":n.mountPath}),r=`${JSON.stringify(e,null,2)}
+`,a=`${JSON.stringify({bundleVersion:1,...t.version!==void 0?{version:t.version}:{}})}
+`,s=w(t.memory),f=[{path:"bundle.json",contents:a},{path:"commands.json",contents:r},...s],h=E(f),l=await N(h);return{commandsJson:r,bundleJson:a,memory:s,tar:h,etag:l}}o(P,"buildBundle");function w(t){const n=new Set;return t.map(e=>{const r=g(e);if(n.has(r))throw new u(`memory document "${e.name}" produces a duplicate tar member path ${r}`);return n.add(r),{path:r,contents:$(e)}})}o(w,"buildMemoryMembers");function g(t){if(t.name.includes("\0"))throw new u(`memory document "${t.name}" must not contain a NUL character`);const n=`memory/${t.name}.md`;if(d.encode(n).length>b)throw new u(`memory document "${t.name}" produces a tar member path longer than 100 bytes (${n}); shorten its name`);return n}o(g,"memoryMemberPath");function $(t){const n=[`kind: ${t.kind}`,`when-and-why-to-read: ${x(t.whenAndWhyToRead)}`];return t.unlisted===!0&&n.push("unlisted: true"),t.rules!==void 0&&t.rules.length>0&&n.push(`surfaces: ${JSON.stringify(t.rules.map(A))}`),`---
+${n.join(`
 `)}
 ---
-${n.body}`}o($,"renderMemoryDoc");function S(n){let t='"';for(const e of n)switch(e){case"\\":t+="\\\\";break;case'"':t+='\\"';break;case`
-`:t+="\\n";break;case"	":t+="\\t";break;case"\r":t+="\\r";break;default:t+=e.charCodeAt(0)<=31||e==="\x7F"?`\\x${e.charCodeAt(0).toString(16).padStart(2,"0")}`:e}return`${t}"`}o(S,"yamlDoubleQuoted");function A(n){const t=[];for(const e of n){const r=d.encode(e.contents);t.push(k(e.path,r.length)),t.push(r);const a=x(r.length);a>0&&t.push(new Uint8Array(a))}return t.push(new Uint8Array(c)),t.push(new Uint8Array(c)),M(t)}o(A,"writeTar");function x(n){const t=n%c;return t===0?0:c-t}o(x,"padLength");function k(n,t){const e=new Uint8Array(c);return i(e,0,n),u(e,100,8,420),u(e,108,8,0),u(e,116,8,0),u(e,124,12,t),u(e,136,12,0),e.fill(32,148,156),e[156]=48,i(e,257,"ustar\0"),i(e,263,"00"),E(e,148,U(e)),e}o(k,"ustarHeader");function i(n,t,e){n.set(d.encode(e),t)}o(i,"writeAscii");function u(n,t,e,r){const a=e-1,s=r.toString(8).padStart(a,"0");if(s.length>a)throw new m(`tar header field at offset ${t} cannot hold value ${r} in ${a} octal digits`);i(n,t,s)}o(u,"writeOctalField");function E(n,t,e){i(n,t,e.toString(8).padStart(6,"0")),n[t+6]=0,n[t+7]=32}o(E,"writeChecksumField");function U(n){let t=0;for(const e of n)t+=e;return t}o(U,"sumBytes");function M(n){const t=n.reduce((a,s)=>a+s.length,0),e=new Uint8Array(t);let r=0;for(const a of n)e.set(a,r),r+=a.length;return e}o(M,"concatBytes");async function B(n){const t=new Uint8Array(await crypto.subtle.digest("SHA-256",n));return`"${Array.from(t,r=>r.toString(16).padStart(2,"0")).join("")}"`}o(B,"sha256Etag");export{D as buildBundle};
+${t.body}`}o($,"renderMemoryDoc");const S={boot:"boot","file-read":"read","document-read":"memory-read",command:"command","pre-command":"pre-command"};function A(t){return{on:S[t.on],at:t.deliver,...t.match!==void 0?{match:t.match}:{},...t.matchFrontmatter!==void 0?{"match-frontmatter":t.matchFrontmatter}:{},...t.if!==void 0?{gate:t.if}:{}}}o(A,"surfaceEntry");function x(t){let n='"';for(const e of t)switch(e){case"\\":n+="\\\\";break;case'"':n+='\\"';break;case`
+`:n+="\\n";break;case"	":n+="\\t";break;case"\r":n+="\\r";break;default:n+=e.charCodeAt(0)<=31||e==="\x7F"?`\\x${e.charCodeAt(0).toString(16).padStart(2,"0")}`:e}return`${n}"`}o(x,"yamlDoubleQuoted");function E(t){const n=[];for(const e of t){const r=d.encode(e.contents);n.push(U(e.path,r.length)),n.push(r);const a=k(r.length);a>0&&n.push(new Uint8Array(a))}return n.push(new Uint8Array(c)),n.push(new Uint8Array(c)),M(n)}o(E,"writeTar");function k(t){const n=t%c;return n===0?0:c-n}o(k,"padLength");function U(t,n){const e=new Uint8Array(c);return i(e,0,t),m(e,100,8,420),m(e,108,8,0),m(e,116,8,0),m(e,124,12,n),m(e,136,12,0),e.fill(32,148,156),e[156]=48,i(e,257,"ustar\0"),i(e,263,"00"),C(e,148,F(e)),e}o(U,"ustarHeader");function i(t,n,e){t.set(d.encode(e),n)}o(i,"writeAscii");function m(t,n,e,r){const a=e-1,s=r.toString(8).padStart(a,"0");if(s.length>a)throw new u(`tar header field at offset ${n} cannot hold value ${r} in ${a} octal digits`);i(t,n,s)}o(m,"writeOctalField");function C(t,n,e){i(t,n,e.toString(8).padStart(6,"0")),t[n+6]=0,t[n+7]=32}o(C,"writeChecksumField");function F(t){let n=0;for(const e of t)n+=e;return n}o(F,"sumBytes");function M(t){const n=t.reduce((a,s)=>a+s.length,0),e=new Uint8Array(n);let r=0;for(const a of t)e.set(a,r),r+=a.length;return e}o(M,"concatBytes");async function N(t){const n=new Uint8Array(await crypto.subtle.digest("SHA-256",t));return`"${Array.from(n,r=>r.toString(16).padStart(2,"0")).join("")}"`}o(N,"sha256Etag");export{P as buildBundle};

package/dist/define.d.ts

@@ -107,6 +107,29 @@ export interface MemoryDoc {
     readonly body: string;
     /** Keep the document out of listings, reachable only by name. */
     readonly unlisted?: boolean;
+    /** When the document loads on its own. Without rules it loads nowhere: an agent
+     *  reaches it only by reading it, a listing, or search. */
+    readonly rules?: readonly MemoryRule[];
+}
+/** Activities that can deliver a plugin document. `workspace-open` and slash
+ *  commands are absent: the first fires only for repo-owned documents, and a
+ *  plugin document is owned by the plugin's app. */
+export type MemoryRuleEvent = 'boot' | 'file-read' | 'document-read' | 'command' | 'pre-command';
+/** One delivery rule, in the vocabulary of `crtr doc write --rule`. `buildBundle`
+ *  writes it as a package-frontmatter `surfaces` entry. */
+export interface MemoryRule {
+    /** The receiving node's activity that fires the rule. */
+    readonly on: MemoryRuleEvent;
+    /** How much of the document is delivered: its name, its preview line, or its whole body. */
+    readonly deliver: 'name' | 'preview' | 'content';
+    /** Globs the activity must match; required on every event except `boot`, which takes none.
+     *  `file-read` may give `matchFrontmatter` instead. */
+    readonly match?: readonly string[];
+    /** `file-read` only: a field→matcher condition over the read file's YAML frontmatter. */
+    readonly matchFrontmatter?: Readonly<Record<string, unknown>>;
+    /** A field→matcher condition over the receiving node (`kind`, `mode`, `lifecycle`, `cwd`,
+     *  `repo`, `profile`, `depth`); the rule delivers only when it matches. */
+    readonly if?: Readonly<Record<string, unknown>>;
 }
 /** A validated, frozen plugin, as returned by `definePlugin`. */
 export interface PluginDefinition {

package/dist/define.js

@@ -1 +1 @@
-var w=Object.defineProperty;var r=(e,t)=>w(e,"name",{value:t,configurable:!0});import{mentionsFile as j,outputBaseType as c}from"@north-light/api/command-manifest";class f extends Error{static{r(this,"PluginDefinitionError")}constructor(t){super(t),this.name="PluginDefinitionError"}}function C(e){return{kind:"leaf",description:e.description,whenToUse:e.whenToUse,summary:e.summary,...e.tier!==void 0?{tier:e.tier}:{},...e.group!==void 0?{group:e.group}:{},...e.sideEffect!==void 0?{sideEffect:e.sideEffect}:{},params:e.params??{},output:e.output,effects:e.effects,streaming:!1,run:r((t,i)=>Promise.resolve(e.handler(t,i)),"run")}}r(C,"defineLeaf");function I(e){return{kind:"leaf",description:e.description,whenToUse:e.whenToUse,summary:e.summary,...e.tier!==void 0?{tier:e.tier}:{},...e.group!==void 0?{group:e.group}:{},...e.sideEffect!==void 0?{sideEffect:e.sideEffect}:{},params:e.params??{},output:e.output,effects:e.effects,streaming:!0,run:r((t,i)=>Promise.resolve(e.handler(t,i)),"run")}}r(I,"defineStreamingLeaf");function R(e){return{kind:"branch",...e}}r(R,"defineBranch");function S(e){if(A(e.name,"plugin name"),a(e.description,"plugin description"),a(e.whenToUse,"plugin whenToUse"),a(e.summary,"plugin summary"),a(e.rootEntry?.concept,"plugin rootEntry.concept"),a(e.rootEntry?.description,"plugin rootEntry.description"),a(e.rootEntry?.whenToUse,"plugin rootEntry.whenToUse"),T(e.timeouts),e.version!==void 0&&(typeof e.version!="number"||!Number.isInteger(e.version)||e.version<1))throw new f("plugin version must be an integer of at least 1");if(e.provider!==void 0&&typeof e.provider!="boolean")throw new f("plugin provider must be a boolean");if(e.provider===!0&&e.version===void 0)throw new f("a provider plugin must declare its major version");for(const[t,i]of Object.entries(e.commands))p(i,[e.name,t]);if(e.provider===!0){const t=y(e.commands,[e.name]);t!==void 0&&n(t,"needs a group because the plugin is a provider")}for(const t of e.memory??[])E(t);return Object.freeze({name:e.name,description:e.description,whenToUse:e.whenToUse,summary:e.summary,rootEntry:Object.freeze({...e.rootEntry}),commands:b(e.commands),memory:Object.freeze((e.memory??[]).map(t=>Object.freeze({...t}))),...e.timeouts!==void 0?{timeouts:Object.freeze({...e.timeouts})}:{},...e.version!==void 0?{version:e.version}:{},...e.provider!==void 0?{provider:e.provider}:{}})}r(S,"definePlugin");function y(e,t){for(const[i,s]of Object.entries(e)){const o=[...t,i];if(s.kind==="leaf"){if(s.group===void 0)return o;continue}const u=y(s.children,o);if(u!==void 0)return u}}r(y,"firstLeafWithoutGroup");function b(e){return Object.freeze(Object.fromEntries(Object.entries(e).map(([t,i])=>[t,O(i)])))}r(b,"snapshotCommands");function O(e){return e.kind==="branch"?Object.freeze({kind:"branch",description:e.description,whenToUse:e.whenToUse,summary:e.summary,...e.tier!==void 0?{tier:e.tier}:{},children:b(e.children)}):Object.freeze({kind:"leaf",description:e.description,whenToUse:e.whenToUse,summary:e.summary,...e.tier!==void 0?{tier:e.tier}:{},params:k(e.params),output:g(e.output),effects:Object.freeze([...e.effects]),streaming:e.streaming,...e.group!==void 0?{group:e.group}:{},...e.sideEffect!==void 0?{sideEffect:e.sideEffect}:{},run:e.run})}r(O,"snapshotNode");function k(e){return Object.freeze(Object.fromEntries(Object.entries(e).map(([t,i])=>[t,$(i)])))}r(k,"snapshotParams");function $(e){return e.kind==="flag"&&e.type==="enum"?Object.freeze({...e,choices:Object.freeze([...e.choices])}):Object.freeze({...e})}r($,"snapshotParam");function g(e){return Object.freeze(Object.fromEntries(Object.entries(e).map(([t,i])=>[t,h(i)])))}r(g,"snapshotOutput");function h(e){return Object.freeze({...e,...e.children!==void 0?{children:g(e.children)}:{},...e.items!==void 0?{items:h(e.items)}:{},...e.values!==void 0?{values:Object.freeze([...e.values])}:{}})}r(h,"snapshotField");function p(e,t){(!d(e)||e.kind!=="branch"&&e.kind!=="leaf")&&n(t,"must be a branch or leaf defined by this package"),a(e.description,`${m(t)} description`),a(e.whenToUse,`${m(t)} whenToUse`),a(e.summary,`${m(t)} summary`),e.tier!==void 0&&e.tier!=="normal"&&e.tier!=="common"&&e.tier!=="important"&&n(t,"tier must be normal, common, or important");const i=t.at(-1);if(i===void 0&&n(t,"has no command name"),v(i,`${m(t)} command key`),e.kind==="branch"){d(e.children)||n(t,"branch children must be an object");for(const[o,u]of Object.entries(e.children))p(u,[...t,o]);return}e.group!==void 0&&(typeof e.group!="string"||!U.test(e.group))&&n(t,`group ${JSON.stringify(e.group)} must match [A-Za-z0-9_-]{1,64}`),e.sideEffect!==void 0&&typeof e.sideEffect!="boolean"&&n(t,"sideEffect must be a boolean"),d(e.params)||n(t,"leaf params must be an object");for(const[o,u]of Object.entries(e.params))v(o,`${m(t)} parameter key`),z(u,[...t,`parameter ${o}`]);Object.values(e.params).filter(o=>d(o)&&o.kind==="positional").length>1&&n(t,"a leaf may have at most one positional parameter"),d(e.output)||n(t,"leaf output must be an object");let s;for(const[o,u]of Object.entries(e.output))o.length===0&&n(t,"output field names must not be empty"),l(u,[...t,`output ${o}`],!0),c(u.type)==="file"&&(s!==void 0&&n(t,`declares file outputs ${s} and ${o}; a leaf may declare at most one file output`),s=o);(!Array.isArray(e.effects)||e.effects.length===0||!e.effects.every(o=>typeof o=="string"))&&n(t,"leaf effects must be a non-empty array of strings"),typeof e.streaming!="boolean"&&n(t,"leaf streaming must be a boolean"),typeof e.run!="function"&&n(t,"leaf handler must be a function")}r(p,"validateNode");function z(e,t){if((!d(e)||e.kind!=="flag"&&e.kind!=="positional"&&e.kind!=="stdin")&&n(t,"must be a parameter descriptor produced by param.*"),a(e.constraint,`${m(t)} constraint`),(typeof e.required!="boolean"||typeof e.repeatable!="boolean")&&n(t,"required and repeatable must be booleans"),e.kind==="stdin"){e.repeatable&&n(t,"stdin cannot be repeatable"),Object.hasOwn(e,"default")&&n(t,"stdin parameters cannot have a default");return}if(e.kind==="positional"){e.type!=="string"&&n(t,"positional parameters must have type string"),Object.hasOwn(e,"default")&&n(t,"positional parameters cannot have a default");return}if(e.type==="enum"?(!Array.isArray(e.choices)||e.choices.length===0||!e.choices.every(s=>typeof s=="string"))&&n(t,"enum parameters need at least one string choice"):e.type!=="string"&&e.type!=="int"&&e.type!=="bool"&&e.type!=="path"&&e.type!=="file"&&n(t,"flag parameters must have a supported type"),(e.type==="bool"||e.type==="path"||e.type==="file")&&e.repeatable&&n(t,`${e.type} parameters cannot be repeatable`),e.type==="path"&&e.encoding!=="text"&&e.encoding!=="base64"&&n(t,"path parameters must have text or base64 encoding"),e.type!=="path"&&e.encoding!==void 0&&n(t,"encoding is only valid on path parameters"),e.repeatable&&Object.hasOwn(e,"default")&&n(t,"repeatable parameters cannot have a default"),!Object.hasOwn(e,"default"))return;const i=e.default;e.type==="string"&&typeof i!="string"&&n(t,"string parameter defaults must be strings"),e.type==="int"&&(typeof i!="number"||!Number.isInteger(i))&&n(t,"int parameter defaults must be integers"),e.type==="bool"&&typeof i!="boolean"&&n(t,"bool parameter defaults must be booleans"),e.type==="enum"&&(typeof i!="string"||!Array.isArray(e.choices)||!e.choices.includes(i))&&n(t,"enum parameter defaults must be one of their choices"),(e.type==="path"||e.type==="file")&&n(t,`${e.type} parameters cannot have a default`)}r(z,"validateParam");function l(e,t,i){(!d(e)||typeof e.type!="string"||e.type.length===0||typeof e.constraint!="string"||typeof e.required!="boolean")&&n(t,"must be an output field descriptor produced by field.*");const s=c(e.type);if(e.kind!==void 0&&s!=="file"&&n(t,"is a parameter descriptor; declare output fields with field.*"),j(e.type)&&s!=="file"&&n(t,`has type ${e.type}; a file output is one file, declared file or file | null`),s==="file"&&!i&&n(t,"is a file, which is only valid as a top-level output field"),e.children!==void 0){s!=="object"&&n(t,"children are only valid on an object field"),d(e.children)||n(t,"children must be an object of output fields");for(const[o,u]of Object.entries(e.children))o.length===0&&n(t,"member names must not be empty"),l(u,[...t,`member ${o}`],!1)}e.items!==void 0&&(s!=="array"&&n(t,"items are only valid on an array field"),l(e.items,[...t,"items"],!1)),e.values!==void 0&&(s!=="enum"&&n(t,"values are only valid on an enum field"),(!Array.isArray(e.values)||e.values.length===0||!e.values.every(o=>typeof o=="string"&&o.length>0))&&n(t,"enum values must be a non-empty array of non-empty strings"),new Set(e.values).size!==e.values.length&&n(t,"enum values must be unique"))}r(l,"validateField");function E(e){if(!d(e)||typeof e.name!="string"||!x(e.name))throw new f("memory document name must be a safe relative path");if(e.kind!=="knowledge"&&e.kind!=="preference")throw new f(`memory document ${e.name} has an invalid kind`);if(a(e.whenAndWhyToRead,`memory document ${e.name} whenAndWhyToRead`),typeof e.body!="string")throw new f(`memory document ${e.name} body must be a string`);if(e.unlisted!==void 0&&typeof e.unlisted!="boolean")throw new f(`memory document ${e.name} unlisted must be a boolean`)}r(E,"validateMemoryDoc");function T(e){if(e!==void 0){if(!d(e))throw new f("timeouts must be an object");for(const t of["connectMs","requestMs","streamIdleMs"]){const i=e[t];if(i!==void 0&&(typeof i!="number"||!Number.isInteger(i)||i<=0))throw new f(`timeouts.${t} must be a positive integer`)}}}r(T,"assertTimeouts");const U=/^[A-Za-z0-9_-]{1,64}$/;function v(e,t){if(P(e).replace(/-([a-z])/g,(s,o)=>o.toUpperCase())!==e)throw new f(`${t} must round-trip between camelCase and kebab-case`)}r(v,"assertKey");function A(e,t){if(!/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/.test(e))throw new f(`${t} must be lowercase kebab-case`)}r(A,"assertKebabName");function P(e){const t=e.replace(/[A-Z]/g,i=>`-${i.toLowerCase()}`);if(!/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/.test(t))throw new f(`invalid key ${JSON.stringify(e)}; use camelCase keys that convert to lowercase kebab-case`);return t}r(P,"kebab");function a(e,t){if(typeof e!="string"||e.length===0)throw new f(`${t} must be a non-empty string`)}r(a,"assertText");function x(e){return e.length>0&&!e.startsWith("/")&&!e.includes("\\")&&e.split("/").every(t=>t.length>0&&t!=="."&&t!=="..")}r(x,"isSafeRelativePath");function d(e){return typeof e=="object"&&e!==null&&!Array.isArray(e)}r(d,"isRecord");function n(e,t){throw new f(`${m(e)} ${t}`)}r(n,"fail");function m(e){return e.join(" ")}r(m,"formatPath");export{f as PluginDefinitionError,R as defineBranch,C as defineLeaf,S as definePlugin,I as defineStreamingLeaf,P as kebab};
+var k=Object.defineProperty;var r=(e,t)=>k(e,"name",{value:t,configurable:!0});import{mentionsFile as E,outputBaseType as l}from"@north-light/api/command-manifest";class s extends Error{static{r(this,"PluginDefinitionError")}constructor(t){super(t),this.name="PluginDefinitionError"}}function q(e){return{kind:"leaf",description:e.description,whenToUse:e.whenToUse,summary:e.summary,...e.tier!==void 0?{tier:e.tier}:{},...e.group!==void 0?{group:e.group}:{},...e.sideEffect!==void 0?{sideEffect:e.sideEffect}:{},params:e.params??{},output:e.output,effects:e.effects,streaming:!1,run:r((t,n)=>Promise.resolve(e.handler(t,n)),"run")}}r(q,"defineLeaf");function D(e){return{kind:"leaf",description:e.description,whenToUse:e.whenToUse,summary:e.summary,...e.tier!==void 0?{tier:e.tier}:{},...e.group!==void 0?{group:e.group}:{},...e.sideEffect!==void 0?{sideEffect:e.sideEffect}:{},params:e.params??{},output:e.output,effects:e.effects,streaming:!0,run:r((t,n)=>Promise.resolve(e.handler(t,n)),"run")}}r(D,"defineStreamingLeaf");function I(e){return{kind:"branch",...e}}r(I,"defineBranch");function K(e){if(R(e.name,"plugin name"),m(e.description,"plugin description"),m(e.whenToUse,"plugin whenToUse"),m(e.summary,"plugin summary"),m(e.rootEntry?.concept,"plugin rootEntry.concept"),m(e.rootEntry?.description,"plugin rootEntry.description"),m(e.rootEntry?.whenToUse,"plugin rootEntry.whenToUse"),M(e.timeouts),e.version!==void 0&&(typeof e.version!="number"||!Number.isInteger(e.version)||e.version<1))throw new s("plugin version must be an integer of at least 1");if(e.provider!==void 0&&typeof e.provider!="boolean")throw new s("plugin provider must be a boolean");if(e.provider===!0&&e.version===void 0)throw new s("a provider plugin must declare its major version");for(const[t,n]of Object.entries(e.commands))w(n,[e.name,t]);if(e.provider===!0){const t=b(e.commands,[e.name]);t!==void 0&&i(t,"needs a group because the plugin is a provider")}for(const t of e.memory??[])P(t);return Object.freeze({name:e.name,description:e.description,whenToUse:e.whenToUse,summary:e.summary,rootEntry:Object.freeze({...e.rootEntry}),commands:h(e.commands),memory:Object.freeze((e.memory??[]).map(x)),...e.timeouts!==void 0?{timeouts:Object.freeze({...e.timeouts})}:{},...e.version!==void 0?{version:e.version}:{},...e.provider!==void 0?{provider:e.provider}:{}})}r(K,"definePlugin");function b(e,t){for(const[n,f]of Object.entries(e)){const o=[...t,n];if(f.kind==="leaf"){if(f.group===void 0)return o;continue}const a=b(f.children,o);if(a!==void 0)return a}}r(b,"firstLeafWithoutGroup");function h(e){return Object.freeze(Object.fromEntries(Object.entries(e).map(([t,n])=>[t,z(n)])))}r(h,"snapshotCommands");function z(e){return e.kind==="branch"?Object.freeze({kind:"branch",description:e.description,whenToUse:e.whenToUse,summary:e.summary,...e.tier!==void 0?{tier:e.tier}:{},children:h(e.children)}):Object.freeze({kind:"leaf",description:e.description,whenToUse:e.whenToUse,summary:e.summary,...e.tier!==void 0?{tier:e.tier}:{},params:T(e.params),output:g(e.output),effects:Object.freeze([...e.effects]),streaming:e.streaming,...e.group!==void 0?{group:e.group}:{},...e.sideEffect!==void 0?{sideEffect:e.sideEffect}:{},run:e.run})}r(z,"snapshotNode");function T(e){return Object.freeze(Object.fromEntries(Object.entries(e).map(([t,n])=>[t,A(n)])))}r(T,"snapshotParams");function A(e){return e.kind==="flag"&&e.type==="enum"?Object.freeze({...e,choices:Object.freeze([...e.choices])}):Object.freeze({...e})}r(A,"snapshotParam");function g(e){return Object.freeze(Object.fromEntries(Object.entries(e).map(([t,n])=>[t,p(n)])))}r(g,"snapshotOutput");function p(e){return Object.freeze({...e,...e.children!==void 0?{children:g(e.children)}:{},...e.items!==void 0?{items:p(e.items)}:{},...e.values!==void 0?{values:Object.freeze([...e.values])}:{}})}r(p,"snapshotField");function w(e,t){(!u(e)||e.kind!=="branch"&&e.kind!=="leaf")&&i(t,"must be a branch or leaf defined by this package"),m(e.description,`${d(t)} description`),m(e.whenToUse,`${d(t)} whenToUse`),m(e.summary,`${d(t)} summary`),e.tier!==void 0&&e.tier!=="normal"&&e.tier!=="common"&&e.tier!=="important"&&i(t,"tier must be normal, common, or important");const n=t.at(-1);if(n===void 0&&i(t,"has no command name"),$(n,`${d(t)} command key`),e.kind==="branch"){u(e.children)||i(t,"branch children must be an object");for(const[o,a]of Object.entries(e.children))w(a,[...t,o]);return}e.group!==void 0&&(typeof e.group!="string"||!N.test(e.group))&&i(t,`group ${JSON.stringify(e.group)} must match [A-Za-z0-9_-]{1,64}`),e.sideEffect!==void 0&&typeof e.sideEffect!="boolean"&&i(t,"sideEffect must be a boolean"),u(e.params)||i(t,"leaf params must be an object");for(const[o,a]of Object.entries(e.params))$(o,`${d(t)} parameter key`),U(a,[...t,`parameter ${o}`]);Object.values(e.params).filter(o=>u(o)&&o.kind==="positional").length>1&&i(t,"a leaf may have at most one positional parameter"),u(e.output)||i(t,"leaf output must be an object");let f;for(const[o,a]of Object.entries(e.output))o.length===0&&i(t,"output field names must not be empty"),c(a,[...t,`output ${o}`],!0),l(a.type)==="file"&&(f!==void 0&&i(t,`declares file outputs ${f} and ${o}; a leaf may declare at most one file output`),f=o);(!Array.isArray(e.effects)||e.effects.length===0||!e.effects.every(o=>typeof o=="string"))&&i(t,"leaf effects must be a non-empty array of strings"),typeof e.streaming!="boolean"&&i(t,"leaf streaming must be a boolean"),typeof e.run!="function"&&i(t,"leaf handler must be a function")}r(w,"validateNode");function U(e,t){if((!u(e)||e.kind!=="flag"&&e.kind!=="positional"&&e.kind!=="stdin")&&i(t,"must be a parameter descriptor produced by param.*"),m(e.constraint,`${d(t)} constraint`),(typeof e.required!="boolean"||typeof e.repeatable!="boolean")&&i(t,"required and repeatable must be booleans"),e.kind==="stdin"){e.repeatable&&i(t,"stdin cannot be repeatable"),Object.hasOwn(e,"default")&&i(t,"stdin parameters cannot have a default");return}if(e.kind==="positional"){e.type!=="string"&&i(t,"positional parameters must have type string"),Object.hasOwn(e,"default")&&i(t,"positional parameters cannot have a default");return}if(e.type==="enum"?(!Array.isArray(e.choices)||e.choices.length===0||!e.choices.every(f=>typeof f=="string"))&&i(t,"enum parameters need at least one string choice"):e.type!=="string"&&e.type!=="int"&&e.type!=="bool"&&e.type!=="path"&&e.type!=="file"&&i(t,"flag parameters must have a supported type"),(e.type==="bool"||e.type==="path"||e.type==="file")&&e.repeatable&&i(t,`${e.type} parameters cannot be repeatable`),e.type==="path"&&e.encoding!=="text"&&e.encoding!=="base64"&&i(t,"path parameters must have text or base64 encoding"),e.type!=="path"&&e.encoding!==void 0&&i(t,"encoding is only valid on path parameters"),e.repeatable&&Object.hasOwn(e,"default")&&i(t,"repeatable parameters cannot have a default"),!Object.hasOwn(e,"default"))return;const n=e.default;e.type==="string"&&typeof n!="string"&&i(t,"string parameter defaults must be strings"),e.type==="int"&&(typeof n!="number"||!Number.isInteger(n))&&i(t,"int parameter defaults must be integers"),e.type==="bool"&&typeof n!="boolean"&&i(t,"bool parameter defaults must be booleans"),e.type==="enum"&&(typeof n!="string"||!Array.isArray(e.choices)||!e.choices.includes(n))&&i(t,"enum parameter defaults must be one of their choices"),(e.type==="path"||e.type==="file")&&i(t,`${e.type} parameters cannot have a default`)}r(U,"validateParam");function c(e,t,n){(!u(e)||typeof e.type!="string"||e.type.length===0||typeof e.constraint!="string"||typeof e.required!="boolean")&&i(t,"must be an output field descriptor produced by field.*");const f=l(e.type);if(e.kind!==void 0&&f!=="file"&&i(t,"is a parameter descriptor; declare output fields with field.*"),E(e.type)&&f!=="file"&&i(t,`has type ${e.type}; a file output is one file, declared file or file | null`),f==="file"&&!n&&i(t,"is a file, which is only valid as a top-level output field"),e.children!==void 0){f!=="object"&&i(t,"children are only valid on an object field"),u(e.children)||i(t,"children must be an object of output fields");for(const[o,a]of Object.entries(e.children))o.length===0&&i(t,"member names must not be empty"),c(a,[...t,`member ${o}`],!1)}e.items!==void 0&&(f!=="array"&&i(t,"items are only valid on an array field"),c(e.items,[...t,"items"],!1)),e.values!==void 0&&(f!=="enum"&&i(t,"values are only valid on an enum field"),(!Array.isArray(e.values)||e.values.length===0||!e.values.every(o=>typeof o=="string"&&o.length>0))&&i(t,"enum values must be a non-empty array of non-empty strings"),new Set(e.values).size!==e.values.length&&i(t,"enum values must be unique"))}r(c,"validateField");function P(e){if(!u(e)||typeof e.name!="string"||!C(e.name))throw new s("memory document name must be a safe relative path");if(e.kind!=="knowledge"&&e.kind!=="preference")throw new s(`memory document ${e.name} has an invalid kind`);if(m(e.whenAndWhyToRead,`memory document ${e.name} whenAndWhyToRead`),typeof e.body!="string")throw new s(`memory document ${e.name} body must be a string`);if(e.unlisted!==void 0&&typeof e.unlisted!="boolean")throw new s(`memory document ${e.name} unlisted must be a boolean`);if(e.rules!==void 0){if(!Array.isArray(e.rules))throw new s(`memory document ${e.name} rules must be an array`);e.rules.forEach((t,n)=>F(t,`memory document ${e.name} rules[${n}]`))}}r(P,"validateMemoryDoc");const v=["boot","file-read","document-read","command","pre-command"],j=["on","deliver","match","matchFrontmatter","if"];function F(e,t){if(!u(e))throw new s(`${t} must be an object`);for(const n of Object.keys(e))if(!j.includes(n))throw new s(`${t} has unknown key ${n}; a rule carries only ${j.join(", ")}`);if(typeof e.on!="string"||!v.includes(e.on))throw new s(`${t} on must be one of ${v.join(", ")}`);if(e.deliver!=="name"&&e.deliver!=="preview"&&e.deliver!=="content")throw new s(`${t} deliver must be name, preview or content`);if(e.match!==void 0){if(e.on==="boot")throw new s(`${t} match is meaningless on boot; drop it`);if(!Array.isArray(e.match)||e.match.length===0||!e.match.every(n=>typeof n=="string"&&n.trim().length>0))throw new s(`${t} match must be a non-empty array of non-empty globs`)}if(e.matchFrontmatter!==void 0){if(e.on!=="file-read")throw new s(`${t} matchFrontmatter applies only to file-read`);O(e.matchFrontmatter,`${t} matchFrontmatter`)}if(e.on!=="boot"&&e.match===void 0&&e.matchFrontmatter===void 0)throw new s(`${t} needs match${e.on==="file-read"?" or matchFrontmatter":""} on ${e.on}`);e.if!==void 0&&O(e.if,`${t} if`)}r(F,"validateMemoryRule");function O(e,t){if(!u(e))throw new s(`${t} must be a field\u2192matcher object`);if(!y(e,0))throw new s(`${t} must hold only strings, finite numbers, booleans, null, arrays and plain objects`)}r(O,"assertCondition");function y(e,t){return t>32?!1:e===null||typeof e=="string"||typeof e=="boolean"?!0:typeof e=="number"?Number.isFinite(e):Array.isArray(e)?e.every(n=>y(n,t+1)):!u(e)||Object.getPrototypeOf(e)!==Object.prototype&&Object.getPrototypeOf(e)!==null?!1:Object.values(e).every(n=>y(n,t+1))}r(y,"isPlainJson");function x(e){const{rules:t,...n}=e;return Object.freeze({...n,...t!==void 0?{rules:Object.freeze(t.map(f=>structuredClone(f)))}:{}})}r(x,"freezeMemoryDoc");function M(e){if(e!==void 0){if(!u(e))throw new s("timeouts must be an object");for(const t of["connectMs","requestMs","streamIdleMs"]){const n=e[t];if(n!==void 0&&(typeof n!="number"||!Number.isInteger(n)||n<=0))throw new s(`timeouts.${t} must be a positive integer`)}}}r(M,"assertTimeouts");const N=/^[A-Za-z0-9_-]{1,64}$/;function $(e,t){if(_(e).replace(/-([a-z])/g,(f,o)=>o.toUpperCase())!==e)throw new s(`${t} must round-trip between camelCase and kebab-case`)}r($,"assertKey");function R(e,t){if(!/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/.test(e))throw new s(`${t} must be lowercase kebab-case`)}r(R,"assertKebabName");function _(e){const t=e.replace(/[A-Z]/g,n=>`-${n.toLowerCase()}`);if(!/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/.test(t))throw new s(`invalid key ${JSON.stringify(e)}; use camelCase keys that convert to lowercase kebab-case`);return t}r(_,"kebab");function m(e,t){if(typeof e!="string"||e.length===0)throw new s(`${t} must be a non-empty string`)}r(m,"assertText");function C(e){return e.length>0&&!e.startsWith("/")&&!e.includes("\\")&&e.split("/").every(t=>t.length>0&&t!=="."&&t!=="..")}r(C,"isSafeRelativePath");function u(e){return typeof e=="object"&&e!==null&&!Array.isArray(e)}r(u,"isRecord");function i(e,t){throw new s(`${d(e)} ${t}`)}r(i,"fail");function d(e){return e.join(" ")}r(d,"formatPath");export{s as PluginDefinitionError,I as defineBranch,q as defineLeaf,K as definePlugin,D as defineStreamingLeaf,_ as kebab};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/plugin",
-  "version": "0.3.461",
+  "version": "0.3.463",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -23,8 +23,8 @@
     "postpack": "node ../../scripts/pack-minify.mjs postpack packages/crouter-plugin"
   },
   "dependencies": {
-    "@north-light/api": "0.3.461",
-    "@north-light/identity": "0.3.461"
+    "@north-light/api": "0.3.463",
+    "@north-light/identity": "0.3.463"
   },
   "license": "UNLICENSED",
   "publishConfig": {