@controllerai/cli 0.2.0

package/dist/commands/node.js

@@ -0,0 +1,885 @@
+import { readFileSync } from 'node:fs';
+import { requireContext } from '../context.js';
+import { validationFailed, validationMessage } from './expr.js';
+import { CaiError, userError } from '../errors.js';
+import { resolveJsSource } from '../jsSource.js';
+import { buildNodeReadiness, expressionReadbackChannel, nodePropsFromPayload, normalizeNodePropWrites, } from '../nodeProps.js';
+import { emit, printKeyValues, printTable, truncate, warn } from '../output.js';
+const readUtf8 = (source, encoding) => readFileSync(source, encoding);
+const loadProps = async (api, workflowId, nodeId) => {
+    const props = await api.tool(workflowId, 'get_node_props', { nodeId });
+    return nodePropsFromPayload(props);
+};
+/**
+ * get_node exposes processOutput after a successful typed run or documented
+ * declaration. Until then, add the component's curated/observed type as
+ * diagnostic context; readiness deliberately remains unresolved until the
+ * runtime adopts it.
+ */
+const addResolvedOutputType = async (api, workflowId, record) => {
+    const nodeSlug = record.nodeSlug ?? record.data?.nodeSlug;
+    const nodeKey = record.key ?? record.data?.key;
+    if (!nodeSlug || !nodeKey)
+        return record;
+    try {
+        const component = await api.tool(workflowId, 'get_node_component', {
+            nodeSlug,
+            nodeKey,
+        });
+        const resolvedOutputType = component?.component?.outputDataType ?? component?.observedOutputType ?? null;
+        return resolvedOutputType ? { ...record, resolvedOutputType } : record;
+    }
+    catch {
+        // Status is still useful for configuration blockers. Fail closed on output
+        // readiness when the component type cannot be resolved.
+        return record;
+    }
+};
+/** Fail closed: a write without current prop metadata is unsafe. */
+const findProp = async (api, workflowId, nodeId, propName) => {
+    const rows = await loadProps(api, workflowId, nodeId);
+    const prop = rows.find(p => p.name === propName);
+    if (!prop) {
+        throw userError(`Node ${nodeId} has no prop "${propName}". Re-read \`cai node props ${nodeId}\`; ` +
+            'a selector, connection, or reload may need to be configured first.', 'UNKNOWN_PROP');
+    }
+    if (prop.enabled === false || prop.source === 'propsCatalog') {
+        throw userError(`Prop "${propName}" is optional but not materialized. Run ` +
+            `\`cai node enable-prop ${nodeId} --prop ${propName}\`, then re-read props.`, 'PROP_NOT_ENABLED');
+    }
+    return prop;
+};
+/**
+ * Prop types whose stored shape pairs a value with the human label the UI displayed.
+ *
+ * `STATIC_DROPDOWN` is deliberately EXCLUDED: its options are fixed in the node definition,
+ * so the UI stores the value alone and inventing a `valueLabel` is wrong (CFG-005 asserts
+ * exactly that). Only remotely-resolved options carry a label.
+ */
+const isOptionBackedProp = (prop) => ['DROPDOWN', 'MULTI_SELECT', 'MULTI_SELECT_DROPDOWN', 'REMOTE_OPTIONS'].includes(String(prop.inputType ?? ''));
+/**
+ * Multi-selects store `value` as an array AND `valueLabel` as an array of `{value, label}`
+ * pairs — not a parallel array of label strings. Single-selects store a plain label string.
+ * Getting this wrong saves cleanly and shows blank chips in the UI (found by CFG-012).
+ */
+const isMultiSelectProp = (prop) => ['MULTI_SELECT', 'MULTI_SELECT_DROPDOWN'].includes(String(prop.inputType ?? ''));
+/**
+ * Remote option providers commonly search human labels rather than opaque ids.
+ * A supplied --label is therefore the lookup query, never an unverified value
+ * written directly to the node.
+ */
+export const optionLookupQueries = (selected, labels) => {
+    const supplied = labels === undefined ? [] : Array.isArray(labels) ? labels : [labels];
+    if (supplied.length > 0 && supplied.length !== selected.length) {
+        throw userError(`Pass one --label per selected value (${selected.length} value(s), ${supplied.length} label(s)).`, 'OPTION_LABEL_COUNT_MISMATCH');
+    }
+    return selected.map((value, index) => supplied[index]?.trim() || String(value));
+};
+export const parseNodeOptionPage = (raw) => {
+    if (raw === undefined)
+        return undefined;
+    const page = Number(raw);
+    if (!Number.isInteger(page) || page < 0) {
+        throw userError('--page must be a non-negative integer.', 'BAD_OPTION_PAGE');
+    }
+    return page;
+};
+/**
+ * Prop types persisted as a `TextExpression` wrapping raw text. Their `--value` must reach
+ * the backend as a STRING; parsing it first (e.g. a JSON body, which is legal JSON) makes
+ * the backend store a bare object the runtime cannot evaluate.
+ */
+const isTextExpressionBackedProp = (prop) => ['JSON', 'LONG_TEXT', 'SHORT_TEXT', 'SQL', 'TEXT'].includes(String(prop.inputType ?? ''));
+const fetchPropOptions = async (api, workflowId, nodeId, propName, query) => {
+    const data = await api.tool(workflowId, 'get_prop_options', { nodeId, propName, ...(query ? { query } : {}) });
+    const rows = Array.isArray(data) ? data : (data?.options ?? []);
+    return rows
+        .map(o => ({
+        value: String(o.value ?? o.id ?? ''),
+        label: String(o.label ?? o.name ?? o.value ?? o.id ?? ''),
+    }))
+        .filter(o => o.value !== '');
+};
+const readObjectOption = (source, flag) => {
+    const raw = source.trimStart().startsWith('{') ? source : readFileSync(source, 'utf8');
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch (error) {
+        throw userError(`${flag} must be a JSON object or a path to one: ${error instanceof Error ? error.message : error}`, 'BAD_JSON_OPTION');
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw userError(`${flag} must contain a JSON object.`, 'BAD_JSON_SHAPE');
+    }
+    return value;
+};
+/** Read a documented response sample before any workflow or network access. */
+export const readNodeOutputSample = (source, reader = readUtf8) => {
+    let raw;
+    try {
+        raw = reader(source === '-' ? 0 : source, 'utf8');
+    }
+    catch (error) {
+        throw userError(`--sample-file "${source}" is not a readable UTF-8 file: ` +
+            `${error instanceof Error ? error.message : error}`, 'BAD_SAMPLE');
+    }
+    let sample;
+    try {
+        sample = JSON.parse(raw);
+    }
+    catch (error) {
+        throw userError(`--sample-file must contain valid JSON: ${error instanceof Error ? error.message : error}`, 'BAD_SAMPLE');
+    }
+    if (!sample || typeof sample !== 'object' || Array.isArray(sample)) {
+        throw userError('--sample-file must contain a JSON object.', 'BAD_SAMPLE');
+    }
+    return sample;
+};
+const nodeProcessOutput = (record) => record.processOutput ?? record.data?.processOutput;
+const renderNodeOutputType = (dataType, declared) => declared && typeof dataType === 'string'
+    ? `${dataType} (declared — unverified)`
+    : dataType;
+const shellQuote = (value) => `'${value.replace(/'/g, "'\\''")}'`;
+const requireCompletedPropReload = (result, nodeId, propName, retryCommand) => {
+    const reload = result;
+    if (reload?.propsReloaded !== false)
+        return;
+    const reloadError = typeof reload.reloadError === 'string' && reload.reloadError.trim()
+        ? reload.reloadError.trim()
+        : 'The backend did not provide a reload error.';
+    const inspectCommand = `cai node props ${nodeId} --json`;
+    throw new CaiError(`Prop "${propName}" was updated, but its dependent props were not reloaded: ` +
+        `${reloadError}\nThe node may still contain stale dependent values. Retry the reload with ` +
+        `\`${retryCommand}\`, then inspect \`${inspectCommand}\` before configuring or running it.`, {
+        code: 'PROPS_RELOAD_FAILED',
+        detail: {
+            nodeId,
+            prop: propName,
+            propsReloaded: false,
+            reloadError,
+            recoveryCommands: [retryCommand, inspectCommand],
+        },
+    });
+};
+const searchScore = (intent, component) => {
+    const normalize = (value) => value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, ' ')
+        .trim();
+    const query = normalize(intent);
+    const terms = query.split(/\s+/).filter(Boolean);
+    const name = normalize(component.name ?? '');
+    const description = normalize(component.description ?? '');
+    const props = normalize((component.propNames ?? []).join(' '));
+    let score = name === query ? 100 : name.includes(query) ? 50 : 0;
+    for (const term of terms) {
+        if (name.split(' ').includes(term))
+            score += 12;
+        else if (name.includes(term))
+            score += 7;
+        if (description.includes(term))
+            score += 3;
+        if (props.includes(term))
+            score += 2;
+    }
+    return score;
+};
+/**
+ * `add_node` needs BOTH nodeSlug and nodeKey, but component keys returned by
+ * search are already `<nodeSlug>-<component>` — so the slug is recoverable.
+ * Prefer an explicit --node, then a catalog lookup, then a prefix split.
+ */
+const resolveSlug = async (api, workflowId, componentKey, explicit) => {
+    if (explicit)
+        return explicit;
+    const guess = componentKey.includes('-') ? componentKey.slice(0, componentKey.indexOf('-')) : '';
+    // Registry slugs themselves contain underscores, not hyphens, so the first
+    // hyphen is the slug boundary for registry components. Verify before trusting.
+    for (const candidate of [guess, componentKey.replace(/-[^-]+$/, '')].filter(Boolean)) {
+        try {
+            const found = await api.tool(workflowId, 'search_node_components', {
+                nodeSlug: candidate,
+                limit: 100,
+            });
+            if ((found?.data ?? []).some(c => c.key === componentKey))
+                return candidate;
+        }
+        catch {
+            // wrong guess — try the next shape
+        }
+    }
+    throw userError(`Cannot infer the node slug from component key "${componentKey}". Pass --node <slug> ` +
+        '(the `nodeSlug` column from `cai node components`).', 'UNRESOLVED_SLUG');
+};
+export const registerNode = (program) => {
+    const node = program.command('node').description('Nodes — search, add, configure, wire');
+    node
+        .command('search')
+        .argument('<query>')
+        .option('--limit <n>', 'max rows', '10')
+        .option('--actions', 'only nodes that have actions')
+        .option('--events', 'only nodes that have trigger events')
+        .description('Search registry + catalog nodes (ranked by featuredWeight, not relevance)')
+        .action(async (query, opts, command) => {
+        const { api, workflowId } = requireContext(command);
+        const result = await api.tool(workflowId, 'search_nodes', {
+            query,
+            limit: Number(opts.limit),
+            ...(opts.actions ? { hasActions: true } : {}),
+            ...(opts.events ? { hasEvents: true } : {}),
+        });
+        const rows = result?.data ?? [];
+        emit({ items: rows, pagination: result?.pagination ?? null }, () => printTable(['slug', 'name', 'source', 'actions', 'events', 'auth', 'weight'], rows.map((n) => [
+            n.slug,
+            n.name,
+            n.source,
+            n.actionsCount,
+            n.eventsCount,
+            n.authRequired ? 'yes' : 'no',
+            n.featuredWeight,
+        ])));
+    });
+    node
+        .command('find')
+        .argument('<intent>', 'capability or action, e.g. "send a Slack message"')
+        .option('--node <slug>', 'search only this integration')
+        .option('--limit <n>', 'max exact component references', '8')
+        .description('Find ranked action components and return exact nodeSlug/nodeKey pairs')
+        .action(async (intent, opts, command) => {
+        const { api, workflowId } = requireContext(command);
+        let slugs;
+        if (opts.node) {
+            slugs = [opts.node];
+        }
+        else {
+            const nodes = await api.tool(workflowId, 'search_nodes', {
+                query: intent,
+                hasActions: true,
+                limit: 10,
+            });
+            slugs = (nodes?.data ?? []).map((row) => row.slug).filter(Boolean);
+        }
+        const batches = await Promise.all(slugs.map(async (nodeSlug) => {
+            const result = await api.tool(workflowId, 'search_node_components', {
+                nodeSlug,
+                query: intent,
+                limit: 20,
+            });
+            return (result?.data ?? []).map((component) => ({
+                ...component,
+                nodeSlug: component.nodeSlug ?? nodeSlug,
+            }));
+        }));
+        const rows = batches
+            .flat()
+            .map(component => ({ ...component, score: searchScore(intent, component) }))
+            .sort((left, right) => right.score - left.score || left.key.localeCompare(right.key))
+            .slice(0, Math.max(1, Number(opts.limit) || 8));
+        emit({ intent, items: rows }, () => printTable(['nodeSlug', 'nodeKey', 'action', 'auth', 'score'], rows.map(row => [
+            row.nodeSlug,
+            row.key,
+            row.name,
+            row.nodeAuthRequired ? 'yes' : 'no',
+            row.score,
+        ])));
+    });
+    node
+        .command('components')
+        .argument('[query]')
+        .requiredOption('--node <slug>', 'node slug whose components to list')
+        .option('--limit <n>', 'max rows', '25')
+        .description('List a node’s action components (the --key values for `node add`)')
+        .action(async (query, opts, command) => {
+        const { api, workflowId } = requireContext(command);
+        const result = await api.tool(workflowId, 'search_node_components', {
+            nodeSlug: opts.node,
+            ...(query ? { query } : {}),
+            limit: Number(opts.limit),
+        });
+        const rows = result?.data ?? [];
+        emit({ items: rows, pagination: result?.pagination ?? null }, () => printTable(['key', 'name', 'type', 'props'], rows.map(c => [c.key, c.name, c.type, (c.propNames ?? []).join(',')])));
+    });
+    node
+        .command('add')
+        .alias('init')
+        .requiredOption('--flow <flowId>')
+        .requiredOption('--key <componentKey>', 'component key, e.g. registry_http-http-request')
+        .option('--node <slug>', 'node slug (inferred from --key when omitted)')
+        .option('--name <displayName>', 'display name; also the outgoing connection label')
+        .option('--after <nodeId>', 'wire this upstream node into the new node at creation')
+        .option('--output <main|error>', 'which system output --after connects from', 'main')
+        .option('--connection <id>', 'bind an existing connection')
+        .option('--props <jsonOrFile>', 'initial prop map; direct values become {value:...}, advanced per-prop writes pass through')
+        .option('--enable-prop <names...>', 'optional prop names to materialize at creation')
+        .description('Initialize a node with its known connection, wiring, optional props, and values')
+        .action(async (opts, command) => {
+        const { api, workflowId } = requireContext(command);
+        const nodeSlug = await resolveSlug(api, workflowId, opts.key, opts.node);
+        const props = opts.props
+            ? normalizeNodePropWrites(readObjectOption(opts.props, '--props'))
+            : undefined;
+        const result = await api.mutate(workflowId, () => api.tool(workflowId, 'add_node', {
+            flowId: opts.flow,
+            nodeSlug,
+            nodeKey: opts.key,
+            connectionId: opts.connection ? Number(opts.connection) : null,
+            ...(opts.name ? { displayName: opts.name } : {}),
+            ...(props ? { props } : {}),
+            ...(opts.enableProp?.length ? { enableOptionalProps: opts.enableProp } : {}),
+            ...(opts.after
+                ? { connectFrom: { sourceNodeId: opts.after, sourceOutput: opts.output } }
+                : {}),
+        }));
+        const [rawRecord, currentProps] = await Promise.all([
+            api.tool(workflowId, 'get_node', { nodeId: result.nodeId }),
+            loadProps(api, workflowId, result.nodeId),
+        ]);
+        const record = await addResolvedOutputType(api, workflowId, rawRecord);
+        const readiness = buildNodeReadiness(result.nodeId, record, currentProps);
+        const requestedPropNames = Object.keys(props ?? {});
+        const propsReadback = currentProps.filter(prop => requestedPropNames.includes(prop.name ?? prop.key ?? ''));
+        emit({ ...result, normalizedProps: props ?? {}, propsReadback, readiness }, () => printKeyValues([
+            ['nodeId', result.nodeId],
+            ['displayName', result.displayName],
+            ['position', JSON.stringify(result.position ?? {})],
+            ['propsSet', (result.propsSet ?? []).join(', ') || '(none)'],
+            [
+                'configuration blockers',
+                readiness.blockedBy.filter(blocker => blocker !== 'output type').join(', ') || '(none)',
+            ],
+            ['next', `cai node status ${result.nodeId} — verify before expressions`],
+        ]));
+    });
+    node
+        .command('component')
+        .requiredOption('--node <slug>', 'integration node slug')
+        .requiredOption('--key <componentKey>', 'component key from `cai node components`')
+        .description('Full static prop schema for a component BEFORE adding it — no node needed')
+        .action(async (opts, command) => {
+        const { api, workflowId } = requireContext(command);
+        const data = await api.tool(workflowId, 'get_node_component', {
+            nodeSlug: opts.node,
+            nodeKey: opts.key,
+        });
+        // The payload nests: {node:{slug,name,authRequired}, component:{key,name,
+        // description,type,outputDataType}, props:[…]} — nothing useful is at the
+        // top level, which is easy to miss when reading only the tool description.
+        const props = data?.props ?? data?.component?.props ?? [];
+        const component = data?.component ?? {};
+        emit(data, () => {
+            printKeyValues([
+                ['key', component.key ?? opts.key],
+                ['name', component.name ?? '-'],
+                [
+                    'node',
+                    `${data?.node?.slug ?? opts.node}${data?.node?.authRequired ? ' (auth required)' : ''}`,
+                ],
+                ['outputType', component.outputDataType ?? data?.observedOutputType ?? '(unresolved)'],
+                ['description', truncate(component.description, 70)],
+            ]);
+            process.stdout.write('\nprops\n');
+            printTable(['name', 'inputType', 'required', 'default', 'remoteOptions', 'reloadProps'], props.map(p => [
+                p.name,
+                p.inputType,
+                p.required ? 'yes' : '',
+                truncate(p.defaultValue, 24),
+                p.remoteOptions ? 'yes — pick with `cai node options` after adding' : '',
+                p.reloadProps ? 'yes — reveals dependent props after adding' : '',
+            ]));
+        });
+    });
+    node
+        .command('duplicate')
+        .argument('<nodeId>')
+        .description('Copy a node into the same flow (offset position, no incoming edges)')
+        .action(async (nodeId, _opts, command) => {
+        const { api, workflowId } = requireContext(command);
+        const result = await api.mutate(workflowId, () => api.tool(workflowId, 'duplicate_node', { nodeId }));
+        warn('A duplicate copies props but NOT the wiring: any prop expression that referenced an ' +
+            'input of the original now has no such input on the copy. Re-wire it with ' +
+            '`cai node connect` and re-read `cai expr context` before trusting its expressions.');
+        emit(result, () => printKeyValues([
+            ['source', nodeId],
+            ['copy', result?.newNodeId ?? result?.nodeId ?? JSON.stringify(result)],
+        ]));
+    });
+    node
+        .command('set-flow')
+        .argument('<nodeId>', 'a Run flow / Run flow on list node')
+        .requiredOption('--flow <flowId>', 'target flow to call')
+        .description('Point a subflow node at a flow; its input props are generated from that flow')
+        .action(async (nodeId, opts, command) => {
+        const { api, workflowId } = requireContext(command);
+        const result = await api.mutate(workflowId, () => api.tool(workflowId, 'set_subflow_node_flow', { nodeId, flowId: opts.flow }));
+        warn('The mapping props are synthesized from the target flow’s CURRENT inputs. A flow input ' +
+            'added later does not appear on this node until it is re-linked — re-run this command ' +
+            'after changing the target flow’s inputs.');
+        emit(result, () => printKeyValues([
+            ['nodeId', nodeId],
+            ['flowId', opts.flow],
+            ['next', 'cai node props ' + nodeId + ' — one mapping prop per flow input'],
+        ]));
+    });
+    node
+        .command('get')
+        .argument('<nodeId>')
+        .description('Full node record: component, inputs, outputs, connection')
+        .action(async (nodeId, _opts, command) => {
+        const { api, workflowId } = requireContext(command);
+        const data = await api.tool(workflowId, 'get_node', { nodeId });
+        emit(data, () => {
+            const processOutput = nodeProcessOutput(data);
+            printKeyValues([
+                ['id', data.id ?? nodeId],
+                ['displayName', data.displayName ?? data.data?.displayName],
+                ['component', data.nodeComponentKey ?? data.data?.nodeComponentKey],
+                ['connectionId', data.connectionId ?? data.data?.connectionId ?? '(none)'],
+                [
+                    'outputType',
+                    processOutput?.dataType
+                        ? renderNodeOutputType(processOutput.dataType, processOutput.declared === true)
+                        : '(none)',
+                ],
+            ]);
+            const inputs = data.inputs ?? data.data?.inputs ?? [];
+            if (inputs.length) {
+                process.stdout.write('\ninputs\n');
+                printTable(['id', 'displayName', 'dataType'], inputs.map((i) => [i.id, i.displayName, i.dataType]));
+            }
+            const outputs = data.outputs ?? data.data?.outputs ?? [];
+            if (outputs.length) {
+                process.stdout.write('\noutputs\n');
+                printTable(['id', 'displayName', 'dataType'], outputs.map((o) => [o.id, o.displayName, o.dataType]));
+            }
+        });
+    });
+    node
+        .command('declare-output')
+        .argument('<nodeId>')
+        .requiredOption('--sample-file <file|->', 'documented response data JSON object; `-` reads stdin')
+        .description('Declare an unverified dynamic output contract from documented response data')
+        .action(async (nodeId, opts, command) => {
+        const sample = readNodeOutputSample(opts.sampleFile);
+        const { api, workflowId } = requireContext(command);
+        const result = await api.mutate(workflowId, () => api.tool(workflowId, 'declare_node_output_type', {
+            nodeId,
+            sample,
+        }));
+        emit(result, () => {
+            printKeyValues([
+                ['dataTypeName', result.dataTypeName],
+                ['status', `${result.status} (unverified)`],
+            ]);
+            process.stdout.write(`\nThis contract comes from documentation, not a run. ` +
+                `The first real completed run verifies it automatically. ` +
+                `Downstream: re-read \`cai node status ${nodeId}\` and \`cai expr context\`.\n`);
+        });
+    });
+    node
+        .command('props')
+        .argument('<nodeId>')
+        .description('Visible + catalog props with current values and decompiled valueJs')
+        .action(async (nodeId, _opts, command) => {
+        const { api, workflowId } = requireContext(command);
+        const data = await api.tool(workflowId, 'get_node_props', { nodeId });
+        const props = nodePropsFromPayload(data);
+        emit(data, () => printTable(['name', 'inputType', 'required', 'enabled', 'value', 'valueJs', 'expressionValueJs'], props.map(p => [
+            p.name ?? p.key,
+            p.inputType,
+            p.required ? 'yes' : '',
+            p.enabled === false ? 'no' : 'yes',
+            truncate(p.value, 40),
+            truncate(p.valueJs, 40),
+            truncate(p.expressionValueJs, 40),
+        ])));
+    });
+    node
+        .command('status')
+        .argument('<nodeId>')
+        .description('Return deterministic configuration readiness and exact blockers')
+        .action(async (nodeId, _opts, command) => {
+        const { api, workflowId } = requireContext(command);
+        const [record, props] = await Promise.all([
+            api.tool(workflowId, 'get_node', { nodeId }),
+            loadProps(api, workflowId, nodeId),
+        ]);
+        const resolvedRecord = await addResolvedOutputType(api, workflowId, record);
+        const readiness = buildNodeReadiness(nodeId, resolvedRecord, props);
+        const outputTypeDeclared = nodeProcessOutput(resolvedRecord)?.declared === true;
+        const payload = {
+            ...readiness,
+            ...(outputTypeDeclared ? { outputTypeDeclared: true } : {}),
+        };
+        emit(payload, () => printKeyValues([
+            ['nodeId', nodeId],
+            [
+                'connection',
+                payload.missingConnection ? 'missing' : (payload.connectionId ?? 'not required'),
+            ],
+            ['required props', payload.missingRequiredProps.join(', ') || 'complete'],
+            ['reload selectors', payload.pendingReloadProps.join(', ') || 'complete'],
+            [
+                'output type',
+                `${payload.outputTypeStatus}${payload.outputTypes.length
+                    ? ` (${payload.outputTypes
+                        .map(type => renderNodeOutputType(type, outputTypeDeclared && payload.outputTypeSource === 'processOutput'))
+                        .join(', ')})`
+                    : ''} via ${payload.outputTypeSource}`,
+            ],
+            ['ready for expressions', payload.readyForExpressions ? 'yes' : 'no'],
+            ['ready to run', payload.readyForRun ? 'yes' : 'no'],
+            [
+                'ready for downstream expressions',
+                payload.readyForDownstreamExpressions ? 'yes' : 'no',
+            ],
+            ['next', payload.next],
+        ]));
+    });
+    node
+        .command('set')
+        .argument('<nodeId>')
+        .requiredOption('--prop <name>', 'prop key from `cai node props`')
+        .option('--value <literal>', 'static value (JSON when it parses, else a string)')
+        .option('--js <src>', 'expression DSL source, compiled server-side before writing')
+        .option('--js-file <path|->', 'read expression DSL source from a UTF-8 file or stdin')
+        .option('--label <labels...>', 'live option label(s), one per value; used to search providers that do not index opaque ids')
+        .option('--expression', 'deprecated compatibility flag; storage is selected automatically', false)
+        .description('Set a prop, selecting and verifying the correct storage shape automatically')
+        .action(async (nodeId, opts, command) => {
+        const js = resolveJsSource(opts, { required: false });
+        const { api, workflowId } = requireContext(command);
+        if (js === undefined && opts.value === undefined) {
+            throw userError('Pass --value <literal>, --js <expression>, or --js-file <path|->.', 'MISSING_VALUE');
+        }
+        if (js !== undefined && opts.value !== undefined) {
+            throw userError('--value is mutually exclusive with --js and --js-file.', 'CONFLICTING_VALUE');
+        }
+        const prop = await findProp(api, workflowId, nodeId, opts.prop);
+        const persistedExpressionChannel = expressionReadbackChannel(prop);
+        if (opts.expression) {
+            warn('`--expression` is no longer needed; the CLI selects the correct storage channel.');
+        }
+        if (js !== undefined) {
+            // Compile FIRST. update_node_prop would also compile, but validating as
+            // a separate read-only call guarantees a failed expression writes
+            // nothing and lets us print the compiler error verbatim.
+            const validation = await api.tool(workflowId, 'validate_expression', {
+                js,
+                nodeId,
+                propName: opts.prop,
+            });
+            if (validationFailed(validation)) {
+                throw userError(`Expression did not compile — nothing was written.\n\n${validationMessage(validation)}`, 'EXPRESSION_COMPILE_ERROR');
+            }
+            for (const w of validation?.warnings ?? [])
+                warn(String(w));
+        }
+        const payload = { nodeId, key: opts.prop };
+        if (js !== undefined) {
+            // valueJs is intentionally the one public write channel. The backend
+            // resolves the prop's real compile target and routes the compiled value
+            // into value or expressionValue as appropriate.
+            payload.valueJs = js;
+        }
+        else if (isTextExpressionBackedProp(prop)) {
+            // These props persist as a TextExpression wrapping the raw TEXT. The backend does
+            // that wrapping only when it receives a string — hand it a parsed object and it
+            // stores the object verbatim, producing a shape the runtime cannot evaluate.
+            // JSON bodies are the common case: `{"a":1}` is valid JSON, so a general-purpose
+            // literal parser eats it. Found by CFG-010.
+            payload.value = opts.value;
+        }
+        else {
+            payload.value = parseLiteral(opts.value);
+        }
+        const suppliedLabels = Array.isArray(opts.label)
+            ? opts.label
+            : opts.label
+                ? [opts.label]
+                : [];
+        if (suppliedLabels.length && !isOptionBackedProp(prop)) {
+            payload.valueLabel = suppliedLabels.length === 1 ? suppliedLabels[0] : suppliedLabels;
+        }
+        // An option-backed prop carries BOTH a value and the human label the UI showed. Resolve
+        // both from live options so a missing or wrongly-shaped label cannot write a
+        // half-configured prop (CFG-004, CFG-012). When a provider does not index opaque ids,
+        // caller-supplied --label is used only as the search query; the returned value must still
+        // match before anything is persisted.
+        if (js === undefined) {
+            const selected = Array.isArray(payload.value) ? payload.value : [payload.value];
+            const queries = optionLookupQueries(selected, suppliedLabels);
+            const optionBatches = prop.remoteOptions
+                ? await Promise.all(queries.map(query => fetchPropOptions(api, workflowId, nodeId, opts.prop, query)))
+                : [
+                    (prop.options ?? []).map(option => ({
+                        value: String(option.value ?? option.id ?? ''),
+                        label: String(option.label ?? option.name ?? option.value ?? option.id ?? ''),
+                    })),
+                ];
+            const options = [
+                ...new Map(optionBatches.flat().map(option => [option.value, option])).values(),
+            ];
+            if (prop.remoteOptions && options.length === 0) {
+                throw userError(`No live options were returned for ${opts.prop}. Check the connection and earlier ` +
+                    'selector props. If you copied an opaque value from `cai node options`, also pass ' +
+                    'its displayed label with `--label`; nothing was written.', 'OPTIONS_UNAVAILABLE');
+            }
+            if (options.length) {
+                const labelFor = (value) => options.find(option => option.value === String(value));
+                const unknown = selected.filter(value => !labelFor(value)).map(value => String(value));
+                if (unknown.length) {
+                    throw userError(`${unknown.map(value => `"${value}"`).join(', ')} is not a valid option for ` +
+                        `${opts.prop}. Run \`cai node options ${nodeId} --prop ${opts.prop} --query ` +
+                        `"<display label>"\`, then retry with the exact returned --value and --label. ` +
+                        'Nothing was written.', 'UNKNOWN_OPTION');
+                }
+                if (isOptionBackedProp(prop)) {
+                    const resolved = selected.map(value => labelFor(value));
+                    payload.valueLabel = isMultiSelectProp(prop)
+                        ? resolved.map(option => ({ value: option.value, label: option.label }))
+                        : resolved[0].label;
+                }
+            }
+        }
+        const result = await api.mutate(workflowId, () => api.tool(workflowId, 'update_node_prop', payload));
+        const retryCommand = `cai node set ${nodeId} --prop ${opts.prop}` +
+            (opts.value !== undefined
+                ? ` --value ${shellQuote(String(opts.value))}` +
+                    (suppliedLabels.length
+                        ? ` --label ${suppliedLabels.map(label => shellQuote(label)).join(' ')}`
+                        : '')
+                : ' --value <same-value>');
+        requireCompletedPropReload(result, nodeId, opts.prop, retryCommand);
+        const readback = await findProp(api, workflowId, nodeId, opts.prop);
+        const persistedChannel = js !== undefined ? persistedExpressionChannel : 'value';
+        if (js !== undefined && !readback[persistedChannel]) {
+            throw userError(`The write returned successfully but ${opts.prop}.${persistedChannel} did not read back.`, 'READBACK_MISMATCH');
+        }
+        if (js === undefined && readback.value === undefined) {
+            throw userError(`The write returned successfully but ${opts.prop}.value did not read back.`, 'READBACK_MISMATCH');
+        }
+        emit({
+            nodeId,
+            prop: opts.prop,
+            mode: js !== undefined ? 'js' : 'static',
+            persistedChannel,
+            readback,
+            result,
+        }, () => printKeyValues([
+            ['nodeId', nodeId],
+            ['prop', opts.prop],
+            ['mode', js !== undefined ? 'expression (compiled)' : 'static'],
+            ['persisted channel', persistedChannel],
+            ['verified', 'yes'],
+        ]));
+    });
+    node
+        .command('set-connection')
+        .argument('<nodeId>')
+        .requiredOption('--connection <id>', 'connection id from `cai connection list`')
+        .description('Bind a connection to an action node')
+        .action(async (nodeId, opts, command) => {
+        const { api, workflowId } = requireContext(command);
+        const result = await api.mutate(workflowId, () => api.tool(workflowId, 'update_node_connection', {
+            nodeId,
+            connectionId: String(opts.connection),
+        }));
+        emit({ nodeId, connectionId: opts.connection, result }, () => printKeyValues([
+            ['nodeId', nodeId],
+            ['connectionId', opts.connection],
+        ]));
+    });
+    node
+        .command('connect')
+        .requiredOption('--from <nodeId>', 'upstream node')
+        .requiredOption('--to <nodeId>', 'downstream node')
+        .requiredOption('--flow <flowId>', 'flow containing both nodes')
+        .option('--output <main|error>', 'which system output to wire from', 'main')
+        .description('Wire two nodes; the source output becomes an input on the target')
+        .action(async (opts, command) => {
+        const { api, workflowId } = requireContext(command);
+        const result = await api.mutate(workflowId, () => api.tool(workflowId, 'connect_nodes', {
+            flowId: opts.flow,
+            sourceNodeId: opts.from,
+            targetNodeId: opts.to,
+            sourceOutput: opts.output,
+        }));
+        emit(result, () => printKeyValues([
+            ['from', `${opts.from} (${opts.output})`],
+            ['to', opts.to],
+            ['result', JSON.stringify(result)],
+        ]));
+    });
+    node
+        .command('disconnect')
+        .requiredOption('--edge <edgeId>')
+        .description('Remove an edge')
+        .action(async (opts, command) => {
+        const { api, workflowId } = requireContext(command);
+        const result = await api.mutate(workflowId, () => api.tool(workflowId, 'disconnect_nodes', { edgeId: opts.edge }));
+        emit(result, () => printKeyValues([['removed', opts.edge]]));
+    });
+    node
+        .command('only-when')
+        .argument('<nodeId>')
+        .option('--js <expr>', 'boolean expression; the node runs only when it is true')
+        .option('--js-file <path|->', 'read the boolean expression from a UTF-8 file or stdin')
+        .option('--clear', 'remove all conditions', false)
+        .description('Set or clear a node’s conditional-execution rule')
+        .action(async (nodeId, opts, command) => {
+        const js = resolveJsSource(opts, { required: false });
+        const { api, workflowId } = requireContext(command);
+        if (js === undefined && !opts.clear) {
+            throw userError('Pass --js <expression>, --js-file <path|->, or --clear.', 'MISSING_CONDITION');
+        }
+        if (js !== undefined && opts.clear) {
+            throw userError('--clear is mutually exclusive with --js and --js-file.', 'CONFLICTING_CONDITION');
+        }
+        if (js !== undefined) {
+            const validation = await api.tool(workflowId, 'validate_expression', {
+                js,
+                nodeId,
+                mode: 'onlyWhen',
+            });
+            if (validationFailed(validation)) {
+                throw userError(`onlyWhen expression did not compile — nothing was written.\n\n${validationMessage(validation)}`, 'EXPRESSION_COMPILE_ERROR');
+            }
+        }
+        const onlyWhen = opts.clear
+            ? { type: 'group', operator: 'OR', rules: [] }
+            : {
+                type: 'group',
+                operator: 'OR',
+                rules: [
+                    {
+                        type: 'group',
+                        operator: 'AND',
+                        rules: [{ type: 'rule', value: js }],
+                    },
+                ],
+            };
+        const result = await api.mutate(workflowId, () => api.tool(workflowId, 'set_node_only_when', { nodeId, onlyWhen }));
+        emit({ nodeId, cleared: Boolean(opts.clear), js: js ?? null, result }, () => printKeyValues([
+            ['nodeId', nodeId],
+            ['onlyWhen', opts.clear ? '(cleared)' : js],
+        ]));
+    });
+    node
+        .command('optional-props')
+        .argument('<nodeId>')
+        .description('List togglable optional props')
+        .action(async (nodeId, _opts, command) => {
+        const { api, workflowId } = requireContext(command);
+        const data = await api.tool(workflowId, 'get_node_optional_props', { nodeId });
+        const rows = Array.isArray(data) ? data : (data?.props ?? []);
+        emit(data, () => printTable(['name', 'displayName', 'inputType', 'enabled'], rows.map(p => [p.name, p.displayName, p.inputType, p.enabled ? 'yes' : 'no'])));
+    });
+    node
+        .command('enable-prop')
+        .argument('<nodeId>')
+        .requiredOption('--prop <name>')
+        .description('Enable an optional prop so it becomes settable')
+        .action(async (nodeId, opts, command) => {
+        const { api, workflowId } = requireContext(command);
+        const result = await api.mutate(workflowId, () => api.tool(workflowId, 'enable_optional_prop', { nodeId, propName: opts.prop }));
+        emit(result, () => printKeyValues([['enabled', `${nodeId}.${opts.prop}`]]));
+    });
+    node
+        .command('options')
+        .argument('<nodeId>')
+        .requiredOption('--prop <name>')
+        // keep in sync with fetchPropOptions() below, which reuses this tool
+        .option('--query <q>', 'search term — strongly preferred over paging')
+        .option('--page <n>', '0-based page when not searching')
+        .description('Resolved remote dropdown options for a prop')
+        .action(async (nodeId, opts, command) => {
+        const { api, workflowId } = requireContext(command);
+        const page = parseNodeOptionPage(opts.page);
+        const data = await api.tool(workflowId, 'get_prop_options', {
+            nodeId,
+            propName: opts.prop,
+            ...(opts.query ? { query: opts.query } : {}),
+            ...(page !== undefined ? { page } : {}),
+        });
+        const rows = data?.options ?? (Array.isArray(data) ? data : []);
+        emit(data, () => printTable(['value', 'label'], rows.map(o => [o.value ?? o.id, o.label ?? o.name])));
+    });
+    node
+        .command('continue-on-error')
+        .argument('<nodeId>')
+        .option('--enable', 'ensure continue-on-error is enabled')
+        .option('--disable', 'ensure continue-on-error is disabled')
+        .description('Idempotently set continue-on-error after reading the current state')
+        .action(async (nodeId, opts, command) => {
+        const { api, workflowId } = requireContext(command);
+        if (opts.enable && opts.disable) {
+            throw userError('--enable and --disable are mutually exclusive.', 'CONFLICTING_STATE');
+        }
+        if (!opts.enable && !opts.disable) {
+            throw userError('Pass --enable or --disable.', 'MISSING_STATE');
+        }
+        const before = await api.tool(workflowId, 'get_node', { nodeId });
+        const current = Boolean(before.continueOnError ?? before.data?.continueOnError);
+        const desired = Boolean(opts.enable);
+        let result = { unchanged: true };
+        if (current !== desired) {
+            result = await api.mutate(workflowId, () => api.tool(workflowId, 'toggle_continue_on_error', { nodeId }));
+        }
+        const after = await api.tool(workflowId, 'get_node', { nodeId });
+        const verified = Boolean(after.continueOnError ?? after.data?.continueOnError) === desired;
+        if (!verified) {
+            throw userError('Continue-on-error did not read back as requested.', 'READBACK_MISMATCH');
+        }
+        emit({ nodeId, enabled: desired, changed: current !== desired, result }, () => printKeyValues([
+            ['nodeId', nodeId],
+            ['continue on error', desired ? 'enabled' : 'disabled'],
+            ['changed', current !== desired ? 'yes' : 'no'],
+            ['verified', 'yes'],
+        ]));
+    });
+    node
+        .command('rename')
+        .argument('<nodeId>')
+        .requiredOption('--name <displayName>')
+        .description('Rename a node (also renames its outgoing connection label)')
+        .action(async (nodeId, opts, command) => {
+        const { api, workflowId } = requireContext(command);
+        const result = await api.mutate(workflowId, () => api.tool(workflowId, 'update_node_display_name', { nodeId, displayName: opts.name }));
+        emit(result, () => printKeyValues([
+            ['nodeId', nodeId],
+            ['displayName', opts.name],
+        ]));
+    });
+    node
+        .command('delete')
+        .argument('<nodeId>')
+        .description('Delete a node')
+        .action(async (nodeId, _opts, command) => {
+        const { api, workflowId } = requireContext(command);
+        const result = await api.mutate(workflowId, () => api.tool(workflowId, 'delete_node', { nodeId }));
+        emit(result, () => printKeyValues([['deleted', nodeId]]));
+    });
+};
+/** `--value 42` should store a number, `--value hello` a string. */
+export const parseLiteral = (raw) => {
+    if (raw === undefined)
+        return raw;
+    const trimmed = raw.trim();
+    if (trimmed === '')
+        return raw;
+    if (/^(true|false|null)$/.test(trimmed))
+        return JSON.parse(trimmed);
+    if (/^-?\d+(\.\d+)?$/.test(trimmed))
+        return Number(trimmed);
+    if (/^[[{"]/.test(trimmed)) {
+        try {
+            return JSON.parse(trimmed);
+        }
+        catch {
+            return raw;
+        }
+    }
+    return raw;
+};
+//# sourceMappingURL=node.js.map