@crouter/api 0.3.377

package/dist/api/command-manifest/index.d.ts

@@ -0,0 +1,3 @@
+export * from './schema.js';
+export * from './manifest.js';
+export * from './result.js';

package/dist/api/command-manifest/index.js

@@ -0,0 +1,3 @@
+export * from './schema.js';
+export * from './manifest.js';
+export * from './result.js';

package/dist/api/command-manifest/manifest.d.ts

@@ -0,0 +1,51 @@
+import type { DeclLeaf, DeclNode, TransportKind, ManifestTimeouts, CommandManifestIssue } from './schema.js';
+export interface ValidatedCoreMount {
+    /** The explicitly extensible core branch receiving this plugin node. */
+    parent: string[];
+    node: DeclNode<DeclLeaf>;
+}
+export interface ValidatedCommandManifest {
+    schemaVersion: 1;
+    /** The plugin's declared integer major (HTTP transport only); absent means
+     *  undeclared, which a locally installed plugin treats as 1. */
+    version?: number;
+    baseUrl?: string;
+    timeouts?: ManifestTimeouts;
+    /** Top-level plugin branches or repository-fragment nodes, ready to mount. */
+    roots: DeclNode<DeclLeaf>[];
+    /** Plugin nodes mounted below an explicitly extensible core branch. */
+    coreMounts: ValidatedCoreMount[];
+    /** Core command path (space-joined, e.g. "cron add") → attributed addendum
+     *  text appended beneath that core command's help. Append-only product
+     *  guidance — a plugin can never alter core contract text. */
+    helpAddenda?: Readonly<Record<string, string>>;
+}
+export interface CommandManifestValidation {
+    /** The validated, materialized manifest (present only if all issues are fixed). */
+    manifest?: ValidatedCommandManifest;
+    /** All typed validation issues. Any issue means zero contributions. */
+    issues: CommandManifestIssue[];
+}
+/**
+ * Validates a HTTP-transport plugin manifest exactly per §4, performing strict atomic
+ * validation and order-independent forest materialization. Returns either a
+ * valid manifest with roots ready to mount, or a complete issues list with
+ * zero contributions.
+ */
+export declare function validateCommandManifest(raw: unknown, options: {
+    transport: TransportKind;
+    reservedCoreNames: ReadonlySet<string>;
+    /** Every core command path (space-joined). Supplied at the strict gates
+     *  (install, bundle parse, doctor/inspect reports) so a helpAddenda key
+     *  naming no core command fails there — and by the help-render lookup
+     *  (`collectHelpAddenda`), which reproduces the gate's verdict so render
+     *  and ingress report can never disagree. Omitted on the tolerant compose
+     *  path, where mounting ignores addenda entirely, and on that lookup's
+     *  claimant pass, which only needs to know whether any addendum targets the
+     *  rendered path at all. */
+    coreCommandPaths?: ReadonlySet<string>;
+    /** A repository fragment attaches roots below an existing extensible branch. */
+    extensionFragment?: boolean;
+    /** Core branch names that accept plugin children. */
+    extensibleCoreBranches?: ReadonlySet<string>;
+}): CommandManifestValidation;

package/dist/api/command-manifest/manifest.js

@@ -0,0 +1,332 @@
+// Transport-parameterized command manifest validation and forest materialization.
+//
+// Validates command manifests atomically, materializes self-contained forests
+// independent of nested-mount order when the parent is inline, validates REST
+// mappings, and enforces the canonical coalesced-body-source rule (exactly one
+// stdin + one non-stdin flag/positional sharing a body `as`).
+//
+// This is pure validation: no fetch, no registration lookup, no file I/O beyond
+// the raw manifest bytes passed in.
+import { validateCommandNode } from './schema.js';
+import { isRecord } from '../../shared/predicates.js';
+// Validation helpers
+const KEBAB = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+const REST_METHODS = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']);
+function typeName(v) {
+    if (v === null)
+        return 'null';
+    if (Array.isArray(v))
+        return 'array';
+    return typeof v;
+}
+// Top-level manifest validation
+/**
+ * Validates a HTTP-transport plugin manifest exactly per §4, performing strict atomic
+ * validation and order-independent forest materialization. Returns either a
+ * valid manifest with roots ready to mount, or a complete issues list with
+ * zero contributions.
+ */
+export function validateCommandManifest(raw, options) {
+    const issues = [];
+    const issue = (code, message, received, expected, next, path) => {
+        issues.push({ code, message, received, expected, next, ...(path ? { path } : {}) });
+    };
+    // Top-level structure check
+    if (!isRecord(raw)) {
+        issue('command_manifest_invalid', 'manifest must be an object', typeName(raw), options.extensionFragment === true ? '{ schemaVersion, transport, mounts }' : options.transport === 'http' ? '{ schemaVersion, version?, baseUrl?, timeouts?, mounts, helpAddenda? }' : '{ schemaVersion, mounts, helpAddenda? }', 'Provide a valid JSON manifest object.');
+        return { issues };
+    }
+    // Check for unknown top-level keys
+    const topKeys = Object.keys(raw);
+    const allowedTopKeys = options.extensionFragment === true
+        ? new Set(['schemaVersion', 'transport', 'mounts'])
+        : options.transport === 'http'
+            ? new Set(['schemaVersion', 'version', 'baseUrl', 'timeouts', 'mounts', 'helpAddenda'])
+            : new Set(['schemaVersion', 'mounts', 'helpAddenda']);
+    const unknownKeys = topKeys.filter((k) => !allowedTopKeys.has(k));
+    if (unknownKeys.length > 0) {
+        issue('command_manifest_invalid', `unknown top-level keys`, unknownKeys.join(', '), options.extensionFragment === true ? 'only: schemaVersion, transport, mounts' : options.transport === 'http' ? 'only: schemaVersion, version, baseUrl, timeouts, mounts, helpAddenda' : 'only: schemaVersion, mounts, helpAddenda', 'Remove the unknown keys.');
+        return { issues };
+    }
+    // Validate schemaVersion
+    if (raw['schemaVersion'] !== 1) {
+        issue('command_schema_version', `schemaVersion must be exactly 1`, String(raw['schemaVersion']), '1', 'Update the manifest schema version to 1.', 'schemaVersion');
+        return { issues };
+    }
+    // Validate optional plugin major version (HTTP only; the key is unknown elsewhere)
+    let version;
+    if (options.transport === 'http' && options.extensionFragment !== true && raw['version'] !== undefined) {
+        const v = raw['version'];
+        if (typeof v !== 'number' || !Number.isInteger(v) || v < 1) {
+            issue('command_manifest_invalid', 'version must be an integer of at least 1', typeName(v) === 'number' ? String(v) : typeName(v), 'the plugin major version as an integer >= 1, or omitted', 'Set version to the plugin\'s integer major.', 'version');
+            return { issues };
+        }
+        version = v;
+    }
+    // Validate optional baseUrl
+    let baseUrl;
+    if (options.transport === 'http' && raw['baseUrl'] !== undefined) {
+        if (typeof raw['baseUrl'] !== 'string') {
+            issue('command_manifest_invalid', 'baseUrl must be a string', typeName(raw['baseUrl']), 'an absolute HTTP(S) URL or omitted', 'Provide a valid baseUrl or remove it.', 'baseUrl');
+            return { issues };
+        }
+        try {
+            const url = new URL(raw['baseUrl']);
+            if (!['http:', 'https:'].includes(url.protocol)) {
+                issue('command_manifest_invalid', 'baseUrl must be http: or https:', url.protocol, 'http: or https:', 'Use an HTTP(S) URL.', 'baseUrl');
+                return { issues };
+            }
+            baseUrl = raw['baseUrl'];
+        }
+        catch {
+            issue('command_manifest_invalid', 'baseUrl must be a valid absolute URL', raw['baseUrl'], 'a valid URL', 'Fix the baseUrl.', 'baseUrl');
+            return { issues };
+        }
+    }
+    // Validate optional timeouts
+    let timeouts;
+    if (options.transport === 'http' && raw['timeouts'] !== undefined) {
+        const t = validateTimeouts(raw['timeouts'], issue);
+        if (t === null)
+            return { issues };
+        timeouts = t;
+    }
+    // Validate optional helpAddenda (both transports)
+    let helpAddenda;
+    if (raw['helpAddenda'] !== undefined) {
+        const h = validateHelpAddenda(raw['helpAddenda'], options.coreCommandPaths, issue);
+        if (h === null)
+            return { issues };
+        if (Object.keys(h).length > 0)
+            helpAddenda = h;
+    }
+    // Validate mounts (required, non-empty)
+    const mounts = raw['mounts'];
+    if (!Array.isArray(mounts)) {
+        issue('command_manifest_invalid', 'mounts must be an array', typeName(mounts), 'a non-empty array of { parent, node } contributions', 'Provide at least one mount.', 'mounts');
+        return { issues };
+    }
+    if (mounts.length === 0) {
+        issue('command_manifest_invalid', 'mounts must be a non-empty array', 'empty array', 'at least one contribution', 'Add at least one mount.', 'mounts');
+        return { issues };
+    }
+    // Validate and collect all mounts
+    const validatedMounts = [];
+    for (let i = 0; i < mounts.length; i++) {
+        const m = validateMount(mounts[i], i, options.transport, issue, options.extensionFragment === true ? { topLevelRootEntry: 'forbidden', allowPassthrough: false, allowExtensible: false } : undefined);
+        if (m === null)
+            return { issues };
+        validatedMounts.push(m);
+    }
+    // Materialize plugin-local trees separately from mounts below an explicitly
+    // extensible core branch. Core mounts remain nodes, never fake plugin roots.
+    const coreMounts = validatedMounts.filter((mount) => mount.parent.length > 0 && options.extensibleCoreBranches?.has(mount.parent.join(' ')) === true);
+    for (const mount of coreMounts) {
+        const parent = mount.parent.join(' ');
+        if (options.coreCommandPaths?.has(`${parent} ${mount.node.name}`) === true) {
+            issue('command_collision', `contributed command "${mount.node.name}" conflicts with a child the extensible core branch already owns`, mount.node.name, `a name not already owned by the ${parent} core branch`, 'Rename the contributed command or remove this mount.', `${mount.parent.join('.')}.${mount.node.name}`);
+            return { issues };
+        }
+    }
+    const roots = materializeForest(validatedMounts.filter((mount) => !coreMounts.includes(mount)), options.reservedCoreNames, options.extensibleCoreBranches, issue);
+    if (roots === null)
+        return { issues };
+    // If we got here with no issues, return the validated manifest
+    if (issues.length === 0) {
+        return {
+            manifest: {
+                schemaVersion: 1,
+                ...(version !== undefined ? { version } : {}),
+                ...(baseUrl !== undefined ? { baseUrl } : {}),
+                ...(timeouts !== undefined ? { timeouts } : {}),
+                ...(helpAddenda !== undefined ? { helpAddenda } : {}),
+                roots,
+                coreMounts,
+            },
+            issues: [],
+        };
+    }
+    // Any issue found -> zero contributions
+    return { issues };
+}
+// Timeouts validation
+function validateTimeouts(raw, issue) {
+    if (!isRecord(raw)) {
+        issue('command_manifest_invalid', 'timeouts must be an object', typeName(raw), '{ connectMs?, requestMs?, streamIdleMs? }', 'Fix timeouts.', 'timeouts');
+        return null;
+    }
+    const allowedKeys = new Set(['connectMs', 'requestMs', 'streamIdleMs']);
+    const unknownKeys = Object.keys(raw).filter((k) => !allowedKeys.has(k));
+    if (unknownKeys.length > 0) {
+        issue('command_manifest_invalid', 'unknown timeouts keys', unknownKeys.join(', '), 'only: connectMs, requestMs, streamIdleMs', 'Remove the unknown keys.', 'timeouts');
+        return null;
+    }
+    const out = {};
+    for (const k of ['connectMs', 'requestMs', 'streamIdleMs']) {
+        if (raw[k] !== undefined) {
+            if (typeof raw[k] !== 'number' || !Number.isInteger(raw[k]) || raw[k] <= 0) {
+                issue('command_manifest_invalid', `${k} must be a positive integer`, String(raw[k]), 'a positive integer', `Fix ${k}.`, `timeouts.${k}`);
+                return null;
+            }
+            out[k] = raw[k];
+        }
+    }
+    return out;
+}
+// Help addenda validation
+/** Validate the optional top-level `helpAddenda` map: core command path →
+ *  addendum text rendered as an attributed block beneath that core command's
+ *  help. When the caller supplies the core command path set, a key naming no
+ *  existing core path is rejected outright — a typo fails at the gate, never
+ *  silently at render. */
+function validateHelpAddenda(raw, coreCommandPaths, issue) {
+    if (!isRecord(raw)) {
+        issue('command_manifest_invalid', 'helpAddenda must be an object', typeName(raw), 'a map of core command path → addendum text', 'Fix helpAddenda.', 'helpAddenda');
+        return null;
+    }
+    const out = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (key.split(' ').some((t) => !KEBAB.test(t))) {
+            issue('command_help_addendum_invalid', 'helpAddenda key must be a space-separated core command path', key, 'kebab tokens separated by single spaces (e.g. "cron" or "cron add")', 'Fix the helpAddenda key.', `helpAddenda.${key}`);
+            return null;
+        }
+        if (typeof value !== 'string' || value.length === 0) {
+            issue('command_manifest_invalid', 'helpAddenda value must be a non-empty string', typeof value === 'string' ? 'empty string' : typeName(value), 'non-empty addendum text', 'Fix the helpAddenda value.', `helpAddenda.${key}`);
+            return null;
+        }
+        if (coreCommandPaths !== undefined && !coreCommandPaths.has(key)) {
+            issue('command_help_addendum_invalid', 'helpAddenda key names no crtr core command path', key, 'an existing core command path (e.g. "cron", "cron add")', 'Fix the key or remove the addendum.', `helpAddenda.${key}`);
+            return null;
+        }
+        out[key] = value;
+    }
+    return out;
+}
+function validateMount(raw, index, transport, issue, nodeOptions) {
+    const path = `mounts[${index}]`;
+    if (!isRecord(raw)) {
+        issue('command_manifest_invalid', 'mount must be an object', typeName(raw), '{ parent, node }', 'Fix the mount.', path);
+        return null;
+    }
+    const allowedKeys = new Set(['parent', 'node']);
+    const unknownKeys = Object.keys(raw).filter((k) => !allowedKeys.has(k));
+    if (unknownKeys.length > 0) {
+        issue('command_manifest_invalid', 'unknown mount keys', unknownKeys.join(', '), 'only: parent, node', 'Remove the unknown keys.', path);
+        return null;
+    }
+    // Validate parent
+    const parentRaw = raw['parent'];
+    if (!Array.isArray(parentRaw)) {
+        issue('command_manifest_invalid', 'mount parent must be an array', typeName(parentRaw), 'an array of kebab tokens, or [] for a top-level mount', 'Fix parent.', `${path}.parent`);
+        return null;
+    }
+    for (let i = 0; i < parentRaw.length; i++) {
+        const t = parentRaw[i];
+        if (typeof t !== 'string' || !KEBAB.test(t)) {
+            issue('command_manifest_invalid', `parent token must be a kebab token`, String(t), 'a kebab-case identifier', 'Fix the parent path.', `${path}.parent[${i}]`);
+            return null;
+        }
+    }
+    const parent = parentRaw;
+    // Validate node
+    const nodeRaw = raw['node'];
+    const topLevel = parent.length === 0;
+    const node = validateCommandNode(nodeRaw, [`${path}.node`], topLevel, transport, issue, nodeOptions);
+    if (node === null)
+        return null;
+    return { parent, node };
+}
+// Forest materialization (order-independent)
+/**
+ * Materializes a flat list of mounts into a forest of top-level branches,
+ * resolving nested mounts whose parent exists in a top-level inline tree regardless of order. Nested mounts that provide another nested mount's parent must appear first. Validates self-containment and no duplicates.
+ */
+function materializeForest(mounts, reservedCoreNames, extensibleCoreBranches, issue) {
+    // Separate top-level (parent: []) from nested (parent non-empty)
+    const topLevel = mounts.filter((m) => m.parent.length === 0);
+    const nested = mounts.filter((m) => m.parent.length > 0);
+    // Check for core-name collisions in top-level nodes
+    for (const m of topLevel) {
+        if (reservedCoreNames.has(m.node.name)) {
+            issue('command_collision', `node name conflicts with a crtr core command`, m.node.name, `a name not in core (not one of: ${[...reservedCoreNames].join(', ')})`, 'Rename the node or remove this mount.', `${m.node.name}`);
+            return null;
+        }
+    }
+    // Build the forest: all top-level nodes with inline children, then attach nested mounts.
+    const roots = topLevel.map((m) => m.node.kind === 'branch'
+        ? { ...m.node, children: [...m.node.children] }
+        : { ...m.node });
+    for (const mount of nested) {
+        if (reservedCoreNames.has(mount.parent[0])) {
+            issue('command_parent_invalid', 'parent path starts with a core branch that is not extensible', mount.parent[0], `an extensible core branch (one of: ${[...(extensibleCoreBranches ?? [])].join(', ')})`, `Mount below one of the extensible core branches: ${[...(extensibleCoreBranches ?? [])].join(', ')}.`, mount.parent.join('.'));
+            return null;
+        }
+    }
+    // Attach nested mounts
+    for (const mount of nested) {
+        const resolved = resolveAndAttachMount(roots, mount, issue);
+        if (!resolved)
+            return null;
+    }
+    // Collect all paths as we materialize (for verification)
+    const pathIndex = new Set();
+    const indexPaths = (node, path) => {
+        const fullPath = path.join('.');
+        if (pathIndex.has(fullPath)) {
+            issue('command_node_invalid', `duplicate node path`, fullPath, 'unique paths within the manifest', 'Remove the duplicate node.', fullPath);
+            return false;
+        }
+        pathIndex.add(fullPath);
+        if (node.kind === 'branch') {
+            return node.children.every((child) => indexPaths(child, [...path, child.name]));
+        }
+        return true;
+    };
+    for (const root of roots) {
+        if (!indexPaths(root, [root.name]))
+            return null;
+    }
+    return roots;
+}
+/**
+ * Resolves a nested mount's parent path within the built roots and attaches
+ * the node. Validates that the parent exists and is a branch.
+ */
+function resolveAndAttachMount(roots, mount, issue) {
+    const [first, ...rest] = mount.parent;
+    const root = roots.find((r) => r.name === first);
+    if (!root) {
+        issue('command_parent_invalid', `parent path starts with unknown branch`, first, 'a branch this manifest contributes', 'Fix the parent path or add the parent branch.', mount.parent.join('.'));
+        return false;
+    }
+    if (root.kind === 'leaf') {
+        issue('command_parent_invalid', 'parent path resolves to a leaf', first, 'a branch', 'Change the parent to point to a branch.', mount.parent.join('.'));
+        return false;
+    }
+    let current = root;
+    for (const token of rest) {
+        const child = current.children.find((c) => c.name === token);
+        if (!child) {
+            issue('command_parent_invalid', `parent path contains unknown branch`, token, 'a branch this manifest contributes', 'Fix the parent path or add the intermediate branch.', mount.parent.join('.'));
+            return false;
+        }
+        if (child.kind === 'leaf') {
+            issue('command_parent_invalid', `parent path resolves to a leaf`, token, 'a branch', 'Change the parent to point to a branch.', mount.parent.join('.'));
+            return false;
+        }
+        current = child;
+    }
+    // A passthrough owns every token below its path, so nested mounts would make
+    // the materialized branch invalid even though its inline children are empty.
+    if (current.passthrough !== undefined) {
+        issue('command_parent_invalid', 'parent path resolves to a passthrough branch', mount.parent.join('.'), 'a branch without passthrough', 'Remove the nested mount or remove passthrough from its parent branch.', mount.parent.join('.'));
+        return false;
+    }
+    // Attach the node
+    if (current.children.some((c) => c.name === mount.node.name)) {
+        issue('command_node_invalid', `duplicate child name`, mount.node.name, 'unique child names within a branch', 'Rename the node or remove the duplicate.', `${mount.parent.join('.')}.${mount.node.name}`);
+        return false;
+    }
+    current.children.push(mount.node);
+    return true;
+}

package/dist/api/command-manifest/result.d.ts

@@ -0,0 +1,25 @@
+export interface DeclaredOutputShape {
+    type: string;
+    constraint: string;
+    /** Named members of an `object` value. */
+    children?: DeclaredOutputField[];
+    /** Element shape of an `array` value. */
+    items?: DeclaredOutputShape;
+    /** Allowed values of an `enum` value. */
+    values?: string[];
+}
+export interface DeclaredOutputField extends DeclaredOutputShape {
+    name: string;
+    required: boolean;
+}
+/** Validates a result object against declared output field descriptors.
+ *  Returns null if valid; otherwise returns a { field, receivedType } error. */
+export declare function validateDeclaredResult(output: DeclaredOutputField[], result: Record<string, unknown>): {
+    field: string;
+    receivedType?: string;
+} | null;
+/** Core leaf declarations may explicitly require a nullable field. */
+export declare function validateCoreDeclaredResult(output: DeclaredOutputField[], result: Record<string, unknown>): {
+    field: string;
+    receivedType?: string;
+} | null;

package/dist/api/command-manifest/result.js

@@ -0,0 +1,97 @@
+import { isRecord } from '../../shared/predicates.js';
+/** Validates a result object against declared output field descriptors.
+ *  Returns null if valid; otherwise returns a { field, receivedType } error. */
+export function validateDeclaredResult(output, result) {
+    return validateFields(output, result, true);
+}
+/** Core leaf declarations may explicitly require a nullable field. */
+export function validateCoreDeclaredResult(output, result) {
+    return validateFields(output, result, true);
+}
+function validateFields(output, result, honorDeclaredNull) {
+    for (const f of output) {
+        const value = result[f.name];
+        const present = Object.prototype.hasOwnProperty.call(result, f.name)
+            && value !== undefined
+            && (honorDeclaredNull || value !== null);
+        if (f.required && !present)
+            return { field: f.name };
+        const matches = honorDeclaredNull ? coreTypeMatches(f, value) : typeMatches(f.type, value);
+        if (present && !matches) {
+            return { field: f.name, receivedType: value === null ? 'null' : typeof value };
+        }
+    }
+    return null;
+}
+/** 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 isRecord(v);
+    return true;
+}
+function coreTypeMatches(shape, v) {
+    const alternatives = shape.type.split('|').map((part) => part.trim()).filter(Boolean);
+    if (alternatives.length === 1 && !knownType(alternatives[0]))
+        return true;
+    const allKnown = alternatives.every((part) => knownType(part) || /^[a-z][a-z0-9_-]*$/.test(part));
+    if (!allKnown)
+        return true;
+    return alternatives.some((part) => atomMatches(part, v, shape));
+}
+function knownType(type) {
+    const t = type.toLowerCase();
+    return t === 'null'
+        || t === 'string'
+        || t === 'path'
+        || t === 'markdown'
+        || t === 'int'
+        || t === 'integer'
+        || t === 'number'
+        || t === 'float'
+        || t === 'bool'
+        || t === 'boolean'
+        || t === 'array'
+        || t.endsWith('[]')
+        || t === 'object'
+        || t === 'enum'
+        || t === 'file';
+}
+function atomMatches(type, v, shape) {
+    const t = type.toLowerCase();
+    if (t === 'null')
+        return v === null;
+    // An enum with declared `values` holds one of them; one without stays
+    // presence-only, as before `values` existed.
+    if (t === 'enum')
+        return shape.values === undefined || (typeof v === 'string' && shape.values.includes(v));
+    // A file output is the provider's file object on the wire, or the runtime path
+    // the daemon put in its place.
+    if (t === 'file')
+        return isRecord(v) || typeof v === 'string';
+    if (t === 'string' || t === 'path' || t === 'markdown')
+        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 isRecord(v);
+    return typeof v === 'string' && v === type;
+}

package/dist/api/command-manifest/schema.d.ts

@@ -0,0 +1,28 @@
+import type { ManifestRootEntry as DeclRootEntry, ManifestPassthrough as DeclPassthrough, ManifestLeafBase as DeclLeafBase, ManifestExecLeaf as ExecDeclLeaf, ManifestHttpLeaf as HttpDeclLeaf, ManifestLeaf as DeclLeaf, ManifestBranch as DeclBranch, ManifestNode as DeclNode, RestMethod, RestParamPlacement, RestParamMapping, RestMapping, ManifestTimeouts } from '../plugin-manifest-schema.js';
+export type { DeclRootEntry, DeclPassthrough, DeclLeafBase, ExecDeclLeaf, HttpDeclLeaf, DeclLeaf, DeclBranch, DeclNode, RestMethod, RestParamPlacement, RestParamMapping, RestMapping, ManifestTimeouts, };
+export interface CommandManifestIssue {
+    code: CommandIssueCode;
+    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' | 'command_help_addendum_invalid' | 'command_rest_invalid' | 'command_extension_invalid';
+type IssueFn = (code: CommandIssueCode, message: string, received: string, expected: string, next: string, path?: string) => void;
+/** Base type of a declared output type: the union with every `null` part
+ *  dropped, lower-cased. It decides which structural keys the shape may carry. */
+export declare function outputBaseType(type: string): string;
+/** Whether a declared output type names `file` anywhere: as a union part or
+ *  as the element of an array type. */
+export declare function mentionsFile(type: string): boolean;
+export type TransportKind = 'exec' | 'http';
+export interface CommandNodeValidationOptions {
+    /** Plugin roots need rootEntry; repository-fragment roots attach under an existing branch and forbid it. */
+    topLevelRootEntry?: 'required' | 'forbidden';
+    /** Repository fragments have no passthrough escape hatch. */
+    allowPassthrough?: boolean;
+    /** Only plugin manifests may mark their own top-level branch extensible. */
+    allowExtensible?: boolean;
+}
+export declare function validateCommandNode(raw: unknown, path: string[], topLevel: boolean, transport: TransportKind, issue: IssueFn, options?: CommandNodeValidationOptions): DeclBranch<DeclLeaf> | DeclLeaf | null;