@north-light/crouter 0.3.318 → 0.3.319

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

@@ -1,736 +1 @@
-// 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 `@north-light/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']);
-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']);
-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']);
-/** 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') {
-                issue('command_node_invalid', `positional type must be string|path`, String(p['type']), 'string | path | 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'];
-            }
-            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`, 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 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;
-}
-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 (!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 (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;
-}
-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 rest = validateRestMapping(raw['rest'], path, params, issue);
-    return rest === null ? null : { ...base, 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 (!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;
-            }
-        }
-        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,
-    };
-}
+var z=Object.defineProperty;var v=(e,o)=>z(e,"name",{value:o,configurable:!0});import{isRecord as x}from"../../shared/predicates.js";const B=new Set(["normal","common","important"]),I=new Set(["string","int","bool","path","enum"]),U=/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/,N=new Set(["kind","name","description","whenToUse","tier","rootEntry","extensible","summary","model","children"]),V=new Set([...N,"passthrough"]),Z=new Set(["bin","installHint"]),O=new Set(["kind","name","description","whenToUse","tier","summary","params","output","effects"]),L=new Set([...O,"outputKind"]),W=new Set([...O,"rest"]),X=new Set(["concept","description","whenToUse"]),J=new Set(["text","base64"]),H={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"])},Q=new Set(["name","type","required","constraint"]),w=/^[A-Z][A-Z0-9_]*$/;function m(e){return e===null?"null":Array.isArray(e)?"array":typeof e}v(m,"typeName");function R(e,o,t,n){const a=Object.keys(e).filter(l=>!o.has(l));return a.length>0?(n("command_node_invalid","unknown keys",a.join(", "),`only: ${[...o].join(", ")}`,"Remove the unknown keys.",t),!1):!0}v(R,"checkKeys");function ee(e,o,t){if(!x(e))return t("command_node_invalid","rootEntry must be an object",m(e),"a { concept, description, whenToUse } object","Fix rootEntry.",o),null;if(!R(e,X,o,t))return null;for(const n of["concept","description","whenToUse"])if(typeof e[n]!="string"||e[n].length===0)return t("command_node_invalid",`rootEntry.${n} must be a non-empty string`,m(e[n]),"a non-empty string",`Add rootEntry.${n}.`,`${o}.${n}`),null;return{concept:e.concept,description:e.description,whenToUse:e.whenToUse}}v(ee,"validateRootEntry");function ne(e,o,t){if(e===void 0)return[];if(!Array.isArray(e))return t("command_node_invalid","params must be an array",m(e),"an array of params (or omitted)","Fix params.",o),null;const n=[],a=new Set;let l=0;for(let s=0;s<e.length;s++){const r=e[s],d=`${o}[${s}]`;if(!x(r))return t("command_node_invalid","param must be an object",m(r),"a param object","Fix the param.",d),null;const g=r.kind;if(typeof g!="string"||!(g in H))return t("command_node_invalid","param kind must be positional|flag|stdin|context-file",String(g),"positional | flag | stdin | context-file","Fix the param kind.",`${d}.kind`),null;if(!R(r,H[g],d,t))return null;const p=r.name;if(typeof p!="string"||!U.test(p))return t("command_node_invalid","param name must be a kebab-case token",String(p),"a kebab-case token","Rename the param.",`${d}.name`),null;if(a.has(p))return t("command_node_invalid","duplicate param name",p,"unique param names","Rename the duplicate param.",`${d}.name`),null;if(a.add(p),typeof r.required!="boolean")return t("command_node_invalid","param required must be a boolean",m(r.required),"true | false","Set required.",`${d}.required`),null;if(typeof r.constraint!="string")return t("command_node_invalid","param constraint must be a string",m(r.constraint),"an inline constraint string","Add a constraint.",`${d}.constraint`),null;if(g==="positional"){if(l++,l>1)return t("command_node_invalid","a leaf may declare at most one positional","multiple positionals","at most one positional param","Convert extra positionals to flags.",d),null;if(r.type!==void 0&&r.type!=="string"&&r.type!=="path")return t("command_node_invalid","positional type must be string|path",String(r.type),"string | path | omitted","Fix the positional type.",`${d}.type`),null;let y=!1;if(r.repeatable!==void 0){if(typeof r.repeatable!="boolean")return t("command_node_invalid","repeatable must be a boolean",m(r.repeatable),"true | false | omitted","Fix repeatable.",`${d}.repeatable`),null;y=r.repeatable}const _=C(r,d,t);if(_===null)return null;const c=M(r,d,t);if(c===null)return null;if(y&&c!==void 0)return t("command_node_invalid","repeatable positional must not declare defaultFromEnv",p,"no defaultFromEnv on a repeatable positional (values accumulate into an array)","Remove defaultFromEnv, or drop repeatable.",`${d}.defaultFromEnv`),null;n.push({kind:"positional",name:p,...r.type!==void 0?{type:r.type}:{},required:r.required,constraint:r.constraint,...y?{repeatable:!0}:{},..._!==void 0?{encoding:_}:{},...c!==void 0?{defaultFromEnv:c}:{}})}else if(g==="stdin")n.push({kind:"stdin",name:p,required:r.required,constraint:r.constraint});else if(g==="context-file")n.push({kind:"context-file",name:p,required:r.required,constraint:r.constraint,...typeof r.shape=="string"?{shape:r.shape}:{}});else if(g==="flag"){const y=r.type;if(typeof y!="string"||!I.has(y))return t("command_node_invalid","flag type must be string|int|bool|path|enum",String(y),"string | int | bool | path | enum","Fix the flag type.",`${d}.type`),null;let _;if(y==="enum"){const f=r.choices;if(!Array.isArray(f)||f.length===0||!f.every(k=>typeof k=="string"))return t("command_node_invalid","enum flag requires a non-empty string choices array",m(f),"a non-empty array of strings","Declare choices for the enum flag.",`${d}.choices`),null;_=f}else if(r.choices!==void 0)return t("command_node_invalid","choices is only valid on an enum flag","choices","no choices unless type is enum","Remove choices.",`${d}.choices`),null;let c=!1;if(r.repeatable!==void 0){if(typeof r.repeatable!="boolean")return t("command_node_invalid","repeatable must be a boolean",m(r.repeatable),"true | false | omitted","Fix repeatable.",`${d}.repeatable`),null;c=r.repeatable}if(c&&(y==="bool"||y==="path"))return t("command_node_invalid",`repeatable is not valid on a ${y} flag`,`${p}: ${y}`,"repeatable only on string | int | enum flags","Remove repeatable or change the flag type.",`${d}.repeatable`),null;if(c&&r.default!==void 0)return t("command_node_invalid","repeatable flag must not declare a default",p,"no default on a repeatable flag (values accumulate into an array)","Remove the default.",`${d}.default`),null;const $=C(r,d,t);if($===null)return null;const E=M(r,d,t);if(E===null)return null;if(c&&E!==void 0)return t("command_node_invalid","repeatable flag must not declare defaultFromEnv",p,"no defaultFromEnv on a repeatable flag (values accumulate into an array)","Remove defaultFromEnv, or drop repeatable.",`${d}.defaultFromEnv`),null;n.push({kind:"flag",name:p,type:y,..._!==void 0?{choices:_}:{},...$!==void 0?{encoding:$}:{},required:r.required,constraint:r.constraint,...r.default!==void 0?{default:r.default}:{},...c?{repeatable:!0}:{},...E!==void 0?{defaultFromEnv:E}:{}})}}return n}v(ne,"validateParams");function C(e,o,t){const n=e.encoding;if(n!==void 0)return typeof n!="string"||!J.has(n)?(t("command_node_invalid","param encoding must be text|base64",String(n),"text | base64 | omitted","Fix the encoding.",`${o}.encoding`),null):e.type!=="path"?(t("command_node_invalid",'encoding is only valid on a type:"path" param',`type ${String(e.type)}`,'type: "path"','Set the param type to "path", or remove encoding.',`${o}.encoding`),null):n}v(C,"validateFileEncoding");function M(e,o,t){const n=e.defaultFromEnv;if(n===void 0)return;if(typeof n!="string"||!w.test(n))return t("command_node_invalid","defaultFromEnv must name an environment variable in UPPER_SNAKE_CASE",String(n),'e.g. "CRTR_NODE_ID"',"Fix the environment variable name.",`${o}.defaultFromEnv`),null;const a=e.type===void 0&&e.kind==="positional"?"string":e.type;return a!=="string"&&a!=="path"?(t("command_node_invalid","defaultFromEnv is only valid on a string|path param",`type ${String(e.type)}`,'type: "string" | "path"',"Change the param type, or remove defaultFromEnv.",`${o}.defaultFromEnv`),null):e.default!==void 0?(t("command_node_invalid","a param must not declare both default and defaultFromEnv",`${String(e.name)}: default + defaultFromEnv`,"exactly one default source","Remove one \u2014 defaultFromEnv counts as supplied, a static default does not.",`${o}.defaultFromEnv`),null):n}v(M,"validateDefaultFromEnv");function te(e,o,t){if(!Array.isArray(e))return t("command_node_invalid","output must be an array",m(e),"an array of output fields","Declare the leaf output fields.",o),null;const n=[];for(let a=0;a<e.length;a++){const l=e[a],s=`${o}[${a}]`;if(!x(l))return t("command_node_invalid","output field must be an object",m(l),"a { name, type, required, constraint } object","Fix the output field.",s),null;if(!R(l,Q,s,t))return null;if(typeof l.name!="string"||l.name.length===0)return t("command_node_invalid","output field name must be a non-empty string",m(l.name),"a field name","Add a name.",`${s}.name`),null;if(typeof l.type!="string"||l.type.length===0)return t("command_node_invalid","output field type must be a non-empty string",m(l.type),"a type name","Add a type.",`${s}.type`),null;if(typeof l.required!="boolean")return t("command_node_invalid","output field required must be a boolean",m(l.required),"true | false","Set required.",`${s}.required`),null;if(typeof l.constraint!="string")return t("command_node_invalid","output field constraint must be a string",m(l.constraint),"a constraint string","Add a constraint.",`${s}.constraint`),null;n.push({name:l.name,type:l.type,required:l.required,constraint:l.constraint})}return n}v(te,"validateOutput");function G(e,o,t){const n=e.name;return typeof n!="string"||!U.test(n)?(t("command_node_invalid","node name must be a lowercase kebab-case token",String(n),'a kebab-case token like "app" or "list-all"',"Rename the node.",`${o}.name`),!1):typeof e.description!="string"||e.description.length===0?(t("command_node_invalid","node description must be a non-empty string",m(e.description),"a short parent-listing description","Add a description.",`${o}.description`),!1):typeof e.whenToUse!="string"||e.whenToUse.length===0?(t("command_node_invalid","node whenToUse must be a non-empty string",m(e.whenToUse),"a parent selection rubric","Add a whenToUse rubric.",`${o}.whenToUse`),!1):e.tier!==void 0&&!B.has(String(e.tier))?(t("command_node_invalid","node tier must be normal|common|important",String(e.tier),"normal | common | important","Fix or omit tier (external plugins cannot declare hidden commands).",`${o}.tier`),!1):!0}v(G,"checkCommon");function ae(e,o,t,n,a,l={}){const s=o.join(".");if(!x(e))return a("command_node_invalid","node must be an object",m(e),"a branch or leaf node object","Fix the node.",s),null;const r=e.kind;return r==="branch"?oe(e,s,t,n,a,l):r==="leaf"?t&&l.topLevelRootEntry!=="forbidden"?(a("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.",`${s}.kind`),null):ie(e,s,n,a):(a("command_node_invalid",'node kind must be "branch" or "leaf"',String(r),"branch | leaf","Set kind to branch or leaf.",`${s}.kind`),null)}v(ae,"validateCommandNode");function oe(e,o,t,n,a,l){const s=l.allowPassthrough!==!1;if(!R(e,n==="exec"&&s?V:N,o,a)||!G(e,o,a))return null;const d=e.rootEntry!==void 0,g=l.topLevelRootEntry??"required";if(t&&g==="required"&&!d)return a("command_node_invalid","top-level branch requires a rootEntry","(missing)","a rootEntry { concept, description, whenToUse }","Add a rootEntry to the top-level branch.",`${o}.rootEntry`),null;if((!t||g==="forbidden")&&d)return a("command_node_invalid",t?"repository fragment root must not declare a rootEntry":"nested branch must not declare a rootEntry","rootEntry",t?"no rootEntry (the owning plugin branch already has one)":"no rootEntry (only top-level branches carry one)",t?"Remove rootEntry from the repository fragment root.":"Remove rootEntry from the nested branch.",`${o}.rootEntry`),null;const p=e.extensible!==void 0;if(p&&(!t||l.allowExtensible===!1||e.extensible!==!0))return a("command_node_invalid",t?"extensible must be exactly true on a plugin top-level branch":"extensible is valid only on a top-level branch mount",String(e.extensible),t?"extensible: true":"no extensible marker on nested branches",t?"Set extensible to true or remove it.":"Move the marker to the plugin top-level branch or remove it.",`${o}.extensible`),null;let y;if(d){const f=ee(e.rootEntry,`${o}.rootEntry`,a);if(f===null)return null;y=f}if(typeof e.summary!="string"||e.summary.length===0)return a("command_node_invalid","branch summary must be a non-empty string",m(e.summary),"a one-line summary string","Add a summary.",`${o}.summary`),null;if(e.model!==void 0&&typeof e.model!="string")return a("command_node_invalid","branch model must be a string",m(e.model),"a string or omitted","Fix or remove model.",`${o}.model`),null;let _;if(n==="exec"&&e.passthrough!==void 0){const f=re(e.passthrough,`${o}.passthrough`,a);if(f===null)return null;_=f}if(p&&_!==void 0)return a("command_node_invalid","an extensible branch cannot declare passthrough","extensible and passthrough","one branch mode: extensible or passthrough","Remove passthrough or remove extensible.",o),null;const c=e.children;if(_!==void 0){if(!Array.isArray(c)||c.length!==0)return a("command_node_invalid","a passthrough branch must declare children: []",Array.isArray(c)?`${c.length} children`:m(c),"an empty children array","Set children to [] \u2014 a passthrough branch forwards all argv and can own no subcommands.",`${o}.children`),null}else if(!Array.isArray(c))return a("command_node_invalid","branch children must be an array",m(c),"an array of branch/leaf nodes (may be empty for populated by mounts)","Fix children.",`${o}.children`),null;const $=[],E=new Set;for(let f=0;f<c.length;f++){const k=ae(c[f],[...o.split("."),`children[${f}]`],!1,n,a,l);if(k===null)return null;if(E.has(k.name))return a("command_node_invalid","duplicate child name",k.name,"unique child names within a branch","Rename the duplicate child.",`${o}.children[${f}].name`),null;E.add(k.name),$.push(k)}return{kind:"branch",name:e.name,description:e.description,whenToUse:e.whenToUse,...e.tier!==void 0?{tier:e.tier}:{},...y!==void 0?{rootEntry:y}:{},...p?{extensible:!0}:{},summary:e.summary,...e.model!==void 0?{model:e.model}:{},..._!==void 0?{passthrough:_}:{},children:$}}v(oe,"validateBranch");function re(e,o,t){if(!x(e))return t("command_node_invalid","passthrough must be an object",m(e),"an object { bin, installHint }","Fix or remove passthrough.",o),null;if(!R(e,Z,o,t))return null;for(const n of["bin","installHint"])if(typeof e[n]!="string"||e[n].length===0)return t("command_node_invalid",`passthrough ${n} must be a non-empty string`,m(e[n]),n==="bin"?"the external binary name":"a one-line install hint",`Set passthrough.${n}.`,`${o}.${n}`),null;return{bin:e.bin,installHint:e.installHint}}v(re,"validatePassthrough");function ie(e,o,t,n){if(!R(e,t==="exec"?L:W,o,n)||!G(e,o,n))return null;if(typeof e.summary!="string"||e.summary.length===0)return n("command_node_invalid","leaf summary must be a non-empty string",m(e.summary),"a one-line summary string","Add a summary.",`${o}.summary`),null;if(t==="exec"&&e.outputKind!=="object")return n("command_node_invalid",'leaf outputKind must be "object" in v1',String(e.outputKind),'exactly "object"','Set outputKind to "object".',`${o}.outputKind`),null;if(t==="http"&&e.rest===void 0)return n("command_node_invalid","HTTP leaf requires a rest mapping","(missing)","a rest object with method, path, and params","Add a rest mapping.",`${o}.rest`),null;const a=ne(e.params,`${o}.params`,n);if(a===null)return null;const l=te(e.output,`${o}.output`,n);if(l===null)return null;const s=e.effects;if(!Array.isArray(s)||s.length===0||!s.every(g=>typeof g=="string"))return n("command_node_invalid","leaf effects must be a non-empty string array",m(s),'a non-empty array of strings (["None. Read-only."] for read-only leaves)',"Declare every persistent effect.",`${o}.effects`),null;const r={kind:"leaf",name:e.name,description:e.description,whenToUse:e.whenToUse,...e.tier!==void 0?{tier:e.tier}:{},summary:e.summary,params:a,output:l,effects:s};if(t==="exec")return{...r,outputKind:"object"};const d=se(e.rest,o,a,n);return d===null?null:{...r,rest:d}}v(ie,"validateLeaf");const le=new Set(["GET","POST","PUT","PATCH","DELETE"]),de=/^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/,me=new Set(["path","query","body","header"]);function se(e,o,t,n){const a=`${o}.rest`;if(!x(e))return n("command_rest_invalid","rest must be an object",m(e),"{ method, path, streaming?, params }","Provide a valid rest mapping.",a),null;const l=new Set(["method","path","streaming","body","bodyRoot","params"]),s=Object.keys(e).filter(i=>!l.has(i));if(s.length>0)return n("command_rest_invalid","unknown rest keys",s.join(", "),"only: method, path, streaming, body, bodyRoot, params","Remove the unknown keys.",a),null;const r=e.method;if(typeof r!="string"||!le.has(r))return n("command_rest_invalid","method must be GET|POST|PUT|PATCH|DELETE",String(r),"one of the HTTP methods","Set method to a valid HTTP verb.",`${a}.method`),null;const d=e.path;if(typeof d!="string"||!d.startsWith("/"))return n("command_rest_invalid","path must be an absolute path starting with /",String(d),'an absolute path like "/v1/devices/{id}"',"Fix the path.",`${a}.path`),null;const g=new Set,p=/\{([a-z][a-z0-9]*(?:-[a-z0-9]+)*)\}/g;let y;for(;(y=p.exec(d))!==null;)g.add(y[1]);let _=!1;if(e.streaming!==void 0){if(typeof e.streaming!="boolean")return n("command_rest_invalid","streaming must be a boolean",m(e.streaming),"true | false | omitted","Fix streaming.",`${a}.streaming`),null;_=e.streaming}const c=e.params;if(!x(c))return n("command_rest_invalid","params must be an object",m(c),"a mapping of param names to placement specs","Provide params.",`${a}.params`),null;const $=new Map;for(const i of t)$.set(i.name,i);const E={},f=[],k=new Set;for(const[i,h]of Object.entries(c)){if(!$.has(i))return n("command_rest_invalid","rest params key has no matching declared param",i,"a name from the leaf params array","Remove this rest params entry or declare the param.",`${a}.params.${i}`),null;if(k.add(i),!x(h))return n("command_rest_invalid","param mapping must be an object",m(h),"{ in, as? }","Fix the param mapping.",`${a}.params.${i}`),null;const S=new Set(["in","as"]),T=Object.keys(h).filter(F=>!S.has(F));if(T.length>0)return n("command_rest_invalid","unknown param mapping keys",T.join(", "),"only: in, as","Remove the unknown keys.",`${a}.params.${i}`),null;const u=h.in;if(typeof u!="string"||!me.has(u))return n("command_rest_invalid","param placement must be path|query|body|header",String(u),"path | query | body | header","Set in to a valid placement.",`${a}.params.${i}.in`),null;const b=h.as;if(b!==void 0&&(typeof b!="string"||b.length===0))return n("command_rest_invalid","as must be a non-empty string",String(b),"a non-empty string","Fix the as value.",`${a}.params.${i}.as`),null;if(u==="header"){if(typeof b!="string"||b.length===0)return n("command_rest_invalid","header placement requires a non-empty as",String(b),"a header name","Provide an as value for the header name.",`${a}.params.${i}.as`),null;if(!de.test(b))return n("command_rest_invalid",'header "as" must be a legal HTTP header field name',b,"an HTTP token (letters, digits, and !#$%&'*+-.^_`|~)","Fix the header name.",`${a}.params.${i}.as`),null}else if(u==="path"){if(b!==void 0)return n("command_rest_invalid","path placement must not have as","as","no as (placeholder name governs)","Remove as.",`${a}.params.${i}.as`),null;const F=$.get(i);if(F.required!==!0)return n("command_rest_invalid",'in:"path" param must be declared required',`${i}: required ${String(F.required)}`,"required: true",`Set "required": true on the "${i}" param.`,`${a}.params.${i}`),null}const K=$.get(i);if((K.kind==="flag"||K.kind==="positional")&&K.repeatable===!0&&u!=="body")return n("command_rest_invalid","repeatable param must use body placement",`${i}: in "${u}"`,'in: "body" (array values ship as a JSON array)',`Map "${i}" to body placement.`,`${a}.params.${i}.in`),null;if(u==="body"){const D=$.get(i).kind==="stdin",Y=b||i;f.push({name:i,isStdin:D,as:Y})}E[i]={in:u,...b!==void 0?{as:b}:{}}}for(const i of t)if(!k.has(i.name))return n("command_rest_invalid","declared param not in rest mapping",i.name,"an entry in rest.params","Add a rest mapping for this param.",`${a}.params`),null;const A=new Set;for(const[i,h]of Object.entries(E))h.in==="path"&&A.add(i);if(A.size!==g.size||![...g].every(i=>A.has(i)))return n("command_rest_invalid","mismatch between path placeholders and path params",`placeholders: ${[...g].join(", ")} | params: ${[...A].join(", ")}`,'exact bijection between {placeholders} and in:"path" params',"Ensure every placeholder has a matching path param, and vice versa.",`${a}.path and ${a}.params`),null;if(r==="GET"&&f.length>0)return n("command_rest_invalid","GET method cannot have body params",f.map(i=>i.name).join(", "),"no body placement for GET","Move body params to query, or change the method.",`${a}.method or ${a}.params`),null;let j;if(e.body!==void 0){if(r==="GET")return n("command_rest_invalid","GET method cannot have body constants","body","no body for GET","Remove body, or change the method.",`${a}.body`),null;const i=e.body;if(!x(i))return n("command_rest_invalid","body must be an object",m(i),"a map of constant literal body fields (string | number | boolean)","Fix body.",`${a}.body`),null;const h={};for(const[u,b]of Object.entries(i)){if(typeof b!="string"&&typeof b!="number"&&typeof b!="boolean")return n("command_rest_invalid",`body.${u} must be a string, number, or boolean`,m(b),"string | number | boolean",`Fix body.${u}.`,`${a}.body.${u}`),null;h[u]=b}const S=new Set(f.map(u=>u.as)),T=Object.keys(h).filter(u=>S.has(u));if(T.length>0)return n("command_rest_invalid","body constant key collides with a param's body key",T.join(", "),"body constant keys distinct from every param's body key (its as or name)","Rename the colliding body constant or param.",`${a}.body`),null;j=h}let P;if(e.bodyRoot!==void 0){if(r==="GET")return n("command_rest_invalid","GET method cannot have bodyRoot","bodyRoot","no bodyRoot for GET","Remove bodyRoot, or change the method.",`${a}.bodyRoot`),null;const i=e.bodyRoot;if(typeof i!="string"||i.length===0)return n("command_rest_invalid","bodyRoot must be a non-empty string",m(i),"a non-empty string key","Fix bodyRoot.",`${a}.bodyRoot`),null;P=i}for(const[i,h]of Object.entries(E)){const S=$.get(i);if((S.kind==="context-file"||(S.kind==="positional"||S.kind==="flag")&&S.type==="path")&&h.in!=="body"){const u=S.kind==="context-file"?"context-file":`path ${S.kind}`;return n("command_rest_invalid",`file param (${u}) must be placed in body`,`${i}: in "${h.in}"`,'in: "body"',"Move the file param to body.",`${a}.params.${i}.in`),null}}const q=new Map;for(const i of f)q.has(i.as)||q.set(i.as,[]),q.get(i.as).push({name:i.name,isStdin:i.isStdin});for(const[i,h]of q.entries())if(h.length>1){const S=h.filter(u=>u.isStdin).length,T=h.filter(u=>!u.isStdin).length;if(!(S===1&&T===1))return n("command_rest_invalid","invalid body as grouping",h.map(u=>u.name).join(", "),"exactly one stdin param and one non-stdin param may share a body as (for coalesced sources)","Fix the body grouping.",`${a}.params (as: "${i}")`),null}return{method:r,path:d,..._!==!1?{streaming:_}:{},...j!==void 0?{body:j}:{},...P!==void 0?{bodyRoot:P}:{},params:E}}v(se,"validateRestMapping");export{ae as validateCommandNode};