@north-light/crouter 0.3.154

package/dist/core/command-manifests/schema.js

@@ -0,0 +1,849 @@
+// Shared command-manifest schema: common descriptors, strict validators,
+// and leaf-dialect specialization for plugins vs configured CLIs.
+//
+// The descriptor vocabulary (DeclRootEntry, DeclBranch, DeclNode, InputParam,
+// Field) is transport-neutral and reused by both plugins (local executable) and
+// configured CLIs (remote HTTP). Leaves specialize into two strict dialects:
+// PluginDeclLeaf requires only outputKind: 'object'; ConfiguredCliDeclLeaf
+// requires only rest (and derives outputKind from rest.streaming).
+// ---------------------------------------------------------------------------
+// Validation helpers
+// ---------------------------------------------------------------------------
+const TIERS = new Set(['normal', 'common', 'important']);
+const FLAG_TYPES = new Set(['string', 'int', 'bool', 'path', 'enum']);
+const KEBAB = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+const BRANCH_KEYS = new Set([
+    'kind', 'name', 'description', 'whenToUse', 'tier', 'rootEntry', 'summary', 'model', 'children',
+]);
+/** Only the plugin dialect may declare `passthrough`; the configured-CLI dialect
+ *  keeps BRANCH_KEYS, so a remote manifest declaring it fails as an unknown key. */
+const PLUGIN_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 PLUGIN_LEAF_KEYS = new Set([...LEAF_KEYS_COMMON, 'outputKind']);
+const CONFIGURED_LEAF_KEYS = new Set([...LEAF_KEYS_COMMON, 'rest']);
+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', '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']);
+/** 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 isObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function typeName(v) {
+    if (v === null)
+        return 'null';
+    if (Array.isArray(v))
+        return 'array';
+    return typeof v;
+}
+function checkKeys(raw, allowed, path, issue) {
+    const unknown = Object.keys(raw).filter((k) => !allowed.has(k));
+    if (unknown.length > 0) {
+        issue('command_node_invalid', `unknown keys`, unknown.join(', '), `only: ${[...allowed].join(', ')}`, 'Remove the unknown keys.', path);
+        return false;
+    }
+    return true;
+}
+function validateRootEntry(raw, path, issue) {
+    if (!isObject(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 (!isObject(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') {
+                issue('command_node_invalid', `positional type must be string|path`, String(p['type']), 'string | path | omitted', 'Fix the positional type.', `${pp}.type`);
+                return null;
+            }
+            const encoding = validateFileEncoding(p, pp, issue);
+            if (encoding === null)
+                return null;
+            const envDefault = validateDefaultFromEnv(p, pp, issue);
+            if (envDefault === null)
+                return null;
+            out.push({
+                kind: 'positional',
+                name,
+                ...(p['type'] !== undefined ? { type: p['type'] } : {}),
+                required: p['required'],
+                constraint: p['constraint'],
+                ...(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`, String(type), 'string | int | bool | path | enum', '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')) {
+                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 flag is in scope: a repeatable flag 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;
+}
+function validateOutput(raw, path, issue) {
+    if (!Array.isArray(raw)) {
+        issue('command_node_invalid', `output must be an array`, typeName(raw), 'an array of output fields', 'Declare the leaf output fields.', path);
+        return null;
+    }
+    const out = [];
+    for (let i = 0; i < raw.length; i++) {
+        const f = raw[i];
+        const fp = `${path}[${i}]`;
+        if (!isObject(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 (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['required'] !== 'boolean') {
+            issue('command_node_invalid', `output field required must be a boolean`, typeName(f['required']), 'true | false', 'Set required.', `${fp}.required`);
+            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;
+        }
+        out.push({ name: f['name'], type: f['type'], required: f['required'], constraint: f['constraint'] });
+    }
+    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;
+}
+// ---------------------------------------------------------------------------
+// Node validators (plugin and configured CLI dialects)
+// ---------------------------------------------------------------------------
+/** Validate a node for the plugin dialect (leaf must have outputKind: 'object'). */
+export function validatePluginNode(raw, path, topLevel, issue) {
+    if (!isObject(raw)) {
+        issue('command_node_invalid', `node must be an object`, typeName(raw), 'a branch or leaf node object', 'Fix the node.', path);
+        return null;
+    }
+    const kind = raw['kind'];
+    if (kind === 'branch')
+        return validatePluginBranch(raw, path, topLevel, issue);
+    if (kind === 'leaf') {
+        if (topLevel) {
+            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.', `${path}.kind`);
+            return null;
+        }
+        return validatePluginLeaf(raw, path, issue);
+    }
+    issue('command_node_invalid', `node kind must be "branch" or "leaf"`, String(kind), 'branch | leaf', 'Set kind to branch or leaf.', `${path}.kind`);
+    return null;
+}
+function validatePluginBranch(raw, path, topLevel, issue) {
+    if (!checkKeys(raw, PLUGIN_BRANCH_KEYS, path, issue))
+        return null;
+    if (!checkCommon(raw, path, issue))
+        return null;
+    const hasRoot = raw['rootEntry'] !== undefined;
+    if (topLevel && !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 && hasRoot) {
+        issue('command_node_invalid', `nested branch must not declare a rootEntry`, 'rootEntry', 'no rootEntry (only top-level branches carry one)', 'Remove rootEntry from the nested branch.', `${path}.rootEntry`);
+        return null;
+    }
+    let rootEntry;
+    if (hasRoot) {
+        const re = validateRootEntry(raw['rootEntry'], `${path}.rootEntry`, issue);
+        if (re === null)
+            return null;
+        rootEntry = re;
+    }
+    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 (raw['passthrough'] !== undefined) {
+        const pt = validatePassthrough(raw['passthrough'], `${path}.passthrough`, issue);
+        if (pt === null)
+            return null;
+        passthrough = pt;
+    }
+    const children = raw['children'];
+    if (passthrough !== undefined) {
+        // A passthrough branch intercepts every argv token after it, so a child
+        // would be unreachable — declare the emptiness rather than implying it.
+        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) || children.length === 0) {
+        issue('command_node_invalid', `branch children must be a non-empty array`, typeName(children), 'a non-empty array of branch/leaf nodes', 'Add at least one child.', `${path}.children`);
+        return null;
+    }
+    const validated = [];
+    const childNames = new Set();
+    for (let i = 0; i < children.length; i++) {
+        const c = validatePluginNode(children[i], `${path}.children[${i}]`, false, issue);
+        if (c === null)
+            return null;
+        if (childNames.has(c.name)) {
+            issue('command_node_invalid', `duplicate child name`, c.name, 'unique child names within a branch', 'Rename the duplicate child.', `${path}.children[${i}].name`);
+            return null;
+        }
+        childNames.add(c.name);
+        validated.push(c);
+    }
+    return {
+        kind: 'branch',
+        name: raw['name'],
+        description: raw['description'],
+        whenToUse: raw['whenToUse'],
+        ...(raw['tier'] !== undefined ? { tier: raw['tier'] } : {}),
+        ...(rootEntry !== undefined ? { rootEntry } : {}),
+        summary: raw['summary'],
+        ...(raw['model'] !== undefined ? { model: raw['model'] } : {}),
+        ...(passthrough !== undefined ? { passthrough } : {}),
+        children: validated,
+    };
+}
+/** `passthrough: { bin, installHint }` — both required non-empty strings. */
+function validatePassthrough(raw, path, issue) {
+    if (!isObject(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 validatePluginLeaf(raw, path, issue) {
+    if (!checkKeys(raw, PLUGIN_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 (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;
+    }
+    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((e) => typeof e === '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;
+    }
+    return {
+        kind: 'leaf',
+        name: raw['name'],
+        description: raw['description'],
+        whenToUse: raw['whenToUse'],
+        ...(raw['tier'] !== undefined ? { tier: raw['tier'] } : {}),
+        summary: raw['summary'],
+        params,
+        output,
+        outputKind: 'object',
+        effects: effects,
+    };
+}
+/** Validate a node for the configured CLI dialect (leaf must have rest). */
+export function validateConfiguredCliNode(raw, path, topLevel, issue) {
+    if (!isObject(raw)) {
+        issue('command_node_invalid', `node must be an object`, typeName(raw), 'a branch or leaf node object', 'Fix the node.', path);
+        return null;
+    }
+    const kind = raw['kind'];
+    if (kind === 'branch')
+        return validateConfiguredCliBranch(raw, path, topLevel, issue);
+    if (kind === 'leaf') {
+        if (topLevel) {
+            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.', `${path}.kind`);
+            return null;
+        }
+        return validateConfiguredCliLeaf(raw, path, issue);
+    }
+    issue('command_node_invalid', `node kind must be "branch" or "leaf"`, String(kind), 'branch | leaf', 'Set kind to branch or leaf.', `${path}.kind`);
+    return null;
+}
+function validateConfiguredCliBranch(raw, path, topLevel, issue) {
+    if (!checkKeys(raw, BRANCH_KEYS, path, issue))
+        return null;
+    if (!checkCommon(raw, path, issue))
+        return null;
+    const hasRoot = raw['rootEntry'] !== undefined;
+    if (topLevel && !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 && hasRoot) {
+        issue('command_node_invalid', `nested branch must not declare a rootEntry`, 'rootEntry', 'no rootEntry (only top-level branches carry one)', 'Remove rootEntry from the nested branch.', `${path}.rootEntry`);
+        return null;
+    }
+    let rootEntry;
+    if (hasRoot) {
+        const re = validateRootEntry(raw['rootEntry'], `${path}.rootEntry`, issue);
+        if (re === null)
+            return null;
+        rootEntry = re;
+    }
+    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;
+    }
+    const children = raw['children'];
+    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 c = validateConfiguredCliNode(children[i], `${path}.children[${i}]`, false, issue);
+        if (c === null)
+            return null;
+        if (childNames.has(c.name)) {
+            issue('command_node_invalid', `duplicate child name`, c.name, 'unique child names within a branch', 'Rename the duplicate child.', `${path}.children[${i}].name`);
+            return null;
+        }
+        childNames.add(c.name);
+        validated.push(c);
+    }
+    return {
+        kind: 'branch',
+        name: raw['name'],
+        description: raw['description'],
+        whenToUse: raw['whenToUse'],
+        ...(raw['tier'] !== undefined ? { tier: raw['tier'] } : {}),
+        ...(rootEntry !== undefined ? { rootEntry } : {}),
+        summary: raw['summary'],
+        ...(raw['model'] !== undefined ? { model: raw['model'] } : {}),
+        children: validated,
+    };
+}
+function validateConfiguredCliLeaf(raw, path, issue) {
+    if (!checkKeys(raw, CONFIGURED_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;
+    }
+    // Configured CLI leaves require `rest`, not `outputKind`
+    if (raw['rest'] === undefined) {
+        issue('command_node_invalid', `configured CLI 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((e) => typeof e === '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;
+    }
+    // Validate the REST mapping (includes coalesced body source rule)
+    const rest = validateRestMapping(raw['rest'], path, params, issue);
+    if (rest === null)
+        return null;
+    return {
+        kind: 'leaf',
+        name: raw['name'],
+        description: raw['description'],
+        whenToUse: raw['whenToUse'],
+        ...(raw['tier'] !== undefined ? { tier: raw['tier'] } : {}),
+        summary: raw['summary'],
+        params,
+        output,
+        effects: effects,
+        rest,
+    };
+}
+// ---------------------------------------------------------------------------
+// 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 (!isObject(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 (!isObject(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 (!isObject(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;
+            }
+        }
+        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 flag'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.repeatable === true && inValue !== 'body') {
+            issue('command_rest_invalid', `repeatable flag 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 (!isObject(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,
+    };
+}