@north-light/api 0.3.518 → 0.3.520

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

@@ -1,10 +1,12 @@
 export interface DeclaredOutputShape {
     type: string;
     constraint: string;
-    /** Named members of an `object` value. */
+    /** Named members of an `object` value. Declaring them closes the object. */
     children?: DeclaredOutputField[];
-    /** Element shape of an `array` value. */
+    /** Shape of each contained value of an `array` or `map` value. */
     items?: DeclaredOutputShape;
+    /** Alternatives of a `union` value. */
+    variants?: DeclaredOutputShape[];
     /** Allowed values of an `enum` value. */
     values?: string[];
 }
@@ -12,14 +14,24 @@ export interface DeclaredOutputField extends DeclaredOutputShape {
     name: string;
     required: boolean;
 }
+/** The first place a value departs from its shape: `path` is the full path from
+ *  the root the caller passed (`data.messages[3].from`, `--to[1]`). */
+export interface ValueMismatch {
+    path: string;
+    expected: string;
+    receivedType: string;
+}
 /** Validates a result object against declared output field descriptors.
- *  Returns null if valid; otherwise returns a { field, receivedType } error. */
+ *  Returns null if valid; otherwise returns a { field, receivedType } error
+ *  where `field` is the full path of the first mismatch. */
 export declare function validateDeclaredResult(output: DeclaredOutputField[], result: Record<string, unknown>): {
     field: string;
     receivedType?: string;
+    expected?: string;
 } | null;
-/** Core leaf declarations may explicitly require a nullable field. */
-export declare function validateCoreDeclaredResult(output: DeclaredOutputField[], result: Record<string, unknown>): {
-    field: string;
-    receivedType?: string;
-} | null;
+/** Checks one JSON value against one shape, recursively: object members, array
+ *  items, map values, union variants, enum values and nullability. An object that
+ *  declares `children` is closed — an undeclared member is a mismatch at any
+ *  depth. Returns null, or the first mismatch with its full path from `path`.
+ *  A declared type that is not recognized is accepted. */
+export declare function validateValue(shape: DeclaredOutputShape, value: unknown, path: string): ValueMismatch | null;

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

@@ -1,55 +1,47 @@
 import { isRecord } from '../../shared/predicates.js';
 /** Validates a result object against declared output field descriptors.
- *  Returns null if valid; otherwise returns a { field, receivedType } error. */
+ *  Returns null if valid; otherwise returns a { field, receivedType } error
+ *  where `field` is the full path of the first mismatch. */
 export function validateDeclaredResult(output, result) {
-    return validateFields(output, result, true);
-}
-/** Core leaf declarations may explicitly require a nullable field. */
-export function validateCoreDeclaredResult(output, result) {
-    return validateFields(output, result, true);
-}
-function validateFields(output, result, honorDeclaredNull) {
     for (const f of output) {
         const value = result[f.name];
-        const present = Object.prototype.hasOwnProperty.call(result, f.name)
-            && value !== undefined
-            && (honorDeclaredNull || value !== null);
-        if (f.required && !present)
-            return { field: f.name };
-        const matches = honorDeclaredNull ? coreTypeMatches(f, value) : typeMatches(f.type, value);
-        if (present && !matches) {
-            return { field: f.name, receivedType: value === null ? 'null' : typeof value };
+        const present = Object.prototype.hasOwnProperty.call(result, f.name) && value !== undefined;
+        if (!present) {
+            if (f.required)
+                return { field: f.name };
+            continue;
         }
+        const mismatch = validateValue(f, value, f.name);
+        if (mismatch !== null)
+            return { field: mismatch.path, receivedType: mismatch.receivedType, expected: mismatch.expected };
     }
     return null;
 }
-/** Loose type check over the declared type vocabulary. Only the recognized
- *  primitive/container categories are enforced; an unrecognized declared type
- *  falls back to presence-only. */
-function typeMatches(type, v) {
-    const t = type.toLowerCase();
-    if (t === 'string' || t === 'path')
-        return typeof v === 'string';
-    if (t === 'int' || t === 'integer')
-        return typeof v === 'number' && Number.isInteger(v);
-    if (t === 'number' || t === 'float')
-        return typeof v === 'number';
-    if (t === 'bool' || t === 'boolean')
-        return typeof v === 'boolean';
-    if (t === 'array' || t.endsWith('[]'))
-        return Array.isArray(v);
-    if (t === 'object')
-        return isRecord(v);
-    return true;
+/** Checks one JSON value against one shape, recursively: object members, array
+ *  items, map values, union variants, enum values and nullability. An object that
+ *  declares `children` is closed — an undeclared member is a mismatch at any
+ *  depth. Returns null, or the first mismatch with its full path from `path`.
+ *  A declared type that is not recognized is accepted. */
+export function validateValue(shape, value, path) {
+    const atoms = shape.type.split('|').map((part) => part.trim()).filter(Boolean);
+    const bases = atoms.filter((part) => part.toLowerCase() !== 'null');
+    if (value === null && bases.length < atoms.length)
+        return null;
+    if (bases.length === 1 && !knownType(bases[0]))
+        return null;
+    if (!atoms.every((part) => knownType(part) || /^[a-z][a-z0-9_-]*$/.test(part)))
+        return null;
+    if (bases.length === 1)
+        return atomMismatch(bases[0], shape, value, path);
+    for (const atom of bases) {
+        if (atomMismatch(atom, shape, value, path) === null)
+            return null;
+    }
+    return mismatch(path, shape.type, value);
 }
-function coreTypeMatches(shape, v) {
-    const alternatives = shape.type.split('|').map((part) => part.trim()).filter(Boolean);
-    if (alternatives.length === 1 && !knownType(alternatives[0]))
-        return true;
-    const allKnown = alternatives.every((part) => knownType(part) || /^[a-z][a-z0-9_-]*$/.test(part));
-    if (!allKnown)
-        return true;
-    return alternatives.some((part) => atomMatches(part, v, shape));
+function mismatch(path, expected, value) {
+    const receivedType = value === null ? 'null' : Array.isArray(value) ? 'array' : typeof value;
+    return { path, expected, receivedType };
 }
 function knownType(type) {
     const t = type.toLowerCase();
@@ -66,32 +58,102 @@ function knownType(type) {
         || t === 'array'
         || t.endsWith('[]')
         || t === 'object'
+        || t === 'map'
+        || t === 'union'
+        || t === 'unknown'
         || t === 'enum'
         || t === 'file';
 }
-function atomMatches(type, v, shape) {
+function atomMismatch(type, shape, v, path) {
     const t = type.toLowerCase();
+    const fail = (expected) => mismatch(path, expected, v);
     if (t === 'null')
-        return v === null;
+        return v === null ? null : fail('null');
+    if (t === 'unknown')
+        return null;
     // An enum with declared `values` holds one of them; one without stays
     // presence-only, as before `values` existed.
-    if (t === 'enum')
-        return shape.values === undefined || (typeof v === 'string' && shape.values.includes(v));
+    if (t === 'enum') {
+        if (shape.values === undefined || (typeof v === 'string' && shape.values.includes(v)))
+            return null;
+        return fail(`one of ${(shape.values ?? []).join(', ')}`);
+    }
     // A file output is the provider's file object on the wire, or the runtime path
     // the daemon put in its place.
     if (t === 'file')
-        return isRecord(v) || typeof v === 'string';
+        return isRecord(v) || typeof v === 'string' ? null : fail('file');
     if (t === 'string' || t === 'path' || t === 'markdown')
-        return typeof v === 'string';
+        return typeof v === 'string' ? null : fail(t);
     if (t === 'int' || t === 'integer')
-        return typeof v === 'number' && Number.isInteger(v);
+        return typeof v === 'number' && Number.isInteger(v) ? null : fail('int');
     if (t === 'number' || t === 'float')
-        return typeof v === 'number';
+        return typeof v === 'number' ? null : fail('number');
     if (t === 'bool' || t === 'boolean')
-        return typeof v === 'boolean';
-    if (t === 'array' || t.endsWith('[]'))
-        return Array.isArray(v);
-    if (t === 'object')
-        return isRecord(v);
-    return typeof v === 'string' && v === type;
+        return typeof v === 'boolean' ? null : fail('bool');
+    if (t === 'array') {
+        if (!Array.isArray(v))
+            return fail('array');
+        if (shape.items === undefined)
+            return null;
+        for (let i = 0; i < v.length; i++) {
+            const inner = validateValue(shape.items, v[i], `${path}[${i}]`);
+            if (inner !== null)
+                return inner;
+        }
+        return null;
+    }
+    if (t.endsWith('[]'))
+        return Array.isArray(v) ? null : fail('array');
+    if (t === 'map') {
+        if (!isRecord(v))
+            return fail('map');
+        if (shape.items === undefined)
+            return null;
+        for (const [key, entry] of Object.entries(v)) {
+            const inner = validateValue(shape.items, entry, `${path}[${JSON.stringify(key)}]`);
+            if (inner !== null)
+                return inner;
+        }
+        return null;
+    }
+    if (t === 'object') {
+        if (!isRecord(v))
+            return fail('object');
+        if (shape.children === undefined)
+            return null;
+        for (const member of shape.children) {
+            const memberValue = v[member.name];
+            const present = Object.prototype.hasOwnProperty.call(v, member.name) && memberValue !== undefined;
+            if (!present) {
+                if (member.required)
+                    return { path: `${path}.${member.name}`, expected: `${member.type} (required)`, receivedType: 'undefined' };
+                continue;
+            }
+            const inner = validateValue(member, memberValue, `${path}.${member.name}`);
+            if (inner !== null)
+                return inner;
+        }
+        const declared = new Set(shape.children.map((member) => member.name));
+        for (const key of Object.keys(v)) {
+            if (!declared.has(key))
+                return mismatch(`${path}.${key}`, 'no such member (the object is closed)', v[key]);
+        }
+        return null;
+    }
+    if (t === 'union') {
+        const failures = [];
+        for (const variant of shape.variants ?? []) {
+            const inner = validateValue(variant, v, path);
+            if (inner === null)
+                return null;
+            failures.push(inner);
+        }
+        // Every variant rejecting the value at the same deeper member names that member, expecting any variant's type.
+        const first = failures[0];
+        if (first !== undefined && first.path !== path && failures.every((failure) => failure.path === first.path)) {
+            return { path: first.path, expected: [...new Set(failures.map((failure) => failure.expected))].join(' | '), receivedType: first.receivedType };
+        }
+        return fail((shape.variants ?? []).map((variant) => variant.type).join(' | '));
+    }
+    return typeof v === 'string' && v === type ? null : fail(type);
 }

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

@@ -6,8 +6,8 @@
 // module owns the validators and re-exports those types under their in-tree names.
 import { isRecord } from '../../shared/predicates.js';
 // Validation helpers
-const TIERS = new Set(['normal', 'common', 'important']);
-const FLAG_TYPES = new Set(['string', 'int', 'bool', 'path', 'enum', 'file']);
+const TIERS = new Set(['hidden', 'normal', 'common', 'important']);
+const FLAG_TYPES = new Set(['string', 'int', 'bool', 'path', 'enum', 'file', 'json']);
 /** A capability-provider tool group id (contract 1 `<id>` grammar), so
  *  `<provider>:<group>` splits on its first `:`. */
 const GROUP_ID = /^[A-Za-z0-9_-]{1,64}$/;
@@ -39,13 +39,14 @@ const PARAM_KEYS_BY_KIND = {
         'repeatable',
         'encoding',
         'defaultFromEnv',
+        'shape',
     ]),
     stdin: new Set(['kind', 'name', 'required', 'constraint']),
     'context-file': new Set(['kind', 'name', 'required', 'constraint', 'shape']),
 };
-const OUTPUT_KEYS = new Set(['name', 'type', 'required', 'constraint', 'children', 'items', 'values']);
+const OUTPUT_KEYS = new Set(['name', 'type', 'required', 'constraint', 'children', 'items', 'variants', 'values']);
 /** An `items` element shape: an output field without a name or required. */
-const OUTPUT_SHAPE_KEYS = new Set(['type', 'constraint', 'children', 'items', 'values']);
+const OUTPUT_SHAPE_KEYS = new Set(['type', 'constraint', 'children', 'items', 'variants', 'values']);
 /** UPPER_SNAKE_CASE environment variable name — the only form an ambient default
  *  may name, so a typo'd lowercase key fails at authoring time rather than
  *  silently never resolving. */
@@ -184,7 +185,7 @@ function validateParams(raw, path, issue) {
         else if (kind === 'flag') {
             const type = p['type'];
             if (typeof type !== 'string' || !FLAG_TYPES.has(type)) {
-                issue('command_node_invalid', `flag type must be string|int|bool|path|enum|file`, String(type), 'string | int | bool | path | enum | file', 'Fix the flag type.', `${pp}.type`);
+                issue('command_node_invalid', `flag type must be string|int|bool|path|enum|file|json`, String(type), 'string | int | bool | path | enum | file | json', 'Fix the flag type.', `${pp}.type`);
                 return null;
             }
             let choices;
@@ -200,6 +201,24 @@ function validateParams(raw, path, issue) {
                 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 shape;
+            if (type === 'json') {
+                const raw = p['shape'];
+                if (!isRecord(raw)) {
+                    issue('command_node_invalid', `json flag requires a shape object`, typeName(raw), 'a { type, constraint, children?, items?, variants?, values? } object', 'Declare the shape of the JSON value the flag takes.', `${pp}.shape`);
+                    return null;
+                }
+                if (!checkKeys(raw, OUTPUT_SHAPE_KEYS, `${pp}.shape`, issue))
+                    return null;
+                const validated = validateOutputShape(raw, `${pp}.shape`, false, issue);
+                if (validated === null)
+                    return null;
+                shape = validated;
+            }
+            else if (p['shape'] !== undefined) {
+                issue('command_node_invalid', `shape is only valid on a json flag`, 'shape', 'no shape unless type is json', 'Remove shape.', `${pp}.shape`);
+                return null;
+            }
             let repeatable = false;
             if (p['repeatable'] !== undefined) {
                 if (typeof p['repeatable'] !== 'boolean') {
@@ -208,7 +227,11 @@ function validateParams(raw, path, issue) {
                 }
                 repeatable = p['repeatable'];
             }
-            if (repeatable && (type === 'bool' || type === 'path' || type === 'file')) {
+            if (type === 'json' && (p['default'] !== undefined || p['defaultFromEnv'] !== undefined)) {
+                issue('command_node_invalid', `a json flag takes no default`, name, 'no default or defaultFromEnv on a json flag', 'Remove the default.', `${pp}.${p['default'] !== undefined ? 'default' : 'defaultFromEnv'}`);
+                return null;
+            }
+            if (repeatable && (type === 'bool' || type === 'path' || type === 'file' || type === 'json')) {
                 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;
             }
@@ -230,6 +253,7 @@ function validateParams(raw, path, issue) {
                 kind: 'flag',
                 name,
                 type: type,
+                ...(shape !== undefined ? { shape } : {}),
                 ...(choices !== undefined ? { choices } : {}),
                 ...(encoding !== undefined ? { encoding } : {}),
                 required: p['required'],
@@ -327,16 +351,26 @@ function validateOutputShape(f, fp, topLevel, issue) {
         return null;
     }
     const structural = [
-        ['children', 'object'],
-        ['items', 'array'],
-        ['values', 'enum'],
+        ['children', ['object']],
+        ['items', ['array', 'map']],
+        ['variants', ['union']],
+        ['values', ['enum']],
     ];
     for (const [key, allowedOn] of structural) {
-        if (f[key] !== undefined && base !== allowedOn) {
-            issue('command_node_invalid', `output ${key} is only valid on an ${allowedOn} field`, `type ${type}`, `type "${allowedOn}" (optionally "${allowedOn} | null")`, `Remove ${key}, or change the type to ${allowedOn}.`, `${fp}.${key}`);
+        if (f[key] !== undefined && !allowedOn.includes(base)) {
+            const names = allowedOn.map((a) => `"${a}"`).join(' or ');
+            issue('command_node_invalid', `output ${key} is only valid on a ${allowedOn.join(' or ')} field`, `type ${type}`, `type ${names} (optionally "| null")`, `Remove ${key}, or change the type to ${allowedOn[0]}.`, `${fp}.${key}`);
             return null;
         }
     }
+    if (base === 'union' && f['variants'] === undefined) {
+        issue('command_node_invalid', `a union output requires variants`, `type ${type}`, 'variants: two or more shapes', 'Declare the alternatives the union may take.', `${fp}.variants`);
+        return null;
+    }
+    if (base === 'map' && f['items'] === undefined) {
+        issue('command_node_invalid', `a map output requires items`, `type ${type}`, 'items: the shape of every value', 'Declare the shape of the map\'s values, or use type "object".', `${fp}.items`);
+        return null;
+    }
     let children;
     if (f['children'] !== undefined) {
         const c = validateOutputFields(f['children'], `${fp}.children`, false, issue);
@@ -349,7 +383,7 @@ function validateOutputShape(f, fp, topLevel, issue) {
         const raw = f['items'];
         const ip = `${fp}.items`;
         if (!isRecord(raw)) {
-            issue('command_node_invalid', `output items must be an object`, typeName(raw), 'a { type, constraint, children?, items?, values? } object', 'Fix the items shape.', ip);
+            issue('command_node_invalid', `output items must be an object`, typeName(raw), 'a { type, constraint, children?, items?, variants?, values? } object', 'Fix the items shape.', ip);
             return null;
         }
         if (!checkKeys(raw, OUTPUT_SHAPE_KEYS, ip, issue))
@@ -359,6 +393,29 @@ function validateOutputShape(f, fp, topLevel, issue) {
             return null;
         items = shape;
     }
+    let variants;
+    if (f['variants'] !== undefined) {
+        const raw = f['variants'];
+        if (!Array.isArray(raw) || raw.length < 2) {
+            issue('command_node_invalid', `union variants must be an array of two or more shapes`, Array.isArray(raw) ? `${raw.length} variant${raw.length === 1 ? '' : 's'}` : typeName(raw), 'an array of two or more { type, constraint, ... } shapes', 'Declare at least two variants, or use the variant\'s own type.', `${fp}.variants`);
+            return null;
+        }
+        variants = [];
+        for (let i = 0; i < raw.length; i++) {
+            const vp = `${fp}.variants[${i}]`;
+            const v = raw[i];
+            if (!isRecord(v)) {
+                issue('command_node_invalid', `union variant must be an object`, typeName(v), 'a { type, constraint, ... } object', 'Fix the variant shape.', vp);
+                return null;
+            }
+            if (!checkKeys(v, OUTPUT_SHAPE_KEYS, vp, issue))
+                return null;
+            const shape = validateOutputShape(v, vp, false, issue);
+            if (shape === null)
+                return null;
+            variants.push(shape);
+        }
+    }
     let values;
     if (f['values'] !== undefined) {
         const v = f['values'];
@@ -377,6 +434,7 @@ function validateOutputShape(f, fp, topLevel, issue) {
         constraint: f['constraint'],
         ...(children !== undefined ? { children } : {}),
         ...(items !== undefined ? { items } : {}),
+        ...(variants !== undefined ? { variants } : {}),
         ...(values !== undefined ? { values } : {}),
     };
 }
@@ -404,8 +462,8 @@ function validateOutputFields(raw, path, topLevel, issue) {
             issue('command_node_invalid', `output field name must be a non-empty string`, typeName(f['name']), 'a field name', 'Add a name.', `${fp}.name`);
             return null;
         }
-        if (!topLevel && names.has(f['name'])) {
-            issue('command_node_invalid', `duplicate output child name`, f['name'], 'unique member names within one object', 'Rename the duplicate member.', `${fp}.name`);
+        if (names.has(f['name'])) {
+            issue('command_node_invalid', topLevel ? `duplicate output field name` : `duplicate output child name`, f['name'], topLevel ? 'unique output field names within one leaf' : 'unique member names within one object', topLevel ? 'Rename the duplicate field.' : 'Rename the duplicate member.', `${fp}.name`);
             return null;
         }
         names.add(f['name']);
@@ -442,7 +500,7 @@ function checkCommon(raw, path, issue) {
         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`);
+        issue('command_node_invalid', `node tier must be hidden|normal|common|important`, String(raw['tier']), 'hidden | normal | common | important', 'Fix or omit tier.', `${path}.tier`);
         return false;
     }
     return true;

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

@@ -1,5 +1,5 @@
 /** How prominently a node surfaces in ancestor `-h` listings. Default 'normal'. */
-export type ManifestTier = 'normal' | 'common' | 'important';
+export type ManifestTier = 'hidden' | 'normal' | 'common' | 'important';
 /** Root-entry prose for a top-level branch — what every agent reads before it
  *  has engaged the command at all. Required on a plugin's top-level branch. */
 export interface ManifestRootEntry {
@@ -16,8 +16,10 @@ export interface ManifestFieldShape {
     constraint: string;
     /** Named members; only when the base type is `object`. */
     children?: ManifestField[];
-    /** Element shape; only when the base type is `array`. */
+    /** Value shape; only when the base type is `array` or `map`. */
     items?: ManifestFieldShape;
+    /** Alternatives; required when the base type is `union`. */
+    variants?: ManifestFieldShape[];
     /** The allowed values; required, and only valid, when the base type is `enum`. */
     values?: string[];
 }
@@ -53,7 +55,9 @@ export interface ManifestFlagParam {
     /** 'bool' flags take no value — presence is true. 'file' names a file
      *  argument a capability-provider call carries; locally it is sent as the
      *  string typed, never read from disk (that is `path` with `encoding`). */
-    type: 'string' | 'int' | 'bool' | 'path' | 'enum' | 'file';
+    type: 'string' | 'int' | 'bool' | 'path' | 'enum' | 'file' | 'json';
+    /** Required only for a json flag. */
+    shape?: ManifestFieldShape;
     /** Required, and only valid, when type is 'enum'. */
     choices?: string[];
     required: boolean;

package/dist/core/help.d.ts

@@ -1,4 +1,4 @@
-import type { DeclaredOutputField } from '../api/command-manifest/result.js';
+import type { DeclaredOutputField, DeclaredOutputShape } from '../api/command-manifest/result.js';
 export type Field = DeclaredOutputField;
 /** Positional argument. A repeatable positional consumes every remaining positional token. */
 export interface PositionalParam {
@@ -43,7 +43,9 @@ export interface FlagParam {
     name: string;
     /** 'bool' flags take no value — presence = true. 'file' names a
      *  capability-provider file argument, sent locally as the string typed. */
-    type: 'string' | 'int' | 'bool' | 'path' | 'enum' | 'file';
+    type: 'string' | 'int' | 'bool' | 'path' | 'enum' | 'file' | 'json';
+    /** Required only when type is 'json': the shape of the one JSON value the flag takes. */
+    shape?: DeclaredOutputShape;
     /** Required only when type is 'enum'. */
     choices?: string[];
     required: boolean;

package/dist/core/help.js

@@ -2,6 +2,7 @@
 // Pure functions — no side effects, no commander, no process.exit.
 // Rendering matches reference.md shapes exactly:
 //   root L11-32, branch L43-58, leaf L65-189.
+import { outputBaseType } from '../api/command-manifest/schema.js';
 /** `help` with the async state the render shows read once: the leaf's for
  *  ordinary help, only `focusedFlag`'s for focused help. A read that throws
  *  renders no element, the same soft failure `evalDynamic` gives a sync one. */
@@ -292,15 +293,24 @@ function paramDesc(p, leafName) {
     const repeatable = f.repeatable === true
         ? ' Repeatable — pass multiple times to accumulate.'
         : '';
+    if (f.type === 'json')
+        return `json, ${req}. One JSON value: ${outputTypePhrase(f.shape ?? { type: 'unknown', constraint: '' })}. ${f.constraint}${focusedNote}`.trim();
     return `${f.type}, ${req}.${choices}${dflt}${fileParamNote(f.type)}${fileEncodingNote(f.encoding)}${envDefaultNote(f.defaultFromEnv)} ${f.constraint}${repeatable}${focusedNote}`.trim();
 }
 /** One output shape's type phrase: `array of <element>` for an array with a
  *  declared element shape, the declared type otherwise. */
 function outputTypePhrase(shape) {
+    const nullable = /\|\s*null\s*$/i.test(shape.type);
+    const base = outputBaseType(shape.type);
+    if (base === 'union' && shape.variants !== undefined) {
+        return `${shape.variants.map(outputTypePhrase).join(' | ')}${nullable ? ' | null' : ''}`;
+    }
+    if (base === 'map' && shape.items !== undefined) {
+        return `{ [key: string]: ${outputTypePhrase(shape.items)} }${nullable ? ' | null' : ''}`;
+    }
     if (shape.items === undefined)
         return shape.type;
-    const nullable = /\|\s*null\s*$/i.test(shape.type) ? ', or null' : '';
-    return `array of ${outputTypePhrase(shape.items)}${nullable}`;
+    return `array of ${outputTypePhrase(shape.items)}${nullable ? ', or null' : ''}`;
 }
 /** The values sentence of an enum shape, or nothing. */
 function outputValuesNote(shape) {
@@ -322,16 +332,27 @@ function renderOutputShapeBody(shape, indent, lines) {
     if (shape.children !== undefined && shape.children.length > 0) {
         renderOutputFields(shape.children, indent, lines);
     }
+    for (const variant of shape.variants ?? []) {
+        const note = outputValuesNote(variant);
+        lines.push(`${indent}variant: ${outputTypePhrase(variant)}.${note}${variant.constraint.length > 0 ? ` ${variant.constraint}` : ''}`);
+        renderOutputShapeBody(variant, `${indent}  `, lines);
+    }
     let item = shape.items;
+    let eachWord = outputBaseType(shape.type) === 'map' ? 'each value' : 'each element';
     while (item !== undefined) {
         const note = outputValuesNote(item);
         if (item.constraint.length > 0 || note.length > 0) {
-            lines.push(`${indent}each element: ${outputTypePhrase(item)}.${note}${item.constraint.length > 0 ? ` ${item.constraint}` : ''}`);
+            lines.push(`${indent}${eachWord}: ${outputTypePhrase(item)}.${note}${item.constraint.length > 0 ? ` ${item.constraint}` : ''}`);
+        }
+        for (const variant of item.variants ?? []) {
+            lines.push(`${indent}variant: ${outputTypePhrase(variant)}.${outputValuesNote(variant)}${variant.constraint.length > 0 ? ` ${variant.constraint}` : ''}`);
+            renderOutputShapeBody(variant, `${indent}  `, lines);
         }
         if (item.children !== undefined && item.children.length > 0) {
             renderOutputFields(item.children, indent, lines);
             return;
         }
+        eachWord = outputBaseType(item.type) === 'map' ? 'each value' : 'each element';
         item = item.items;
     }
 }
@@ -380,6 +401,10 @@ export function renderLeafArgv(h, focusedFlag) {
         const colW = maxLen(labels);
         for (let i = 0; i < params.length; i++) {
             lines.push(`  ${pad(labels[i], colW)}  ${paramDesc(params[i], h.name)}`);
+            const param = params[i];
+            if (param.kind === 'flag' && param.type === 'json' && param.shape !== undefined) {
+                renderOutputShapeBody(param.shape, `  ${' '.repeat(colW)}    `, lines);
+            }
         }
     }
     else {

package/dist/core/plugin-objects-manifest.d.ts

@@ -15,7 +15,9 @@ export declare function objectBlocksReasons(manifest: Pick<PluginManifest, 'obje
 export declare function declaresObjectBlocks(manifest: Pick<PluginManifest, 'object_kinds' | 'scopes'>): boolean;
 /** A user plugin holds a `crtr_app_` token when it is not a provider and declares kinds or scopes, or serves over HTTP. */
 export declare function needsAppToken(manifest: Pick<PluginManifest, 'object_kinds' | 'scopes' | 'provider' | 'transport'>): boolean;
-/** The space-joined path of every leaf below the plugin's root command (`page read` for plugin `search`'s leaf `search page read`). */
-export declare function leafPathsBelowRoot(name: string, roots: ReadonlyArray<DeclNode<DeclLeaf>>): Set<string>;
+/** A provider leaf's tool path from its full command path (root first): root-relative when the bundle has one root command, else as declared. The one rule `providerLeaves` dispatches by and the object-kind gate validates against. */
+export declare function providerToolPath(rootCount: number, path: readonly string[]): string;
+/** The space-joined path of every leaf below the plugin's root command (`page read` for plugin `search`'s leaf `search page read`); for a provider bundle, every leaf's tool path (`providerToolPath`). */
+export declare function leafPathsBelowRoot(name: string, manifest: Pick<PluginManifest, 'provider'>, roots: ReadonlyArray<DeclNode<DeclLeaf>>): Set<string>;
 /** The leaves of `leafPathsBelowRoot` that declare `rest.streaming: true`. */
-export declare function streamingLeafPathsBelowRoot(name: string, roots: ReadonlyArray<DeclNode<DeclLeaf>>): Set<string>;
+export declare function streamingLeafPathsBelowRoot(name: string, manifest: Pick<PluginManifest, 'provider'>, roots: ReadonlyArray<DeclNode<DeclLeaf>>): Set<string>;

package/dist/core/plugin-objects-manifest.js

@@ -49,28 +49,38 @@ export function needsAppToken(manifest) {
         return false;
     return Object.keys(manifest.object_kinds ?? {}).length > 0 || (manifest.scopes?.length ?? 0) > 0 || manifest.transport?.kind === 'http';
 }
-/** The space-joined path of every leaf below the plugin's root command (`page read` for plugin `search`'s leaf `search page read`). */
-export function leafPathsBelowRoot(name, roots) {
-    return collectLeafPaths(name, roots, () => true);
+/** A provider leaf's tool path from its full command path (root first): root-relative when the bundle has one root command, else as declared. The one rule `providerLeaves` dispatches by and the object-kind gate validates against. */
+export function providerToolPath(rootCount, path) {
+    return (rootCount === 1 ? path.slice(1) : path).join(' ');
+}
+/** The space-joined path of every leaf below the plugin's root command (`page read` for plugin `search`'s leaf `search page read`); for a provider bundle, every leaf's tool path (`providerToolPath`). */
+export function leafPathsBelowRoot(name, manifest, roots) {
+    return collectLeafPaths(name, manifest, roots, () => true);
 }
 /** The leaves of `leafPathsBelowRoot` that declare `rest.streaming: true`. */
-export function streamingLeafPathsBelowRoot(name, roots) {
-    return collectLeafPaths(name, roots, (leaf) => 'rest' in leaf && leaf.rest.streaming === true);
+export function streamingLeafPathsBelowRoot(name, manifest, roots) {
+    return collectLeafPaths(name, manifest, roots, (leaf) => 'rest' in leaf && leaf.rest.streaming === true);
 }
-function collectLeafPaths(name, roots, include) {
+function collectLeafPaths(name, manifest, roots, include) {
+    const provider = manifest.provider !== undefined;
     const leafPaths = new Set();
     const walk = (node, prefix) => {
         if (node.kind === 'leaf') {
             if (include(node))
-                leafPaths.add([...prefix, node.name].join(' '));
+                leafPaths.add(provider ? providerToolPath(roots.length, [...prefix, node.name]) : [...prefix, node.name].join(' '));
         }
         else
             for (const child of node.children)
                 walk(child, [...prefix, node.name]);
     };
-    for (const root of roots)
-        if (root.name === name && root.kind === 'branch')
+    for (const root of roots) {
+        if (root.kind !== 'branch' || (!provider && root.name !== name))
+            continue;
+        if (provider)
+            walk(root, []);
+        else
             for (const child of root.children)
                 walk(child, []);
+    }
     return leafPaths;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/api",
-  "version": "0.3.518",
+  "version": "0.3.520",
   "description": "Typed crtrd /v1 API contract — DTOs, route builders, the error contract, the CrtrClient, and the command-plugin manifest format. Zero runtime dependencies.",
   "type": "module",
   "main": "./dist/api/index.js",