@martini-film/cli 0.3.0 → 0.4.0

package/dist/manifest.js

@@ -1,10 +1,37 @@
 import manifestJson from './generated/manifest.json' with { type: 'json' };
+export const TOOL_NAME_PATTERN = /^[a-z][a-z0-9_]{1,80}$/;
 export function loadManifest() {
     return manifestJson;
 }
 export function findTool(name, manifest = loadManifest()) {
     return manifest.tools.find(tool => tool.name === name);
 }
+export function compareManifests(build, server) {
+    const built = new Map(build.tools.map(tool => [tool.name, tool]));
+    const served = new Map(server.tools.map(tool => [tool.name, tool]));
+    const sorted = (names) => [...names].sort((a, b) => a.localeCompare(b));
+    return {
+        serverOnly: sorted([...served.keys()].filter(name => !built.has(name))),
+        buildOnly: sorted([...built.keys()].filter(name => !served.has(name))),
+        changed: sorted([...served.values()]
+            .filter(tool => {
+            const local = built.get(tool.name);
+            return local !== undefined && canonicalJson(local.inputSchema) !== canonicalJson(tool.inputSchema);
+        })
+            .map(tool => tool.name)),
+    };
+}
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    if (value && typeof value === 'object') {
+        const entries = Object.entries(value)
+            .filter(([, item]) => item !== undefined)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+        return `{${entries.map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson(item)}`).join(',')}}`;
+    }
+    return JSON.stringify(value) ?? 'null';
+}
 export function groupTools(tools) {
     const groups = new Map();
     for (const tool of tools) {

package/dist/manifest.js.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAOA,OAAO,YAAY,MAAM,2BAA2B,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAA;AAmD1E,MAAM,UAAU,YAAY;IAC1B,OAAO,YAAmC,CAAA;AAC5C,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,IAAY,EAAE,WAAqB,YAAY,EAAE;IACxE,OAAO,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,CAAA;AACxD,CAAC;AAGD,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAA;IACxC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAChC,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAA;QACpC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACf,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,CAAA;IACzB,CAAC;IACD,OAAO,CAAC,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;SACzB,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;SACtC,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;AAClG,CAAC;AAED,MAAM,cAAc,GAA4B;IAC9C,CAAC,sBAAsB,EAAE,UAAU,CAAC;IACpC,CAAC,4BAA4B,EAAE,YAAY,CAAC;IAC5C,CAAC,uBAAuB,EAAE,QAAQ,CAAC;IACnC,CAAC,iBAAiB,EAAE,QAAQ,CAAC;IAC7B,CAAC,kEAAkE,EAAE,UAAU,CAAC;IAChF,CAAC,mCAAmC,EAAE,OAAO,CAAC;IAC9C;QACE,0GAA0G;QAC1G,WAAW;KACZ;IACD,CAAC,yBAAyB,EAAE,SAAS,CAAC;IACtC,CAAC,4BAA4B,EAAE,SAAS,CAAC;IACzC,CAAC,6BAA6B,EAAE,QAAQ,CAAC;IACzC,CAAC,+CAA+C,EAAE,YAAY,CAAC;IAC/D,CAAC,wFAAwF,EAAE,QAAQ,CAAC;IACpG,CAAC,SAAS,EAAE,UAAU,CAAC;IACvB,CAAC,6DAA6D,EAAE,QAAQ,CAAC;IACzE,CAAC,SAAS,EAAE,SAAS,CAAC;IACtB,CAAC,SAAS,EAAE,UAAU,CAAC;CACxB,CAAA;AAED,MAAM,UAAU,OAAO,CAAC,IAAY;IAClC,KAAK,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,cAAc;QAAE,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,OAAO,KAAK,CAAA;IACnF,OAAO,OAAO,CAAA;AAChB,CAAC"}
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"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"}

package/dist/manifestCache.js

@@ -0,0 +1,196 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { cacheDir, isRunKey } from './config.js';
+export const MANIFEST_REFRESH_ENV = 'MARTINI_MANIFEST_REFRESH';
+const CACHE_FORMAT = 1;
+function digest(value, length) {
+    return createHash('sha256').update(value).digest('hex').slice(0, length);
+}
+export function keyFingerprint(apiKey) {
+    return digest(apiKey, 16);
+}
+export function credentialCachePath(kind, env, apiUrl, apiKey) {
+    return join(cacheDir(env), `${kind}-${digest(apiUrl, 12)}-${keyFingerprint(apiKey)}.json`);
+}
+export function manifestCachePath(env, apiUrl, apiKey) {
+    return credentialCachePath('manifest', env, apiUrl, apiKey);
+}
+export function refreshDisabled(env) {
+    const value = env[MANIFEST_REFRESH_ENV]?.trim().toLowerCase();
+    return value === '0' || value === 'false' || value === 'no' || value === 'off';
+}
+export function openManifest(options) {
+    const { baked, apiUrl, apiKey, env, warn } = options;
+    const now = options.now ?? Date.now;
+    const runKey = isRunKey(apiKey);
+    const cachePath = apiKey && !runKey ? manifestCachePath(env, apiUrl, apiKey) : null;
+    const fingerprint = apiKey ? keyFingerprint(apiKey) : '';
+    let cached = cachePath ? readCache(cachePath, apiUrl, fingerprint, warn) : null;
+    let bakedConfirmed = false;
+    return {
+        get state() {
+            if (cached) {
+                return {
+                    manifest: cached.manifest,
+                    source: 'cache',
+                    baked,
+                    server: cached.manifest,
+                    fetchedAt: cached.fetchedAt,
+                    cachePath,
+                };
+            }
+            return { manifest: baked, source: 'baked', baked, server: bakedConfirmed ? baked : null, cachePath };
+        },
+        async refresh({ force = false } = {}) {
+            if (runKey)
+                return 'skipped';
+            if (refreshDisabled(env)) {
+                if (force) {
+                    warn('MANIFEST_REFRESH_DISABLED', `${MANIFEST_REFRESH_ENV}=${env[MANIFEST_REFRESH_ENV]} turns refreshes off, so the tool list was not fetched. Unset it to refresh.`);
+                }
+                return 'skipped';
+            }
+            const inUse = cached ? `the cached list from ${cached.fetchedAt}` : "this build's list";
+            let answer;
+            try {
+                answer = await options.fetchManifest(force ? undefined : (cached?.manifest.hash ?? baked.hash));
+            }
+            catch (error) {
+                warn('MANIFEST_REFRESH_FAILED', `Could not refresh the tool list from ${apiUrl} (${messageOf(error)}); commands use ${inUse}.`);
+                return 'failed';
+            }
+            if (answer.notModified) {
+                if (!cached)
+                    bakedConfirmed = true;
+                return 'unchanged';
+            }
+            const manifest = usableManifest(answer.body, answer.etag);
+            if (!manifest) {
+                warn('MANIFEST_REFRESH_FAILED', `The server answered GET /v1/tools without a usable tool list; commands use ${inUse}.`);
+                return 'failed';
+            }
+            cached = {
+                format: CACHE_FORMAT,
+                apiUrl,
+                keyFingerprint: fingerprint,
+                fetchedAt: new Date(now()).toISOString(),
+                manifest,
+            };
+            if (cachePath)
+                writeCache(cachePath, cached, warn);
+            return 'updated';
+        },
+    };
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function isUsableSchema(schema, depth = 0) {
+    if (!isRecord(schema))
+        return false;
+    if (depth > 16)
+        return true;
+    const { properties, required, items, additionalProperties } = schema;
+    if (properties !== undefined &&
+        (!isRecord(properties) || !Object.values(properties).every(child => isUsableSchema(child, depth + 1))))
+        return false;
+    if (required !== undefined && (!Array.isArray(required) || !required.every(item => typeof item === 'string')))
+        return false;
+    if (items !== undefined && !isUsableSchema(items, depth + 1))
+        return false;
+    if (isRecord(additionalProperties) && !isUsableSchema(additionalProperties, depth + 1))
+        return false;
+    for (const key of ['anyOf', 'oneOf', 'allOf']) {
+        const variants = schema[key];
+        if (variants !== undefined &&
+            (!Array.isArray(variants) || !variants.every(child => isUsableSchema(child, depth + 1))))
+            return false;
+    }
+    return true;
+}
+function isUsableTool(tool) {
+    if (!isRecord(tool) || typeof tool.name !== 'string' || typeof tool.description !== 'string')
+        return false;
+    if (!isRecord(tool.annotations))
+        return false;
+    return isUsableSchema(tool.inputSchema);
+}
+function usableManifest(body, etag) {
+    if (!isRecord(body))
+        return null;
+    const hash = typeof body.hash === 'string' && body.hash ? body.hash : etag;
+    if (!hash || !Array.isArray(body.tools) || body.tools.length === 0 || !body.tools.every(isUsableTool))
+        return null;
+    return {
+        version: 1,
+        hash,
+        generatedAt: typeof body.generatedAt === 'string' ? body.generatedAt : '',
+        tools: body.tools,
+    };
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function readCache(path, apiUrl, fingerprint, warn) {
+    let text;
+    try {
+        text = readFileSync(path, 'utf8');
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'ENOENT' || code === 'ENOTDIR')
+            return null;
+        warn('MANIFEST_CACHE_IGNORED', `Could not read the cached tool list ${path} (${messageOf(error)}); commands use this build's list.`);
+        return null;
+    }
+    let entry;
+    try {
+        entry = JSON.parse(text);
+    }
+    catch {
+        entry = null;
+    }
+    if (isRecord(entry) && entry.format !== undefined && entry.format !== CACHE_FORMAT)
+        return null;
+    const manifest = isRecord(entry) ? usableManifest(entry.manifest, null) : null;
+    if (!isRecord(entry) ||
+        !manifest ||
+        entry.apiUrl !== apiUrl ||
+        entry.keyFingerprint !== fingerprint ||
+        typeof entry.fetchedAt !== 'string') {
+        try {
+            rmSync(path, { force: true });
+        }
+        catch {
+        }
+        warn('MANIFEST_CACHE_IGNORED', `The cached tool list ${path} was not valid and has been removed; commands use this build's list until the next refresh.`);
+        return null;
+    }
+    return { format: CACHE_FORMAT, apiUrl, keyFingerprint: fingerprint, fetchedAt: entry.fetchedAt, manifest };
+}
+export function writePrivateFileAtomic(path, text) {
+    const temp = `${path}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
+    try {
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        writeFileSync(temp, text, { mode: 0o600 });
+        renameSync(temp, path);
+    }
+    catch (error) {
+        try {
+            rmSync(temp, { force: true });
+        }
+        catch {
+        }
+        throw error;
+    }
+}
+function writeCache(path, entry, warn) {
+    try {
+        writePrivateFileAtomic(path, JSON.stringify(entry));
+    }
+    catch (error) {
+        warn('MANIFEST_CACHE_WRITE_FAILED', `Could not save the tool list to ${path} (${messageOf(error)}); only this command uses it.`);
+    }
+}
+//# sourceMappingURL=manifestCache.js.map

package/dist/manifestCache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifestCache.js","sourceRoot":"","sources":["../src/manifestCache.ts"],"names":[],"mappings":"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"}

package/dist/output.js

@@ -1,5 +1,6 @@
 import { writeFileSync } from 'node:fs';
-import { CliApiError } from './api.js';
+import { extname } from 'node:path';
+import { CliApiError, isMediaBlock as isMediaContentBlock } from './api.js';
 import { ArgumentError } from './schema.js';
 import { WaitTimeoutError } from './wait.js';
 export const EXIT = {
@@ -19,11 +20,17 @@ function writeError(options, text) {
     (options.stderr ?? (line => process.stderr.write(line)))(text);
 }
 export function printResult(value, options = {}) {
+    if (options.out && isMediaOutPath(options.out)) {
+        const { out, ...rest } = options;
+        printWarning('OUT_NOT_MEDIA', `This result is JSON, not media, so nothing was written to ${out}; it is printed here.`, rest);
+        printResult(value, rest);
+        return;
+    }
     if (options.out) {
         const text = typeof value === 'string' ? value : JSON.stringify(value, null, 2) + '\n';
         writeFileSync(options.out, text);
-        if (!options.quiet)
-            write(options, `${summarize(value)} → ${options.out}\n`);
+        const { out: _out, ...receiptOptions } = options;
+        printResult({ path: options.out, bytes: Buffer.byteLength(text), summary: summarize(value) }, receiptOptions);
         return;
     }
     if (options.quiet)
@@ -36,7 +43,43 @@ export function printResult(value, options = {}) {
     const printable = withoutMediaBytes(value);
     write(options, (tty ? JSON.stringify(printable, null, 2) : JSON.stringify(printable)) + '\n');
 }
-export const MEDIA_BYTES_HINT = 'The bytes are not printed. Write them with --out <path> plus --raw (a result with one media block) or --out-dir <dir> (every block, read-only tools); --out <path> alone writes this JSON with the base64 kept.';
+export const MEDIA_BYTES_HINT = 'The bytes are not printed. Save them with --out <file.jpg|.png|.webp|.mp3|.wav> (a result with one media block; --raw does the same for any file name) or --out-dir <dir> (every block, read-only tools); --out <file.json> writes this JSON with the base64 kept.';
+export const MEDIA_EXTENSIONS = {
+    'image/jpeg': 'jpg',
+    'image/png': 'png',
+    'image/webp': 'webp',
+    'audio/mpeg': 'mp3',
+    'audio/wav': 'wav',
+};
+const MEDIA_OUT_EXTENSIONS = new Set([
+    'jpg',
+    'jpeg',
+    'png',
+    'webp',
+    'gif',
+    'mp3',
+    'wav',
+    'm4a',
+    'aac',
+    'flac',
+    'ogg',
+    'mp4',
+    'mov',
+    'webm',
+]);
+function extensionOf(path) {
+    return extname(path).slice(1).toLowerCase();
+}
+export function isMediaOutPath(path) {
+    return MEDIA_OUT_EXTENSIONS.has(extensionOf(path));
+}
+export function mismatchedExtension(path, contentType) {
+    const expected = MEDIA_EXTENSIONS[contentType.split(';')[0].trim().toLowerCase()];
+    const actual = extensionOf(path);
+    if (!expected || !MEDIA_OUT_EXTENSIONS.has(actual))
+        return null;
+    return actual === expected || (expected === 'jpg' && actual === 'jpeg') ? null : expected;
+}
 function isMediaBlock(block) {
     return block !== null && typeof block === 'object' && typeof block.data === 'string';
 }
@@ -61,6 +104,11 @@ function withoutMediaBytes(value) {
             : block),
     };
 }
+export function noteMediaStubs(blocks, options = {}) {
+    if (blocks.some(block => isMediaContentBlock(block) && !('data' in block))) {
+        printWarning('MEDIA_NOT_PRINTED', MEDIA_BYTES_HINT, options);
+    }
+}
 export function assertRawDestination(options) {
     if (options.out)
         return;
@@ -71,8 +119,19 @@ export function assertRawDestination(options) {
 export function printBytes(bytes, options) {
     if (options.out) {
         writeFileSync(options.out, bytes);
-        if (!options.quiet)
-            write(options, `${bytes.byteLength} bytes${options.contentType ? ` (${options.contentType})` : ''} → ${options.out}\n`);
+        const expected = options.contentType ? mismatchedExtension(options.out, options.contentType) : null;
+        if (expected) {
+            printWarning('EXTENSION_MISMATCH', `${options.out} holds ${options.contentType} bytes; a viewer that trusts the extension may refuse it. Name the file .${expected}.`, options);
+        }
+        const { out: _out, contentType, meta, fields, ...receiptOptions } = options;
+        const receipt = {
+            path: options.out,
+            bytes: bytes.byteLength,
+            ...(contentType ? { contentType } : {}),
+            ...(meta !== null && meta !== undefined ? { result: meta } : {}),
+        };
+        const trimmed = fields?.length ? selectFields(receipt, fields) : receipt;
+        printResult(fields?.length && isEmptyProjection(trimmed) ? receipt : trimmed, receiptOptions);
         return;
     }
     assertRawDestination(options);
@@ -83,21 +142,121 @@ export function printWarning(code, message, options = {}) {
         return;
     writeError(options, JSON.stringify({ warning: { code, message } }) + '\n');
 }
-export function warnNoFieldsMatched(result, fields, options = {}, knownFields = []) {
-    if (fields.length === 0 || options.quiet)
-        return;
-    const empty = result !== null && typeof result === 'object' && Object.keys(result).length === 0;
-    if (!empty)
-        return;
+export function isEmptyProjection(result) {
+    if (result === null || typeof result !== 'object')
+        return false;
+    return Object.keys(result).length === 0 || !holdsValue(result);
+}
+export function unmatchedFields(result, fields) {
+    return fields.filter(path => !holdsValue(project(result, path.split('.'))));
+}
+function holdsValue(value) {
+    if (value === undefined)
+        return false;
+    if (Array.isArray(value))
+        return value.length === 0 || value.some(item => item !== null && holdsValue(item));
+    if (value !== null && typeof value === 'object') {
+        const values = Object.values(value);
+        return values.length === 0 || values.some(holdsValue);
+    }
+    return true;
+}
+export function noFieldsMatchedMessage(fields, knownFields = []) {
     const shape = knownFields.length
-        ? `The result's top-level fields are: ${knownFields.join(', ')} (martini <tool> --help lists the nested ones).`
+        ? `The result's top-level fields are: ${knownFields.join(', ')} (--help on this command lists the nested ones).`
         : 'Run once without --fields to see the shape.';
-    writeError(options, JSON.stringify({
-        warning: {
-            code: 'NO_FIELDS_MATCHED',
-            message: `--fields ${fields.join(',')} matched nothing in the result. Paths are dotted and case-sensitive (asset.imageUrl, nodes.nodeId). ${shape}`,
-        },
-    }) + '\n');
+    return `--fields ${fields.join(',')} matched nothing in the result. Paths are dotted and case-sensitive (asset.imageUrl, nodes.nodeId); a field that is a map keyed by id takes a * step, quoted for the shell ('assets.*.status'). ${shape}`;
+}
+export function warnUnmatchedFields(result, fields, options = {}, schema) {
+    if (fields.length < 2)
+        return;
+    const unmatched = unmatchedFields(result, fields);
+    const missing = unmatched.filter(path => !isDeclaredPath(path, schema));
+    if (missing.length === 0 || unmatched.length === fields.length)
+        return;
+    printWarning('FIELDS_NOT_FOUND', `--fields ${missing.join(',')} matched nothing in the result; the other paths are printed. Check the spelling; --help on this command lists the result fields it declares.`, options);
+}
+function walkMapPath(path, schema) {
+    const out = [];
+    const everyRecord = [];
+    let undeclaredMapStep = false;
+    let node = schema;
+    for (const segment of path.split('.')) {
+        while (node && node.type === 'array' && node.items)
+            node = node.items;
+        if (node && segment !== '*' && isIdKeyedMap(node)) {
+            let values = node.additionalProperties;
+            while (values && values.type === 'array' && values.items)
+                values = values.items;
+            everyRecord.push('*');
+            if (values?.properties?.[segment] === undefined) {
+                undeclaredMapStep = true;
+                out.push(segment);
+                everyRecord.push(segment);
+                node = values;
+                continue;
+            }
+            out.push('*');
+            node = values;
+        }
+        out.push(segment);
+        everyRecord.push(segment);
+        if (!node)
+            continue;
+        node =
+            segment === '*'
+                ? typeof node.additionalProperties === 'object'
+                    ? node.additionalProperties
+                    : undefined
+                : node.properties?.[segment];
+    }
+    return { path: out.join('.'), everyRecord: everyRecord.join('.'), undeclaredMapStep };
+}
+export function expandMapPaths(paths, schema) {
+    if (!schema)
+        return [...paths];
+    return paths.map(path => walkMapPath(path, schema).path);
+}
+export function hasUndeclaredMapStep(paths, schema) {
+    return schema !== undefined && paths.some(path => walkMapPath(path, schema).undeclaredMapStep);
+}
+export function resolveMapPaths(result, paths, schema) {
+    if (!schema)
+        return [...paths];
+    return paths.map(path => {
+        const walked = walkMapPath(path, schema);
+        if (!walked.undeclaredMapStep)
+            return walked.path;
+        return isEmptyProjection(selectFields(result, [walked.path])) ? walked.everyRecord : walked.path;
+    });
+}
+export function isDeclaredPath(path, schema) {
+    let node = schema;
+    for (const segment of path.split('.')) {
+        while (node && node.type === 'array' && node.items)
+            node = node.items;
+        if (!node)
+            return false;
+        const variants = node.anyOf ?? node.oneOf ?? [node];
+        const next = variants
+            .map((variant) => {
+            if (segment === '*')
+                return typeof variant.additionalProperties === 'object' ? variant.additionalProperties : undefined;
+            return variant.properties?.[segment];
+        })
+            .find(found => found !== undefined);
+        if (next === undefined)
+            return false;
+        node = next;
+    }
+    return true;
+}
+function isIdKeyedMap(schema) {
+    const values = schema.additionalProperties;
+    return (Object.keys(schema.properties ?? {}).length === 0 &&
+        values !== null &&
+        typeof values === 'object' &&
+        Object.keys(values.properties ?? {}).length > 0);
 }
 export function selectFields(value, paths) {
     if (paths.length === 0)
@@ -128,13 +287,20 @@ function project(value, segments) {
             }
             return Object.keys(out).length ? out : undefined;
         }
-        if (!Object.prototype.hasOwnProperty.call(value, head))
-            return undefined;
+        if (!Object.prototype.hasOwnProperty.call(value, head)) {
+            return isIdKeyedData(value) ? project(value, ['*', ...segments]) : undefined;
+        }
         const inner = project(value[head], rest);
         return inner === undefined ? undefined : { [head]: inner };
     }
     return undefined;
 }
+const ID_KEY = /^(?:[a-z]+-)?[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i;
+function isIdKeyedData(value) {
+    const entries = Object.entries(value);
+    return (entries.length > 0 &&
+        entries.every(([key, item]) => ID_KEY.test(key) && item !== null && typeof item === 'object' && !Array.isArray(item)));
+}
 function merge(a, b) {
     if (a === undefined)
         return b;
@@ -179,7 +345,11 @@ export function exitCodeFor(error) {
             /^(INVALID_API_KEY|API_KEY_REVOKED|API_KEY_EXPIRED|API_KEY_DEFAULTS_MISSING)$/.test(error.code)) {
             return EXIT.auth;
         }
-        if (error.code === 'INSUFFICIENT_CREDITS' || error.code === 'INSUFFICIENT_OLIVES' || error.status === 402) {
+        if (error.code === 'INSUFFICIENT_CREDITS' ||
+            error.code === 'INSUFFICIENT_OLIVES' ||
+            error.status === 402 ||
+            error.code === 'PLAN_OVER_BUDGET' ||
+            error.code === 'PLAN_UNPRICED') {
             return EXIT.insufficientCredits;
         }
         if (/_NOT_READY$/.test(error.code) ||
@@ -187,7 +357,10 @@ export function exitCodeFor(error) {
             error.code === 'RUN_NOT_ACTIVE' ||
             error.code === 'LOGIN_PENDING')
             return EXIT.notReady;
-        if (error.code === 'INVALID_ARGUMENTS' || error.code === 'INVALID_REQUEST' || error.code === 'TOOL_NOT_FOUND') {
+        if (error.code === 'INVALID_ARGUMENTS' ||
+            error.code === 'INVALID_REQUEST' ||
+            error.code === 'TOOL_NOT_FOUND' ||
+            error.code === 'NO_FIELDS_MATCHED') {
             return EXIT.usage;
         }
         return EXIT.toolError;
@@ -196,6 +369,8 @@ export function exitCodeFor(error) {
 }
 const RUN_CREDENTIAL_GONE_HINT = 'This execution’s run credential is expired or revoked. Stop and report it; do not run martini login. Retrying or resuming the run provisions a new one.';
 export function hintFor(error, context = {}) {
+    if (error instanceof CliApiError && error.hint)
+        return error.hint;
     if (error instanceof WaitTimeoutError) {
         return `Still running; nothing was lost. Resume with: ${error.resumeCommand()} — give --timeout the seconds your shell step allows (a video generation takes minutes).`;
     }
@@ -224,6 +399,10 @@ export function hintFor(error, context = {}) {
                     : 'Run keys work only while their workflow run is executing.';
             case 'INSUFFICIENT_CREDITS':
                 return 'Top up olives in Martini, or lower the batch.';
+            case 'PLAN_OVER_BUDGET':
+                return 'The quote is on stdout. Ask the person before raising --max-olives, or make the batch smaller.';
+            case 'NO_FIELDS_MATCHED':
+                return 'Nothing was changed; run the command again with paths the result has.';
             case 'FFPROBE_MISSING':
                 return 'Install ffmpeg (it ships ffprobe) and make sure it is on PATH.';
             default:
@@ -232,12 +411,17 @@ export function hintFor(error, context = {}) {
                 return undefined;
         }
     }
-    if (error instanceof ArgumentError)
-        return 'Run martini <command> --help.';
+    if (error instanceof ArgumentError) {
+        return error.hint ?? (context.command ? `Run martini ${context.command} --help.` : 'Run martini --help.');
+    }
     return undefined;
 }
 export function printError(error, options = {}) {
     const code = exitCodeFor(error);
+    const hint = hintFor(error, {
+        inRun: options.inRun ?? false,
+        ...(options.command ? { command: options.command } : {}),
+    });
     const payload = {
         error: {
             code: error instanceof CliApiError ? error.code : error instanceof ArgumentError ? 'USAGE' : 'CLI_ERROR',
@@ -245,9 +429,7 @@ export function printError(error, options = {}) {
             ...(error instanceof CliApiError && error.tool ? { tool: error.tool } : {}),
             ...(error instanceof WaitTimeoutError ? { pending: error.pending } : {}),
             ...(error instanceof WaitTimeoutError && error.settled.length ? { settled: error.settled } : {}),
-            ...(hintFor(error, { inRun: options.inRun ?? false })
-                ? { hint: hintFor(error, { inRun: options.inRun ?? false }) }
-                : {}),
+            ...(hint ? { hint } : {}),
             exitCode: code,
         },
     };