@trydreamstate/cli 1.0.0

package/dist/index.js

@@ -0,0 +1,896 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CliUsageError = exports.CLI_EXIT = void 0;
+exports.parseCliArgs = parseCliArgs;
+exports.toolTurnToken = toolTurnToken;
+exports.refusalEnvelope = refusalEnvelope;
+exports.openWebUrl = openWebUrl;
+exports.exitCodeForError = exitCodeForError;
+exports.runCli = runCli;
+const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = require("node:crypto");
+const promises_1 = require("node:fs/promises");
+const tableFilePreview_1 = require("./tableFilePreview");
+const node_os_1 = require("node:os");
+const node_util_1 = require("node:util");
+const config_1 = require("./config");
+const turnCache_1 = require("./turnCache");
+const client_1 = require("./client");
+const skillInstaller_1 = require("./skillInstaller");
+exports.CLI_EXIT = { SUCCESS: 0, UNCLASSIFIED: 1, USAGE: 2, AUTH: 3, NOT_FOUND: 4, SERVER: 5, RATE_LIMITED: 6, APPROVAL: 7, TIMEOUT: 8, REFUSED: 9, TRANSPORT: 10 };
+const TOOLS_RUN_MODES = ['smoke_test', 'dry_run', 'live'];
+const USAGE = `Dreamstate CLI
+
+Usage:
+  dreamstate --help
+  dreamstate --version
+  dreamstate login
+  dreamstate login --token <ds_live_...>
+  dreamstate logout
+  dreamstate whoami [--json-output|--json]
+  dreamstate auth login [--api-key-file <path>]
+  dreamstate auth whoami [--json-output|--json]
+  dreamstate packs list [--json-output|--json]
+  dreamstate packs get <pack_id> [--json-output|--json]
+  dreamstate packs route --goal <text> [--json-output|--json]
+  dreamstate skills list [--query <query>] [--limit <n>] [--json-output|--json]
+  dreamstate skills get <skill_id> [--json-output|--json]
+  dreamstate skills search <query> [--limit <n>] [--json-output|--json]
+  dreamstate skills install [--skill <skill_id|*>] [--agents <codex claude-code cursor>] [--project] [--copy] [--json-output|--json]
+  dreamstate skills doctor [--agents <codex claude-code cursor>] [--project] [--json-output|--json]
+  dreamstate commands search <term> [--json-output|--json]
+  dreamstate tools search --goal <goal> [--terms <csv>] [--limit <n>] [--toolset <pack_id>] [--json-output|--json]
+  dreamstate tools get <capability_id> [--json-output|--json]
+  dreamstate tools run <capability_id> [--params <object>|--json <body>] [--turn-token <token>] (--live | --dry-run | --mode <smoke_test|dry_run|live>) [--agent-session-id <uuid>] [--approved] [--approved-effect-unknown] [--max-credits <n>] [--idempotency-key <key>] [--open] [--json-output|--json]
+  dreamstate sequences <verb> [args] [flags]
+  dreamstate workflows <verb> [args] [flags]
+  dreamstate tables import --table-id <uuid> --file <path> [--format <csv|json|jsonl|xlsx>] [--preview] [--upsert-key <header>] [--background] [--json-output|--json]
+  dreamstate runs list [--json <query>] [--json-output|--json]
+  dreamstate runs get <run_id> [--json-output|--json]
+  dreamstate runs resume <run_id> --state-version <n> [--reason <text>] [--idempotency-key <key>] [--open] [--json-output|--json]
+  dreamstate runs events <run_id> [--json-output|--json]
+  dreamstate runs cancel <run_id> --json <body> [--idempotency-key <key>] [--json-output|--json]
+
+All catalog discovery reads live API records. Set DREAMSTATE_API_URL and DREAMSTATE_API_KEY.
+login opens browser approval; login --token stores a ds_live_ key (for SSH or remote machines) after verifying it with whoami.
+logout deletes the stored credentials file. --agents takes space-separated, comma-separated or repeated values.
+`;
+class CliUsageError extends Error {
+    constructor(message) { super(message); this.name = 'CliUsageError'; }
+}
+exports.CliUsageError = CliUsageError;
+function outputOption(values) {
+    return values['json-output'] ? { jsonOutput: true } : {};
+}
+function parseJsonObject(raw, flag = '--json') {
+    try {
+        const value = JSON.parse(raw);
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            throw new Error('must contain a JSON object');
+        return value;
+    }
+    catch (error) {
+        throw new CliUsageError(`${flag} ${error instanceof Error ? error.message : 'is invalid'}`);
+    }
+}
+function requireOne(positionals, usage) {
+    if (positionals.length !== 2 || !positionals[1])
+        throw new CliUsageError(`Usage: ${usage}`);
+    return positionals[1];
+}
+function csv(raw, flag = '--terms') {
+    const values = raw.split(',').map((value) => value.trim()).filter(Boolean);
+    if (!values.length)
+        throw new CliUsageError(`${flag} must contain at least one value`);
+    return [...new Set(values)];
+}
+function requireToolsRunMode(body) {
+    if (TOOLS_RUN_MODES.includes(body.mode))
+        return;
+    throw new CliUsageError('mode must be one of: smoke_test, dry_run, live.');
+}
+function nonNegativeNumber(raw, flag) {
+    const value = Number(raw);
+    if (!Number.isFinite(value) || value < 0)
+        throw new CliUsageError(`${flag} must be a non-negative number`);
+    return value;
+}
+function nonNegativeInteger(raw, flag) {
+    const value = Number(raw);
+    if (!Number.isSafeInteger(value) || value < 0)
+        throw new CliUsageError(`${flag} must be a non-negative integer`);
+    return value;
+}
+function parsePacks(argv) {
+    const { values, positionals } = (0, node_util_1.parseArgs)({ args: argv, options: { goal: { type: 'string' }, 'json-output': { type: 'boolean' }, help: { type: 'boolean', short: 'h' } }, allowPositionals: true, strict: true });
+    if (values.help)
+        return { command: 'help' };
+    if (positionals.length === 1 && positionals[0] === 'list')
+        return { command: 'packs_list', ...outputOption(values) };
+    if (positionals[0] === 'get')
+        return { command: 'packs_get', packId: requireOne(positionals, 'dreamstate packs get <pack_id>'), ...outputOption(values) };
+    if (positionals.length === 1 && positionals[0] === 'route' && values.goal?.trim())
+        return { command: 'packs_route', goal: values.goal.trim(), ...outputOption(values) };
+    throw new CliUsageError('Usage: dreamstate packs <list|get|route>');
+}
+/** Rewrites `--agents a b c` into `--agents=a --agents=b --agents=c` so parseArgs sees every value. */
+function spaceSeparatedAgents(argv) {
+    const out = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        if (argv[index] !== '--agents') {
+            out.push(argv[index]);
+            continue;
+        }
+        let consumed = 0;
+        while (index + 1 < argv.length && !argv[index + 1].startsWith('-')) {
+            out.push(`--agents=${argv[index + 1]}`);
+            index += 1;
+            consumed += 1;
+        }
+        if (!consumed)
+            out.push('--agents');
+    }
+    return out;
+}
+function parseSkills(argv) {
+    const { values, positionals } = (0, node_util_1.parseArgs)({ args: spaceSeparatedAgents(argv), options: { query: { type: 'string' }, limit: { type: 'string' }, skill: { type: 'string' }, agents: { type: 'string', multiple: true }, project: { type: 'boolean' }, copy: { type: 'boolean' }, 'json-output': { type: 'boolean' }, help: { type: 'boolean', short: 'h' } }, allowPositionals: true, strict: true });
+    if (values.help)
+        return { command: 'help' };
+    const agents = () => {
+        if (!values.agents)
+            return [...skillInstaller_1.SKILL_INSTALL_AGENTS];
+        const requested = [...new Set(values.agents.flatMap((raw) => csv(raw, '--agents')))];
+        const invalid = requested.filter((agent) => !skillInstaller_1.SKILL_INSTALL_AGENTS.includes(agent));
+        if (invalid.length)
+            throw new CliUsageError(`--agents values must be one of: ${skillInstaller_1.SKILL_INSTALL_AGENTS.join(', ')} (got: ${invalid.join(', ')})`);
+        return requested;
+    };
+    if (positionals.length === 1 && positionals[0] === 'list') {
+        const query = {};
+        if (values.query)
+            query.query = values.query;
+        if (values.limit !== undefined)
+            query.limit = nonNegativeInteger(values.limit, '--limit');
+        return { command: 'skills_list', query, ...outputOption(values) };
+    }
+    if (positionals[0] === 'get')
+        return { command: 'skills_get', skillId: requireOne(positionals, 'dreamstate skills get <skill_id>'), ...outputOption(values) };
+    if (positionals[0] === 'search' && positionals.length > 1) {
+        const query = { query: positionals.slice(1).join(' ') };
+        if (values.limit !== undefined)
+            query.limit = nonNegativeInteger(values.limit, '--limit');
+        return { command: 'skills_search', query, ...outputOption(values) };
+    }
+    if (positionals.length === 1 && positionals[0] === 'install')
+        return { command: 'skills_install', skillId: values.skill?.trim() || '*', agents: agents(), ...(values.project ? { project: true } : {}), ...(values.copy ? { copy: true } : {}), ...outputOption(values) };
+    if (positionals.length === 1 && positionals[0] === 'doctor')
+        return { command: 'skills_doctor', agents: agents(), ...(values.project ? { project: true } : {}), ...outputOption(values) };
+    throw new CliUsageError('Usage: dreamstate skills <list|get|search|install|doctor>');
+}
+function parseCommands(argv) {
+    const { values, positionals } = (0, node_util_1.parseArgs)({ args: argv, options: { 'json-output': { type: 'boolean' }, help: { type: 'boolean', short: 'h' } }, allowPositionals: true, strict: true });
+    if (values.help)
+        return { command: 'help' };
+    if (positionals[0] !== 'search' || positionals.length < 2)
+        throw new CliUsageError('Usage: dreamstate commands search <term>');
+    return { command: 'commands_search', term: positionals.slice(1).join(' '), ...outputOption(values) };
+}
+/**
+ * One place that turns the mode flags into a mode. --dry-run, --live and --mode
+ * are mutually exclusive ways of saying the same thing, and disagreeing ones are a
+ * usage error rather than a silent winner.
+ *
+ * --approved is deliberately NOT here. It is a retained no-op: the run body schema
+ * is strict and has no `approved` key, so sending it failed the entire call rather
+ * than authorizing anything. Spend authority is max_credits and a human grant
+ * arrives as approval_id.
+ */
+function toolsRunMode(values) {
+    const chosen = new Set();
+    if (values['dry-run'])
+        chosen.add('dry_run');
+    if (values.live)
+        chosen.add('live');
+    if (values.mode !== undefined) {
+        const mode = values.mode.trim();
+        if (!TOOLS_RUN_MODES.includes(mode)) {
+            throw new CliUsageError(`--mode must be one of: ${TOOLS_RUN_MODES.join(', ')}`);
+        }
+        chosen.add(mode);
+    }
+    if (chosen.size > 1) {
+        throw new CliUsageError(`Conflicting execution modes requested: ${[...chosen].sort().join(', ')}. Pass exactly one of --live, --dry-run, --mode.`);
+    }
+    return [...chosen][0];
+}
+function parseTools(argv) {
+    const { values, positionals } = (0, node_util_1.parseArgs)({ args: argv, options: {
+            json: { type: 'string' }, params: { type: 'string' }, goal: { type: 'string' }, terms: { type: 'string' },
+            limit: { type: 'string' }, toolset: { type: 'string' },
+            'idempotency-key': { type: 'string' }, 'json-output': { type: 'boolean' }, open: { type: 'boolean' },
+            'dry-run': { type: 'boolean' }, live: { type: 'boolean' }, mode: { type: 'string' },
+            'agent-session-id': { type: 'string' }, approved: { type: 'boolean' }, 'approved-effect-unknown': { type: 'boolean' },
+            'max-credits': { type: 'string' }, 'turn-token': { type: 'string' }, help: { type: 'boolean', short: 'h' },
+        }, allowPositionals: true, strict: true });
+    if (values.help)
+        return { command: 'help' };
+    const output = outputOption(values);
+    if (positionals.length === 1 && positionals[0] === 'search') {
+        const query = values.json ? parseJsonObject(values.json) : {};
+        if (values.goal)
+            query.goal = values.goal;
+        if (values.terms)
+            query.query_terms = csv(values.terms);
+        if (values.limit !== undefined)
+            query.limit = nonNegativeInteger(values.limit, '--limit');
+        if (values.toolset !== undefined)
+            query.toolset = values.toolset;
+        if (typeof query.goal !== 'string' && !Array.isArray(query.query_terms))
+            throw new CliUsageError('tools search requires --goal, --terms, or --json query fields');
+        return { command: 'tools_search', query, ...output };
+    }
+    if (positionals[0] === 'get')
+        return { command: 'tools_get', capabilityId: requireOne(positionals, 'dreamstate tools get <capability_id>'), ...output };
+    if (positionals[0] === 'run') {
+        const capabilityId = requireOne(positionals, 'dreamstate tools run <capability_id> [--params <object>|--json <body>]');
+        if (values.json && values.params)
+            throw new CliUsageError('Use either --params for tool parameters or --json for the complete request, not both.');
+        if (!values.json && !values.params)
+            throw new CliUsageError('tools run requires --params <object> or --json <body>; fetch live schema first with tools get');
+        const body = values.json ? parseJsonObject(values.json) : {};
+        if (values.params)
+            body.params = parseJsonObject(values.params, '--params');
+        // The server never defaults a mode, so a mutating run with none is refused
+        // mode_required; --live and --mode exist so a caller can actually ask for one.
+        // `approved` is no longer sent: the run body schema is strict and has no such
+        // key, so passing it failed the whole call instead of authorizing anything.
+        const chosenMode = toolsRunMode(values);
+        if (chosenMode)
+            body.mode = chosenMode;
+        if (values['agent-session-id'])
+            body.agent_session_id = values['agent-session-id'];
+        if (values['approved-effect-unknown'])
+            body.approved_effect_unknown = true;
+        if (values['max-credits'] !== undefined)
+            body.max_credits = nonNegativeNumber(values['max-credits'], '--max-credits');
+        // No client-side mode requirement: the server owns that refusal and answers
+        // mode_required with a repair, and the parse grammar is expected to accept a
+        // run without one. What was missing was any way to ASK for live.
+        if (body.mode !== undefined)
+            requireToolsRunMode(body);
+        return { command: 'tools_run', capabilityId, body, ...(values['turn-token'] ? { turnToken: values['turn-token'] } : {}), ...(values['idempotency-key'] ? { idempotencyKey: values['idempotency-key'] } : {}), ...(values.open ? { open: true } : {}), ...output };
+    }
+    throw new CliUsageError('Usage: dreamstate tools <search|get|run>');
+}
+function parseTables(argv) {
+    const { values, positionals } = (0, node_util_1.parseArgs)({ args: argv, options: {
+            'table-id': { type: 'string' }, file: { type: 'string' }, format: { type: 'string' }, background: { type: 'boolean' },
+            preview: { type: 'boolean' }, 'upsert-key': { type: 'string' },
+            'json-output': { type: 'boolean' }, help: { type: 'boolean', short: 'h' },
+        }, allowPositionals: true, strict: true });
+    if (values.help)
+        return { command: 'help' };
+    if (positionals.length !== 1 || positionals[0] !== 'import' || !values['table-id'] || !values.file) {
+        throw new CliUsageError('Usage: dreamstate tables import --table-id <uuid> --file <path> [--format <csv|json|jsonl|xlsx>] [--preview] [--upsert-key <header>] [--background]');
+    }
+    // --format is an override, not a requirement. Requiring it made the caller restate
+    // what the file path already says, and an omitted flag produced a usage error rather
+    // than an import. Omitted, the flag is not forwarded at all and the server derives
+    // the kind from the file it receives.
+    const format = values.format;
+    if (format !== undefined && !['csv', 'json', 'jsonl', 'xlsx'].includes(format)) {
+        throw new CliUsageError('--format must be one of csv, json, jsonl, xlsx');
+    }
+    const upsertKey = values['upsert-key']?.trim();
+    return {
+        command: 'tables_import',
+        tableId: values['table-id'],
+        file: values.file,
+        ...(format ? { format: format } : {}),
+        ...(values.preview ? { preview: true } : {}),
+        ...(upsertKey ? { upsertKey } : {}),
+        background: Boolean(values.background),
+        ...outputOption(values),
+    };
+}
+function parseRuns(argv) {
+    const { values, positionals } = (0, node_util_1.parseArgs)({ args: argv, options: { json: { type: 'string' }, reason: { type: 'string' }, 'state-version': { type: 'string' }, 'idempotency-key': { type: 'string' }, open: { type: 'boolean' }, 'json-output': { type: 'boolean' }, help: { type: 'boolean', short: 'h' } }, allowPositionals: true, strict: true });
+    if (values.help)
+        return { command: 'help' };
+    const output = outputOption(values);
+    if (positionals.length === 1 && positionals[0] === 'list')
+        return { command: 'runs_list', query: values.json ? parseJsonObject(values.json) : {}, ...output };
+    const runId = requireOne(positionals, `dreamstate runs ${positionals[0] ?? '<get|events|cancel>'} <run_id>`);
+    if (positionals[0] === 'get')
+        return { command: 'runs_get', runId, ...output };
+    if (positionals[0] === 'events')
+        return { command: 'runs_events', runId, ...output };
+    if (positionals[0] === 'resume') {
+        if (values.json)
+            throw new CliUsageError('Use --state-version and --reason with runs resume, not --json.');
+        if (values['state-version'] === undefined)
+            throw new CliUsageError('--state-version is required for runs resume.');
+        return { command: 'runs_resume', runId, stateVersion: nonNegativeInteger(values['state-version'], '--state-version'), ...(values.reason ? { reason: values.reason } : {}), ...(values['idempotency-key'] ? { idempotencyKey: values['idempotency-key'] } : {}), ...(values.open ? { open: true } : {}), ...output };
+    }
+    if (positionals[0] === 'cancel') {
+        if (!values.json)
+            throw new CliUsageError('runs cancel requires --json <body>');
+        return { command: 'runs_cancel', runId, body: parseJsonObject(values.json), ...(values['idempotency-key'] ? { idempotencyKey: values['idempotency-key'] } : {}), ...output };
+    }
+    throw new CliUsageError('Usage: dreamstate runs <get|events|cancel> <run_id>');
+}
+function normalizeJsonOutputAlias(argv) {
+    return argv.map((argument, index) => argument === '--json' && (index === argv.length - 1 || argv[index + 1]?.startsWith('-'))
+        ? '--json-output'
+        : argument);
+}
+function parseCliArgs(argv) {
+    argv = normalizeJsonOutputAlias(argv);
+    if (!argv.length || argv[0] === '--help' || argv[0] === '-h')
+        return { command: 'help' };
+    if (argv.length === 1 && (argv[0] === '--version' || argv[0] === '-v'))
+        return { command: 'version' };
+    const [group, ...rest] = argv;
+    if (group === 'login') {
+        const { values, positionals } = (0, node_util_1.parseArgs)({ args: rest, options: { token: { type: 'string' }, 'api-key-file': { type: 'string' }, 'json-output': { type: 'boolean' }, help: { type: 'boolean', short: 'h' } }, allowPositionals: true, strict: true });
+        if (values.help)
+            return { command: 'help' };
+        if (positionals.length)
+            throw new CliUsageError('Usage: dreamstate login [--token <ds_live_...>]');
+        if (values.token !== undefined && values['api-key-file'])
+            throw new CliUsageError('Use either --token or --api-key-file, not both.');
+        return { command: 'login', ...(values.token !== undefined ? { token: values.token } : {}), ...(values['api-key-file'] ? { apiKeyFile: values['api-key-file'] } : {}), ...outputOption(values) };
+    }
+    if (group === 'logout') {
+        const { values, positionals } = (0, node_util_1.parseArgs)({ args: rest, options: { 'json-output': { type: 'boolean' }, help: { type: 'boolean', short: 'h' } }, allowPositionals: true, strict: true });
+        if (values.help)
+            return { command: 'help' };
+        if (positionals.length)
+            throw new CliUsageError('Usage: dreamstate logout');
+        return { command: 'logout', ...outputOption(values) };
+    }
+    if (group === 'whoami') {
+        const { values, positionals } = (0, node_util_1.parseArgs)({ args: rest, options: { 'json-output': { type: 'boolean' } }, allowPositionals: true, strict: true });
+        if (positionals.length === 0)
+            return { command: 'whoami', ...outputOption(values) };
+        throw new CliUsageError('Usage: dreamstate whoami [--json-output]');
+    }
+    if (group === 'auth') {
+        const { values, positionals } = (0, node_util_1.parseArgs)({ args: rest, options: { 'api-key-file': { type: 'string' }, 'json-output': { type: 'boolean' } }, allowPositionals: true, strict: true });
+        if (positionals.length === 1 && positionals[0] === 'login')
+            return { command: 'login', ...(values['api-key-file'] ? { apiKeyFile: values['api-key-file'] } : {}), ...outputOption(values) };
+        if (positionals.length === 1 && positionals[0] === 'whoami')
+            return { command: 'whoami', ...outputOption(values) };
+        throw new CliUsageError('Usage: dreamstate auth <login|whoami>');
+    }
+    if (group === 'packs')
+        return parsePacks(rest);
+    if (group === 'skills')
+        return parseSkills(rest);
+    if (group === 'commands')
+        return parseCommands(rest);
+    if (group === 'tools')
+        return parseTools(rest);
+    if (group === 'tables')
+        return parseTables(rest);
+    if (group === 'runs')
+        return parseRuns(rest);
+    if (group === 'sequences')
+        return require('./commands/sequences').parseSequencesCommand(rest);
+    if (group === 'workflows')
+        return require('./commands/workflows').parseWorkflowsCommand(rest);
+    throw new CliUsageError(`Unknown command: ${group}`);
+}
+function print(value, stdout, compact) {
+    stdout.write(`${JSON.stringify(value, (key, nested) => key === 'tool_turn_token' ? undefined : nested, compact ? 0 : 2)}\n`);
+}
+function printPackRoute(value, stdout) {
+    const data = value && typeof value === 'object' && !Array.isArray(value)
+        ? value.data
+        : null;
+    const result = data && typeof data === 'object' && !Array.isArray(data)
+        ? data
+        : {};
+    const route = result.route && typeof result.route === 'object' && !Array.isArray(result.route)
+        ? result.route
+        : null;
+    if (route && typeof route.pack_id === 'string' && typeof route.posture === 'string') {
+        stdout.write(`Pack: ${route.pack_id}\nPosture: ${route.posture}\nRecommended capability ids:\n`);
+        for (const capabilityId of Array.isArray(route.recommended_capability_ids) ? route.recommended_capability_ids : []) {
+            if (typeof capabilityId === 'string')
+                stdout.write(`${capabilityId}\n`);
+        }
+        return;
+    }
+    stdout.write('No matching pack.\nPacks considered:\n');
+    for (const alternate of Array.isArray(result.alternates) ? result.alternates : []) {
+        if (!alternate || typeof alternate !== 'object' || Array.isArray(alternate))
+            continue;
+        const { pack_id: packId, reason } = alternate;
+        if (typeof packId === 'string')
+            stdout.write(`${packId}${typeof reason === 'string' ? `: ${reason}` : ''}\n`);
+    }
+}
+function toolTurnToken(value) {
+    const root = value && typeof value === 'object' ? value : {};
+    const data = root.data && typeof root.data === 'object' ? root.data : {};
+    if (typeof data.tool_turn_token === 'string' && data.tool_turn_token.trim())
+        return data.tool_turn_token;
+    throw new client_1.CliError('tools get did not return a tool_turn_token.', 'invalid_tool_turn_token', 0);
+}
+function code(error) {
+    return error && typeof error === 'object' && typeof error.code === 'string'
+        ? error.code
+        : undefined;
+}
+function refusalEnvelope(error, exitCode) {
+    const cliError = error instanceof client_1.CliError ? error : null;
+    return {
+        ok: false,
+        executed: false,
+        error: {
+            code: code(error) ?? 'invalid_request',
+            message: error instanceof Error ? error.message : String(error),
+            ...(cliError?.details === undefined ? {} : { details: cliError.details }),
+            // The client keeps the server's retry decision and repair; dropping them
+            // here left CLI automation without the recovery Architect and MCP get.
+            ...(cliError?.retryable === undefined ? {} : { retryable: cliError.retryable }),
+            ...(cliError?.repair === undefined ? {} : { repair: cliError.repair }),
+        },
+        meta: { exit_code: exitCode },
+    };
+}
+function openWebUrl(rawUrl, launch = node_child_process_1.spawn) {
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        throw new client_1.CliError('The API returned an invalid web_url.', 'invalid_web_url', 0);
+    }
+    if (!['https:', 'http:'].includes(url.protocol) || rawUrl.length > 4_096) {
+        throw new client_1.CliError('The API returned an unsafe web_url.', 'invalid_web_url', 0);
+    }
+    const target = url.toString();
+    const [command, args] = process.platform === 'darwin'
+        ? ['open', [target]]
+        : process.platform === 'win32'
+            ? ['rundll32', ['url.dll,FileProtocolHandler', target]]
+            : ['xdg-open', [target]];
+    launch(command, args, { detached: true, stdio: 'ignore', shell: false }).unref();
+}
+function resultWebUrl(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const envelope = value;
+    const meta = envelope.meta && typeof envelope.meta === 'object' && !Array.isArray(envelope.meta)
+        ? envelope.meta
+        : {};
+    if (typeof meta.web_url === 'string')
+        return meta.web_url;
+    const data = envelope.data && typeof envelope.data === 'object' && !Array.isArray(envelope.data)
+        ? envelope.data
+        : {};
+    return typeof data.web_url === 'string' ? data.web_url : null;
+}
+function openResult(value, runtime) {
+    const webUrl = resultWebUrl(value);
+    if (!webUrl)
+        throw new client_1.CliError('The API response did not include a web_url.', 'web_url_unavailable', 0);
+    (runtime.openWebUrl ?? openWebUrl)(webUrl);
+}
+function discoveredCapabilityId(value) {
+    const root = value && typeof value === 'object' ? value : {};
+    const data = root.data && typeof root.data === 'object' ? root.data : {};
+    const candidates = ['tools', 'capabilities', 'results'].flatMap((key) => Array.isArray(data[key]) ? data[key] : [])
+        .map((candidate) => candidate && typeof candidate === 'object'
+        ? candidate.capability_id ?? candidate.id
+        : undefined)
+        .filter((candidate) => typeof candidate === 'string' && candidate.length > 0);
+    const ids = [...new Set(candidates)];
+    if (ids.length !== 1)
+        throw new CliUsageError('Local file import discovery must return exactly one capability.');
+    return ids[0];
+}
+function hostedSkill(value) {
+    const root = value && typeof value === 'object' ? value : {};
+    const data = root.data && typeof root.data === 'object' ? root.data : {};
+    const skill = data.skill;
+    if (!skill || typeof skill !== 'object')
+        throw new client_1.CliError('Dreamstate API returned an invalid skill document.', 'invalid_response', 200);
+    const entry = skill;
+    if (typeof entry.id !== 'string' || typeof entry.name !== 'string' || typeof entry.description !== 'string' || typeof entry.body !== 'string') {
+        throw new client_1.CliError('Dreamstate API returned an invalid skill document.', 'invalid_response', 200);
+    }
+    const frontmatter = entry.frontmatter && typeof entry.frontmatter === 'object' && !Array.isArray(entry.frontmatter)
+        ? entry.frontmatter : undefined;
+    const documents = Array.isArray(entry.documents)
+        ? entry.documents.filter((document) => Boolean(document) && typeof document === 'object' && typeof document.name === 'string' && typeof document.content === 'string')
+        : undefined;
+    return { id: entry.id, name: entry.name, description: entry.description, body: entry.body, frontmatter, documents };
+}
+function exitCodeForError(error) {
+    if (code(error)?.startsWith('ERR_PARSE_ARGS'))
+        return exports.CLI_EXIT.USAGE;
+    if (error instanceof CliUsageError || error instanceof config_1.ApiKeyFileError || error instanceof config_1.ApiBaseUrlError || error instanceof config_1.MissingApiUrlError)
+        return exports.CLI_EXIT.USAGE;
+    if (error instanceof config_1.MissingApiKeyError)
+        return exports.CLI_EXIT.AUTH;
+    if (code(error) === 'request_timeout')
+        return exports.CLI_EXIT.TIMEOUT;
+    const status = error instanceof client_1.CliError ? error.status : 0;
+    if (status === 401 || status === 403)
+        return exports.CLI_EXIT.AUTH;
+    if (status === 404)
+        return exports.CLI_EXIT.NOT_FOUND;
+    if (status === 429)
+        return exports.CLI_EXIT.RATE_LIMITED;
+    if (code(error) === 'network_error')
+        return exports.CLI_EXIT.TRANSPORT;
+    if (status >= 500 || code(error) === 'invalid_response')
+        return exports.CLI_EXIT.SERVER;
+    if (status >= 400)
+        return exports.CLI_EXIT.REFUSED;
+    return exports.CLI_EXIT.UNCLASSIFIED;
+}
+async function readLoginKey(command, runtime) {
+    if (command.apiKeyFile)
+        return (0, config_1.readApiKeyFile)(command.apiKeyFile);
+    const fromEnv = (runtime.env ?? process.env).DREAMSTATE_API_KEY?.trim();
+    if (fromEnv)
+        return fromEnv;
+    const stdin = runtime.stdin ?? process.stdin;
+    if (!stdin.isTTY) {
+        let value = '';
+        for await (const part of stdin)
+            value += part.toString();
+        if (value.trim())
+            return value.trim();
+    }
+    if (runtime.promptHidden)
+        return runtime.promptHidden('API key (input hidden): ');
+    throw new CliUsageError('No API key provided. Pipe it on stdin, set DREAMSTATE_API_KEY, or pass --api-key-file.');
+}
+function deviceState() {
+    return (0, node_crypto_1.randomBytes)(32).toString('base64url');
+}
+function runtimeCredentialsPath(runtime) {
+    return runtime.credentialsPath ?? (0, config_1.credentialsPath)(undefined, runtime.env ?? process.env);
+}
+function wait(milliseconds) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+async function loginWithDeviceAuthorization(runtime, stdout, stderr) {
+    const environment = runtime.env ?? process.env;
+    const baseUrl = (0, config_1.resolveApiBaseUrl)(environment);
+    const state = runtime.deviceState ?? deviceState();
+    const authorization = await (0, client_1.requestDeviceAuthorization)(baseUrl, {
+        state,
+        client: { os: process.platform, hostname: (0, node_os_1.hostname)(), cli_version: client_1.CLI_VERSION },
+    });
+    stderr.write(`Open: ${authorization.verification_uri_complete}\nConfirmation code: ${authorization.user_code}\n`);
+    (runtime.openWebUrl ?? openWebUrl)(authorization.verification_uri_complete);
+    for (;;) {
+        const claim = await (0, client_1.claimDeviceAuthorization)(baseUrl, authorization.device_code);
+        if (claim.status === 'ready') {
+            await (0, config_1.storeApiKey)(claim.token, runtimeCredentialsPath(runtime));
+            const client = new client_1.DreamstateClient({
+                baseUrl,
+                apiKey: claim.token,
+                requestTimeoutMs: runtime.requestTimeoutMs,
+                onVersionWarning: (message) => (runtime.stderr ?? process.stderr).write(`${message}\n`),
+            });
+            print(await client.getWhoami(), stdout, false);
+            return;
+        }
+        await (runtime.sleep ?? wait)(authorization.interval_seconds * 1_000);
+    }
+}
+function ignoreBrokenPipe(stdout) {
+    // EPIPE is an async stream 'error', not a rejected promise. runCli().catch
+    // does not see it. A closed stdout (piped to head) must keep the exit code
+    // the command already set and must not dump a stack.
+    const emitter = stdout;
+    if (typeof emitter.on !== 'function')
+        return;
+    emitter.on('error', (error) => {
+        if (error.code !== 'EPIPE')
+            throw error;
+    });
+}
+async function runCli(argv = process.argv.slice(2), runtime = {}) {
+    const stdout = runtime.stdout ?? process.stdout;
+    const stderr = runtime.stderr ?? process.stderr;
+    ignoreBrokenPipe(stdout);
+    ignoreBrokenPipe(stderr);
+    try {
+        const command = parseCliArgs(argv);
+        if (command.command === 'help') {
+            print({ ok: true, data: { usage: USAGE }, meta: {} }, stdout, false);
+            process.exitCode = exports.CLI_EXIT.SUCCESS;
+            return;
+        }
+        if (command.command === 'version') {
+            print({ ok: true, data: { version: client_1.CLI_VERSION }, meta: {} }, stdout, false);
+            process.exitCode = exports.CLI_EXIT.SUCCESS;
+            return;
+        }
+        if (command.command === 'logout') {
+            const path = runtimeCredentialsPath(runtime);
+            let removed = true;
+            try {
+                await (0, promises_1.access)(path);
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+                removed = false;
+            }
+            if (removed)
+                await (0, promises_1.rm)(path, { force: true });
+            const message = removed ? `Removed ${path}` : `Already logged out: no credentials at ${path}`;
+            stderr.write(`${message}\n`);
+            print({ ok: true, data: { credentials_path: path, removed }, meta: {} }, stdout, Boolean(command.jsonOutput));
+            process.exitCode = exports.CLI_EXIT.SUCCESS;
+            return;
+        }
+        if (command.command === 'login' && command.token !== undefined) {
+            const token = command.token.trim();
+            if (!token.startsWith('ds_live_') || token.length <= 'ds_live_'.length)
+                throw new CliUsageError('--token must be a Dreamstate API key starting with ds_live_.');
+            const baseUrl = (0, config_1.resolveApiBaseUrl)(runtime.env ?? process.env);
+            const client = new client_1.DreamstateClient({
+                baseUrl,
+                apiKey: token,
+                requestTimeoutMs: runtime.requestTimeoutMs,
+                onVersionWarning: (message) => stderr.write(`${message}\n`),
+            });
+            const whoami = await client.getWhoami();
+            await (0, config_1.storeApiKey)(token, runtimeCredentialsPath(runtime));
+            print(whoami, stdout, Boolean(command.jsonOutput));
+            process.exitCode = exports.CLI_EXIT.SUCCESS;
+            return;
+        }
+        if (command.command === 'login') {
+            if (command.apiKeyFile || (runtime.env ?? process.env).DREAMSTATE_API_KEY || runtime.promptHidden) {
+                const key = await readLoginKey(command, runtime);
+                if (!key.startsWith('ds_live_'))
+                    throw new CliUsageError('Dreamstate API keys must start with ds_live_.');
+                const path = await (0, config_1.storeApiKey)(key, runtimeCredentialsPath(runtime));
+                print({ ok: true, data: { credentials_path: path }, meta: {} }, stdout, Boolean(command.jsonOutput));
+                stderr.write('Run dreamstate skills install to install Dreamstate skills.\n');
+                process.exitCode = exports.CLI_EXIT.SUCCESS;
+                return;
+            }
+            await loginWithDeviceAuthorization(runtime, stdout, stderr);
+            stderr.write('Run dreamstate skills install to install Dreamstate skills.\n');
+            process.exitCode = exports.CLI_EXIT.SUCCESS;
+            return;
+        }
+        if (command.command === 'skills_doctor') {
+            const environment = runtime.env ?? process.env;
+            const baseUrl = (0, config_1.resolveApiBaseUrl)(environment);
+            const credentialFilePath = runtimeCredentialsPath(runtime);
+            const apiKey = await (0, config_1.resolveApiKey)(environment, credentialFilePath);
+            const client = new client_1.DreamstateClient({ baseUrl, apiKey, requestTimeoutMs: runtime.requestTimeoutMs });
+            await client.listSkills({ limit: 1 });
+            const installers = await (0, skillInstaller_1.inspectSkillInstallers)(command.agents, runtime.homeDirectory, Boolean(command.project));
+            print({ ok: true, data: { index_reachable: true, installers }, meta: {} }, stdout, Boolean(command.jsonOutput));
+            process.exitCode = exports.CLI_EXIT.SUCCESS;
+            return;
+        }
+        // Preview parses the local file and writes nothing, so it must not require a key.
+        if (command.command === 'tables_import' && command.preview) {
+            await (0, promises_1.access)(command.file);
+            try {
+                const preview = await (0, tableFilePreview_1.previewLocalTableFile)(command.file, command.format);
+                print({
+                    ok: true,
+                    data: { ...preview, table_id: command.tableId, file_path: command.file, upsert_key: command.upsertKey ?? null },
+                    meta: {},
+                }, stdout, Boolean(command.jsonOutput));
+            }
+            catch (error) {
+                throw new CliUsageError(error instanceof CliUsageError ? error.message : error instanceof Error ? error.message : String(error));
+            }
+            process.exitCode = exports.CLI_EXIT.SUCCESS;
+            return;
+        }
+        // init writes a local scaffold and calls no API, so it must not require a key.
+        // Resolving credentials first would refuse it with not_authenticated.
+        if (command.command === 'pack' && command.verb === 'init') {
+            if (command.pack === 'sequences') {
+                await require('./commands/sequences')
+                    .runSequencesCommand(undefined, command, stdout);
+            }
+            else {
+                await require('./commands/workflows')
+                    .runWorkflowsCommand(undefined, command, stdout);
+            }
+            process.exitCode = exports.CLI_EXIT.SUCCESS;
+            return;
+        }
+        const environment = runtime.env ?? process.env;
+        const baseUrl = (0, config_1.resolveApiBaseUrl)(environment);
+        const credentialFilePath = runtimeCredentialsPath(runtime);
+        let apiKey;
+        try {
+            apiKey = await (0, config_1.resolveApiKey)(environment, credentialFilePath);
+        }
+        catch (error) {
+            if (command.command === 'skills_install' && error instanceof config_1.MissingApiKeyError) {
+                throw new client_1.CliError('Dreamstate skills installation requires authentication.', 'skills_authentication_required', 401, {
+                    details: { next_step: 'Run dreamstate login, then retry' },
+                });
+            }
+            throw error;
+        }
+        const client = new client_1.DreamstateClient({
+            baseUrl,
+            apiKey,
+            requestTimeoutMs: runtime.requestTimeoutMs,
+            onVersionWarning: (message) => (runtime.stderr ?? process.stderr).write(`${message}\n`),
+        });
+        let result;
+        switch (command.command) {
+            case 'whoami':
+                result = await client.getWhoami();
+                break;
+            case 'packs_list':
+                result = await client.listPacks();
+                break;
+            case 'packs_get':
+                result = await client.getPack(command.packId);
+                break;
+            case 'packs_route':
+                result = await client.routePack(command.goal);
+                break;
+            case 'skills_list':
+                result = await client.listSkills(command.query);
+                break;
+            case 'skills_get':
+                result = await client.getSkill(command.skillId);
+                break;
+            case 'skills_search':
+                result = await client.searchSkillDocuments(command.query);
+                break;
+            case 'skills_install': {
+                const listed = command.skillId === '*' ? await client.listAllSkills() : null;
+                const entries = listed && typeof listed === 'object' && listed.data?.skills;
+                const ids = command.skillId === '*'
+                    ? Array.isArray(entries) ? entries.map((skill) => skill && typeof skill === 'object' ? skill.id : undefined).filter((id) => typeof id === 'string') : []
+                    : [command.skillId];
+                if (!ids.length)
+                    throw new client_1.CliError('Dreamstate API returned no installable skills.', 'invalid_response', 200);
+                // A remote id becomes a directory name; refuse traversal before any request or write.
+                if (ids.some((id) => !/^[a-z0-9][a-z0-9_-]*$/i.test(id)))
+                    throw new CliUsageError('Dreamstate API returned an invalid skill id.');
+                const skills = await Promise.all(ids.map(async (id) => {
+                    const skill = hostedSkill(await client.getSkill(id));
+                    if (!/^[a-z0-9][a-z0-9_-]*$/i.test(skill.id))
+                        throw new CliUsageError('Dreamstate API returned an invalid skill id.');
+                    if (skill.id !== id)
+                        throw new client_1.CliError('Dreamstate API returned a mismatched skill id.', 'invalid_response', 200);
+                    return skill;
+                }));
+                const packs = await client.listPacks();
+                const installed = await (0, skillInstaller_1.installSkills)([...skills, (0, skillInstaller_1.routerSkill)(packs)], {
+                    agents: command.agents,
+                    homeDirectory: runtime.homeDirectory,
+                    project: Boolean(command.project),
+                    copy: Boolean(command.copy) || process.platform === 'win32',
+                });
+                result = { ok: true, data: { installed_files: installed.files, skill_ids: [...ids, 'router'], agents: command.agents, ...(command.project ? { lock_file: 'skills-lock.json' } : {}) }, meta: {} };
+                break;
+            }
+            case 'commands_search':
+                result = await client.listTools({ goal: command.term });
+                break;
+            case 'tools_search':
+                result = await client.listTools(command.query);
+                break;
+            case 'tools_get':
+                result = await client.getTool(command.capabilityId);
+                break;
+            case 'tools_run': {
+                // A quote binds to the turn that asked for it. Reuse a turn only while
+                // a quote is pending (after a dry run or a quote_required refusal), and
+                // forget it once the paid run is admitted, so every other call keeps
+                // fetching a fresh turn exactly as before.
+                const turns = (0, turnCache_1.turnCachePath)(credentialFilePath);
+                let warnedAboutTurnCache = false;
+                const warnTurnCache = () => {
+                    if (warnedAboutTurnCache)
+                        return;
+                    warnedAboutTurnCache = true;
+                    stderr.write('Warning: Dreamstate turn cache unavailable; continuing without turn reuse.\n');
+                };
+                const pending = command.turnToken
+                    ? null
+                    : await (0, turnCache_1.reusableTurnToken)(turns, baseUrl, apiKey, command.capabilityId, Date.now(), warnTurnCache);
+                const turnToken = command.turnToken ?? pending ?? toolTurnToken(await client.getTool(command.capabilityId));
+                try {
+                    result = await client.runCapability(command.capabilityId, { ...command.body, tool_turn_token: turnToken }, command.idempotencyKey);
+                }
+                catch (error) {
+                    if (!command.turnToken && code(error) === 'quote_required') {
+                        await (0, turnCache_1.rememberTurnToken)(turns, baseUrl, apiKey, command.capabilityId, turnToken, Date.now(), warnTurnCache);
+                    }
+                    throw error;
+                }
+                if (!command.turnToken) {
+                    if (command.body.mode === 'dry_run')
+                        await (0, turnCache_1.rememberTurnToken)(turns, baseUrl, apiKey, command.capabilityId, turnToken, Date.now(), warnTurnCache);
+                    else if (pending)
+                        await (0, turnCache_1.forgetTurnToken)(turns, baseUrl, apiKey, command.capabilityId, warnTurnCache);
+                }
+                break;
+            }
+            case 'tables_import': {
+                await (0, promises_1.access)(command.file);
+                const discovered = await client.listTools({
+                    goal: 'prepare a local file import into a table',
+                    query_terms: ['local', 'file', 'import'],
+                });
+                const importCapabilityId = discoveredCapabilityId(discovered);
+                result = await client.runCapability(importCapabilityId, {
+                    // A mutation run needs the turn token its own get minted; without it
+                    // an API-key import was refused after the local file work.
+                    tool_turn_token: toolTurnToken(await client.getTool(importCapabilityId)),
+                    mode: 'live',
+                    params: {
+                        table_id: command.tableId,
+                        file_path: command.file,
+                        ...(command.format ? { file_kind: command.format } : {}),
+                        ...(command.upsertKey ? { upsert_key: command.upsertKey } : {}),
+                    },
+                });
+                break;
+            }
+            case 'runs_list':
+                result = await client.listRuns(command.query);
+                break;
+            case 'runs_get':
+                result = await client.getRun(command.runId);
+                break;
+            case 'runs_resume':
+                result = await client.resumeRun(command.runId, {
+                    expected_state_version: command.stateVersion,
+                    ...(command.reason ? { reason: command.reason } : {}),
+                }, command.idempotencyKey);
+                break;
+            case 'runs_events':
+                result = await client.getRunEvents(command.runId);
+                break;
+            case 'runs_cancel':
+                result = await client.cancelRun(command.runId, command.body, command.idempotencyKey);
+                break;
+            case 'pack': {
+                if (command.pack === 'sequences') {
+                    await require('./commands/sequences').runSequencesCommand(client, command, stdout);
+                }
+                else {
+                    await require('./commands/workflows').runWorkflowsCommand(client, command, stdout);
+                }
+                return;
+            }
+            default: return;
+        }
+        if ((command.command === 'tools_run' || command.command === 'runs_resume') && command.open)
+            openResult(result, runtime);
+        if (command.command === 'packs_route' && !command.jsonOutput)
+            printPackRoute(result, stdout);
+        else
+            print(result, stdout, Boolean(command.jsonOutput));
+        process.exitCode = exports.CLI_EXIT.SUCCESS;
+    }
+    catch (error) {
+        const exitCode = exitCodeForError(error);
+        stdout.write(`${JSON.stringify(refusalEnvelope(error, exitCode))}\n`);
+        process.exitCode = exitCode;
+        throw error;
+    }
+}
+if (require.main === module)
+    runCli().catch(() => undefined);