@martini-film/cli 0.1.0

package/dist/help.js

@@ -0,0 +1,127 @@
+/**
+ * `--help` is written for the model that reads it: every command on one screen
+ * grouped by noun, every flag with its type and whether it is required, the
+ * tool's own description (already written for agents), and one example. Limits
+ * live in the descriptions the registry ships, so they are never restated here.
+ */
+import { CLI_VERSION } from './api.js';
+import { groupTools } from './manifest.js';
+import { flagSpecs } from './schema.js';
+export const GLOBAL_FLAGS = [
+    ['--fields a,b.c', 'keep only these dotted paths of the result (applied on the server)'],
+    ['--out <path>', 'write the result (or media bytes) to a file; print one summary line'],
+    ['--json <object|@file>', 'pass the whole arguments object as JSON instead of flags'],
+    [
+        '--wait / --no-wait',
+        'block until produced assets, renders, or runs settle (default on for single-item generation)',
+    ],
+    ['--timeout <seconds>', 'how long --wait waits before exiting 4 with the pending ids (default 50)'],
+    ['--project / --canvas / --run <id>', 'context defaults for projectId / canvasId / runId'],
+    [
+        '--api-key / --api-url / --profile',
+        'credential and endpoint overrides (else env, .martini/config.json, ~/.config/martini/config.json)',
+    ],
+    ['--quiet', 'print nothing on success'],
+];
+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('');
+    lines.push('Commands (what no single tool does):');
+    for (const command of compounds)
+        lines.push(`  ${command.name.padEnd(28)} ${command.summary}`);
+    lines.push('');
+    lines.push(`Tools (${manifest.tools.length}; each MCP tool is a command with flags derived from its arguments):`);
+    for (const { group, tools } of groupTools(manifest.tools)) {
+        lines.push(`  ${group}:`);
+        lines.push(`    ${tools.map(tool => tool.name).join('  ')}`);
+    }
+    lines.push('');
+    lines.push('Global flags:');
+    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('Docs: https://www.martini.film/docs/cli');
+    return lines.join('\n') + '\n';
+}
+function describeFlag(spec) {
+    const type = spec.kind === 'array'
+        ? `${spec.items ?? 'string'}[] (repeat the flag, or a JSON list)`
+        : spec.kind === 'object' || spec.kind === 'json'
+            ? 'JSON'
+            : spec.kind;
+    const parts = [`--${spec.flag}`.padEnd(30), `${type}${spec.required ? ', required' : ''}`];
+    if (spec.enum)
+        parts.push(`one of: ${spec.enum.map(value => JSON.stringify(value)).join(', ')}`);
+    return parts.join('  ');
+}
+export function renderToolHelp(tool) {
+    const specs = flagSpecs(tool);
+    const lines = [];
+    lines.push(`martini ${tool.name}${tool.title ? ` — ${tool.title}` : ''}`);
+    lines.push('');
+    lines.push(wrap(tool.description, 100));
+    lines.push('');
+    const facts = [
+        tool.annotations.readOnlyHint ? 'read-only' : tool.annotations.destructiveHint ? 'destructive write' : 'write',
+        tool.requiresActions ? 'needs workflows (Actions) access' : null,
+        tool.deprecated ? `deprecated${tool.deprecated.supersededBy ? `, use ${tool.deprecated.supersededBy}` : ''}` : null,
+    ].filter(Boolean);
+    lines.push(`Kind: ${facts.join('; ')}`);
+    lines.push('');
+    lines.push('Flags:');
+    if (specs.length === 0)
+        lines.push('  (no arguments)');
+    for (const spec of specs) {
+        lines.push(`  ${describeFlag(spec)}`);
+        if (spec.description)
+            lines.push(`      ${wrap(spec.description, 96).split('\n').join('\n      ')}`);
+    }
+    lines.push('');
+    lines.push('Example:');
+    lines.push(`  ${exampleFor(tool, specs)}`);
+    lines.push('');
+    lines.push('Any argument can also be given as JSON: --json \'{"...": ...}\' or --json @args.json.');
+    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');
+    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}`);
+    }
+    return parts.join(' ');
+}
+export function wrap(text, width) {
+    const words = text.split(/\s+/);
+    const lines = [];
+    let current = '';
+    for (const word of words) {
+        if ((current + ' ' + word).trim().length > width && current) {
+            lines.push(current);
+            current = word;
+        }
+        else {
+            current = current ? `${current} ${word}` : word;
+        }
+    }
+    if (current)
+        lines.push(current);
+    return lines.join('\n');
+}
+//# sourceMappingURL=help.js.map

package/dist/help.js.map

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

package/dist/host.js

@@ -0,0 +1,30 @@
+/**
+ * Which agent the CLI is running inside, read from the environment the host
+ * sets. Carried in the User-Agent (`martini-cli/0.1.0 (claude-code)`) so a
+ * tool call from the CLI under Claude Code is distinguishable from one Claude
+ * Code made over MCP. Unknown hosts yield null; nothing is guessed.
+ */
+const HOST_ENV_MARKERS = [
+    ['CLAUDECODE', 'claude-code'],
+    ['CLAUDE_CODE', 'claude-code'],
+    ['CURSOR_AGENT', 'cursor'],
+    ['CURSOR_TRACE_ID', 'cursor'],
+    ['CODEX_SANDBOX', 'codex'],
+    ['CODEX_CI', 'codex'],
+    ['GEMINI_CLI', 'gemini-cli'],
+    ['OPENCODE', 'opencode'],
+    ['WINDSURF_AGENT', 'windsurf'],
+    ['MARTINI_RUN_ID', 'martini-workflow'],
+];
+export function detectHostAgent(env = process.env) {
+    if (env.MARTINI_HOST_AGENT)
+        return env.MARTINI_HOST_AGENT;
+    for (const [variable, host] of HOST_ENV_MARKERS) {
+        if (env[variable])
+            return host;
+    }
+    if (env.TERM_PROGRAM && /cursor/i.test(env.TERM_PROGRAM))
+        return 'cursor';
+    return null;
+}
+//# sourceMappingURL=host.js.map

package/dist/host.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.js","sourceRoot":"","sources":["../src/host.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,gBAAgB,GAA4B;IAChD,CAAC,YAAY,EAAE,aAAa,CAAC;IAC7B,CAAC,aAAa,EAAE,aAAa,CAAC;IAC9B,CAAC,cAAc,EAAE,QAAQ,CAAC;IAC1B,CAAC,iBAAiB,EAAE,QAAQ,CAAC;IAC7B,CAAC,eAAe,EAAE,OAAO,CAAC;IAC1B,CAAC,UAAU,EAAE,OAAO,CAAC;IACrB,CAAC,YAAY,EAAE,YAAY,CAAC;IAC5B,CAAC,UAAU,EAAE,UAAU,CAAC;IACxB,CAAC,gBAAgB,EAAE,UAAU,CAAC;IAC9B,CAAC,gBAAgB,EAAE,kBAAkB,CAAC;CACvC,CAAA;AAED,MAAM,UAAU,eAAe,CAAC,MAAyB,OAAO,CAAC,GAAG;IAClE,IAAI,GAAG,CAAC,kBAAkB;QAAE,OAAO,GAAG,CAAC,kBAAkB,CAAA;IACzD,KAAK,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,gBAAgB,EAAE,CAAC;QAChD,IAAI,GAAG,CAAC,QAAQ,CAAC;YAAE,OAAO,IAAI,CAAA;IAChC,CAAC;IACD,IAAI,GAAG,CAAC,YAAY,IAAI,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC;QAAE,OAAO,QAAQ,CAAA;IACzE,OAAO,IAAI,CAAA;AACb,CAAC"}

package/dist/manifest.js

@@ -0,0 +1,48 @@
+/**
+ * The tool manifest the CLI is generated from: `src/generated/manifest.json`,
+ * exported from the backend registry with `pnpm --dir backend run export:tool-manifest`
+ * and drift-tested there against the live registry. Every entry becomes a
+ * command with the tool's name; the JSON Schema becomes its flags.
+ */
+import manifestJson from './generated/manifest.json' with { type: 'json' };
+/** Imported, not read at runtime, so the compiled single-file binary embeds it. */
+export function loadManifest() {
+    return manifestJson;
+}
+export function findTool(name, manifest = loadManifest()) {
+    return manifest.tools.find(tool => tool.name === name);
+}
+/** Tools grouped for `--help`, by the noun their name is about. */
+export function groupTools(tools) {
+    const groups = new Map();
+    for (const tool of tools) {
+        const group = groupOf(tool.name);
+        const list = groups.get(group) ?? [];
+        list.push(tool);
+        groups.set(group, list);
+    }
+    return [...groups.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([group, list]) => ({ group, tools: list.sort((a, b) => a.name.localeCompare(b.name)) }));
+}
+const GROUP_KEYWORDS = [
+    [/timeline|checkpoint|render|export_timeline|artifact|audio_report/, 'timeline'],
+    [/project_file|json_file|file_input/, 'files'],
+    [/workflow|run\b|_run$|actions?\b|^(pause|resume|approve|cancel|list)_run/, 'workflows'],
+    [/upload|storage|download/, 'uploads'],
+    [/library|subject|collection/, 'library'],
+    [/model|voice|upscale_presets/, 'models'],
+    [/generate|draft|upscale|enhance|blender|camera/, 'generation'],
+    [/bin|node|canvas|text_note|variable|layout|move_|duplicate|delete|metadata|labels|color/, 'canvas'],
+    [/comment/, 'comments'],
+    [/asset|inspect|frame|crop|view_/, 'assets'],
+    [/support/, 'support'],
+    [/project/, 'projects'],
+];
+export function groupOf(name) {
+    for (const [pattern, group] of GROUP_KEYWORDS)
+        if (pattern.test(name))
+            return group;
+    return 'other';
+}
+//# sourceMappingURL=manifest.js.map

package/dist/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,YAAY,MAAM,2BAA2B,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAA;AAgD1E,mFAAmF;AACnF,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;AAED,mEAAmE;AACnE,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,kEAAkE,EAAE,UAAU,CAAC;IAChF,CAAC,mCAAmC,EAAE,OAAO,CAAC;IAC9C,CAAC,yEAAyE,EAAE,WAAW,CAAC;IACxF,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,gCAAgC,EAAE,QAAQ,CAAC;IAC5C,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"}

package/dist/output.js

@@ -0,0 +1,128 @@
+/**
+ * The output and exit contract (docs/plans/agent-cli.md, decision 4).
+ *
+ * stdout carries results only: compact JSON when it is a pipe (an agent is
+ * reading), indented JSON on a terminal. `--out <path>` writes the result to a
+ * file and prints one summary line instead. Errors are one JSON object on
+ * stderr: `{ "error": { "code", "message", "hint" } }`, never mixed into stdout.
+ *
+ * Exit codes: 0 ok · 1 tool error · 2 usage · 3 auth · 4 not ready / timeout ·
+ * 5 insufficient credits.
+ */
+import { writeFileSync } from 'node:fs';
+import { CliApiError } from './api.js';
+import { ArgumentError } from './schema.js';
+export const EXIT = {
+    ok: 0,
+    toolError: 1,
+    usage: 2,
+    auth: 3,
+    notReady: 4,
+    insufficientCredits: 5,
+};
+function write(options, text) {
+    ;
+    (options.stdout ?? (line => process.stdout.write(line)))(text);
+}
+export function printResult(value, options = {}) {
+    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`);
+        return;
+    }
+    if (options.quiet)
+        return;
+    if (typeof value === 'string') {
+        write(options, value.endsWith('\n') ? value : `${value}\n`);
+        return;
+    }
+    const tty = options.isTTY ?? Boolean(process.stdout.isTTY);
+    write(options, (tty ? JSON.stringify(value, null, 2) : JSON.stringify(value)) + '\n');
+}
+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`);
+        return;
+    }
+    process.stdout.write(bytes);
+}
+/** One line describing a result for the `--out` summary. */
+export function summarize(value) {
+    if (value === null || value === undefined)
+        return 'empty result';
+    if (typeof value !== 'object')
+        return String(value);
+    if (Array.isArray(value))
+        return `${value.length} items`;
+    const record = value;
+    const keys = Object.keys(record);
+    const counted = keys.find(key => Array.isArray(record[key]));
+    if (counted)
+        return `${record[counted].length} ${counted}`;
+    return keys.length ? `object with ${keys.join(', ')}` : 'empty object';
+}
+export function exitCodeFor(error) {
+    if (error instanceof ArgumentError)
+        return EXIT.usage;
+    if (error instanceof CliApiError) {
+        if (error.code === 'NO_API_KEY' ||
+            error.status === 401 ||
+            /^(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) {
+            return EXIT.insufficientCredits;
+        }
+        if (/_NOT_READY$/.test(error.code) || error.code === 'TIMEOUT' || error.code === 'RUN_NOT_ACTIVE')
+            return EXIT.notReady;
+        if (error.code === 'INVALID_ARGUMENTS' || error.code === 'INVALID_REQUEST' || error.code === 'TOOL_NOT_FOUND') {
+            return EXIT.usage;
+        }
+        return EXIT.toolError;
+    }
+    return EXIT.toolError;
+}
+export function hintFor(error) {
+    if (error instanceof CliApiError) {
+        switch (error.code) {
+            case 'NO_API_KEY':
+                return 'Run martini login (laptops) or set MARTINI_API_KEY (scripts). Inside a workflow run the key is in .martini/config.json.';
+            case 'API_KEY_EXPIRED':
+                return 'Run martini login again to mint a fresh key.';
+            case 'INVALID_ARGUMENTS':
+                return error.tool ? `Run martini ${error.tool} --help for the flags and their types.` : undefined;
+            case 'TOOL_NOT_FOUND':
+                return 'Run martini tools to list what this key can call.';
+            case 'RUN_NOT_ACTIVE':
+                return 'Run keys work only while their workflow run is executing.';
+            case 'INSUFFICIENT_CREDITS':
+                return 'Top up olives in Martini, or lower the batch.';
+            default:
+                if (/_NOT_READY$/.test(error.code))
+                    return 'Wait for status completed: martini wait <asset-id>, or pass --wait.';
+                return undefined;
+        }
+    }
+    if (error instanceof ArgumentError)
+        return 'Run martini <command> --help.';
+    return undefined;
+}
+export function printError(error, options = {}) {
+    const code = exitCodeFor(error);
+    const payload = {
+        error: {
+            code: error instanceof CliApiError ? error.code : error instanceof ArgumentError ? 'USAGE' : 'CLI_ERROR',
+            message: error instanceof Error ? error.message : String(error),
+            ...(error instanceof CliApiError && error.tool ? { tool: error.tool } : {}),
+            ...(hintFor(error) ? { hint: hintFor(error) } : {}),
+            exitCode: code,
+        },
+    };
+    (options.stderr ?? (line => process.stderr.write(line)))(JSON.stringify(payload) + '\n');
+    return code;
+}
+//# sourceMappingURL=output.js.map

package/dist/output.js.map

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

package/dist/schema.js

@@ -0,0 +1,169 @@
+/**
+ * From a tool's JSON Schema to command flags, and from parsed flags back to the
+ * arguments object the tool expects. Scalars become `--kebab-case` flags,
+ * arrays repeat the flag (or take a JSON list), objects take JSON. `--json
+ * '{...}'` and `--json @file.json` merge a whole arguments object, so a plan a
+ * script computed is submitted without retyping it flag by flag.
+ */
+import { readFileSync } from 'node:fs';
+export class ArgumentError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ArgumentError';
+    }
+}
+export function kebab(property) {
+    return property
+        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+        .replace(/_/g, '-')
+        .toLowerCase();
+}
+function schemaKind(schema) {
+    if (!schema)
+        return 'json';
+    const type = Array.isArray(schema.type) ? schema.type.find(t => t !== 'null') : schema.type;
+    switch (type) {
+        case 'string':
+            return 'string';
+        case 'number':
+            return 'number';
+        case 'integer':
+            return 'integer';
+        case 'boolean':
+            return 'boolean';
+        case 'array':
+            return 'array';
+        case 'object':
+            return 'object';
+        default: {
+            const variants = schema.anyOf ?? schema.oneOf;
+            if (variants && variants.length > 0) {
+                const kinds = new Set(variants.map(variant => schemaKind(variant)));
+                if (kinds.size === 1)
+                    return [...kinds][0];
+            }
+            if (schema.enum)
+                return 'string';
+            return 'json';
+        }
+    }
+}
+export function flagSpecs(tool) {
+    const properties = tool.inputSchema.properties ?? {};
+    const required = new Set(tool.inputSchema.required ?? []);
+    return Object.entries(properties).map(([property, schema]) => {
+        const kind = schemaKind(schema);
+        const spec = {
+            property,
+            flag: kebab(property),
+            kind,
+            required: required.has(property),
+            description: schema.description ?? '',
+        };
+        if (schema.enum)
+            spec.enum = schema.enum;
+        if (kind === 'array')
+            spec.items = schemaKind(schema.items);
+        return spec;
+    });
+}
+function readJsonArgument(raw, what) {
+    const text = raw.startsWith('@') ? readFileSync(raw === '@-' ? 0 : raw.slice(1), 'utf8') : raw;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new ArgumentError(`${what} must be JSON${raw.startsWith('@') ? ` (read from ${raw.slice(1)})` : ''}.`);
+    }
+}
+function coerceScalar(raw, kind, what) {
+    switch (kind) {
+        case 'string':
+            return raw;
+        case 'number': {
+            const value = Number(raw);
+            if (!Number.isFinite(value))
+                throw new ArgumentError(`${what} must be a number.`);
+            return value;
+        }
+        case 'integer': {
+            const value = Number(raw);
+            if (!Number.isInteger(value))
+                throw new ArgumentError(`${what} must be an integer.`);
+            return value;
+        }
+        case 'boolean':
+            if (raw === 'true' || raw === '1' || raw === 'yes')
+                return true;
+            if (raw === 'false' || raw === '0' || raw === 'no')
+                return false;
+            throw new ArgumentError(`${what} must be true or false.`);
+        case 'object':
+        case 'json':
+        case 'array':
+            return readJsonArgument(raw, what);
+    }
+}
+/** Build the tool arguments from flags (plus `--json`); unknown flags are an error so typos never silently drop an argument. */
+export function buildArguments(tool, flags, options = {}) {
+    const specs = flagSpecs(tool);
+    const byFlag = new Map(specs.map(spec => [spec.flag, spec]));
+    const args = {};
+    const json = flags.get('json');
+    if (json !== undefined && json !== true) {
+        const raw = Array.isArray(json) ? json[json.length - 1] : json;
+        const merged = readJsonArgument(raw, '--json');
+        if (!merged || typeof merged !== 'object' || Array.isArray(merged)) {
+            throw new ArgumentError('--json must be an object of tool arguments.');
+        }
+        Object.assign(args, merged);
+    }
+    for (const [flag, value] of flags) {
+        if (flag === 'json' || options.ignore?.has(flag))
+            continue;
+        const spec = byFlag.get(flag);
+        if (!spec) {
+            const known = specs.map(s => `--${s.flag}`).join(', ');
+            throw new ArgumentError(`Unknown flag --${flag} for ${tool.name}. Flags: ${known || '(none)'}.`);
+        }
+        const what = `--${spec.flag}`;
+        if (value === true) {
+            if (spec.kind !== 'boolean')
+                throw new ArgumentError(`${what} needs a value.`);
+            args[spec.property] = true;
+            continue;
+        }
+        const values = Array.isArray(value) ? value : [value];
+        if (spec.kind === 'array') {
+            const single = values.length === 1 && values[0].trim().startsWith('[') ? values[0] : null;
+            const jsonList = single ? readJsonArgument(single, what) : null;
+            args[spec.property] = Array.isArray(jsonList)
+                ? jsonList
+                : values.map(raw => coerceScalar(raw, spec.items === 'json' ? 'string' : (spec.items ?? 'string'), what));
+            continue;
+        }
+        args[spec.property] = coerceScalar(values[values.length - 1], spec.kind, what);
+    }
+    // Context (the run's project, the configured canvas) fills what the caller
+    // left out, before required-ness is judged — a sandbox never types --project-id.
+    const filled = options.context ? applyContextDefaults(tool, args, options.context) : args;
+    for (const spec of specs) {
+        if (spec.required && filled[spec.property] === undefined) {
+            throw new ArgumentError(`--${spec.flag} is required for ${tool.name}.`);
+        }
+    }
+    return filled;
+}
+/** Fill `projectId` / `canvasId` / `runId` from the configured context when the tool takes them and the caller did not say. */
+export function applyContextDefaults(tool, args, context) {
+    const properties = tool.inputSchema.properties ?? {};
+    const filled = { ...args };
+    if ('projectId' in properties && filled.projectId === undefined && context.projectId)
+        filled.projectId = context.projectId;
+    if ('canvasId' in properties && filled.canvasId === undefined && context.canvasId)
+        filled.canvasId = context.canvasId;
+    if ('runId' in properties && filled.runId === undefined && context.runId)
+        filled.runId = context.runId;
+    return filled;
+}
+//# sourceMappingURL=schema.js.map

package/dist/schema.js.map

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