@crouter/api 0.3.377

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

@@ -0,0 +1,856 @@
+// Unified command-manifest schema. Transport is the sole leaf-dialect discriminator.
+//
+// The SHAPE of a manifest is declared once, in `src/api/plugin-manifest-schema.ts`,
+// and published as `@crouter/api/plugin-manifest` so a server that
+// serves a plugin bundle compiles against the same types validated here. This
+// module owns the validators and re-exports those types under their in-tree names.
+import { isRecord } from '../../shared/predicates.js';
+// Validation helpers
+const TIERS = new Set(['normal', 'common', 'important']);
+const FLAG_TYPES = new Set(['string', 'int', 'bool', 'path', 'enum', 'file']);
+/** A capability-provider tool group id (contract 1 `<id>` grammar), so
+ *  `<provider>:<group>` splits on its first `:`. */
+const GROUP_ID = /^[A-Za-z0-9_-]{1,64}$/;
+const KEBAB = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+const BRANCH_KEYS = new Set([
+    'kind', 'name', 'description', 'whenToUse', 'tier', 'rootEntry', 'extensible', 'summary', 'model', 'children',
+]);
+/** Only exec transport may declare `passthrough`; HTTP manifests keep
+ *  BRANCH_KEYS, so a declared passthrough fails as an unknown key. */
+const EXEC_BRANCH_KEYS = new Set([...BRANCH_KEYS, 'passthrough']);
+const PASSTHROUGH_KEYS = new Set(['bin', 'installHint']);
+const LEAF_KEYS_COMMON = new Set([
+    'kind', 'name', 'description', 'whenToUse', 'tier', 'summary', 'params', 'output', 'effects',
+]);
+const EXEC_LEAF_KEYS = new Set([...LEAF_KEYS_COMMON, 'outputKind']);
+const HTTP_LEAF_KEYS = new Set([...LEAF_KEYS_COMMON, 'rest', 'group']);
+const ROOT_ENTRY_KEYS = new Set(['concept', 'description', 'whenToUse']);
+const FILE_ENCODINGS = new Set(['text', 'base64']);
+const PARAM_KEYS_BY_KIND = {
+    positional: new Set(['kind', 'name', 'type', 'required', 'constraint', 'repeatable', 'encoding', 'defaultFromEnv']),
+    flag: new Set([
+        'kind',
+        'name',
+        'type',
+        'choices',
+        'required',
+        'constraint',
+        'default',
+        'repeatable',
+        'encoding',
+        'defaultFromEnv',
+    ]),
+    stdin: new Set(['kind', 'name', 'required', 'constraint']),
+    'context-file': new Set(['kind', 'name', 'required', 'constraint', 'shape']),
+};
+const OUTPUT_KEYS = new Set(['name', 'type', 'required', 'constraint', 'children', 'items', 'values']);
+/** An `items` element shape: an output field without a name or required. */
+const OUTPUT_SHAPE_KEYS = new Set(['type', 'constraint', 'children', 'items', 'values']);
+/** UPPER_SNAKE_CASE environment variable name — the only form an ambient default
+ *  may name, so a typo'd lowercase key fails at authoring time rather than
+ *  silently never resolving. */
+const ENV_VAR_NAME = /^[A-Z][A-Z0-9_]*$/;
+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;
+}
+function validateRootEntry(raw, path, issue) {
+    if (!isRecord(raw)) {
+        issue('command_node_invalid', `rootEntry must be an object`, typeName(raw), 'a { concept, description, whenToUse } object', 'Fix rootEntry.', path);
+        return null;
+    }
+    if (!checkKeys(raw, ROOT_ENTRY_KEYS, path, issue))
+        return null;
+    for (const k of ['concept', 'description', 'whenToUse']) {
+        if (typeof raw[k] !== 'string' || raw[k].length === 0) {
+            issue('command_node_invalid', `rootEntry.${k} must be a non-empty string`, typeName(raw[k]), 'a non-empty string', `Add rootEntry.${k}.`, `${path}.${k}`);
+            return null;
+        }
+    }
+    return {
+        concept: raw['concept'],
+        description: raw['description'],
+        whenToUse: raw['whenToUse'],
+    };
+}
+function validateParams(raw, path, issue) {
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw)) {
+        issue('command_node_invalid', `params must be an array`, typeName(raw), 'an array of params (or omitted)', 'Fix params.', path);
+        return null;
+    }
+    const out = [];
+    const names = new Set();
+    let positionals = 0;
+    for (let i = 0; i < raw.length; i++) {
+        const p = raw[i];
+        const pp = `${path}[${i}]`;
+        if (!isRecord(p)) {
+            issue('command_node_invalid', `param must be an object`, typeName(p), 'a param object', 'Fix the param.', pp);
+            return null;
+        }
+        const kind = p['kind'];
+        if (typeof kind !== 'string' || !(kind in PARAM_KEYS_BY_KIND)) {
+            issue('command_node_invalid', `param kind must be positional|flag|stdin|context-file`, String(kind), 'positional | flag | stdin | context-file', 'Fix the param kind.', `${pp}.kind`);
+            return null;
+        }
+        if (!checkKeys(p, PARAM_KEYS_BY_KIND[kind], pp, issue))
+            return null;
+        const name = p['name'];
+        if (typeof name !== 'string' || !KEBAB.test(name)) {
+            issue('command_node_invalid', `param name must be a kebab-case token`, String(name), 'a kebab-case token', 'Rename the param.', `${pp}.name`);
+            return null;
+        }
+        if (names.has(name)) {
+            issue('command_node_invalid', `duplicate param name`, name, 'unique param names', 'Rename the duplicate param.', `${pp}.name`);
+            return null;
+        }
+        names.add(name);
+        if (typeof p['required'] !== 'boolean') {
+            issue('command_node_invalid', `param required must be a boolean`, typeName(p['required']), 'true | false', 'Set required.', `${pp}.required`);
+            return null;
+        }
+        if (typeof p['constraint'] !== 'string') {
+            issue('command_node_invalid', `param constraint must be a string`, typeName(p['constraint']), 'an inline constraint string', 'Add a constraint.', `${pp}.constraint`);
+            return null;
+        }
+        if (kind === 'positional') {
+            positionals++;
+            if (positionals > 1) {
+                issue('command_node_invalid', `a leaf may declare at most one positional`, 'multiple positionals', 'at most one positional param', 'Convert extra positionals to flags.', pp);
+                return null;
+            }
+            if (p['type'] !== undefined && p['type'] !== 'string' && p['type'] !== 'path' && p['type'] !== 'file') {
+                issue('command_node_invalid', `positional type must be string|path|file`, String(p['type']), 'string | path | file | omitted', 'Fix the positional type.', `${pp}.type`);
+                return null;
+            }
+            let repeatable = false;
+            if (p['repeatable'] !== undefined) {
+                if (typeof p['repeatable'] !== 'boolean') {
+                    issue('command_node_invalid', `repeatable must be a boolean`, typeName(p['repeatable']), 'true | false | omitted', 'Fix repeatable.', `${pp}.repeatable`);
+                    return null;
+                }
+                repeatable = p['repeatable'];
+            }
+            if (repeatable && p['type'] === 'file') {
+                issue('command_node_invalid', `repeatable is not valid on a file positional`, `${name}: file`, 'one file per file param', 'Remove repeatable, or declare one file param per file.', `${pp}.repeatable`);
+                return null;
+            }
+            const encoding = validateFileEncoding(p, pp, issue);
+            if (encoding === null)
+                return null;
+            const envDefault = validateDefaultFromEnv(p, pp, issue);
+            if (envDefault === null)
+                return null;
+            if (repeatable && envDefault !== undefined) {
+                issue('command_node_invalid', `repeatable positional must not declare defaultFromEnv`, name, 'no defaultFromEnv on a repeatable positional (values accumulate into an array)', 'Remove defaultFromEnv, or drop repeatable.', `${pp}.defaultFromEnv`);
+                return null;
+            }
+            out.push({
+                kind: 'positional',
+                name,
+                ...(p['type'] !== undefined ? { type: p['type'] } : {}),
+                required: p['required'],
+                constraint: p['constraint'],
+                ...(repeatable ? { repeatable: true } : {}),
+                ...(encoding !== undefined ? { encoding } : {}),
+                ...(envDefault !== undefined ? { defaultFromEnv: envDefault } : {}),
+            });
+        }
+        else if (kind === 'stdin') {
+            out.push({ kind: 'stdin', name, required: p['required'], constraint: p['constraint'] });
+        }
+        else if (kind === 'context-file') {
+            out.push({
+                kind: 'context-file',
+                name,
+                required: p['required'],
+                constraint: p['constraint'],
+                ...(typeof p['shape'] === 'string' ? { shape: p['shape'] } : {}),
+            });
+        }
+        else if (kind === 'flag') {
+            const type = p['type'];
+            if (typeof type !== 'string' || !FLAG_TYPES.has(type)) {
+                issue('command_node_invalid', `flag type must be string|int|bool|path|enum|file`, String(type), 'string | int | bool | path | enum | file', 'Fix the flag type.', `${pp}.type`);
+                return null;
+            }
+            let choices;
+            if (type === 'enum') {
+                const c = p['choices'];
+                if (!Array.isArray(c) || c.length === 0 || !c.every((x) => typeof x === 'string')) {
+                    issue('command_node_invalid', `enum flag requires a non-empty string choices array`, typeName(c), 'a non-empty array of strings', 'Declare choices for the enum flag.', `${pp}.choices`);
+                    return null;
+                }
+                choices = c;
+            }
+            else if (p['choices'] !== undefined) {
+                issue('command_node_invalid', `choices is only valid on an enum flag`, 'choices', 'no choices unless type is enum', 'Remove choices.', `${pp}.choices`);
+                return null;
+            }
+            let repeatable = false;
+            if (p['repeatable'] !== undefined) {
+                if (typeof p['repeatable'] !== 'boolean') {
+                    issue('command_node_invalid', `repeatable must be a boolean`, typeName(p['repeatable']), 'true | false | omitted', 'Fix repeatable.', `${pp}.repeatable`);
+                    return null;
+                }
+                repeatable = p['repeatable'];
+            }
+            if (repeatable && (type === 'bool' || type === 'path' || type === 'file')) {
+                issue('command_node_invalid', `repeatable is not valid on a ${type} flag`, `${name}: ${type}`, 'repeatable only on string | int | enum flags', 'Remove repeatable or change the flag type.', `${pp}.repeatable`);
+                return null;
+            }
+            if (repeatable && p['default'] !== undefined) {
+                issue('command_node_invalid', `repeatable flag must not declare a default`, name, 'no default on a repeatable flag (values accumulate into an array)', 'Remove the default.', `${pp}.default`);
+                return null;
+            }
+            const encoding = validateFileEncoding(p, pp, issue);
+            if (encoding === null)
+                return null;
+            const envDefault = validateDefaultFromEnv(p, pp, issue);
+            if (envDefault === null)
+                return null;
+            if (repeatable && envDefault !== undefined) {
+                issue('command_node_invalid', `repeatable flag must not declare defaultFromEnv`, name, 'no defaultFromEnv on a repeatable flag (values accumulate into an array)', 'Remove defaultFromEnv, or drop repeatable.', `${pp}.defaultFromEnv`);
+                return null;
+            }
+            out.push({
+                kind: 'flag',
+                name,
+                type: type,
+                ...(choices !== undefined ? { choices } : {}),
+                ...(encoding !== undefined ? { encoding } : {}),
+                required: p['required'],
+                constraint: p['constraint'],
+                ...(p['default'] !== undefined ? { default: p['default'] } : {}),
+                ...(repeatable ? { repeatable: true } : {}),
+                ...(envDefault !== undefined ? { defaultFromEnv: envDefault } : {}),
+            });
+        }
+    }
+    return out;
+}
+/** `encoding` declares the local-file materialization contract: the CLI-side
+ *  value is a path, and the invoker sends the FILE's content under the mapped
+ *  body key. It is meaningful only on a `path` param — anywhere else there is no
+ *  file to read, so declaring it is an authoring error, not a silent no-op.
+ *  Returns the encoding, undefined when absent, or null when invalid. */
+function validateFileEncoding(p, pp, issue) {
+    const encoding = p['encoding'];
+    if (encoding === undefined)
+        return undefined;
+    if (typeof encoding !== 'string' || !FILE_ENCODINGS.has(encoding)) {
+        issue('command_node_invalid', `param encoding must be text|base64`, String(encoding), 'text | base64 | omitted', 'Fix the encoding.', `${pp}.encoding`);
+        return null;
+    }
+    if (p['type'] !== 'path') {
+        issue('command_node_invalid', `encoding is only valid on a type:"path" param`, `type ${String(p['type'])}`, 'type: "path"', 'Set the param type to "path", or remove encoding.', `${pp}.encoding`);
+        return null;
+    }
+    return encoding;
+}
+/** `defaultFromEnv` names an environment variable on the CALLING machine whose
+ *  value fills the param when the caller omits it — and counts as supplied, so it
+ *  satisfies `required` and ships like a typed value. It carries a textual value,
+ *  so it is meaningful only on a string|path param, and it cannot coexist with a
+ *  static `default` (two competing sources for one slot is an authoring error,
+ *  not a precedence puzzle for the reader). The caller checks `repeatable`
+ *  separately, where that param is in scope: a repeatable param accumulates an
+ *  ARRAY, and one env string cannot honestly fill it. Returns the env var name,
+ *  undefined when absent, or null when invalid. */
+function validateDefaultFromEnv(p, pp, issue) {
+    const envVar = p['defaultFromEnv'];
+    if (envVar === undefined)
+        return undefined;
+    if (typeof envVar !== 'string' || !ENV_VAR_NAME.test(envVar)) {
+        issue('command_node_invalid', `defaultFromEnv must name an environment variable in UPPER_SNAKE_CASE`, String(envVar), 'e.g. "CRTR_NODE_ID"', 'Fix the environment variable name.', `${pp}.defaultFromEnv`);
+        return null;
+    }
+    // A positional with no declared type is a string.
+    const type = p['type'] === undefined && p['kind'] === 'positional' ? 'string' : p['type'];
+    if (type !== 'string' && type !== 'path') {
+        issue('command_node_invalid', `defaultFromEnv is only valid on a string|path param`, `type ${String(p['type'])}`, 'type: "string" | "path"', 'Change the param type, or remove defaultFromEnv.', `${pp}.defaultFromEnv`);
+        return null;
+    }
+    if (p['default'] !== undefined) {
+        issue('command_node_invalid', `a param must not declare both default and defaultFromEnv`, `${String(p['name'])}: default + defaultFromEnv`, 'exactly one default source', 'Remove one — defaultFromEnv counts as supplied, a static default does not.', `${pp}.defaultFromEnv`);
+        return null;
+    }
+    return envVar;
+}
+/** 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 function outputBaseType(type) {
+    return type
+        .split('|')
+        .map((part) => part.trim().toLowerCase())
+        .filter((part) => part.length > 0 && part !== 'null')
+        .join(' | ');
+}
+/** Whether a declared output type names `file` anywhere: as a union part or
+ *  as the element of an array type. */
+export function mentionsFile(type) {
+    return type.split('|').some((part) => /^file(\[\])*$/i.test(part.trim()));
+}
+/** Validate the type/constraint/children/items/values of one output shape.
+ *  `topLevel` is true only for a leaf's own output fields: a `file` field may
+ *  appear nowhere else. Returns the shape, or null after raising an issue. */
+function validateOutputShape(f, fp, topLevel, issue) {
+    if (typeof f['type'] !== 'string' || f['type'].length === 0) {
+        issue('command_node_invalid', `output field type must be a non-empty string`, typeName(f['type']), 'a type name', 'Add a type.', `${fp}.type`);
+        return null;
+    }
+    if (typeof f['constraint'] !== 'string') {
+        issue('command_node_invalid', `output field constraint must be a string`, typeName(f['constraint']), 'a constraint string', 'Add a constraint.', `${fp}.constraint`);
+        return null;
+    }
+    const type = f['type'];
+    const base = outputBaseType(type);
+    if (mentionsFile(type) && base !== 'file') {
+        issue('command_node_invalid', `a file output is one file, optionally nullable`, type, 'type "file" or "file | null"', 'Return one file per leaf; declare it as "file" or "file | null".', `${fp}.type`);
+        return null;
+    }
+    if (base === 'file' && !topLevel) {
+        issue('command_node_invalid', `a file output must be a top-level output field`, type, 'type "file" only on a leaf\'s own output fields, never inside children or items', 'Move the file field to the top level of the leaf output.', `${fp}.type`);
+        return null;
+    }
+    const structural = [
+        ['children', 'object'],
+        ['items', 'array'],
+        ['values', 'enum'],
+    ];
+    for (const [key, allowedOn] of structural) {
+        if (f[key] !== undefined && base !== allowedOn) {
+            issue('command_node_invalid', `output ${key} is only valid on an ${allowedOn} field`, `type ${type}`, `type "${allowedOn}" (optionally "${allowedOn} | null")`, `Remove ${key}, or change the type to ${allowedOn}.`, `${fp}.${key}`);
+            return null;
+        }
+    }
+    let children;
+    if (f['children'] !== undefined) {
+        const c = validateOutputFields(f['children'], `${fp}.children`, false, issue);
+        if (c === null)
+            return null;
+        children = c;
+    }
+    let items;
+    if (f['items'] !== undefined) {
+        const raw = f['items'];
+        const ip = `${fp}.items`;
+        if (!isRecord(raw)) {
+            issue('command_node_invalid', `output items must be an object`, typeName(raw), 'a { type, constraint, children?, items?, values? } object', 'Fix the items shape.', ip);
+            return null;
+        }
+        if (!checkKeys(raw, OUTPUT_SHAPE_KEYS, ip, issue))
+            return null;
+        const shape = validateOutputShape(raw, ip, false, issue);
+        if (shape === null)
+            return null;
+        items = shape;
+    }
+    let values;
+    if (f['values'] !== undefined) {
+        const v = f['values'];
+        if (!Array.isArray(v) || v.length === 0 || !v.every((x) => typeof x === 'string' && x.length > 0)) {
+            issue('command_node_invalid', `enum output values must be a non-empty array of strings`, typeName(v), 'a non-empty array of non-empty strings', 'Declare the values the field may take.', `${fp}.values`);
+            return null;
+        }
+        if (new Set(v).size !== v.length) {
+            issue('command_node_invalid', `enum output values must be unique`, v.join(', '), 'distinct values', 'Remove the duplicate value.', `${fp}.values`);
+            return null;
+        }
+        values = v;
+    }
+    return {
+        type,
+        constraint: f['constraint'],
+        ...(children !== undefined ? { children } : {}),
+        ...(items !== undefined ? { items } : {}),
+        ...(values !== undefined ? { values } : {}),
+    };
+}
+function validateOutput(raw, path, issue) {
+    return validateOutputFields(raw, path, true, issue);
+}
+function validateOutputFields(raw, path, topLevel, issue) {
+    if (!Array.isArray(raw)) {
+        issue('command_node_invalid', topLevel ? `output must be an array` : `output children must be an array`, typeName(raw), 'an array of output fields', topLevel ? 'Declare the leaf output fields.' : 'Declare the object\'s member fields.', path);
+        return null;
+    }
+    const out = [];
+    const names = new Set();
+    let fileField;
+    for (let i = 0; i < raw.length; i++) {
+        const f = raw[i];
+        const fp = `${path}[${i}]`;
+        if (!isRecord(f)) {
+            issue('command_node_invalid', `output field must be an object`, typeName(f), 'a { name, type, required, constraint } object', 'Fix the output field.', fp);
+            return null;
+        }
+        if (!checkKeys(f, OUTPUT_KEYS, fp, issue))
+            return null;
+        if (typeof f['name'] !== 'string' || f['name'].length === 0) {
+            issue('command_node_invalid', `output field name must be a non-empty string`, typeName(f['name']), 'a field name', 'Add a name.', `${fp}.name`);
+            return null;
+        }
+        if (!topLevel && names.has(f['name'])) {
+            issue('command_node_invalid', `duplicate output child name`, f['name'], 'unique member names within one object', 'Rename the duplicate member.', `${fp}.name`);
+            return null;
+        }
+        names.add(f['name']);
+        if (typeof f['required'] !== 'boolean') {
+            issue('command_node_invalid', `output field required must be a boolean`, typeName(f['required']), 'true | false', 'Set required.', `${fp}.required`);
+            return null;
+        }
+        const shape = validateOutputShape(f, fp, topLevel, issue);
+        if (shape === null)
+            return null;
+        if (outputBaseType(shape.type) === 'file') {
+            if (fileField !== undefined) {
+                issue('command_node_invalid', `a leaf declares at most one file output`, `${fileField}, ${f['name']}`, 'one top-level output field of type "file"', 'Return the extra files through a separate leaf, or drop the extra file field.', `${fp}.type`);
+                return null;
+            }
+            fileField = f['name'];
+        }
+        out.push({ name: f['name'], ...shape, required: f['required'] });
+    }
+    return out;
+}
+function checkCommon(raw, path, issue) {
+    const name = raw['name'];
+    if (typeof name !== 'string' || !KEBAB.test(name)) {
+        issue('command_node_invalid', `node name must be a lowercase kebab-case token`, String(name), 'a kebab-case token like "app" or "list-all"', 'Rename the node.', `${path}.name`);
+        return false;
+    }
+    if (typeof raw['description'] !== 'string' || raw['description'].length === 0) {
+        issue('command_node_invalid', `node description must be a non-empty string`, typeName(raw['description']), 'a short parent-listing description', 'Add a description.', `${path}.description`);
+        return false;
+    }
+    if (typeof raw['whenToUse'] !== 'string' || raw['whenToUse'].length === 0) {
+        issue('command_node_invalid', `node whenToUse must be a non-empty string`, typeName(raw['whenToUse']), 'a parent selection rubric', 'Add a whenToUse rubric.', `${path}.whenToUse`);
+        return false;
+    }
+    if (raw['tier'] !== undefined && !TIERS.has(String(raw['tier']))) {
+        issue('command_node_invalid', `node tier must be normal|common|important`, String(raw['tier']), 'normal | common | important', 'Fix or omit tier (external plugins cannot declare hidden commands).', `${path}.tier`);
+        return false;
+    }
+    return true;
+}
+export function validateCommandNode(raw, path, topLevel, transport, issue, options = {}) {
+    const pathString = path.join('.');
+    if (!isRecord(raw)) {
+        issue('command_node_invalid', 'node must be an object', typeName(raw), 'a branch or leaf node object', 'Fix the node.', pathString);
+        return null;
+    }
+    const kind = raw['kind'];
+    if (kind === 'branch')
+        return validateBranch(raw, pathString, topLevel, transport, issue, options);
+    if (kind === 'leaf') {
+        if (topLevel && options.topLevelRootEntry !== 'forbidden') {
+            issue('command_node_invalid', 'top-level node must be a branch', 'leaf', 'a branch node with a rootEntry', 'Wrap the command in a top-level branch (noun) with a rootEntry.', `${pathString}.kind`);
+            return null;
+        }
+        return validateLeaf(raw, pathString, transport, issue);
+    }
+    issue('command_node_invalid', 'node kind must be "branch" or "leaf"', String(kind), 'branch | leaf', 'Set kind to branch or leaf.', `${pathString}.kind`);
+    return null;
+}
+function validateBranch(raw, path, topLevel, transport, issue, options) {
+    const allowsPassthrough = options.allowPassthrough !== false;
+    const allowedKeys = transport === 'exec' && allowsPassthrough ? EXEC_BRANCH_KEYS : BRANCH_KEYS;
+    if (!checkKeys(raw, allowedKeys, path, issue))
+        return null;
+    if (!checkCommon(raw, path, issue))
+        return null;
+    const hasRoot = raw['rootEntry'] !== undefined;
+    const rootEntryPolicy = options.topLevelRootEntry ?? 'required';
+    if (topLevel && rootEntryPolicy === 'required' && !hasRoot) {
+        issue('command_node_invalid', 'top-level branch requires a rootEntry', '(missing)', 'a rootEntry { concept, description, whenToUse }', 'Add a rootEntry to the top-level branch.', `${path}.rootEntry`);
+        return null;
+    }
+    if ((!topLevel || rootEntryPolicy === 'forbidden') && hasRoot) {
+        issue('command_node_invalid', topLevel ? 'repository fragment root must not declare a rootEntry' : 'nested branch must not declare a rootEntry', 'rootEntry', topLevel ? 'no rootEntry (the owning plugin branch already has one)' : 'no rootEntry (only top-level branches carry one)', topLevel ? 'Remove rootEntry from the repository fragment root.' : 'Remove rootEntry from the nested branch.', `${path}.rootEntry`);
+        return null;
+    }
+    const hasExtensible = raw['extensible'] !== undefined;
+    if (hasExtensible && (!topLevel || options.allowExtensible === false || raw['extensible'] !== true)) {
+        issue('command_node_invalid', !topLevel ? 'extensible is valid only on a top-level branch mount' : 'extensible must be exactly true on a plugin top-level branch', String(raw['extensible']), !topLevel ? 'no extensible marker on nested branches' : 'extensible: true', !topLevel ? 'Move the marker to the plugin top-level branch or remove it.' : 'Set extensible to true or remove it.', `${path}.extensible`);
+        return null;
+    }
+    let rootEntry;
+    if (hasRoot) {
+        const validatedRootEntry = validateRootEntry(raw['rootEntry'], `${path}.rootEntry`, issue);
+        if (validatedRootEntry === null)
+            return null;
+        rootEntry = validatedRootEntry;
+    }
+    if (typeof raw['summary'] !== 'string' || raw['summary'].length === 0) {
+        issue('command_node_invalid', 'branch summary must be a non-empty string', typeName(raw['summary']), 'a one-line summary string', 'Add a summary.', `${path}.summary`);
+        return null;
+    }
+    if (raw['model'] !== undefined && typeof raw['model'] !== 'string') {
+        issue('command_node_invalid', 'branch model must be a string', typeName(raw['model']), 'a string or omitted', 'Fix or remove model.', `${path}.model`);
+        return null;
+    }
+    let passthrough;
+    if (transport === 'exec' && raw['passthrough'] !== undefined) {
+        const validated = validatePassthrough(raw['passthrough'], `${path}.passthrough`, issue);
+        if (validated === null)
+            return null;
+        passthrough = validated;
+    }
+    if (hasExtensible && passthrough !== undefined) {
+        issue('command_node_invalid', 'an extensible branch cannot declare passthrough', 'extensible and passthrough', 'one branch mode: extensible or passthrough', 'Remove passthrough or remove extensible.', path);
+        return null;
+    }
+    const children = raw['children'];
+    if (passthrough !== undefined) {
+        if (!Array.isArray(children) || children.length !== 0) {
+            issue('command_node_invalid', 'a passthrough branch must declare children: []', Array.isArray(children) ? `${children.length} children` : typeName(children), 'an empty children array', 'Set children to [] — a passthrough branch forwards all argv and can own no subcommands.', `${path}.children`);
+            return null;
+        }
+    }
+    else if (!Array.isArray(children)) {
+        issue('command_node_invalid', 'branch children must be an array', typeName(children), 'an array of branch/leaf nodes (may be empty for populated by mounts)', 'Fix children.', `${path}.children`);
+        return null;
+    }
+    const validated = [];
+    const childNames = new Set();
+    for (let i = 0; i < children.length; i++) {
+        const child = validateCommandNode(children[i], [...path.split('.'), `children[${i}]`], false, transport, issue, options);
+        if (child === null)
+            return null;
+        if (childNames.has(child.name)) {
+            issue('command_node_invalid', 'duplicate child name', child.name, 'unique child names within a branch', 'Rename the duplicate child.', `${path}.children[${i}].name`);
+            return null;
+        }
+        childNames.add(child.name);
+        validated.push(child);
+    }
+    return {
+        kind: 'branch', name: raw['name'], description: raw['description'], whenToUse: raw['whenToUse'],
+        ...(raw['tier'] !== undefined ? { tier: raw['tier'] } : {}),
+        ...(rootEntry !== undefined ? { rootEntry } : {}),
+        ...(hasExtensible ? { extensible: true } : {}), summary: raw['summary'],
+        ...(raw['model'] !== undefined ? { model: raw['model'] } : {}),
+        ...(passthrough !== undefined ? { passthrough } : {}), children: validated,
+    };
+}
+/** `passthrough: { bin, installHint }` — `bin` is a bare PATH command or a
+ *  plugin-root-relative executable path; both fields are required non-empty strings. */
+function validatePassthrough(raw, path, issue) {
+    if (!isRecord(raw)) {
+        issue('command_node_invalid', 'passthrough must be an object', typeName(raw), 'an object { bin, installHint }', 'Fix or remove passthrough.', path);
+        return null;
+    }
+    if (!checkKeys(raw, PASSTHROUGH_KEYS, path, issue))
+        return null;
+    for (const key of ['bin', 'installHint']) {
+        if (typeof raw[key] !== 'string' || raw[key].length === 0) {
+            issue('command_node_invalid', `passthrough ${key} must be a non-empty string`, typeName(raw[key]), key === 'bin' ? 'the external binary name' : 'a one-line install hint', `Set passthrough.${key}.`, `${path}.${key}`);
+            return null;
+        }
+    }
+    return { bin: raw['bin'], installHint: raw['installHint'] };
+}
+function validateLeaf(raw, path, transport, issue) {
+    if (!checkKeys(raw, transport === 'exec' ? EXEC_LEAF_KEYS : HTTP_LEAF_KEYS, path, issue))
+        return null;
+    if (!checkCommon(raw, path, issue))
+        return null;
+    if (typeof raw['summary'] !== 'string' || raw['summary'].length === 0) {
+        issue('command_node_invalid', 'leaf summary must be a non-empty string', typeName(raw['summary']), 'a one-line summary string', 'Add a summary.', `${path}.summary`);
+        return null;
+    }
+    if (transport === 'exec' && raw['outputKind'] !== 'object') {
+        issue('command_node_invalid', 'leaf outputKind must be "object" in v1', String(raw['outputKind']), 'exactly "object"', 'Set outputKind to "object".', `${path}.outputKind`);
+        return null;
+    }
+    if (transport === 'http' && raw['rest'] === undefined) {
+        issue('command_node_invalid', 'HTTP leaf requires a rest mapping', '(missing)', 'a rest object with method, path, and params', 'Add a rest mapping.', `${path}.rest`);
+        return null;
+    }
+    const params = validateParams(raw['params'], `${path}.params`, issue);
+    if (params === null)
+        return null;
+    const output = validateOutput(raw['output'], `${path}.output`, issue);
+    if (output === null)
+        return null;
+    const effects = raw['effects'];
+    if (!Array.isArray(effects) || effects.length === 0 || !effects.every((effect) => typeof effect === 'string')) {
+        issue('command_node_invalid', 'leaf effects must be a non-empty string array', typeName(effects), 'a non-empty array of strings (["None. Read-only."] for read-only leaves)', 'Declare every persistent effect.', `${path}.effects`);
+        return null;
+    }
+    const base = { kind: 'leaf', name: raw['name'], description: raw['description'], whenToUse: raw['whenToUse'],
+        ...(raw['tier'] !== undefined ? { tier: raw['tier'] } : {}), summary: raw['summary'], params, output, effects: effects };
+    if (transport === 'exec')
+        return { ...base, outputKind: 'object' };
+    const group = raw['group'];
+    if (group !== undefined && (typeof group !== 'string' || !GROUP_ID.test(group))) {
+        issue('command_node_invalid', `leaf group must match [A-Za-z0-9_-]{1,64}`, typeof group === 'string' ? group : typeName(group), 'a group id of 1-64 letters, digits, "_" or "-" (no ":" or whitespace)', `Rename the group on leaf ${path}.`, `${path}.group`);
+        return null;
+    }
+    const rest = validateRestMapping(raw['rest'], path, params, issue);
+    return rest === null ? null : { ...base, rest, ...(group !== undefined ? { group: group } : {}) };
+}
+// REST mapping validation (§4.4)
+const REST_METHODS_SET = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']);
+// RFC 7230 `token` grammar — the legal charset for an HTTP header field name.
+const HTTP_TOKEN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+const REST_PARAM_PLACEMENT_SET = new Set(['path', 'query', 'body', 'header']);
+function validateRestMapping(raw, basePath, params, issue) {
+    const path = `${basePath}.rest`;
+    if (!isRecord(raw)) {
+        issue('command_rest_invalid', `rest must be an object`, typeName(raw), '{ method, path, streaming?, params }', 'Provide a valid rest mapping.', path);
+        return null;
+    }
+    // Check for unknown keys
+    const allowedKeys = new Set(['method', 'path', 'streaming', 'body', 'bodyRoot', 'params']);
+    const unknownKeys = Object.keys(raw).filter((k) => !allowedKeys.has(k));
+    if (unknownKeys.length > 0) {
+        issue('command_rest_invalid', `unknown rest keys`, unknownKeys.join(', '), 'only: method, path, streaming, body, bodyRoot, params', 'Remove the unknown keys.', path);
+        return null;
+    }
+    // Validate method (required)
+    const method = raw['method'];
+    if (typeof method !== 'string' || !REST_METHODS_SET.has(method)) {
+        issue('command_rest_invalid', `method must be GET|POST|PUT|PATCH|DELETE`, String(method), 'one of the HTTP methods', 'Set method to a valid HTTP verb.', `${path}.method`);
+        return null;
+    }
+    // Validate path (required, must start with /)
+    const restPath = raw['path'];
+    if (typeof restPath !== 'string' || !restPath.startsWith('/')) {
+        issue('command_rest_invalid', `path must be an absolute path starting with /`, String(restPath), 'an absolute path like "/v1/devices/{id}"', 'Fix the path.', `${path}.path`);
+        return null;
+    }
+    // Extract and validate placeholders in path
+    const placeholders = new Set();
+    const placeholderRegex = /\{([a-z][a-z0-9]*(?:-[a-z0-9]+)*)\}/g;
+    let match;
+    while ((match = placeholderRegex.exec(restPath)) !== null) {
+        placeholders.add(match[1]);
+    }
+    // Validate streaming (optional, default false)
+    let streaming = false;
+    if (raw['streaming'] !== undefined) {
+        if (typeof raw['streaming'] !== 'boolean') {
+            issue('command_rest_invalid', `streaming must be a boolean`, typeName(raw['streaming']), 'true | false | omitted', 'Fix streaming.', `${path}.streaming`);
+            return null;
+        }
+        streaming = raw['streaming'];
+    }
+    // Validate params mapping (required object)
+    const restParams = raw['params'];
+    if (!isRecord(restParams)) {
+        issue('command_rest_invalid', `params must be an object`, typeName(restParams), 'a mapping of param names to placement specs', 'Provide params.', `${path}.params`);
+        return null;
+    }
+    // Build param name to param object map
+    const paramsByName = new Map();
+    for (const p of params) {
+        paramsByName.set(p.name, p);
+    }
+    // Validate each REST param mapping
+    const restParamMappings = {};
+    const bodyParams = [];
+    const declaredNames = new Set();
+    for (const [paramName, mapping] of Object.entries(restParams)) {
+        if (!paramsByName.has(paramName)) {
+            issue('command_rest_invalid', `rest params key has no matching declared param`, paramName, 'a name from the leaf params array', 'Remove this rest params entry or declare the param.', `${path}.params.${paramName}`);
+            return null;
+        }
+        declaredNames.add(paramName);
+        if (!isRecord(mapping)) {
+            issue('command_rest_invalid', `param mapping must be an object`, typeName(mapping), '{ in, as? }', 'Fix the param mapping.', `${path}.params.${paramName}`);
+            return null;
+        }
+        const allowedMappingKeys = new Set(['in', 'as']);
+        const unknownMappingKeys = Object.keys(mapping).filter((k) => !allowedMappingKeys.has(k));
+        if (unknownMappingKeys.length > 0) {
+            issue('command_rest_invalid', `unknown param mapping keys`, unknownMappingKeys.join(', '), 'only: in, as', 'Remove the unknown keys.', `${path}.params.${paramName}`);
+            return null;
+        }
+        const inValue = mapping['in'];
+        if (typeof inValue !== 'string' || !REST_PARAM_PLACEMENT_SET.has(inValue)) {
+            issue('command_rest_invalid', `param placement must be path|query|body|header`, String(inValue), 'path | query | body | header', 'Set in to a valid placement.', `${path}.params.${paramName}.in`);
+            return null;
+        }
+        const asValue = mapping['as'];
+        if (asValue !== undefined && (typeof asValue !== 'string' || asValue.length === 0)) {
+            issue('command_rest_invalid', `as must be a non-empty string`, String(asValue), 'a non-empty string', 'Fix the as value.', `${path}.params.${paramName}.as`);
+            return null;
+        }
+        // Validate 'as' placement rules
+        if (inValue === 'header') {
+            if (typeof asValue !== 'string' || asValue.length === 0) {
+                issue('command_rest_invalid', `header placement requires a non-empty as`, String(asValue), 'a header name', 'Provide an as value for the header name.', `${path}.params.${paramName}.as`);
+                return null;
+            }
+            // The header name becomes a real HTTP field name at invoke time (Node's
+            // req.setHeader throws ERR_INVALID_HTTP_TOKEN for an illegal one) — reject
+            // it here so a malformed manifest fails a structured, static check instead.
+            if (!HTTP_TOKEN.test(asValue)) {
+                issue('command_rest_invalid', `header "as" must be a legal HTTP header field name`, asValue, 'an HTTP token (letters, digits, and !#$%&\'*+-.^_`|~)', 'Fix the header name.', `${path}.params.${paramName}.as`);
+                return null;
+            }
+            if (asValue.toLowerCase() === 'crtr-request-id') {
+                issue('command_rest_invalid', `Crtr-Request-Id is assigned by crtr for each leaf call`, asValue, 'a header name other than Crtr-Request-Id', 'Remove this header mapping.', `${path}.params.${paramName}.as`);
+                return null;
+            }
+        }
+        else if (inValue === 'path') {
+            if (asValue !== undefined) {
+                issue('command_rest_invalid', `path placement must not have as`, 'as', 'no as (placeholder name governs)', 'Remove as.', `${path}.params.${paramName}.as`);
+                return null;
+            }
+            // §4.4: a path placeholder must always be filled, so the underlying param
+            // must itself be required — otherwise an omitted call renders the literal
+            // string "undefined" into the URL.
+            const pathParam = paramsByName.get(paramName);
+            if (pathParam.required !== true) {
+                issue('command_rest_invalid', `in:"path" param must be declared required`, `${paramName}: required ${String(pathParam.required)}`, 'required: true', `Set "required": true on the "${paramName}" param.`, `${path}.params.${paramName}`);
+                return null;
+            }
+        }
+        // A repeatable param's parsed value is an array; only JSON body placement
+        // can carry it faithfully (query/header/path would String() it into "a,b").
+        const mappedParam = paramsByName.get(paramName);
+        if ((mappedParam.kind === 'flag' || mappedParam.kind === 'positional') && mappedParam.repeatable === true && inValue !== 'body') {
+            issue('command_rest_invalid', `repeatable param must use body placement`, `${paramName}: in "${inValue}"`, 'in: "body" (array values ship as a JSON array)', `Map "${paramName}" to body placement.`, `${path}.params.${paramName}.in`);
+            return null;
+        }
+        // Collect body params for coalesced source validation
+        if (inValue === 'body') {
+            const param = paramsByName.get(paramName);
+            const isStdin = param.kind === 'stdin';
+            const asName = asValue || paramName;
+            bodyParams.push({ name: paramName, isStdin, as: asName });
+        }
+        restParamMappings[paramName] = {
+            in: inValue,
+            ...(asValue !== undefined ? { as: asValue } : {}),
+        };
+    }
+    // Check that every declared param is in rest.params
+    for (const param of params) {
+        if (!declaredNames.has(param.name)) {
+            issue('command_rest_invalid', `declared param not in rest mapping`, param.name, 'an entry in rest.params', 'Add a rest mapping for this param.', `${path}.params`);
+            return null;
+        }
+    }
+    // Validate path placeholders ↔ path params bijection
+    const pathParams = new Set();
+    for (const [name, mapping] of Object.entries(restParamMappings)) {
+        if (mapping.in === 'path') {
+            pathParams.add(name);
+        }
+    }
+    if (pathParams.size !== placeholders.size || ![...placeholders].every((p) => pathParams.has(p))) {
+        issue('command_rest_invalid', `mismatch between path placeholders and path params`, `placeholders: ${[...placeholders].join(', ')} | params: ${[...pathParams].join(', ')}`, 'exact bijection between {placeholders} and in:"path" params', 'Ensure every placeholder has a matching path param, and vice versa.', `${path}.path and ${path}.params`);
+        return null;
+    }
+    // Validate no body placement on GET
+    if (method === 'GET') {
+        if (bodyParams.length > 0) {
+            issue('command_rest_invalid', `GET method cannot have body params`, bodyParams.map((p) => p.name).join(', '), 'no body placement for GET', 'Move body params to query, or change the method.', `${path}.method or ${path}.params`);
+            return null;
+        }
+    }
+    // Validate rest.body (constant literal body fields, e.g. an `op` discriminator)
+    // and rest.bodyRoot (nests all param-sourced body values under one key, e.g.
+    // `args`) — both forbidden on GET, same as body params.
+    let bodyConstants;
+    if (raw['body'] !== undefined) {
+        if (method === 'GET') {
+            issue('command_rest_invalid', `GET method cannot have body constants`, 'body', 'no body for GET', 'Remove body, or change the method.', `${path}.body`);
+            return null;
+        }
+        const rawBody = raw['body'];
+        if (!isRecord(rawBody)) {
+            issue('command_rest_invalid', `body must be an object`, typeName(rawBody), 'a map of constant literal body fields (string | number | boolean)', 'Fix body.', `${path}.body`);
+            return null;
+        }
+        const constants = {};
+        for (const [key, value] of Object.entries(rawBody)) {
+            if (typeof value !== 'string' && typeof value !== 'number' && typeof value !== 'boolean') {
+                issue('command_rest_invalid', `body.${key} must be a string, number, or boolean`, typeName(value), 'string | number | boolean', `Fix body.${key}.`, `${path}.body.${key}`);
+                return null;
+            }
+            constants[key] = value;
+        }
+        // A constant key must not collide with any param's effective body key (its
+        // `as` or name) — the constant and a param-sourced value can't both claim
+        // the same top-level (or, with bodyRoot set, the same nested) key.
+        const bodyParamKeys = new Set(bodyParams.map((p) => p.as));
+        const colliding = Object.keys(constants).filter((k) => bodyParamKeys.has(k));
+        if (colliding.length > 0) {
+            issue('command_rest_invalid', `body constant key collides with a param's body key`, colliding.join(', '), "body constant keys distinct from every param's body key (its as or name)", 'Rename the colliding body constant or param.', `${path}.body`);
+            return null;
+        }
+        bodyConstants = constants;
+    }
+    let bodyRoot;
+    if (raw['bodyRoot'] !== undefined) {
+        if (method === 'GET') {
+            issue('command_rest_invalid', `GET method cannot have bodyRoot`, 'bodyRoot', 'no bodyRoot for GET', 'Remove bodyRoot, or change the method.', `${path}.bodyRoot`);
+            return null;
+        }
+        const rawBodyRoot = raw['bodyRoot'];
+        if (typeof rawBodyRoot !== 'string' || rawBodyRoot.length === 0) {
+            issue('command_rest_invalid', `bodyRoot must be a non-empty string`, typeName(rawBodyRoot), 'a non-empty string key', 'Fix bodyRoot.', `${path}.bodyRoot`);
+            return null;
+        }
+        bodyRoot = rawBodyRoot;
+    }
+    // Validate file params: only context-file and any type:"path" param (positional
+    // or flag) can be placed in body — §4.4's "path param" covers both authoring forms.
+    for (const [name, placement] of Object.entries(restParamMappings)) {
+        const param = paramsByName.get(name);
+        const isFileParam = param.kind === 'context-file' ||
+            ((param.kind === 'positional' || param.kind === 'flag') && param.type === 'path');
+        if (isFileParam && placement.in !== 'body') {
+            const paramKind = param.kind === 'context-file' ? 'context-file' : `path ${param.kind}`;
+            issue('command_rest_invalid', `file param (${paramKind}) must be placed in body`, `${name}: in "${placement.in}"`, 'in: "body"', 'Move the file param to body.', `${path}.params.${name}.in`);
+            return null;
+        }
+    }
+    // Validate coalesced body source rule: exactly one stdin + one non-stdin sharing same `as`
+    const bodyAsGroups = new Map();
+    for (const bp of bodyParams) {
+        if (!bodyAsGroups.has(bp.as)) {
+            bodyAsGroups.set(bp.as, []);
+        }
+        bodyAsGroups.get(bp.as).push({ name: bp.name, isStdin: bp.isStdin });
+    }
+    for (const [asName, group] of bodyAsGroups.entries()) {
+        if (group.length > 1) {
+            // Multiple params sharing the same body `as`
+            const stdinCount = group.filter((g) => g.isStdin).length;
+            const nonStdinCount = group.filter((g) => !g.isStdin).length;
+            // Only valid if exactly one stdin + one non-stdin
+            if (!(stdinCount === 1 && nonStdinCount === 1)) {
+                issue('command_rest_invalid', `invalid body as grouping`, group.map((g) => g.name).join(', '), 'exactly one stdin param and one non-stdin param may share a body as (for coalesced sources)', 'Fix the body grouping.', `${path}.params (as: "${asName}")`);
+                return null;
+            }
+        }
+    }
+    return {
+        method: method,
+        path: restPath,
+        ...(streaming !== false ? { streaming } : {}),
+        ...(bodyConstants !== undefined ? { body: bodyConstants } : {}),
+        ...(bodyRoot !== undefined ? { bodyRoot } : {}),
+        params: restParamMappings,
+    };
+}