@trydreamstate/cli 1.3.2 → 1.3.4

package/dist/commands/shared.js

@@ -11,9 +11,11 @@ const node_util_1 = require("node:util");
 // main and no generator, so they still carry pre-cutover spellings, and
 // audit:canonical-cutover:clean treats importing them as a release blocker.
 const index_1 = require("../index");
+const errors_1 = require("../errors");
+const gatedRun_1 = require("../gatedRun");
 const node_fs_1 = require("node:fs");
 const runWait_1 = require("../runWait");
-const MODES = ['dry_run', 'live', 'smoke_test'];
+const runContract_1 = require("../runContract");
 function parseObject(raw, flag) {
     try {
         const value = JSON.parse(raw);
@@ -22,153 +24,147 @@ function parseObject(raw, flag) {
         return value;
     }
     catch (error) {
-        throw new index_1.CliUsageError(`${flag} ${error instanceof Error ? error.message : 'is invalid JSON'}`);
+        throw new errors_1.CliUsageError(`${flag} ${error instanceof Error ? error.message : 'is invalid JSON'}`);
     }
 }
-function parseJson(raw, flag) {
-    try {
-        return JSON.parse(raw);
-    }
-    catch {
-        throw new index_1.CliUsageError(`${flag} must contain valid JSON`);
+/**
+ * Canonical parameter flags are deliberately open-ended.  A pack verb only owns
+ * its route and positional aliases; `--field-name value` becomes `field_name` and
+ * is checked against the live `tools get` schema before execution.  This keeps a
+ * newly published schema field usable without another CLI flag-table release.
+ */
+function takeSchemaFlags(argv, known) {
+    const kept = [];
+    const params = {};
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (!token.startsWith('--') || token === '--' || known.has(token.slice(2).split('=', 1)[0])) {
+            kept.push(token);
+            continue;
+        }
+        const equals = token.indexOf('=');
+        const name = (equals < 0 ? token.slice(2) : token.slice(2, equals)).replace(/-/g, '_');
+        if (!name) {
+            kept.push(token);
+            continue;
+        }
+        if (name === 'agent_session_id') {
+            throw new errors_1.CliUsageError('--agent-session-id is not accepted by the CLI: only the in-app Architect may name an Architect session.');
+        }
+        if (equals >= 0) {
+            params[name] = token.slice(equals + 1);
+            continue;
+        }
+        const value = argv[index + 1];
+        if (value !== undefined && !value.startsWith('--')) {
+            params[name] = value;
+            index += 1;
+        }
+        else
+            params[name] = true;
     }
+    return { argv: kept, params };
 }
 function parseMode(value) {
     if (value === undefined)
         return undefined;
-    if (MODES.includes(value))
+    if (runContract_1.RUN_MODES.includes(value))
         return value;
-    throw new index_1.CliUsageError(`--mode must be one of: ${MODES.join(', ')}`);
+    throw new errors_1.CliUsageError(`--mode must be one of: ${runContract_1.RUN_MODES.join(', ')}`);
 }
 function buildPackParser(pack, kind, specs, usage) {
     return (argv) => {
         const spec = specs.find((candidate) => candidate.verb === argv[0]);
         if (!spec)
-            throw new index_1.CliUsageError(`Unknown ${pack} verb: ${argv[0] ?? '(missing)'}\n${usage}`);
+            throw new errors_1.CliUsageError(`Unknown ${pack} verb: ${argv[0] ?? '(missing)'}\n${usage}`);
+        // The door inputs here are the same ones `tools run` takes (parseTools in index.ts),
+        // and they reach the same gate (runGated): a verb is never a quieter way to run.
         const options = {
-            mode: { type: 'string' }, 'dry-run': { type: 'boolean' }, live: { type: 'boolean' }, 'agent-session-id': { type: 'string' },
+            mode: { type: 'string' }, 'dry-run': { type: 'boolean' }, live: { type: 'boolean' },
             'idempotency-key': { type: 'string' }, 'max-credits': { type: 'string' }, params: { type: 'string' },
+            'max-live-sends': { type: 'string' },
+            approved: { type: 'boolean' }, 'approval-id': { type: 'string' }, 'approved-effect-unknown': { type: 'boolean' },
+            'quote-hash': { type: 'string' }, 'turn-token': { type: 'string' },
             'wait-timeout': { type: 'string' }, 'no-wait': { type: 'boolean' }, 'json-output': { type: 'boolean' }, open: { type: 'boolean' }, help: { type: 'boolean', short: 'h' },
         };
-        // A verb that takes a JSON document on a flag also takes it from a file, so a
-        // whole authored document can be linted or imported straight off disk instead of
-        // being pasted through the shell. The competitor authors this way and it is the
-        // only thing their file workflow had that ours did not.
-        // A verb that declares its own `file` flag owns the name, for example init, whose
-        // --file is where the scaffold is written rather than a document to read.
-        const declaresOwnFile = Object.keys(spec.flags ?? {}).includes('file');
-        const jsonFlag = declaresOwnFile
-            ? undefined
-            : Object.entries(spec.flags ?? {}).find(([, definition]) => definition.document === true);
-        if (!declaresOwnFile)
-            options.file = { type: 'string' };
-        for (const [flag, definition] of Object.entries(spec.flags ?? {}))
-            options[flag] = { type: definition.type };
+        const schemaFlags = takeSchemaFlags(argv.slice(1), new Set(Object.keys(options)));
         let values;
         let positionals;
         try {
-            ({ values, positionals } = (0, node_util_1.parseArgs)({ args: argv.slice(1), options, allowPositionals: true, strict: true }));
+            ({ values, positionals } = (0, node_util_1.parseArgs)({ args: schemaFlags.argv, options, allowPositionals: true, strict: true }));
         }
         catch (error) {
-            throw new index_1.CliUsageError(`${error instanceof Error ? error.message : 'Invalid arguments.'}\n${usage}`);
+            // parseArgs raises a TypeError whose class can come from another realm, so read the message
+            // instead of trusting instanceof: otherwise the user sees 'Invalid arguments.' and not the flag.
+            const reason = error?.message;
+            throw new errors_1.CliUsageError(`${typeof reason === 'string' && reason ? reason : 'Invalid arguments.'}\n${usage}`);
         }
         const mode = values.mode;
         const dryRun = values['dry-run'];
         const live = values.live;
-        const agentSessionId = values['agent-session-id'];
         const idempotencyKey = values['idempotency-key'];
+        if (idempotencyKey !== undefined && idempotencyKey.length > runContract_1.IDEMPOTENCY_KEY_MAX_LENGTH) {
+            throw new errors_1.CliUsageError(`--idempotency-key must be at most ${runContract_1.IDEMPOTENCY_KEY_MAX_LENGTH} characters`);
+        }
         const rawParams = values.params;
         const rawMaxCredits = values['max-credits'];
+        const rawMaxLiveSends = values['max-live-sends'];
         const rawWaitTimeout = values['wait-timeout'];
         if (values.help)
             return { command: 'pack_help', usage, ...(values['json-output'] ? { jsonOutput: true } : {}) };
-        for (const [flag, definition] of Object.entries(spec.flags ?? {})) {
-            if (definition.required && values[flag] === undefined)
-                throw new index_1.CliUsageError(`--${flag} is required for ${pack} ${spec.verb}.\n${usage}`);
-        }
         const positional = spec.positional ?? [];
-        // A document supplied inline or from a file is authored, not saved, so there is no
-        // id to name yet. lint and its kin accept a hypothetical document, which is the
-        // whole point of authoring in a file before anything exists in the workspace.
-        const documentSupplied = values.file !== undefined
-            || (jsonFlag !== undefined && values[jsonFlag[0]] !== undefined);
         const requiredPositionals = positional.filter((definition) => definition.optional !== true).length;
         const positionalsAcceptable = positionals.length <= positional.length
-            && (positionals.length >= requiredPositionals || (documentSupplied && positionals.length === 0));
+            && positionals.length >= requiredPositionals;
         if (!positionalsAcceptable)
-            throw new index_1.CliUsageError(`Usage: ${usage}`);
+            throw new errors_1.CliUsageError(`Usage: ${usage}`);
         if ((mode && (dryRun || live)) || (dryRun && live)) {
-            throw new index_1.CliUsageError('Use exactly one of --mode, --dry-run, or --live.');
+            throw new errors_1.CliUsageError('Use exactly one of --mode, --dry-run, or --live.');
         }
-        const input = rawParams ? parseObject(rawParams, '--params') : {};
+        const input = { ...(rawParams ? parseObject(rawParams, '--params') : {}), ...schemaFlags.params };
         positional.forEach((definition, index) => {
             const value = positionals[index];
             if (value !== undefined)
                 input[definition.into] = value;
         });
-        for (const [flag, definition] of Object.entries(spec.flags ?? {})) {
-            const value = values[flag];
-            if (value === undefined)
-                continue;
-            if (definition.json) {
-                input[definition.into] = parseJson(String(value), `--${flag}`);
-            }
-            else if (definition.number) {
-                const parsedNumber = Number(String(value));
-                if (!Number.isFinite(parsedNumber))
-                    throw new index_1.CliUsageError(`--${flag} must be a number`);
-                input[definition.into] = parsedNumber;
-            }
-            else {
-                input[definition.into] = value;
-            }
-        }
-        const filePath = declaresOwnFile ? undefined : values.file;
-        if (filePath !== undefined) {
-            if (jsonFlag && values[jsonFlag[0]] !== undefined) {
-                throw new index_1.CliUsageError(`Use either --${jsonFlag[0]} or --file, not both.`);
-            }
-            let contents;
-            try {
-                contents = (0, node_fs_1.readFileSync)(filePath, 'utf8');
-            }
-            catch (error) {
-                throw new index_1.CliUsageError(`--file could not be read: ${error instanceof Error ? error.message : String(error)}`);
-            }
-            const parsed = parseJson(contents, `--file ${filePath}`);
-            if (jsonFlag) {
-                input[jsonFlag[1].into] = parsed;
-            }
-            else if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
-                // A verb with no single document flag spreads the file's fields across its
-                // params, which is what `dreamstate <pack> init` writes and what `create`
-                // needs: name and steps are separate params there, not one document. Without
-                // this, the scaffold composed with no verb at all.
-                Object.assign(input, parsed);
-            }
-            else {
-                throw new index_1.CliUsageError(`--file for ${pack} ${spec.verb} must contain a JSON object of params.`);
-            }
-        }
         // kind is the discriminator of the SHARED authoring family only. The
         // family-specific capabilities have strict schemas that do not declare it,
         // so injecting it everywhere made every one of those verbs fail validation
         // with an unrecognized key before it reached the server's real work.
         if (spec.capabilityId.startsWith('workflow.automations.'))
             input.kind = kind;
+        // No default mode. A mutating verb run with no mode used to be rewritten to dry_run
+        // silently, where `tools run` sends none and lets the server answer mode_required
+        // with its repair; one rule for both now, so a person is told to choose.
         const explicitMode = dryRun ? 'dry_run' : live ? 'live' : parseMode(mode);
         const maxCredits = rawMaxCredits === undefined ? undefined : Number(rawMaxCredits);
         if (maxCredits !== undefined && (!Number.isFinite(maxCredits) || maxCredits < 0))
-            throw new index_1.CliUsageError('--max-credits must be a non-negative number');
+            throw new errors_1.CliUsageError('--max-credits must be a non-negative number');
+        const maxLiveSends = rawMaxLiveSends === undefined ? undefined : Number(rawMaxLiveSends);
+        if (maxLiveSends !== undefined && (!Number.isInteger(maxLiveSends) || maxLiveSends < 1))
+            throw new errors_1.CliUsageError('--max-live-sends must be an integer greater than or equal to 1');
+        const quoteHash = values['quote-hash'];
+        if (quoteHash !== undefined && !runContract_1.QUOTE_HASH_PATTERN.test(quoteHash))
+            throw new errors_1.CliUsageError('--quote-hash must be the sha256:<64 hex> quote_hash a dry run returned');
+        const approvalId = values['approval-id'];
+        if (approvalId !== undefined && !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(approvalId))
+            throw new errors_1.CliUsageError('--approval-id must be the uuid of a recorded approval');
         const waitTimeout = rawWaitTimeout === undefined ? 120 : Number(rawWaitTimeout);
         if (!Number.isFinite(waitTimeout) || waitTimeout < 0)
-            throw new index_1.CliUsageError('--wait-timeout must be a non-negative number');
+            throw new errors_1.CliUsageError('--wait-timeout must be a non-negative number');
         return {
             command: 'pack', pack, verb: spec.verb, capabilityId: spec.capabilityId, input,
-            ...(explicitMode ? { mode: explicitMode } : spec.mutating ? { mode: 'dry_run' } : {}),
-            ...(agentSessionId ? { agentSessionId } : {}),
+            ...(explicitMode ? { mode: explicitMode } : {}),
+            // --approved is the caller's assertion that a person saw the dry run and agreed. It only
+            // means something on a live run, so no other mode ever sends it (same rule as tools run).
+            ...(values.approved && explicitMode === 'live' ? { approved: true } : {}),
+            ...(approvalId ? { approvalId } : {}),
+            ...(values['approved-effect-unknown'] ? { approvedEffectUnknown: true } : {}),
+            ...(quoteHash ? { quoteHash } : {}),
+            ...(values['turn-token'] ? { turnToken: values['turn-token'] } : {}),
             ...(idempotencyKey ? { idempotencyKey } : {}),
             ...(maxCredits === undefined ? {} : { maxCredits }), ...(values['json-output'] ? { jsonOutput: true } : {}),
+            ...(maxLiveSends === undefined ? {} : { maxLiveSends }),
             waitTimeout, ...(values['no-wait'] ? { noWait: true } : {}),
             ...(values.open ? { open: true } : {}),
         };
@@ -181,47 +177,21 @@ function buildPackParser(pack, kind, specs, usage) {
  * usefully, rather than to guess a valid sequence on the caller's behalf.
  */
 function packScaffold(kind, name) {
-    // The step fields are FLAT and the step carries an id. An earlier scaffold nested
-    // channel/action under `fields` and omitted the id, and the document it wrote was
-    // refused by our own lint with `node_contract_unresolved: Node unknown has no
-    // canonical node-contract mapping`, because canonicalSequenceStepContractNode reads
-    // step.kind and step.action off the step itself. A scaffold whose output the next
-    // command in its own printed next_steps rejects is worse than no scaffold.
+    // Empty graph. Step and node shapes belong to the server contract, not a second copy here.
     return kind === 'sequence'
-        ? {
-            kind: 'sequence',
-            name,
-            steps: [
-                {
-                    id: 'step_1',
-                    kind: 'email',
-                    channel: 'email',
-                    action: 'send_email',
-                    subject_template: 'Quick question, {{first_name}}',
-                    body_template: 'Hi {{first_name}},\n\nWould this be useful to you?',
-                },
-            ],
-        }
-        : {
-            kind: 'workflow',
-            name,
-            nodes: [
-                { id: 'trigger-root', type: 'trigger', position: { x: 0, y: 0 }, data: { kind: 'trigger', subtype: 'table', config: {} } },
-                { id: 'action-example', type: 'action', position: { x: 0, y: 160 }, data: { kind: 'action', subtype: 'send_connection_request_to_contact', config: {} } },
-            ],
-            edges: [{ id: 'edge-trigger-action', source: 'trigger-root', target: 'action-example' }],
-        };
+        ? { kind: 'sequence', name, steps: [] }
+        : { kind: 'workflow', name, nodes: [], edges: [] };
 }
 function runPackInit(kind, command, stdout) {
     if (command.command !== 'pack')
-        throw new index_1.CliUsageError('Pack command required.');
+        throw new errors_1.CliUsageError('Pack command required.');
     const input = command.input;
     const name = typeof input.name === 'string' && input.name.trim() ? input.name.trim() : `My ${kind}`;
     const target = typeof input.file === 'string' && input.file.trim()
         ? input.file.trim()
         : `./${kind}.json`;
     if ((0, node_fs_1.existsSync)(target)) {
-        throw new index_1.CliUsageError(`${target} already exists. Pass --file <path> to write somewhere else.`);
+        throw new errors_1.CliUsageError(`${target} already exists. Pass --file <path> to write somewhere else.`);
     }
     const document = packScaffold(kind, name);
     (0, node_fs_1.writeFileSync)(target, `${JSON.stringify(document, null, 2)}\n`, 'utf8');
@@ -237,27 +207,25 @@ function runPackInit(kind, command, stdout) {
         },
     }, null, command.jsonOutput ? 0 : 2)}\n`);
 }
-async function runPackCommand(client, command, stdout, sleep = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds))) {
+/**
+ * Verbs whose request needs the current version ids of the thing they act on.
+ * Keyed by the capability the verb runs, never by the verb's name: `sequences
+ * publish` and `workflows publish` share a name and nothing else (the sequence
+ * one takes sequence_id and needs no read; it was once caught by the workflow
+ * branch and refused with "workflows publish requires <id>").
+ */
+const WORKFLOW_PUBLISH = 'workflow.workflows.draft_publish';
+const WORKFLOW_ACTIVATE = 'workflow.workflows.activate';
+async function runPackCommand(context, command, stdout) {
     if (command.command !== 'pack')
-        throw new index_1.CliUsageError('Pack command required.');
-    // Every run needs a tool_turn_token from tools_get, exactly as the generic
-    // tools run path does. Without it the server refuses capability_not_fetched,
-    // which made every pack verb unusable even though its capability id was right.
-    const { toolTurnToken, capabilityIdempotencyKey } = require('../index');
-    if (command.verb === 'activate' && command.input.max_credits === undefined) {
-        throw new index_1.CliUsageError('workflows activate requires --max-credits <n>.');
-    }
-    if (command.verb === 'publish' || command.verb === 'activate') {
+        throw new errors_1.CliUsageError('Pack command required.');
+    if (command.capabilityId === WORKFLOW_PUBLISH || command.capabilityId === WORKFLOW_ACTIVATE) {
         const workflowId = command.input.workflow_id;
         if (typeof workflowId !== 'string')
-            throw new index_1.CliUsageError(`workflows ${command.verb} requires <id>.`);
-        const readFetched = await client.getTool('workflow.automations.get');
-        const current = await client.runCapability('workflow.automations.get', {
-            params: { kind: 'workflow', automation_id: workflowId },
-            tool_turn_token: toolTurnToken(readFetched),
-        }, capabilityIdempotencyKey(readFetched));
+            throw new errors_1.CliUsageError(`${command.pack} ${command.verb} requires <id>.`);
+        const current = await (0, gatedRun_1.readCapability)(context, 'workflow.automations.get', { kind: 'workflow', automation_id: workflowId }, command.waitTimeout);
         const workflow = workflowFromGet(current);
-        if (command.verb === 'publish') {
+        if (command.capabilityId === WORKFLOW_PUBLISH) {
             command.input.expected_draft_version_id ??= nullableString(workflow.latest_draft_version_id, 'latest_draft_version_id');
             command.input.expected_active_version_id ??= nullableString(workflow.active_version_id, 'active_version_id');
         }
@@ -265,19 +233,30 @@ async function runPackCommand(client, command, stdout, sleep = (milliseconds) =>
             command.input.expected_version_id ??= requiredString(workflow.active_version_id, 'active_version_id');
         }
     }
-    const fetched = await client.getTool(command.capabilityId);
-    const turnToken = toolTurnToken(fetched);
-    let result = await client.runCapability(command.capabilityId, {
-        params: command.input, tool_turn_token: turnToken, ...(command.mode ? { mode: command.mode } : {}),
-        ...(command.agentSessionId ? { agent_session_id: command.agentSessionId } : {}),
-        ...(command.maxCredits === undefined ? {} : { max_credits: command.maxCredits }),
-    }, capabilityIdempotencyKey(fetched, command.idempotencyKey));
-    if (!command.noWait && !(0, runWait_1.columnRunReturnsRunId)(command.capabilityId)) {
-        const waited = await (0, runWait_1.waitForRun)(client, result, command.waitTimeout, sleep);
-        result = waited.value;
-        if (waited.timedOut)
-            process.exitCode = runWait_1.RUN_WAIT_TIMEOUT_EXIT_CODE;
-    }
+    const maxCredits = command.maxCredits;
+    const outcome = await (0, gatedRun_1.runGated)(context, {
+        capabilityId: command.capabilityId,
+        body: {
+            params: {
+                ...command.input,
+                ...(command.maxLiveSends === undefined ? {} : { max_live_sends: command.maxLiveSends }),
+            },
+            ...(command.mode ? { mode: command.mode } : {}),
+            ...(maxCredits === undefined ? {} : { max_credits: maxCredits }),
+            ...(command.approved ? { approved: true } : {}),
+            ...(command.approvalId ? { approval_id: command.approvalId } : {}),
+            ...(command.approvedEffectUnknown ? { approved_effect_unknown: true } : {}),
+            ...(command.quoteHash ? { quote_hash: command.quoteHash } : {}),
+        },
+        ...(command.turnToken ? { turnToken: command.turnToken } : {}),
+        ...(command.idempotencyKey ? { idempotencyKey: command.idempotencyKey } : {}),
+        waitTimeout: command.waitTimeout,
+        ...(command.noWait ? { noWait: true } : {}),
+        coerceParams: true,
+    });
+    const result = outcome.value;
+    if (outcome.timedOut)
+        process.exitCode = runWait_1.RUN_WAIT_TIMEOUT_EXIT_CODE;
     const output = command.mode === 'dry_run' && result && typeof result === 'object' && !Array.isArray(result)
         ? { ...result, meta: { ...(result.meta ?? {}), dry_run: true, note: 'dry_run: true, rerun with --live to apply' } }
         : result;
@@ -292,15 +271,14 @@ async function runPackCommand(client, command, stdout, sleep = (milliseconds) =>
         const root = result && typeof result === 'object' ? result : {};
         const webUrl = root.meta?.web_url ?? root.data?.web_url;
         if (typeof webUrl !== 'string')
-            throw new index_1.CliUsageError('The API response did not include a web_url.');
+            throw new errors_1.CliUsageError('The API response did not include a web_url.');
         (0, index_1.openWebUrl)(webUrl);
     }
 }
 function renderPackUsage(pack, specs) {
-    return `Usage: dreamstate ${pack} <verb> [args] [flags]\nRequired positionals use <name:field>. Optional positionals use [name:field]. Flags list target input fields. Run responses wait by default, use --wait-timeout <seconds> (default 120) or --no-wait.\n\nVerbs:\n${specs.map((spec) => {
+    return `Usage: dreamstate ${pack} <verb> [args] [--canonical-field value]\nRequired positionals use <name:field>. Optional positionals use [name:field]. Remote fields, types, required fields and descriptions come from \`dreamstate tools get <capability_id>\`. Run responses wait by default, use --wait-timeout <seconds> (default 120) or --no-wait.\n\nVerbs:\n${specs.map((spec) => {
         const positionals = (spec.positional ?? []).map(({ name, into, optional }) => `${optional ? '[' : '<'}${name}:${into}${optional ? ']' : '>'}`).join(' ');
-        const flags = Object.entries(spec.flags ?? {}).map(([flag, definition]) => `--${flag} <${definition.into}>${definition.required ? ' (required)' : ''}`).join(' ');
-        return `  ${spec.verb.padEnd(18)} ${[positionals, flags].filter(Boolean).join(' ')}\n${' '.repeat(20)}${spec.summary} Capability: ${spec.capabilityId}`;
+        return `  ${spec.verb.padEnd(18)} ${positionals}\n${' '.repeat(20)}Capability: ${spec.capabilityId}${spec.local ? ' (local scaffold)' : ''}`;
     }).join('\n')}`;
 }
 function workflowFromGet(value) {
@@ -312,16 +290,16 @@ function workflowFromGet(value) {
     const outputs = run?.steps?.[0]?.outputs;
     const workflow = outputs ?? data;
     if (!workflow || typeof workflow !== 'object' || Array.isArray(workflow))
-        throw new index_1.CliUsageError('workflow get returned no workflow version data.');
+        throw new errors_1.CliUsageError('workflow get returned no workflow version data.');
     return workflow;
 }
 function nullableString(value, name) {
     if (value === null || typeof value === 'string')
         return value;
-    throw new index_1.CliUsageError(`workflow get returned no ${name}.`);
+    throw new errors_1.CliUsageError(`workflow get returned no ${name}.`);
 }
 function requiredString(value, name) {
     if (typeof value === 'string' && value)
         return value;
-    throw new index_1.CliUsageError(`workflow get returned no ${name}; publish workflow before activation.`);
+    throw new errors_1.CliUsageError(`workflow get returned no ${name}; publish workflow before activation.`);
 }

package/dist/commands/workflows.d.ts

@@ -1,7 +1,8 @@
-import { runPackCommand, type PackVerbSpec } from './shared';
+import { type PackVerbSpec } from './shared';
 import type { CliCommand } from '../index';
+import type { GatedRunContext } from '../gatedRun';
 export declare const WORKFLOW_VERBS: PackVerbSpec[];
 export declare const WORKFLOWS_USAGE: string;
 export declare const parseWorkflowsCommand: (argv: string[]) => CliCommand;
-export declare function runWorkflowsCommand(client: Parameters<typeof runPackCommand>[0], command: CliCommand, stdout: NodeJS.WritableStream, sleep?: Parameters<typeof runPackCommand>[3]): Promise<void>;
+export declare function runWorkflowsCommand(context: GatedRunContext | undefined, command: CliCommand, stdout: NodeJS.WritableStream): Promise<void>;
 //# sourceMappingURL=workflows.d.ts.map

package/dist/commands/workflows.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workflows.d.ts","sourceRoot":"","sources":["../../src/commands/workflows.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,cAAc,EAEd,KAAK,YAAY,EAClB,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAS3C,eAAO,MAAM,cAAc,EAAE,YAAY,EA8BxC,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,MAAqD,CAAC;AACpF,eAAO,MAAM,qBAAqB,gCAA4E,CAAC;AAC/G,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC,CAAC,CAAC,EAC5C,OAAO,EAAE,UAAU,EACnB,MAAM,EAAE,MAAM,CAAC,cAAc,EAC7B,KAAK,CAAC,EAAE,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC,CAAC,CAAC,GAC3C,OAAO,CAAC,IAAI,CAAC,CAMf"}
+{"version":3,"file":"workflows.d.ts","sourceRoot":"","sources":["../../src/commands/workflows.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiE,KAAK,YAAY,EAAE,MAAM,UAAU,CAAC;AAC5G,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAInD,eAAO,MAAM,cAAc,EAAE,YAAY,EAMpC,CAAC;AAEN,eAAO,MAAM,eAAe,QAA+C,CAAC;AAC5E,eAAO,MAAM,qBAAqB,gCAA4E,CAAC;AAC/G,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,eAAe,GAAG,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAQjJ"}

package/dist/commands/workflows.js

@@ -1,51 +1,29 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseWorkflowsCommand = exports.WORKFLOWS_USAGE = exports.WORKFLOW_VERBS = void 0;
 exports.runWorkflowsCommand = runWorkflowsCommand;
 const shared_1 = require("./shared");
-const id = [{ name: 'id', into: 'automation_id' }];
-const workflowId = [{ name: 'id', into: 'workflow_id' }];
-const campaignId = [{ name: 'id', into: 'campaign_id' }];
-const workflowVersion = {
-    'expected-latest-draft-version-id': { type: 'string', into: 'expected_latest_draft_version_id' },
-};
-exports.WORKFLOW_VERBS = [
-    { verb: 'list', capabilityId: 'workflow.automations.list', summary: 'List workflows.', flags: { limit: { type: 'string', into: 'limit' }, cursor: { type: 'string', into: 'cursor' }, lifecycle: { type: 'string', into: 'lifecycle' }, 'include-archived': { type: 'boolean', into: 'include_archived' }, search: { type: 'string', into: 'search' } }, mutating: false },
-    // Local only: writes a starter document to disk and calls no API, so authoring can
-    // begin from a file. capabilityId names the verb this scaffold is meant to feed.
-    { verb: 'init', capabilityId: 'workflow.automations.lint', summary: 'Write a starter workflow document to a local file. Calls no API and changes nothing.', flags: { name: { type: 'string', into: 'name' }, file: { type: 'string', into: 'file' } }, mutating: false },
-    { verb: 'get', capabilityId: 'workflow.automations.get', summary: 'Get workflow.', positional: id, mutating: false },
-    { verb: 'create', capabilityId: 'workflow.automations.compose', summary: 'Create workflow.', flags: { name: { type: 'string', into: 'name' }, description: { type: 'string', into: 'description' }, trigger: { type: 'string', into: 'trigger', json: true }, steps: { type: 'string', into: 'steps', json: true } }, mutating: true },
-    { verb: 'update', capabilityId: 'workflow.automations.update', summary: 'Update workflow.', positional: id, flags: { ...workflowVersion, patch: { type: 'string', into: 'patch', json: true, document: true } }, mutating: true },
-    { verb: 'lint', capabilityId: 'workflow.automations.lint', summary: 'Lint workflow.', positional: id, flags: { phase: { type: 'string', into: 'phase' }, document: { type: 'string', into: 'document', json: true, document: true } }, mutating: false },
-    { verb: 'preview', capabilityId: 'workflow.automations.preview', summary: 'Preview workflow effects.', positional: id, mutating: false },
-    { verb: 'variables', capabilityId: 'workflow.automations.variables_list', summary: 'List workflow variables.', positional: id, flags: { 'node-id': { type: 'string', into: 'node_id' }, query: { type: 'string', into: 'query' }, limit: { type: 'string', into: 'limit' }, document: { type: 'string', into: 'document', json: true, document: true } }, mutating: false },
-    { verb: 'node-catalog', capabilityId: 'workflow.automations.node_catalog', summary: 'List workflow node types.', flags: { 'node-kind': { type: 'string', into: 'node_kind' }, query: { type: 'string', into: 'query' }, family: { type: 'string', into: 'family' }, 'include-blocked': { type: 'boolean', into: 'include_blocked' } }, mutating: false },
-    { verb: 'node-inspect', capabilityId: 'workflow.automations.node_inspect', summary: 'Inspect workflow node type.', flags: { 'node-kind': { type: 'string', into: 'node_kind' }, subtype: { type: 'string', into: 'subtype' }, config: { type: 'string', into: 'config', json: true }, 'automation-id': { type: 'string', into: 'automation_id' }, 'node-id': { type: 'string', into: 'node_id' } }, mutating: false },
-    { verb: 'node-add', capabilityId: 'workflow.automations.node_add', summary: 'Add workflow node.', positional: id, flags: { ...workflowVersion, 'after-node-id': { type: 'string', into: 'after_node_id' }, branch: { type: 'string', into: 'branch' }, node: { type: 'string', into: 'node', json: true, document: true } }, mutating: true },
-    { verb: 'node-patch', capabilityId: 'workflow.automations.node_patch', summary: 'Patch workflow node.', positional: id, flags: { ...workflowVersion, 'node-id': { type: 'string', into: 'node_id' }, fields: { type: 'string', into: 'fields', json: true } }, mutating: true },
-    { verb: 'node-remove', capabilityId: 'workflow.automations.node_remove', summary: 'Remove workflow node.', positional: id, flags: { ...workflowVersion, 'node-id': { type: 'string', into: 'node_id' } }, mutating: true },
-    { verb: 'node-move', capabilityId: 'workflow.automations.node_move', summary: 'Move workflow node.', positional: id, flags: { ...workflowVersion, 'node-id': { type: 'string', into: 'node_id' }, 'after-node-id': { type: 'string', into: 'after_node_id' }, branch: { type: 'string', into: 'branch' } }, mutating: true },
-    { verb: 'field-options', capabilityId: 'workflow.automations.field_options', summary: 'Resolve workflow node field options.', flags: { 'node-kind': { type: 'string', into: 'node_kind' }, subtype: { type: 'string', into: 'subtype' }, 'automation-id': { type: 'string', into: 'automation_id' }, 'node-id': { type: 'string', into: 'node_id' }, 'field-key': { type: 'string', into: 'field_key' }, 'field-keys': { type: 'string', into: 'field_keys', json: true }, query: { type: 'string', into: 'query' }, limit: { type: 'string', into: 'limit' }, cursor: { type: 'string', into: 'cursor' }, 'field-context': { type: 'string', into: 'field_context', json: true } }, mutating: false },
-    { verb: 'draft-save', capabilityId: 'workflow.workflows.draft_save', summary: 'Save workflow draft.', positional: workflowId, flags: { graph: { type: 'string', into: 'graph', json: true, document: true }, 'expected-latest-draft-version-id': { type: 'string', into: 'expected_latest_draft_version_id' } }, mutating: true },
-    { verb: 'publish', capabilityId: 'workflow.workflows.draft_publish', summary: 'Publish workflow draft.', positional: workflowId, flags: { 'expected-draft-version-id': { type: 'string', into: 'expected_draft_version_id' }, 'expected-active-version-id': { type: 'string', into: 'expected_active_version_id' } }, mutating: true },
-    { verb: 'activate', capabilityId: 'workflow.workflows.activate', summary: 'Activate workflow.', positional: workflowId, flags: { 'expected-version-id': { type: 'string', into: 'expected_version_id' }, 'max-credits': { type: 'string', into: 'max_credits', number: true, required: true }, 'delivery-binding': { type: 'string', into: 'delivery_binding', json: true } }, mutating: true },
-    { verb: 'deactivate', capabilityId: 'workflow.workflows.deactivate', summary: 'Deactivate workflow.', positional: workflowId, mutating: true },
-    { verb: 'enroll', capabilityId: 'workflow.workflows.enroll_selection', summary: 'Enroll saved worksheet selection in workflow.', positional: workflowId, flags: { 'workbook-id': { type: 'string', into: 'workbook_id' }, 'worksheet-id': { type: 'string', into: 'worksheet_id' }, 'saved-view-id': { type: 'string', into: 'saved_view_id' }, 'selection-snapshot-id': { type: 'string', into: 'selection_snapshot_id' }, 'trigger-node-id': { type: 'string', into: 'trigger_node_id' }, 'audience-filter': { type: 'string', into: 'audience_filter', json: true }, 'enrollment-priority': { type: 'string', into: 'enrollment_priority', json: true }, 'enrollment-sort': { type: 'string', into: 'enrollment_sort', json: true }, 'max-live-sends': { type: 'string', into: 'max_live_sends', number: true } }, mutating: true },
-    { verb: 'runs', capabilityId: 'workflow.workflows.runs_list', summary: 'List workflow runs.', positional: workflowId, flags: { workflow: { type: 'string', into: 'workflow_id' }, limit: { type: 'string', into: 'limit' } }, mutating: false },
-    { verb: 'run', capabilityId: 'workflow.workflows.run_trace_get', summary: 'Get workflow run trace.', positional: workflowId, flags: { 'subject-id': { type: 'string', into: 'subject_id' } }, mutating: false },
-    { verb: 'retry', capabilityId: 'workflow.workflows.run_retry', summary: 'Retry failed workflow run event.', positional: workflowId, flags: { 'subject-id': { type: 'string', into: 'subject_id' }, 'failed-event-id': { type: 'string', into: 'failed_event_id' }, 'failed-node-id': { type: 'string', into: 'failed_node_id' } }, mutating: true },
-    { verb: 'duplicate', capabilityId: 'workflow.automations.duplicate', summary: 'Duplicate workflow.', positional: id, flags: { ...workflowVersion, name: { type: 'string', into: 'name' } }, mutating: true },
-    { verb: 'archive', capabilityId: 'workflow.automations.archive', summary: 'Archive workflow.', positional: id, flags: { ...workflowVersion, reason: { type: 'string', into: 'reason' } }, mutating: true },
-    { verb: 'export', capabilityId: 'workflow.automations.export', summary: 'Export workflow.', positional: id, mutating: false },
-    { verb: 'import', capabilityId: 'workflow.automations.import', summary: 'Import workflow.', flags: { name: { type: 'string', into: 'name' }, document: { type: 'string', into: 'document', json: true, document: true } }, mutating: true },
-];
+const errors_1 = require("../errors");
+const packVerbs_generated_json_1 = __importDefault(require("../generated/packVerbs.generated.json"));
+exports.WORKFLOW_VERBS = packVerbs_generated_json_1.default.verbs
+    .filter(({ command }) => command.startsWith('workflows '))
+    .map(({ command, capabilityId, positional, local }) => ({
+    verb: command.slice('workflows '.length), capabilityId,
+    ...(positional ? { positional } : {}),
+    ...(local === 'init' ? { local: 'init' } : {}),
+}));
 exports.WORKFLOWS_USAGE = (0, shared_1.renderPackUsage)('workflows', exports.WORKFLOW_VERBS);
 exports.parseWorkflowsCommand = (0, shared_1.buildPackParser)('workflows', 'workflow', exports.WORKFLOW_VERBS, exports.WORKFLOWS_USAGE);
-async function runWorkflowsCommand(client, command, stdout, sleep) {
+async function runWorkflowsCommand(context, command, stdout) {
+    // init writes a local file and calls no API, so it has no gated context.
     if (command.command === 'pack' && command.verb === 'init') {
         (0, shared_1.runPackInit)('workflow', command, stdout);
         return;
     }
-    await (0, shared_1.runPackCommand)(client, command, stdout, sleep);
+    if (!context)
+        throw new errors_1.CliUsageError('workflows commands other than init require an authenticated session.');
+    await (0, shared_1.runPackCommand)(context, command, stdout);
 }

package/dist/errors.d.ts

@@ -0,0 +1,74 @@
+export declare class CliUsageError extends Error {
+    constructor(message: string);
+}
+/**
+ * Process exit codes. The numbers are a published contract; change them only
+ * with a major version. `dreamstate --help` renders their stable meanings.
+ *
+ * Contract C5 (cross-surface): 0 ok, 1 generic, 2 usage, 3 auth, 4 not found,
+ * 5 conflict/validation, 6 rate limited, 7 repair.kind ask_user (a person must decide),
+ * 8 cli_update_required, 9 other refusal. Where this CLI had already published a
+ * different meaning it kept the published one and the mapping is documented:
+ *
+ * - 5 stays "server failure" (HTTP 5xx and unreadable responses). A 4xx
+ *   conflict or validation refusal exits 9, as published and pinned by
+ *   exitCodes.test.ts: a script must not read a caller mistake as a broken server.
+ * - 8 is cli_update_required. It was "request timeout" before; timeouts are 11
+ *   now, so a script can tell "update the CLI" from "try again later".
+ */
+export declare const CLI_EXIT: {
+    readonly SUCCESS: 0;
+    readonly UNCLASSIFIED: 1;
+    readonly USAGE: 2;
+    readonly AUTH: 3;
+    readonly NOT_FOUND: 4;
+    readonly SERVER: 5;
+    readonly RATE_LIMITED: 6;
+    readonly APPROVAL: 7;
+    readonly UPDATE_REQUIRED: 8;
+    readonly REFUSED: 9;
+    readonly TRANSPORT: 10;
+    readonly TIMEOUT: 11;
+};
+/**
+ * Codes the CLI process raises itself, with no server answer behind them.
+ * The server never emits these. They are declared here, once, so the README
+ * table and the tests that keep every code in CLI source accounted for
+ * (errorCodes.test.ts) read one list. A code that is not in this table must be
+ * a member of the shared API_ERROR_CODES.
+ */
+export declare const CLI_LOCAL_ERROR_CODES: Readonly<Record<string, string>>;
+/** Recovery metadata for failures raised by this CLI, rather than the API. */
+export declare const CLI_LOCAL_ERROR_REPAIRS: {
+    readonly network_error: {
+        readonly kind: "wait";
+        readonly hint: "Retry the unchanged request when network connectivity is available.";
+    };
+    readonly request_timeout: {
+        readonly kind: "ask_user";
+        readonly hint: "Read the target back first. If absent, repeat once with the same idempotency key; otherwise ask the person.";
+    };
+    readonly invalid_response: {
+        readonly kind: "server_defect";
+        readonly hint: "The API response was not a Dreamstate envelope; report the trace id if one was returned.";
+    };
+    readonly invalid_web_url: {
+        readonly kind: "server_defect";
+        readonly hint: "The API returned an invalid web URL; report the response trace id.";
+    };
+    readonly web_url_unavailable: {
+        readonly kind: "not_possible";
+        readonly hint: "This result has no web URL to open.";
+    };
+    readonly plugin_install_failed: {
+        readonly kind: "ask_user";
+        readonly hint: "Install a supported agent, then retry plugin installation.";
+    };
+    readonly skills_authentication_required: {
+        readonly kind: "ask_user";
+        readonly hint: "Sign in with dreamstate login, then retry.";
+    };
+};
+export declare function isApprovalRepair(error: unknown): boolean;
+export declare function isLocalRefusalCode(code: string | undefined): boolean;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,aAAc,SAAQ,KAAK;gBAC1B,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,QAAQ;;;;;;;;;;;;;CAaX,CAAC;AAEX;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAQlE,CAAC;AAEF,8EAA8E;AAC9E,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAQ1B,CAAC;AAEX,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAMxD;AAQD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAEpE"}