@north-light/api 0.3.579 → 0.3.587

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

@@ -0,0 +1,240 @@
+import { realpathSync, readFileSync, statSync } from 'node:fs';
+import { isAbsolute, resolve, sep } from 'node:path';
+import { validateCommandManifest } from '../../api/command-manifest/manifest.js';
+import { qualifiedTopLevelCommandName, resolveCommandRegistry } from '../command-manifests/registry.js';
+import { adaptPluginContributions, adaptPluginCoreMounts } from './compose.js';
+import { validateHttpPluginTransport } from './endpoint.js';
+import { effectiveCommandPlugins } from './presence.js';
+import { applyCommandExtensions } from './extensions.js';
+function issueFor(plugin, issues) {
+    return (issue) => issues.push({ ...issue, plugin: plugin.name });
+}
+function safePath(root, rel) {
+    if (typeof rel !== 'string' || rel.length === 0)
+        return null;
+    try {
+        const rootReal = realpathSync(root);
+        const real = realpathSync(resolve(root, rel));
+        return real === rootReal || real.startsWith(rootReal + sep) ? statSync(real).isFile() ? real : null : null;
+    }
+    catch {
+        return null;
+    }
+}
+function transportFor(plugin, issues) {
+    const raw = plugin.manifest.transport;
+    if (raw === undefined) {
+        issues.push({ code: 'command_manifest_invalid', plugin: plugin.name, message: 'commands requires transport in plugin.json', received: '(missing)', expected: 'a transport object', next: 'Add plugin.json.transport.', path: 'transport' });
+        return undefined;
+    }
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        issues.push({ code: 'command_manifest_invalid', plugin: plugin.name, message: 'transport must be an object', received: Array.isArray(raw) ? 'array' : typeof raw, expected: 'an exec or http transport object', next: 'Fix plugin.json.transport.', path: 'transport' });
+        return undefined;
+    }
+    const value = raw;
+    if (value.kind === 'http') {
+        const result = validateHttpPluginTransport(value);
+        if (result.transport !== undefined)
+            return result.transport;
+        issues.push({ code: 'command_manifest_invalid', plugin: plugin.name, message: result.errors.join('; '), received: JSON.stringify(raw), expected: 'a valid HTTP transport', next: 'Fix plugin.json.transport.', path: 'transport' });
+        return undefined;
+    }
+    if (value.kind === 'machine') {
+        // Only a capability-provider bundle calls a device machine; its commands.json is the HTTP dialect and never names an endpoint.
+        if (plugin.manifest.provider === undefined || Object.keys(value).length !== 1) {
+            issues.push({ code: 'command_manifest_invalid', plugin: plugin.name, message: plugin.manifest.provider === undefined ? 'a machine transport belongs to a capability provider bundle' : 'transport has unknown keys', received: JSON.stringify(raw), expected: '{ kind: "machine" } on a provider bundle', next: 'Fix plugin.json.transport.', path: 'transport' });
+            return undefined;
+        }
+        return { kind: 'machine' };
+    }
+    const unknown = Object.keys(value).filter((key) => !['kind', 'executable'].includes(key));
+    if (value.kind !== 'exec' || unknown.length || (value.executable !== undefined && (typeof value.executable !== 'string' || value.executable.length === 0))) {
+        issues.push({ code: 'command_manifest_invalid', plugin: plugin.name, message: unknown.length ? `transport has unknown keys: ${unknown.join(', ')}` : 'exec transport requires a non-empty executable when declared', received: JSON.stringify(raw), expected: '{ kind: "exec", executable?: "plugin-relative path" }', next: 'Fix plugin.json.transport.', path: 'transport' });
+        return undefined;
+    }
+    return { kind: 'exec', ...(value.executable !== undefined ? { executable: value.executable } : {}) };
+}
+function hasExecutableLeaf(node) {
+    return node.kind === 'leaf' || node.children.some(hasExecutableLeaf);
+}
+function manifestNodes(manifest) {
+    return [...manifest.roots, ...manifest.coreMounts.map((mount) => mount.node)];
+}
+function validateExecExecutable(plugin, transport, manifest, issues) {
+    if (transport.executable === undefined) {
+        if (!manifestNodes(manifest).some(hasExecutableLeaf))
+            return transport;
+        issues.push({ code: 'command_manifest_invalid', plugin: plugin.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 undefined;
+    }
+    const executable = safePath(plugin.root, transport.executable);
+    if (executable === null) {
+        issues.push({ code: 'command_path_unsafe', plugin: plugin.name, message: 'executable escapes the plugin root or is not a regular file', received: transport.executable, expected: 'a relative path to a regular file inside the plugin root', next: 'Fix plugin.json.transport.executable.', path: 'transport.executable' });
+        return undefined;
+    }
+    if ((statSync(executable).mode & 0o111) === 0) {
+        issues.push({ code: 'command_not_executable', plugin: plugin.name, message: 'executable lacks the POSIX exec bit', received: transport.executable, expected: 'a file with an executable permission bit', next: 'chmod +x the plugin executable, then update the plugin.', path: 'transport.executable' });
+        return undefined;
+    }
+    return { kind: 'exec', executable };
+}
+function namesPath(bin) {
+    return isAbsolute(bin) || bin.startsWith('.') || bin.includes('/') || bin.includes('\\');
+}
+/** Resolve plugin-owned passthrough programs during discovery. Bare program
+ * names intentionally remain untouched so spawn resolves them through PATH. */
+function resolvePassthroughBinaries(plugin, manifest, issues) {
+    let valid = true;
+    const visit = (node) => {
+        if (node.kind !== 'branch')
+            return;
+        const passthrough = node.passthrough;
+        if (passthrough !== undefined && namesPath(passthrough.bin)) {
+            const executable = safePath(plugin.root, passthrough.bin);
+            if (executable === null) {
+                issues.push({ code: 'command_path_unsafe', plugin: plugin.name, message: 'passthrough binary escapes the plugin root or is not a regular file', received: passthrough.bin, expected: 'a relative path to a regular file inside the plugin root', next: 'Fix passthrough.bin in commands.json.', path: 'passthrough.bin' });
+                valid = false;
+            }
+            else if ((statSync(executable).mode & 0o111) === 0) {
+                issues.push({ code: 'command_not_executable', plugin: plugin.name, message: 'passthrough binary lacks the POSIX exec bit', received: passthrough.bin, expected: 'a file with an executable permission bit', next: 'chmod +x the plugin executable, then update commands.json.', path: 'passthrough.bin' });
+                valid = false;
+            }
+            else {
+                node.passthrough = { ...passthrough, bin: executable };
+            }
+        }
+        for (const child of node.children)
+            visit(child);
+    };
+    for (const root of manifestNodes(manifest))
+        visit(root);
+    return valid;
+}
+export function validatePluginCommands(plugin, reservedNames = new Set(), coreCommandPaths, extensibleCoreBranches = new Set()) {
+    const issues = [];
+    const commands = plugin.manifest.commands;
+    const transportRaw = plugin.manifest.transport;
+    let manifestPath = resolve(plugin.root, typeof commands === 'string' ? commands : 'commands.json');
+    const empty = (transport) => ({ plugin, manifestPath, ...(transport === undefined ? {} : { transport }), contributions: [], coreMounts: [], issues });
+    if (commands === undefined && transportRaw === undefined)
+        return empty();
+    if (typeof commands !== 'string' || commands.length === 0) {
+        issues.push({ code: 'command_manifest_invalid', plugin: plugin.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' });
+        return empty();
+    }
+    const transport = transportFor(plugin, issues);
+    if (transport === undefined)
+        return empty();
+    const safe = safePath(plugin.root, commands);
+    if (safe === null) {
+        issues.push({ code: 'command_path_unsafe', plugin: plugin.name, message: 'commands pointer escapes the plugin root or is not a regular file', received: commands, expected: 'a relative path to a regular file inside the plugin root', next: 'Fix plugin.json.commands.', path: 'commands' });
+        return empty(transport);
+    }
+    manifestPath = safe;
+    let bytes;
+    try {
+        bytes = readFileSync(safe);
+    }
+    catch {
+        bytes = null;
+    }
+    if (bytes === null) {
+        issues.push({ code: 'command_manifest_unreadable', plugin: plugin.name, message: 'commands.json is missing or unreadable', received: safe, expected: 'a readable JSON file', next: 'Reinstall or update the plugin.' });
+        return empty(transport);
+    }
+    let raw;
+    try {
+        raw = JSON.parse(Buffer.from(bytes).toString('utf8'));
+    }
+    catch {
+        issues.push({ code: 'command_manifest_invalid', plugin: plugin.name, message: 'commands.json is not valid JSON', received: safe, expected: 'a JSON object', next: 'Regenerate commands.json.' });
+        return empty(transport);
+    }
+    const validation = validateCommandManifest(raw, { transport: transport.kind === 'machine' ? 'http' : transport.kind, reservedCoreNames: reservedNames, extensibleCoreBranches, ...(coreCommandPaths !== undefined ? { coreCommandPaths } : {}) });
+    if (validation.manifest === undefined) {
+        validation.issues.forEach(issueFor(plugin, issues));
+        return empty(transport);
+    }
+    const resolvedTransport = transport.kind === 'exec'
+        ? validateExecExecutable(plugin, transport, validation.manifest, issues)
+        : transport;
+    if (resolvedTransport === undefined)
+        return empty(transport);
+    if (resolvedTransport.kind === 'exec' && !resolvePassthroughBinaries(plugin, validation.manifest, issues))
+        return empty(resolvedTransport);
+    const provider = plugin.manifest.provider;
+    const roots = validation.manifest.roots;
+    if (!roots.every((node) => node.kind === 'branch')) {
+        throw new Error('plugin manifest validation returned a top-level leaf');
+    }
+    return {
+        plugin,
+        manifestPath,
+        transport: resolvedTransport,
+        manifest: validation.manifest,
+        // A provider that ships documents only has a root with no leaf below it: nothing to call, so nothing to mount.
+        contributions: roots.filter((node) => provider === undefined || hasExecutableLeaf(node)).map((node) => ({ plugin, transport: resolvedTransport, node, manifest: validation.manifest, manifestName: node.name, ...(provider !== undefined ? { provider } : {}) })),
+        coreMounts: validation.manifest.coreMounts.map((mount) => ({ plugin, transport: resolvedTransport, parent: mount.parent, node: mount.node, manifest: validation.manifest, ...(provider !== undefined ? { provider } : {}) })),
+        issues,
+    };
+}
+export function discoverPluginCommandCandidates(startDir = process.cwd(), profileId) {
+    return effectiveCommandPlugins(startDir, profileId).map((plugin) => validatePluginCommands(plugin));
+}
+export function validateEffectiveCommandPlugins(reservedNames, startDir = process.cwd(), profileId, coreCommandPaths, extensibleCoreBranches = new Set()) {
+    const validations = effectiveCommandPlugins(startDir, profileId).map((plugin) => validatePluginCommands(plugin, reservedNames, coreCommandPaths, extensibleCoreBranches));
+    const claims = new Map();
+    for (const validation of validations)
+        for (const contribution of validation.contributions) {
+            const claimants = claims.get(contribution.node.name);
+            if (claimants === undefined)
+                claims.set(contribution.node.name, [contribution]);
+            else
+                claimants.push(contribution);
+        }
+    for (const [name, claimants] of claims)
+        if (claimants.length > 1)
+            for (const claimant of claimants) {
+                const { plugin } = claimant;
+                const qualifiedName = qualifiedTopLevelCommandName({ name: plugin.name, sourceMarketplace: plugin.sourceMarketplace }, name);
+                const validation = validations.find((candidate) => candidate.plugin.root === plugin.root);
+                validation.contributions = validation.contributions.map((contribution) => contribution === claimant ? { ...contribution, node: { ...contribution.node, name: qualifiedName } } : contribution);
+                validation.issues.push({ code: 'command_collision', plugin: plugin.name, path: name, message: `top-level command "${name}" is claimed by ${claimants.map((entry) => entry.plugin.name).join(', ')} — mounted as "${qualifiedName}"`, received: claimants.map((entry) => entry.plugin.name).join(', '), expected: 'an origin-qualified top-level command for each claimant', next: `Invoke "${qualifiedName}" to use this plugin command.` });
+            }
+    const coreClaims = new Map();
+    for (const validation of validations)
+        for (const mount of validation.coreMounts) {
+            const key = [...mount.parent, mount.node.name].join('/');
+            const claimants = coreClaims.get(key);
+            if (claimants === undefined)
+                coreClaims.set(key, [mount]);
+            else
+                claimants.push(mount);
+        }
+    for (const [path, claimants] of coreClaims)
+        if (claimants.length > 1)
+            for (const claimant of claimants) {
+                const validation = validations.find((candidate) => candidate.plugin.root === claimant.plugin.root);
+                validation.coreMounts = validation.coreMounts.filter((mount) => mount !== claimant);
+                validation.issues.push({ code: 'command_collision', plugin: claimant.plugin.name, path: path.replace('/', '.'), message: `contributed command "${claimant.node.name}" conflicts with another plugin child below the extensible core branch`, received: claimants.map((entry) => entry.plugin.name).join(', '), expected: `a unique child name below ${claimant.parent.join('.')}`, next: 'Rename the contributed command or remove this mount.' });
+            }
+    return validations;
+}
+function contributorIssue(plugin, issue) {
+    return { ...issue, contributor: { name: plugin.name, scope: plugin.scope, sourceMarketplace: plugin.sourceMarketplace } };
+}
+export function discoverCommandContributions(reservedNames, startDir = process.cwd(), profileId, coreCommandPaths, extensibleCoreBranches = new Set()) {
+    const validations = validateEffectiveCommandPlugins(reservedNames, startDir, profileId, coreCommandPaths, extensibleCoreBranches);
+    return { contributions: validations.flatMap((validation) => validation.contributions), coreMounts: validations.flatMap((validation) => validation.coreMounts), issues: validations.flatMap((validation) => validation.issues) };
+}
+export function buildExternalCommandSnapshot(reservedCoreNames, startDir = process.cwd(), profileId, coreCommandPaths, extensibleCoreBranches = new Set()) {
+    const validations = validateEffectiveCommandPlugins(reservedCoreNames, startDir, profileId, coreCommandPaths, extensibleCoreBranches);
+    const candidates = adaptPluginContributions(validations.flatMap((validation) => validation.contributions)).contributions;
+    const resolved = resolveCommandRegistry(candidates, reservedCoreNames);
+    const extensions = applyCommandExtensions(resolved.contributions, startDir);
+    return {
+        contributions: extensions.contributions,
+        coreMounts: adaptPluginCoreMounts(validations.flatMap((validation) => validation.coreMounts)),
+        issues: [...validations.flatMap((validation) => validation.issues.map((issue) => contributorIssue(validation.plugin, issue))), ...resolved.issues],
+    };
+}

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,166 @@
+import { existsSync, realpathSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
+import { projectScopeRoots } from '../scope.js';
+import { validateCommandManifest } from '../../api/command-manifest/manifest.js';
+import { executeExternalLeaf } from './transport/exec-invoke.js';
+import { isRecord } from '../../shared/predicates.js';
+function issue(fragmentPath, message, received, expected, next, nodePath) {
+    return {
+        code: 'command_extension_invalid',
+        message,
+        received,
+        expected,
+        next,
+        path: nodePath === undefined ? fragmentPath : `${fragmentPath}:${nodePath}`,
+    };
+}
+function regenerate(fragmentPath) {
+    return `Fix the repository CLI definition and regenerate ${fragmentPath}.`;
+}
+function safeExecutable(fragmentPath, root, executable) {
+    if (isAbsolute(executable)) {
+        return { issue: issue(fragmentPath, 'fragment transport executable must be project-relative', executable, 'a project-root-relative regular file', 'Fix transport.executable in the repository CLI definition and regenerate the fragment.', 'transport.executable') };
+    }
+    try {
+        const rootReal = realpathSync(root);
+        const resolved = realpathSync(resolve(root, executable));
+        if ((resolved !== rootReal && !resolved.startsWith(rootReal + sep)) || !statSync(resolved).isFile()) {
+            return { issue: issue(fragmentPath, 'fragment transport executable escapes the project root or is not a regular file', executable, 'a project-root-relative regular file', 'Fix transport.executable in the repository CLI definition and regenerate the fragment.', 'transport.executable') };
+        }
+        if ((statSync(resolved).mode & 0o111) === 0) {
+            return { issue: issue(fragmentPath, 'fragment transport executable lacks the POSIX exec bit', executable, 'a file with an executable permission bit', 'chmod +x the repository command executable, then regenerate the fragment.', 'transport.executable') };
+        }
+        return { executable: resolved };
+    }
+    catch {
+        return { issue: issue(fragmentPath, 'fragment transport executable escapes the project root or is not a regular file', executable, 'a project-root-relative regular file', 'Fix transport.executable in the repository CLI definition and regenerate the fragment.', 'transport.executable') };
+    }
+}
+function validateFragment(fragmentPath, projectRoot, branch, ownChildren) {
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(fragmentPath, 'utf8'));
+    }
+    catch {
+        return { issue: issue(fragmentPath, 'extension fragment is missing, unreadable, or not valid JSON', fragmentPath, 'a readable generated JSON fragment', `Regenerate ${fragmentPath}.`) };
+    }
+    if (!isRecord(raw)) {
+        return { issue: issue(fragmentPath, 'extension fragment must be an object', raw === null ? 'null' : Array.isArray(raw) ? 'array' : typeof raw, '{ schemaVersion, transport, mounts }', `Regenerate ${fragmentPath}.`) };
+    }
+    const unknown = Object.keys(raw).filter((key) => !['schemaVersion', 'transport', 'mounts'].includes(key));
+    if (unknown.length > 0) {
+        return { issue: issue(fragmentPath, 'extension fragment has unknown top-level keys', unknown.join(', '), 'only: schemaVersion, transport, mounts', `Regenerate ${fragmentPath}.`) };
+    }
+    const transport = raw['transport'];
+    if (!isRecord(transport) || Object.keys(transport).some((key) => !['kind', 'executable'].includes(key)) || transport['kind'] !== 'exec' || typeof transport['executable'] !== 'string' || transport['executable'].length === 0) {
+        return { issue: issue(fragmentPath, 'extension fragment transport must be { kind: "exec", executable: "project-relative path" }', JSON.stringify(transport), 'an exec transport with an executable', `Regenerate ${fragmentPath}.`, 'transport') };
+    }
+    const executableResult = safeExecutable(fragmentPath, projectRoot, transport['executable']);
+    if (executableResult.issue !== undefined)
+        return { issue: executableResult.issue };
+    const validation = validateCommandManifest(raw, {
+        transport: 'exec',
+        reservedCoreNames: new Set(),
+        extensionFragment: true,
+    });
+    if (validation.manifest === undefined) {
+        const source = validation.issues[0];
+        return {
+            issue: issue(fragmentPath, source.message, source.received, source.expected, regenerate(fragmentPath), source.path),
+        };
+    }
+    const conflict = validation.manifest.roots.find((root) => ownChildren.includes(root.name));
+    if (conflict !== undefined) {
+        return {
+            issue: issue(fragmentPath, `contributed command "${conflict.name}" conflicts with a child the extensible branch already owns`, conflict.name, 'a name not already owned by the plugin branch', `Rename "${conflict.name}" in the repository CLI tree, then regenerate ${fragmentPath}.`, conflict.name),
+        };
+    }
+    return { fragment: { roots: validation.manifest.roots, executable: executableResult.executable } };
+}
+function nearestFragment(branch, startDir) {
+    for (const scopeRoot of projectScopeRoots(startDir, null)) {
+        const projectRoot = dirname(scopeRoot);
+        const fragmentPath = join(scopeRoot, 'commands', `${branch}.json`);
+        if (existsSync(fragmentPath))
+            return { fragmentPath, projectRoot };
+    }
+    return undefined;
+}
+function markLeaves(node, leaves) {
+    if (node.kind === 'leaf') {
+        leaves.add(node);
+        return;
+    }
+    node.children.forEach((child) => markLeaves(child, leaves));
+}
+/** Attach the nearest repository-owned fragment to each marked plugin branch.
+ * Discovery reads only; execution remains in the leaf adapter. */
+export function applyCommandExtensions(contributions, startDir = process.cwd()) {
+    const validations = [];
+    const attached = contributions.map((contribution) => {
+        if (contribution.node.extensible !== true)
+            return contribution;
+        const branch = contribution.node.name;
+        const located = nearestFragment(branch, startDir);
+        if (located === undefined)
+            return contribution;
+        const result = validateFragment(located.fragmentPath, located.projectRoot, branch, contribution.node.children.map((child) => child.name));
+        if (result.issue !== undefined) {
+            validations.push({ branch, fragmentPath: located.fragmentPath, projectRoot: located.projectRoot, issue: result.issue });
+            return {
+                ...contribution,
+                extensionIssue: { fragment: located.fragmentPath, message: result.issue.message },
+            };
+        }
+        const fragment = result.fragment;
+        validations.push({ branch, fragmentPath: located.fragmentPath, projectRoot: located.projectRoot });
+        const leaves = new WeakSet();
+        fragment.roots.forEach((root) => markLeaves(root, leaves));
+        return {
+            ...contribution,
+            node: { ...contribution.node, children: [...contribution.node.children, ...fragment.roots] },
+            adaptLeaf: (leaf, path) => {
+                if (!leaves.has(leaf))
+                    return contribution.adaptLeaf(leaf, path);
+                const commandPath = [...path];
+                return {
+                    outputKind: 'object',
+                    run: async (input) => executeExternalLeaf({
+                        extension: { branch, root: located.projectRoot },
+                        executable: fragment.executable,
+                        commandPath,
+                        output: leaf.output,
+                    }, input),
+                };
+            },
+        };
+    });
+    return { contributions: attached, validations };
+}
+/** Doctor's only directory scan: fragments with no matching effective marked branch are otherwise inert by design. */
+export function orphanCommandExtensionValidations(contributions, startDir = process.cwd()) {
+    const scopeRoot = projectScopeRoots(startDir, null)[0];
+    if (scopeRoot === undefined)
+        return [];
+    const commandsDir = join(scopeRoot, 'commands');
+    let names;
+    try {
+        names = readdirSync(commandsDir);
+    }
+    catch {
+        return [];
+    }
+    const extensible = new Set(contributions.filter((contribution) => contribution.node.extensible === true).map((contribution) => contribution.node.name));
+    return names.filter((name) => name.endsWith('.json')).flatMap((name) => {
+        const branch = name.slice(0, -'.json'.length);
+        if (extensible.has(branch))
+            return [];
+        const fragmentPath = join(commandsDir, name);
+        return [{
+                branch,
+                fragmentPath,
+                projectRoot: dirname(scopeRoot),
+                issue: issue(fragmentPath, `fragment names branch "${branch}" but no effective plugin branch is extensible`, branch, 'the name of an effective extensible plugin branch', `Mark the plugin branch extensible or rename/remove ${fragmentPath}.`),
+            }];
+    });
+}

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,55 @@
+// Plugin help addenda: a command plugin may append attributed product guidance
+// beneath a CORE command's help (`helpAddenda` in its command manifest).
+// Append-only, never replace — a plugin cannot alter substrate contract text.
+//
+// This module is the help-render lookup. It loads only on the help path
+// (dynamic import from runCli) and reads stored manifest bytes only (no
+// network). The caller supplies the SAME inputs the install/bundle gates pass
+// to `validateCommandManifest` — the reserved core names and the full core
+// command path set — so this lookup reproduces the gate's exact verdict: a
+// manifest whose `helpAddenda` was rejected at ingress (reported there as a
+// typed issue, e.g. `command_help_addendum_invalid`) contributes nothing at
+// render either. Ingress report and render can never disagree; nothing
+// disappears here that was not already loudly rejected at the gate.
+import { validatePluginCommands } from './discovery.js';
+import { effectiveCommandPlugins } from './presence.js';
+/** 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 async function collectHelpAddenda(commandPath, gate, startDir, profileId) {
+    if (commandPath.length === 0)
+        return [];
+    const extensibleCoreBranches = await gate.extensibleCoreBranches();
+    const asked = [];
+    const claimants = effectiveCommandPlugins(startDir, profileId).filter((plugin) => {
+        const manifest = validatePluginCommands(plugin, gate.reservedCoreNames, undefined, extensibleCoreBranches).manifest;
+        if (manifest?.helpAddenda?.[commandPath] === undefined)
+            return false;
+        asked.push(...Object.keys(manifest.helpAddenda), ...manifest.coreMounts.map((mount) => [...mount.parent, mount.node.name].join(' ')));
+        return true;
+    });
+    if (claimants.length === 0)
+        return [];
+    const coreCommandPaths = await gate.coreCommandPaths(asked);
+    const out = [];
+    for (const plugin of claimants) {
+        const text = validatePluginCommands(plugin, gate.reservedCoreNames, coreCommandPaths, extensibleCoreBranches).manifest?.helpAddenda?.[commandPath];
+        if (text !== undefined)
+            out.push({ plugin: plugin.name, text });
+    }
+    out.sort((a, b) => a.plugin.localeCompare(b.plugin));
+    return out;
+}

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

@@ -0,0 +1,4 @@
+import type { InstalledPlugin } from '../../types.js';
+/** Whether an enabled command plugin survives nearest-scope name shadowing. */
+export declare function hasEffectiveCommandPlugins(startDir?: string, profileId?: string | null): boolean;
+export declare function effectiveCommandPlugins(startDir?: string, profileId?: string | null): InstalledPlugin[];

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

@@ -0,0 +1,36 @@
+import { listInstalledPlugins, listInstalledPluginsInRoot } from '../resolver.js';
+import { projectScopeRoots } from '../scope.js';
+import { isSandboxedNode } from '../../shared/env.js';
+import { providerRootClaims } from '../providers/roots.js';
+/** Whether an enabled command plugin survives nearest-scope name shadowing. */
+export function hasEffectiveCommandPlugins(startDir = process.cwd(), profileId) {
+    const seen = new Set();
+    const consider = (plugin) => {
+        if (seen.has(plugin.name))
+            return false;
+        seen.add(plugin.name);
+        return plugin.enabled && (plugin.manifest.commands !== undefined || plugin.manifest.transport !== undefined);
+    };
+    for (const root of projectScopeRoots(startDir, profileId)) {
+        if (listInstalledPluginsInRoot('project', root).some(consider))
+            return true;
+    }
+    return listInstalledPlugins('user').some(consider);
+}
+export function effectiveCommandPlugins(startDir = process.cwd(), profileId) {
+    const seen = new Set();
+    const result = [];
+    const consider = (plugin) => { if (!seen.has(plugin.name)) {
+        seen.add(plugin.name);
+        result.push(plugin);
+    } };
+    for (const root of projectScopeRoots(startDir, profileId))
+        for (const plugin of listInstalledPluginsInRoot('project', root))
+            consider(plugin);
+    if (!isSandboxedNode())
+        for (const plugin of listInstalledPlugins('user'))
+            consider(plugin);
+    // Two provider bundles claiming one root command: the earlier-installed serves, the later is skipped (and logged).
+    const { skipped } = providerRootClaims(result);
+    return result.filter((plugin) => !skipped.has(plugin.name)).filter((plugin) => plugin.enabled && (plugin.manifest.commands !== undefined || plugin.manifest.transport !== undefined));
+}

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

@@ -0,0 +1,42 @@
+import type { InstalledPlugin } from '../../../types.js';
+import type { Field } from '../../help.js';
+import { CrtrError } from '../../errors.js';
+export declare const MAX_STDOUT: number;
+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[];
+    /** Extra environment for this call, layered over the inherited environment. */
+    appEnv?: Record<string, string>;
+} | {
+    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[];
+    /** Extra environment for this call, layered over the inherited environment. */
+    appEnv?: Record<string, string>;
+};
+/** The one JSON request written to the plugin's stdin. */
+export declare function buildLeafRequest(spec: ExternalLeafSpec, input: Record<string, unknown>, cwd: string): Record<string, unknown>;
+/** 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>;
+/** Turn a finished plugin process (stdout text, exit status, terminating signal)
+ *  into the result object, or throw the plugin's own error or a protocol error.
+ *  Shared by the synchronous and asynchronous runners. */
+export declare function parseLeafEnvelope(spec: ExternalLeafSpec, stdout: string, status: number | null, signal: NodeJS.Signals | null): Record<string, unknown>;
+export declare function protocolError(spec: ExternalLeafSpec, received: string, expected: string): CrtrError;
+export declare function label(spec: ExternalLeafSpec): string;