@north-light/crouter 0.3.154

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

@@ -0,0 +1,22 @@
+import type { InstalledPlugin } from '../../types.js';
+import type { Field } from '../help.js';
+export interface ExternalLeafSpec {
+    plugin: InstalledPlugin;
+    /** 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[];
+}
+/** Validates a result object against declared output field descriptors.
+ *  Returns null if valid; otherwise returns a { field, receivedType } error.
+ *  Transport-neutral: used by both command-plugin and configured-CLI adapters. */
+export declare function validateDeclaredResult(output: Field[], result: Record<string, unknown>): {
+    field: string;
+    receivedType?: string;
+} | null;
+/** Execute one external leaf and return its result object (crtr renders it via
+ *  the generic renderer; `--json` mirrors it). Throws a CrtrError for any
+ *  protocol violation or the plugin's own recoverable error. */
+export declare function executeExternalLeaf(spec: ExternalLeafSpec, input: Record<string, unknown>): Record<string, unknown>;

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

@@ -0,0 +1,160 @@
+// External leaf adapter — the execution seam for a command plugin's leaf.
+//
+// On explicit leaf invocation only (never on discovery/help), direct-spawn the
+// plugin's canonical executable with `--crtr-command-protocol 1`, write one
+// JSON request to stdin, and parse exactly one JSON response envelope from
+// stdout. The envelope's `ok` is the source of truth; crtr owns rendering and
+// error normalization. The executable inherits the caller's cwd + full
+// environment and owns its own time budget (no crtr timeout) — this is a trust
+// boundary, not a sandbox (installed code can already read the caller's files).
+import { spawnSync } from 'node:child_process';
+import { CrtrError } from '../errors.js';
+import { diag } from '../io.js';
+import { ExitCode } from '../../types.js';
+const MAX_STDOUT = 10 * 1024 * 1024; // 10 MiB hard cap on plugin stdout.
+const RESERVED_CODES = new Set(['internal', 'unknown_path', 'command_collision', 'plugin_protocol_error']);
+// Strict snake_case: no leading/trailing underscore, no consecutive underscores.
+const SNAKE = /^[a-z][a-z0-9]*(_[a-z0-9]+)*$/;
+const NEXT = 'Run `crtr pkg plugin show` or `crtr sys doctor` to inspect the plugin.';
+/** Validates a result object against declared output field descriptors.
+ *  Returns null if valid; otherwise returns a { field, receivedType } error.
+ *  Transport-neutral: used by both command-plugin and configured-CLI adapters. */
+export function validateDeclaredResult(output, result) {
+    for (const f of output) {
+        const present = Object.prototype.hasOwnProperty.call(result, f.name) && result[f.name] !== undefined && result[f.name] !== null;
+        if (f.required && !present) {
+            return { field: f.name };
+        }
+        if (present && !typeMatches(f.type, result[f.name])) {
+            return { field: f.name, receivedType: typeof result[f.name] };
+        }
+    }
+    return null;
+}
+/** 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 function executeExternalLeaf(spec, input) {
+    const request = {
+        protocolVersion: 1,
+        command: spec.commandPath,
+        input,
+        context: {
+            cwd: process.cwd(),
+            plugin: {
+                name: spec.plugin.name,
+                version: spec.plugin.version ?? spec.plugin.manifest.version ?? null,
+                scope: spec.plugin.scope,
+                root: spec.plugin.root,
+            },
+        },
+    };
+    const res = spawnSync(spec.executable, ['--crtr-command-protocol', '1'], {
+        input: JSON.stringify(request),
+        cwd: process.cwd(),
+        env: process.env,
+        maxBuffer: MAX_STDOUT,
+        stdio: ['pipe', 'pipe', 'inherit'],
+        encoding: 'utf8',
+    });
+    if (res.error !== undefined) {
+        const err = res.error;
+        // spawnSync signals a maxBuffer overrun as ENOBUFS (and kills the child);
+        // the exec-family code is accepted too for robustness across Node versions.
+        if (err.code === 'ENOBUFS' || err.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER') {
+            throw protocolError(spec, `stdout exceeded the 10 MiB cap`, 'one JSON envelope under 10 MiB on stdout');
+        }
+        throw protocolError(spec, `executable could not be run (${err.code ?? err.message})`, 'a runnable command executable');
+    }
+    if (res.signal !== null) {
+        throw protocolError(spec, `executable was killed by signal ${res.signal}`, 'a clean exit with one JSON envelope on stdout');
+    }
+    const stdout = res.stdout ?? '';
+    let envelope;
+    try {
+        envelope = JSON.parse(stdout.trim());
+    }
+    catch {
+        throw protocolError(spec, `stdout was not a single JSON envelope`, 'exactly one JSON envelope on stdout');
+    }
+    if (!isObject(envelope)) {
+        throw protocolError(spec, `stdout was not a JSON object`, 'a { protocolVersion: 1, ok: boolean, ... } envelope');
+    }
+    if (envelope['protocolVersion'] !== 1) {
+        throw protocolError(spec, `unsupported protocolVersion ${String(envelope['protocolVersion'])}`, 'protocolVersion exactly 1');
+    }
+    if (typeof envelope['ok'] !== 'boolean') {
+        throw protocolError(spec, `envelope is missing a boolean "ok"`, 'a boolean ok field');
+    }
+    const ok = envelope['ok'];
+    // `ok` is the source of truth; an exit-code mismatch is a soft diagnostic.
+    if (ok && res.status !== 0) {
+        diag(`crtr: ${label(spec)} returned ok:true but exited ${res.status} (honoring the envelope)`);
+    }
+    else if (!ok && res.status === 0) {
+        diag(`crtr: ${label(spec)} returned ok:false but exited 0 (honoring the envelope)`);
+    }
+    if (ok) {
+        const result = envelope['result'];
+        if (!isObject(result)) {
+            throw protocolError(spec, `success envelope has no result object`, 'result: an object matching the declared output');
+        }
+        validateResult(spec, result);
+        return result;
+    }
+    // Recoverable command failure → structured CrtrError with the plugin's code.
+    const error = envelope['error'];
+    if (!isObject(error) || typeof error['code'] !== 'string' || typeof error['message'] !== 'string') {
+        throw protocolError(spec, `error envelope is missing a { code, message }`, 'error: { code, message, ... }');
+    }
+    const code = error['code'];
+    if (!SNAKE.test(code) || RESERVED_CODES.has(code)) {
+        throw protocolError(spec, `error code "${code}" is invalid or reserved`, `a lowercase snake_case code not in {${[...RESERVED_CODES].join(', ')}}`);
+    }
+    throw new CrtrError(code, error['message'], ExitCode.GENERAL, {
+        received: error['received'],
+        field: typeof error['field'] === 'string' ? error['field'] : undefined,
+        next: typeof error['next'] === 'string' ? error['next'] : NEXT,
+    });
+}
+/** Enforce declared top-level output field presence + primitive/container
+ *  type. A missing required field or a type mismatch is a protocol error. */
+function validateResult(spec, result) {
+    const issue = validateDeclaredResult(spec.output, result);
+    if (issue === null)
+        return;
+    const field = issue.field;
+    const outputField = spec.output.find(f => f.name === field);
+    if (issue.receivedType !== undefined) {
+        throw protocolError(spec, `output field "${field}" has the wrong type`, `${field}: ${outputField?.type ?? 'unknown'}`);
+    }
+    throw protocolError(spec, `result is missing required output field "${field}"`, `a "${field}" field of type ${outputField?.type ?? 'unknown'}`);
+}
+/** Loose type check over the declared type vocabulary. Only the recognized
+ *  primitive/container categories are enforced; an unrecognized declared type
+ *  falls back to presence-only. */
+function typeMatches(type, v) {
+    const t = type.toLowerCase();
+    if (t === 'string' || t === 'path')
+        return typeof v === 'string';
+    if (t === 'int' || t === 'integer')
+        return typeof v === 'number' && Number.isInteger(v);
+    if (t === 'number' || t === 'float')
+        return typeof v === 'number';
+    if (t === 'bool' || t === 'boolean')
+        return typeof v === 'boolean';
+    if (t === 'array' || t.endsWith('[]'))
+        return Array.isArray(v);
+    if (t === 'object')
+        return isObject(v);
+    return true;
+}
+function protocolError(spec, received, expected) {
+    return new CrtrError('plugin_protocol_error', `${label(spec)}: ${received}. Expected ${expected}.`, ExitCode.GENERAL, { received, next: NEXT });
+}
+function label(spec) {
+    return `plugin "${spec.plugin.name}" command \`${spec.commandPath.join(' ')}\``;
+}
+function isObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}

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

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

@@ -0,0 +1,88 @@
+// 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. */
+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,
+        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]));
+}
+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])),
+    });
+}
+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,
+    });
+}

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

@@ -0,0 +1,74 @@
+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`. */
+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 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>;
+}
+/** 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;
+    contributions: ValidatedContribution[];
+    issues: CommandDiscoveryIssue[];
+}
+/** 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[];
+}
+/** 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 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;

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

@@ -0,0 +1,291 @@
+// Command-plugin discovery + validation.
+//
+// An installed, enabled plugin may declare `commands?: string` in its
+// `plugin.json` — a plugin-root-relative path to one declarative command
+// manifest (`commands.json`). This module reads and validates those manifests
+// WITHOUT executing any plugin code, turning each into either an accepted
+// contribution (a validated top-level branch node) or one or more typed
+// discovery issues. crtr owns parse/help/render/errors; the plugin owns one
+// executable that the adapter direct-spawns per leaf invocation.
+//
+// Everything here is invocation-local and side-effect-free: no cache, no
+// persisted state, no spawning. `discoverCommandContributions` is called only
+// on the fallthrough (non-core-fast-path) command path (see `build-root.ts`);
+// `validateEffectiveCommandPlugins` is the entry point Phase 2 lifecycle
+// surfaces (`pkg plugin show`, `sys doctor`) consume to report issues — it
+// carries cross-plugin collision issues that the per-plugin
+// `validatePluginCommands` structurally cannot see.
+import { realpathSync, readFileSync, statSync } from 'node:fs';
+import { resolve, sep } from 'node:path';
+import { listInstalledPlugins, listInstalledPluginsInRoot } from '../resolver.js';
+import { projectScopeRoots } from '../scope.js';
+import { validatePluginNode, } from '../command-manifests/schema.js';
+const MANIFEST_KEYS = new Set(['schemaVersion', 'executable', 'mounts']);
+const MOUNT_KEYS = new Set(['parent', 'node']);
+// ---------------------------------------------------------------------------
+// Effective plugin resolution (M3 — reuse, no new resolver)
+// ---------------------------------------------------------------------------
+/** 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 function effectiveCommandPlugins(startDir = process.cwd(), profileId) {
+    const seen = new Set();
+    const deduped = [];
+    const consider = (p) => {
+        if (seen.has(p.name))
+            return;
+        seen.add(p.name);
+        deduped.push(p);
+    };
+    for (const root of projectScopeRoots(startDir, profileId)) {
+        for (const p of listInstalledPluginsInRoot('project', root))
+            consider(p);
+    }
+    for (const p of listInstalledPlugins('user'))
+        consider(p);
+    return deduped.filter((p) => p.enabled && typeof p.manifest.commands === 'string' && p.manifest.commands.length > 0);
+}
+// ---------------------------------------------------------------------------
+// Discovery snapshot (tree composer entry point)
+// ---------------------------------------------------------------------------
+/** 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 function discoverPluginCommandCandidates(startDir = process.cwd(), profileId) {
+    return effectiveCommandPlugins(startDir, profileId).map((p) => validatePluginCommands(p, new Set()));
+}
+/** 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 function discoverCommandContributions(reservedNames, startDir = process.cwd(), profileId) {
+    const validations = validateEffectiveCommandPlugins(reservedNames, startDir, profileId);
+    const contributions = validations.flatMap((v) => v.contributions);
+    contributions.sort((a, b) => a.node.name.localeCompare(b.node.name));
+    return { contributions, issues: validations.flatMap((v) => v.issues) };
+}
+/** 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 function validateEffectiveCommandPlugins(reservedNames, startDir = process.cwd(), profileId) {
+    const validations = effectiveCommandPlugins(startDir, profileId).map((p) => validatePluginCommands(p, reservedNames));
+    // Plugin-vs-plugin top-level name collision: drop all claimants + flag each.
+    const claimants = new Map();
+    for (const v of validations) {
+        for (const c of v.contributions) {
+            const list = claimants.get(c.node.name);
+            if (list !== undefined)
+                list.push(v);
+            else
+                claimants.set(c.node.name, [v]);
+        }
+    }
+    for (const [name, vs] of claimants) {
+        if (vs.length === 1)
+            continue;
+        const names = vs.map((x) => x.plugin.name).join(', ');
+        for (const v of vs) {
+            v.contributions = v.contributions.filter((c) => c.node.name !== name);
+            v.issues.push({
+                code: 'command_collision',
+                plugin: v.plugin.name,
+                path: name,
+                message: `top-level command "${name}" is claimed by multiple plugins: ${names}`,
+                received: names,
+                expected: 'exactly one plugin per top-level command name',
+                next: `Disable or remove all but one of: ${names}.`,
+            });
+        }
+    }
+    return validations;
+}
+// ---------------------------------------------------------------------------
+// Per-plugin validation (Phase 2 lifecycle entry point)
+// ---------------------------------------------------------------------------
+/** 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 function validatePluginCommands(plugin, reservedNames = new Set()) {
+    const issues = [];
+    const contributions = [];
+    const rel = plugin.manifest.commands ?? '';
+    const manifestPath = resolve(plugin.root, rel);
+    const issue = (code, message, received, expected, next, path) => {
+        issues.push({ code, plugin: plugin.name, ...(path !== undefined ? { path } : {}), message, received, expected, next });
+    };
+    // Load + parse the manifest under path-safety confinement.
+    const safe = safePath(plugin.root, rel);
+    if (safe === null) {
+        issue('command_path_unsafe', `commands pointer escapes the plugin root or is not a regular file`, rel, 'a relative path to a regular file inside the plugin root', 'Fix the `commands` field in plugin.json.');
+        return { plugin, manifestPath, contributions, issues };
+    }
+    let raw;
+    try {
+        raw = readFileSync(safe, 'utf8');
+    }
+    catch {
+        issue('command_manifest_unreadable', `commands.json is missing or unreadable`, safe, 'a readable JSON file', 'Reinstall or update the plugin.');
+        return { plugin, manifestPath, contributions, issues };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        issue('command_manifest_invalid', `commands.json is not valid JSON`, safe, 'a JSON object', 'Regenerate commands.json from the plugin\'s command definitions.');
+        return { plugin, manifestPath, contributions, issues };
+    }
+    if (!isObject(parsed)) {
+        issue('command_manifest_invalid', `commands.json must be a JSON object`, typeName(parsed), 'a JSON object', 'Regenerate commands.json.');
+        return { plugin, manifestPath, contributions, issues };
+    }
+    // Top-level shape: exact schemaVersion, no unknown keys.
+    const unknown = Object.keys(parsed).filter((k) => !MANIFEST_KEYS.has(k));
+    if (unknown.length > 0) {
+        issue('command_manifest_invalid', `commands.json has unknown top-level keys`, unknown.join(', '), 'only: schemaVersion, executable, mounts', 'Remove the unknown keys.');
+        return { plugin, manifestPath, contributions, issues };
+    }
+    if (parsed['schemaVersion'] !== 1) {
+        issue('command_schema_version', `unsupported command schemaVersion`, String(parsed['schemaVersion']), 'exactly the integer 1', 'Update the plugin to a version compatible with this crtr.');
+        return { plugin, manifestPath, contributions, issues };
+    }
+    // Executable path safety + exec bit. Optional: a manifest whose mounts are all
+    // passthrough branches ships no leaf and therefore no protocol binary. A leaf
+    // without an executable is rejected per-mount below.
+    const execRel = parsed['executable'];
+    let execSafe;
+    if (execRel !== undefined) {
+        if (typeof execRel !== 'string' || execRel.length === 0) {
+            issue('command_manifest_invalid', `executable must be a non-empty string`, typeName(execRel), 'a relative path string, or omitted when the manifest declares no leaf', 'Set executable to the plugin-relative path of the command binary.', 'executable');
+            return { plugin, manifestPath, contributions, issues };
+        }
+        const resolved = safePath(plugin.root, execRel);
+        if (resolved === null) {
+            issue('command_path_unsafe', `executable escapes the plugin root or is not a regular file`, execRel, 'a relative path to a regular file inside the plugin root', 'Fix the executable path in commands.json.', 'executable');
+            return { plugin, manifestPath, contributions, issues };
+        }
+        if (!hasExecBit(resolved)) {
+            issue('command_not_executable', `executable lacks the POSIX exec bit`, execRel, 'a file with an executable permission bit', 'chmod +x the plugin\'s command binary, then update the plugin.', 'executable');
+            return { plugin, manifestPath, contributions, issues };
+        }
+        execSafe = resolved;
+    }
+    // Mounts.
+    const mounts = parsed['mounts'];
+    if (!Array.isArray(mounts)) {
+        issue('command_manifest_invalid', `mounts must be an array`, typeName(mounts), 'an array of mounts', 'Declare at least one mount.', 'mounts');
+        return { plugin, manifestPath, ...(execSafe !== undefined ? { executable: execSafe } : {}), contributions, issues };
+    }
+    if (mounts.length === 0) {
+        issue('command_manifest_invalid', `manifest declares no mounts (inert)`, '[]', 'at least one top-level mount', 'Declare a mount, or drop the `commands` field.', 'mounts');
+    }
+    const topNames = new Set();
+    mounts.forEach((mount, i) => {
+        const pathStr = `mounts[${i}]`;
+        if (!isObject(mount)) {
+            issue('command_node_invalid', `mount must be an object`, typeName(mount), 'a { parent, node } object', 'Fix the mount.', pathStr);
+            return;
+        }
+        const mUnknown = Object.keys(mount).filter((k) => !MOUNT_KEYS.has(k));
+        if (mUnknown.length > 0) {
+            issue('command_node_invalid', `mount has unknown keys`, mUnknown.join(', '), 'only: parent, node', 'Remove the unknown keys.', pathStr);
+            return;
+        }
+        // v1: top-level mounts only — parent must be [].
+        if (!Array.isArray(mount['parent']) || mount['parent'].length !== 0) {
+            issue('command_parent_invalid', `mount parent must be [] (top-level only in v1)`, JSON.stringify(mount['parent']), 'an empty array []', 'Mount the node at top level; nested mounts are not supported in v1.', `${pathStr}.parent`);
+            return;
+        }
+        const node = validatePluginNode(mount['node'], `${pathStr}.node`, true, issue);
+        if (node === null)
+            return;
+        // node is a top-level branch here (validatePluginNode enforced kind + rootEntry).
+        if (topNames.has(node.name)) {
+            issue('command_node_invalid', `this plugin declares two top-level commands named "${node.name}"`, node.name, 'a unique top-level command name per plugin', 'Rename one of the duplicate top-level mounts.', `${pathStr}.node.name`);
+            return;
+        }
+        topNames.add(node.name);
+        if (reservedNames.has(node.name)) {
+            issue('command_collision', `top-level command "${node.name}" collides with a core command`, node.name, 'a name not used by a core crtr command', 'Rename the plugin\'s top-level command.', `${pathStr}.node.name`);
+            return;
+        }
+        if (execSafe === undefined && declaresLeaf(node)) {
+            issue('command_manifest_invalid', `manifest declares a leaf but no executable`, '(missing)', 'an executable path, or a leafless (passthrough-only) mount', 'Add `executable` to commands.json — every leaf runs the plugin binary over the command protocol.', `${pathStr}.node`);
+            return;
+        }
+        contributions.push({ plugin, ...(execSafe !== undefined ? { executable: execSafe } : {}), node: node });
+    });
+    return { plugin, manifestPath, ...(execSafe !== undefined ? { executable: execSafe } : {}), contributions, issues };
+}
+/** True when any node in the subtree is a leaf — i.e. the contribution needs a
+ *  protocol executable. */
+function declaresLeaf(node) {
+    if (node.kind === 'leaf')
+        return true;
+    return node.children.some((c) => declaresLeaf(c));
+}
+// ---------------------------------------------------------------------------
+// Small helpers
+// ---------------------------------------------------------------------------
+function isObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function typeName(v) {
+    if (v === null)
+        return 'null';
+    if (Array.isArray(v))
+        return 'array';
+    return typeof v;
+}
+function checkKeys(raw, allowed, path, issue) {
+    const unknown = Object.keys(raw).filter((k) => !allowed.has(k));
+    if (unknown.length > 0) {
+        issue('command_node_invalid', `unknown keys`, unknown.join(', '), `only: ${[...allowed].join(', ')}`, 'Remove the unknown keys.', path);
+        return false;
+    }
+    return true;
+}
+/** Resolve `rel` under `root`, confining it to the realpath'd root and
+ *  requiring a regular file. Returns the resolved absolute path or null. */
+function safePath(root, rel) {
+    if (typeof rel !== 'string' || rel.length === 0)
+        return null;
+    let rootReal;
+    let real;
+    try {
+        rootReal = realpathSync(root);
+        real = realpathSync(resolve(root, rel));
+    }
+    catch {
+        return null;
+    }
+    if (real !== rootReal && !real.startsWith(rootReal + sep))
+        return null;
+    try {
+        if (!statSync(real).isFile())
+            return null;
+    }
+    catch {
+        return null;
+    }
+    return real;
+}
+function hasExecBit(file) {
+    try {
+        return (statSync(file).mode & 0o111) !== 0;
+    }
+    catch {
+        return false;
+    }
+}