@crouton-kit/crouter 0.3.78 → 0.3.80

package/dist/core/canvas/browse/app.js

@@ -17,6 +17,28 @@ import { setupTerminal, restoreTerminal, getTerminalSize, parseKeypress, } from
 import { buildTree, flatten, pruneNode, TABS } from './model.js';
 import { loadPins, savePins } from './pins.js';
 import { createCoalescedRebuilder } from './rebuild-coalescer.js';
+import { matchesTerminalInput, resolveUserKeybindings, } from '../../keybindings/index.js';
+const BROWSE_NAV_ACTIONS = [
+    'crtr.browse.quit', 'crtr.browse.down', 'crtr.browse.up', 'crtr.browse.first', 'crtr.browse.last',
+    'crtr.browse.expand-or-child', 'crtr.browse.collapse-or-parent', 'crtr.browse.toggle-fold',
+    'crtr.browse.tab-next', 'crtr.browse.tab-previous', 'crtr.browse.tab.1', 'crtr.browse.tab.2',
+    'crtr.browse.tab.3', 'crtr.browse.tab.4', 'crtr.browse.tab.5', 'crtr.browse.close-subtree', 'crtr.browse.sort',
+    'crtr.browse.scope', 'crtr.browse.residents', 'crtr.browse.preview', 'crtr.browse.search',
+    'crtr.browse.revive-now', 'crtr.browse.focus',
+];
+const BROWSE_SEARCH_ACTIONS = [
+    'crtr.browse.search.cancel', 'crtr.browse.search.commit', 'crtr.browse.search.delete',
+    'crtr.browse.search.quit',
+];
+function firstMatching(bindings, ids, raw) {
+    return ids.find((id) => matchesTerminalInput(bindings, id, raw)) ?? null;
+}
+export function resolveBrowseNavAction(bindings, raw) {
+    return firstMatching(bindings, BROWSE_NAV_ACTIONS, raw);
+}
+export function resolveBrowseSearchAction(bindings, raw) {
+    return firstMatching(bindings, BROWSE_SEARCH_ACTIONS, raw);
+}
 // Sort cycle for the `s` key. Starts on the default `attention` ordering; one `s`
 // press restores the structural `tree` view, then relevance/recency, then back.
 const SORT_CYCLE = ['attention', 'tree', 'relevance', 'recency'];
@@ -45,6 +67,7 @@ export function wireEventStreamRebuild(eventStream, rebuild) {
 export async function runBrowse(opts = {}) {
     const source = opts.source ?? localCanvasSource;
     const isRemote = source instanceof RemoteCanvasSource;
+    const bindings = resolveUserKeybindings();
     // No TTY → print the static forest and exit 0 (no raw mode).
     if (!process.stdin.isTTY) {
         process.stdout.write(await renderForestFromSource(source) + '\n');
@@ -310,6 +333,13 @@ export async function runBrowse(opts = {}) {
             n.row.status = m.status; // real post-close status (done / canceled)
             n.row.streaming = false;
             n.row.viewed = false;
+            // A finalized node is no longer hanging and owes no answer — clear both so it
+            // actually LEAVES the Attention tab (asks>0 || hanging) and stops rendering the
+            // stale `⚠ down` rail. Without this, closing a faulted/asking node from the
+            // Attention tab looks like a no-op: the row was finalized in the db but its
+            // stale fault/ask kept it matching the tab, so it never disappeared.
+            n.row.hanging = null;
+            n.row.asks = 0;
         }
         // Keep the cursor at the same INDEX (the row that shifts up into the closed
         // slot), not pinned to the now-gone node — recompute() leaves state.cursor
@@ -389,7 +419,8 @@ export async function runBrowse(opts = {}) {
         });
     };
     const onKeySearch = (input, key) => {
-        if (key.escape) {
+        const action = resolveBrowseSearchAction(bindings, { input, ...key });
+        if (action === 'crtr.browse.search.cancel') {
             // Cancel the search: drop the query AND the relevance ranking it switched
             // on, returning to the tree. Synchronous: we're leaving search mode.
             state.search = false;
@@ -399,7 +430,7 @@ export async function runBrowse(opts = {}) {
             scheduleFlush();
             return;
         }
-        if (key.return) {
+        if (action === 'crtr.browse.search.commit') {
             // Commit: keep the filter, drop search mode, land on the first match. Must
             // recompute synchronously first so the match index reflects the final query
             // even if a coalesced repaint is still pending.
@@ -411,17 +442,16 @@ export async function runBrowse(opts = {}) {
             scheduleFlush();
             return;
         }
-        if (key.backspace) {
+        if (action === 'crtr.browse.search.delete') {
             state.query = state.query.slice(0, -1);
             scheduleSearchRepaint();
             return;
         }
-        // Any ctrl-combo: Ctrl+C quits; everything else is swallowed (never typed).
-        if (key.ctrl) {
-            if (input === 'c')
-                quit();
+        // Bound quit acts before text capture; other ctrl-combos are swallowed.
+        if (action === 'crtr.browse.search.quit')
+            quit();
+        if (key.ctrl)
             return;
-        }
         // Append every printable char in the chunk. Fast typing batches multiple
         // chars into one stdin read, so we must take them all (not just a length-1
         // chunk) or keystrokes get dropped. Filtering to >= ' ' strips control/escape
@@ -530,17 +560,17 @@ export async function runBrowse(opts = {}) {
         scheduleFlush();
     };
     const onKeyNav = (input, key) => {
-        // Ctrl-combos first: only Ctrl+C is meaningful (quit); swallow the rest so
-        // Ctrl+L / Ctrl+J / Ctrl+Q etc. don't masquerade as l/j/q commands.
-        if (key.ctrl) {
-            if (input === 'c')
-                quit();
-            return;
-        }
-        // Close-out confirm sub-state: a streaming node is awaiting y/n. Swallow every
-        // other key so the confirm is modal.
+        const raw = { input, ...key };
+        const action = resolveBrowseNavAction(bindings, raw);
+        // Unbound ctrl-combos are swallowed so they never masquerade as printable commands.
+        if (key.ctrl && action === null)
+            return;
+        // Preserve an explicitly bound control-combo quit while the close confirmation is open.
+        // Other non-confirming input dismisses the modal without also running navigation actions.
+        if (state.pendingClose !== null && action === 'crtr.browse.quit' && key.ctrl)
+            quit();
         if (state.pendingClose !== null) {
-            if (input === 'y' || input === 'Y') {
+            if (matchesTerminalInput(bindings, 'crtr.browse.confirm-close', raw)) {
                 const target = state.pendingClose;
                 void doClose(target).then(() => scheduleFlush()).catch(() => scheduleFlush());
                 return;
@@ -551,32 +581,31 @@ export async function runBrowse(opts = {}) {
             return;
         }
         const row = curRow();
-        // Quit.
-        if (input === 'q' || key.escape)
+        // Quit and move.
+        if (action === 'crtr.browse.quit')
             quit();
-        // Move.
-        if (key.upArrow || input === 'k') {
+        if (action === 'crtr.browse.up') {
             state.cursor = Math.max(0, state.cursor - 1);
             scheduleFlush();
             return;
         }
-        if (key.downArrow || input === 'j') {
+        if (action === 'crtr.browse.down') {
             state.cursor = Math.max(0, Math.min(visible.length - 1, state.cursor + 1));
             scheduleFlush();
             return;
         }
-        if (input === 'g') {
+        if (action === 'crtr.browse.first') {
             state.cursor = 0;
             scheduleFlush();
             return;
         }
-        if (input === 'G') {
+        if (action === 'crtr.browse.last') {
             state.cursor = Math.max(0, visible.length - 1);
             scheduleFlush();
             return;
         }
         // Expand / descend.
-        if (key.rightArrow || input === 'l') {
+        if (action === 'crtr.browse.expand-or-child') {
             if (row !== undefined && row.hasChildren) {
                 if (!isExpanded(row.id)) {
                     state.collapsed.delete(row.id);
@@ -590,7 +619,7 @@ export async function runBrowse(opts = {}) {
             return;
         }
         // Collapse / ascend.
-        if (key.leftArrow || input === 'h') {
+        if (action === 'crtr.browse.collapse-or-parent') {
             if (row !== undefined && row.hasChildren && isExpanded(row.id)) {
                 state.collapsed.add(row.id);
                 recompute(row.id);
@@ -607,7 +636,7 @@ export async function runBrowse(opts = {}) {
             return;
         }
         // Toggle collapse.
-        if (input === ' ') {
+        if (action === 'crtr.browse.toggle-fold') {
             if (row !== undefined && row.hasChildren) {
                 if (isExpanded(row.id))
                     state.collapsed.add(row.id);
@@ -618,19 +647,20 @@ export async function runBrowse(opts = {}) {
             scheduleFlush();
             return;
         }
-        // Tabs.
-        if (key.tab || input === ']') {
+        // Tabs. next/previous and tab.1–5 (including Pinned) all resolve through the
+        // catalog, so each numbered tab is user-remappable like any other binding.
+        if (action === 'crtr.browse.tab-next') {
             cycleTab(1);
             scheduleFlush();
             return;
         }
-        if (key.shiftTab || input === '[') {
+        if (action === 'crtr.browse.tab-previous') {
             cycleTab(-1);
             scheduleFlush();
             return;
         }
-        if (input >= '1' && input <= '5') {
-            const idx = Number(input) - 1;
+        if (action?.startsWith('crtr.browse.tab.')) {
+            const idx = Number(action.slice(-1)) - 1;
             if (idx < TABS.length) {
                 state.tab = TABS[idx];
                 state.cursor = 0;
@@ -643,7 +673,7 @@ export async function runBrowse(opts = {}) {
         // Close-out the selected node (+ its exclusive subtree). If anything in that
         // subtree is actively streaming, confirm first (y/n); otherwise close at once.
         // No-op against a remote canvas — mutations are disabled (footer says so).
-        if (input === 'x') {
+        if (action === 'crtr.browse.close-subtree') {
             if (isRemote)
                 return;
             if (row === undefined) {
@@ -659,22 +689,22 @@ export async function runBrowse(opts = {}) {
             return;
         }
         // Sort / scope / residents / preview.
-        if (input === 's') {
+        if (action === 'crtr.browse.sort') {
             cycleSort();
             scheduleFlush();
             return;
         }
-        if (input === 'c') {
+        if (action === 'crtr.browse.scope') {
             toggleScope();
             scheduleFlush();
             return;
         }
-        if (input === 'r') {
+        if (action === 'crtr.browse.residents') {
             toggleResidents();
             scheduleFlush();
             return;
         }
-        if (input === 'p') {
+        if (action === 'crtr.browse.preview') {
             state.preview = !state.preview;
             scheduleFlush();
             return;
@@ -724,7 +754,7 @@ export async function runBrowse(opts = {}) {
         }
         // Search. Starting a search ranks by relevance (decision) so the best prompt/
         // name match floats to the top as you type.
-        if (input === '/') {
+        if (action === 'crtr.browse.search') {
             state.search = true;
             state.query = '';
             state.sort = 'relevance';
@@ -740,7 +770,7 @@ export async function runBrowse(opts = {}) {
         // --now` (browse goes through commands, never touching the runtime directly). 'k' is
         // vim-up here, so the kick is on SHIFT-K.
         // No-op against a remote canvas — mutations are disabled (footer says so).
-        if (input === 'K') {
+        if (action === 'crtr.browse.revive-now') {
             if (isRemote)
                 return;
             if (row !== undefined) {
@@ -753,7 +783,7 @@ export async function runBrowse(opts = {}) {
         }
         // Resume. No-op against a remote canvas — mutations/focus are disabled
         // (footer says so).
-        if (key.return) {
+        if (action === 'crtr.browse.focus') {
             if (isRemote)
                 return;
             if (row !== undefined)

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

@@ -0,0 +1,15 @@
+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[];
+}
+/** 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,145 @@
+// 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.';
+/** 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) {
+    for (const f of spec.output) {
+        const present = Object.prototype.hasOwnProperty.call(result, f.name) && result[f.name] !== undefined && result[f.name] !== null;
+        if (f.required && !present) {
+            throw protocolError(spec, `result is missing required output field "${f.name}"`, `a "${f.name}" field of type ${f.type}`);
+        }
+        if (present && !typeMatches(f.type, result[f.name])) {
+            throw protocolError(spec, `output field "${f.name}" has the wrong type`, `${f.name}: ${f.type}`);
+        }
+    }
+}
+/** 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,5 @@
+import type { BranchDef } from '../command.js';
+import type { CommandRegistrySnapshot } from './discovery.js';
+/** Map an accepted registry snapshot to real top-level BranchDefs, ready to
+ *  concatenate beside core subtrees in `buildRoot()`. */
+export declare function composeExternalSubtrees(snapshot: CommandRegistrySnapshot): BranchDef[];

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

@@ -0,0 +1,56 @@
+// Tree composer — adapt validated declarative nodes 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
+// the external adapter. Composition is deterministic: contributions arrive
+// already sorted by name from discovery.
+import { defineBranch, defineLeaf } from '../command.js';
+import { executeExternalLeaf } from './adapter.js';
+/** Map an accepted registry snapshot to real top-level BranchDefs, ready to
+ *  concatenate beside core subtrees in `buildRoot()`. */
+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 } : {}),
+        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) {
+    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: 'object',
+            effects: node.effects,
+        },
+        run: async (input) => executeExternalLeaf({ plugin: contribution.plugin, executable: contribution.executable, commandPath: path, output: node.output }, input),
+    });
+}

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

@@ -0,0 +1,104 @@
+import type { InstalledPlugin } from '../../types.js';
+import type { InputParam, Field } from '../help.js';
+/** A stable, doctor-renderable validation issue. Never thrown — accumulated
+ *  and surfaced through `pkg plugin show` / `sys doctor`. */
+export interface CommandDiscoveryIssue {
+    /** Stable code the surfaces branch on. */
+    code: CommandIssueCode;
+    /** The offending plugin's name. */
+    plugin: string;
+    /** Dotted path to the offending field/node within the manifest, when known. */
+    path?: string;
+    message: string;
+    received: string;
+    expected: string;
+    next: string;
+}
+export type CommandIssueCode = 'command_manifest_unreadable' | 'command_manifest_invalid' | 'command_schema_version' | 'command_path_unsafe' | 'command_not_executable' | 'command_parent_invalid' | 'command_node_invalid' | 'command_collision';
+/** The validated declarative node schema (static-only — no closures, no
+ *  dynamicState, no renderers). Params/output reuse the existing public help
+ *  vocabulary so composition maps them straight through. */
+export interface DeclRootEntry {
+    concept: string;
+    description: string;
+    whenToUse: string;
+}
+export interface DeclBranch {
+    kind: 'branch';
+    name: string;
+    description: string;
+    whenToUse: string;
+    tier?: 'normal' | 'common' | 'important';
+    /** Required on a top-level branch, forbidden on a nested one. */
+    rootEntry?: DeclRootEntry;
+    summary: string;
+    model?: string;
+    children: DeclNode[];
+}
+export interface DeclLeaf {
+    kind: 'leaf';
+    name: string;
+    description: string;
+    whenToUse: string;
+    tier?: 'normal' | 'common' | 'important';
+    summary: string;
+    params: InputParam[];
+    output: Field[];
+    outputKind: 'object';
+    effects: string[];
+}
+export type DeclNode = DeclBranch | DeclLeaf;
+/** 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. */
+    executable: string;
+    /** The validated top-level branch node (always kind 'branch'). */
+    node: DeclBranch;
+}
+/** 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[];
+/** 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;