@trydreamstate/cli 1.0.0

package/README.md

@@ -0,0 +1,62 @@
+# Dreamstate CLI
+
+Live terminal client for Dreamstate capability catalog. No pack list, capability list, or schema lives in package.
+
+```sh
+npm install -g @trydreamstate/cli
+
+# Opens browser approval. No API key or prior CLI state needed.
+dreamstate login
+
+# SSH or remote box with no browser: paste the token minted by "Create session" in the web app.
+dreamstate login --token <ds_live_...>
+
+# Install hosted skills for your agents (space-separated, comma-separated or repeated --agents).
+dreamstate skills install --agents claude-code codex cursor --skill '*' --json
+
+# Delete the stored credentials.
+dreamstate logout
+
+# Optional: point CLI at local or test API.
+export DREAMSTATE_API_URL=http://localhost:3001/api/v1
+
+dreamstate auth whoami
+dreamstate whoami --json
+dreamstate packs list
+dreamstate packs get <pack_id>
+dreamstate commands search "create a workbook and add rows"
+dreamstate tools get <capability_id>
+dreamstate tools search --goal "create a workbook" --limit 50 --toolset tables
+dreamstate tools run tables.workbooks.create --params '{"name":"Pipeline"}' --mode live --approved
+```
+
+`login --token <ds_live_...>` checks the token looks like a `ds_live_` key, verifies it with `whoami` against the API, and only then stores it (mode `0600`) and prints the same `whoami` output. The token is never echoed, and a rejected token is not stored. `auth login` keeps `--api-key-file`, stdin and `DREAMSTATE_API_KEY`. `logout` deletes `~/.dreamstate/credentials` (or `$DREAMSTATE_CONFIG_DIR/credentials`), prints what it removed, and exits 0 even when already logged out. `--agents` accepts `codex`, `claude-code` and `cursor`, as `--agents claude-code codex cursor`, `--agents claude-code,codex` or repeated flags, for `skills install` and `skills doctor`. Node 22 or newer is required.
+
+`login` prints approval URL plus confirmation code. Approval page shows same code, then CLI stores granted credential with mode `0600` and prints `whoami`. Default API is `https://api.trydreamstate.com/api/v1`; `DREAMSTATE_API_URL` overrides it. `whoami` and `auth whoami` are aliases. `auth whoami` prints API `registry_hash` unchanged. `packs list`, `packs get`, and `commands search` read authenticated API catalog at request time.
+
+`--json` is output alias for `--json-output` when used without a value. `tools run --json <body>`, `runs list --json <query>`, and `runs cancel --json <body>` keep JSON input meaning. `tools run --mode smoke_test|dry_run|live` sends canonical execution mode; `--dry-run` aliases `--mode dry_run`. `--approved` authorizes request only, never enters request body. `tools search --limit <n>` and `--toolset <pack_id>` send canonical discovery query fields.
+
+## Stream contract and exit codes
+
+Every invocation writes one JSON envelope to stdout. Pipe stdout to `jq`; progress, warnings, confirmation codes, and version-skew notices use stderr. Error envelopes have `ok: false`, `executed: false`, `error`, and `meta.exit_code`; usage errors use same envelope.
+
+| Exit code | Meaning |
+| --- | --- |
+| 0 | Success |
+| 2 | Usage error |
+| 3 | Authentication failure |
+| 4 | Not found |
+| 5 | Server failure |
+| 6 | Rate limited |
+| 7 | Approval required |
+| 8 | Request timeout |
+| 9 | Server refusal (HTTP 4xx) |
+| 10 | Transport failure |
+
+Build and test:
+
+```sh
+npm run build --workspace=packages/cli
+npm test --workspace=packages/cli
+npm run pack:smoke --workspace=packages/cli
+```

package/dist/client.d.ts

@@ -0,0 +1,106 @@
+export declare const CLI_VERSION: string;
+export interface DreamstateClientOptions {
+    apiKey: string;
+    baseUrl: string;
+    requestTimeoutMs?: number;
+    onVersionWarning?: (message: string) => void;
+}
+export declare const DEFAULT_REQUEST_TIMEOUT_MS = 15000;
+export declare const TOOL_AND_RUN_REQUEST_TIMEOUT_MS = 60000;
+export interface WhoamiResponse {
+    registry_hash: string;
+    workspace_id: string;
+    actor: {
+        type: string;
+        user_id?: string;
+        key_id?: string;
+    };
+    key_id: string | null;
+    actor_user_id: string | null;
+    scopes: string[];
+    plan_tier: string | null;
+    subscription_status: string | null;
+    api_base_url: string;
+    mcp_endpoint_url: string;
+}
+export interface CapabilityRunBody {
+    params: Record<string, unknown>;
+    mode?: 'smoke_test' | 'dry_run' | 'live';
+    agent_session_id?: string;
+    approved?: boolean;
+    max_credits?: number;
+    [key: string]: unknown;
+}
+export interface DeviceAuthorization {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    verification_uri_complete: string;
+    interval_seconds: number;
+    expires_at: string;
+    confirmation_code: string;
+}
+export type DeviceAuthorizationClaim = {
+    status: 'pending';
+} | {
+    status: 'ready';
+    token: string;
+    workspace: {
+        id: string;
+        name: string;
+    };
+};
+export declare class CliError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly details?: unknown;
+    readonly retryAfter?: string;
+    readonly traceId?: string;
+    readonly idempotencyKey?: string;
+    /** The server's retry decision and repair, forwarded unchanged so the CLI never re-derives them. */
+    readonly retryable?: boolean;
+    readonly repair?: unknown;
+    constructor(message: string, code: string, status: number, options?: {
+        details?: unknown;
+        retryAfter?: string;
+        traceId?: string;
+        idempotencyKey?: string;
+        retryable?: boolean;
+        repair?: unknown;
+    });
+}
+export declare function readToolEnvelopeTraceId(value: unknown): string | undefined;
+export declare function requestDeviceAuthorization(baseUrl: string, body: {
+    state: string;
+    client: {
+        os: string;
+        hostname: string;
+        cli_version: string;
+    };
+}): Promise<DeviceAuthorization>;
+export declare function claimDeviceAuthorization(baseUrl: string, state: string): Promise<DeviceAuthorizationClaim>;
+export declare class DreamstateClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly requestTimeoutMs?;
+    private readonly onVersionWarning?;
+    constructor(options: DreamstateClientOptions);
+    getWhoami(): Promise<unknown>;
+    listPacks(query?: Record<string, unknown>): Promise<unknown>;
+    getPack(packId: string, query?: Record<string, unknown>): Promise<unknown>;
+    routePack(goal: string): Promise<unknown>;
+    listSkills(query?: Record<string, unknown>): Promise<unknown>;
+    searchSkillDocuments(query: Record<string, unknown>): Promise<unknown>;
+    listAllSkills(): Promise<unknown>;
+    getSkill(skillId: string, query?: Record<string, unknown>): Promise<unknown>;
+    listTools(query?: Record<string, unknown>): Promise<unknown>;
+    getTool(capabilityId: string, query?: Record<string, unknown>): Promise<unknown>;
+    runCapability(capabilityId: string, body: CapabilityRunBody, idempotencyKey?: string | null): Promise<unknown>;
+    getRun(id: string): Promise<unknown>;
+    listRuns(query?: Record<string, unknown>): Promise<unknown>;
+    resumeRun(id: string, body: Record<string, unknown>, idempotencyKey?: string): Promise<unknown>;
+    getRunEvents(id: string, query?: Record<string, unknown>): Promise<unknown>;
+    cancelRun(id: string, body: Record<string, unknown>, idempotencyKey?: string): Promise<unknown>;
+    private request;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

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

package/dist/client.js

@@ -0,0 +1,265 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DreamstateClient = exports.CliError = exports.TOOL_AND_RUN_REQUEST_TIMEOUT_MS = exports.DEFAULT_REQUEST_TIMEOUT_MS = exports.CLI_VERSION = void 0;
+exports.readToolEnvelopeTraceId = readToolEnvelopeTraceId;
+exports.requestDeviceAuthorization = requestDeviceAuthorization;
+exports.claimDeviceAuthorization = claimDeviceAuthorization;
+const node_crypto_1 = require("node:crypto");
+exports.CLI_VERSION = require('../package.json').version;
+exports.DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
+exports.TOOL_AND_RUN_REQUEST_TIMEOUT_MS = 60_000;
+class CliError extends Error {
+    code;
+    status;
+    details;
+    retryAfter;
+    traceId;
+    idempotencyKey;
+    /** The server's retry decision and repair, forwarded unchanged so the CLI never re-derives them. */
+    retryable;
+    repair;
+    constructor(message, code, status, options = {}) {
+        super(message);
+        this.name = 'CliError';
+        this.code = code;
+        this.status = status;
+        if (options.details !== undefined)
+            this.details = options.details;
+        if (options.retryAfter !== undefined)
+            this.retryAfter = options.retryAfter;
+        if (options.traceId !== undefined)
+            this.traceId = options.traceId;
+        if (options.idempotencyKey !== undefined)
+            this.idempotencyKey = options.idempotencyKey;
+        if (options.retryable !== undefined)
+            this.retryable = options.retryable;
+        if (options.repair !== undefined)
+            this.repair = options.repair;
+    }
+}
+exports.CliError = CliError;
+function isApiErrorBody(value) {
+    const error = value && typeof value === 'object' ? value.error : null;
+    if (!error || typeof error !== 'object')
+        return false;
+    const candidate = error;
+    return typeof candidate.code === 'string' && typeof candidate.message === 'string';
+}
+function readToolEnvelopeTraceId(value) {
+    const envelope = value !== null && typeof value === 'object' ? value : null;
+    const meta = envelope?.meta;
+    const traceId = meta !== null && typeof meta === 'object' ? meta.trace_id : undefined;
+    if (typeof traceId === 'string' && traceId.trim())
+        return traceId;
+    const details = envelope?.error && typeof envelope.error === 'object' ? envelope.error.details : undefined;
+    const detailTraceId = details !== null && typeof details === 'object' ? details.trace_id : undefined;
+    return typeof detailTraceId === 'string' && detailTraceId.trim() ? detailTraceId : undefined;
+}
+function queryString(query) {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+        if (value === undefined || value === null)
+            continue;
+        for (const item of Array.isArray(value) ? value : [value]) {
+            params.append(key, typeof item === 'string' ? item : JSON.stringify(item));
+        }
+    }
+    const serialized = params.toString();
+    return serialized ? `?${serialized}` : '';
+}
+function retryAfter(response, body) {
+    const value = body.error.details && typeof body.error.details === 'object'
+        ? body.error.details.retry_after
+        : undefined;
+    if (typeof value === 'string' && value.trim())
+        return value.trim();
+    if (typeof value === 'number' && Number.isFinite(value))
+        return String(value);
+    return response.headers.get('Retry-After')?.trim() || undefined;
+}
+function versionAtMost(current, target) {
+    return !isVersionGreater(current, target);
+}
+function responseError(payload, status) {
+    if (isApiErrorBody(payload)) {
+        return new CliError(payload.error.message, payload.error.code, status, {
+            details: payload.error.details,
+            ...(typeof payload.error.retryable === 'boolean' ? { retryable: payload.error.retryable } : {}),
+            ...(payload.error.repair && typeof payload.error.repair === 'object' ? { repair: payload.error.repair } : {}),
+        });
+    }
+    const error = payload && typeof payload === 'object' ? payload.error : null;
+    if (error && typeof error === 'object' && typeof error.code === 'string') {
+        const code = error.code;
+        return new CliError(code, code, status);
+    }
+    return null;
+}
+async function requestDeviceAuthorization(baseUrl, body) {
+    return requestPublic(baseUrl, '/cli/login-requests', { method: 'POST', body: JSON.stringify(body) });
+}
+async function claimDeviceAuthorization(baseUrl, state) {
+    return requestPublic(baseUrl, '/cli/login-requests/claim', { method: 'POST', body: JSON.stringify({ state }) });
+}
+async function requestPublic(baseUrl, path, init) {
+    let response;
+    try {
+        response = await fetch(`${baseUrl.replace(/\/+$/, '')}${path}`, {
+            ...init,
+            headers: { Accept: 'application/json', 'Content-Type': 'application/json', 'X-Dreamstate-Client-Version': exports.CLI_VERSION, ...init.headers },
+        });
+    }
+    catch (error) {
+        throw new CliError(`Request failed: ${error instanceof Error ? error.message : String(error)}`, 'network_error', 0);
+    }
+    let payload;
+    try {
+        payload = await response.json();
+    }
+    catch {
+        throw new CliError(`Dreamstate API returned invalid JSON (HTTP ${response.status})`, 'invalid_response', response.status);
+    }
+    const apiError = responseError(payload, response.status);
+    if (apiError)
+        throw apiError;
+    if (!response.ok)
+        throw new CliError(`Dreamstate API request failed (HTTP ${response.status})`, 'request_failed', response.status);
+    const data = payload && typeof payload === 'object' ? payload.data : undefined;
+    if (!data || typeof data !== 'object')
+        throw new CliError('Dreamstate API returned invalid device authorization data.', 'invalid_response', response.status);
+    return data;
+}
+class DreamstateClient {
+    apiKey;
+    baseUrl;
+    requestTimeoutMs;
+    onVersionWarning;
+    constructor(options) {
+        this.apiKey = options.apiKey;
+        this.baseUrl = options.baseUrl.replace(/\/+$/, '');
+        this.requestTimeoutMs = options.requestTimeoutMs;
+        this.onVersionWarning = options.onVersionWarning;
+    }
+    getWhoami() { return this.request('/whoami'); }
+    listPacks(query = {}) { return this.request(`/packs${queryString(query)}`); }
+    getPack(packId, query = {}) {
+        return this.request(`/packs/${encodeURIComponent(packId)}${queryString(query)}`);
+    }
+    routePack(goal) {
+        return this.request(`/packs/route${queryString({ goal })}`);
+    }
+    listSkills(query = {}) {
+        return this.request(`/skills${queryString(query)}`);
+    }
+    searchSkillDocuments(query) {
+        return this.request(`/skills/search${queryString(query)}`);
+    }
+    listAllSkills() {
+        return this.listSkills();
+    }
+    getSkill(skillId, query = {}) {
+        return this.request(`/skills/${encodeURIComponent(skillId)}${queryString(query)}`);
+    }
+    listTools(query = {}) {
+        return this.request(`/tools${queryString(query)}`, {}, exports.TOOL_AND_RUN_REQUEST_TIMEOUT_MS);
+    }
+    getTool(capabilityId, query = {}) {
+        return this.request(`/tools/${encodeURIComponent(capabilityId)}${queryString(query)}`, {}, exports.TOOL_AND_RUN_REQUEST_TIMEOUT_MS);
+    }
+    runCapability(capabilityId, body, idempotencyKey) {
+        const key = idempotencyKey === null ? undefined : idempotencyKey ?? (0, node_crypto_1.randomUUID)();
+        return this.request(`/tools/${encodeURIComponent(capabilityId)}/run`, {
+            method: 'POST', body: JSON.stringify(body),
+            ...(key ? { headers: { 'Idempotency-Key': key } } : {}),
+        }, exports.TOOL_AND_RUN_REQUEST_TIMEOUT_MS);
+    }
+    getRun(id) {
+        return this.request(`/runs/${encodeURIComponent(id)}`, {}, exports.TOOL_AND_RUN_REQUEST_TIMEOUT_MS);
+    }
+    listRuns(query = {}) {
+        return this.request(`/runs${queryString(query)}`, {}, exports.TOOL_AND_RUN_REQUEST_TIMEOUT_MS);
+    }
+    resumeRun(id, body, idempotencyKey) {
+        const key = idempotencyKey ?? (0, node_crypto_1.randomUUID)();
+        return this.request(`/runs/${encodeURIComponent(id)}/resume`, {
+            method: 'POST', body: JSON.stringify(body),
+            headers: { 'Idempotency-Key': key },
+        }, exports.TOOL_AND_RUN_REQUEST_TIMEOUT_MS);
+    }
+    getRunEvents(id, query = {}) {
+        return this.request(`/runs/${encodeURIComponent(id)}/events${queryString(query)}`);
+    }
+    cancelRun(id, body, idempotencyKey) {
+        const key = idempotencyKey ?? (0, node_crypto_1.randomUUID)();
+        return this.request(`/runs/${encodeURIComponent(id)}/cancel`, {
+            method: 'POST', body: JSON.stringify(body),
+            ...(key ? { headers: { 'Idempotency-Key': key } } : {}),
+        });
+    }
+    async request(path, init = {}, defaultTimeoutMs = exports.DEFAULT_REQUEST_TIMEOUT_MS) {
+        const requestTimeoutMs = this.requestTimeoutMs ?? defaultTimeoutMs;
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), requestTimeoutMs);
+        let response;
+        try {
+            const idempotencyKey = new Headers(init.headers).get('Idempotency-Key') ?? undefined;
+            try {
+                response = await fetch(`${this.baseUrl}${path}`, {
+                    ...init,
+                    signal: controller.signal,
+                    headers: {
+                        Accept: 'application/json', Authorization: `Bearer ${this.apiKey}`,
+                        'X-Dreamstate-Client-Version': exports.CLI_VERSION,
+                        ...(init.body ? { 'Content-Type': 'application/json' } : {}), ...init.headers,
+                    },
+                });
+            }
+            catch (error) {
+                if (controller.signal.aborted) {
+                    throw new CliError(`Request timed out after ${requestTimeoutMs}ms`, 'request_timeout', 0, { idempotencyKey });
+                }
+                throw new CliError(`Request failed: ${error instanceof Error ? error.message : String(error)}`, 'network_error', 0);
+            }
+            let payload;
+            try {
+                payload = await response.json();
+            }
+            catch {
+                if (controller.signal.aborted) {
+                    throw new CliError(`Request timed out after ${requestTimeoutMs}ms`, 'request_timeout', response.status, { idempotencyKey });
+                }
+                throw new CliError(`Dreamstate API returned invalid JSON (HTTP ${response.status})`, 'invalid_response', response.status);
+            }
+            if (isApiErrorBody(payload)) {
+                throw new CliError(payload.error.message, payload.error.code, response.status, {
+                    details: payload.error.details, retryAfter: retryAfter(response, payload),
+                    traceId: readToolEnvelopeTraceId(payload), idempotencyKey,
+                    ...(typeof payload.error.retryable === 'boolean' ? { retryable: payload.error.retryable } : {}),
+                    ...(payload.error.repair && typeof payload.error.repair === 'object' ? { repair: payload.error.repair } : {}),
+                });
+            }
+            if (!response.ok)
+                throw new CliError(`Dreamstate API request failed (HTTP ${response.status})`, 'request_failed', response.status);
+            const minimum = payload && typeof payload === 'object' ? payload.meta?.minimum_cli_version : undefined;
+            if (typeof minimum === 'string' && isVersionGreater(minimum, exports.CLI_VERSION)) {
+                throw new CliError(`CLI ${minimum} or newer is required. Run: npm install -g @trydreamstate/cli@latest`, 'cli_update_required', 0);
+            }
+            const server = payload && typeof payload === 'object' ? payload.meta?.server_version : undefined;
+            if (typeof server === 'string' && isVersionGreater(server, exports.CLI_VERSION) && (typeof minimum !== 'string' || versionAtMost(minimum, exports.CLI_VERSION))) {
+                this.onVersionWarning?.(`Warning: CLI ${exports.CLI_VERSION} is behind server ${server}. Proceeding; server minimum is ${minimum ?? 'not declared'}.`);
+            }
+            return payload;
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+}
+exports.DreamstateClient = DreamstateClient;
+function isVersionGreater(required, current) {
+    const parse = (version) => version.replace(/^v/, '').split('-')[0].split('.').map((part) => Number(part));
+    const [requiredMajor = 0, requiredMinor = 0, requiredPatch = 0] = parse(required);
+    const [currentMajor = 0, currentMinor = 0, currentPatch = 0] = parse(current);
+    return requiredMajor > currentMajor || (requiredMajor === currentMajor && requiredMinor > currentMinor)
+        || (requiredMajor === currentMajor && requiredMinor === currentMinor && requiredPatch > currentPatch);
+}

package/dist/commands/sequences.d.ts

@@ -0,0 +1,7 @@
+import { runPackCommand, type PackVerbSpec } from './shared';
+import type { CliCommand } from '../index';
+export declare const SEQUENCE_VERBS: PackVerbSpec[];
+export declare const SEQUENCES_USAGE: string;
+export declare const parseSequencesCommand: (argv: string[]) => CliCommand;
+export declare function runSequencesCommand(client: Parameters<typeof runPackCommand>[0], command: CliCommand, stdout: NodeJS.WritableStream): Promise<void>;
+//# sourceMappingURL=sequences.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sequences.d.ts","sourceRoot":"","sources":["../../src/commands/sequences.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoC,cAAc,EAAe,KAAK,YAAY,EAAE,MAAM,UAAU,CAAC;AAC5G,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C,eAAO,MAAM,cAAc,EAAE,YAAY,EA6BxC,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,GAC5B,OAAO,CAAC,IAAI,CAAC,CAMf"}

package/dist/commands/sequences.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseSequencesCommand = exports.SEQUENCES_USAGE = exports.SEQUENCE_VERBS = void 0;
+exports.runSequencesCommand = runSequencesCommand;
+const shared_1 = require("./shared");
+exports.SEQUENCE_VERBS = [
+    { verb: 'list', capabilityId: 'workflow.automations.list', summary: 'List sequences in workspace.', 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 sequence 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 one sequence.', positional: [{ name: 'id', into: 'automation_id' }], mutating: false },
+    { verb: 'create', capabilityId: 'workflow.automations.compose', summary: 'Create draft sequence. Does not publish or send.', flags: { name: { type: 'string', into: 'name' }, description: { type: 'string', into: 'description' }, timezone: { type: 'string', into: 'timezone' }, enrollment: { type: 'string', into: 'enrollment', json: true }, 'daily-cap': { type: 'string', into: 'daily_cap' }, 'max-new-enrollments-per-day': { type: 'string', into: 'max_new_enrollments_per_day' }, senders: { type: 'string', into: 'senders', json: true }, steps: { type: 'string', into: 'steps', json: true }, 'on-duplicate-name': { type: 'string', into: 'on_duplicate_name' } }, mutating: true },
+    { verb: 'update', capabilityId: 'workflow.automations.update', summary: 'Update sequence draft settings. Does not publish or send.', positional: [{ name: 'id', into: 'automation_id' }], flags: { patch: { type: 'string', into: 'patch', json: true }, 'expected-version': { type: 'string', into: 'expected_version', number: true } }, mutating: true },
+    { verb: 'lint', capabilityId: 'workflow.automations.lint', summary: 'Lint sequence draft. Makes no changes.', positional: [{ name: 'id', into: 'automation_id' }], flags: { document: { type: 'string', into: 'document', json: true, document: true } }, mutating: false },
+    { verb: 'preview', capabilityId: 'workflow.automations.preview', summary: 'Preview saved sequence. Creates no run and sends nothing.', positional: [{ name: 'id', into: 'automation_id' }], mutating: false },
+    { verb: 'variables', capabilityId: 'workflow.automations.variables_list', summary: 'List template variables available in sequence.', positional: [{ name: 'id', into: 'automation_id' }], flags: { document: { type: 'string', into: 'document', json: true, document: true }, node: { type: 'string', into: 'node_id' }, query: { type: 'string', into: 'query' }, limit: { type: 'string', into: 'limit' } }, mutating: false },
+    { verb: 'node-catalog', capabilityId: 'workflow.automations.node_catalog', summary: 'List available sequence node types.', flags: { 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 sequence node type or saved node.', positional: [{ name: 'id', into: 'automation_id', optional: true }], flags: { node: { type: 'string', into: 'node_id' }, 'node-kind': { type: 'string', into: 'node_kind' }, subtype: { type: 'string', into: 'subtype' }, config: { type: 'string', into: 'config', json: true } }, mutating: false },
+    { verb: 'node-add', capabilityId: 'workflow.automations.node_add', summary: 'Add node to sequence draft. Does not publish or send.', positional: [{ name: 'id', into: 'automation_id' }], flags: { node: { type: 'string', into: 'node', json: true }, 'after-node': { type: 'string', into: 'after_node_id' }, branch: { type: 'string', into: 'branch' }, 'expected-version': { type: 'string', into: 'expected_version', number: true } }, mutating: true },
+    { verb: 'node-patch', capabilityId: 'workflow.automations.node_patch', summary: 'Patch sequence node. Does not publish or send.', positional: [{ name: 'id', into: 'automation_id' }], flags: { node: { type: 'string', into: 'node_id' }, fields: { type: 'string', into: 'fields', json: true }, 'expected-version': { type: 'string', into: 'expected_version', number: true } }, mutating: true },
+    { verb: 'node-remove', capabilityId: 'workflow.automations.node_remove', summary: 'Remove node from sequence draft. Does not publish or send.', positional: [{ name: 'id', into: 'automation_id' }], flags: { node: { type: 'string', into: 'node_id' }, 'expected-version': { type: 'string', into: 'expected_version', number: true } }, mutating: true },
+    { verb: 'node-move', capabilityId: 'workflow.automations.node_move', summary: 'Move sequence node. Does not publish or send.', positional: [{ name: 'id', into: 'automation_id' }], flags: { node: { type: 'string', into: 'node_id' }, 'after-node': { type: 'string', into: 'after_node_id' }, branch: { type: 'string', into: 'branch' }, 'expected-version': { type: 'string', into: 'expected_version', number: true } }, mutating: true },
+    { verb: 'field-options', capabilityId: 'workflow.automations.field_options', summary: 'List options for sequence node fields.', positional: [{ name: 'id', into: 'automation_id', optional: true }], flags: { node: { type: 'string', into: 'node_id' }, 'node-kind': { type: 'string', into: 'node_kind' }, subtype: { type: 'string', into: 'subtype' }, '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: 'publish', capabilityId: 'sequence.sequences.publish', summary: 'Publish sequence draft. Does not enroll or send.', positional: [{ name: 'id', into: 'sequence_id' }], flags: { 'sequence-version-id': { type: 'string', into: 'sequence_version_id' }, 'latest-draft-version-id': { type: 'string', into: 'latest_draft_version_id' } }, mutating: true },
+    { verb: 'enroll', capabilityId: 'sequence.sequences.enroll_selection', summary: 'Enroll rows into sequence. Spends no credits and sends nothing; dispatch only happens at launch.', positional: [{ name: 'id', into: 'sequence_id' }], flags: { worksheet: { type: 'string', into: 'worksheet_id' }, view: { type: 'string', into: 'view_id' }, 'enrollment-filter': { type: 'string', into: 'enrollment_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' }, 'max-new-enrollments-per-day': { type: 'string', into: 'max_new_enrollments_per_day' } }, mutating: true },
+    { verb: 'launch', capabilityId: 'sequence.sequences.launch', summary: 'Launch published sequence dispatch.', positional: [{ name: 'id', into: 'sequence_id' }], flags: { 'max-live-sends': { type: 'string', into: 'max_live_sends' } }, mutating: true },
+    { verb: 'pause', capabilityId: 'sequence.sequences.pause', summary: 'Pause sequence dispatch. Sends no new messages.', positional: [{ name: 'id', into: 'sequence_id' }], mutating: true },
+    { verb: 'resume', capabilityId: 'sequence.sequences.resume', summary: 'Resume sequence dispatch.', positional: [{ name: 'id', into: 'sequence_id' }], flags: { 'max-live-sends': { type: 'string', into: 'max_live_sends' } }, mutating: true },
+    { verb: 'stats', capabilityId: 'sequence.sequences.step_counts_get', summary: 'Get sequence step counts.', positional: [{ name: 'id', into: 'sequence_id' }], mutating: false },
+    { verb: 'analytics', capabilityId: 'sequence.sequences.analytics_get', summary: 'Get sequence analytics.', positional: [{ name: 'id', into: 'sequence_id' }], flags: { period: { type: 'string', into: 'period' } }, mutating: false },
+    { verb: 'duplicate', capabilityId: 'workflow.automations.duplicate', summary: 'Duplicate sequence as draft. Does not publish or send.', positional: [{ name: 'id', into: 'automation_id' }], flags: { name: { type: 'string', into: 'name' }, 'expected-version': { type: 'string', into: 'expected_version', number: true } }, mutating: true },
+    { verb: 'archive', capabilityId: 'workflow.automations.archive', summary: 'Archive sequence. Does not delete records or send.', positional: [{ name: 'id', into: 'automation_id' }], flags: { reason: { type: 'string', into: 'reason' }, 'expected-version': { type: 'string', into: 'expected_version', number: true } }, mutating: true },
+    { verb: 'export', capabilityId: 'workflow.automations.export', summary: 'Export sequence definition. Makes no changes.', positional: [{ name: 'id', into: 'automation_id' }], mutating: false },
+    { verb: 'import', capabilityId: 'workflow.automations.import', summary: 'Import sequence as draft. Does not publish or send.', flags: { name: { type: 'string', into: 'name' }, document: { type: 'string', into: 'document', json: true, document: true } }, mutating: true },
+];
+exports.SEQUENCES_USAGE = (0, shared_1.renderPackUsage)('sequences', exports.SEQUENCE_VERBS);
+exports.parseSequencesCommand = (0, shared_1.buildPackParser)('sequences', 'sequence', exports.SEQUENCE_VERBS, exports.SEQUENCES_USAGE);
+async function runSequencesCommand(client, command, stdout) {
+    if (command.command === 'pack' && command.verb === 'init') {
+        (0, shared_1.runPackInit)('sequence', command, stdout);
+        return;
+    }
+    await (0, shared_1.runPackCommand)(client, command, stdout);
+}

package/dist/commands/shared.d.ts

@@ -0,0 +1,53 @@
+import type { DreamstateClient } from '../client';
+import { type CliCommand } from '../index';
+export interface PackVerbSpec {
+    verb: string;
+    capabilityId: string;
+    summary: string;
+    /**
+     * `optional: true` marks a positional the verb can do without. node-inspect and
+     * field-options answer two different questions: the contract for a node TYPE, which
+     * needs no automation at all, and the state of one saved node, which needs an id.
+     * Requiring the id for both meant reading a type's schema was impossible without
+     * first creating something to read it from.
+     */
+    positional?: {
+        name: string;
+        into: string;
+        optional?: boolean;
+    }[];
+    /**
+     * `document: true` marks the ONE flag that carries a whole authored document, so
+     * --file knows where to put a file's contents. Without it --file bound to whichever
+     * json flag happened to be declared first, which on `sequences create` was
+     * `enrollment`: a whole sequence document arrived as the enrollment binding and the
+     * server refused it field by field. Flag order is not a contract, so the document
+     * flag has to say so itself.
+     */
+    /**
+     * `number: true` marks a flag whose capability param is numeric. Every flag arrives
+     * from the shell as a string, so `--expected-version 1` was sent as "1" and refused
+     * with `params.expected_version: expected number; received string`: the optimistic
+     * concurrency check could not be satisfied from the CLI at all.
+     */
+    flags?: Record<string, {
+        type: 'string' | 'boolean';
+        into: string;
+        json?: boolean;
+        document?: boolean;
+        number?: boolean;
+    }>;
+    mutating: boolean;
+}
+export declare function buildPackParser(pack: 'sequences' | 'workflows', kind: 'sequence' | 'workflow', specs: PackVerbSpec[], usage: string): (argv: string[]) => CliCommand;
+/**
+ * A starter document written to disk, so authoring can begin from a file the way the
+ * rest of this pack now accepts one. It writes nothing to the workspace and calls no
+ * API: the point is to hand back something `lint --file` will accept and refuse
+ * usefully, rather than to guess a valid sequence on the caller's behalf.
+ */
+export declare function packScaffold(kind: 'sequence' | 'workflow', name: string): Record<string, unknown>;
+export declare function runPackInit(kind: 'sequence' | 'workflow', command: CliCommand, stdout: NodeJS.WritableStream): void;
+export declare function runPackCommand(client: DreamstateClient, command: CliCommand, stdout: NodeJS.WritableStream): Promise<void>;
+export declare function renderPackUsage(pack: string, specs: PackVerbSpec[]): string;
+//# sourceMappingURL=shared.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/commands/shared.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAKlD,OAAO,EAA6B,KAAK,UAAU,EAAiC,MAAM,UAAU,CAAC;AAMrG,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IACpD;;;;;;OAMG;IACH,UAAU,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC;IAClE;;;;;;;OAOG;IACH;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,QAAQ,GAAC,SAAS,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACzH,QAAQ,EAAE,OAAO,CAAC;CACnB;AAsBD,wBAAgB,eAAe,CAC7B,IAAI,EAAE,WAAW,GAAC,WAAW,EAAE,IAAI,EAAE,UAAU,GAAC,UAAU,EAAE,KAAK,EAAE,YAAY,EAAE,EAAE,KAAK,EAAE,MAAM,GAC/F,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,UAAU,CAsGhC;AAGD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA2BjG;AAED,wBAAgB,WAAW,CACzB,IAAI,EAAE,UAAU,GAAG,UAAU,EAC7B,OAAO,EAAE,UAAU,EACnB,MAAM,EAAE,MAAM,CAAC,cAAc,GAC5B,IAAI,CAuBN;AAED,wBAAsB,cAAc,CAAC,MAAM,EAAE,gBAAgB,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAmBhI;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,EAAE,GAAG,MAAM,CAE3E"}