@controllerai/cli 0.2.0

package/dist/config.js

@@ -0,0 +1,74 @@
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+export const DEFAULT_API_URL = 'https://api.app.getcontroller.ai';
+const defaultConfigDirectory = () => join(homedir(), '.config', 'cai');
+const defaultConfigPath = () => join(defaultConfigDirectory(), 'config.json');
+export const configPath = () => process.env.CAI_CONFIG ?? defaultConfigPath();
+/**
+ * Create the config parent securely without changing permissions on a directory
+ * the caller already owns. The default cai directory is CLI-owned and may always
+ * be hardened; a custom parent may only be chmodded when this call created it.
+ */
+const ensureConfigParent = (path) => {
+    const parent = dirname(path);
+    const parentExisted = existsSync(parent);
+    mkdirSync(parent, { recursive: true, mode: 0o700 });
+    if (!parentExisted || resolve(parent) === resolve(defaultConfigDirectory())) {
+        chmodSync(parent, 0o700);
+    }
+};
+const readFile = () => {
+    const path = configPath();
+    if (!existsSync(path))
+        return {};
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+};
+/** File config overlaid with env vars. Env always wins. */
+export const loadConfig = () => {
+    const file = readFile();
+    const envWorkflow = process.env.CAI_WORKFLOW ? Number(process.env.CAI_WORKFLOW) : undefined;
+    return {
+        apiUrl: (process.env.CAI_API_URL ?? file.apiUrl ?? DEFAULT_API_URL).replace(/\/+$/, ''),
+        appUrl: file.appUrl,
+        token: process.env.CAI_TOKEN ?? file.token,
+        tokenKind: process.env.CAI_TOKEN ? detectTokenKind(process.env.CAI_TOKEN) : file.tokenKind,
+        workflowId: envWorkflow ?? file.workflowId,
+        headStateId: file.headStateId,
+    };
+};
+/** Merge a patch into the persisted config file (env overrides are not written). */
+export const saveConfig = (patch) => {
+    const path = configPath();
+    ensureConfigParent(path);
+    const next = { ...readFile(), ...patch };
+    writeFileSync(path, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+    chmodSync(path, 0o600);
+    return next;
+};
+export const clearToken = () => {
+    const current = readFile();
+    const next = { ...current };
+    delete next.token;
+    delete next.tokenKind;
+    delete next.expiresAt;
+    const path = configPath();
+    ensureConfigParent(path);
+    writeFileSync(path, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+    chmodSync(path, 0o600);
+    return next;
+};
+export const detectTokenKind = (token) => token.startsWith('cai_') ? 'cli' : token.startsWith('sk-') ? 'apiKey' : 'jwt';
+export const maskToken = (token) => {
+    if (!token)
+        return '(none)';
+    if (token.length <= 12)
+        return `${token.slice(0, 3)}…`;
+    return `${token.slice(0, 6)}…${token.slice(-4)}`;
+};
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/context.js

@@ -0,0 +1,39 @@
+import { ApiClient } from './api/client.js';
+import { loadConfig } from './config.js';
+import { userError } from './errors.js';
+export const buildClient = (command) => {
+    const config = loadConfig();
+    const overrideUrl = globalOpt(command, 'apiUrl');
+    if (typeof overrideUrl === 'string' && overrideUrl) {
+        config.apiUrl = overrideUrl.replace(/\/+$/, '');
+    }
+    return { config, api: new ApiClient(config) };
+};
+/** Walk to the root program to read a global flag from any depth of subcommand. */
+export const globalOpt = (command, name) => {
+    let node = command;
+    while (node) {
+        const value = node.opts()[name];
+        if (value !== undefined)
+            return value;
+        node = node.parent;
+    }
+    return undefined;
+};
+export const resolveWorkflowId = (command, config) => {
+    const flag = globalOpt(command, 'workflow');
+    const raw = flag ?? config.workflowId;
+    if (raw === undefined || raw === null || raw === '') {
+        throw userError('No workflow selected. Pass --workflow <id>, set CAI_WORKFLOW, or run `cai use <id>`.', 'NO_WORKFLOW');
+    }
+    const id = Number(raw);
+    if (!Number.isInteger(id) || id <= 0) {
+        throw userError(`Invalid workflow id: ${String(raw)}`, 'BAD_WORKFLOW_ID');
+    }
+    return id;
+};
+export const requireContext = (command) => {
+    const { config, api } = buildClient(command);
+    return { config, api, workflowId: resolveWorkflowId(command, config) };
+};
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAC3C,OAAO,EAAa,UAAU,EAAE,MAAM,aAAa,CAAA;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AASvC,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,OAAgB,EAAyC,EAAE;IACrF,MAAM,MAAM,GAAG,UAAU,EAAE,CAAA;IAC3B,MAAM,WAAW,GAAG,SAAS,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAA;IAChD,IAAI,OAAO,WAAW,KAAK,QAAQ,IAAI,WAAW,EAAE,CAAC;QACnD,MAAM,CAAC,MAAM,GAAG,WAAW,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;IACjD,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,SAAS,CAAC,MAAM,CAAC,EAAE,CAAA;AAC/C,CAAC,CAAA;AAED,mFAAmF;AACnF,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,OAAgB,EAAE,IAAY,EAAW,EAAE;IACnE,IAAI,IAAI,GAAmB,OAAO,CAAA;IAClC,OAAO,IAAI,EAAE,CAAC;QACZ,MAAM,KAAK,GAAI,IAAI,CAAC,IAAI,EAA8B,CAAC,IAAI,CAAC,CAAA;QAC5D,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,KAAK,CAAA;QACrC,IAAI,GAAG,IAAI,CAAC,MAAM,CAAA;IACpB,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,OAAgB,EAAE,MAAiB,EAAU,EAAE;IAC/E,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,EAAE,UAAU,CAAC,CAAA;IAC3C,MAAM,GAAG,GAAG,IAAI,IAAI,MAAM,CAAC,UAAU,CAAA;IACrC,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,EAAE,EAAE,CAAC;QACpD,MAAM,SAAS,CACb,sFAAsF,EACtF,aAAa,CACd,CAAA;IACH,CAAC;IACD,MAAM,EAAE,GAAG,MAAM,CAAC,GAAG,CAAC,CAAA;IACtB,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC;QACrC,MAAM,SAAS,CAAC,wBAAwB,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,iBAAiB,CAAC,CAAA;IAC3E,CAAC;IACD,OAAO,EAAE,CAAA;AACX,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,OAAgB,EAAkB,EAAE;IACjE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,WAAW,CAAC,OAAO,CAAC,CAAA;IAC5C,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,EAAE,iBAAiB,CAAC,OAAO,EAAE,MAAM,CAAC,EAAE,CAAA;AACxE,CAAC,CAAA"}

package/dist/errors.js

@@ -0,0 +1,59 @@
+/**
+ * Exit codes are part of the CLI contract:
+ *   0 ok | 1 user/validation | 2 conflict (OCC) | 3 auth | 4 network
+ */
+export const EXIT = {
+    ok: 0,
+    user: 1,
+    conflict: 2,
+    auth: 3,
+    network: 4,
+};
+export class CaiError extends Error {
+    exitCode;
+    code;
+    detail;
+    /** Set when the backend scrubbed a 5xx and the real cause is only in its log. */
+    scrubbed;
+    constructor(message, opts = {}) {
+        // Every auth-class failure must be actionable without reading docs.
+        const exitCode = opts.exitCode ?? EXIT.user;
+        const actionable = exitCode === EXIT.auth && !/cai auth login/.test(message)
+            ? `${message} Run \`cai auth login\` to re-authenticate.`
+            : message;
+        super(actionable);
+        this.name = 'CaiError';
+        this.exitCode = exitCode;
+        this.code = opts.code ?? 'ERROR';
+        this.detail = opts.detail;
+        this.scrubbed = opts.scrubbed ?? false;
+    }
+}
+export const userError = (message, code = 'VALIDATION_ERROR') => new CaiError(message, { exitCode: EXIT.user, code });
+export const authError = (message, code = 'UNAUTHORIZED') => new CaiError(message, { exitCode: EXIT.auth, code });
+export const conflictError = (message, code = 'STATE_CONFLICT') => new CaiError(message, { exitCode: EXIT.conflict, code });
+export const networkError = (message, code = 'NETWORK_ERROR') => new CaiError(message, { exitCode: EXIT.network, code });
+/**
+ * Map an HTTP status + backend error code onto a CLI exit code.
+ * 401/403 -> auth, 409 (or STATE_CONFLICT) -> conflict, 4xx -> user, 5xx -> network.
+ */
+export const exitCodeForStatus = (status, backendCode) => {
+    if (backendCode === 'STATE_CONFLICT')
+        return EXIT.conflict;
+    if (status === 401 || status === 403)
+        return EXIT.auth;
+    if (status === 409)
+        return EXIT.conflict;
+    if (status >= 500)
+        return EXIT.network;
+    if (status >= 400)
+        return EXIT.user;
+    return EXIT.user;
+};
+/** The backend's error middleware replaces every 5xx cause with this string. */
+export const SCRUBBED_MESSAGES = new Set(['Internal server error', 'INTERNAL_SERVER_ERROR']);
+export const isScrubbed = (status, message) => status >= 500 && SCRUBBED_MESSAGES.has(message.trim());
+export const SCRUBBED_HINT = 'The backend scrubbed this 5xx: the response carries no cause, and the CLI will not invent one. ' +
+    'The real stack trace is only in the backend container log ' +
+    '(feature stacks: .feature-stacks/<name>/be.log; docker: `docker logs <be-container>`).';
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

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

package/dist/index.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+import { realpathSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import { Command } from 'commander';
+import { addGlobalOptions, applyExitOverride, collectFlags, explainUnknownOptions, normalizeArgv, } from './argv.js';
+import { globalOpt } from './context.js';
+import { CaiError, EXIT } from './errors.js';
+import { emitError, setCommandPath, setJsonMode } from './output.js';
+import { registerAuth } from './commands/auth.js';
+import { registerAgent } from './commands/agent.js';
+import { registerBranch } from './commands/branch.js';
+import { registerConnection } from './commands/connection.js';
+import { registerData } from './commands/data.js';
+import { registerDeps } from './commands/deps.js';
+import { registerDoctor } from './commands/doctor.js';
+import { registerEvents } from './commands/events.js';
+import { registerExec } from './commands/exec.js';
+import { registerExpr } from './commands/expr.js';
+import { registerFlow } from './commands/flow.js';
+import { registerIntegration } from './commands/integration.js';
+import { registerNode } from './commands/node.js';
+import { registerOrganize } from './commands/organize.js';
+import { registerRun } from './commands/run.js';
+import { registerSchema } from './commands/schema.js';
+import { registerTrigger } from './commands/trigger.js';
+import { registerUse, registerWorkflow } from './commands/workflow.js';
+import { registerConnect } from './commands/connect.js';
+import { registerSkills } from './commands/skills.js';
+import { CLI_VERSION } from './version.js';
+export { CLI_VERSION } from './version.js';
+export const buildProgram = () => {
+    const program = new Command();
+    program
+        .name('cai')
+        .description('Build and operate Controller AI workflows and agents')
+        .version(CLI_VERSION)
+        // No default on --json: absent must read as `undefined` so globalOpt() keeps
+        // walking up. A `false` here would shadow a --json given after the
+        // subcommand, and vice versa.
+        .option('--json', 'machine-readable output on stdout')
+        .option('--workflow <id>', 'workflow id (overrides `cai use` and CAI_WORKFLOW)')
+        .option('--api-url <url>', 'backend base URL (overrides CAI_API_URL)')
+        .option('--id <value>', 'positional id, for ids that begin with "-"')
+        .showHelpAfterError()
+        .enablePositionalOptions();
+    registerAuth(program);
+    registerConnect(program);
+    registerSkills(program);
+    registerDoctor(program);
+    registerAgent(program);
+    registerUse(program);
+    registerWorkflow(program);
+    registerFlow(program);
+    registerIntegration(program);
+    registerNode(program);
+    registerExpr(program);
+    registerRun(program);
+    registerExec(program);
+    registerConnection(program);
+    registerBranch(program);
+    registerData(program);
+    registerDeps(program);
+    registerEvents(program);
+    registerSchema(program);
+    registerTrigger(program);
+    registerOrganize(program);
+    // The three global flags are documented as working on every command, so they
+    // are declared on every command — commander only parses an option on the
+    // command that declares it, and `cai flow list --json` must work as readily as
+    // `cai --json flow list`.
+    addGlobalOptions(program);
+    program.hook('preAction', (_thisCommand, actionCommand) => {
+        // Read from the LEAF upwards so the flag is honoured in either position.
+        setJsonMode(Boolean(globalOpt(actionCommand, 'json')));
+        const path = [];
+        let node = actionCommand;
+        while (node) {
+            path.unshift(node.name());
+            node = node.parent;
+        }
+        setCommandPath(path.join(' '));
+    });
+    return program;
+};
+const main = async () => {
+    const program = buildProgram();
+    explainUnknownOptions(program);
+    applyExitOverride(program, error => {
+        // commander's own exits (help, version, bad usage) keep their codes
+        process.exit(error.exitCode === 0 ? 0 : EXIT.user);
+    });
+    await program.parseAsync(normalizeArgv(process.argv, collectFlags(program)));
+};
+// Only drive the CLI when this module is the process entry point; the test
+// suite imports buildProgram() from here and must not trigger a parse+exit.
+// `import.meta.url` is always the REAL path, so a symlinked bin (`npm link`, or a
+// PATH shim that links dist/index.js) compares unequal to argv[1] and the CLI exits
+// 0 having printed nothing — silently, which is the worst possible failure. Resolve
+// argv[1] through realpath before comparing.
+const isEntryPoint = () => {
+    const entry = process.argv[1];
+    if (!entry)
+        return false;
+    let resolved = entry;
+    try {
+        resolved = realpathSync(entry);
+    }
+    catch {
+        // not a real file (bundled/virtual entry) — fall back to the raw argv value
+    }
+    return import.meta.url === pathToFileURL(resolved).href;
+};
+if (isEntryPoint()) {
+    main().catch(error => {
+        const caiError = error instanceof CaiError
+            ? error
+            : new CaiError(error instanceof Error ? error.message : String(error), {
+                exitCode: EXIT.user,
+                code: 'UNEXPECTED',
+            });
+        emitError(caiError);
+        process.exit(caiError.exitCode);
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/jsSource.js

@@ -0,0 +1,32 @@
+import { readFileSync } from 'node:fs';
+import { userError } from './errors.js';
+const readUtf8 = (source, encoding) => readFileSync(source, encoding);
+/**
+ * Resolve an inline expression or a UTF-8 file before any caller performs a
+ * write. `-` deliberately maps to stdin's file descriptor.
+ */
+export const resolveJsSource = (opts, settings = {}, reader = readUtf8) => {
+    const inlineFlag = settings.inlineFlag ?? '--js';
+    const fileFlag = settings.fileFlag ?? '--js-file';
+    const hasInline = opts.js !== undefined;
+    const hasFile = opts.jsFile !== undefined;
+    if (hasInline && hasFile) {
+        throw userError(`${inlineFlag} and ${fileFlag} are mutually exclusive.`, 'CONFLICTING_JS_SOURCE');
+    }
+    if (hasInline)
+        return opts.js;
+    if (hasFile) {
+        try {
+            return reader(opts.jsFile === '-' ? 0 : opts.jsFile, 'utf8');
+        }
+        catch (error) {
+            throw userError(`${fileFlag} "${opts.jsFile}" is not a readable UTF-8 file: ` +
+                `${error instanceof Error ? error.message : error}`, 'UNREADABLE_JS_FILE');
+        }
+    }
+    if (settings.required !== false) {
+        throw userError(`Pass ${inlineFlag} <expression> or ${fileFlag} <path|->.`, 'MISSING_JS_SOURCE');
+    }
+    return undefined;
+};
+//# sourceMappingURL=jsSource.js.map

package/dist/jsSource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsSource.js","sourceRoot":"","sources":["../src/jsSource.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAevC,MAAM,QAAQ,GAAe,CAAC,MAAM,EAAE,QAAQ,EAAE,EAAE,CAAC,YAAY,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAA;AAEjF;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAC7B,IAAqB,EACrB,WAA6B,EAAE,EAC/B,SAAqB,QAAQ,EACT,EAAE;IACtB,MAAM,UAAU,GAAG,QAAQ,CAAC,UAAU,IAAI,MAAM,CAAA;IAChD,MAAM,QAAQ,GAAG,QAAQ,CAAC,QAAQ,IAAI,WAAW,CAAA;IACjD,MAAM,SAAS,GAAG,IAAI,CAAC,EAAE,KAAK,SAAS,CAAA;IACvC,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,KAAK,SAAS,CAAA;IAEzC,IAAI,SAAS,IAAI,OAAO,EAAE,CAAC;QACzB,MAAM,SAAS,CACb,GAAG,UAAU,QAAQ,QAAQ,0BAA0B,EACvD,uBAAuB,CACxB,CAAA;IACH,CAAC;IACD,IAAI,SAAS;QAAE,OAAO,IAAI,CAAC,EAAE,CAAA;IAC7B,IAAI,OAAO,EAAE,CAAC;QACZ,IAAI,CAAC;YACH,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAO,EAAE,MAAM,CAAC,CAAA;QAC/D,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,SAAS,CACb,GAAG,QAAQ,KAAK,IAAI,CAAC,MAAM,kCAAkC;gBAC3D,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,EAAE,EACrD,oBAAoB,CACrB,CAAA;QACH,CAAC;IACH,CAAC;IACD,IAAI,QAAQ,CAAC,QAAQ,KAAK,KAAK,EAAE,CAAC;QAChC,MAAM,SAAS,CAAC,QAAQ,UAAU,oBAAoB,QAAQ,YAAY,EAAE,mBAAmB,CAAC,CAAA;IAClG,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC,CAAA"}

package/dist/nodeProps.js

@@ -0,0 +1,177 @@
+const NODE_PROP_WRITE_KEYS = new Set([
+    'value',
+    'valueLabel',
+    'valueJs',
+    'expressionValue',
+    'expressionValueJs',
+    'useExpression',
+]);
+const isExplicitNodePropWrite = (value) => Boolean(value) &&
+    typeof value === 'object' &&
+    !Array.isArray(value) &&
+    Object.keys(value).some(key => NODE_PROP_WRITE_KEYS.has(key));
+/**
+ * `add_node.props` is a map of per-prop write objects. Humans and skills naturally
+ * pass a direct map (`{"channel":"C123"}`), so accept both forms and normalize
+ * direct values to the backend's exact `{value: ...}` contract.
+ */
+export const normalizeNodePropWrites = (props) => Object.fromEntries(Object.entries(props).map(([key, value]) => [
+    key,
+    isExplicitNodePropWrite(value) ? value : { value },
+]));
+export const nodePropsFromPayload = (payload) => {
+    if (Array.isArray(payload))
+        return payload;
+    if (!payload || typeof payload !== 'object')
+        return [];
+    const record = payload;
+    for (const key of ['props', 'data', 'summary']) {
+        if (Array.isArray(record[key]))
+            return record[key];
+    }
+    return [];
+};
+export const hasConfiguredPropValue = (prop) => ![prop.value, prop.valueJs, prop.expressionValue, prop.expressionValueJs].every(value => value === undefined || value === null || value === '');
+// This mirrors the backend's TEXT_FAMILY_PROP_INPUT_TYPES. Callers always send
+// valueJs; the backend chooses the stored field and get_node_props decompiles it
+// back into one of these two readback channels.
+const EXPRESSION_STORED_IN_VALUE = new Set([
+    'TEXT',
+    'SHORT_TEXT',
+    'LONG_TEXT',
+    'JSON',
+    'SQL',
+    'CUSTOM_DATA',
+]);
+export const expressionReadbackChannel = (prop) => Boolean(prop.allowsExpressionMode) &&
+    !EXPRESSION_STORED_IN_VALUE.has(String(prop.inputType ?? ''))
+    ? 'expressionValueJs'
+    : 'valueJs';
+const shellQuote = (value) => `'${value.replace(/'/g, "'\\''")}'`;
+const propName = (prop) => prop.name ?? prop.key;
+const propNextCommand = (nodeId, prop, fallbackName) => {
+    const name = propName(prop ?? {}) ?? fallbackName;
+    if (prop?.remoteOptions) {
+        return (`cai node options ${nodeId} --prop ${name} --query "<option label>"; then ` +
+            `cai node set ${nodeId} --prop ${name} --value <exact-returned-value> ` +
+            '--label "<exact-returned-label>"');
+    }
+    const options = prop?.options ?? [];
+    if (options.length > 0) {
+        const values = options
+            .map(option => option.value ?? option.id)
+            .filter(value => value !== undefined);
+        const first = values[0];
+        if (first !== undefined) {
+            const multi = [
+                'MULTI_SELECT',
+                'MULTI_SELECT_DROPDOWN',
+                'STATIC_MULTI_SELECT_DROPDOWN',
+            ].includes(String(prop?.inputType ?? ''));
+            const selected = multi ? [first] : first;
+            const choices = options
+                .map(option => {
+                const value = option.value ?? option.id;
+                const label = option.label ?? option.name ?? value;
+                return `${JSON.stringify(value)} (${String(label)})`;
+            })
+                .join(', ');
+            return `cai node set ${nodeId} --prop ${name} --value ${shellQuote(typeof selected === 'string' ? selected : JSON.stringify(selected))}; advertised choices: ${choices}`;
+        }
+    }
+    const supportsExpression = EXPRESSION_STORED_IN_VALUE.has(String(prop?.inputType ?? '')) ||
+        Boolean(prop?.allowsExpressionMode);
+    if (supportsExpression) {
+        return (`Choose by intent for ${name}: literal -> cai node set ${nodeId} --prop ${name} ` +
+            `--value <value>; runtime-derived -> cai expr context ${nodeId} --prop ${name}, then ` +
+            `cai expr set ${nodeId} --prop ${name} --js <expression>`);
+    }
+    return `cai node set ${nodeId} --prop ${name} --value <value>`;
+};
+/** Pure readiness projection used by `cai node status` and its tests. */
+export const buildNodeReadiness = (nodeId, record, props) => {
+    const connectionId = record.connectionId ?? record.data?.connectionId ?? null;
+    const requireAuth = Boolean(record.requireAuth ?? record.data?.requireAuth);
+    const missingConnection = requireAuth && !connectionId;
+    const pendingReloadProps = props
+        .filter(prop => prop.reloadProps && prop.enabled !== false && !hasConfiguredPropValue(prop))
+        .map(prop => prop.name ?? prop.key)
+        .filter((name) => Boolean(name));
+    const pendingReloadSet = new Set(pendingReloadProps);
+    const missingRequiredProps = props
+        .filter(prop => prop.required &&
+        prop.enabled !== false &&
+        !hasConfiguredPropValue(prop) &&
+        !pendingReloadSet.has(prop.name ?? prop.key ?? ''))
+        .map(prop => prop.name ?? prop.key)
+        .filter((name) => Boolean(name));
+    const propsByName = new Map(props
+        .map(prop => [propName(prop), prop])
+        .filter((entry) => Boolean(entry[0])));
+    const outputs = record.outputs ?? record.data?.outputs ?? [];
+    const outputPortTypes = (Array.isArray(outputs) ? outputs : [])
+        .map((output) => output?.dataType)
+        .filter((value) => typeof value === 'string' && value.length > 0);
+    // get_node.outputs reports connection-port wrappers such as
+    // output.node.<id>#data. That says where a value came from, not what the
+    // process returned, and must never make downstream expression readiness true.
+    const processOutputType = record.processOutput?.dataType ?? record.data?.processOutput?.dataType ?? null;
+    const componentOutputType = record.resolvedOutputType ?? record.componentOutputType ?? null;
+    const outputTypes = [processOutputType ?? componentOutputType].filter((value) => typeof value === 'string' && value.length > 0);
+    const outputTypeSource = processOutputType
+        ? 'processOutput'
+        : componentOutputType
+            ? 'component'
+            : outputPortTypes.length
+                ? 'port-wrapper'
+                : 'none';
+    const isUnresolvedType = (type) => /(^|[.#])any$|unknown|unresolved/i.test(type) ||
+        /^node\./.test(type) ||
+        /^output\.node\./.test(type);
+    const outputTypeStatus = processOutputType
+        ? outputTypes.some(isUnresolvedType)
+            ? 'unresolved'
+            : 'concrete'
+        : componentOutputType || outputPortTypes.length > 0
+            ? 'unresolved'
+            : 'none';
+    const configurationBlockers = [
+        ...(missingConnection ? ['connection'] : []),
+        ...missingRequiredProps.map(name => `required prop: ${name}`),
+        ...pendingReloadProps.map(name => `reload selector: ${name}`),
+    ];
+    const blockedBy = [
+        ...configurationBlockers,
+        ...(outputTypeStatus === 'unresolved' ? ['output type'] : []),
+    ];
+    const readyForRun = configurationBlockers.length === 0;
+    const readyForExpressions = readyForRun;
+    const readyForDownstreamExpressions = readyForRun && outputTypeStatus === 'concrete';
+    const next = missingConnection
+        ? `cai connection list --node ${record.nodeSlug ?? record.data?.nodeSlug ?? '<nodeSlug>'}; then cai node set-connection ${nodeId} --connection <id> (if none exist, run cai connection connect ${record.nodeSlug ?? record.data?.nodeSlug ?? '<nodeSlug>'} and list again)`
+        : missingRequiredProps.length
+            ? propNextCommand(nodeId, propsByName.get(missingRequiredProps[0]), missingRequiredProps[0])
+            : pendingReloadProps.length
+                ? propNextCommand(nodeId, propsByName.get(pendingReloadProps[0]), pendingReloadProps[0])
+                : outputTypeStatus === 'unresolved'
+                    ? `cai run node ${nodeId} --inputs <values.json>`
+                    : `cai expr context ${nodeId} --prop <prop>`;
+    return {
+        nodeId,
+        requireAuth,
+        connectionId,
+        missingConnection,
+        missingRequiredProps,
+        pendingReloadProps,
+        outputTypeStatus,
+        outputTypes,
+        outputPortTypes,
+        outputTypeSource,
+        readyForExpressions,
+        readyForRun,
+        readyForDownstreamExpressions,
+        blockedBy,
+        next,
+    };
+};
+//# sourceMappingURL=nodeProps.js.map

package/dist/nodeProps.js.map

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

package/dist/output.js

@@ -0,0 +1,85 @@
+import { SCRUBBED_HINT } from './errors.js';
+let jsonMode = false;
+let commandPath = 'cai';
+const warnings = [];
+export const setJsonMode = (value) => {
+    jsonMode = value;
+};
+export const isJsonMode = () => jsonMode;
+export const setCommandPath = (value) => {
+    commandPath = value;
+};
+/**
+ * Never let a silent null pass unremarked — the engine turns several real
+ * failures (unknown op on a CType, missing injected source, a null resolved
+ * config) into a quiet null. Warnings go to stderr so `--json` stdout stays
+ * pipeable, and are also embedded in the JSON envelope.
+ */
+export const warn = (message) => {
+    warnings.push(message);
+    process.stderr.write(`warning: ${message}\n`);
+};
+export const emit = (data, human) => {
+    if (jsonMode) {
+        const envelope = { ok: true, command: commandPath, data };
+        if (warnings.length)
+            envelope.warnings = [...warnings];
+        process.stdout.write(`${JSON.stringify(envelope, null, 2)}\n`);
+        return;
+    }
+    human();
+};
+export const emitError = (error) => {
+    if (jsonMode) {
+        const envelope = {
+            ok: false,
+            command: commandPath,
+            error: {
+                code: error.code,
+                message: error.message,
+                ...(error.scrubbed ? { scrubbed: true } : {}),
+                ...(error.detail !== undefined ? { detail: error.detail } : {}),
+            },
+        };
+        if (warnings.length)
+            envelope.warnings = [...warnings];
+        process.stdout.write(`${JSON.stringify(envelope, null, 2)}\n`);
+        return;
+    }
+    process.stderr.write(`error: ${error.message}\n`);
+    if (error.scrubbed)
+        process.stderr.write(`\n${SCRUBBED_HINT}\n`);
+};
+const cell = (value) => {
+    if (value === null || value === undefined)
+        return '-';
+    if (typeof value === 'object')
+        return JSON.stringify(value);
+    return String(value);
+};
+/** Left-aligned fixed-width table. Empty rows print a dash line, never nothing. */
+export const table = (columns, rows) => {
+    if (rows.length === 0)
+        return '(none)';
+    const body = rows.map(r => r.map(cell));
+    const widths = columns.map((c, i) => Math.max(c.length, ...body.map(r => (r[i] ?? '').length)));
+    const line = (cells) => cells
+        .map((c, i) => c.padEnd(widths[i]))
+        .join('  ')
+        .trimEnd();
+    return [line(columns), line(widths.map(w => '-'.repeat(w))), ...body.map(line)].join('\n');
+};
+export const printTable = (columns, rows) => {
+    process.stdout.write(`${table(columns, rows)}\n`);
+};
+export const printKeyValues = (pairs) => {
+    const width = Math.max(...pairs.map(([k]) => k.length));
+    for (const [key, value] of pairs) {
+        process.stdout.write(`${key.padEnd(width)}  ${cell(value)}\n`);
+    }
+};
+export const truncate = (value, max = 80) => {
+    const text = cell(value);
+    return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+};
+//# sourceMappingURL=output.js.map