@north-light/cli 0.0.0 → 0.3.414

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

@@ -0,0 +1,149 @@
+import { type ValidatedCommandManifest } from '../../api/command-manifest/manifest.js';
+import type { KindConfig, MemoryExtensionDeclarations, PageComponentRegistration, PluginBundle, PluginManifest, Scope } from '../../types.js';
+/** Who may call a capability provider's tool group (contract 3). */
+export type ProviderGroupWho = 'own' | 'user' | 'allowlist' | 'any';
+/** One tool group a capability provider declares in `bundle.json`. */
+export interface ProviderGroupDeclaration {
+    group: string;
+    consent_line: string;
+    /** Price per unit, or null/absent when the group is unpriced. */
+    rate?: number | null;
+    who: ProviderGroupWho;
+    /** The app principals the group admits: `[]` unless `who` is `allowlist`
+     *  (where it may also be empty). */
+    allowlist: string[];
+}
+/** The `provider` block of a capability-provider bundle emitted by the directory. */
+export interface ProviderBlock {
+    id: string;
+    major: number;
+    groups: ProviderGroupDeclaration[];
+}
+export interface BundleIssue {
+    code: string;
+    path?: string;
+    message: string;
+    received: string;
+    expected: string;
+    next: string;
+}
+export interface ValidatedBundle {
+    bundleVersion: 1;
+    /** The plugin's integer major: `bundle.json` `version`, else `commands.json`
+     *  `version`; absent when neither declares one (treated as 1 locally). */
+    version?: number;
+    /** The transport `bundle.json` declares, when it declares one (a bundle the
+     *  directory emits for a capability provider always does). */
+    transport?: {
+        kind: 'http';
+        endpoint: string;
+        authEnv?: string;
+    };
+    /** The capability-provider block: present only on a provider bundle. */
+    provider?: ProviderBlock;
+    /** Kind-registry contributions declared in `bundle.json` (optional). The
+     *  installer copies this validated block into the synthesized plugin
+     *  manifest, where `readMergedLaunchConfig` layers it — see
+     *  `PluginManifest.kinds`. */
+    kinds?: Record<string, Partial<KindConfig>>;
+    /** Page-component contributions declared in `bundle.json` (optional). The
+     *  installer copies this validated block into the synthesized plugin
+     *  manifest, where `resolvePageComponents` reads it — see
+     *  `PluginManifest.page_components`. */
+    page_components?: PageComponentRegistration[];
+    /** Plugin-owned memory metadata declarations copied into the synthesized
+     * installed manifest alongside the archive's memory documents. */
+    memory_extensions?: MemoryExtensionDeclarations;
+    commands: ValidatedCommandManifest;
+    commandsBytes: Uint8Array;
+    directories: ReadonlyArray<{
+        path: string;
+    }>;
+    memory: ReadonlyArray<{
+        path: string;
+        bytes: Uint8Array;
+    }>;
+    hooks?: {
+        manifest: Uint8Array;
+        files: ReadonlyArray<{
+            path: string;
+            bytes: Uint8Array;
+        }>;
+    };
+}
+export interface PluginBundleValidation {
+    bundle?: ValidatedBundle;
+    issues: BundleIssue[];
+}
+/** Validate a Core-served plugin directory archive entirely in memory. */
+export declare function validatePluginBundle(archive: Uint8Array, options: {
+    reservedCoreNames: ReadonlySet<string>;
+    coreCommandPaths?: ReadonlySet<string>;
+    extensibleCoreBranches?: ReadonlySet<string>;
+}): Promise<PluginBundleValidation>;
+/** An archive install's invocation transport. */
+export type BundleInvocationTransport = {
+    kind: 'http';
+    endpoint: string;
+    authEnv?: string;
+};
+/** The hash recorded as a bundle package's `version`: the exact archive bytes
+ *  unpacked at its root. Same bytes, same version — which is what lets a
+ *  re-sent archive be recognized as the generation already installed. */
+export declare function bundleVersion(raw: Uint8Array): string;
+/** Whether `version` is the generation already unpacked at `root`. Both halves
+ *  matter: the recorded version says the config agrees, and `commands.json`
+ *  says the tree that config describes is actually on disk. A swap that died
+ *  between the rename and the config write leaves the second false, and that is
+ *  exactly the case a no-op must not claim. */
+export declare function isInstalledGeneration(name: string, scope: Scope, root: string, version: string): boolean;
+/** The ledger for a check that reached a served archive. `swapped` says whether
+ *  that archive replaced the package on disk; the validator and the check time
+ *  are recorded either way, because both describe the bytes now at the root. */
+export declare function recordCheckedGeneration(scope: Scope, name: string, etag: string | undefined, options: {
+    swapped: boolean;
+}): void;
+export interface InstallBundleArchiveOptions<M> {
+    scope: Scope;
+    /** The scope root whose `tmp/` holds staging, `.prev` and the swap lock. */
+    scopeRootPath: string;
+    /** Where the package lives once swapped in: `<plugins>/<name>`. */
+    root: string;
+    /** The archive source recorded on the manifest. */
+    bundle: PluginBundle;
+    /** Invocation transport for an ordinary archive. A provider bundle's own
+     *  `bundle.json` transport (the provider endpoint) replaces it: the archive
+     *  comes from the directory, but calls go to the provider. */
+    transport: BundleInvocationTransport;
+    /** The server's validator for `raw`, recorded once the swap lands. */
+    etag: string | undefined;
+    enable: boolean;
+    /** `bundleVersion(raw)` when the caller already computed it. */
+    version?: string;
+    validation: {
+        reservedCoreNames: ReadonlySet<string>;
+        coreCommandPaths?: ReadonlySet<string>;
+        extensibleCoreBranches?: ReadonlySet<string>;
+    };
+    /** Full candidate validation of the staged tree; throws to refuse it. */
+    validateStaged: (staging: string, manifest: PluginManifest) => Promise<M>;
+    /** Builds the error an invalid archive throws. */
+    invalid: (summary: string, issues: readonly BundleIssue[]) => Error;
+    /** Checked against the validated archive before anything is written; a
+     *  returned message refuses the archive (a provider bundle naming another id). */
+    accept?: (bundle: ValidatedBundle) => string | undefined;
+}
+export interface InstalledBundleArchive<M> {
+    manifest: PluginManifest;
+    validated: ValidatedBundle;
+    version: string;
+    root: string;
+    staged: M;
+}
+/**
+ * Validate `raw`, stage it beside the package root, swap it in, then record
+ * the config version and the state validator — in that order, never the
+ * reverse. A failure before the swap leaves the previous package untouched.
+ * The caller holds the plugin's swap lock (`bundleSwapLockPath`).
+ */
+export declare function installBundleArchive<M>(name: string, raw: Uint8Array, options: InstallBundleArchiveOptions<M>): Promise<InstalledBundleArchive<M>>;

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

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

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

@@ -0,0 +1,11 @@
+import type { BranchDef, LeafDef } from '../command.js';
+import type { CommandRegistrySnapshot, CoreBranchMount } from '../command-manifests/registry.js';
+import type { ProviderToolDescription, UnavailableProviderToolDescription } from '../providers/call.js';
+import type { ValidatedContribution, ValidatedCoreMount } from './discovery.js';
+/** A sandbox sees no user plugin files. Compose only daemon-projected help data,
+ *  with an adapter that cannot execute plugin code or send provider HTTP. */
+export declare function composeSandboxProviderSubtrees(providers: readonly (ProviderToolDescription | UnavailableProviderToolDescription)[], reserved: ReadonlySet<string>): BranchDef[];
+export declare function adaptPluginContributions(contributions: ValidatedContribution[]): CommandRegistrySnapshot;
+export declare function adaptPluginCoreMounts(mounts: ValidatedCoreMount[]): CoreBranchMount[];
+export declare function composeExternalSubtrees(snapshot: CommandRegistrySnapshot): BranchDef[];
+export declare function composeCoreBranchMounts(mounts: readonly CoreBranchMount[], parent: string[]): (BranchDef | LeafDef)[];

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

@@ -0,0 +1 @@
+var x=Object.defineProperty;var p=(n,e)=>x(n,"name",{value:e,configurable:!0});import{resolve as k}from"node:path";import{envNodeId as E}from"../../shared/env.js";import{cliClient as c}from"../../commands/api-client.js";import{defineBranch as h,defineLeaf as j}from"../command.js";import{resolveCommandRegistry as w}from"../command-manifests/registry.js";import{executeExternalLeaf as C}from"./transport/exec-invoke.js";import{invokeHttpLeaf as L}from"./transport/http-invoke.js";async function U(n){const e=await c().request("GET",`/v1/providers/${encodeURIComponent(n)}/tools`);return new Set(e.groups.flatMap(r=>r.leaves.map(a=>a.tool)))}p(U,"allowedProviderTools");function m(n,e,r){return n.children.some(a=>a.kind==="leaf"?r.has([...e,a.name].join(" ")):m(a,[...e,a.name],r))}p(m,"hasAllowedLeaf");function M(n,e,r){return n.children.filter(a=>a.tier!=="hidden"&&(a.kind==="leaf"?r.has([...e,a.name].join(" ")):m(a,[...e,a.name],r))).length}p(M,"visibleChildCount");function T(n,e,r){return async()=>{if(!E())return n.help;const a=await U(e.id);return{...n.help,listing:n.help.listing?.flatMap(s=>{const t=n.children.find(o=>o.name===s.name);if(t?.kind==="leaf")return a.has([...r,t.name].join(" "))?[s]:[];if(t?.kind!=="branch")return[];const i=[...r,t.name];if(!m(t,i,a))return[];const u=M(t,i,a);return[{...s,...s.subCount!==void 0?{subCount:u}:{}}]})}}}p(T,"providerHelp");function g(n,e,r){return{outputKind:"object",run:p(async a=>{const s={...a};for(const t of r.params){if(!("type"in t)||t.type!=="file")continue;const i=t.name.replace(/-([a-z])/g,(o,d)=>d.toUpperCase()),u=s[i];typeof u=="string"&&(s[i]=k(u))}return c({timeoutMs:0}).request("POST","/v1/provider/call",{provider:n,tool:e,arguments:s},{timeout:0})},"run")}}p(g,"providerLeafAdapter");function H(n,e){const r=[],a=[];for(const s of n){const{provider:t,commands:i}=s;if(!/^[A-Za-z0-9_-]{1,64}$/.test(t)||t==="crtr"||e.has(t)||!Array.isArray(i))continue;if(s.status!=="available"){const o=s.error??"bundle installation pending",d=`Unavailable (${s.status}): ${o}`,f=h({name:t,rootEntry:{concept:s.display_name,desc:d,useWhen:d},help:{name:t,summary:d},children:[]});f.unavailable=d,a.push(f);continue}const u=p(o=>o.kind==="branch"?{...o,children:o.children.map(u)}:{...o,rest:{method:"GET",path:"/",params:{}}},"helpNode");for(const o of i)o.name!==t||o.kind!=="branch"||!Array.isArray(o.children)||r.push({contributor:{name:t,scope:"user"},manifestName:o.name,node:u(o),adaptLeaf:p((d,f)=>g(t,f.slice(1).join(" "),d),"adaptLeaf")})}return[...A(w(r,e)),...a]}p(H,"composeSandboxProviderSubtrees");function v(n,e){return(r,a)=>{const s=n.transport,t=e(a);if(n.provider!==void 0)return g(n.provider.id,t.slice(1).join(" "),r);if(s.kind==="exec"){const u=s.executable;if(u===void 0)throw new Error(`exec plugin "${n.plugin.name}" has an executable leaf without transport.executable`);return{outputKind:"object",run:p(async o=>C({plugin:n.plugin,executable:u,commandPath:t,output:r.output},o),"run")}}const i=r;return{outputKind:i.rest.streaming===!0?"jsonl":"object",run:p((u,o)=>L({registration:{name:n.plugin.name,endpoint:s.endpoint,...s.authEnv!==void 0?{authEnv:s.authEnv}:{}},...n.manifest?.baseUrl!==void 0?{baseUrl:n.manifest.baseUrl}:{},...n.manifest?.timeouts!==void 0?{timeouts:n.manifest.timeouts}:{},params:i.params,rest:i.rest,output:i.output,commandPath:t},u,o),"run")}}}p(v,"adaptLeaf");function _(n){return{contributions:n.map(e=>({contributor:{name:e.plugin.name,scope:e.plugin.scope,sourceMarketplace:e.plugin.sourceMarketplace},node:e.node,manifestName:e.manifestName,adaptLeaf:v(e,r=>[e.manifestName,...r.slice(1)]),...e.provider!==void 0?{provider:e.provider}:{}})),coreMounts:[],issues:[]}}p(_,"adaptPluginContributions");function q(n){return n.map(e=>({parent:e.parent,plugin:e.plugin.name,contributor:{name:e.plugin.name,scope:e.plugin.scope,sourceMarketplace:e.plugin.sourceMarketplace},node:e.node,...e.provider!==void 0?{provider:e.provider}:{},adaptLeaf:v({...e,manifestName:e.node.name},r=>e.provider===void 0?[...r]:[e.provider.id,...r.slice(e.parent.length)])}))}p(q,"adaptPluginCoreMounts");function A(n){return n.contributions.map(e=>l(e,e.node,[e.node.name]))}p(A,"composeExternalSubtrees");function z(n,e){return n.filter(r=>r.parent.join("\0")===e.join("\0")).map(r=>r.node.kind==="branch"?l(r,r.node,[...e,r.node.name],r.provider===void 0?1:e.length):y(r,r.node,[...e,r.node.name]))}p(z,"composeCoreBranchMounts");function l(n,e,r,a=1){const s=e.rootEntry===void 0?void 0:{concept:e.rootEntry.concept,desc:e.rootEntry.description,useWhen:e.rootEntry.whenToUse},t=h({name:e.name,description:e.description,whenToUse:e.whenToUse,...e.tier!==void 0?{tier:e.tier}:{},...n.plugin!==void 0?{plugin:n.plugin}:{},...s!==void 0?{rootEntry:s}:{},help:{name:r.join(" "),summary:e.summary,...e.model!==void 0?{model:e.model}:{},...r.length===1&&n.extensionIssue!==void 0?{extensionIssue:n.extensionIssue}:{}},...e.passthrough!==void 0?{passthrough:e.passthrough}:{},children:e.children.map(i=>i.kind==="branch"?l(n,i,[...r,i.name],a):y(n,i,[...r,i.name]))});return n.provider!==void 0&&(t.effectiveHelp=T(t,n.provider,r.slice(a))),t}p(l,"buildBranch");function y(n,e,r){const a=n.adaptLeaf(e,r);return j({name:e.name,description:e.description,whenToUse:e.whenToUse,...e.tier!==void 0?{tier:e.tier}:{},...n.plugin!==void 0?{plugin:n.plugin}:{},help:{name:r.join(" "),summary:e.summary,params:e.params,output:e.output,outputKind:a.outputKind,effects:[...e.effects]},run:a.run})}p(y,"buildLeaf");export{_ as adaptPluginContributions,q as adaptPluginCoreMounts,z as composeCoreBranchMounts,A as composeExternalSubtrees,H as composeSandboxProviderSubtrees};

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

@@ -0,0 +1,50 @@
+import type { InstalledPlugin, PluginTransport } from '../../types.js';
+import { type ValidatedCommandManifest } from '../../api/command-manifest/manifest.js';
+import type { CommandManifestIssue, DeclBranch as DeclBranchGeneric, DeclLeaf as DeclLeafGeneric } from '../../api/command-manifest/schema.js';
+import type { CommandRegistrySnapshot } from '../command-manifests/registry.js';
+import type { ProviderBlock } from './bundle.js';
+export interface CommandDiscoveryIssue extends CommandManifestIssue {
+    plugin: string;
+}
+export type { DeclRootEntry, CommandIssueCode, TransportKind } from '../../api/command-manifest/schema.js';
+export type DeclLeaf = DeclLeafGeneric;
+export type DeclBranch = DeclBranchGeneric<DeclLeafGeneric>;
+export type DeclNode = DeclBranch | DeclLeaf;
+export interface ValidatedContribution {
+    plugin: InstalledPlugin;
+    transport: PluginTransport;
+    node: DeclBranchGeneric<DeclLeafGeneric>;
+    manifest: ValidatedCommandManifest;
+    manifestName: string;
+    /** Directory bundle metadata, kept separate from the commands manifest. */
+    provider?: ProviderBlock;
+}
+export interface ValidatedCoreMount {
+    plugin: InstalledPlugin;
+    transport: PluginTransport;
+    parent: string[];
+    node: DeclNode;
+    manifest: ValidatedCommandManifest;
+    provider?: ProviderBlock;
+}
+export interface PluginCommandValidation {
+    plugin: InstalledPlugin;
+    manifestPath: string;
+    transport?: PluginTransport;
+    /** The validated manifest — present only when validation fully passed.
+     *  Carries `helpAddenda` for the help-render lookup. */
+    manifest?: ValidatedCommandManifest;
+    contributions: ValidatedContribution[];
+    coreMounts: ValidatedCoreMount[];
+    issues: CommandDiscoveryIssue[];
+}
+export declare function effectiveCommandPlugins(startDir?: string, profileId?: string | null): InstalledPlugin[];
+export declare function validatePluginCommands(plugin: InstalledPlugin, reservedNames?: ReadonlySet<string>, coreCommandPaths?: ReadonlySet<string>, extensibleCoreBranches?: ReadonlySet<string>): PluginCommandValidation;
+export declare function discoverPluginCommandCandidates(startDir?: string, profileId?: string | null): PluginCommandValidation[];
+export declare function validateEffectiveCommandPlugins(reservedNames: ReadonlySet<string>, startDir?: string, profileId?: string | null, coreCommandPaths?: ReadonlySet<string>, extensibleCoreBranches?: ReadonlySet<string>): PluginCommandValidation[];
+export declare function discoverCommandContributions(reservedNames: ReadonlySet<string>, startDir?: string, profileId?: string | null, coreCommandPaths?: ReadonlySet<string>, extensibleCoreBranches?: ReadonlySet<string>): {
+    contributions: ValidatedContribution[];
+    coreMounts: ValidatedCoreMount[];
+    issues: CommandDiscoveryIssue[];
+};
+export declare function buildExternalCommandSnapshot(reservedCoreNames: ReadonlySet<string>, startDir?: string, profileId?: string | null, coreCommandPaths?: ReadonlySet<string>, extensibleCoreBranches?: ReadonlySet<string>): CommandRegistrySnapshot;

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

@@ -0,0 +1 @@
+var C=Object.defineProperty;var d=(e,t)=>C(e,"name",{value:t,configurable:!0});import{realpathSync as y,readFileSync as N,statSync as b}from"node:fs";import{isSandboxedNode as F}from"../../shared/env.js";import{isAbsolute as O,resolve as _,sep as q}from"node:path";import{listInstalledPlugins as A,listInstalledPluginsInRoot as E}from"../resolver.js";import{projectScopeRoots as R}from"../scope.js";import{validateCommandManifest as I}from"../../api/command-manifest/manifest.js";import{qualifiedTopLevelCommandName as $,resolveCommandRegistry as J}from"../command-manifests/registry.js";import{adaptPluginContributions as T,adaptPluginCoreMounts as B}from"./compose.js";import{validateHttpPluginTransport as H}from"./endpoint.js";import{applyCommandExtensions as L}from"./extensions.js";function w(e=process.cwd(),t){const a=new Set,s=[],i=d(n=>{a.has(n.name)||(a.add(n.name),s.push(n))},"consider");for(const n of R(e,t))for(const r of E("project",n))i(r);if(!F())for(const n of A("user"))i(n);return s.filter(n=>n.enabled&&(n.manifest.commands!==void 0||n.manifest.transport!==void 0))}d(w,"effectiveCommandPlugins");function W(e,t){return a=>t.push({...a,plugin:e.name})}d(W,"issueFor");function v(e,t){if(typeof t!="string"||t.length===0)return null;try{const a=y(e),s=y(_(e,t));return(s===a||s.startsWith(a+q))&&b(s).isFile()?s:null}catch{return null}}d(v,"safePath");function X(e,t){const a=e.manifest.transport;if(a===void 0){t.push({code:"command_manifest_invalid",plugin:e.name,message:"commands requires transport in plugin.json",received:"(missing)",expected:"a transport object",next:"Add plugin.json.transport.",path:"transport"});return}if(typeof a!="object"||a===null||Array.isArray(a)){t.push({code:"command_manifest_invalid",plugin:e.name,message:"transport must be an object",received:Array.isArray(a)?"array":typeof a,expected:"an exec or http transport object",next:"Fix plugin.json.transport.",path:"transport"});return}const s=a;if(s.kind==="http"){const n=H(s);if(n.transport!==void 0)return n.transport;t.push({code:"command_manifest_invalid",plugin:e.name,message:n.errors.join("; "),received:JSON.stringify(a),expected:"a valid HTTP transport",next:"Fix plugin.json.transport.",path:"transport"});return}const i=Object.keys(s).filter(n=>!["kind","executable"].includes(n));if(s.kind!=="exec"||i.length||s.executable!==void 0&&(typeof s.executable!="string"||s.executable.length===0)){t.push({code:"command_manifest_invalid",plugin:e.name,message:i.length?`transport has unknown keys: ${i.join(", ")}`:"exec transport requires a non-empty executable when declared",received:JSON.stringify(a),expected:'{ kind: "exec", executable?: "plugin-relative path" }',next:"Fix plugin.json.transport.",path:"transport"});return}return{kind:"exec",...s.executable!==void 0?{executable:s.executable}:{}}}d(X,"transportFor");function k(e){return e.kind==="leaf"||e.children.some(k)}d(k,"hasExecutableLeaf");function M(e){return[...e.roots,...e.coreMounts.map(t=>t.node)]}d(M,"manifestNodes");function z(e,t,a,s){if(t.executable===void 0){if(!M(a).some(k))return t;s.push({code:"command_manifest_invalid",plugin:e.name,message:"exec transport requires executable when commands.json declares executable leaves",received:"(missing)",expected:'{ kind: "exec", executable: "plugin-relative path" }',next:"Add plugin.json.transport.executable.",path:"transport.executable"});return}const i=v(e.root,t.executable);if(i===null){s.push({code:"command_path_unsafe",plugin:e.name,message:"executable escapes the plugin root or is not a regular file",received:t.executable,expected:"a relative path to a regular file inside the plugin root",next:"Fix plugin.json.transport.executable.",path:"transport.executable"});return}if((b(i).mode&73)===0){s.push({code:"command_not_executable",plugin:e.name,message:"executable lacks the POSIX exec bit",received:t.executable,expected:"a file with an executable permission bit",next:"chmod +x the plugin executable, then update the plugin.",path:"transport.executable"});return}return{kind:"exec",executable:i}}d(z,"validateExecExecutable");function G(e){return O(e)||e.startsWith(".")||e.includes("/")||e.includes("\\")}d(G,"namesPath");function K(e,t,a){let s=!0;const i=d(n=>{if(n.kind!=="branch")return;const r=n.passthrough;if(r!==void 0&&G(r.bin)){const l=v(e.root,r.bin);l===null?(a.push({code:"command_path_unsafe",plugin:e.name,message:"passthrough binary escapes the plugin root or is not a regular file",received:r.bin,expected:"a relative path to a regular file inside the plugin root",next:"Fix passthrough.bin in commands.json.",path:"passthrough.bin"}),s=!1):(b(l).mode&73)===0?(a.push({code:"command_not_executable",plugin:e.name,message:"passthrough binary lacks the POSIX exec bit",received:r.bin,expected:"a file with an executable permission bit",next:"chmod +x the plugin executable, then update commands.json.",path:"passthrough.bin"}),s=!1):n.passthrough={...r,bin:l}}for(const l of n.children)i(l)},"visit");for(const n of M(t))i(n);return s}d(K,"resolvePassthroughBinaries");function S(e,t=new Set,a,s=new Set){const i=[],n=e.manifest.commands,r=e.manifest.transport;let l=_(e.root,typeof n=="string"?n:"commands.json");const c=d(x=>({plugin:e,manifestPath:l,...x===void 0?{}:{transport:x},contributions:[],coreMounts:[],issues:i}),"empty");if(n===void 0&&r===void 0)return c();if(typeof n!="string"||n.length===0)return i.push({code:"command_manifest_invalid",plugin:e.name,message:"transport requires commands in plugin.json",received:"(missing)",expected:"a plugin-root-relative commands path",next:"Add plugin.json.commands or remove transport.",path:"commands"}),c();const o=X(e,i);if(o===void 0)return c();const u=v(e.root,n);if(u===null)return i.push({code:"command_path_unsafe",plugin:e.name,message:"commands pointer escapes the plugin root or is not a regular file",received:n,expected:"a relative path to a regular file inside the plugin root",next:"Fix plugin.json.commands.",path:"commands"}),c(o);l=u;let p;try{p=N(u)}catch{p=null}if(p===null)return i.push({code:"command_manifest_unreadable",plugin:e.name,message:"commands.json is missing or unreadable",received:u,expected:"a readable JSON file",next:"Reinstall or update the plugin."}),c(o);let h;try{h=JSON.parse(Buffer.from(p).toString("utf8"))}catch{return i.push({code:"command_manifest_invalid",plugin:e.name,message:"commands.json is not valid JSON",received:u,expected:"a JSON object",next:"Regenerate commands.json."}),c(o)}const f=I(h,{transport:o.kind,reservedCoreNames:t,extensibleCoreBranches:s,...a!==void 0?{coreCommandPaths:a}:{}});if(f.manifest===void 0)return f.issues.forEach(W(e,i)),c(o);const m=o.kind==="exec"?z(e,o,f.manifest,i):o;if(m===void 0)return c(o);if(m.kind==="exec"&&!K(e,f.manifest,i))return c(m);const g=e.manifest.provider,j=f.manifest.roots;if(!j.every(x=>x.kind==="branch"))throw new Error("plugin manifest validation returned a top-level leaf");return{plugin:e,manifestPath:l,transport:m,manifest:f.manifest,contributions:j.map(x=>({plugin:e,transport:m,node:x,manifest:f.manifest,manifestName:x.name,...g!==void 0?{provider:g}:{}})),coreMounts:f.manifest.coreMounts.map(x=>({plugin:e,transport:m,parent:x.parent,node:x.node,manifest:f.manifest,...g!==void 0?{provider:g}:{}})),issues:i}}d(S,"validatePluginCommands");function ie(e=process.cwd(),t){return w(e,t).map(a=>S(a))}d(ie,"discoverPluginCommandCandidates");function P(e,t=process.cwd(),a,s,i=new Set){const n=w(t,a).map(c=>S(c,e,s,i)),r=new Map;for(const c of n)for(const o of c.contributions){const u=r.get(o.node.name);u===void 0?r.set(o.node.name,[o]):u.push(o)}for(const[c,o]of r)if(o.length>1)for(const u of o){const{plugin:p}=u,h=$({name:p.name,sourceMarketplace:p.sourceMarketplace},c),f=n.find(m=>m.plugin.root===p.root);f.contributions=f.contributions.map(m=>m===u?{...m,node:{...m.node,name:h}}:m),f.issues.push({code:"command_collision",plugin:p.name,path:c,message:`top-level command "${c}" is claimed by ${o.map(m=>m.plugin.name).join(", ")} \u2014 mounted as "${h}"`,received:o.map(m=>m.plugin.name).join(", "),expected:"an origin-qualified top-level command for each claimant",next:`Invoke "${h}" to use this plugin command.`})}const l=new Map;for(const c of n)for(const o of c.coreMounts){const u=[...o.parent,o.node.name].join("/"),p=l.get(u);p===void 0?l.set(u,[o]):p.push(o)}for(const[c,o]of l)if(o.length>1)for(const u of o){const p=n.find(h=>h.plugin.root===u.plugin.root);p.coreMounts=p.coreMounts.filter(h=>h!==u),p.issues.push({code:"command_collision",plugin:u.plugin.name,path:c.replace("/","."),message:`contributed command "${u.node.name}" conflicts with another plugin child below the extensible core branch`,received:o.map(h=>h.plugin.name).join(", "),expected:`a unique child name below ${u.parent.join(".")}`,next:"Rename the contributed command or remove this mount."})}return n}d(P,"validateEffectiveCommandPlugins");function Q(e,t){return{...t,contributor:{name:e.name,scope:e.scope,sourceMarketplace:e.sourceMarketplace}}}d(Q,"contributorIssue");function re(e,t=process.cwd(),a,s,i=new Set){const n=P(e,t,a,s,i);return{contributions:n.flatMap(r=>r.contributions),coreMounts:n.flatMap(r=>r.coreMounts),issues:n.flatMap(r=>r.issues)}}d(re,"discoverCommandContributions");function ce(e,t=process.cwd(),a,s,i=new Set){const n=P(e,t,a,s,i),r=T(n.flatMap(o=>o.contributions)).contributions,l=J(r,e);return{contributions:L(l.contributions,t).contributions,coreMounts:B(n.flatMap(o=>o.coreMounts)),issues:[...n.flatMap(o=>o.issues.map(u=>Q(o.plugin,u))),...l.issues]}}d(ce,"buildExternalCommandSnapshot");export{ce as buildExternalCommandSnapshot,re as discoverCommandContributions,ie as discoverPluginCommandCandidates,w as effectiveCommandPlugins,P as validateEffectiveCommandPlugins,S as validatePluginCommands};

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

@@ -0,0 +1,24 @@
+export interface HttpPluginFetchTarget {
+    name: string;
+    endpoint: string;
+    authEnv?: string;
+}
+export interface HttpPluginRegistration extends HttpPluginFetchTarget {
+    root: string;
+    commands: string;
+    scope: 'user' | 'project';
+}
+export interface EndpointValidation {
+    isValid: boolean;
+    errors: string[];
+}
+export declare function validateEndpoint(endpoint: unknown): EndpointValidation;
+export declare function normalizeEndpoint(endpoint: string): string;
+export declare function validateHttpPluginTransport(raw: unknown): {
+    transport?: {
+        kind: 'http';
+        endpoint: string;
+        authEnv?: string;
+    };
+    errors: string[];
+};

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

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

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

@@ -0,0 +1,20 @@
+import type { CommandManifestIssue } from '../../api/command-manifest/schema.js';
+import type { CommandContribution } from '../command-manifests/registry.js';
+export interface ExtensionIssueNotice {
+    fragment: string;
+    message: string;
+}
+export interface CommandExtensionValidation {
+    branch: string;
+    fragmentPath: string;
+    projectRoot: string;
+    issue?: CommandManifestIssue;
+}
+/** Attach the nearest repository-owned fragment to each marked plugin branch.
+ * Discovery reads only; execution remains in the leaf adapter. */
+export declare function applyCommandExtensions(contributions: readonly CommandContribution[], startDir?: string): {
+    contributions: CommandContribution[];
+    validations: CommandExtensionValidation[];
+};
+/** Doctor's only directory scan: fragments with no matching effective marked branch are otherwise inert by design. */
+export declare function orphanCommandExtensionValidations(contributions: readonly CommandContribution[], startDir?: string): CommandExtensionValidation[];

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

@@ -0,0 +1 @@
+var S=Object.defineProperty;var l=(e,s)=>S(e,"name",{value:s,configurable:!0});import{existsSync as k,realpathSync as x,readFileSync as w,readdirSync as $,statSync as h}from"node:fs";import{dirname as b,isAbsolute as C,join as f,resolve as F,sep as L}from"node:path";import{projectScopeRoots as g}from"../scope.js";import{validateCommandManifest as I}from"../../api/command-manifest/manifest.js";import{executeExternalLeaf as O}from"./transport/exec-invoke.js";import{isRecord as y}from"../../shared/predicates.js";function d(e,s,r,c,t,a){return{code:"command_extension_invalid",message:s,received:r,expected:c,next:t,path:a===void 0?e:`${e}:${a}`}}l(d,"issue");function E(e){return`Fix the repository CLI definition and regenerate ${e}.`}l(E,"regenerate");function N(e,s,r){if(C(r))return{issue:d(e,"fragment transport executable must be project-relative",r,"a project-root-relative regular file","Fix transport.executable in the repository CLI definition and regenerate the fragment.","transport.executable")};try{const c=x(s),t=x(F(s,r));return t!==c&&!t.startsWith(c+L)||!h(t).isFile()?{issue:d(e,"fragment transport executable escapes the project root or is not a regular file",r,"a project-root-relative regular file","Fix transport.executable in the repository CLI definition and regenerate the fragment.","transport.executable")}:(h(t).mode&73)===0?{issue:d(e,"fragment transport executable lacks the POSIX exec bit",r,"a file with an executable permission bit","chmod +x the repository command executable, then regenerate the fragment.","transport.executable")}:{executable:t}}catch{return{issue:d(e,"fragment transport executable escapes the project root or is not a regular file",r,"a project-root-relative regular file","Fix transport.executable in the repository CLI definition and regenerate the fragment.","transport.executable")}}}l(N,"safeExecutable");function J(e,s,r,c){let t;try{t=JSON.parse(w(e,"utf8"))}catch{return{issue:d(e,"extension fragment is missing, unreadable, or not valid JSON",e,"a readable generated JSON fragment",`Regenerate ${e}.`)}}if(!y(t))return{issue:d(e,"extension fragment must be an object",t===null?"null":Array.isArray(t)?"array":typeof t,"{ schemaVersion, transport, mounts }",`Regenerate ${e}.`)};const a=Object.keys(t).filter(o=>!["schemaVersion","transport","mounts"].includes(o));if(a.length>0)return{issue:d(e,"extension fragment has unknown top-level keys",a.join(", "),"only: schemaVersion, transport, mounts",`Regenerate ${e}.`)};const n=t.transport;if(!y(n)||Object.keys(n).some(o=>!["kind","executable"].includes(o))||n.kind!=="exec"||typeof n.executable!="string"||n.executable.length===0)return{issue:d(e,'extension fragment transport must be { kind: "exec", executable: "project-relative path" }',JSON.stringify(n),"an exec transport with an executable",`Regenerate ${e}.`,"transport")};const i=N(e,s,n.executable);if(i.issue!==void 0)return{issue:i.issue};const u=I(t,{transport:"exec",reservedCoreNames:new Set,extensionFragment:!0});if(u.manifest===void 0){const o=u.issues[0];return{issue:d(e,o.message,o.received,o.expected,E(e),o.path)}}const p=u.manifest.roots.find(o=>c.includes(o.name));return p!==void 0?{issue:d(e,`contributed command "${p.name}" conflicts with a child the extensible branch already owns`,p.name,"a name not already owned by the plugin branch",`Rename "${p.name}" in the repository CLI tree, then regenerate ${e}.`,p.name)}:{fragment:{roots:u.manifest.roots,executable:i.executable}}}l(J,"validateFragment");function V(e,s){for(const r of g(s,null)){const c=b(r),t=f(r,"commands",`${e}.json`);if(k(t))return{fragmentPath:t,projectRoot:c}}}l(V,"nearestFragment");function j(e,s){if(e.kind==="leaf"){s.add(e);return}e.children.forEach(r=>j(r,s))}l(j,"markLeaves");function q(e,s=process.cwd()){const r=[];return{contributions:e.map(t=>{if(t.node.extensible!==!0)return t;const a=t.node.name,n=V(a,s);if(n===void 0)return t;const i=J(n.fragmentPath,n.projectRoot,a,t.node.children.map(o=>o.name));if(i.issue!==void 0)return r.push({branch:a,fragmentPath:n.fragmentPath,projectRoot:n.projectRoot,issue:i.issue}),{...t,extensionIssue:{fragment:n.fragmentPath,message:i.issue.message}};const u=i.fragment;r.push({branch:a,fragmentPath:n.fragmentPath,projectRoot:n.projectRoot});const p=new WeakSet;return u.roots.forEach(o=>j(o,p)),{...t,node:{...t.node,children:[...t.node.children,...u.roots]},adaptLeaf:l((o,m)=>{if(!p.has(o))return t.adaptLeaf(o,m);const v=[...m];return{outputKind:"object",run:l(async R=>O({extension:{branch:a,root:n.projectRoot},executable:u.executable,commandPath:v,output:o.output},R),"run")}},"adaptLeaf")}}),validations:r}}l(q,"applyCommandExtensions");function z(e,s=process.cwd()){const r=g(s,null)[0];if(r===void 0)return[];const c=f(r,"commands");let t;try{t=$(c)}catch{return[]}const a=new Set(e.filter(n=>n.node.extensible===!0).map(n=>n.node.name));return t.filter(n=>n.endsWith(".json")).flatMap(n=>{const i=n.slice(0,-5);if(a.has(i))return[];const u=f(c,n);return[{branch:i,fragmentPath:u,projectRoot:b(r),issue:d(u,`fragment names branch "${i}" but no effective plugin branch is extensible`,i,"the name of an effective extensible plugin branch",`Mark the plugin branch extensible or rename/remove ${u}.`)}]})}l(z,"orphanCommandExtensionValidations");export{q as applyCommandExtensions,z as orphanCommandExtensionValidations};

package/dist/core/command-plugins/help-addenda.d.ts

@@ -0,0 +1,25 @@
+export interface HelpAddendum {
+    plugin: string;
+    text: string;
+}
+/** Collect every enabled plugin's addendum targeting `commandPath` (the
+ *  space-joined walked path, e.g. "cron add"), in plugin-name order. `gate`
+ *  carries the strict-validation inputs the install/bundle gates use; the
+ *  help renderer already holds both (build-root exports them).
+ *
+ *  `coreCommandPaths` arrives as a thunk because producing that set walks core
+ *  subtrees — command modules loaded on a path that renders one leaf's help.
+ *  So the claimant pass below runs the SAME validator without it: the core path
+ *  set can only reject an addendum, never introduce one, so a commandPath no
+ *  manifest claims tolerantly claims none under the gate either, and the
+ *  expensive input is never forced. Claimants then re-validate strictly,
+ *  reproducing the gate's exact verdict — a manifest the gate rejects renders
+ *  nothing, including its valid keys. The thunk receives every path that
+ *  strict verdict asks about (the claimants' addendum keys and core-mount
+ *  paths); it must answer membership for those exactly as the complete set
+ *  would, and may load only the subtrees they name. */
+export declare function collectHelpAddenda(commandPath: string, gate: {
+    reservedCoreNames: ReadonlySet<string>;
+    coreCommandPaths: (asked: readonly string[]) => Promise<ReadonlySet<string>>;
+    extensibleCoreBranches: () => Promise<ReadonlySet<string>>;
+}, startDir?: string, profileId?: string | null): Promise<HelpAddendum[]>;

package/dist/core/command-plugins/help-addenda.js

@@ -0,0 +1 @@
+var p=Object.defineProperty;var l=(r,n)=>p(r,"name",{value:n,configurable:!0});import{effectiveCommandPlugins as h,validatePluginCommands as c}from"./discovery.js";async function v(r,n,u,f){if(r.length===0)return[];const o=await n.extensibleCoreBranches(),a=[],i=h(u,f).filter(t=>{const e=c(t,n.reservedCoreNames,void 0,o).manifest;return e?.helpAddenda?.[r]===void 0?!1:(a.push(...Object.keys(e.helpAddenda),...e.coreMounts.map(d=>[...d.parent,d.node.name].join(" "))),!0)});if(i.length===0)return[];const m=await n.coreCommandPaths(a),s=[];for(const t of i){const e=c(t,n.reservedCoreNames,m,o).manifest?.helpAddenda?.[r];e!==void 0&&s.push({plugin:t.name,text:e})}return s.sort((t,e)=>t.plugin.localeCompare(e.plugin)),s}l(v,"collectHelpAddenda");export{v as collectHelpAddenda};

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

@@ -0,0 +1,2 @@
+/** Whether an enabled command plugin survives nearest-scope name shadowing. */
+export declare function hasEffectiveCommandPlugins(startDir?: string, profileId?: string | null): boolean;

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

@@ -0,0 +1 @@
+var a=Object.defineProperty;var n=(o,t)=>a(o,"name",{value:t,configurable:!0});import{listInstalledPlugins as f,listInstalledPluginsInRoot as m}from"../resolver.js";import{projectScopeRoots as d}from"../scope.js";function l(o=process.cwd(),t){const s=new Set,r=n(e=>s.has(e.name)?!1:(s.add(e.name),e.enabled&&(e.manifest.commands!==void 0||e.manifest.transport!==void 0)),"consider");for(const e of d(o,t))if(m("project",e).some(r))return!0;return f("user").some(r)}n(l,"hasEffectiveCommandPlugins");export{l as hasEffectiveCommandPlugins};

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

@@ -0,0 +1,18 @@
+/**
+ * Bring every installed bundle plugin whose last check has aged out back in
+ * step with its endpoint. Never throws: a plugin that cannot be revalidated
+ * keeps the package already unpacked on disk, which is a complete and valid
+ * command tree, and the failure is reported on stderr rather than replacing the
+ * caller's command with an error about a background check.
+ */
+export declare function revalidateBundlePlugins(argv: readonly string[]): Promise<void>;
+/**
+ * Force one plugin back in step with its endpoint, ignoring both the TTL and
+ * the stored validator. Recovery from a server that answered `manifest_stale`:
+ * the description the caller invoked from is out of date, so the check that
+ * would normally be skipped is exactly the one that has to run.
+ *
+ * Returns whether the package on disk actually changed, so a caller can tell a
+ * recoverable staleness from an operation that is genuinely gone.
+ */
+export declare function forceRevalidateBundlePlugin(name: string): Promise<boolean>;

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

@@ -0,0 +1,2 @@
+var m=Object.defineProperty;var s=(n,e)=>m(n,"name",{value:e,configurable:!0});import{readState as g}from"../config.js";import{listInstalledPluginsInRoot as d}from"../installed-plugins.js";import{scopeRoot as l}from"../scope.js";import{GLOBAL_TOKENS as b}from"../command.js";const f=900*1e3,p=["project","user"];function P(){const n=process.env.CRTR_PLUGIN_REVALIDATE_TTL_MS;if(n===void 0||n.trim()==="")return f;const e=Number(n);return!Number.isFinite(e)||e<0?f:e}s(P,"ttlMs");function _(n,e,i){if(n===void 0)return!1;const r=Date.parse(n);if(Number.isNaN(r))return!1;const t=i-r;return t>=0&&t<e}s(_,"isFresh");function h(n){return n.slice(2).find(e=>!b.has(e))==="pkg"}s(h,"managesPackages");function v(n,e){const i=[],r=new Set;for(const t of p){const a=l(t);if(a===null)continue;const u=g(t);for(const o of d(t,a)){if(r.has(o.name))continue;r.add(o.name);const c=o.manifest.bundle;!o.enabled||c===void 0||o.manifest.provider===void 0&&(_(u.plugins[o.name]?.checked_at,n,e)||i.push({name:o.name,scope:t,bundle:c,enabled:o.enabled}))}}return i}s(v,"duePlugins");async function E(n){const e=P();if(e===0||h(n))return;let i;try{i=v(e,Date.now())}catch{return}if(i.length===0)return;const{revalidateBundlePlugin:r}=await import("../../commands/pkg/plugin-manage.js");for(const t of i)try{await r(t.name,t.bundle,t.scope,{enable:t.enabled,conditional:!0,timeoutMs:2e3})}catch(a){const u=a instanceof Error?a.message:String(a);process.stderr.write(`crtr: plugin "${t.name}" could not be revalidated (${u}); using the installed package.
+`)}}s(E,"revalidateBundlePlugins");async function R(n){let e;for(const a of p){const u=l(a);if(u!==null&&(e=d(a,u).find(o=>o.name===n),e!==void 0))break}const i=e?.manifest.bundle;if(e===void 0||i===void 0||e.manifest.provider!==void 0)return!1;const{revalidateBundlePlugin:r}=await import("../../commands/pkg/plugin-manage.js");return await r(n,i,e.scope,{enable:e.enabled,conditional:!1})!==void 0}s(R,"forceRevalidateBundlePlugin");export{R as forceRevalidateBundlePlugin,E as revalidateBundlePlugins};

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

@@ -0,0 +1,28 @@
+import type { InstalledPlugin } from '../../../types.js';
+import type { Field } from '../../help.js';
+export type ExternalLeafSpec = {
+    plugin: InstalledPlugin;
+    extension?: never;
+    /** Absolute, resolved executable path. */
+    executable: string;
+    /** Full canonical command path, e.g. ['app', 'show']. */
+    commandPath: string[];
+    /** Declared leaf output fields — validated against the result before render. */
+    output: Field[];
+} | {
+    plugin?: never;
+    extension: {
+        branch: string;
+        root: string;
+    };
+    /** Absolute, resolved executable path. */
+    executable: string;
+    /** Full canonical command path, e.g. ['app', 'show']. */
+    commandPath: string[];
+    /** Declared leaf output fields — validated against the result before render. */
+    output: Field[];
+};
+/** Execute one external leaf and return its result object (crtr renders it via
+ *  the generic renderer; `--json` mirrors it). Throws a CrtrError for any
+ *  protocol violation or the plugin's own recoverable error. */
+export declare function executeExternalLeaf(spec: ExternalLeafSpec, input: Record<string, unknown>): Record<string, unknown>;

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

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

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

@@ -0,0 +1,41 @@
+import type { HttpPluginFetchTarget } from '../endpoint.js';
+/** Exact archive bytes returned by a successful authenticated bundle fetch. */
+export interface FetchSuccess {
+    status: 200;
+    raw: Uint8Array;
+    /** The server's validator for these exact bytes, when it sent one. Storing it
+     *  is what lets the next fetch be conditional. */
+    etag?: string;
+}
+/** The archive the caller already holds is still current. Only ever returned
+ *  when the caller supplied `ifNoneMatch`. */
+export interface FetchNotModified {
+    status: 304;
+}
+export type FetchResult = FetchSuccess | FetchNotModified | FetchFailure;
+export interface FetchFailure {
+    status: 'auth_env_missing' | 'cli_unreachable' | 'cli_protocol_error';
+    message: string;
+}
+export interface FetchOptions {
+    /** Send as `If-None-Match`, inviting the server to answer 304 instead of
+     *  resending an archive the caller already has unpacked. */
+    ifNoneMatch?: string;
+    /** Inactivity timeout. Defaults to ten seconds, which suits an install the
+     *  caller is waiting on; a revalidation on an ordinary command's latency path
+     *  passes something far shorter. */
+    timeoutMs?: number;
+}
+/**
+ * One authenticated GET for a plugin directory archive, conditional when the
+ * caller supplies a validator. It never retries.
+ *
+ * A caller that sends no validator cannot be answered 304 — there is nothing
+ * for the server to compare against — and the overloads say so, so an
+ * unconditional caller handles the two outcomes it can actually get instead of
+ * carrying an unreachable branch for the third.
+ */
+export declare function fetchHttpPluginBundle(registration: HttpPluginFetchTarget, options?: FetchOptions & {
+    ifNoneMatch?: never;
+}): Promise<FetchSuccess | FetchFailure>;
+export declare function fetchHttpPluginBundle(registration: HttpPluginFetchTarget, options: FetchOptions): Promise<FetchResult>;

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

@@ -0,0 +1 @@
+var m=Object.defineProperty;var f=(t,s)=>m(t,"name",{value:s,configurable:!0});import{URL as l}from"node:url";import{request as p}from"node:https";import{request as h}from"node:http";async function T(t,s={}){let n;if(t.authEnv&&(n=process.env[t.authEnv],!n))return{status:"auth_env_missing",message:`Environment variable '${t.authEnv}' is required but not set or empty.`};let r;try{r=new l(t.endpoint)}catch{return{status:"cli_protocol_error",message:`Invalid endpoint URL: ${t.endpoint}`}}const d=s.timeoutMs??1e4,c={Accept:"application/x-tar"};return n&&(c.Authorization=`Bearer ${n}`),s.ifNoneMatch!==void 0&&(c["If-None-Match"]=s.ifNoneMatch),new Promise(o=>{const a=(r.protocol==="https:"?p:h)(r,{method:"GET",headers:c,timeout:d},e=>{let i=Buffer.alloc(0);e.on("data",u=>{i=Buffer.concat([i,u])}),e.on("end",()=>{const u=e.headers.etag;e.statusCode?e.statusCode===304?s.ifNoneMatch===void 0?o({status:"cli_protocol_error",message:`HTTP 304 from ${t.endpoint} without a conditional request`}):o({status:304}):e.statusCode>=200&&e.statusCode<300?o({status:200,raw:new Uint8Array(i),...typeof u=="string"?{etag:u}:{}}):o({status:"cli_protocol_error",message:`HTTP ${e.statusCode} from ${t.endpoint}`}):o({status:"cli_protocol_error",message:"No HTTP status code received."})})});a.on("timeout",()=>{a.destroy(),o({status:"cli_unreachable",message:`Request timeout (${d}ms) fetching ${t.endpoint}`})}),a.on("error",e=>{o({status:"cli_unreachable",message:`Network error fetching ${t.endpoint}: ${e.message}`})}),a.end()})}f(T,"fetchHttpPluginBundle");export{T as fetchHttpPluginBundle};

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

@@ -0,0 +1,15 @@
+import type { LeafRunContext } from '../../command.js';
+import type { HttpInvokerSpec } from './http-plan.js';
+/**
+ * Execute one HTTP-transport plugin leaf. Unary leaves return the validated response
+ * object (crtr's ordinary dispatcher renders it, or mirrors it under --json).
+ * Streaming leaves relay NDJSON frames to stdout incrementally and return void.
+ *
+ * Pre-network failures (missing auth, unreadable local file, illegal header
+ * value) and pre-first-frame transport / protocol failures throw a structured
+ * CrtrError for handle() to render. A streaming transport failure AFTER any
+ * frame has been emitted writes only a stderr diagnostic and sets
+ * process.exitCode = NETWORK — it never throws into handle() and never writes a
+ * second result/error object to stdout.
+ */
+export declare function invokeHttpLeaf(spec: HttpInvokerSpec, input: Record<string, unknown>, context?: LeafRunContext): Promise<Record<string, unknown> | void>;

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

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