@controllerai/cli 0.2.0

package/dist/commands/trigger.js

@@ -0,0 +1,992 @@
+import { readFileSync } from 'node:fs';
+import { requireContext } from '../context.js';
+import { userError } from '../errors.js';
+import { emit, printKeyValues, printTable, truncate, warn } from '../output.js';
+/**
+ * Trigger canvases. A trigger targets exactly one flow. Real events execute
+ * LIVE after publish; explicit one-shot replay can verify either DEV or LIVE.
+ */
+/**
+ * `create_trigger.sourceBasis` is a must-ask gate enforced in the backend.
+ * Do not advertise its deliberately rejected "assumption" sentinel as a valid
+ * CLI choice: the user must answer before the command can proceed.
+ */
+const SOURCE_BASES = [
+    'explicit-in-request',
+    'user-answer',
+    'inferred-from-existing-workflow',
+];
+export const assertSourceBasis = (value) => {
+    if (!SOURCE_BASES.includes(value)) {
+        throw userError(`--source-basis must be one of ${SOURCE_BASES.join(', ')}. It declares what the trigger ` +
+            'source choice is based on; the backend rejects the call without it.', 'BAD_SOURCE_BASIS');
+    }
+    return value;
+};
+export const assertReplayTarget = (value, confirmLive) => {
+    if (value !== 'dev' && value !== 'live') {
+        throw userError('--target must be "dev" or "live".', 'BAD_REPLAY_TARGET');
+    }
+    if (value === 'live' && !confirmLive) {
+        throw userError('LIVE replay runs the published workflow and can perform real external actions. ' +
+            'Retry with `--target live --confirm-live` to acknowledge that explicitly.', 'LIVE_REPLAY_CONFIRMATION_REQUIRED');
+    }
+    if (value === 'dev' && confirmLive) {
+        throw userError('--confirm-live is only valid with `--target live`.', 'UNUSED_LIVE_CONFIRMATION');
+    }
+    return value;
+};
+export const assertTriggerTestEventsMode = (allow, disallow, acknowledgeDualRun) => {
+    if (allow === disallow) {
+        throw userError(allow
+            ? '--allow and --disallow are mutually exclusive.'
+            : 'Choose exactly one of --allow or --disallow.', allow ? 'CONFLICTING_TEST_EVENTS_MODE' : 'MISSING_TEST_EVENTS_MODE');
+    }
+    if (!allow && acknowledgeDualRun) {
+        throw userError('--acknowledge-dual-run is only valid with --allow.', 'UNUSED_DUAL_RUN_ACKNOWLEDGEMENT');
+    }
+    return allow;
+};
+export const readJsonOption = (source, flag) => {
+    let raw;
+    try {
+        raw =
+            source === '-'
+                ? readFileSync(0, 'utf8')
+                : /^[{[]/.test(source.trimStart())
+                    ? source
+                    : readFileSync(source, 'utf8');
+    }
+    catch (error) {
+        throw userError(`${flag} "${source}" is not a readable file and does not look like inline JSON ` +
+            `(inline JSON must start with "{" or "["): ${error instanceof Error ? error.message : error}`, 'UNREADABLE_JSON_OPTION');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw userError(`${flag} is neither valid JSON nor a readable file: ${error instanceof Error ? error.message : error}`, 'BAD_JSON_OPTION');
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw userError(`${flag} must be a JSON object.`, 'BAD_JSON_SHAPE');
+    }
+    return parsed;
+};
+/**
+ * The scheduled trigger's `cron` prop is an OBJECT (`{cron}` / `{intervalSeconds}`),
+ * not a string. The backend coerces a bare string, but only for `cron` — say so
+ * rather than letting a plausible-looking string deploy a broken schedule.
+ */
+export const normalizeTriggerProps = (props) => {
+    if (typeof props.cron === 'string') {
+        return { ...props, cron: { cron: props.cron } };
+    }
+    return props;
+};
+/**
+ * `get_trigger_component_props` publishes an `inputType` and nothing about the
+ * JSON shape that inputType expects. For most types the mapping is obvious;
+ * for TIMER it is not — `cron` is a prop whose VALUE is an object, and the
+ * nesting is invisible in every field the backend returns except a defaultValue
+ * that is easy to read as decoration. Naming the shape per prop is the whole
+ * difference between `trigger props` being a listing and being a contract.
+ */
+export const triggerPropValueShape = (prop) => {
+    const options = (prop?.options ?? []);
+    switch (prop?.inputType) {
+        case 'TIMER':
+            return 'object {cron?, intervalSeconds?, timezone?}';
+        case 'CHECKBOX':
+            return 'boolean';
+        case 'NUMBER':
+            return 'number';
+        case 'NUMBER_ARRAY':
+            return 'number[]';
+        case 'SHORT_TEXT_ARRAY':
+        case 'MULTI_SELECT_DROPDOWN':
+        case 'STATIC_MULTI_SELECT_DROPDOWN':
+            return 'string[]';
+        case 'OBJECT':
+        case 'JSON':
+        case 'CUSTOM_DATA':
+            return 'object';
+        case 'STATIC_DROPDOWN':
+            return options.length
+                ? `string, one of: ${options.map(o => String(o.value)).join(' | ')}`
+                : 'string';
+        case 'DROPDOWN':
+            return options.length
+                ? `string, one of: ${options.map(o => String(o.value)).join(' | ')}`
+                : 'string (dynamic — re-run with --configured to load options)';
+        default:
+            return 'string';
+    }
+};
+/** A value of the right SHAPE for a prop, so the printed example parses and deploys. */
+export const triggerPropExampleValue = (prop) => {
+    if (prop?.defaultValue !== undefined && prop?.defaultValue !== null)
+        return prop.defaultValue;
+    const firstOption = (prop?.options ?? [])[0];
+    switch (prop?.inputType) {
+        case 'TIMER':
+            return { cron: '0 9 * * *', timezone: 'America/Chicago' };
+        case 'CHECKBOX':
+            return false;
+        case 'NUMBER':
+            return 0;
+        case 'NUMBER_ARRAY':
+        case 'SHORT_TEXT_ARRAY':
+            return [];
+        case 'MULTI_SELECT_DROPDOWN':
+        case 'STATIC_MULTI_SELECT_DROPDOWN':
+            return firstOption ? [firstOption.value] : [];
+        case 'OBJECT':
+        case 'JSON':
+        case 'CUSTOM_DATA':
+            return {};
+        default:
+            return firstOption ? firstOption.value : `<${prop?.name ?? 'value'}>`;
+    }
+};
+const OPTION_INPUT_TYPES = new Set([
+    'DROPDOWN',
+    'STATIC_DROPDOWN',
+    'MULTI_SELECT',
+    'MULTI_SELECT_DROPDOWN',
+    'STATIC_MULTI_SELECT_DROPDOWN',
+    'REMOTE_OPTIONS',
+]);
+const hasConfiguredTriggerValue = (configuredProps, name) => typeof name === 'string' &&
+    Object.prototype.hasOwnProperty.call(configuredProps, name) &&
+    configuredProps[name] !== undefined &&
+    configuredProps[name] !== null &&
+    configuredProps[name] !== '';
+export const unresolvedTriggerOptionProps = (props, configuredProps = {}) => (props ?? []).filter(prop => {
+    if (!prop?.required || prop?.hidden)
+        return false;
+    if (!prop.remoteOptions && !OPTION_INPUT_TYPES.has(String(prop.inputType ?? '')))
+        return false;
+    if (hasConfiguredTriggerValue(configuredProps, prop.name))
+        return false;
+    if (prop.defaultValue !== undefined && prop.defaultValue !== null)
+        return false;
+    return !Array.isArray(prop.options) || prop.options.length === 0;
+});
+/**
+ * The `--props` object a caller can paste: every required, non-hidden prop with
+ * a shape-correct value. Hidden props are Pipedream's own reload plumbing and
+ * are never set by hand.
+ */
+export const triggerPropsExample = (props, configuredProps = {}) => {
+    const example = {};
+    const unresolved = new Set(unresolvedTriggerOptionProps(props, configuredProps));
+    for (const prop of props ?? []) {
+        if (!prop?.required || prop?.hidden || unresolved.has(prop))
+            continue;
+        example[prop.name] = hasConfiguredTriggerValue(configuredProps, prop.name)
+            ? configuredProps[prop.name]
+            : triggerPropExampleValue(prop);
+    }
+    return example;
+};
+/**
+ * The create-ready prop object for the newest dynamic schema. Values already
+ * selected by the caller win over generated defaults; values for props that
+ * disappeared during a reload are deliberately discarded.
+ */
+export const triggerPropsForCreate = (props, configuredProps = {}) => {
+    const result = triggerPropsExample(props, configuredProps);
+    for (const prop of props ?? []) {
+        if (prop?.hidden || !hasConfiguredTriggerValue(configuredProps, prop?.name))
+            continue;
+        result[prop.name] = configuredProps[prop.name];
+    }
+    return result;
+};
+export const shellQuote = (value) => `'${value.replace(/'/g, "'\\''")}'`;
+/** A complete, copyable dynamic-prop reload command for the current event. */
+export const triggerPropsReloadCommand = (opts, configuredProps, dynamicPropsId) => `cai trigger props --node ${opts.node} --event ${opts.event}` +
+    (opts.connection ? ` --connection ${opts.connection}` : '') +
+    ` --configured ${shellQuote(JSON.stringify(configuredProps))}` +
+    (dynamicPropsId ? ` --dynamic-props-id ${dynamicPropsId}` : '') +
+    ' --json';
+/** A complete option lookup that preserves the current dynamic-prop context. */
+export const triggerOptionLookupCommand = (opts, propName, configuredProps, dynamicPropsId) => `cai trigger options --node ${opts.node} --event ${opts.event} --prop ${propName}` +
+    (opts.connection ? ` --connection ${opts.connection}` : '') +
+    (Object.keys(configuredProps).length
+        ? ` --configured ${shellQuote(JSON.stringify(configuredProps))}`
+        : '') +
+    (dynamicPropsId ? ` --dynamic-props-id ${dynamicPropsId}` : '') +
+    ' --json';
+const parseOptionPage = (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;
+};
+export const buildTriggerOptionToolInput = (opts) => ({
+    nodeSlug: opts.node,
+    eventKey: opts.event,
+    propName: opts.prop,
+    ...(opts.connection ? { connectionId: Number(opts.connection) } : {}),
+    ...(opts.configuredProps ? { configuredProps: opts.configuredProps } : {}),
+    ...(opts.dynamicPropsId ? { dynamicPropsId: opts.dynamicPropsId } : {}),
+    ...(opts.query ? { query: opts.query } : {}),
+    ...(opts.page !== undefined ? { page: opts.page } : {}),
+    ...(opts.prevContext ? { prevContext: opts.prevContext } : {}),
+});
+const numericBackendTriggerId = (value) => {
+    if (typeof value === 'number' && Number.isSafeInteger(value) && value > 0)
+        return value;
+    if (typeof value === 'string' && /^\d+$/.test(value) && Number(value) > 0)
+        return Number(value);
+    return null;
+};
+const directBackendTriggerId = (trigger) => numericBackendTriggerId(trigger?.identity?.backendTriggerId ?? trigger?.backendTriggerId);
+export const triggerReadinessStage = (trigger) => {
+    if (typeof trigger?.readiness === 'string')
+        return trigger.readiness;
+    return trigger?.readiness?.stage ?? '-';
+};
+export const triggerIssueSummary = (trigger) => {
+    const issues = Array.isArray(trigger?.issues) ? trigger.issues : [];
+    if (!issues.length)
+        return 'none';
+    return issues.map((issue) => issue?.code ?? String(issue)).join(', ');
+};
+/** Normalize current lifecycle reads and the legacy flat read shape. */
+export const normalizeTriggerRow = (trigger, fallbackBackendTriggerId, requestedCanvasTriggerId) => {
+    const triggerId = trigger?.identity?.canvasTriggerId ??
+        trigger?.id ??
+        trigger?.triggerId ??
+        requestedCanvasTriggerId;
+    const enabled = typeof trigger?.devCanvasEnabled === 'boolean'
+        ? trigger.devCanvasEnabled
+        : typeof trigger?.deployment?.devCanvasEnabled === 'boolean'
+            ? trigger.deployment.devCanvasEnabled
+            : typeof trigger?.enabled === 'boolean'
+                ? trigger.enabled
+                : null;
+    const readiness = trigger?.readiness ?? null;
+    const issues = Array.isArray(trigger?.issues) ? trigger.issues : [];
+    return {
+        ...trigger,
+        id: triggerId,
+        triggerId,
+        backendTriggerId: directBackendTriggerId(trigger) ?? numericBackendTriggerId(fallbackBackendTriggerId),
+        enabled,
+        devCanvasEnabled: enabled,
+        flowId: trigger?.flowId ?? null,
+        nodeCount: trigger?.nodeCount ?? (Array.isArray(trigger?.nodes) ? trigger.nodes.length : null),
+        presence: trigger?.presence ?? null,
+        readiness,
+        issues,
+    };
+};
+/**
+ * Lifecycle reads normally expose `identity.backendTriggerId` directly. Older
+ * backends and malformed lifecycle rows may not, so recover only those missing
+ * ids from the development canvas node's `data.triggerId` as a compatibility
+ * fallback.
+ */
+export const backendTriggerIds = async (api, workflowId) => {
+    const ids = new Map();
+    const state = await api.rest(`/workflow-agent/development-version-state/${workflowId}`);
+    if (!state?.json)
+        return ids;
+    let document;
+    try {
+        document = JSON.parse(state.json);
+    }
+    catch {
+        return ids;
+    }
+    for (const trigger of document?.triggers ?? []) {
+        for (const node of trigger?.nodes ?? []) {
+            const backendId = node?.data?.triggerId;
+            if (typeof backendId === 'number')
+                ids.set(trigger.id, backendId);
+        }
+    }
+    return ids;
+};
+const normalizedTriggerRows = async (api, workflowId, rows) => {
+    const needsFallback = (rows ?? []).some(trigger => directBackendTriggerId(trigger) === null);
+    const fallbackIds = needsFallback
+        ? await backendTriggerIds(api, workflowId)
+        : new Map();
+    return (rows ?? []).map(trigger => {
+        const triggerId = trigger?.identity?.canvasTriggerId ?? trigger?.id ?? trigger?.triggerId;
+        return normalizeTriggerRow(trigger, fallbackIds.get(triggerId));
+    });
+};
+const auditBoolean = (trigger, key) => {
+    const deploymentValue = trigger?.deployment?.[key];
+    if (typeof deploymentValue === 'boolean')
+        return deploymentValue;
+    const flatValue = trigger?.[key];
+    return typeof flatValue === 'boolean' ? flatValue : undefined;
+};
+const auditLiveCanvasEnabled = (trigger) => {
+    const deploymentValue = trigger?.deployment?.liveCanvasEnabled;
+    if (typeof deploymentValue === 'boolean' || deploymentValue === null)
+        return deploymentValue;
+    const flatValue = trigger?.liveCanvasEnabled;
+    return typeof flatValue === 'boolean' || flatValue === null ? flatValue : undefined;
+};
+const triggerAuditState = (trigger) => {
+    const devCanvasEnabled = auditBoolean(trigger, 'devCanvasEnabled');
+    const liveCanvasEnabled = auditLiveCanvasEnabled(trigger);
+    const inLiveVersion = auditBoolean(trigger, 'inLiveVersion');
+    const workflowActive = auditBoolean(trigger, 'workflowActive');
+    const allowTestEvents = auditBoolean(trigger, 'allowTestEvents');
+    const reportedDevDispatchArmed = auditBoolean(trigger, 'devDispatchArmed');
+    const devDispatchArmed = reportedDevDispatchArmed ??
+        (devCanvasEnabled !== undefined && allowTestEvents !== undefined
+            ? devCanvasEnabled && allowTestEvents
+            : undefined);
+    const reportedDualDispatchLive = auditBoolean(trigger, 'dualDispatchLive');
+    const dualDispatchLive = reportedDualDispatchLive ??
+        (devDispatchArmed !== undefined &&
+            typeof liveCanvasEnabled === 'boolean' &&
+            workflowActive !== undefined
+            ? devDispatchArmed && liveCanvasEnabled && workflowActive
+            : undefined);
+    const newlyLiveOnPublish = devCanvasEnabled === true && inLiveVersion === false;
+    return {
+        devCanvasEnabled,
+        liveCanvasEnabled,
+        inLiveVersion,
+        workflowActive,
+        devDispatchArmed,
+        dualDispatchLive,
+        dualDispatchReported: reportedDualDispatchLive !== undefined,
+        liveAfterPublish: liveCanvasEnabled === true || newlyLiveOnPublish,
+        newlyLiveOnPublish,
+        reducedFidelity: liveCanvasEnabled === undefined ||
+            inLiveVersion === undefined ||
+            workflowActive === undefined ||
+            devDispatchArmed === undefined ||
+            reportedDualDispatchLive === undefined,
+    };
+};
+export const summarizeTriggerAudit = (items) => ({
+    liveAfterPublish: items.filter(item => triggerAuditState(item).liveAfterPublish),
+    armed: items.filter(item => triggerAuditState(item).devDispatchArmed === true),
+    doubleRunRisk: items.filter(item => triggerAuditState(item).dualDispatchLive === true),
+    newlyLiveOnPublish: items.filter(item => triggerAuditState(item).newlyLiveOnPublish),
+});
+const auditBooleanCell = (value) => value === true ? 'yes' : value === false ? 'no' : '-';
+const auditArmedCell = (value) => value === true ? 'armed' : value === false ? 'off' : '-';
+const auditTriggerLabel = (trigger) => `${trigger?.name || 'Unnamed trigger'} (${trigger?.triggerId ?? '-'})`;
+const auditDisarmCommand = (trigger) => `cai trigger test-events --id ${shellQuote(String(trigger?.triggerId ?? '-'))} --disallow`;
+const liveAfterPublishReason = (trigger) => {
+    const state = triggerAuditState(trigger);
+    if (state.newlyLiveOnPublish)
+        return 'dev enabled; will enter the live version on publish';
+    if (state.workflowActive === true)
+        return 'already live-enabled and workflow active';
+    if (state.workflowActive === false)
+        return 'live-enabled; publishing reactivates the workflow';
+    return 'already live-enabled; workflow active state unavailable';
+};
+export const registerTrigger = (program) => {
+    const trigger = program
+        .command('trigger')
+        .description('Trigger canvases and captured events (triggers run the LIVE version only)');
+    trigger
+        .command('list')
+        .description('Trigger lifecycle rows: ids, development state, readiness and issues')
+        .action(async (_opts, command) => {
+        const { api, workflowId } = requireContext(command);
+        const rows = await api.tool(workflowId, 'get_triggers', {});
+        const triggers = await normalizedTriggerRows(api, workflowId, rows);
+        for (const t of triggers) {
+            if (t.backendTriggerId === null) {
+                warn(`Trigger ${t.triggerId} has no recoverable backendTriggerId after checking its ` +
+                    'lifecycle identity and development canvas state — `cai trigger events` and ' +
+                    '`cai trigger replay` need that numeric id.');
+            }
+        }
+        emit({ items: triggers, triggers }, () => {
+            const includeLegacyGraph = triggers.some(t => t.flowId !== null || t.nodeCount !== null);
+            printTable([
+                'triggerId',
+                'backendTriggerId',
+                'name',
+                'enabled',
+                'presence',
+                'readiness',
+                'issues',
+                'events',
+                'testEvents',
+                ...(includeLegacyGraph ? ['flowId', 'nodes'] : []),
+            ], triggers.map(t => [
+                t.triggerId,
+                t.backendTriggerId ?? '-',
+                t.name,
+                t.enabled === true ? 'yes' : t.enabled === false ? 'no' : '-',
+                t.presence ?? '-',
+                triggerReadinessStage(t),
+                truncate(triggerIssueSummary(t), 42),
+                t.recordedEventCount ?? '-',
+                t.allowTestEvents === true ? 'allowed' : t.allowTestEvents === false ? 'off' : '-',
+                ...(includeLegacyGraph ? [t.flowId, t.nodeCount] : []),
+            ]));
+        });
+    });
+    trigger
+        .command('audit')
+        .description('Pre-publish trigger coverage, development dispatch and double-run risk')
+        .action(async (_opts, command) => {
+        const { api, workflowId } = requireContext(command);
+        const rows = await api.tool(workflowId, 'get_triggers', {});
+        const items = await normalizedTriggerRows(api, workflowId, rows);
+        const summary = summarizeTriggerAudit(items);
+        const reducedFidelityCount = items.filter(item => triggerAuditState(item).reducedFidelity).length;
+        const reducedFidelityMessage = reducedFidelityCount
+            ? `Reduced fidelity: ${reducedFidelityCount} trigger ${reducedFidelityCount === 1 ? 'row is' : 'rows are'} missing lifecycle deployment fields; unavailable values are shown as "-".`
+            : null;
+        if (reducedFidelityMessage)
+            warn(reducedFidelityMessage);
+        for (const item of summary.doubleRunRisk) {
+            warn(`DOUBLE-RUN RISK: ${auditTriggerLabel(item)} is armed for development dispatch ` +
+                'while live-active; one real event runs twice (both real, both billed). ' +
+                `Disarm with ${auditDisarmCommand(item)}.`);
+        }
+        emit({ items, summary }, () => {
+            printTable([
+                'name',
+                'flowId',
+                'triggerId',
+                'backendTriggerId',
+                'dev enabled',
+                'live enabled',
+                'in live version',
+                'test-events armed',
+            ], items.map(item => {
+                const state = triggerAuditState(item);
+                return [
+                    item.name,
+                    item.flowId,
+                    item.triggerId,
+                    item.backendTriggerId,
+                    auditBooleanCell(state.devCanvasEnabled),
+                    auditBooleanCell(state.liveCanvasEnabled),
+                    auditBooleanCell(state.inLiveVersion),
+                    auditArmedCell(state.devDispatchArmed),
+                ];
+            }));
+            process.stdout.write('\nWill start this workflow LIVE after publish:\n');
+            printTable(['trigger', 'state'], summary.liveAfterPublish.map(item => [
+                auditTriggerLabel(item),
+                liveAfterPublishReason(item),
+            ]));
+            process.stdout.write('\nArmed for dev dispatch (finish setup):\n');
+            printTable(['trigger', 'disarm command'], summary.armed.map(item => [auditTriggerLabel(item), auditDisarmCommand(item)]));
+            process.stdout.write('\nDOUBLE-RUN RISK:\n');
+            printTable(['trigger', 'impact'], summary.doubleRunRisk.map(item => [
+                auditTriggerLabel(item),
+                'one real event runs twice (both real, both billed)',
+            ]));
+            process.stdout.write('\nEnabled in dev but not in the live version yet (starts firing only after publish):\n');
+            printTable(['trigger', 'state'], summary.newlyLiveOnPublish.map(item => [
+                auditTriggerLabel(item),
+                'dev enabled; absent from live',
+            ]));
+            if (reducedFidelityMessage)
+                process.stdout.write(`\nnote: ${reducedFidelityMessage}\n`);
+        });
+    });
+    trigger
+        .command('get')
+        .argument('<triggerId>', 'canvas trigger id from `cai trigger list`')
+        .description('Full lifecycle for one trigger: capture, deployment, verification and issues')
+        .action(async (triggerId, _opts, command) => {
+        const { api, workflowId } = requireContext(command);
+        const data = await api.tool(workflowId, 'get_trigger', { triggerId });
+        const fallbackIds = directBackendTriggerId(data) === null
+            ? await backendTriggerIds(api, workflowId)
+            : new Map();
+        const normalized = normalizeTriggerRow(data, fallbackIds.get(triggerId), triggerId);
+        if (normalized.backendTriggerId === null) {
+            warn(`Trigger ${normalized.triggerId} has no recoverable backendTriggerId after checking its ` +
+                'lifecycle identity and development canvas state — `cai trigger events` and ' +
+                '`cai trigger replay` need that numeric id.');
+        }
+        emit(normalized, () => {
+            const lifecycle = Boolean(data?.identity && data?.deployment && data?.capture);
+            printKeyValues(lifecycle
+                ? [
+                    ['triggerId', normalized.triggerId],
+                    ['backendTriggerId', normalized.backendTriggerId ?? '(not recoverable)'],
+                    ['development enabled', normalized.enabled === true ? 'yes' : 'no'],
+                    ['readiness', triggerReadinessStage(normalized)],
+                    ['next action', normalized.readiness?.nextAction ?? '-'],
+                    ['issues', triggerIssueSummary(normalized)],
+                    ['captured events', normalized.capture?.recordedEventCount ?? 0],
+                    ['latest event', normalized.capture?.latestEventAt ?? '-'],
+                    ['source enabled', normalized.capture?.sourceEnabled ? 'yes' : 'no'],
+                    [
+                        'live canvas enabled',
+                        normalized.deployment?.liveCanvasEnabled === null
+                            ? '(not published)'
+                            : normalized.deployment?.liveCanvasEnabled
+                                ? 'yes'
+                                : 'no',
+                    ],
+                    ['workflow active', normalized.deployment?.workflowActive ? 'yes' : 'no'],
+                    ['live matches dev', normalized.deployment?.workflowLiveMatchesDev ? 'yes' : 'no'],
+                    ['test events allowed', normalized.deployment?.allowTestEvents ? 'yes' : 'no'],
+                    ['development dispatch', normalized.deployment?.devDispatchArmed ? 'armed' : 'off'],
+                    ['dual dispatch live', normalized.deployment?.dualDispatchLive ? 'possible' : 'no'],
+                    ['last dev run', normalized.verification?.lastDevRun?.workflowExecutionId ?? '-'],
+                    ['last live run', normalized.verification?.lastLiveRun?.workflowExecutionId ?? '-'],
+                ]
+                : [
+                    ['triggerId', normalized.triggerId],
+                    ['backendTriggerId', normalized.backendTriggerId ?? '(not recoverable)'],
+                    ['name', normalized.name],
+                    [
+                        'enabled',
+                        normalized.enabled === true ? 'yes' : normalized.enabled === false ? 'no' : '-',
+                    ],
+                    ['readiness', triggerReadinessStage(normalized)],
+                    ['issues', triggerIssueSummary(normalized)],
+                    ['flowId', normalized.flowId ?? '-'],
+                ]);
+            if (normalized.issues.length) {
+                process.stdout.write('\nissues\n');
+                printTable(['code', 'severity', 'blocksNextAction', 'detail'], normalized.issues.map((issue) => [
+                    issue.code,
+                    issue.severity,
+                    issue.blocksNextAction ? 'yes' : 'no',
+                    truncate(issue.detail, 72),
+                ]));
+            }
+            const nodes = normalized.nodes ?? [];
+            if (nodes.length) {
+                process.stdout.write('\nnodes\n');
+                printTable(['id', 'displayName', 'key'], nodes.map((n) => [
+                    n.id,
+                    n.displayName ?? n.data?.displayName,
+                    n.key ?? n.data?.key,
+                ]));
+            }
+        });
+    });
+    trigger
+        .command('test-events')
+        .argument('<triggerId>', 'canvas trigger id from `cai trigger list`')
+        .option('--allow', 'arm ambient real-event dispatch against the development canvas')
+        .option('--disallow', 'turn ambient development dispatch off')
+        .option('--acknowledge-dual-run', 'when arming, acknowledge that one real event may execute more than once')
+        .description('Set ambient development test-event dispatch (routine tests should use replay)')
+        .action(async (triggerId, opts, command) => {
+        const { api, workflowId } = requireContext(command);
+        const allow = assertTriggerTestEventsMode(Boolean(opts.allow), Boolean(opts.disallow), Boolean(opts.acknowledgeDualRun));
+        const result = await api.mutate(workflowId, () => api.tool(workflowId, 'set_trigger_test_events', {
+            triggerId,
+            allow,
+            ...(opts.acknowledgeDualRun ? { acknowledgeDualRun: true } : {}),
+        }));
+        if (result?.warning) {
+            warn(String(result.warning).replace(/set_trigger_test_events(?:\s*\([^)]*\))?/gi, `cai trigger test-events --id ${shellQuote(triggerId)} --disallow`));
+        }
+        const allowTestEvents = result?.allowTestEvents ?? allow;
+        emit({ ...result, triggerId, allowTestEvents }, () => printKeyValues([
+            ['triggerId', triggerId],
+            ['allow test events', allowTestEvents ? 'yes (allowed)' : 'no (disallowed)'],
+            ['development dispatch', result?.devDispatchArmed ? 'armed' : 'off'],
+            ['dual dispatch live', result?.dualDispatchLive ? 'possible' : 'no'],
+        ]));
+    });
+    trigger
+        .command('search')
+        .argument('[query]', 'search term, plain English')
+        .option('--node <slug>', 'also return this node’s full event list')
+        .option('--limit <n>', 'max nodes', '20')
+        .option('--events-per-node <n>', 'event rows listed per node (raise to see them all)', '6')
+        .description('Nodes that can trigger a flow, and the --event keys each one publishes')
+        .action(async (query, opts, command) => {
+        const { api, workflowId } = requireContext(command);
+        const result = await api.tool(workflowId, 'search_trigger_nodes', {
+            ...(query ? { query } : {}),
+            ...(opts.node ? { nodeSlug: opts.node } : {}),
+            limit: Number(opts.limit),
+        });
+        const nodes = result?.nodes?.data ?? result?.nodes ?? [];
+        const components = result?.components ?? [];
+        const perNode = Math.max(1, Number(opts.eventsPerNode) || 6);
+        // `eventKey` is required by both `trigger props` and `trigger create` and is
+        // published nowhere else. A one-line-per-node table truncated the very column
+        // that carries it — so the keys get their own rows, with the description that
+        // separates sibling events and the connection requirement that decides
+        // whether `--connection` is needed.
+        const eventRows = nodes.flatMap(n => (n.eventKeys ?? [])
+            .slice(0, perNode)
+            .map(e => [
+            n.slug,
+            e.key,
+            truncate(e.name, 34),
+            e.needsConnection ? 'yes' : 'no',
+            truncate(e.description ?? '-', 58),
+        ]));
+        emit({ nodes, components }, () => {
+            printTable(['slug', 'name', 'source', 'connection', 'events'], nodes.map(n => [
+                n.slug,
+                n.name,
+                n.source,
+                n.authRequired ? 'required' : 'none',
+                n.eventsCount,
+            ]));
+            process.stdout.write('\nevent keys (pass one as --event)\n');
+            printTable(['node', 'eventKey', 'name', 'conn', 'description'], eventRows);
+            for (const n of nodes) {
+                const total = (n.eventKeys ?? []).length;
+                if (total > perNode) {
+                    process.stdout.write(`… ${n.slug} has ${total} events, ${perNode} shown — ` +
+                        `cai trigger search --node ${n.slug} for the full list\n`);
+                }
+            }
+            if (components.length) {
+                process.stdout.write(`\nall events on ${opts.node}\n`);
+                printTable(['eventKey', 'name', 'conn', 'description'], components.map(c => [
+                    c.key,
+                    c.name,
+                    c.needsConnection ? 'yes' : 'no',
+                    truncate(c.description, 70),
+                ]));
+            }
+            process.stdout.write('\nnext: cai trigger props --node <slug> --event <eventKey>' +
+                ' (add --connection <id> when conn is yes; `cai connection list`)\n');
+        });
+    });
+    trigger
+        .command('props')
+        .requiredOption('--node <slug>', 'trigger node slug')
+        .requiredOption('--event <eventKey>', 'event key from `cai trigger search` — never guess it')
+        .option('--connection <id>', 'connection id when the trigger needs auth')
+        .option('--configured <json|file|->', 'already-set prop values, for dependent dynamic props')
+        .option('--dynamic-props-id <id>', 'dynamicPropsId from a previous call, to reload')
+        .description('Configurable props for a trigger event; returns the dynamicPropsId to reuse')
+        .action(async (opts, command) => {
+        const { api, workflowId } = requireContext(command);
+        const configuredProps = opts.configured
+            ? readJsonOption(opts.configured, '--configured')
+            : undefined;
+        const data = await api.tool(workflowId, 'get_trigger_component_props', {
+            nodeSlug: opts.node,
+            eventKey: opts.event,
+            ...(opts.connection ? { connectionId: Number(opts.connection) } : {}),
+            ...(configuredProps ? { configuredProps } : {}),
+            ...(opts.dynamicPropsId ? { dynamicPropsId: opts.dynamicPropsId } : {}),
+        });
+        const props = data?.props ?? [];
+        const propsForCreate = triggerPropsForCreate(props, configuredProps ?? {});
+        const unresolvedOptions = unresolvedTriggerOptionProps(props, configuredProps ?? {});
+        const unresolvedOptionProps = unresolvedOptions
+            .map(prop => prop.name)
+            .filter((name) => Boolean(name));
+        const readyForCreate = unresolvedOptionProps.length === 0;
+        const dynamicPropsId = data?.id || '';
+        emit({
+            ...data,
+            propsExample: propsForCreate,
+            propsForCreate,
+            readyForCreate,
+            unresolvedOptionProps,
+        }, () => {
+            printKeyValues([
+                ['node', opts.node],
+                ['event', opts.event],
+                ['dynamicPropsId', dynamicPropsId || '(none — registry nodes have no dynamic props)'],
+                ['ready for create', readyForCreate ? 'yes' : 'no — resolve required options below'],
+            ]);
+            if (!props.length) {
+                process.stdout.write('\nThis event has no configurable props — omit --props on `cai trigger create`.\n');
+            }
+            else {
+                process.stdout.write('\nprops\n');
+                printTable(['name', 'displayName', 'inputType', 'valueShape', 'required', 'default'], props.map(p => [
+                    p.name,
+                    truncate(p.displayName, 28),
+                    p.inputType,
+                    triggerPropValueShape(p),
+                    p.required ? 'yes' : '',
+                    p.hidden ? '(hidden — leave unset)' : truncate(p.defaultValue, 34),
+                ]));
+                // inputType names the widget, not the JSON. Print the object that goes
+                // into --props so the shape never has to be inferred from the widget.
+                process.stdout.write(readyForCreate
+                    ? '\n--props value (configured values plus required defaults):\n'
+                    : '\nresolved required props so far (not yet a create-ready object):\n');
+                process.stdout.write(`  ${shellQuote(JSON.stringify(propsForCreate))}\n`);
+                if (props.some(p => p.inputType === 'TIMER')) {
+                    process.stdout.write('\nTIMER props take an OBJECT, not a string: {"cron":"0 9 * * *",' +
+                        '"timezone":"America/Chicago"} for a cron schedule, or {"intervalSeconds":900} ' +
+                        'for a fixed interval. A bare string is coerced to {"cron": "…"} and silently ' +
+                        'loses the timezone.\n');
+                }
+                if (props.some(p => p.reloadProps && !p.hidden)) {
+                    const reloadCommand = triggerPropsReloadCommand(opts, propsForCreate, dynamicPropsId || undefined);
+                    process.stdout.write('\nProps marked reloadProps change the prop set. Set their values, then re-run ' +
+                        'this complete command to see the props they unlock:\n' +
+                        `  ${reloadCommand}\n`);
+                }
+                if (unresolvedOptions.length) {
+                    process.stdout.write('\nRequired option props have no advertised values yet. Resolve each one; copy an ' +
+                        'exact returned value (not its label), merge it into --configured, then rerun ' +
+                        '`cai trigger props`:\n');
+                    for (const prop of unresolvedOptions) {
+                        process.stdout.write(`  ${triggerOptionLookupCommand(opts, prop.name, propsForCreate, dynamicPropsId || undefined)}\n`);
+                    }
+                }
+            }
+            if (readyForCreate) {
+                process.stdout.write(`\nnext: cai trigger create --flow <flowId> --node ${opts.node} --event ${opts.event} ` +
+                    '--source-basis <explicit-in-request|user-answer|inferred-from-existing-workflow>' +
+                    (opts.connection ? ` --connection ${opts.connection}` : '') +
+                    (dynamicPropsId ? ` --dynamic-props-id ${dynamicPropsId}` : '') +
+                    (props.length ? ` --props ${shellQuote(JSON.stringify(propsForCreate))}` : '') +
+                    '\n');
+            }
+        });
+    });
+    trigger
+        .command('options')
+        .requiredOption('--node <slug>', 'trigger node slug')
+        .requiredOption('--event <eventKey>', 'event key from `cai trigger search`')
+        .requiredOption('--prop <name>', 'option-backed prop name from `cai trigger props`')
+        .option('--connection <id>', 'connection id when the trigger needs auth')
+        .option('--configured <json|file|->', 'already-set trigger prop values')
+        .option('--dynamic-props-id <id>', 'dynamicPropsId from `cai trigger props`')
+        .option('--query <text>', 'search by human option label')
+        .option('--page <n>', '0-based option page when not searching')
+        .option('--prev-context <json|file|->', 'context returned by a previous options page')
+        .description('Resolve exact values for one trigger dropdown prop before trigger creation')
+        .action(async (opts, command) => {
+        const { api, workflowId } = requireContext(command);
+        const configuredProps = opts.configured
+            ? readJsonOption(opts.configured, '--configured')
+            : undefined;
+        const prevContext = opts.prevContext
+            ? readJsonOption(opts.prevContext, '--prev-context')
+            : undefined;
+        const page = parseOptionPage(opts.page);
+        const data = await api.tool(workflowId, 'get_trigger_prop_options', buildTriggerOptionToolInput({
+            node: opts.node,
+            event: opts.event,
+            prop: opts.prop,
+            connection: opts.connection,
+            configuredProps,
+            dynamicPropsId: opts.dynamicPropsId,
+            query: opts.query,
+            page,
+            prevContext,
+        }));
+        emit(data, () => {
+            printKeyValues([
+                ['prop', opts.prop],
+                ['source', data?.source ?? '-'],
+                ['context', data?.context ? JSON.stringify(data.context) : '(none)'],
+            ]);
+            printTable(['label', 'value'], (data?.options ?? []).map((option) => [option.label, JSON.stringify(option.value)]));
+            process.stdout.write('\nCopy the exact returned value into --configured, then rerun `cai trigger props`; ' +
+                'do not substitute the display label.\n');
+        });
+    });
+    trigger
+        .command('create')
+        .requiredOption('--flow <flowId>', 'flow this trigger runs (a trigger targets exactly one)')
+        .requiredOption('--node <slug>', 'trigger node slug')
+        .requiredOption('--event <eventKey>', 'event key from `cai trigger search` — never guess it')
+        .requiredOption('--source-basis <basis>', `one of ${SOURCE_BASES.join(' | ')}`)
+        .option('--connection <id>', 'connection id when the trigger needs auth')
+        .option('--props <json|file|->', 'configured prop values')
+        .option('--dynamic-props-id <id>', 'dynamicPropsId from `cai trigger props`')
+        .description('Create a trigger source and its canvas')
+        .action(async (opts, command) => {
+        const { api, workflowId } = requireContext(command);
+        assertSourceBasis(opts.sourceBasis);
+        const props = opts.props
+            ? normalizeTriggerProps(readJsonOption(opts.props, '--props'))
+            : undefined;
+        const result = await api.mutate(workflowId, () => api.tool(workflowId, 'create_trigger', {
+            flowId: opts.flow,
+            nodeSlug: opts.node,
+            eventKey: opts.event,
+            // The public backend handler consumes sourceBasis but does not persist
+            // sourceEvidence, so do not offer a flag whose value would be dropped.
+            sourceBasis: opts.sourceBasis,
+            ...(opts.connection ? { connectionId: Number(opts.connection) } : {}),
+            ...(props ? { props } : {}),
+            ...(opts.dynamicPropsId ? { dynamicPropsId: opts.dynamicPropsId } : {}),
+        }));
+        warn('Trigger data does NOT flow into the target flow automatically: the run-subflow node ' +
+            'grows one mapping prop per flow input, and only after those inputs exist. Read ' +
+            'nextSteps and follow them in order. The trigger stays inert until `cai workflow publish`.');
+        emit(result, () => {
+            printKeyValues([
+                ['triggerId (canvas)', result?.triggerId],
+                ['backendTriggerId', result?.backendTriggerId],
+                ['triggerNodeId', result?.triggerNodeId],
+                ['runSubflowNodeId', result?.runSubflowNodeId],
+                ['webhookUrl', result?.webhookUrl ?? '-'],
+                ['emailAddress', result?.emailAddress ?? '-'],
+                ['schedule', result?.schedule ?? '-'],
+            ]);
+            if ((result?.nextSteps ?? []).length) {
+                process.stdout.write('\nnextSteps (in order)\n');
+                for (const [i, step] of result.nextSteps.entries()) {
+                    process.stdout.write(`${i + 1}. ${step}\n`);
+                }
+            }
+        });
+    });
+    trigger
+        .command('events')
+        .requiredOption('--trigger <backendTriggerId>', 'the NUMERIC backendTriggerId, not the canvas id')
+        .option('--limit <n>', 'newest-first page size (default 5, max 50)')
+        .description('Captured events for a trigger source — compact payload previews')
+        .action(async (opts, command) => {
+        const { api, workflowId } = requireContext(command);
+        const triggerId = Number(opts.trigger);
+        if (!Number.isInteger(triggerId)) {
+            throw userError('--trigger takes the NUMERIC backendTriggerId (from `cai trigger create`), not the ' +
+                'canvas trigger id used by get/rename/delete. The two id spaces are different.', 'BAD_TRIGGER_ID');
+        }
+        const response = await api.tool(workflowId, 'get_trigger_events', {
+            triggerId,
+            ...(opts.limit ? { limit: Number(opts.limit) } : {}),
+        });
+        // Envelope shape since the trigger-lifecycle BE branch: { events, capture }.
+        // The array fallback keeps this command working against older backends.
+        const rows = Array.isArray(response) ? response : (response?.events ?? []);
+        const capture = Array.isArray(response) ? undefined : response?.capture;
+        if (!rows.length) {
+            warn(capture?.emptyState ??
+                capture?.note ??
+                'No captured events. Sample-event selection and replay both need at least one — ' +
+                    'send a real event to the trigger source first.');
+        }
+        emit({ triggerId, events: rows ?? [] }, () => printTable(['eventId', 'createdAt', 'dataTypeName', 'payloadPreview'], (rows ?? []).map(e => [
+            e.id,
+            e.createdAt,
+            e.dataTypeName ?? '-',
+            truncate(e.payloadPreview, 60),
+        ])));
+    });
+    trigger
+        .command('event')
+        .argument('<eventId>', 'captured event id from `cai trigger events`')
+        .description('One captured event with its full payload')
+        .action(async (eventId, _opts, command) => {
+        const { api, workflowId } = requireContext(command);
+        const data = await api.tool(workflowId, 'get_trigger_event', { eventId: Number(eventId) });
+        if (data?.payload?._truncated || data?._truncated) {
+            warn('Payload over 8KB — the backend returned {_truncated, totalChars, preview} instead of ' +
+                'the whole thing. This is a preview, not the event.');
+        }
+        emit(data, () => process.stdout.write(`${JSON.stringify(data, null, 2)}\n`));
+    });
+    trigger
+        .command('select-event')
+        .requiredOption('--node <triggerNodeId>', 'trigger node id from `cai trigger create`')
+        .requiredOption('--event <eventId>', 'captured event id')
+        .description('Adopt a captured event as the trigger’s sample, defining its output schema')
+        .action(async (opts, command) => {
+        const { api, workflowId } = requireContext(command);
+        const result = await api.mutate(workflowId, () => api.tool(workflowId, 'select_trigger_event', {
+            triggerNodeId: opts.node,
+            eventId: Number(opts.event),
+        }));
+        if (!result?.note) {
+            warn('The selection defines the trigger OUTPUT SCHEMA only when the event carries a ' +
+                'dataTypeName. Without one the sample is stored but downstream bindings stay ' +
+                'untyped — check `cai expr context <downstream node>` before writing expressions.');
+        }
+        emit(result, () => printKeyValues([
+            ['triggerNodeId', opts.node],
+            ['eventId', opts.event],
+            ['note', result?.note ?? '(none — see the warning above)'],
+        ]));
+    });
+    trigger
+        .command('replay')
+        .requiredOption('--trigger <backendTriggerId>', 'the NUMERIC backendTriggerId')
+        .option('--event <eventId>', 'captured event to replay (exclusive with --payload)')
+        .option('--payload <json|file|->', 'custom raw payload (exclusive with --event)')
+        .option('--target <dev|live>', 'DEV pre-publish or LIVE post-publish verification', 'dev')
+        .option('--confirm-live', 'acknowledge LIVE replay side effects and usage', false)
+        .description('Replay through real ingestion; defaults to safe DEV-rail verification')
+        .action(async (opts, command) => {
+        const { api, workflowId } = requireContext(command);
+        if (opts.event && opts.payload) {
+            throw userError('--event and --payload are mutually exclusive.', 'CONFLICTING_REPLAY_INPUT');
+        }
+        const target = assertReplayTarget(opts.target, Boolean(opts.confirmLive));
+        const triggerId = Number(opts.trigger);
+        if (!Number.isInteger(triggerId) || triggerId <= 0) {
+            throw userError('--trigger must be a positive numeric backendTriggerId.', 'BAD_TRIGGER_ID');
+        }
+        warn(target === 'live'
+            ? 'LIVE replay executes the published workflow: external actions fire and usage is spent.'
+            : 'DEV replay does not dispatch live, but it still executes real external actions and spends usage.');
+        const result = await api.tool(workflowId, 'replay_trigger_event', {
+            triggerId,
+            target,
+            ...(opts.event ? { eventId: Number(opts.event) } : {}),
+            ...(opts.payload ? { payload: readJsonOption(opts.payload, '--payload') } : {}),
+        });
+        for (const w of result?.warnings ?? [])
+            warn(String(w));
+        emit(result, () => printKeyValues([
+            ['target', target],
+            ['workflowExecutionId', result?.workflowExecutionId ?? '-'],
+            ['eventId', result?.eventId ?? '-'],
+            ['next', 'cai exec tree <workflowExecutionId> — and check resolvedConfigs'],
+        ]));
+    });
+    trigger
+        .command('toggle')
+        .argument('<triggerId>', 'canvas trigger id')
+        .description('Flip a trigger between enabled and disabled (a toggle, not a setter)')
+        .action(async (triggerId, _opts, command) => {
+        const { api, workflowId } = requireContext(command);
+        const result = await api.mutate(workflowId, () => api.tool(workflowId, 'toggle_trigger_enabled', { triggerId }));
+        warn('toggle_trigger_enabled flips the current state — there is no set-to-enabled tool. ' +
+            'Read `cai trigger list` afterwards to see which way it went.');
+        emit({ triggerId, result }, () => printKeyValues([
+            ['triggerId', triggerId],
+            ['result', JSON.stringify(result)],
+        ]));
+    });
+    trigger
+        .command('rename')
+        .argument('<triggerId>', 'canvas trigger id')
+        .requiredOption('--name <name>')
+        .description('Rename a trigger')
+        .action(async (triggerId, opts, command) => {
+        const { api, workflowId } = requireContext(command);
+        const result = await api.mutate(workflowId, () => api.tool(workflowId, 'rename_trigger', { triggerId, name: opts.name }));
+        emit({ triggerId, name: opts.name, result }, () => printKeyValues([
+            ['triggerId', triggerId],
+            ['name', opts.name],
+        ]));
+    });
+    trigger
+        .command('delete')
+        .argument('<triggerId>', 'canvas trigger id')
+        .description('Delete a trigger and its canvas')
+        .action(async (triggerId, _opts, command) => {
+        const { api, workflowId } = requireContext(command);
+        const result = await api.mutate(workflowId, () => api.tool(workflowId, 'delete_trigger', { triggerId }));
+        emit({ triggerId, result }, () => printKeyValues([['deleted', triggerId]]));
+    });
+};
+//# sourceMappingURL=trigger.js.map