@north-light/cli 0.0.0-stage → 0.3.413

package/dist/core/command-hooks/artifact.js

@@ -0,0 +1 @@
+var y=Object.defineProperty;var r=(a,i)=>y(a,"name",{value:i,configurable:!0});import{readFileSync as g,realpathSync as f,statSync as k}from"node:fs";import{isAbsolute as b,resolve as m,sep as v}from"node:path";import{validateHookManifest as E}from"./schema.js";function _(a){if(typeof a!="object"||a===null||Array.isArray(a))return[];const i=a.lifecycle;return Array.isArray(i)?i.flatMap((t,o)=>{if(typeof t!="object"||t===null||Array.isArray(t))return[];const e=t;return typeof e.event=="string"?[{event:e.event,op:typeof e.op=="string"?e.op:"<invalid>",index:o}]:[]}):[]}r(_,"lifecycleCandidates");function x(a,i){if(b(i))return null;try{const t=f(a),o=f(m(a,i));return(o===t||o.startsWith(t+v))&&k(o).isFile()?o:null}catch{return null}}r(x,"safeFilePath");function P(a,i){const t=i.hooks,o=i.hookExecutable,e=[],l=t!==void 0;if(l!==(o!==void 0))return e.push({code:"hook_manifest_invalid",path:l?"hookExecutable":"hooks",message:"hooks and hookExecutable must be declared together",received:l?"hooks without hookExecutable":"hookExecutable without hooks",expected:"both hooks and hookExecutable",next:l?"Add plugin.json.hookExecutable or remove hooks.":"Add plugin.json.hooks or remove hookExecutable."}),{lifecycleCandidates:[],issues:e};if(!l)return{lifecycleCandidates:[],issues:e};if((typeof t!="string"||t.length===0)&&e.push({code:"hook_manifest_invalid",path:"hooks",message:"hooks must be a non-empty plugin-root-relative path",received:typeof t=="string"?"(empty)":Array.isArray(t)?"array":typeof t,expected:"a non-empty relative path to hooks.json",next:"Fix plugin.json.hooks."}),(typeof o!="string"||o.length===0)&&e.push({code:"hook_manifest_invalid",path:"hookExecutable",message:"hookExecutable must be a non-empty plugin-root-relative path",received:typeof o=="string"?"(empty)":Array.isArray(o)?"array":typeof o,expected:"a non-empty relative path to an executable file",next:"Fix plugin.json.hookExecutable."}),e.length>0)return{lifecycleCandidates:[],issues:e};const p=t,c=o,s=x(a,p);s===null&&e.push({code:"hook_path_unsafe",path:"hooks",message:"hooks pointer escapes the plugin root or is not a regular file",received:p,expected:"a relative path to a regular file inside the plugin root",next:"Fix plugin.json.hooks."});const n=x(a,c);if(n===null&&e.push({code:"hook_path_unsafe",path:"hookExecutable",message:"hookExecutable escapes the plugin root or is not a regular file",received:c,expected:"a relative path to a regular file inside the plugin root",next:"Fix plugin.json.hookExecutable."}),n!==null&&(k(n).mode&73)===0&&e.push({code:"hook_not_executable",path:"hookExecutable",message:"hookExecutable lacks the POSIX exec bit",received:c,expected:"a file with an executable permission bit",next:"chmod +x the hook executable, then update the plugin."}),s===null)return{lifecycleCandidates:[],...n===null?{}:{executablePath:n},issues:e};let d;try{d=g(s,"utf8")}catch{return e.push({code:"hook_manifest_unreadable",message:"hooks.json is missing or unreadable",received:s,expected:"a readable JSON file",next:"Reinstall or update the plugin."}),{manifestPath:s,lifecycleCandidates:[],...n===null?{}:{executablePath:n},issues:e}}let u;try{u=JSON.parse(d)}catch{return e.push({code:"hook_manifest_invalid",message:"hooks.json is not valid JSON",received:s,expected:"a JSON object",next:"Regenerate hooks.json."}),{manifestPath:s,lifecycleCandidates:[],...n===null?{}:{executablePath:n},issues:e}}const h=E(u);return{manifestPath:s,lifecycleCandidates:_(u),...n===null?{}:{executablePath:n},...h.manifest===void 0?{}:{manifest:h.manifest},issues:[...e,...h.issues]}}r(P,"validatePluginHookArtifact");export{P as validatePluginHookArtifact};

package/dist/core/command-hooks/catalog.d.ts

@@ -0,0 +1,14 @@
+import type { BranchDef, LeafDef } from '../command.js';
+export interface CoreHookTarget {
+    /** Exact space-joined core leaf path named by hooks.json. */
+    path: string;
+    segments: readonly string[];
+    leaf: LeafDef;
+}
+export interface CoreHookCatalog {
+    targets: readonly CoreHookTarget[];
+    byPath: ReadonlyMap<string, CoreHookTarget>;
+    has(path: string): boolean;
+}
+/** Projects every composed core subtree to leaves whose objects flow through central rendering. */
+export declare function createCoreHookCatalog(subtrees: readonly BranchDef[]): CoreHookCatalog;

package/dist/core/command-hooks/catalog.js

@@ -0,0 +1 @@
+var u=Object.defineProperty;var r=(t,s)=>u(t,"name",{value:s,configurable:!0});const p=new Set(["pkg browse","sys settings","sys setup","canvas browse","surface inspect"]);function f(t){return t==="sys doctor"||t==="pkg plugin"||t.startsWith("pkg plugin ")||p.has(t)}r(f,"excluded");function h(t){const s=[],c=r((e,n)=>{const o=n.join(" ");if(e.kind==="leaf"){e.help.outputKind==="object"&&e.hookEligible!==!1&&!f(o)&&s.push({path:o,segments:Object.freeze([...n]),leaf:e});return}if(!(e.passthrough!==void 0||f(o)))for(const a of e.children)c(a,[...n,a.name])},"visit");for(const e of t)c(e,[e.name]);const i=new Map(s.map(e=>[e.path,e]));return Object.freeze({targets:Object.freeze(s),byPath:i,has:r(e=>i.has(e),"has")})}r(h,"createCoreHookCatalog");export{h as createCoreHookCatalog};

package/dist/core/command-hooks/compose.d.ts

@@ -0,0 +1,15 @@
+import type { BranchDef } from '../command.js';
+import type { HookRegistry } from './discovery.js';
+/** Registry compilation never executes hook code. */
+export type HookRegistryLoader = () => Promise<HookRegistry>;
+/** Wrap every hook-eligible core leaf so its run is the before → primary →
+ *  after pipeline. Nothing else about the leaf changes: path, params, frozen
+ *  help, renderer, and output declaration are carried through untouched, and
+ *  ineligible leaves (JSONL, UI/void, `pkg plugin`, `sys doctor`, passthrough)
+ *  keep their original run function so recovery dispatch never depends on hook
+ *  discovery.
+ *
+ *  Eligibility is per-path, so projecting the passed subtrees answers it for
+ *  those subtrees exactly as the complete catalog would; the complete catalog
+ *  is what the loaded registry validates hook targets against. */
+export declare function composeCoreHooks(subtrees: readonly BranchDef[], loadRegistry: HookRegistryLoader): BranchDef[];

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

@@ -0,0 +1 @@
+var $=Object.defineProperty;var p=(n,r)=>$(n,"name",{value:r,configurable:!0});import{ExitCode as w}from"../../types.js";import{CrtrError as v}from"../errors.js";import{operationIdContext as E}from"../events/operation-id.js";import{createCoreHookCatalog as x}from"./catalog.js";function A(n,r){const a=x(n),c=p((t,e)=>{if(t.kind==="leaf"){const o=e.join(" ");return a.has(o)?Object.freeze({...t,effectiveHelp:H(t,o,r),run:j(t,e,r)}):t}return{...t,children:t.children.map(o=>c(o,[...e,o.name]))}},"visit");return n.map(t=>c(t,[t.name]))}p(A,"composeCoreHooks");function H(n,r,a){return async c=>{const{projectEffectiveLeafHelp:t}=await import("./help.js"),e=n.effectiveHelp!==void 0?await n.effectiveHelp(c):n.help;try{const o=await a();return t(e,o.valid?o.plans.get(r):void 0)}catch{return t(e)}}}p(H,"projectedHelp");function j(n,r,a){const c=n.run,t=r.join(" ");return async(e,o)=>{const f=await a();if(!f.valid)throw k(t,f.issues);const d=f.plans.get(t);if(d===void 0)return c(e,o);const l=E.current();if(l===void 0)throw new v("internal",`\`${t}\` ran outside a crouter operation identity, so its plugin hooks cannot be dispatched.`,w.GENERAL,{command:[...r]});const{invokeExecHook:s}=await import("./transport/exec-invoke.js"),u=p(i=>({id:i.id,plugin:i.plugin.name,executable:i.executable,op:i.op,phase:i.phase,commandPath:r,...i.phase==="replace"?{output:n.help.output}:{}}),"spec"),m=[...o?.providedParams??[]];for(const i of d.before)await s(u(i),{operationId:l,input:e,providedParams:m});const g=d.replacements[0],h=g===void 0?await c(e,o):await s(u(g),{operationId:l,input:e,providedParams:m});for(const i of d.after)await s(u(i),{operationId:l,input:e,providedParams:m,...h===void 0?{}:{result:h}});return h}}p(j,"hookedRun");function k(n,r){const a=r[0],c=r.map(e=>`${e.plugin} (${e.scope}) ${e.path??"hooks"}: ${e.message} \u2014 received ${e.received}, expected ${e.expected}`).join("; "),t=[...new Set(r.map(e=>e.plugin))];return new v(a.code,`\`${n}\` cannot run: ${String(r.length)} unusable hook declaration${r.length===1?"":"s"} \u2014 ${c}.`,w.GENERAL,{received:a.received,...a.path===void 0?{}:{field:a.path},next:`${a.next} ${t.map(e=>`\`crtr pkg plugin show ${e}\``).join(" and ")} or \`crtr sys doctor\` reports the same issues; disabling the plugin also clears them.`})}p(k,"registryError");export{A as composeCoreHooks};

package/dist/core/command-hooks/discovery.d.ts

@@ -0,0 +1,133 @@
+import type { InstalledPlugin } from '../../types.js';
+import { type LifecycleDeclarationCandidate } from './artifact.js';
+import type { CoreHookCatalog } from './catalog.js';
+import type { HookManifestIssue, HookPhase, LifecycleHookPhase, ValidatedHookManifest } from './schema.js';
+import type { LifecycleEvent } from './lifecycle-catalog.js';
+export type HookDiscoveryIssueCode = HookManifestIssue['code'] | 'command_hook_target_invalid' | 'command_hook_collision';
+export interface HookDiscoveryIssue {
+    code: HookDiscoveryIssueCode;
+    plugin: string;
+    scope: 'project' | 'user';
+    path?: string;
+    message: string;
+    received: string;
+    expected: string;
+    next: string;
+}
+export interface HookPluginAttribution {
+    name: string;
+    scope: 'project' | 'user';
+    root: string;
+}
+/** One declaration resolved to the local executable that will receive it. */
+export interface EffectiveHook {
+    /** Stable identity within this plugin's effective declaration set. */
+    id: string;
+    executable: string;
+    plugin: HookPluginAttribution;
+    target: string;
+    phase: HookPhase;
+    op: string;
+    description: string;
+    effects: readonly string[];
+    /** Index in this plugin's hooks.json declaration array. */
+    declarationIndex: number;
+    /** Stable discovery order: scope, lexical plugin name, declaration index. */
+    order: number;
+}
+export interface EffectiveHookPlan {
+    target: string;
+    before: readonly EffectiveHook[];
+    /** Reverse discovery order: execute directly after the primary. */
+    after: readonly EffectiveHook[];
+    replacements: readonly EffectiveHook[];
+}
+/** One lifecycle declaration resolved to the local executable that receives it. */
+export interface EffectiveLifecycleHook {
+    executable: string;
+    plugin: HookPluginAttribution;
+    event: LifecycleEvent;
+    phase: LifecycleHookPhase;
+    op: string;
+    description: string;
+    effects: readonly string[];
+    /** Index in this plugin's lifecycle declaration array. */
+    declarationIndex: number;
+    /** Stable discovery order: scope, lexical plugin name, declaration index. */
+    order: number;
+}
+export interface LifecycleHookRegistry {
+    hooks: readonly EffectiveLifecycleHook[];
+    plans: ReadonlyMap<LifecycleEvent, readonly EffectiveLifecycleHook[]>;
+    validations: readonly HookPluginValidation[];
+    issues: readonly HookDiscoveryIssue[];
+    valid: boolean;
+}
+export interface HookPluginValidation {
+    plugin: InstalledPlugin;
+    manifestPath?: string;
+    executablePath?: string;
+    manifest?: ValidatedHookManifest;
+    lifecycleCandidates: readonly LifecycleDeclarationCandidate[];
+    hooks: readonly EffectiveHook[];
+    issues: readonly HookDiscoveryIssue[];
+}
+export type RemoteHookMetadata = Pick<EffectiveHook, 'id' | 'target' | 'phase' | 'op' | 'description' | 'effects' | 'declarationIndex'> & {
+    plugin: string;
+};
+export declare function hookIdentity(hook: {
+    plugin: {
+        name: string;
+    };
+    target: string;
+    phase: HookPhase;
+    op: string;
+    declarationIndex: number;
+}): string;
+export interface HookRegistry {
+    catalog: CoreHookCatalog;
+    hooks: readonly EffectiveHook[];
+    plans: ReadonlyMap<string, EffectiveHookPlan>;
+    validations: readonly HookPluginValidation[];
+    issues: readonly HookDiscoveryIssue[];
+    valid: boolean;
+}
+export interface HookScope {
+    scope: 'project' | 'user';
+    root: string;
+}
+/** Project scopes nearest-outward, followed by the user scope. */
+export declare function hookDiscoveryScopes(startDir?: string, profileId?: string | null): HookScope[];
+/** Effective enabled hook plugins, with disabled nearest copies still shadowing outer copies. */
+export declare function effectiveHookPlugins(startDir?: string, profileId?: string | null): InstalledPlugin[];
+/** Effective hook plugins with one source-install candidate taking the exact
+ *  scope/name slot it would occupy after activation. The candidate remains
+ *  subject to normal nearer-scope shadowing and no plugin code is executed. */
+export interface HookPluginCandidate {
+    plugin: InstalledPlugin;
+    scopeRoot: string;
+}
+/** Every command-hook target the plugins' valid hook artifacts declare. The
+ *  registry compiler only asks the core catalog about these paths, so a caller
+ *  can build the catalog over just the subtrees they name. */
+export declare function declaredCommandHookTargets(plugins: readonly InstalledPlugin[]): string[];
+/**
+ * Statically compiles hooks from already-resolved effective plugins. It reads
+ * manifest files to validate them but never executes a plugin executable.
+ */
+export declare function compileHookRegistry(catalog: CoreHookCatalog, plugins: readonly InstalledPlugin[], remote?: readonly RemoteHookMetadata[]): HookRegistry;
+/** Compiles lifecycle declarations from resolved plugins without loading the command tree. */
+export declare function compileLifecycleHookRegistry(plugins: readonly InstalledPlugin[]): LifecycleHookRegistry;
+/** Discovers lifecycle hooks for one node's resolved cwd and profile. */
+export declare function discoverLifecycleHookRegistry(startDir: string, profileId?: string | null): LifecycleHookRegistry;
+/** Discovers and compiles the invocation-local effective registry. */
+export declare function discoverHookRegistry(catalog: CoreHookCatalog, startDir?: string, profileId?: string | null): HookRegistry;
+/** Compile the exact effective set a source candidate would create before its
+ *  bytes replace the installed plugin. */
+export declare function discoverCandidateHookRegistry(catalog: CoreHookCatalog, candidate: InstalledPlugin, scopeRoot: string, startDir?: string, profileId?: string | null): HookRegistry;
+/** Compile the exact effective set after all supplied source candidates take
+ * their scope/name slots. This lets one transaction reject collisions introduced
+ * only by the combined revision. */
+export declare function discoverCandidateHookRegistryForCandidates(catalog: CoreHookCatalog, candidates: readonly HookPluginCandidate[], startDir?: string, profileId?: string | null): HookRegistry;
+/** Fixture-friendly discovery seam; production callers should use discoverHookRegistry. */
+export declare function discoverHookRegistryInScopes(catalog: CoreHookCatalog, scopes: readonly HookScope[]): HookRegistry;

package/dist/core/command-hooks/discovery.js

@@ -0,0 +1 @@
+var R=Object.defineProperty;var f=(t,n)=>R(t,"name",{value:n,configurable:!0});import{isSandboxedNode as C}from"../../shared/env.js";import{listInstalledPluginsInRoot as O}from"../resolver.js";import{projectScopeRoots as I,userScopeRoot as S}from"../scope.js";import{validatePluginHookArtifact as g}from"./artifact.js";function H(t){return JSON.stringify([t.plugin.name,t.target,t.phase,t.op,t.declarationIndex])}f(H,"hookIdentity");function z(t){return t.manifest.hooks!==void 0||t.manifest.hookExecutable!==void 0}f(z,"hasHookDeclaration");function v(t){const n=new Set,o=[];for(const i of t){const p=O(i.scope,i.root).sort((s,c)=>s.name<c.name?-1:s.name>c.name?1:0);for(const s of p)n.has(s.name)||(n.add(s.name),s.enabled&&z(s)&&o.push(s))}return o}f(v,"orderedPluginsInScopes");function y(t=process.cwd(),n){return[...I(t,n).map(o=>({scope:"project",root:o})),...C()?[]:[{scope:"user",root:S()}]]}f(y,"hookDiscoveryScopes");function P(t=process.cwd(),n){return v(y(t,n))}f(P,"effectiveHookPlugins");function _(t,n=process.cwd(),o){const i=new Set,p=[];for(const s of y(n,o)){const c=t.filter(e=>e.plugin.scope===s.scope&&e.scopeRoot===s.root),a=new Set(c.map(e=>e.plugin.name)),d=[...O(s.scope,s.root).filter(e=>!a.has(e.name)),...c.map(e=>e.plugin)];d.sort((e,r)=>e.name<r.name?-1:e.name>r.name?1:0);for(const e of d)i.has(e.name)||(i.add(e.name),e.enabled&&z(e)&&p.push(e))}return p}f(_,"effectiveHookPluginsWithCandidates");function b(t,n){return{...n,plugin:t.name,scope:t.scope}}f(b,"issue");function k(t,n){return n.map(o=>b(t,o))}f(k,"artifactIssues");function E(t,n,o){const i=[];return n.forEach((p,s)=>{o.has(p.target)||i.push(b(t,{code:"command_hook_target_invalid",path:`hooks[${s}].target`,message:`hook target "${p.target}" is not an eligible core returned-object leaf`,received:p.target,expected:"an exact eligible core leaf path",next:"Choose a current returned-object core leaf; pkg plugin, sys doctor, JSONL, passthrough, and UI/void surfaces are unavailable."}))}),i}f(E,"targetIssues");function A(t){return t.flatMap(n=>g(n.root,n.manifest).manifest?.hooks.map(o=>o.target)??[])}f(A,"declaredCommandHookTargets");function j(t,n,o=[]){const i=[],p=[],s=[];let c=0;for(const e of n){const r=g(e.root,e.manifest),u=k(e,r.issues);let l=[];if(u.length===0&&r.manifest!==void 0&&r.executablePath!==void 0){const h=E(e,r.manifest.hooks,t);u.push(...h),u.length===0&&(l=r.manifest.hooks.map((m,x)=>Object.freeze({id:H({plugin:{name:e.name},...m,declarationIndex:x}),executable:r.executablePath,plugin:Object.freeze({name:e.name,scope:e.scope,root:e.root}),target:m.target,phase:m.phase,op:m.op,description:m.description,effects:Object.freeze([...m.effects]),declarationIndex:x,order:c++})),p.push(...l))}i.push(Object.freeze({plugin:e,...r.manifestPath===void 0?{}:{manifestPath:r.manifestPath},...r.executablePath===void 0?{}:{executablePath:r.executablePath},...r.manifest===void 0?{}:{manifest:r.manifest},lifecycleCandidates:Object.freeze([...r.lifecycleCandidates]),hooks:Object.freeze(l),issues:Object.freeze(u)})),s.push(...u)}for(const e of o){if(!t.has(e.target))throw new Error(`daemon supplied an ineligible hook target: ${e.target}`);p.push(Object.freeze({...e,executable:"",plugin:Object.freeze({name:e.plugin,scope:"user",root:""}),order:c++}))}const a=new Map;for(const e of p){const r=a.get(e.target);r===void 0?a.set(e.target,[e]):r.push(e)}const d=new Map;for(const[e,r]of a){const u=r.filter(l=>l.phase==="replace");if(u.length>1)for(const l of u)s.push(b(l.plugin,{code:"command_hook_collision",path:`hooks[${l.declarationIndex}]`,message:`multiple replacements target "${e}"`,received:u.map(h=>`${h.plugin.name}:${h.op}`).join(", "),expected:"exactly one replacement for this core leaf",next:"Remove or change one replace declaration; before and after hooks may coexist with one replacement."}));d.set(e,Object.freeze({target:e,before:Object.freeze(r.filter(l=>l.phase==="before")),after:Object.freeze(r.filter(l=>l.phase==="after").reverse()),replacements:Object.freeze(u)}))}return Object.freeze({catalog:t,hooks:Object.freeze(p),plans:d,validations:Object.freeze(i),issues:Object.freeze(s),valid:s.length===0})}f(j,"compileHookRegistry");function w(t){const n=[],o=[],i=[];let p=0;for(const c of t){const a=g(c.root,c.manifest),d=k(c,a.issues);let e=[];d.length===0&&a.manifest!==void 0&&a.executablePath!==void 0&&(e=(a.manifest.schemaVersion===2?a.manifest.lifecycle:[]).map((u,l)=>Object.freeze({executable:a.executablePath,plugin:Object.freeze({name:c.name,scope:c.scope,root:c.root}),event:u.event,phase:u.phase,op:u.op,description:u.description,effects:Object.freeze([...u.effects]),declarationIndex:l,order:p++})),o.push(...e)),n.push(Object.freeze({plugin:c,...a.manifestPath===void 0?{}:{manifestPath:a.manifestPath},...a.executablePath===void 0?{}:{executablePath:a.executablePath},...a.manifest===void 0?{}:{manifest:a.manifest},lifecycleCandidates:Object.freeze([...a.lifecycleCandidates]),hooks:Object.freeze([]),issues:Object.freeze(d)})),i.push(...d)}const s=new Map;for(const c of o){const a=s.get(c.event)??[];s.set(c.event,Object.freeze([...a,c]))}return Object.freeze({hooks:Object.freeze(o),plans:s,validations:Object.freeze(n),issues:Object.freeze(i),valid:i.length===0})}f(w,"compileLifecycleHookRegistry");function F(t,n){return process.env.CRTR_TEST_DISABLE_LIFECYCLE_HOOK_DISCOVERY==="1"?w([]):w(P(t,n))}f(F,"discoverLifecycleHookRegistry");function J(t,n=process.cwd(),o){return j(t,P(n,o))}f(J,"discoverHookRegistry");function V(t,n,o,i=process.cwd(),p){return $(t,[{plugin:n,scopeRoot:o}],i,p)}f(V,"discoverCandidateHookRegistry");function $(t,n,o=process.cwd(),i){return j(t,_(n,o,i))}f($,"discoverCandidateHookRegistryForCandidates");function Y(t,n){return j(t,v(n))}f(Y,"discoverHookRegistryInScopes");export{j as compileHookRegistry,w as compileLifecycleHookRegistry,A as declaredCommandHookTargets,V as discoverCandidateHookRegistry,$ as discoverCandidateHookRegistryForCandidates,J as discoverHookRegistry,Y as discoverHookRegistryInScopes,F as discoverLifecycleHookRegistry,P as effectiveHookPlugins,y as hookDiscoveryScopes,H as hookIdentity};

package/dist/core/command-hooks/help.d.ts

@@ -0,0 +1,5 @@
+import type { EffectiveLeafHelp } from '../help.js';
+import type { EffectiveHookPlan } from './discovery.js';
+/** Build a frozen help view whose Effects order matches the effective pipeline.
+ *  Core help is never modified; all non-effects fields retain their references. */
+export declare function projectEffectiveLeafHelp(core: EffectiveLeafHelp, plan?: EffectiveHookPlan): EffectiveLeafHelp;

package/dist/core/command-hooks/help.js

@@ -0,0 +1 @@
+var s=Object.defineProperty;var n=(e,t)=>s(e,"name",{value:t,configurable:!0});function r(e){const t=`plugin=${e.plugin.name} phase=${e.phase} op=${e.op}`;return e.effects.map(f=>`[${t}] ${f}`)}n(r,"attributedEffects");function u(e,t){const f=t?.before.flatMap(r)??[],c=t?.replacements.length===1?t.replacements[0]:void 0,a=c===void 0?e.effects:r(c),p=t?.after.flatMap(r)??[];return Object.freeze({...e,effects:Object.freeze([...f,...a,...p])})}n(u,"projectEffectiveLeafHelp");export{u as projectEffectiveLeafHelp};

package/dist/core/command-hooks/index.d.ts

@@ -0,0 +1,7 @@
+export { createCoreHookCatalog, type CoreHookCatalog, type CoreHookTarget } from './catalog.js';
+export { projectEffectiveLeafHelp } from './help.js';
+export { compileHookRegistry, compileLifecycleHookRegistry, discoverCandidateHookRegistry, discoverHookRegistry, discoverHookRegistryInScopes, discoverLifecycleHookRegistry, effectiveHookPlugins, hookDiscoveryScopes, type EffectiveHook, type EffectiveHookPlan, type EffectiveLifecycleHook, type HookDiscoveryIssue, type HookPluginAttribution, type HookPluginValidation, type HookRegistry, type HookScope, type LifecycleHookRegistry, } from './discovery.js';
+export { validatePluginHookArtifact, type HookArtifactValidation } from './artifact.js';
+export { hasDeclaredHooks, hookReport, HOOK_TRUST_WARNING, type HookDeclarationReport, type HookReport, type LifecycleHookDeclarationReport } from './report.js';
+export { validateHookManifest, type DeclaredHook, type DeclaredLifecycleHook, type HookManifestIssue, type HookManifestValidation, type HookPhase, type LifecycleHookPhase, type ValidatedHookManifest, } from './schema.js';
+export { LIFECYCLE_EVENTS, isLifecycleEvent, type LifecycleEvent } from './lifecycle-catalog.js';

package/dist/core/command-hooks/index.js

@@ -0,0 +1 @@
+import{createCoreHookCatalog as r}from"./catalog.js";import{projectEffectiveLeafHelp as t}from"./help.js";import{compileHookRegistry as s,compileLifecycleHookRegistry as f,discoverCandidateHookRegistry as a,discoverHookRegistry as p,discoverHookRegistryInScopes as k,discoverLifecycleHookRegistry as H,effectiveHookPlugins as l,hookDiscoveryScopes as v}from"./discovery.js";import{validatePluginHookArtifact as d}from"./artifact.js";import{hasDeclaredHooks as m,hookReport as R,HOOK_TRUST_WARNING as x}from"./report.js";import{validateHookManifest as E}from"./schema.js";import{LIFECYCLE_EVENTS as C,isLifecycleEvent as S}from"./lifecycle-catalog.js";export{x as HOOK_TRUST_WARNING,C as LIFECYCLE_EVENTS,s as compileHookRegistry,f as compileLifecycleHookRegistry,r as createCoreHookCatalog,a as discoverCandidateHookRegistry,p as discoverHookRegistry,k as discoverHookRegistryInScopes,H as discoverLifecycleHookRegistry,l as effectiveHookPlugins,m as hasDeclaredHooks,v as hookDiscoveryScopes,R as hookReport,S as isLifecycleEvent,t as projectEffectiveLeafHelp,E as validateHookManifest,d as validatePluginHookArtifact};

package/dist/core/command-hooks/lifecycle-catalog.d.ts

@@ -0,0 +1,21 @@
+export declare const LIFECYCLE_CATALOG: {
+    readonly 'node:create': {
+        readonly phase: "before";
+        readonly hookTimeoutMs: 5000;
+        readonly eventBudgetMs: 10000;
+    };
+    readonly 'node:start': {
+        readonly phase: "on";
+        readonly hookTimeoutMs: 5000;
+        readonly eventBudgetMs: 10000;
+    };
+    readonly 'node:close': {
+        readonly phase: "on";
+        readonly hookTimeoutMs: 120000;
+        readonly eventBudgetMs: 180000;
+    };
+};
+export type LifecycleEvent = keyof typeof LIFECYCLE_CATALOG;
+export type LifecycleHookPhase = (typeof LIFECYCLE_CATALOG)[LifecycleEvent]['phase'];
+export declare const LIFECYCLE_EVENTS: readonly ("node:create" | "node:start" | "node:close")[];
+export declare function isLifecycleEvent(value: string): value is LifecycleEvent;

package/dist/core/command-hooks/lifecycle-catalog.js

@@ -0,0 +1 @@
+var n=Object.defineProperty;var t=(e,s)=>n(e,"name",{value:s,configurable:!0});const o={"node:create":{phase:"before",hookTimeoutMs:5e3,eventBudgetMs:1e4},"node:start":{phase:"on",hookTimeoutMs:5e3,eventBudgetMs:1e4},"node:close":{phase:"on",hookTimeoutMs:12e4,eventBudgetMs:18e4}},r=Object.freeze(Object.keys(o));function u(e){return Object.hasOwn(o,e)}t(u,"isLifecycleEvent");export{o as LIFECYCLE_CATALOG,r as LIFECYCLE_EVENTS,u as isLifecycleEvent};

package/dist/core/command-hooks/lifecycle-create.d.ts

@@ -0,0 +1,4 @@
+import type { NodeCreateHookRequest } from '../../hook-authoring.js';
+export type NodeCreateRequest = NodeCreateHookRequest['create'];
+/** Admit one node creation and return the release that must run after its row exists. */
+export declare function admitNodeCreate(create: NodeCreateRequest, app: string): Promise<() => void>;

package/dist/core/command-hooks/lifecycle-create.js

@@ -0,0 +1 @@
+var m=Object.defineProperty;var a=(e,r)=>m(e,"name",{value:r,configurable:!0});import{crtrHome as g}from"../canvas/paths.js";import{nodeCreateRefused as u}from"../errors.js";import{discoverLifecycleHookRegistry as y}from"./discovery.js";import{invokeBlockingLifecycleHooks as w}from"./transport/exec-lifecycle.js";let p=Promise.resolve();async function h(){let e;const r=p;p=new Promise(t=>{e=t}),await r;let o=!1;return()=>{o||(o=!0,e())}}a(h,"enterNodeCreateGate");function v(e,r){const o=y(e,r),t=o.plans.get("node:create")??[],n=o.validations.flatMap(i=>i.lifecycleCandidates.filter(s=>s.event==="node:create"&&!t.some(l=>l.plugin.name===i.plugin.name&&l.declarationIndex===s.index)).map(s=>({validation:i,candidate:s,issue:i.issues.find(l=>l.path===`lifecycle[${s.index}]`||l.path?.startsWith(`lifecycle[${s.index}].`))??i.issues[0]})))[0];if(n===void 0)return o;const{validation:c,candidate:f,issue:d}=n;throw u(`plugin "${c.plugin.name}" lifecycle hook "${f.op}" for node:create could not be discovered: ${d.message}`,`Refused by plugin ${c.plugin.name}, op ${f.op}.`)}a(v,"refusedCreateHookDiscovery");async function R(e,r){const o=await h();try{const t=v(e.cwd,e.profile),n=await w(t.plans.get("node:create")??[],{app:r,create:e,runtime:{canvasHome:g(),profile:e.profile}});if(n!==null)throw u(n.message,n.next);return o}catch(t){throw o(),t}}a(R,"admitNodeCreate");export{R as admitNodeCreate};

package/dist/core/command-hooks/report.d.ts

@@ -0,0 +1,32 @@
+import type { PluginManifest } from '../../types.js';
+import type { HookDiscoveryIssue, HookPluginValidation } from './discovery.js';
+import type { DeclaredHook, DeclaredLifecycleHook } from './schema.js';
+export declare const HOOK_TRUST_WARNING = "Command hooks receive normalized inputs and may block or replace declared targets. Lifecycle hooks run unprompted at every declared event before node launch. Both run local executables with runtime authority and may transmit received data.";
+export interface HookDeclarationReport {
+    target: string;
+    phase: DeclaredHook['phase'];
+    op: string;
+    description: string;
+    effects: readonly string[];
+}
+export interface LifecycleHookDeclarationReport {
+    event: DeclaredLifecycleHook['event'];
+    phase: DeclaredLifecycleHook['phase'];
+    op: string;
+    description: string;
+    effects: readonly string[];
+}
+/** One static hook artifact report shared by plugin inspection and lifecycle
+ * output. It only reads declarations and filesystem metadata; it never runs
+ * the hook executable. */
+export interface HookReport {
+    manifestPath?: string;
+    executablePath?: string;
+    declarations: readonly HookDeclarationReport[];
+    /** Present only for schemaVersion 2 manifests. */
+    lifecycle?: readonly LifecycleHookDeclarationReport[];
+    issues: readonly HookDiscoveryIssue[];
+    trust: typeof HOOK_TRUST_WARNING;
+}
+export declare function hasDeclaredHooks(manifest: Pick<PluginManifest, 'hooks' | 'hookExecutable'>): boolean;
+export declare function hookReport(validation: HookPluginValidation, issues?: readonly HookDiscoveryIssue[]): HookReport;

package/dist/core/command-hooks/report.js

@@ -0,0 +1 @@
+var s=Object.defineProperty;var c=(e,r)=>s(e,"name",{value:r,configurable:!0});const n="Command hooks receive normalized inputs and may block or replace declared targets. Lifecycle hooks run unprompted at every declared event before node launch. Both run local executables with runtime authority and may transmit received data.";function f(e){return e.hooks!==void 0||e.hookExecutable!==void 0}c(f,"hasDeclaredHooks");function u(e,r=e.issues){return Object.freeze({...e.manifestPath===void 0?{}:{manifestPath:e.manifestPath},...e.executablePath===void 0?{}:{executablePath:e.executablePath},declarations:Object.freeze((e.manifest?.hooks??[]).map(t=>Object.freeze({target:t.target,phase:t.phase,op:t.op,description:t.description,effects:Object.freeze([...t.effects])}))),...e.manifest?.schemaVersion===2?{lifecycle:Object.freeze(e.manifest.lifecycle.map(t=>Object.freeze({event:t.event,phase:t.phase,op:t.op,description:t.description,effects:Object.freeze([...t.effects])})))}:{},issues:Object.freeze([...r]),trust:n})}c(u,"hookReport");export{n as HOOK_TRUST_WARNING,f as hasDeclaredHooks,u as hookReport};

package/dist/core/command-hooks/schema.d.ts

@@ -0,0 +1,42 @@
+import { type LifecycleEvent, type LifecycleHookPhase } from './lifecycle-catalog.js';
+export type { LifecycleHookPhase } from './lifecycle-catalog.js';
+export type HookPhase = 'before' | 'after' | 'replace';
+export interface DeclaredHook {
+    target: string;
+    phase: HookPhase;
+    op: string;
+    description: string;
+    effects: string[];
+}
+export interface DeclaredLifecycleHook {
+    event: LifecycleEvent;
+    phase: LifecycleHookPhase;
+    op: string;
+    description: string;
+    effects: string[];
+}
+export interface ValidatedV1HookManifest {
+    schemaVersion: 1;
+    hooks: DeclaredHook[];
+}
+export interface ValidatedV2HookManifest {
+    schemaVersion: 2;
+    hooks: DeclaredHook[];
+    lifecycle: DeclaredLifecycleHook[];
+}
+export type ValidatedHookManifest = ValidatedV1HookManifest | ValidatedV2HookManifest;
+export type HookIssueCode = 'hook_manifest_unreadable' | 'hook_manifest_invalid' | 'hook_schema_version' | 'hook_path_unsafe' | 'hook_not_executable';
+export interface HookManifestIssue {
+    code: HookIssueCode;
+    path?: string;
+    message: string;
+    received: string;
+    expected: string;
+    next: string;
+}
+export interface HookManifestValidation {
+    manifest?: ValidatedHookManifest;
+    issues: HookManifestIssue[];
+}
+/** Validates the declarative hooks.json payload without filesystem access. */
+export declare function validateHookManifest(raw: unknown): HookManifestValidation;

package/dist/core/command-hooks/schema.js

@@ -0,0 +1 @@
+var j=Object.defineProperty;var c=(e,o)=>j(e,"name",{value:o,configurable:!0});import{isRecord as p}from"../../shared/predicates.js";import{LIFECYCLE_CATALOG as v,LIFECYCLE_EVENTS as y,isLifecycleEvent as V}from"./lifecycle-catalog.js";function a(e){return e===null?"null":Array.isArray(e)?"array":typeof e}c(a,"typeName");function u(e,o,n){const i=`hooks[${o}]`;if(!p(e)){n("hook_manifest_invalid","hook must be an object",a(e),"{ target, phase, op, description, effects }","Fix the hook declaration.",i);return}const s=Object.keys(e).filter(t=>!["target","phase","op","description","effects"].includes(t));if(s.length>0){n("hook_manifest_invalid","unknown hook keys",s.join(", "),"only: target, phase, op, description, effects","Remove the unknown keys.",i);return}for(const t of["target","op","description"])if(typeof e[t]!="string"||e[t].length===0){n("hook_manifest_invalid",`${t} must be a non-empty string`,a(e[t]),"a non-empty string",`Set ${t}.`,`${i}.${t}`);return}if(e.phase!=="before"&&e.phase!=="after"&&e.phase!=="replace"){n("hook_manifest_invalid","phase must be before|after|replace",String(e.phase),"before | after | replace","Set phase to a supported hook phase.",`${i}.phase`);return}if(!_(e.effects)){n("hook_manifest_invalid","effects must be a non-empty string array",a(e.effects),"a non-empty array of non-empty strings","Declare every persistent effect.",`${i}.effects`);return}return{target:e.target,phase:e.phase,op:e.op,description:e.description,effects:e.effects}}c(u,"validateCommandDeclaration");function A(e,o,n){const i=`lifecycle[${o}]`;if(!p(e)){n("hook_manifest_invalid","lifecycle hook must be an object",a(e),"{ event, phase, op, description, effects }","Fix the lifecycle declaration.",i);return}const s=Object.keys(e).filter(f=>!["event","phase","op","description","effects"].includes(f));if(s.length>0){n("hook_manifest_invalid","unknown lifecycle hook keys",s.join(", "),"only: event, phase, op, description, effects","Remove the unknown keys.",i);return}for(const f of["event","op","description"])if(typeof e[f]!="string"||e[f].length===0){n("hook_manifest_invalid",`${f} must be a non-empty string`,a(e[f]),"a non-empty string",`Set ${f}.`,`${i}.${f}`);return}if(!V(e.event)){n("hook_manifest_invalid","event must name a supported lifecycle event",String(e.event),y.join(" | "),`Set event to one of: ${y.join(", ")}.`,`${i}.event`);return}const t=v[e.event].phase;if(e.phase!==t){n("hook_manifest_invalid",`phase must be ${t}`,String(e.phase),t,`Set phase to ${t}.`,`${i}.phase`);return}if(!_(e.effects)){n("hook_manifest_invalid","effects must be a non-empty string array",a(e.effects),"a non-empty array of non-empty strings","Declare every persistent effect.",`${i}.effects`);return}return{event:e.event,phase:t,op:e.op,description:e.description,effects:e.effects}}c(A,"validateLifecycleDeclaration");function _(e){return Array.isArray(e)&&e.length>0&&e.every(o=>typeof o=="string"&&o.length>0)}c(_,"isEffects");function S(e,o){const n=Object.keys(e).filter(s=>s!=="schemaVersion"&&s!=="hooks");if(n.length>0)return o("hook_manifest_invalid","unknown top-level keys",n.join(", "),"only: schemaVersion, hooks","Remove the unknown keys."),{issues:[]};if(!Array.isArray(e.hooks)||e.hooks.length===0)return o("hook_manifest_invalid","hooks must be a non-empty array",a(e.hooks),"a non-empty array of hook declarations","Declare at least one hook.","hooks"),{issues:[]};const i=[];for(let s=0;s<e.hooks.length;s++){const t=u(e.hooks[s],s,o);if(t===void 0)return{issues:[]};i.push(t)}return{manifest:{schemaVersion:1,hooks:i},issues:[]}}c(S,"validateV1");function C(e){const o=[],n=c((r,h,g,b,$,k)=>{o.push({code:r,message:h,received:g,expected:b,next:$,...k===void 0?{}:{path:k}})},"issue");if(!p(e))return n("hook_manifest_invalid","manifest must be an object",a(e),"{ schemaVersion, hooks }","Provide a valid hooks.json manifest."),{issues:o};if(e.schemaVersion===1){const r=S(e,n);return{...r.manifest===void 0?{}:{manifest:r.manifest},issues:o}}if(e.schemaVersion!==2)return n("hook_schema_version","schemaVersion must be exactly 1 or 2",String(e.schemaVersion),"1 | 2","Update the manifest schema version to 1 or 2.","schemaVersion"),{issues:o};const i=Object.keys(e).filter(r=>r!=="schemaVersion"&&r!=="hooks"&&r!=="lifecycle");if(i.length>0)return n("hook_manifest_invalid","unknown top-level keys",i.join(", "),"only: schemaVersion, hooks, lifecycle","Remove the unknown keys."),{issues:o};const s=e.hooks,t=e.lifecycle;if(s!==void 0&&!Array.isArray(s))return n("hook_manifest_invalid","hooks must be an array when present",a(s),"an array of hook declarations","Fix hooks.","hooks"),{issues:o};if(t!==void 0&&!Array.isArray(t))return n("hook_manifest_invalid","lifecycle must be an array when present",a(t),"an array of lifecycle hook declarations","Fix lifecycle.","lifecycle"),{issues:o};const f=s??[],d=t??[];if(f.length===0&&d.length===0)return n("hook_manifest_invalid","hooks or lifecycle must be a non-empty array","both arrays were empty or absent","at least one command or lifecycle hook declaration","Declare at least one hook.","hooks"),{issues:o};const m=[];for(let r=0;r<f.length;r++){const h=u(f[r],r,n);if(h===void 0)return{issues:o};m.push(h)}const l=[];for(let r=0;r<d.length;r++){const h=A(d[r],r,n);if(h===void 0)return{issues:o};l.push(h)}return{manifest:{schemaVersion:2,hooks:m,lifecycle:l},issues:o}}c(C,"validateHookManifest");export{C as validateHookManifest};

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

@@ -0,0 +1,24 @@
+import type { HookPhase } from '../../../hook-authoring.js';
+import type { Field } from '../../help.js';
+export declare const EXEC_HOOK_TIMEOUT_MS = 15000;
+export interface ExecHookSpec {
+    /** Identity resolved against the daemon's effective hook plan on Linux. */
+    id: string;
+    plugin: string;
+    /** Absolute, validated hookExecutable path. */
+    executable: string;
+    op: string;
+    phase: HookPhase;
+    commandPath: readonly string[];
+    /** Required for replacement hooks; ignored for before and after hooks. */
+    output?: Field[];
+}
+export interface ExecHookInvocation {
+    operationId: string;
+    input: Record<string, unknown>;
+    providedParams: readonly string[];
+    /** The completed primary result, present only for an after hook. */
+    result?: Record<string, unknown>;
+}
+/** Invoke one hook executable; after failures retain the completed primary result. */
+export declare function invokeExecHook(spec: ExecHookSpec, invocation: ExecHookInvocation): Promise<Record<string, unknown> | void>;

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

@@ -0,0 +1 @@
+var R=Object.defineProperty;var f=(e,t)=>R(e,"name",{value:t,configurable:!0});import{spawn as T}from"node:child_process";import{socketFetch as A}from"../../../api/node-transport.js";import{apiSocketPath as C}from"../../canvas/paths.js";import{posixProcessGroupSpawnOptions as j,terminateProcessGroup as D}from"../../../hook-process.js";import{ExitCode as S}from"../../../types.js";import{isRecord as m}from"../../../shared/predicates.js";import{envExecutionId as G,envNodeId as K}from"../../../shared/env.js";import{validateCoreDeclaredResult as M}from"../../../api/command-manifest/result.js";import{CrtrError as b}from"../../errors.js";import{diag as I}from"../../io.js";const q=10*1024*1024,V=15e3,B=new Set(["internal","unknown_path","command_collision","command_hook_collision","plugin_protocol_error","hook_protocol_error"]),H=/^[a-z][a-z0-9]*(_[a-z0-9]+)*$/,L=/^[0-9a-f]{32}$/,$="Run `crtr pkg plugin show` or `crtr sys doctor` to inspect the plugin.";async function ie(e,t){const u=process.cwd(),o=F(e,t,u),r=await z(e,t,JSON.stringify(o),u);if(r.signal!==null)throw n(e,t,`executable was killed by signal ${r.signal}`,"a clean exit with one JSON envelope on stdout");const s=U(e,t,r.stdout);if(s.ok&&r.status!==0?I(`crtr: ${k(e)} returned ok:true but exited ${r.status} (honoring the envelope)`):!s.ok&&r.status===0&&I(`crtr: ${k(e)} returned ok:false but exited 0 (honoring the envelope)`),s.ok||X(e,t,s),e.phase!=="replace")return;const l=s.result;if(!m(l))throw n(e,t,"replacement success result was not an object","result: an object matching the target output declaration");const h=e.output;if(h===void 0)throw n(e,t,"replacement target output declaration was missing","the target leaf output declaration");const d=M(h,l);if(d!==null){const i=h.find(a=>a.name===d.field);throw d.receivedType!==void 0?n(e,t,`replacement output field "${d.field}" has the wrong type`,`${d.field}: ${i?.type??"unknown"}`):n(e,t,`replacement result is missing required output field "${d.field}"`,`a "${d.field}" field of type ${i?.type??"unknown"}`)}return l}f(ie,"invokeExecHook");async function z(e,t,u,o){if(process.platform==="linux"){const s=K(),l=G(),h=process.env.CRTR_API_SOCKET??C();if(s&&!l)throw n(e,t,"executable requires a current node execution","a current node execution");let d;try{const i=s?`/v1/nodes/${encodeURIComponent(s)}/hooks/exec`:"/v1/hooks/exec";d=await A(h)(`http://localhost${i}`,{method:"POST",headers:{"content-type":"application/json"},body:JSON.stringify({...s?{expected_execution_id:l}:{},hook_id:e.id,cwd:o,request:u})});const a=await d.json();if(!d.ok){const c=m(a)&&m(a.error)?a.error:null,g=c&&typeof c.message=="string"?c.message:`daemon refused hook execution (${d.status})`;throw c&&(c.code==="hook_timeout"||c.code==="hook_output_limit")?new b(c.code,`${k(e)}: ${g}`,S.GENERAL,N(e,t,void 0,$,g)):new Error(g)}if(!m(a)||typeof a.stdout!="string"||a.status!==null&&typeof a.status!="number"||a.signal!==null&&typeof a.signal!="string")throw new Error("invalid hook execution response");return{stdout:a.stdout,status:a.status,signal:a.signal}}catch(i){throw i instanceof b?i:n(e,t,`executable could not be run (${E(i)})`,"a registered runnable hook executable")}}let r;try{r=T(e.executable,["--crtr-hook-protocol","1"],{cwd:o,env:process.env,stdio:["pipe","pipe","inherit"],...j()})}catch(s){throw n(e,t,`executable could not be run (${E(s)})`,"a runnable hook executable")}return new Promise((s,l)=>{let h=0;const d=[];let i,a=!1,c=!1,g=null,P=null,w;const x=f(()=>{if(!(!a||i!==void 0&&!c)){if(w!==void 0&&clearTimeout(w),i?.kind==="timeout"){l(n(e,t,`executable timed out after ${V}ms`,"one JSON envelope before the execution timeout"));return}if(i?.kind==="output_limit"){l(n(e,t,"stdout exceeded the 10 MiB cap","one JSON envelope under 10 MiB on stdout"));return}if(i?.kind==="spawn"){l(n(e,t,`executable could not be run (${E(i.error)})`,"a runnable hook executable"));return}if(i?.kind==="cleanup"){l(n(e,t,`executable cleanup failed (${E(i.error)})`,"a hook executable whose process group can be terminated"));return}s({stdout:Buffer.concat(d).toString("utf8"),status:g,signal:P})}},"finish"),_=f(p=>{i===void 0&&(i=p,w!==void 0&&clearTimeout(w),D(r).then(()=>{c=!0,x()},O=>{i={kind:"cleanup",error:O},c=!0,x()}))},"terminate");r.stdout.on("data",p=>{if(h+=p.byteLength,h>q){_({kind:"output_limit"});return}d.push(p)}),r.once("error",p=>{if(r.pid===void 0){i={kind:"spawn",error:p},a=!0,c=!0,x();return}_({kind:"spawn",error:p})}),r.once("close",(p,O)=>{g=p,P=O,a=!0,x()}),w=setTimeout(()=>_({kind:"timeout"}),V),r.stdin.end(u)})}f(z,"runHookProcess");function F(e,t,u){if(!L.test(t.operationId))throw n(e,t,"operationId was not a 32-character lowercase hexadecimal string","a valid crouter operation identity");if(!y(t.input))throw n(e,t,"input was not JSON-compatible","a JSON object");if(!t.providedParams.every(r=>typeof r=="string"))throw n(e,t,"providedParams contained a non-string value","an array of parameter names");const o={protocolVersion:1,op:e.op,command:[...e.commandPath],operationId:t.operationId,input:t.input,context:{cwd:u,providedParams:[...t.providedParams]}};if(e.phase==="after"){if(t.result===void 0||!y(t.result))throw n(e,t,"after hook result was missing or not JSON-compatible","the completed primary result");return{...o,phase:"after",result:t.result}}if(t.result!==void 0)throw n(e,t,`${e.phase} hook invocation included a result`,"result only for after hooks");return e.phase==="before"?{...o,phase:"before"}:{...o,phase:"replace"}}f(F,"buildRequest");function U(e,t,u){let o;try{o=JSON.parse(u.trim())}catch{throw n(e,t,"stdout was not a single JSON envelope","exactly one JSON envelope on stdout")}if(!m(o))throw n(e,t,"stdout was not a JSON object","a { protocolVersion: 1, ok: boolean, ... } envelope");if(o.protocolVersion!==1)throw n(e,t,`unsupported protocolVersion ${String(o.protocolVersion)}`,"protocolVersion exactly 1");if(o.ok===!0){const s=e.phase==="replace"?["protocolVersion","ok","result"]:["protocolVersion","ok"];if(!J(o,s))throw n(e,t,"success envelope had missing or extra fields",`{ ${s.join(", ")} } only`);if(e.phase==="replace"){if(!y(o.result))throw n(e,t,"replacement result was not JSON-compatible","a JSON result");return{protocolVersion:1,ok:!0,result:o.result}}return{protocolVersion:1,ok:!0}}if(o.ok!==!1||!J(o,["protocolVersion","ok","error"]))throw n(e,t,"failure envelope had missing or extra fields","{ protocolVersion, ok, error } only");const r=o.error;if(!m(r)||!J(r,["code","message"],["field","next"]))throw n(e,t,"error envelope was missing fields or contained extra fields","error: { code, message, field?, next? }");if(typeof r.code!="string"||r.code===""||typeof r.message!="string"||r.message==="")throw n(e,t,"error envelope had an empty or non-string code/message","non-empty error code and message strings");if(r.field!==void 0&&typeof r.field!="string"||r.next!==void 0&&typeof r.next!="string")throw n(e,t,"error envelope had a non-string field/next","string field and next values when present");return{protocolVersion:1,ok:!1,error:{code:r.code,message:r.message,...r.field===void 0?{}:{field:r.field},...r.next===void 0?{}:{next:r.next}}}}f(U,"parseEnvelope");function X(e,t,u){const{code:o,message:r,field:s,next:l}=u.error;throw!H.test(o)||B.has(o)?n(e,t,`error code "${o}" was invalid or reserved`,"a non-reserved lowercase snake_case code"):new b(o,`${k(e)}: ${r}`,S.GENERAL,N(e,t,s,l))}f(X,"throwHookFailure");function n(e,t,u,o){return new b("hook_protocol_error",`${k(e)}: ${u}. Expected ${o}.`,S.GENERAL,N(e,t,void 0,$,u))}f(n,"protocolError");function N(e,t,u,o,r){const s={plugin:e.plugin,op:e.op,phase:e.phase,command:[...e.commandPath],...r===void 0?{}:{received:r},...u===void 0?{}:{field:u}};if(e.phase!=="after")return{...s,next:o??$};const l="Do not retry the original command; its primary action completed. Inspect and reconcile the failed after hook.";return{...s,primaryCompleted:!0,result:t.result,next:o===void 0||o===$?l:`${o} ${l}`}}f(N,"failureDetails");function k(e){return`plugin "${e.plugin}" ${e.phase} hook "${e.op}" for \`${e.commandPath.join(" ")}\``}f(k,"label");function J(e,t,u=[]){const o=Object.keys(e);return t.every(r=>Object.hasOwn(e,r))&&o.every(r=>t.includes(r)||u.includes(r))}f(J,"hasExactKeys");function y(e){return e===null||typeof e=="boolean"||typeof e=="string"?!0:typeof e=="number"?Number.isFinite(e):Array.isArray(e)?e.every(y):m(e)&&Object.values(e).every(y)}f(y,"isJson");function E(e){return e instanceof Error?e.message:String(e)}f(E,"describeError");export{V as EXEC_HOOK_TIMEOUT_MS,ie as invokeExecHook};

package/dist/core/command-hooks/transport/exec-lifecycle.d.ts

@@ -0,0 +1,23 @@
+import type { LifecycleHookRequest, NodeCreateHookRequest } from '../../../hook-authoring.js';
+import type { EffectiveLifecycleHook } from '../discovery.js';
+export interface NodeLifecycleHookInvocation {
+    node: LifecycleHookRequest['node'];
+    runtime: LifecycleHookRequest['runtime'];
+}
+export interface NodeCreateHookInvocation {
+    app: string;
+    create: NodeCreateHookRequest['create'];
+    runtime: NodeCreateHookRequest['runtime'];
+}
+export interface BlockingLifecycleHookRefusal {
+    hook: EffectiveLifecycleHook;
+    message: string;
+    next: string;
+}
+/** Runs one lifecycle hook. `node:start` and `node:close` remain best-effort. */
+export declare function invokeLifecycleHook(hook: EffectiveLifecycleHook, invocation: NodeLifecycleHookInvocation, timeoutMs: number): Promise<void>;
+/** Executes non-blocking lifecycle hooks in discovery order within the event's catalogued budget. */
+export declare function invokeLifecycleHooks(hooks: readonly EffectiveLifecycleHook[], invocation: NodeLifecycleHookInvocation): Promise<void>;
+/** Runs blocking `node:create` hooks. Every protocol or process failure refuses the create. */
+export declare function invokeBlockingLifecycleHooks(hooks: readonly EffectiveLifecycleHook[], invocation: NodeCreateHookInvocation): Promise<BlockingLifecycleHookRefusal | null>;
+export declare function lifecycleHookAttribution(hook: EffectiveLifecycleHook): string;

package/dist/core/command-hooks/transport/exec-lifecycle.js

@@ -0,0 +1 @@
+var M=Object.defineProperty;var c=(e,t)=>M(e,"name",{value:t,configurable:!0});import{randomBytes as k}from"node:crypto";import{spawn as _}from"node:child_process";import{PROCESS_GROUP_KILL_GRACE_MS as S,posixProcessGroupSpawnOptions as R,terminateProcessGroup as V}from"../../../hook-process.js";import{isRecord as L}from"../../../shared/predicates.js";import{diag as x}from"../../io.js";import{LIFECYCLE_CATALOG as O}from"../lifecycle-catalog.js";import{getNode as A}from"../../canvas/canvas.js";import{buildAppProcessEnv as C}from"../../runtime/spawn-env.js";import{appProcessSandboxed as D,launchAppProcess as G}from"../../spaces/process.js";const P=10*1024*1024;async function H(e,t,n){try{const r=await B(e,t,n);r.ok||x(`crtr: ${g(e)} failed: ${r.error.code}: ${r.error.message}`)}catch(r){x(`crtr: ${g(e)} failed: ${w(r)}`)}}c(H,"invokeLifecycleHook");async function te(e,t){if(e.length===0)return;const{hookTimeoutMs:n,eventBudgetMs:r}=O[e[0].event],s=Date.now()+r;for(const o of e){const a=s-Date.now(),u=Math.min(n,a-S);if(u<=0){x(`crtr: lifecycle hook event ${o.event} exceeded its ${r}ms aggregate budget; skipped ${g(o)}`);return}await H(o,t,u)}}c(te,"invokeLifecycleHooks");async function re(e,t){if(e.length===0)return null;const{hookTimeoutMs:n,eventBudgetMs:r}=O["node:create"],s=Date.now()+r;for(const o of e){const a=s-Date.now(),u=Math.min(n,a-S);if(u<=0)return T(o,`lifecycle hook event node:create exceeded its ${r}ms aggregate budget`);try{const i=await B(o,t,u);if(!i.ok)return{hook:o,message:i.error.message,next:i.error.next??E(o)}}catch(i){return T(o,w(i))}}return null}c(re,"invokeBlockingLifecycleHooks");function T(e,t){return{hook:e,message:`${g(e)} failed: ${t}`,next:E(e)}}c(T,"refusal");function ne(e){return E(e)}c(ne,"lifecycleHookAttribution");async function B(e,t,n){const r=e.event==="node:create"?N(e,t):I(e,t),s=D()?await J(e,t,JSON.stringify(r),n):await q(e,JSON.stringify(r),n);if(s.signal!==null)throw new Error(`executable was killed by signal ${s.signal}`);const o=K(s.stdout);return o.ok&&s.status!==0&&x(`crtr: ${g(e)} returned ok:true but exited ${s.status} (honoring the envelope)`),o}c(B,"executeLifecycleHook");function I(e,t){return{protocolVersion:1,op:e.op,event:e.event,phase:e.phase,operationId:k(16).toString("hex"),node:t.node,runtime:t.runtime,context:{cwd:t.node.cwd}}}c(I,"nodeRequest");function N(e,t){return{protocolVersion:1,op:e.op,event:"node:create",phase:"before",operationId:k(16).toString("hex"),create:t.create,runtime:t.runtime,context:{cwd:t.create.cwd}}}c(N,"createRequest");async function J(e,t,n,r){const s=e.event==="node:create",o=s?t.create.cwd:t.node.cwd,a=s?void 0:t.node.id,u=s?t.app:A(a)?.grantee;if(!u)throw new Error(`missing app for lifecycle hook ${e.event}`);const i=C(o,t.runtime.profile,u),m=await G({...s?{app:u}:{nodeId:a},command:[e.executable,"--crtr-hook-protocol","1"],cwd:e.plugin.root,pluginRoot:e.plugin.root,env:i,stdin:n,stdoutBytes:P,stderrBytes:64*1024});let l;try{const p=await Promise.race([m.completion,new Promise((b,f)=>{l=setTimeout(()=>{m.stop().then(()=>f(new Error(`executable timed out after ${r}ms`)),f)},r)})]);if(p.stdoutTruncated)throw new Error("stdout exceeded the 10 MiB cap");return{stdout:p.stdout,status:p.exitCode,signal:p.signal}}finally{l&&clearTimeout(l)}}c(J,"runSandboxedLifecycleProcess");async function q(e,t,n){let r;try{r=_(e.executable,["--crtr-hook-protocol","1"],{cwd:e.plugin.root,env:process.env,stdio:["pipe","pipe","inherit"],...R()})}catch(s){throw new Error(`executable could not be run (${w(s)})`)}return new Promise((s,o)=>{let a=0;const u=[];let i,m=!1,l=!1,p=null,b=null,f;const y=c(()=>{if(!(!m||i!==void 0&&!l)){if(f!==void 0&&clearTimeout(f),i?.kind==="timeout")return o(new Error(`executable timed out after ${n}ms`));if(i?.kind==="output_limit")return o(new Error("stdout exceeded the 10 MiB cap"));if(i?.kind==="spawn")return o(new Error(`executable could not be run (${w(i.error)})`));if(i?.kind==="cleanup")return o(new Error(`executable cleanup failed (${w(i.error)})`));s({stdout:Buffer.concat(u).toString("utf8"),status:p,signal:b})}},"finish"),$=c(d=>{i===void 0&&(i=d,f!==void 0&&clearTimeout(f),V(r).then(()=>{l=!0,y()},h=>{i={kind:"cleanup",error:h},l=!0,y()}))},"terminate");r.stdout.on("data",d=>{if(a+=d.byteLength,a>P)return $({kind:"output_limit"});u.push(d)}),r.once("error",d=>{if(r.pid===void 0){i={kind:"spawn",error:d},m=!0,l=!0,y();return}$({kind:"spawn",error:d})}),r.once("close",(d,h)=>{p=d,b=h,m=!0,y()}),f=setTimeout(()=>$({kind:"timeout"}),n),r.stdin.end(t)})}c(q,"runLifecycleProcess");function K(e){let t;try{t=JSON.parse(e.trim())}catch{throw new Error("stdout was not a single JSON envelope")}if(!L(t)||t.protocolVersion!==1)throw new Error("stdout was not a protocolVersion: 1 envelope");if(t.ok===!0&&v(t,["protocolVersion","ok"]))return{protocolVersion:1,ok:!0};if(t.ok!==!1||!v(t,["protocolVersion","ok","error"]))throw new Error("response envelope had missing or extra fields");const n=t.error;if(!L(n)||!v(n,["code","message"],["next"])||typeof n.code!="string"||n.code===""||typeof n.message!="string"||n.message===""||n.next!==void 0&&typeof n.next!="string")throw new Error("failure envelope had invalid error fields");return{protocolVersion:1,ok:!1,error:{code:n.code,message:n.message,...n.next===void 0?{}:{next:n.next}}}}c(K,"parseEnvelope");function v(e,t,n=[]){return t.every(r=>Object.hasOwn(e,r))&&Object.keys(e).every(r=>t.includes(r)||n.includes(r))}c(v,"exactKeys");function g(e){return`plugin "${e.plugin.name}" lifecycle hook "${e.op}" for ${e.event}`}c(g,"label");function E(e){return`Refused by plugin ${e.plugin.name}, op ${e.op}.`}c(E,"attribution");function w(e){return e instanceof Error?e.message:String(e)}c(w,"describeError");export{re as invokeBlockingLifecycleHooks,H as invokeLifecycleHook,te as invokeLifecycleHooks,ne as lifecycleHookAttribution};

package/dist/core/command-hooks/transport/plan.d.ts

@@ -0,0 +1,3 @@
+import type { RemoteHookMetadata } from '../discovery.js';
+/** The daemon reads user-installed manifests; no plugin path or executable crosses into the node. */
+export declare function remoteHookPlan(cwd: string): Promise<readonly RemoteHookMetadata[]>;

package/dist/core/command-hooks/transport/plan.js

@@ -0,0 +1 @@
+var d=Object.defineProperty;var c=(s,r)=>d(s,"name",{value:r,configurable:!0});import{socketFetch as h}from"../../../api/node-transport.js";import{isRecord as t}from"../../../shared/predicates.js";import{envExecutionId as u,envNodeId as l}from"../../../shared/env.js";async function v(s){const r=l(),i=u(),a=process.env.CRTR_API_SOCKET;if(!r||!i||!a)throw new Error("hook plan requires the current node execution");const p=new URLSearchParams({cwd:s,expected_execution_id:i}),n=await h(a)(`http://localhost/v1/nodes/${encodeURIComponent(r)}/hooks/plan?${p}`),o=await n.json();if(!n.ok){const e=t(o)&&t(o.error)&&typeof o.error.message=="string"?o.error.message:`hook plan refused (${n.status})`;throw new Error(e)}if(!t(o)||!Array.isArray(o.hooks))throw new Error("invalid hook plan response");return o.hooks.map(e=>{if(!t(e)||typeof e.id!="string"||typeof e.plugin!="string"||typeof e.target!="string"||!["before","after","replace"].includes(String(e.phase))||typeof e.op!="string"||typeof e.description!="string"||!Array.isArray(e.effects)||!e.effects.every(f=>typeof f=="string")||!Number.isInteger(e.declarationIndex))throw new Error("invalid hook plan entry");return e})}c(v,"remoteHookPlan");export{v as remoteHookPlan};

package/dist/core/command-manifests/registry.d.ts

@@ -0,0 +1,67 @@
+import type { LeafDef } from '../command.js';
+import type { DeclLeafBase, DeclBranch, DeclNode, CommandManifestIssue } from '../../api/command-manifest/schema.js';
+import type { ExtensionIssueNotice } from '../command-plugins/extensions.js';
+/** Reference to an external contributor (plugin or HTTP-transport plugin). */
+export type CommandContributorRef = {
+    name: string;
+    scope: 'user' | 'project';
+    sourceMarketplace?: string;
+};
+/** The stable source name used to qualify a colliding plugin command. */
+export declare function commandContributorOrigin(contributor: Pick<CommandContributorRef, 'name' | 'sourceMarketplace'>): string;
+/** The top-level name assigned to a plugin command that collides with another
+ * plugin command. */
+export declare function qualifiedTopLevelCommandName(contributor: Pick<CommandContributorRef, 'name' | 'sourceMarketplace'>, commandName: string): string;
+/** Adapter callback to turn a declared leaf into a crtr LeafDef. Takes the
+ *  leaf definition and its resolved command path, returns the outputKind and
+ *  run function to be used by the tree composer. */
+export type LeafAdapter = (leaf: DeclLeafBase, commandPath: readonly string[]) => {
+    outputKind: 'object' | 'jsonl';
+    run: LeafDef['run'];
+};
+/** One accepted external contribution after collision resolution: a validated
+ *  top-level branch node, contributor identity, and the adapter callback that
+ *  will produce its leaves' run implementations. */
+export interface CommandContribution {
+    contributor: CommandContributorRef;
+    /** Validated directory bundle metadata, when this command is a provider. */
+    provider?: import('../command-plugins/bundle.js').ProviderBlock;
+    /** Every leaf below this branch carries its transport dialect — a validated
+     *  contribution is never a bare {@link DeclLeafBase}. */
+    node: DeclBranch;
+    /** Root name from the manifest, before collision qualification. */
+    manifestName: string;
+    adaptLeaf: LeafAdapter;
+    /** Present only on an extensible branch whose nearest repository fragment was rejected. */
+    extensionIssue?: ExtensionIssueNotice;
+}
+/** Per-contributor collision issue. */
+export interface ContributorIssue extends CommandManifestIssue {
+    contributor: CommandContributorRef;
+}
+/** One plugin node accepted below an explicitly extensible core branch. */
+export interface CoreBranchMount {
+    parent: string[];
+    provider?: import('../command-plugins/bundle.js').ProviderBlock;
+    contributor: CommandContributorRef;
+    plugin: string;
+    node: DeclNode;
+    adaptLeaf: LeafAdapter;
+}
+/** Invocation-local registry snapshot after collision resolution: the accepted
+ *  contributions and every discovered issue. */
+export interface CommandRegistrySnapshot {
+    /** Accepted top-level contributions, deterministically ordered by
+     *  contributor name. */
+    contributions: CommandContribution[];
+    /** Accepted plugin nodes below an extensible core branch. */
+    coreMounts: CoreBranchMount[];
+    /** Every discovered issue, including collisions. */
+    issues: ContributorIssue[];
+}
+/** Resolve a flat list of candidate contributions into a collision-resolved
+ *  snapshot. Plugin claimants at a collided path are qualified by origin and
+ *  kept; core names take precedence and are dropped. An issue is recorded on
+ *  every claimant, and results are deterministically ordered by contributor
+ *  name. */
+export declare function resolveCommandRegistry(candidates: readonly CommandContribution[], reservedCoreNames: ReadonlySet<string>): CommandRegistrySnapshot;

package/dist/core/command-manifests/registry.js

@@ -0,0 +1 @@
+var h=Object.defineProperty;var m=(n,i)=>h(n,"name",{value:i,configurable:!0});function f(n){return n.sourceMarketplace??n.name}m(f,"commandContributorOrigin");function b(n,i){return`${f(n)}:${i}`}m(b,"qualifiedTopLevelCommandName");function C(n,i){const c=new Map,r=new Map;for(const e of n){const{node:t,contributor:d}=e,a=[t.name],o=a.join("/");if(i.has(t.name)){c.set(o,{path:a,claimants:[e],isCoreCollision:!0});continue}if(r.has(o)){const p=r.get(o),u=c.get(o);u===void 0?c.set(o,{path:a,claimants:[p,e],isCoreCollision:!1}):u.claimants.push(e)}else r.set(o,e)}const s=[],l=[];for(const e of n){const t=[e.node.name].join("/");if(c.has(t)){const d=c.get(t),a=d.claimants.map(o=>o.contributor.name).join(", ");if(d.isCoreCollision)l.push({code:"command_collision",contributor:e.contributor,path:e.node.name,message:`top-level command "${e.node.name}" collides with a crtr core command and is dropped`,received:a,expected:"no top-level command name matching a reserved core command",next:`Rename "${e.node.name}" to a name that does not collide with core.`});else{const o=b(e.contributor,e.node.name);s.push({...e,node:{...e.node,name:o}}),l.push({code:"command_collision",contributor:e.contributor,path:e.node.name,message:`top-level command "${e.node.name}" is claimed by ${a} \u2014 mounted as "${o}"`,received:a,expected:"an origin-qualified top-level command for each claimant",next:`Invoke "${o}" to use this plugin command.`})}}else s.push(e)}return s.sort((e,t)=>e.contributor.name.localeCompare(t.contributor.name)||e.node.name.localeCompare(t.node.name)),{contributions:s,coreMounts:[],issues:l}}m(C,"resolveCommandRegistry");export{f as commandContributorOrigin,b as qualifiedTopLevelCommandName,C as resolveCommandRegistry};