@martini-film/cli 0.3.0 → 0.4.1

package/dist/help.js

@@ -1,7 +1,7 @@
 import { CLI_VERSION } from './api.js';
 import { approvalSupport } from './approve.js';
 import { groupTools } from './manifest.js';
-import { flagSpecs, kebab } from './schema.js';
+import { cliArgumentDefault, flagSpecs, kebab, propertySchema, withoutNull } from './schema.js';
 export const SUPERSEDED_BY_COMPOUND = {
     upload_assets_prepare: 'upload',
     upload_assets_complete: 'upload',
@@ -9,13 +9,31 @@ export const SUPERSEDED_BY_COMPOUND = {
     get_asset_download_url: 'download',
 };
 const CONTEXT_PROPERTIES = ['projectId', 'canvasId', 'runId'];
+export const MEDIA_RESULT_TOOLS = new Set([
+    'view_asset',
+    'view_library_asset',
+    'inspect_video',
+    'render_timeline_frame',
+    'inspect_timeline_artifact',
+    'get_timeline_audio_report',
+    'extract_video_frame',
+]);
+const COMPACT_FLAGS_OVER = 12;
+const RESULT_FIELD_DEFAULT_LINES = 30;
 export const GLOBAL_FLAGS = [
     [
         '--fields a,b.c',
-        'keep only these dotted paths of the result (on the server; in the CLI after a wait or when a segment is * — assets.*.status steps into an id-keyed map); a tool argument named like a global flag is spelled --tool-<name> (--tool-fields)',
+        "keep only these dotted paths of the result (on the server; in the CLI after a wait or when a segment is *); an id-keyed map is stepped into by its records' field (assets.status), so a * step is rarely needed — quote it when you write one ('assets.*.status'), or the shell expands it; a tool argument named like a global flag is spelled --tool-<name> (--tool-fields)",
     ],
-    ['--out-dir <dir>', 'write each media block to its own file'],
-    ['--out <path>', 'write the result (or media bytes) to a file; print one summary line'],
+    [
+        '--out-dir <dir>',
+        'write each media block to its own file, in result order, named by the asset its text block names',
+    ],
+    [
+        '--out <path>',
+        'write the result to a file and print a one-line JSON receipt; a media extension (.jpg .png .webp .mp3 .wav) writes the media bytes of a one-media result (view_asset, render_timeline_frame)',
+    ],
+    ['--raw', 'with --out or a pipe: the media bytes of a one-media result, whatever the file is called'],
     [
         '--args <object|@file>',
         'pass the whole arguments object as JSON instead of flags (tools only; --json is an alias unless the tool has an argument named json)',
@@ -34,19 +52,30 @@ export const GLOBAL_FLAGS = [
     ],
     [
         '--project / --canvas / --run <id>',
-        'context defaults for projectId / canvasId / runId (--project-id, --canvas-id, --run-id mean the same); --no-context sends only what you typed',
+        'projectId / canvasId / runId for this command (--project-id, --canvas-id, --run-id mean the same); martini use <project> sets the first two once for the directory',
+    ],
+    [
+        '--no-context',
+        'send only what you typed: no projectId / canvasId / runId from martini use, the environment, or the profile (martini call sends none unless given --context)',
     ],
     [
         '--api-key / --api-url / --profile',
         'credential and endpoint overrides (else env, .martini/config.json, ~/.config/martini/config.json)',
     ],
     ['--quiet', 'print nothing on success'],
+    [
+        '--schema [<flag>] [--keys]',
+        "on a tool: print that argument's JSON Schema (no flag: the whole input schema) and exit; --keys prints one line per key instead (name, type, first sentence); needs no key, sends nothing",
+    ],
+    ['--help [--all]', 'on a tool: its flags, result fields, and examples; --all prints every description in full'],
 ];
+export const EXIT_CODES_LINE = 'Exit codes: 0 done, all of it · 1 tool error · 2 usage · 3 auth · 4 not ready or timed out · 5 over budget (olives, or a quote over --max-olives)';
 export function renderHelp(manifest, compounds) {
     const lines = [];
     lines.push(`martini ${CLI_VERSION} — the Martini CLI for agents and scripts`);
     lines.push('');
     lines.push('Usage: martini <command> [flags]        martini <command> --help');
+    lines.push('Start with martini guide: the operator rules, once per session (martini guide <topic> for one topic).');
     lines.push('');
     lines.push('Commands (what no single tool does):');
     for (const command of compounds)
@@ -75,14 +104,17 @@ export function renderHelp(manifest, compounds) {
     for (const [flag, description] of GLOBAL_FLAGS)
         lines.push(`  ${flag.padEnd(36)} ${description}`);
     lines.push('');
-    lines.push('Output: JSON on stdout (compact when piped). Errors: one JSON object on stderr.');
-    lines.push('Exit codes: 0 ok · 1 tool error · 2 usage · 3 auth · 4 not ready or timed out · 5 insufficient olives');
+    lines.push('Output: JSON on stdout (compact when piped); guide, init without --write, files cat, and --help print text. Errors: one JSON object on stderr; a command that did part of its work prints that part on stdout as well.');
+    lines.push(EXIT_CODES_LINE);
     lines.push('Docs: https://www.martini.film/docs/cli');
     return lines.join('\n') + '\n';
 }
-function describeFlag(spec) {
+function describeFlag(tool, spec) {
     const type = spec.kind === 'array'
-        ? `${spec.items ?? 'string'}[] (values after the flag, a repeated flag, or a JSON list)`
+        ? spec.items === 'object' || spec.items === 'json'
+            ?
+                `${spec.items ?? 'string'}[] (each value after the flag is one element: --${spec.flag} '{…}' '{…}'; or one JSON list, or @file holding one)`
+            : `${spec.items ?? 'string'}[] (values after the flag, a repeated flag, or a JSON list)`
         : spec.kind === 'object' || spec.kind === 'json'
             ? spec.acceptsString
                 ? 'JSON or text'
@@ -95,8 +127,86 @@ function describeFlag(spec) {
     const values = spec.enum ?? spec.itemEnum;
     if (values)
         parts.push(`${spec.itemEnum ? 'each ' : ''}one of: ${values.map(value => JSON.stringify(value)).join(', ')}`);
+    const cliDefault = cliArgumentDefault(tool, spec.property);
+    if (cliDefault !== undefined)
+        parts.push(`(the CLI sends ${JSON.stringify(cliDefault)} unless you pass one)`);
+    if (takesJson(spec))
+        parts.push(`(martini ${tool.name} --schema ${spec.flag})`);
     return parts.join('  ');
 }
+export function firstSentence(text, max = 100) {
+    const flat = text.replace(/\s+/g, ' ').trim();
+    const end = flat.search(/(?<!\b(?:e\.g|i\.e|e|i|vs|etc))(?<!\d)[.!?](?=\s|$)/);
+    const sentence = end >= 0 ? flat.slice(0, end + 1) : flat;
+    return sentence.length > max ? `${sentence.slice(0, max - 1).trimEnd()}…` : sentence;
+}
+function flagType(spec) {
+    if (spec.kind === 'array')
+        return `${spec.items ?? 'string'}[]`;
+    if (spec.kind === 'object' || spec.kind === 'json')
+        return spec.acceptsString ? 'JSON or text' : 'JSON';
+    return spec.kind;
+}
+function briefFlag(spec, tool) {
+    const values = spec.enum ?? spec.itemEnum;
+    const choice = values && values.length <= 6 ? `  one of: ${values.map(value => JSON.stringify(value)).join(', ')}` : '';
+    const cliDefault = tool ? cliArgumentDefault(tool, spec.property) : undefined;
+    const sent = cliDefault !== undefined ? `  (the CLI sends ${JSON.stringify(cliDefault)} unless you pass one)` : '';
+    const about = spec.description ? `  ${firstSentence(spec.description)}` : '';
+    return `${`--${spec.flag}`.padEnd(30)}  ${flagType(spec)}${choice}${sent}${about}`;
+}
+export function schemaKeyLines(raw, what) {
+    const { schema } = withoutNull(raw);
+    const type = typeOf(schema);
+    const variants = unionVariants(schema);
+    if (variants) {
+        return variants.flatMap((variant, index) => [
+            ...(index > 0 ? [''] : []),
+            ...schemaKeyLines(variant, `${what}, variant ${index + 1} of ${variants.length}`),
+        ]);
+    }
+    if (type === 'array' && schema.items)
+        return schemaKeyLines(schema.items, `${what} (each element)`);
+    const properties = Object.entries(schema.properties ?? {});
+    if (type !== 'object' || properties.length === 0) {
+        return [
+            `${what}: ${variantSummary(schema)}${schema.description ? ` — ${firstSentence(schema.description, 160)}` : ''}`,
+        ];
+    }
+    const required = new Set(schema.required ?? []);
+    const names = properties.map(([name]) => `${name}${required.has(name) ? '*' : ''}`);
+    const kinds = properties.map(([, value]) => keyType(value));
+    const nameWidth = Math.min(32, Math.max(...names.map(name => name.length)));
+    const kindWidth = Math.min(28, Math.max(...kinds.map(kind => kind.length)));
+    return [
+        `${what}: ${properties.length} key${properties.length === 1 ? '' : 's'} (* required)`,
+        ...properties.map(([, value], index) => {
+            const about = value.description ? firstSentence(value.description, 110) : '';
+            return `  ${names[index].padEnd(nameWidth)}  ${kinds[index].padEnd(kindWidth)}${about ? `  ${about}` : ''}`.trimEnd();
+        }),
+    ];
+}
+function keyType(raw) {
+    const { schema, nullable } = withoutNull(raw);
+    const summary = (() => {
+        if ('const' in schema)
+            return JSON.stringify(schema.const);
+        if (schema.enum?.length) {
+            const listedValues = listed(schema.enum.map(value => JSON.stringify(value)));
+            return listedValues.length <= 48 ? listedValues : 'string (enum)';
+        }
+        const type = typeOf(schema);
+        if (type === 'array')
+            return `${(schema.items && typeOf(withoutNull(schema.items).schema)) ?? 'any'}[]`;
+        return type ?? (unionVariants(schema) ? 'union' : 'any');
+    })();
+    return nullable ? `${summary}?` : summary;
+}
+function takesJson(spec) {
+    return (spec.kind === 'object' ||
+        spec.kind === 'json' ||
+        (spec.kind === 'array' && (spec.items === 'object' || spec.items === 'json')));
+}
 function shadowNote(tool, spec, shadows) {
     const scalar = (kind) => kind === 'number' || kind === 'integer' ? '1' : kind === 'boolean' ? 'true' : kind === 'string' ? '"…"' : '{…}';
     const sample = spec.kind === 'array' ? `[${scalar(spec.items === 'json' ? 'string' : spec.items)}]` : scalar(spec.kind);
@@ -107,9 +217,11 @@ function shadowNote(tool, spec, shadows) {
         `  martini ${tool.name} --args '{"${spec.property}": ${sample}}'`,
     ];
 }
-export function renderToolHelp(tool) {
+export function renderToolHelp(tool, options = {}) {
     const specs = flagSpecs(tool);
     const lines = [];
+    const compact = !options.all && specs.length > COMPACT_FLAGS_OVER;
+    const shortened = [];
     lines.push(`martini ${tool.name}${tool.title ? ` — ${tool.title}` : ''}`);
     lines.push('');
     lines.push(wrap(tool.description, 100));
@@ -128,21 +240,41 @@ export function renderToolHelp(tool) {
     lines.push('Flags:');
     if (specs.length === 0)
         lines.push('  (no arguments)');
+    const brief = compact ? specs.filter(spec => !spec.required) : [];
     for (const spec of specs) {
-        lines.push(`  ${describeFlag(spec)}`);
+        if (brief.includes(spec))
+            continue;
+        lines.push(`  ${describeFlag(tool, spec)}`);
         if (spec.description)
             lines.push(`      ${wrap(spec.description, 96).split('\n').join('\n      ')}`);
+        for (const line of shapeLines(propertySchema(tool, spec.property))) {
+            lines.push(`      ${wrap(line, 94).split('\n').join('\n        ')}`);
+        }
         if (spec.shadows)
             for (const line of shadowNote(tool, spec, spec.shadows))
                 lines.push(`      ${line}`);
     }
+    if (brief.length > 0) {
+        lines.push('');
+        lines.push(`Optional flags (${brief.length}; one line each):`);
+        for (const spec of brief)
+            lines.push(`  ${briefFlag(spec, tool)}`);
+        shortened.push('every optional flag in full');
+    }
+    const rules = ruleLines(tool, specs);
+    if (rules.length > 0) {
+        lines.push('');
+        lines.push('Rules:');
+        for (const line of rules)
+            lines.push(`  ${line}`);
+    }
     const properties = tool.inputSchema.properties ?? {};
     const contextual = CONTEXT_PROPERTIES.filter(property => property in properties);
     if (contextual.length > 0) {
         lines.push('');
         lines.push(wrap(`Context: ${contextual.map(property => `--${kebabOf(property)}`).join(' / ')} may be omitted; the value then comes from ${contextual
             .map(property => `--${property.replace(/Id$/, '')}`)
-            .join(' / ')}, ${contextual.map(property => `MARTINI_${property.replace(/Id$/, '').toUpperCase()}_ID`).join(' / ')}, or .martini/config.json (a Martini workflow run provides one).`, 100));
+            .join(' / ')}, ${contextual.map(property => `MARTINI_${property.replace(/Id$/, '').toUpperCase()}_ID`).join(' / ')}, or what martini use <project> set for this directory (a Martini workflow run has its own).`, 100));
     }
     const approval = approvalSupport(tool);
     if (approval) {
@@ -151,16 +283,43 @@ export function renderToolHelp(tool) {
             ? `Approval: without --${kebab(approval.argument)} the tool answers a quote (approvalNeeded: true, planHash, totalEstimatedOlives) and starts nothing. --approve --max-olives <n> takes the quote, refuses when the total is over the cap (PLAN_OVER_BUDGET, nothing started), and otherwise re-calls with the quote's planHash${approval.echoesBatchRequestId ? ', batchRequestId,' : ''} and the approval in one command; the result carries approvedPlan.`
             : `Approval: --${kebab(approval.argument)} records that the plan was approved; there is no server quote, so --approve attests and --max-olives cannot apply here (for a capped batch: create_nodes, then generate_nodes --approve --max-olives <n>).`, 100));
     }
+    if (MEDIA_RESULT_TOOLS.has(tool.name)) {
+        lines.push('');
+        lines.push('Output: the result carries media. Printed, each image or audio block is a stub (type and size). Save it:');
+        lines.push(`  martini ${tool.name} … --out <file.jpg>    one media block → that file; prints { path, bytes, contentType, result }`);
+        if (tool.annotations.readOnlyHint) {
+            lines.push(`  martini ${tool.name} … --out-dir <dir>     every block → a file each, named by its asset; prints { dir, files }`);
+        }
+        lines.push('Then open the file to look at it: nothing is shown until you do.');
+    }
     if (tool.outputSchema) {
+        const every = resultFieldLines(tool.outputSchema);
+        let depth = RESULT_FIELD_DEPTH;
+        while (!options.all &&
+            depth > 1 &&
+            resultFieldLines(tool.outputSchema, depth).length > RESULT_FIELD_DEFAULT_LINES) {
+            depth -= 1;
+        }
+        const shown = resultFieldLines(tool.outputSchema, depth);
+        const deeper = every.length - shown.length;
         lines.push('');
         lines.push('Result fields (use with --fields; the tool may return more):');
-        for (const line of resultFieldLines(tool.outputSchema))
+        for (const line of shown)
             lines.push(`  ${line}`);
+        if (deeper > 0) {
+            lines.push(`  … ${deeper} more nested field${deeper === 1 ? '' : 's'}`);
+            shortened.push('every result field');
+        }
     }
     lines.push('');
-    lines.push('Example:');
-    lines.push(`  ${exampleFor(tool, specs)}`);
+    const examples = examplesFor(tool, specs);
+    lines.push(examples.length > 1 ? 'Examples:' : 'Example:');
+    for (const example of examples)
+        lines.push(`  ${example}`);
     lines.push('');
+    if (shortened.length > 0) {
+        lines.push(wrap(`Shortened: martini ${tool.name} --help --all prints ${shortened.join(' and ')}; martini ${tool.name} --schema <flag> --keys lists one JSON argument's keys.`, 100));
+    }
     const owner = 'json' in (tool.inputSchema.properties ?? {});
     lines.push(owner
         ? 'The whole arguments object can also be given as JSON: --args \'{"...": ...}\' or --args @args.json (this tool owns --json).'
@@ -168,7 +327,7 @@ export function renderToolHelp(tool) {
     return lines.join('\n') + '\n';
 }
 const RESULT_FIELD_DEPTH = 3;
-export function resultFieldLines(schema) {
+export function resultFieldLines(schema, maxDepth = RESULT_FIELD_DEPTH) {
     const rows = [];
     const visit = (node, path, depth) => {
         const properties = node.properties ?? {};
@@ -177,7 +336,7 @@ export function resultFieldLines(schema) {
             const here = path ? `${path}.${name}` : name;
             const { kind, inner, mapped } = fieldKind(field);
             rows.push([mapped ? `${here}.*` : here, kind, describeField(field)]);
-            if (inner && depth < RESULT_FIELD_DEPTH)
+            if (inner && depth < maxDepth)
                 visit(inner, mapped ? `${here}.*` : here, depth + 1);
         }
     };
@@ -270,27 +429,225 @@ export function renderCompoundHelp(command) {
             lines.push(`  ${example}`);
         lines.push('');
     }
-    lines.push('Global flags apply too: --project / --canvas (or --project-id / --canvas-id), --fields, --out, --wait / --no-wait, --timeout, --quiet, --api-key, --profile.');
+    lines.push('Global flags apply too: --project / --canvas (or --project-id / --canvas-id; martini use sets both once), --fields, --out, --wait / --no-wait, --timeout, --quiet, --api-key, --profile.');
     return lines.join('\n') + '\n';
 }
-export function exampleFor(tool, specs = flagSpecs(tool)) {
-    const required = specs.filter(spec => spec.required && spec.property !== 'projectId' && spec.property !== 'canvasId');
+export function examplesFor(tool, specs = flagSpecs(tool)) {
+    const needed = new Set(specs.filter(spec => spec.required).map(spec => spec.property));
+    for (const [, variants] of rootRules(tool.inputSchema))
+        for (const key of variants[0].required ?? [])
+            needed.add(key);
     const parts = [`martini ${tool.name}`];
-    for (const spec of required) {
-        const sample = spec.enum?.[0] !== undefined
-            ? JSON.stringify(spec.enum[0])
-            : spec.kind === 'boolean'
-                ? ''
-                : spec.kind === 'number' || spec.kind === 'integer'
-                    ? '1'
-                    : spec.kind === 'array'
-                        ? '<id>'
-                        : spec.kind === 'object' || spec.kind === 'json'
-                            ? "'{...}'"
-                            : `<${spec.flag}>`;
-        parts.push(sample ? `--${spec.flag} ${sample}` : `--${spec.flag}`);
+    for (const spec of specs) {
+        if (!needed.has(spec.property))
+            continue;
+        if (spec.property === 'projectId')
+            parts.push('--project <project-id>');
+        else if (spec.property === 'canvasId')
+            parts.push('--canvas <canvas-id>');
+        else
+            parts.push(exampleFlag(tool, spec));
+    }
+    const first = parts.join(' ');
+    if (approvalSupport(tool)?.kind === 'quote')
+        return [`${first} --approve --max-olives 20`, first];
+    const optional = specs.find(spec => !needed.has(spec.property) && takesJson(spec) && isObjectSample(sampleFor(tool, spec)));
+    return optional ? [first, `${first} ${exampleFlag(tool, optional)}`] : [first];
+}
+function exampleFlag(tool, spec) {
+    if (takesJson(spec))
+        return `--${spec.flag} ${shellWord(JSON.stringify(sampleFor(tool, spec)))}`;
+    const sample = spec.enum?.[0] !== undefined
+        ? JSON.stringify(spec.enum[0])
+        : spec.kind === 'boolean'
+            ? ''
+            : spec.kind === 'number' || spec.kind === 'integer'
+                ? '1'
+                : spec.kind === 'array'
+                    ? spec.itemEnum?.[0] !== undefined
+                        ? JSON.stringify(spec.itemEnum[0])
+                        : spec.items === 'number' || spec.items === 'integer'
+                            ? '1'
+                            : spec.items === 'boolean'
+                                ? 'true'
+                                : '<id>'
+                    : `<${spec.flag}>`;
+    return sample ? `--${spec.flag} ${sample}` : `--${spec.flag}`;
+}
+function sampleFor(tool, spec) {
+    return sampleValue(propertySchema(tool, spec.property), spec.property, 0);
+}
+function isObjectSample(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value) && Object.keys(value).length > 0;
+}
+function shellWord(text) {
+    return /^[\w.,:@/-]+$/.test(text) ? text : `'${text.replace(/'/g, `'\\''`)}'`;
+}
+const SAMPLE_DEPTH = 2;
+function sampleValue(raw, key, depth) {
+    const { schema } = withoutNull(raw);
+    if ('const' in schema)
+        return schema.const;
+    if (schema.enum?.length)
+        return schema.enum[0];
+    const variants = unionVariants(schema);
+    if (variants) {
+        const object = variants.find(variant => typeOf(withoutNull(variant).schema) === 'object');
+        return sampleValue(object ?? variants[0], key, depth);
+    }
+    switch (typeOf(schema)) {
+        case 'string':
+            return `<${key}>`;
+        case 'number':
+        case 'integer':
+            return typeof schema.minimum === 'number' && schema.minimum > 1 ? schema.minimum : 1;
+        case 'boolean':
+            return true;
+        case 'array':
+            return schema.items ? [sampleValue(schema.items, key, depth)] : [];
+        case 'object':
+            return sampleObject(schema, depth, depth >= SAMPLE_DEPTH);
+        default:
+            return {};
     }
-    return parts.join(' ');
+}
+function sampleObject(schema, depth, requiredOnly = false) {
+    const properties = schema.properties ?? {};
+    const names = Object.keys(properties);
+    if (names.length === 0) {
+        const values = schema.additionalProperties;
+        return !requiredOnly && values && typeof values === 'object'
+            ? { '<key>': sampleValue(values, 'value', depth + 1) }
+            : {};
+    }
+    const required = (schema.required ?? []).filter(name => name in properties);
+    const keys = required.length > 0 ? required : requiredOnly ? [] : names.slice(0, 1);
+    return Object.fromEntries(keys.map(name => [name, sampleValue(properties[name], name, depth + 1)]));
+}
+const SUMMARY_KEYS = 12;
+const SUMMARY_OBJECT_KEYS = 64;
+const NESTED_SUMMARY_WIDTH = 64;
+const SUMMARY_WIDTH = 96;
+export function shapeLines(raw) {
+    const { schema } = withoutNull(raw);
+    const variants = unionVariants(schema);
+    if (variants)
+        return unionLines('one of:', variants);
+    const type = typeOf(schema);
+    if (type === 'object') {
+        const summary = objectSummary(schema);
+        return summary ? [`shape: ${summary}`] : [];
+    }
+    if (type === 'array' && schema.items) {
+        const items = withoutNull(schema.items).schema;
+        const itemVariants = unionVariants(items);
+        if (itemVariants)
+            return unionLines('each one of:', itemVariants);
+        const summary = typeOf(items) === 'object' ? objectSummary(items) : undefined;
+        return summary ? [`each: ${summary}`] : [];
+    }
+    return [];
+}
+function unionLines(label, variants) {
+    const summaries = variants.map(variantSummary);
+    const line = `${label} ${summaries.join(' | ')}`;
+    return line.length <= SUMMARY_WIDTH ? [line] : [label, ...summaries.map(summary => `  ${summary}`)];
+}
+function unionVariants(schema) {
+    const variants = (schema.anyOf ?? schema.oneOf)?.filter(variant => variant.type !== 'null' && variant.const !== null);
+    return variants && variants.length > 1 ? variants : undefined;
+}
+function typeOf(schema) {
+    return Array.isArray(schema.type) ? schema.type.find(type => type !== 'null') : schema.type;
+}
+function objectSummary(schema, nested = false) {
+    const properties = Object.entries(schema.properties ?? {});
+    if (properties.length === 0) {
+        const values = schema.additionalProperties;
+        return values && typeof values === 'object' ? `{ <key>: ${variantSummary(values)} }` : undefined;
+    }
+    const required = new Set(schema.required ?? []);
+    const ordered = [
+        ...properties.filter(([name]) => required.has(name)),
+        ...properties.filter(([name]) => !required.has(name)),
+    ];
+    const shown = ordered.slice(0, Math.max(SUMMARY_OBJECT_KEYS, required.size));
+    const keys = shown.map(([name, value]) => `${name}${required.has(name) ? '*' : ''}${fixedValue(value) || (!nested && required.has(name) ? requiredShape(value) : '')}`);
+    const more = ordered.length - shown.length;
+    return `{ ${keys.join(', ')}${more > 0 ? `, … +${more} more` : ''} }`;
+}
+function requiredShape(raw) {
+    const { schema } = withoutNull(raw);
+    const list = typeOf(schema) === 'array' && schema.items ? withoutNull(schema.items).schema : undefined;
+    const object = list ?? schema;
+    if (typeOf(object) !== 'object' || unionVariants(object))
+        return '';
+    const summary = objectSummary(object, true);
+    if (!summary || summary.length > NESTED_SUMMARY_WIDTH)
+        return '';
+    return `: ${list ? `[${summary}]` : summary}`;
+}
+function fixedValue(raw) {
+    const { schema } = withoutNull(raw);
+    if ('const' in schema)
+        return `: ${JSON.stringify(schema.const)}`;
+    return schema.enum?.length === 1 ? `: ${JSON.stringify(schema.enum[0])}` : '';
+}
+function variantSummary(raw) {
+    const { schema } = withoutNull(raw);
+    if ('const' in schema)
+        return JSON.stringify(schema.const);
+    if (schema.enum?.length)
+        return listed(schema.enum.map(value => JSON.stringify(value)));
+    const variants = unionVariants(schema);
+    if (variants)
+        return `(${listed(variants.map(variantSummary))})`;
+    const type = typeOf(schema);
+    if (type === 'object')
+        return objectSummary(schema) ?? 'object';
+    if (type === 'array')
+        return `${(schema.items && typeOf(withoutNull(schema.items).schema)) ?? 'any'}[]`;
+    return type ?? 'any';
+}
+function listed(values) {
+    const shown = values.slice(0, SUMMARY_KEYS);
+    return `${shown.join(' | ')}${values.length > shown.length ? ` | … +${values.length - shown.length} more` : ''}`;
+}
+export function ruleLines(tool, specs = flagSpecs(tool)) {
+    const flagOf = (property) => `--${specs.find(spec => spec.property === property)?.flag ?? kebab(property)}`;
+    const lines = [];
+    for (const [label, variants] of rootRules(tool.inputSchema)) {
+        const requires = variants.map(variant => (variant.required ?? []).map(flagOf).join(' and '));
+        if (variants.every(variant => onlyRequires(variant) && (variant.required?.length ?? 0) > 0)) {
+            lines.push(`${label}: ${requires.join(' | ')}`);
+            continue;
+        }
+        lines.push(`${label} these:`);
+        variants.forEach((variant, index) => {
+            const adds = Object.keys(variant.properties ?? {}).map(flagOf);
+            const needs = requires[index] ? `requires ${requires[index]}` : 'requires nothing more';
+            lines.push(`  - ${needs}${adds.length ? `; takes ${adds.join(', ')}` : ''}`);
+        });
+    }
+    return lines;
+}
+function rootRules(schema) {
+    const rules = [];
+    const collect = (node) => {
+        if (node.oneOf?.length)
+            rules.push(['Exactly one of', node.oneOf]);
+        if (node.anyOf?.length)
+            rules.push(['At least one of', node.anyOf]);
+        for (const member of node.allOf ?? [])
+            collect(member);
+    };
+    collect(schema);
+    return rules;
+}
+function onlyRequires(variant) {
+    return Object.entries(variant).every(([key, value]) => key === 'required' ||
+        key === 'description' ||
+        (key === 'not' && typeof value === 'object' && value !== null && onlyRequires(value)));
 }
 export function wrap(text, width) {
     const words = text.split(/\s+/);