@north-light/crouter 0.3.164 → 0.3.165

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

@@ -1,11 +1,4 @@
-// Shared command-manifest schema: common descriptors, strict validators,
-// and leaf-dialect specialization for plugins vs configured CLIs.
-//
-// The descriptor vocabulary (DeclRootEntry, DeclBranch, DeclNode, InputParam,
-// Field) is transport-neutral and reused by both plugins (local executable) and
-// configured CLIs (remote HTTP). Leaves specialize into two strict dialects:
-// PluginDeclLeaf requires only outputKind: 'object'; ConfiguredCliDeclLeaf
-// requires only rest (and derives outputKind from rest.streaming).
+// Unified command-manifest schema. Transport is the sole leaf-dialect discriminator.
 // ---------------------------------------------------------------------------
 // Validation helpers
 // ---------------------------------------------------------------------------
@@ -15,15 +8,15 @@ const KEBAB = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
 const BRANCH_KEYS = new Set([
     'kind', 'name', 'description', 'whenToUse', 'tier', 'rootEntry', 'summary', 'model', 'children',
 ]);
-/** Only the plugin dialect may declare `passthrough`; the configured-CLI dialect
- *  keeps BRANCH_KEYS, so a remote manifest declaring it fails as an unknown key. */
-const PLUGIN_BRANCH_KEYS = new Set([...BRANCH_KEYS, 'passthrough']);
+/** Only exec transport may declare `passthrough`; HTTP manifests keep
+ *  BRANCH_KEYS, so a declared passthrough fails as an unknown key. */
+const EXEC_BRANCH_KEYS = new Set([...BRANCH_KEYS, 'passthrough']);
 const PASSTHROUGH_KEYS = new Set(['bin', 'installHint']);
 const LEAF_KEYS_COMMON = new Set([
     'kind', 'name', 'description', 'whenToUse', 'tier', 'summary', 'params', 'output', 'effects',
 ]);
-const PLUGIN_LEAF_KEYS = new Set([...LEAF_KEYS_COMMON, 'outputKind']);
-const CONFIGURED_LEAF_KEYS = new Set([...LEAF_KEYS_COMMON, 'rest']);
+const EXEC_LEAF_KEYS = new Set([...LEAF_KEYS_COMMON, 'outputKind']);
+const HTTP_LEAF_KEYS = new Set([...LEAF_KEYS_COMMON, 'rest']);
 const ROOT_ENTRY_KEYS = new Set(['concept', 'description', 'whenToUse']);
 const FILE_ENCODINGS = new Set(['text', 'base64']);
 const PARAM_KEYS_BY_KIND = {
@@ -342,107 +335,97 @@ function checkCommon(raw, path, issue) {
     }
     return true;
 }
-// ---------------------------------------------------------------------------
-// Node validators (plugin and configured CLI dialects)
-// ---------------------------------------------------------------------------
-/** Validate a node for the plugin dialect (leaf must have outputKind: 'object'). */
-export function validatePluginNode(raw, path, topLevel, issue) {
+export function validateCommandNode(raw, path, topLevel, transport, issue) {
+    const pathString = path.join('.');
     if (!isObject(raw)) {
-        issue('command_node_invalid', `node must be an object`, typeName(raw), 'a branch or leaf node object', 'Fix the node.', path);
+        issue('command_node_invalid', 'node must be an object', typeName(raw), 'a branch or leaf node object', 'Fix the node.', pathString);
         return null;
     }
     const kind = raw['kind'];
     if (kind === 'branch')
-        return validatePluginBranch(raw, path, topLevel, issue);
+        return validateBranch(raw, pathString, topLevel, transport, issue);
     if (kind === 'leaf') {
         if (topLevel) {
-            issue('command_node_invalid', `top-level node must be a branch`, 'leaf', 'a branch node with a rootEntry', 'Wrap the command in a top-level branch (noun) with a rootEntry.', `${path}.kind`);
+            issue('command_node_invalid', 'top-level node must be a branch', 'leaf', 'a branch node with a rootEntry', 'Wrap the command in a top-level branch (noun) with a rootEntry.', `${pathString}.kind`);
             return null;
         }
-        return validatePluginLeaf(raw, path, issue);
+        return validateLeaf(raw, pathString, transport, issue);
     }
-    issue('command_node_invalid', `node kind must be "branch" or "leaf"`, String(kind), 'branch | leaf', 'Set kind to branch or leaf.', `${path}.kind`);
+    issue('command_node_invalid', 'node kind must be "branch" or "leaf"', String(kind), 'branch | leaf', 'Set kind to branch or leaf.', `${pathString}.kind`);
     return null;
 }
-function validatePluginBranch(raw, path, topLevel, issue) {
-    if (!checkKeys(raw, PLUGIN_BRANCH_KEYS, path, issue))
+function validateBranch(raw, path, topLevel, transport, issue) {
+    if (!checkKeys(raw, transport === 'exec' ? EXEC_BRANCH_KEYS : BRANCH_KEYS, path, issue))
         return null;
     if (!checkCommon(raw, path, issue))
         return null;
     const hasRoot = raw['rootEntry'] !== undefined;
     if (topLevel && !hasRoot) {
-        issue('command_node_invalid', `top-level branch requires a rootEntry`, '(missing)', 'a rootEntry { concept, description, whenToUse }', 'Add a rootEntry to the top-level branch.', `${path}.rootEntry`);
+        issue('command_node_invalid', 'top-level branch requires a rootEntry', '(missing)', 'a rootEntry { concept, description, whenToUse }', 'Add a rootEntry to the top-level branch.', `${path}.rootEntry`);
         return null;
     }
     if (!topLevel && hasRoot) {
-        issue('command_node_invalid', `nested branch must not declare a rootEntry`, 'rootEntry', 'no rootEntry (only top-level branches carry one)', 'Remove rootEntry from the nested branch.', `${path}.rootEntry`);
+        issue('command_node_invalid', 'nested branch must not declare a rootEntry', 'rootEntry', 'no rootEntry (only top-level branches carry one)', 'Remove rootEntry from the nested branch.', `${path}.rootEntry`);
         return null;
     }
     let rootEntry;
     if (hasRoot) {
-        const re = validateRootEntry(raw['rootEntry'], `${path}.rootEntry`, issue);
-        if (re === null)
+        const validatedRootEntry = validateRootEntry(raw['rootEntry'], `${path}.rootEntry`, issue);
+        if (validatedRootEntry === null)
             return null;
-        rootEntry = re;
+        rootEntry = validatedRootEntry;
     }
     if (typeof raw['summary'] !== 'string' || raw['summary'].length === 0) {
-        issue('command_node_invalid', `branch summary must be a non-empty string`, typeName(raw['summary']), 'a one-line summary string', 'Add a summary.', `${path}.summary`);
+        issue('command_node_invalid', 'branch summary must be a non-empty string', typeName(raw['summary']), 'a one-line summary string', 'Add a summary.', `${path}.summary`);
         return null;
     }
     if (raw['model'] !== undefined && typeof raw['model'] !== 'string') {
-        issue('command_node_invalid', `branch model must be a string`, typeName(raw['model']), 'a string or omitted', 'Fix or remove model.', `${path}.model`);
+        issue('command_node_invalid', 'branch model must be a string', typeName(raw['model']), 'a string or omitted', 'Fix or remove model.', `${path}.model`);
         return null;
     }
     let passthrough;
-    if (raw['passthrough'] !== undefined) {
-        const pt = validatePassthrough(raw['passthrough'], `${path}.passthrough`, issue);
-        if (pt === null)
+    if (transport === 'exec' && raw['passthrough'] !== undefined) {
+        const validated = validatePassthrough(raw['passthrough'], `${path}.passthrough`, issue);
+        if (validated === null)
             return null;
-        passthrough = pt;
+        passthrough = validated;
     }
     const children = raw['children'];
     if (passthrough !== undefined) {
-        // A passthrough branch intercepts every argv token after it, so a child
-        // would be unreachable — declare the emptiness rather than implying it.
         if (!Array.isArray(children) || children.length !== 0) {
-            issue('command_node_invalid', `a passthrough branch must declare children: []`, Array.isArray(children) ? `${children.length} children` : typeName(children), 'an empty children array', 'Set children to [] — a passthrough branch forwards all argv and can own no subcommands.', `${path}.children`);
+            issue('command_node_invalid', 'a passthrough branch must declare children: []', Array.isArray(children) ? `${children.length} children` : typeName(children), 'an empty children array', 'Set children to [] — a passthrough branch forwards all argv and can own no subcommands.', `${path}.children`);
             return null;
         }
     }
-    else if (!Array.isArray(children) || children.length === 0) {
-        issue('command_node_invalid', `branch children must be a non-empty array`, typeName(children), 'a non-empty array of branch/leaf nodes', 'Add at least one child.', `${path}.children`);
+    else if (!Array.isArray(children)) {
+        issue('command_node_invalid', 'branch children must be an array', typeName(children), 'an array of branch/leaf nodes (may be empty for populated by mounts)', 'Fix children.', `${path}.children`);
         return null;
     }
     const validated = [];
     const childNames = new Set();
     for (let i = 0; i < children.length; i++) {
-        const c = validatePluginNode(children[i], `${path}.children[${i}]`, false, issue);
-        if (c === null)
+        const child = validateCommandNode(children[i], [...path.split('.'), `children[${i}]`], false, transport, issue);
+        if (child === null)
             return null;
-        if (childNames.has(c.name)) {
-            issue('command_node_invalid', `duplicate child name`, c.name, 'unique child names within a branch', 'Rename the duplicate child.', `${path}.children[${i}].name`);
+        if (childNames.has(child.name)) {
+            issue('command_node_invalid', 'duplicate child name', child.name, 'unique child names within a branch', 'Rename the duplicate child.', `${path}.children[${i}].name`);
             return null;
         }
-        childNames.add(c.name);
-        validated.push(c);
+        childNames.add(child.name);
+        validated.push(child);
     }
     return {
-        kind: 'branch',
-        name: raw['name'],
-        description: raw['description'],
-        whenToUse: raw['whenToUse'],
+        kind: 'branch', name: raw['name'], description: raw['description'], whenToUse: raw['whenToUse'],
         ...(raw['tier'] !== undefined ? { tier: raw['tier'] } : {}),
-        ...(rootEntry !== undefined ? { rootEntry } : {}),
-        summary: raw['summary'],
+        ...(rootEntry !== undefined ? { rootEntry } : {}), summary: raw['summary'],
         ...(raw['model'] !== undefined ? { model: raw['model'] } : {}),
-        ...(passthrough !== undefined ? { passthrough } : {}),
-        children: validated,
+        ...(passthrough !== undefined ? { passthrough } : {}), children: validated,
     };
 }
 /** `passthrough: { bin, installHint }` — both required non-empty strings. */
 function validatePassthrough(raw, path, issue) {
     if (!isObject(raw)) {
-        issue('command_node_invalid', `passthrough must be an object`, typeName(raw), 'an object { bin, installHint }', 'Fix or remove passthrough.', path);
+        issue('command_node_invalid', 'passthrough must be an object', typeName(raw), 'an object { bin, installHint }', 'Fix or remove passthrough.', path);
         return null;
     }
     if (!checkKeys(raw, PASSTHROUGH_KEYS, path, issue))
@@ -455,133 +438,21 @@ function validatePassthrough(raw, path, issue) {
     }
     return { bin: raw['bin'], installHint: raw['installHint'] };
 }
-function validatePluginLeaf(raw, path, issue) {
-    if (!checkKeys(raw, PLUGIN_LEAF_KEYS, path, issue))
-        return null;
-    if (!checkCommon(raw, path, issue))
-        return null;
-    if (typeof raw['summary'] !== 'string' || raw['summary'].length === 0) {
-        issue('command_node_invalid', `leaf summary must be a non-empty string`, typeName(raw['summary']), 'a one-line summary string', 'Add a summary.', `${path}.summary`);
-        return null;
-    }
-    if (raw['outputKind'] !== 'object') {
-        issue('command_node_invalid', `leaf outputKind must be "object" in v1`, String(raw['outputKind']), 'exactly "object"', 'Set outputKind to "object".', `${path}.outputKind`);
-        return null;
-    }
-    const params = validateParams(raw['params'], `${path}.params`, issue);
-    if (params === null)
-        return null;
-    const output = validateOutput(raw['output'], `${path}.output`, issue);
-    if (output === null)
-        return null;
-    const effects = raw['effects'];
-    if (!Array.isArray(effects) || effects.length === 0 || !effects.every((e) => typeof e === 'string')) {
-        issue('command_node_invalid', `leaf effects must be a non-empty string array`, typeName(effects), 'a non-empty array of strings (["None. Read-only."] for read-only leaves)', 'Declare every persistent effect.', `${path}.effects`);
-        return null;
-    }
-    return {
-        kind: 'leaf',
-        name: raw['name'],
-        description: raw['description'],
-        whenToUse: raw['whenToUse'],
-        ...(raw['tier'] !== undefined ? { tier: raw['tier'] } : {}),
-        summary: raw['summary'],
-        params,
-        output,
-        outputKind: 'object',
-        effects: effects,
-    };
-}
-/** Validate a node for the configured CLI dialect (leaf must have rest). */
-export function validateConfiguredCliNode(raw, path, topLevel, issue) {
-    if (!isObject(raw)) {
-        issue('command_node_invalid', `node must be an object`, typeName(raw), 'a branch or leaf node object', 'Fix the node.', path);
-        return null;
-    }
-    const kind = raw['kind'];
-    if (kind === 'branch')
-        return validateConfiguredCliBranch(raw, path, topLevel, issue);
-    if (kind === 'leaf') {
-        if (topLevel) {
-            issue('command_node_invalid', `top-level node must be a branch`, 'leaf', 'a branch node with a rootEntry', 'Wrap the command in a top-level branch (noun) with a rootEntry.', `${path}.kind`);
-            return null;
-        }
-        return validateConfiguredCliLeaf(raw, path, issue);
-    }
-    issue('command_node_invalid', `node kind must be "branch" or "leaf"`, String(kind), 'branch | leaf', 'Set kind to branch or leaf.', `${path}.kind`);
-    return null;
-}
-function validateConfiguredCliBranch(raw, path, topLevel, issue) {
-    if (!checkKeys(raw, BRANCH_KEYS, path, issue))
+function validateLeaf(raw, path, transport, issue) {
+    if (!checkKeys(raw, transport === 'exec' ? EXEC_LEAF_KEYS : HTTP_LEAF_KEYS, path, issue))
         return null;
     if (!checkCommon(raw, path, issue))
         return null;
-    const hasRoot = raw['rootEntry'] !== undefined;
-    if (topLevel && !hasRoot) {
-        issue('command_node_invalid', `top-level branch requires a rootEntry`, '(missing)', 'a rootEntry { concept, description, whenToUse }', 'Add a rootEntry to the top-level branch.', `${path}.rootEntry`);
-        return null;
-    }
-    if (!topLevel && hasRoot) {
-        issue('command_node_invalid', `nested branch must not declare a rootEntry`, 'rootEntry', 'no rootEntry (only top-level branches carry one)', 'Remove rootEntry from the nested branch.', `${path}.rootEntry`);
-        return null;
-    }
-    let rootEntry;
-    if (hasRoot) {
-        const re = validateRootEntry(raw['rootEntry'], `${path}.rootEntry`, issue);
-        if (re === null)
-            return null;
-        rootEntry = re;
-    }
     if (typeof raw['summary'] !== 'string' || raw['summary'].length === 0) {
-        issue('command_node_invalid', `branch summary must be a non-empty string`, typeName(raw['summary']), 'a one-line summary string', 'Add a summary.', `${path}.summary`);
+        issue('command_node_invalid', 'leaf summary must be a non-empty string', typeName(raw['summary']), 'a one-line summary string', 'Add a summary.', `${path}.summary`);
         return null;
     }
-    if (raw['model'] !== undefined && typeof raw['model'] !== 'string') {
-        issue('command_node_invalid', `branch model must be a string`, typeName(raw['model']), 'a string or omitted', 'Fix or remove model.', `${path}.model`);
-        return null;
-    }
-    const children = raw['children'];
-    if (!Array.isArray(children)) {
-        issue('command_node_invalid', `branch children must be an array`, typeName(children), 'an array of branch/leaf nodes (may be empty for populated by mounts)', 'Fix children.', `${path}.children`);
-        return null;
-    }
-    const validated = [];
-    const childNames = new Set();
-    for (let i = 0; i < children.length; i++) {
-        const c = validateConfiguredCliNode(children[i], `${path}.children[${i}]`, false, issue);
-        if (c === null)
-            return null;
-        if (childNames.has(c.name)) {
-            issue('command_node_invalid', `duplicate child name`, c.name, 'unique child names within a branch', 'Rename the duplicate child.', `${path}.children[${i}].name`);
-            return null;
-        }
-        childNames.add(c.name);
-        validated.push(c);
-    }
-    return {
-        kind: 'branch',
-        name: raw['name'],
-        description: raw['description'],
-        whenToUse: raw['whenToUse'],
-        ...(raw['tier'] !== undefined ? { tier: raw['tier'] } : {}),
-        ...(rootEntry !== undefined ? { rootEntry } : {}),
-        summary: raw['summary'],
-        ...(raw['model'] !== undefined ? { model: raw['model'] } : {}),
-        children: validated,
-    };
-}
-function validateConfiguredCliLeaf(raw, path, issue) {
-    if (!checkKeys(raw, CONFIGURED_LEAF_KEYS, path, issue))
-        return null;
-    if (!checkCommon(raw, path, issue))
-        return null;
-    if (typeof raw['summary'] !== 'string' || raw['summary'].length === 0) {
-        issue('command_node_invalid', `leaf summary must be a non-empty string`, typeName(raw['summary']), 'a one-line summary string', 'Add a summary.', `${path}.summary`);
+    if (transport === 'exec' && raw['outputKind'] !== 'object') {
+        issue('command_node_invalid', 'leaf outputKind must be "object" in v1', String(raw['outputKind']), 'exactly "object"', 'Set outputKind to "object".', `${path}.outputKind`);
         return null;
     }
-    // Configured CLI leaves require `rest`, not `outputKind`
-    if (raw['rest'] === undefined) {
-        issue('command_node_invalid', `configured CLI leaf requires a rest mapping`, '(missing)', 'a rest object with method, path, and params', 'Add a rest mapping.', `${path}.rest`);
+    if (transport === 'http' && raw['rest'] === undefined) {
+        issue('command_node_invalid', 'HTTP leaf requires a rest mapping', '(missing)', 'a rest object with method, path, and params', 'Add a rest mapping.', `${path}.rest`);
         return null;
     }
     const params = validateParams(raw['params'], `${path}.params`, issue);
@@ -591,26 +462,16 @@ function validateConfiguredCliLeaf(raw, path, issue) {
     if (output === null)
         return null;
     const effects = raw['effects'];
-    if (!Array.isArray(effects) || effects.length === 0 || !effects.every((e) => typeof e === 'string')) {
-        issue('command_node_invalid', `leaf effects must be a non-empty string array`, typeName(effects), 'a non-empty array of strings (["None. Read-only."] for read-only leaves)', 'Declare every persistent effect.', `${path}.effects`);
+    if (!Array.isArray(effects) || effects.length === 0 || !effects.every((effect) => typeof effect === 'string')) {
+        issue('command_node_invalid', 'leaf effects must be a non-empty string array', typeName(effects), 'a non-empty array of strings (["None. Read-only."] for read-only leaves)', 'Declare every persistent effect.', `${path}.effects`);
         return null;
     }
-    // Validate the REST mapping (includes coalesced body source rule)
+    const base = { kind: 'leaf', name: raw['name'], description: raw['description'], whenToUse: raw['whenToUse'],
+        ...(raw['tier'] !== undefined ? { tier: raw['tier'] } : {}), summary: raw['summary'], params, output, effects: effects };
+    if (transport === 'exec')
+        return { ...base, outputKind: 'object' };
     const rest = validateRestMapping(raw['rest'], path, params, issue);
-    if (rest === null)
-        return null;
-    return {
-        kind: 'leaf',
-        name: raw['name'],
-        description: raw['description'],
-        whenToUse: raw['whenToUse'],
-        ...(raw['tier'] !== undefined ? { tier: raw['tier'] } : {}),
-        summary: raw['summary'],
-        params,
-        output,
-        effects: effects,
-        rest,
-    };
+    return rest === null ? null : { ...base, rest };
 }
 // ---------------------------------------------------------------------------
 // REST mapping validation (§4.4)

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

@@ -1,11 +1,5 @@
 import type { BranchDef } from '../command.js';
 import type { CommandRegistrySnapshot } from '../command-manifests/registry.js';
 import type { ValidatedContribution } from './discovery.js';
-/** Adapt legacy ValidatedContribution (plugin format) to transport-neutral
- *  CommandContribution. Returns a snapshot conforming to the unified registry
- *  contract, with an adaptLeaf callback that wraps executeExternalLeaf. */
 export declare function adaptPluginContributions(contributions: ValidatedContribution[]): CommandRegistrySnapshot;
-/** Map an accepted registry snapshot to real top-level BranchDefs, ready to
- *  concatenate beside core subtrees in `buildRoot()`. Consumes transport-neutral
- *  CommandContribution entries from a unified registry snapshot. */
 export declare function composeExternalSubtrees(snapshot: CommandRegistrySnapshot): BranchDef[];

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

@@ -1,88 +1,41 @@
-// Tree composer — adapt transport-neutral contributions into ordinary crtr
-// BranchDef/LeafDef values via the SAME defineBranch/defineRoot path core uses,
-// so external contributions get child-owned parent representations and the
-// existing help renderer with no second help engine. External nodes are
-// static-only (no dynamicState, no custom renderer); each leaf's run closure is
-// supplied by the contribution's adaptLeaf callback. Composition is deterministic:
-// contributions arrive already sorted by name from registry resolution.
 import { defineBranch, defineLeaf } from '../command.js';
-import { executeExternalLeaf } from './adapter.js';
-/** Adapt legacy ValidatedContribution (plugin format) to transport-neutral
- *  CommandContribution. Returns a snapshot conforming to the unified registry
- *  contract, with an adaptLeaf callback that wraps executeExternalLeaf. */
+import { executeExternalLeaf } from './transport/exec-invoke.js';
+import { invokeHttpLeaf } from './transport/http-invoke.js';
 export function adaptPluginContributions(contributions) {
-    const adapted = contributions.map((vc) => ({
-        contributor: {
-            kind: 'plugin',
-            name: vc.plugin.name,
-            scope: vc.plugin.scope, // plugins are never builtin
-        },
-        node: vc.node,
-        adaptLeaf: (leaf, commandPath) => ({
-            outputKind: 'object',
-            run: async (input) => executeExternalLeaf({
-                plugin: vc.plugin,
-                // Discovery rejects a leaf-bearing manifest that omits `executable`,
-                // so a contribution reaching adaptLeaf always carries one.
-                executable: vc.executable,
-                commandPath: Array.from(commandPath),
-                output: leaf.output,
-            }, input),
-        }),
-    }));
     return {
-        contributions: adapted,
+        contributions: contributions.map((contribution) => ({
+            contributor: { name: contribution.plugin.name, scope: contribution.plugin.scope },
+            node: contribution.node,
+            adaptLeaf: (leaf, commandPath) => {
+                const transport = contribution.transport;
+                if (transport.kind === 'exec')
+                    return {
+                        outputKind: 'object',
+                        run: async (input) => executeExternalLeaf({ plugin: contribution.plugin, executable: transport.executable, commandPath: [...commandPath], output: leaf.output }, input),
+                    };
+                const httpLeaf = leaf;
+                return {
+                    outputKind: httpLeaf.rest.streaming === true ? 'jsonl' : 'object',
+                    run: (input, context) => invokeHttpLeaf({
+                        registration: { name: contribution.plugin.name, endpoint: transport.endpoint, ...(transport.authEnv !== undefined ? { authEnv: transport.authEnv } : {}) },
+                        ...(contribution.manifest?.baseUrl !== undefined ? { baseUrl: contribution.manifest.baseUrl } : {}),
+                        ...(contribution.manifest?.timeouts !== undefined ? { timeouts: contribution.manifest.timeouts } : {}),
+                        params: httpLeaf.params, rest: httpLeaf.rest, output: httpLeaf.output, commandPath: [...commandPath],
+                    }, input, context),
+                };
+            },
+        })),
         issues: [],
     };
 }
-/** Map an accepted registry snapshot to real top-level BranchDefs, ready to
- *  concatenate beside core subtrees in `buildRoot()`. Consumes transport-neutral
- *  CommandContribution entries from a unified registry snapshot. */
 export function composeExternalSubtrees(snapshot) {
-    return snapshot.contributions.map((c) => buildBranch(c, c.node, [c.node.name]));
+    return snapshot.contributions.map((contribution) => buildBranch(contribution, contribution.node, [contribution.node.name]));
 }
 function buildBranch(contribution, node, path) {
-    const rootEntry = node.rootEntry !== undefined
-        ? {
-            concept: node.rootEntry.concept,
-            // Explicit field mapping: declarative description→desc, whenToUse→useWhen.
-            desc: node.rootEntry.description,
-            useWhen: node.rootEntry.whenToUse,
-        }
-        : undefined;
-    return defineBranch({
-        name: node.name,
-        description: node.description,
-        whenToUse: node.whenToUse,
-        ...(node.tier !== undefined ? { tier: node.tier } : {}),
-        ...(rootEntry !== undefined ? { rootEntry } : {}),
-        ...(node.passthrough !== undefined ? { passthrough: node.passthrough } : {}),
-        help: {
-            name: path.join(' '),
-            summary: node.summary,
-            ...(node.model !== undefined ? { model: node.model } : {}),
-        },
-        children: node.children.map((child) => child.kind === 'branch'
-            ? buildBranch(contribution, child, [...path, child.name])
-            : buildLeaf(contribution, child, [...path, child.name])),
-    });
+    const rootEntry = node.rootEntry === undefined ? undefined : { concept: node.rootEntry.concept, desc: node.rootEntry.description, useWhen: node.rootEntry.whenToUse };
+    return defineBranch({ name: node.name, description: node.description, whenToUse: node.whenToUse, ...(node.tier !== undefined ? { tier: node.tier } : {}), ...(rootEntry !== undefined ? { rootEntry } : {}), help: { name: path.join(' '), summary: node.summary, ...(node.model !== undefined ? { model: node.model } : {}) }, ...(node.passthrough !== undefined ? { passthrough: node.passthrough } : {}), children: node.children.map((child) => child.kind === 'branch' ? buildBranch(contribution, child, [...path, child.name]) : buildLeaf(contribution, child, [...path, child.name])) });
 }
 function buildLeaf(contribution, node, path) {
-    // Use the contribution's adapter to get the outputKind and run implementation.
     const adapted = contribution.adaptLeaf(node, path);
-    return defineLeaf({
-        name: node.name,
-        description: node.description,
-        whenToUse: node.whenToUse,
-        ...(node.tier !== undefined ? { tier: node.tier } : {}),
-        help: {
-            name: path.join(' '),
-            summary: node.summary,
-            params: node.params,
-            output: node.output,
-            outputKind: adapted.outputKind,
-            effects: node.effects,
-        },
-        run: adapted.run,
-    });
+    return defineLeaf({ name: node.name, description: node.description, whenToUse: node.whenToUse, ...(node.tier !== undefined ? { tier: node.tier } : {}), help: { name: path.join(' '), summary: node.summary, params: node.params, output: node.output, outputKind: adapted.outputKind, effects: node.effects }, run: adapted.run });
 }

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

@@ -1,74 +1,41 @@
-import type { InstalledPlugin } from '../../types.js';
-import { type DeclBranch as DeclBranchGeneric, type PluginDeclLeaf, type CommandManifestIssue } from '../command-manifests/schema.js';
-/** A stable, doctor-renderable validation issue. Never thrown — accumulated
- *  and surfaced through `pkg plugin show` / `sys doctor`. */
+import type { InstalledPlugin, PluginTransport } from '../../types.js';
+import { type ValidatedCommandManifest } from '../command-manifests/manifest.js';
+import type { CommandManifestIssue, DeclBranch as DeclBranchGeneric, DeclLeaf as DeclLeafGeneric } from '../command-manifests/schema.js';
+import type { CommandRegistrySnapshot } from '../command-manifests/registry.js';
+import type { HttpPluginManifestStore } from './store.js';
 export interface CommandDiscoveryIssue extends CommandManifestIssue {
-    /** The offending plugin's name. */
     plugin: string;
 }
-export type { DeclRootEntry } from '../command-manifests/schema.js';
-export type { CommandIssueCode } from '../command-manifests/schema.js';
-export type DeclLeaf = PluginDeclLeaf;
-export type DeclBranch = DeclBranchGeneric<PluginDeclLeaf>;
-export type DeclNode = DeclBranchGeneric<PluginDeclLeaf> | PluginDeclLeaf;
-/** One accepted top-level contribution: a validated branch node plus the
- *  plugin identity and canonical executable the adapter needs at run time. */
+export type { DeclRootEntry, CommandIssueCode, TransportKind } from '../command-manifests/schema.js';
+export type DeclLeaf = DeclLeafGeneric;
+export type DeclBranch = DeclBranchGeneric<DeclLeafGeneric>;
+export type DeclNode = DeclBranch | DeclLeaf;
 export interface ValidatedContribution {
     plugin: InstalledPlugin;
-    /** Absolute, realpath-resolved executable path. Absent only for a manifest
-     *  that declares no leaf at all — a passthrough-only contribution execs the
-     *  external binary it names and never speaks the leaf protocol. */
-    executable?: string;
-    /** The validated top-level branch node (always kind 'branch'). */
-    node: DeclBranchGeneric<PluginDeclLeaf>;
+    transport: PluginTransport;
+    node: DeclBranchGeneric<DeclLeafGeneric>;
+    manifest: ValidatedCommandManifest;
 }
-/** Per-plugin validation result — the Phase 2 lifecycle entry point. Reports
- *  accepted contributions and every issue without executing the binary. */
 export interface PluginCommandValidation {
     plugin: InstalledPlugin;
-    /** Absolute path to the plugin's commands.json (whether or not it loaded). */
     manifestPath: string;
-    /** Absolute, resolved executable path when it passed path/exec-bit safety. */
-    executable?: string;
+    transport?: PluginTransport;
     contributions: ValidatedContribution[];
     issues: CommandDiscoveryIssue[];
+    absentStore?: boolean;
+    httpManifestStore?: HttpPluginManifestStore;
 }
-/** The invocation-local registry snapshot the tree composer consumes. */
-export interface CommandRegistrySnapshot {
-    /** Accepted top-level contributions, deterministically ordered by name. */
-    contributions: ValidatedContribution[];
-    /** Every discovery issue across all effective command plugins. */
-    issues: CommandDiscoveryIssue[];
+export interface AbsentStoreHydration {
+    hydratedAny: boolean;
+    diagnostics: string[];
 }
-/** The effective, deduped set of enabled plugins that declare a command
- *  manifest, in scope-precedence order. Enumerated with existing machinery
- *  only: `projectScopeRoots()` (profile-widened, nearest-first) via
- *  `listInstalledPluginsInRoot('project', root)`, then user scope. Dedup is by
- *  plugin NAME across ALL copies (highest precedence wins) BEFORE the enabled
- *  filter — so a disabled higher-precedence copy suppresses lower-precedence
- *  copies of the same name. */
 export declare function effectiveCommandPlugins(startDir?: string, profileId?: string | null): InstalledPlugin[];
-/** Get raw plugin candidates before the cross-plugin collision pass.
- *  Each plugin validation includes its contributions and per-plugin issues;
- *  call resolveCommandRegistry (or a later unified collision handler) to
- *  produce the final snapshot with cross-plugin collision detection. */
+export declare function validatePluginCommands(plugin: InstalledPlugin, reservedNames?: ReadonlySet<string>): PluginCommandValidation;
 export declare function discoverPluginCommandCandidates(startDir?: string, profileId?: string | null): PluginCommandValidation[];
-/** Validate every effective command plugin and compose an invocation-local
- *  registry snapshot. `reservedNames` are the core top-level subtree names —
- *  a contribution claiming one is silently skipped from the tree and recorded
- *  as a `command_collision` issue (core always wins). A plugin-vs-plugin
- *  top-level name collision drops all claimants with an issue. Accepted
- *  contributions are sorted by name for deterministic help/order. */
-export declare function discoverCommandContributions(reservedNames: ReadonlySet<string>, startDir?: string, profileId?: string | null): CommandRegistrySnapshot;
-/** Validate every effective command plugin, including the cross-plugin
- *  top-level name collision pass: a name claimed by more than one plugin is
- *  dropped from EVERY claimant's contributions and a `command_collision`
- *  issue is recorded on EACH claimant's validation, so per-plugin surfaces
- *  (`sys doctor`, `pkg plugin show`) see it too. This is the entry point for
- *  any surface that reports on mounted commands — the per-plugin
- *  `validatePluginCommands` cannot see other plugins' claims. */
 export declare function validateEffectiveCommandPlugins(reservedNames: ReadonlySet<string>, startDir?: string, profileId?: string | null): PluginCommandValidation[];
-/** Validate one plugin's command manifest without executing its binary.
- *  `reservedNames` are the core top-level names used for the core-collision
- *  check; pass an empty set to skip it. Never throws. */
-export declare function validatePluginCommands(plugin: InstalledPlugin, reservedNames?: ReadonlySet<string>): PluginCommandValidation;
+export declare function discoverCommandContributions(reservedNames: ReadonlySet<string>, startDir?: string, profileId?: string | null): {
+    contributions: ValidatedContribution[];
+    issues: CommandDiscoveryIssue[];
+};
+export declare function buildExternalCommandSnapshot(reservedCoreNames: ReadonlySet<string>): CommandRegistrySnapshot;
+export declare function hydrateAbsentHttpPlugins(): Promise<AbsentStoreHydration>;