@north-light/api 0.3.580 → 0.3.587

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

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

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

@@ -0,0 +1,118 @@
+// Unified command registry: transport-neutral collision resolution and
+// contributor attribution. This module takes raw candidates (from plugins,
+// HTTP-transport plugins, or any external source) and runs one unified pass that:
+//
+// 1. Detects top-level collisions between plugins.
+// 2. Keeps every plugin claimant by mounting it at <origin>:<command>.
+// 3. Records an informational issue on every qualified claimant.
+// 4. Gives core absolute precedence and drops core-name claimants.
+// 5. Returns a deterministically ordered, collision-resolved snapshot.
+//
+// The registry itself is transport-neutral: it knows nothing about plugin
+// executables or HTTP invokers. Each contribution carries its own adapter
+// callback, which the tree composer invokes to turn a leaf into a real crtr
+// LeafDef.
+/** The stable source name used to qualify a colliding plugin command. */
+export function commandContributorOrigin(contributor) {
+    return contributor.sourceMarketplace ?? contributor.name;
+}
+/** The top-level name assigned to a plugin command that collides with another
+ * plugin command. */
+export function qualifiedTopLevelCommandName(contributor, commandName) {
+    return `${commandContributorOrigin(contributor)}:${commandName}`;
+}
+/** Resolve a flat list of candidate contributions into a collision-resolved
+ *  snapshot. Plugin claimants at a collided path are qualified by origin and
+ *  kept; core names take precedence and are dropped. An issue is recorded on
+ *  every claimant, and results are deterministically ordered by contributor
+ *  name. */
+export function resolveCommandRegistry(candidates, reservedCoreNames) {
+    const collisions = new Map();
+    const contributionsByPath = new Map();
+    // Phase 1: Detect collisions. A core collision drops the plugin claimant;
+    // a cross-plugin collision qualifies every claimant in phase 2.
+    for (const contrib of candidates) {
+        const { node, contributor } = contrib;
+        const path = [node.name];
+        const pathKey = path.join('/');
+        // Check for core collision at top level.
+        if (reservedCoreNames.has(node.name)) {
+            collisions.set(pathKey, {
+                path,
+                claimants: [contrib],
+                isCoreCollision: true,
+            });
+            continue;
+        }
+        // Check for cross-contributor collision.
+        if (contributionsByPath.has(pathKey)) {
+            const existing = contributionsByPath.get(pathKey);
+            const key = collisions.get(pathKey);
+            if (key === undefined) {
+                collisions.set(pathKey, {
+                    path,
+                    claimants: [existing, contrib],
+                    isCoreCollision: false,
+                });
+            }
+            else {
+                key.claimants.push(contrib);
+            }
+        }
+        else {
+            contributionsByPath.set(pathKey, contrib);
+        }
+    }
+    // Phase 2: Build the final snapshot. Core collisions are dropped; plugin
+    // collisions keep every claimant under its origin-qualified command name.
+    const accepted = [];
+    const issues = [];
+    for (const contrib of candidates) {
+        const pathKey = [contrib.node.name].join('/');
+        if (collisions.has(pathKey)) {
+            const collision = collisions.get(pathKey);
+            const claimantNames = collision.claimants.map((c) => c.contributor.name).join(', ');
+            // A core collision has exactly one claimant contesting a reserved
+            // built-in name. Plugin collisions are informative: every claimant is
+            // retained under the source-qualified name reported here.
+            if (collision.isCoreCollision) {
+                issues.push({
+                    code: 'command_collision',
+                    contributor: contrib.contributor,
+                    path: contrib.node.name,
+                    message: `top-level command "${contrib.node.name}" collides with a crtr core command and is dropped`,
+                    received: claimantNames,
+                    expected: 'no top-level command name matching a reserved core command',
+                    next: `Rename "${contrib.node.name}" to a name that does not collide with core.`,
+                });
+            }
+            else {
+                const qualifiedName = qualifiedTopLevelCommandName(contrib.contributor, contrib.node.name);
+                accepted.push({ ...contrib, node: { ...contrib.node, name: qualifiedName } });
+                issues.push({
+                    code: 'command_collision',
+                    contributor: contrib.contributor,
+                    path: contrib.node.name,
+                    message: `top-level command "${contrib.node.name}" is claimed by ${claimantNames} — mounted as "${qualifiedName}"`,
+                    received: claimantNames,
+                    expected: 'an origin-qualified top-level command for each claimant',
+                    next: `Invoke "${qualifiedName}" to use this plugin command.`,
+                });
+            }
+        }
+        else {
+            // Not collided — accept it.
+            accepted.push(contrib);
+        }
+    }
+    // Phase 3: Sort accepted contributions deterministically by contributor
+    // name (then by node name for secondary ordering, though each contributor
+    // should have at most one top-level contribution).
+    accepted.sort((a, b) => a.contributor.name.localeCompare(b.contributor.name) ||
+        a.node.name.localeCompare(b.node.name));
+    return {
+        contributions: accepted,
+        coreMounts: [],
+        issues,
+    };
+}

package/dist/core/command-plugins/caller-header.d.ts

@@ -0,0 +1,10 @@
+export interface CrtrCallerFields {
+    node?: string | undefined;
+    machine?: string | undefined;
+    profile?: string | undefined;
+    run?: string | undefined;
+}
+/** `node=<id>; machine=<id>; profile=<id>; run=<id>`, in that order. A field
+ *  that is empty, or whose value holds `;`, `=`, CR or LF, is left out rather
+ *  than injected into the header. Returns '' when no field remains. */
+export declare function formatCrtrCaller(fields: CrtrCallerFields): string;

package/dist/core/command-plugins/caller-header.js

@@ -0,0 +1,15 @@
+// The `Crtr-Caller` request header: who is behind a plugin call. Canvas-free so
+// the CLI and the daemon share one formatter.
+/** `node=<id>; machine=<id>; profile=<id>; run=<id>`, in that order. A field
+ *  that is empty, or whose value holds `;`, `=`, CR or LF, is left out rather
+ *  than injected into the header. Returns '' when no field remains. */
+export function formatCrtrCaller(fields) {
+    const parts = [];
+    for (const key of ['node', 'machine', 'profile', 'run']) {
+        const value = fields[key];
+        if (typeof value !== 'string' || value === '' || /[;=\r\n]/.test(value))
+            continue;
+        parts.push(`${key}=${value}`);
+    }
+    return parts.join('; ');
+}

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/description.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,241 @@
+import { resolve } from 'node:path';
+import { ExitCode } from '../../types.js';
+import { envNodeId } from '../../shared/env.js';
+import { cliClient } from '../../commands/api-client.js';
+import { apiErrorToCliError } from '../io.js';
+import { ApiError } from '../../api/index.js';
+import { defineBranch, defineLeaf } from '../command.js';
+import { qualifiedTopLevelCommandName, resolveCommandRegistry } from '../command-manifests/registry.js';
+import { executeExternalLeaf } from './transport/exec-invoke.js';
+import { invokeHttpLeaf } from './transport/http-invoke.js';
+import { readPathParam } from './transport/http-plan.js';
+import { sha256Hex, signedHeaderDigest } from './transport/sign.js';
+import { needsAppToken } from '../plugin-objects-manifest.js';
+/** The daemon checks scope again at dispatch. This list controls only help. */
+async function allowedProviderTools(id) {
+    const response = await cliClient().request('GET', `/v1/providers/${encodeURIComponent(id)}/tools`);
+    return new Set(response.groups.flatMap((group) => group.leaves.map((leaf) => leaf.tool)));
+}
+function hasAllowedLeaf(branch, relative, allowed) {
+    return branch.children.some((child) => child.kind === 'leaf'
+        ? allowed.has([...relative, child.name].join(' '))
+        : hasAllowedLeaf(child, [...relative, child.name], allowed));
+}
+function visibleChildCount(branch, relative, allowed) {
+    return branch.children.filter((child) => child.tier !== 'hidden' && (child.kind === 'leaf'
+        ? allowed.has([...relative, child.name].join(' '))
+        : hasAllowedLeaf(child, [...relative, child.name], allowed))).length;
+}
+function providerHelp(branch, relative, allowedTools) {
+    return async () => {
+        if (!envNodeId())
+            return branch.help;
+        // A single lookup for this help rendering, including all nested children.
+        // Do not cache: a grant can change while the broker remains running.
+        const allowed = await allowedTools();
+        return {
+            ...branch.help,
+            listing: branch.help.listing?.flatMap((item) => {
+                const child = branch.children.find((entry) => entry.name === item.name);
+                if (child?.kind === 'leaf')
+                    return allowed.has([...relative, child.name].join(' ')) ? [item] : [];
+                if (child?.kind !== 'branch')
+                    return [];
+                const childPath = [...relative, child.name];
+                if (!hasAllowedLeaf(child, childPath, allowed))
+                    return [];
+                const count = visibleChildCount(child, childPath, allowed);
+                return [{ ...item, ...(item.subCount !== undefined ? { subCount: count } : {}) }];
+            }),
+        };
+    };
+}
+const MACHINE_SELECTOR_GUIDE = 'Runs on one of your devices. Add `--machine <machine_id>` to pick which; without it the call goes to your only device, and with several the answer is `machine_required` listing each one\'s machine_id. The `runtime:` prefix on the id is optional.';
+function providerLeafAdapter(provider, tool, leaf, machineTransport = false) {
+    return {
+        outputKind: 'object',
+        ...(machineTransport ? { machineSelector: true } : {}),
+        run: async (input, context) => {
+            const argumentsForDaemon = { ...input };
+            for (const param of leaf.params) {
+                if (!('type' in param))
+                    continue;
+                const key = param.name.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+                const value = argumentsForDaemon[key];
+                // `file` params are uploaded by the daemon from an absolute path; `path`
+                // params are read here, in the caller's cwd, and travel as their content.
+                if (param.type === 'file' && typeof value === 'string')
+                    argumentsForDaemon[key] = resolve(value);
+                else if (param.type === 'path' && value !== undefined)
+                    argumentsForDaemon[key] = readPathParam(`provider command \`${provider} ${tool}\``, param, value);
+            }
+            try {
+                return await cliClient({ timeoutMs: 0 }).request('POST', '/v1/provider/call', {
+                    provider, tool, arguments: argumentsForDaemon, ...(context?.machine === undefined ? {} : { machine: context.machine }),
+                }, { timeout: 0 });
+            }
+            catch (error) {
+                // The runtime's own code and details (`machine_required` + candidates, `device_offline`, …) reach the caller, not the status default.
+                if (error instanceof ApiError)
+                    throw apiErrorToCliError(error, undefined, { providerCall: true });
+                throw error;
+            }
+        },
+    };
+}
+function validRootName(name, reserved) {
+    return /^[A-Za-z0-9_-]{1,64}$/.test(name) && name !== 'crtr' && !reserved.has(name);
+}
+/** 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 function composeSandboxProviderSubtrees(providers, reserved) {
+    const contributions = [];
+    const unavailable = [];
+    for (const entry of providers) {
+        const { provider, commands } = entry;
+        if (!Array.isArray(commands))
+            continue;
+        // An unavailable provider has no bundle, so its id is the only name it can mount under.
+        if (entry.status !== 'available' && !validRootName(provider, reserved))
+            continue;
+        if (entry.status !== 'available') {
+            const reason = entry.error ?? 'bundle installation pending';
+            const summary = `Unavailable (${entry.status}): ${reason}`;
+            // No manifest means no safe leaf schema to advertise. The branch itself
+            // handles any attempted path with the same failure, never unknown_path.
+            const branch = defineBranch({ name: provider, rootEntry: { concept: entry.display_name, desc: summary, useWhen: summary },
+                help: { name: provider, summary }, children: [],
+                refusal: { code: 'provider_unavailable', message: summary, exit: ExitCode.NETWORK,
+                    next: 'The daemon retries bundle installation on grant sync; retry after the provider becomes available.' } });
+            unavailable.push(branch);
+            continue;
+        }
+        const helpNode = (node) => node.kind === 'branch'
+            ? { ...node, children: node.children.map(helpNode) }
+            // The transport is never read by the provider adapter. A fixed placeholder
+            // satisfies the manifest dialect without transferring a REST mapping.
+            : { ...node, rest: { method: 'GET', path: '/', params: {} } };
+        for (const command of commands) {
+            // The command a person types is the bundle's root name, which need not be the provider id.
+            if (command.kind !== 'branch' || !Array.isArray(command.children) || !validRootName(command.name, reserved))
+                continue;
+            // The tree is the provider's whole tree so an ungranted leaf parses and the daemon refuses it; a caller with no group of the provider
+            // gets no root entry, so root help does not advertise a command it cannot use.
+            const node = helpNode(command);
+            contributions.push({
+                contributor: { name: provider, scope: 'user' }, manifestName: command.name,
+                node: entry.groups.length === 0 ? { ...node, rootEntry: undefined } : node,
+                adaptLeaf: (leaf, path) => providerLeafAdapter(provider, path.slice(1).join(' '), leaf, entry.transport === 'machine'),
+            });
+        }
+    }
+    const branches = composeExternalSubtrees(resolveCommandRegistry(contributions, reserved));
+    for (const branch of branches) {
+        const entry = providers.find((provider) => provider.status === 'available' && provider.commands.some((command) => command.name === branch.name || qualifiedTopLevelCommandName({ name: provider.provider }, command.name) === branch.name));
+        if (entry?.status !== 'available')
+            continue;
+        const allowed = new Set(entry.groups.flatMap((group) => group.leaves.map((leaf) => leaf.tool)));
+        const attachHelp = (node, relative) => {
+            node.effectiveHelp = providerHelp(node, relative, async () => allowed);
+            for (const child of node.children)
+                if (child.kind === 'branch')
+                    attachHelp(child, [...relative, child.name]);
+        };
+        attachHelp(branch, []);
+    }
+    return [...branches, ...unavailable];
+}
+/** The plugin's app credential for an exec leaf, as env. A plugin without a token (404) and a sandboxed node, which may
+ *  not hold it (403), run without; any other failure fails the call. */
+async function appEnvFor(plugin) {
+    try {
+        const { token, socket } = await cliClient().plugins.appToken(plugin);
+        return { CRTR_APP_TOKEN: token, CRTR_DAEMON_SOCKET: socket };
+    }
+    catch (error) {
+        if (error instanceof ApiError && (error.status === 404 || error.status === 403))
+            return undefined;
+        if (error instanceof ApiError)
+            throw apiErrorToCliError(error);
+        throw error;
+    }
+}
+function adaptLeaf(contribution, commandPathFor) {
+    return (leaf, commandPath) => {
+        const transport = contribution.transport;
+        const manifestCommandPath = commandPathFor(commandPath);
+        if (contribution.provider !== undefined)
+            return providerLeafAdapter(contribution.provider.id, manifestCommandPath.slice(1).join(' '), leaf, transport.kind === 'machine');
+        if (transport.kind === 'exec') {
+            const executable = transport.executable;
+            if (executable === undefined)
+                throw new Error(`exec plugin "${contribution.plugin.name}" has an executable leaf without transport.executable`);
+            return {
+                outputKind: 'object',
+                run: async (input) => {
+                    const appEnv = needsAppToken(contribution.plugin.manifest) ? await appEnvFor(contribution.plugin.name) : undefined;
+                    return executeExternalLeaf({ plugin: contribution.plugin, executable, commandPath: manifestCommandPath, output: leaf.output, ...(appEnv !== undefined ? { appEnv } : {}) }, input);
+                },
+            };
+        }
+        if (transport.kind === 'machine')
+            throw new Error(`machine plugin "${contribution.plugin.name}" is not a capability provider`);
+        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: manifestCommandPath,
+            }, input, context, {
+                // crtrd names the caller and decides, from the final URL, whether to sign. Only digests leave this process.
+                callHeaders: (plan) => cliClient().plugins.callHeaders(contribution.plugin.name, {
+                    method: plan.method, url: plan.url.href, body_sha256: sha256Hex(plan.body), ...signedHeaderDigest(plan.headers),
+                }).then((answer) => answer.headers, (error) => { throw error instanceof ApiError ? apiErrorToCliError(error) : error; }),
+            }),
+        };
+    };
+}
+export function adaptPluginContributions(contributions) {
+    return {
+        contributions: contributions.map((contribution) => ({
+            contributor: { name: contribution.plugin.name, scope: contribution.plugin.scope, sourceMarketplace: contribution.plugin.sourceMarketplace },
+            node: contribution.node,
+            manifestName: contribution.manifestName,
+            adaptLeaf: adaptLeaf(contribution, (commandPath) => [contribution.manifestName, ...commandPath.slice(1)]),
+            ...(contribution.provider !== undefined ? { provider: contribution.provider } : {}),
+        })),
+        coreMounts: [],
+        issues: [],
+    };
+}
+export function adaptPluginCoreMounts(mounts) {
+    return mounts.map((mount) => ({
+        parent: mount.parent,
+        plugin: mount.plugin.name,
+        contributor: { name: mount.plugin.name, scope: mount.plugin.scope, sourceMarketplace: mount.plugin.sourceMarketplace },
+        node: mount.node,
+        ...(mount.provider !== undefined ? { provider: mount.provider } : {}),
+        adaptLeaf: adaptLeaf({ ...mount, manifestName: mount.node.name }, (commandPath) => mount.provider === undefined ? [...commandPath] : [mount.provider.id, ...commandPath.slice(mount.parent.length)]),
+    }));
+}
+export function composeExternalSubtrees(snapshot) {
+    return snapshot.contributions.map((contribution) => buildBranch(contribution, contribution.node, [contribution.node.name]));
+}
+export function composeCoreBranchMounts(mounts, parent) {
+    return mounts.filter((mount) => mount.parent.join('\u0000') === parent.join('\u0000')).map((mount) => mount.node.kind === 'branch'
+        ? buildBranch(mount, mount.node, [...parent, mount.node.name], mount.provider === undefined ? 1 : parent.length)
+        : buildLeaf(mount, mount.node, [...parent, mount.node.name]));
+}
+function buildBranch(contribution, node, path, toolPrefixLength = 1) {
+    const rootEntry = node.rootEntry === undefined ? undefined : { concept: node.rootEntry.concept, desc: node.rootEntry.description, useWhen: node.rootEntry.whenToUse };
+    const branch = defineBranch({ name: node.name, description: node.description, whenToUse: node.whenToUse, ...(node.tier !== undefined ? { tier: node.tier } : {}), ...(contribution.plugin !== undefined ? { plugin: contribution.plugin } : {}), ...(rootEntry !== undefined ? { rootEntry } : {}), help: { name: path.join(' '), summary: node.summary, ...(node.model !== undefined ? { model: node.model } : {}), ...(path.length === 1 && contribution.extensionIssue !== undefined ? { extensionIssue: contribution.extensionIssue } : {}) }, ...(node.passthrough !== undefined ? { passthrough: node.passthrough } : {}), children: node.children.map((child) => child.kind === 'branch' ? buildBranch(contribution, child, [...path, child.name], toolPrefixLength) : buildLeaf(contribution, child, [...path, child.name])) });
+    if (contribution.provider !== undefined)
+        branch.effectiveHelp = providerHelp(branch, path.slice(toolPrefixLength), () => allowedProviderTools(contribution.provider.id));
+    return branch;
+}
+function buildLeaf(contribution, node, path) {
+    const adapted = contribution.adaptLeaf(node, path);
+    return defineLeaf({ name: node.name, description: node.description, whenToUse: node.whenToUse, ...(node.tier !== undefined ? { tier: node.tier } : {}), ...(contribution.plugin !== undefined ? { plugin: contribution.plugin } : {}), ...(adapted.machineSelector === true ? { machineSelector: true } : {}), help: { name: path.join(' '), summary: node.summary, ...(adapted.machineSelector === true ? { guide: MACHINE_SELECTOR_GUIDE } : {}), params: node.params, output: node.output, outputKind: adapted.outputKind, effects: [...node.effects] }, run: adapted.run });
+}

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

@@ -0,0 +1,49 @@
+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 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;