@tapicker/bridge 1.0.0 → 1.1.0

package/dist/cli.js

@@ -1,33 +1,39 @@
 #!/usr/bin/env node
 import { cac } from 'cac';
-import { chmodSync, closeSync, openSync, readFileSync } from 'node:fs';
+import { chmodSync, closeSync, constants, openSync, readFileSync } from 'node:fs';
 import { fork } from 'node:child_process';
-import { mkdir } from 'node:fs/promises';
-import { resolve } from 'node:path';
+import { access, mkdir, open, rm, stat } from 'node:fs/promises';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { join, parse, resolve, sep } from 'node:path';
 import { serveStdio } from '@modelcontextprotocol/server/stdio';
 import { DEFAULT_HOST, DEFAULT_PORT, VERSION } from './constants.js';
 import { BridgeError, serializeBridgeError } from './errors.js';
 import { createHttpMcpApi, createTapickerMcpServer } from './mcp.js';
-import { DataInputSchema, WorkflowControlInputSchema, WorkflowStartInputSchema, WorkflowStatusEventSchema, } from './protocol/schema.js';
-import { connectWorkflowWatch, waitForWorkflowStatus, workflowWatchWebSocketUrl } from './workflow-watch.js';
+import { createHttpBridgeApi, parseBridgeUrl } from './http-client.js';
+import { DataInputSchema, DataGetInputSchema, DataExportInputSchema, DataExportResultSchema, DataListInputSchema, DataPreviewInputSchema, WorkflowControlInputSchema, WorkflowStartInputSchema, WorkflowStartResultSchema, WorkflowStatusEventSchema, WorkflowStatusInputSchema, WorkflowLogsInputSchema, WorkflowLogInputSchema, WorkflowListInputSchema, WorkflowGetInputSchema, WorkflowCreateInputSchema, WorkflowUpdateInputSchema, WorkflowGuideInputSchema, WorkflowSchemaInputSchema, WorkflowValidateInputSchema, } from './protocol/schema.js';
+import { connectWorkflowStatusWatch, waitForWorkflowStatus, workflowStatusWatchWebSocketUrl } from './workflow-watch.js';
 import { BridgeServer } from './server.js';
+import { showCachedUpdate } from './update-notifier.js';
 import { getDefaultBridgeDataDir } from './bridge/pairing-state.js';
 import { sendBridgeControlRequest, startBridgeControlServer } from './bridge/control.js';
 import { getBridgeDaemonLogPath, isProcessRunning, readBridgeDaemonState, removeBridgeDaemonState, writeBridgeDaemonState, } from './bridge/daemon.js';
 const DAEMON_CHILD_ENV = 'TAPICKER_BRIDGE_DAEMON_CHILD';
 const cli = cac('tapicker');
+const defaultBridgeUrl = process.env.TAPICKER_BRIDGE_URL || `http://${DEFAULT_HOST}:${DEFAULT_PORT}`;
 cli
     .command('bridge <action>', 'Manage Bridge: start/stop it, view the pairing code, or list connected Extensions')
-    .option('--host <host>', 'Host to bind', { default: DEFAULT_HOST })
+    .option('--host <host>', 'Host to bind')
     .option('--port <port>', 'Port to bind; defaults to the first available port from 9520 to 9530')
     .option('--token <token>', 'Bearer token for HTTP command clients')
-    .option('--cors-origin <origins>', 'Comma-separated allowed HTTP origins (default: *)', { default: '*' })
+    .option('--cors-origin <origins>', 'Comma-separated allowed HTTP origins (default: *)')
     .option('--tls-key <path>', 'TLS private key path')
     .option('--tls-cert <path>', 'TLS certificate path')
     .option('--data-dir <path>', 'Directory for Bridge state and logs')
     .option('--daemon', 'Run Bridge as a daemon')
     .option('--refresh', 'Rotate the pairing code and unlock pairing')
     .action(async (action, options) => {
+    validateActionOptions(action, options, bridgeCommonOptions, bridgeActionOptions);
     if (action === 'start') {
         if (options.daemon && process.env[DAEMON_CHILD_ENV] !== '1') {
             await startBridgeInBackground(options);
@@ -52,61 +58,136 @@ cli
     throw new BridgeError('CommandNotFound', `Unsupported bridge action: ${action}`, { status: 404 });
 });
 cli
-    .command('workflow <action> <workflowId>', 'Start, pause, resume, stop, query, or watch a Workflow')
-    .option('--args <json>', 'Workflow input as a JSON object (start only)', { default: '{}' })
-    .option('--tab <target>', 'Target tab: active, new, or id:<tabId> (start only)')
-    .option('--host <host>', 'Bridge host', { default: DEFAULT_HOST })
-    .option('--port <port>', 'Bridge port', { default: String(DEFAULT_PORT) })
+    .command('workflow <action> [target] [logId]', 'Read guides, validate nodes, list/get/create/update Workflows, control execution, or query logs')
+    .option('--scope <scope>', 'Workflow list scope: own, shared or pinned (list only)')
+    .option('--name <name>', 'Match a substring of Workflow full names (list only)')
+    .option('--host <host>', 'Match Workflow host exactly, without a scheme or path (list only)')
+    .option('--page <page>', 'Page number (list only; default: 1)')
+    .option('--page-size <count>', 'Page size, 1–100 (list only; default: 20)')
+    .option('--node-types <types>', 'Comma-separated node types to use (schema only; omit for all business nodes)')
+    .option('--json <json>', 'Inline JSON request (validate, create or update only)')
+    .option('--args <json>', 'Workflow input as a JSON object (start only; default: {})')
+    .option('--url <url>', 'Bridge HTTP(S) URL (or TAPICKER_BRIDGE_URL)', { default: defaultBridgeUrl })
     .option('--token <token>', 'Bridge Bearer token')
     .option('--client-id <clientId>', 'Target Extension clientId when multiple Extensions are connected')
-    .option('--https', 'Use HTTPS when calling the Bridge')
-    .option('--watch', 'After start, stream status updates until the Workflow reaches a terminal state')
+    .option('--watch', 'Wait for status updates until stopped (start or status only)')
     .option('--timeout <milliseconds>', 'Maximum watch duration; does not stop the Workflow')
-    .action(async (action, workflowId, options) => {
+    .option('--levels <levels>', 'Comma-separated exact log levels (logs only)')
+    .option('--limit <count>', 'Number of matching logs, 1–500 (default: 100)')
+    .option('--before <id>', 'Read logs before this ID (exclusive)')
+    .option('--after <id>', 'Read logs after this ID (exclusive)')
+    .option('--run-at <timestamp>', 'Require the saved runAt to match (status, logs, or log)')
+    .option('--include-data-summary', 'Include saved data changes (status without --watch only)')
+    .action(async (action, workflowId, logId, options) => {
+    validateActionOptions(action, options, workflowCommonOptions, workflowActionOptions);
+    if (options.timeout !== undefined && !options.watch) {
+        throw new BridgeError('InvalidArguments', '--timeout requires --watch', { status: 400 });
+    }
+    if (action === 'guide' ||
+        action === 'schema' ||
+        action === 'validate' ||
+        action === 'list' ||
+        action === 'get' ||
+        action === 'create' ||
+        action === 'update') {
+        // cac 忽略单独的 -；恢复约定的 stdin 标记，不影响其他动作的位置参数。
+        if ((action === 'validate' || action === 'create' || action === 'update') &&
+            workflowId === undefined &&
+            process.argv.includes('-'))
+            workflowId = '-';
+        await queryWorkflowAuthoring(action, workflowId, logId, options);
+        return;
+    }
+    if (!workflowId) {
+        throw new BridgeError('InvalidArguments', 'workflowId is required for this action', { status: 400 });
+    }
+    if (action === 'logs' || action === 'log') {
+        await queryWorkflowLogs(action, workflowId, logId, options);
+        return;
+    }
+    if (logId !== undefined)
+        throw new BridgeError('InvalidArguments', 'logId is only valid for workflow log', { status: 400 });
     if (action === 'start') {
         await startWorkflow(workflowId, options);
         return;
     }
-    if (action === 'pause' || action === 'resume' || action === 'stop' || action === 'status') {
-        await controlWorkflow(action, workflowId, options);
+    if (action === 'status' && options.watch) {
+        if (options.runAt !== undefined || options.includeDataSummary !== undefined) {
+            throw new BridgeError('InvalidArguments', '--run-at and --include-data-summary require a single status query', { status: 400 });
+        }
+        await watchWorkflowStatus(workflowId, options);
         return;
     }
-    if (action === 'watch') {
-        await watchWorkflow(workflowId, options);
+    if (action === 'pause' || action === 'resume' || action === 'stop' || action === 'status') {
+        await controlWorkflow(action, workflowId, options);
         return;
     }
     throw new BridgeError('CommandNotFound', `Unsupported workflow action: ${action}`, { status: 404 });
 });
 cli
-    .command('data <action> <tableId>', 'Get or delete an extracted data table by its ID')
-    .option('--host <host>', 'Bridge host', { default: DEFAULT_HOST })
-    .option('--port <port>', 'Bridge port', { default: String(DEFAULT_PORT) })
+    .command('data <action> [tableId]', 'List, preview, read, export, or delete saved data tables')
+    .option('--url <url>', 'Bridge HTTP(S) URL (or TAPICKER_BRIDGE_URL)', { default: defaultBridgeUrl })
     .option('--token <token>', 'Bridge Bearer token')
     .option('--client-id <clientId>', 'Target Extension clientId when multiple Extensions are connected')
-    .option('--https', 'Use HTTPS when calling the Bridge')
+    .option('--sample <sample>', 'Oldest or latest rows (preview only; default: oldest)')
+    .option('--all', 'Read the full table (get only)')
+    .option('--format <format>', 'File format (export only; default: csv)')
+    .option('--output <path>', 'Destination file or existing directory (export only)')
+    .option('--table-name <name>', 'Filter by table name (list only)')
+    .option('--workflow-id <workflowId>', 'Filter by owning Workflow ID (list only)')
+    .option('--page <page>', 'Page number (list or get; default: 1)')
+    .option('--page-size <count>', 'Page size (list or get)')
     .action(async (action, tableId, options) => {
-    if (action !== 'get' && action !== 'delete') {
-        throw new BridgeError('CommandNotFound', `Unsupported data action: ${action}`, { status: 404 });
+    validateActionOptions(action, options, dataCommonOptions, dataActionOptions);
+    if (action === 'export') {
+        await exportDataTable(tableId, options);
+        return;
+    }
+    if (action === 'list' && tableId !== undefined) {
+        throw new BridgeError('InvalidArguments', 'data list accepts filters as options', { status: 400 });
     }
-    const parsed = DataInputSchema.safeParse({ tableId });
+    const pagination = {
+        page: options.page === undefined ? undefined : Number(options.page),
+        pageSize: options.pageSize === undefined ? undefined : Number(options.pageSize),
+    };
+    const parsed = action === 'list'
+        ? DataListInputSchema.safeParse({ ...pagination, tableName: options.tableName, workflowId: options.workflowId })
+        : action === 'preview'
+            ? DataPreviewInputSchema.safeParse({ tableId, sample: options.sample })
+            : action === 'get'
+                ? DataGetInputSchema.safeParse({ ...pagination, tableId, all: options.all })
+                : DataInputSchema.safeParse({ tableId });
     if (!parsed.success) {
         throw new BridgeError('InvalidArguments', `Invalid data ${action} arguments`, {
             status: 400,
-            details: parsed.error.issues,
+            details: { issues: parsed.error.issues },
         });
     }
-    await sendDataCommand(`data.${action}`, parsed.data, options);
+    await printBridgeCommandResult(`data.${action}`, parsed.data, options);
+});
+cli
+    .command('user <action>', 'Read the current Tapicker account in an Extension')
+    .option('--url <url>', 'Bridge HTTP(S) URL (or TAPICKER_BRIDGE_URL)', { default: defaultBridgeUrl })
+    .option('--token <token>', 'Bridge Bearer token')
+    .option('--client-id <clientId>', 'Target Extension clientId when multiple Extensions are connected')
+    .example('tapicker user me')
+    .action(async (action, options) => {
+    validateActionOptions(action, options, workflowCommonOptions, { me: [] });
+    if (cli.args.length > 1) {
+        throw new BridgeError('InvalidArguments', 'user me does not take positional arguments', { status: 400 });
+    }
+    await printBridgeCommandResult('user.me', {}, options);
 });
 cli
     .command('mcp', 'Expose a running Tapicker Bridge to an MCP client over stdio')
     .option('--url <url>', 'Bridge HTTP(S) URL', {
-    default: process.env.TAPICKER_BRIDGE_URL || `http://${DEFAULT_HOST}:${DEFAULT_PORT}`,
+    default: defaultBridgeUrl,
 })
     .option('--token <token>', 'Bridge Bearer token; prefer TAPICKER_BRIDGE_TOKEN for MCP host configuration')
     .example('tapicker mcp')
     .example('tapicker mcp --url https://bridge.example.com --token <token>')
     .action((options) => {
-    const token = options.token || process.env.TAPICKER_BRIDGE_TOKEN;
+    const token = options.token ?? process.env.TAPICKER_BRIDGE_TOKEN;
     const api = createHttpMcpApi(options.url, token);
     serveStdio(() => createTapickerMcpServer(api), {
         onerror: (error) => console.error('Tapicker MCP stdio error:', error),
@@ -114,6 +195,9 @@ cli
 });
 cli.help((sections) => formatCliHelp(sections));
 cli.version(VERSION);
+// 统一在命令输出前处理更新提示，包括 CAC 默认会在 parse 中直接输出的帮助和版本。
+cli.showHelpOnExit = false;
+cli.showVersionOnExit = false;
 const bridgeActions = {
     start: {
         summary: 'Start the Bridge server in the foreground or as a daemon.',
@@ -137,82 +221,177 @@ const bridgeActions = {
     },
 };
 const workflowActions = {
+    guide: {
+        summary: 'Read Workflow authoring documentation by topic.',
+        description: 'Read overview by default. Follow references.topic with another guide call; reuse the returned clientId.',
+        example: 'tapicker workflow guide [topic] [--client-id <uuid>]',
+    },
+    schema: {
+        summary: 'Get a self-contained Workflow document JSON Schema.',
+        description: 'Get the schema for the node types you plan to use, as comma-separated names. Omit --node-types for all business nodes.',
+        example: 'tapicker workflow schema [--node-types NodeLoop,NodeExtractData]',
+    },
+    validate: {
+        summary: 'Validate a Workflow document.',
+        description: 'Read a tapicker/nodes or tapicker/workflow document from --json, a file or stdin (-). Inspect isValid and normalized nodes or issues; does not save or run.',
+        example: 'tapicker workflow validate <file|-|--json JSON>',
+    },
+    list: {
+        summary: 'List your Workflow summaries with pagination.',
+        description: 'List own Workflows by default, or select shared/pinned. Filter by name or exact host. Does not return nodes.',
+        example: 'tapicker workflow list --name example --scope own',
+    },
+    get: {
+        summary: 'Read current Workflow nodes and metadata.',
+        description: 'Read the latest Workflow metadata and startup arguments using an ID from workflow list. Nodes are returned with view, edit or manage permission.',
+        example: 'tapicker workflow get <workflowId>',
+    },
+    create: {
+        summary: 'Validate and create a private Workflow from JSON.',
+        description: 'Read {name, intro?, href?, nodes} from --json, a file or stdin (-). Does not run. Check the list before retrying after timeout or connection failure.',
+        example: 'tapicker workflow create <file|-|--json JSON>',
+    },
+    update: {
+        summary: 'Update a Workflow using its last-read revision.',
+        description: 'Read {workflowId, revision, name?, intro?, href?, nodes?} from --json, a file or stdin (-). Provide at least one change. On WorkflowConflict, read the latest Workflow and reconcile changes before submitting again.',
+        example: 'tapicker workflow update <file|-|--json JSON>',
+    },
     start: {
         summary: 'Start one Workflow instance; optionally stream its status with --watch.',
-        description: 'Start the specified Workflow and return its workflowId, full workflowName, and selected clientId. A Workflow supports one active instance at a time. By default this returns after the start response; add --watch to stream status until it completes, stops, or fails.',
-        example: `tapicker workflow start <workflowId> [--args '{"name":"Tom"}'] [--tab active|new|id:<tabId>] [--watch]`,
+        description: 'Start a saved Workflow from the browser’s active tab and return an accepted receipt with workflowId, workflowName, and clientId. A Workflow supports one active instance at a time. By default this returns after the start response; add --watch to stream status until it completes, stops, or fails.',
+        example: `tapicker workflow start <workflowId> [--args '{"name":"Tom"}'] [--watch]`,
     },
     pause: {
         summary: 'Pause the active instance of a Workflow.',
-        description: 'Pause the active instance of the specified Workflow.',
+        description: 'Pause the active instance at its next pause point. An already paused instance stays paused.',
         example: 'tapicker workflow pause <workflowId>',
     },
     resume: {
         summary: 'Resume a paused Workflow instance.',
-        description: 'Resume a paused instance of the specified Workflow.',
+        description: 'Resume the same paused instance. An already running instance continues.',
         example: 'tapicker workflow resume <workflowId>',
     },
     stop: {
-        summary: 'Stop the active instance of a Workflow.',
-        description: 'Stop the active instance of the specified Workflow.',
+        summary: 'Request a stop for the active Workflow instance.',
+        description: 'Request a stop for the active instance, including a paused instance. Use workflow status to confirm it has stopped.',
         example: 'tapicker workflow stop <workflowId>',
     },
     status: {
-        summary: 'Fetch one current Workflow status snapshot.',
-        description: 'Fetch a single current-state snapshot. Use watch to receive ongoing updates without polling.',
-        example: 'tapicker workflow status <workflowId>',
+        summary: 'Query Workflow status; optionally wait for updates with --watch.',
+        description: 'Read the latest recorded status, or add --watch to wait until stopped, timeout, or cancellation. Does not start the Workflow. An already stopped snapshot returns immediately.',
+        example: 'tapicker workflow status <workflowId> [--watch] [--timeout <milliseconds>]',
+    },
+    logs: {
+        summary: 'Query latest-run log previews with optional level filters and pagination.',
+        description: 'Without a cursor, return the newest matching page in ascending ID order. Use before for older logs, after for new logs, and log for full details. run-at optionally checks the run identity.',
+        example: 'tapicker workflow logs <workflowId> [--levels warn,error] [--limit 100] [--before <id> | --after <id>]',
     },
-    watch: {
-        summary: 'Stream Workflow status until it completes, stops, or fails.',
-        description: 'Listen for status updates until the Workflow reaches completed, stopped, or failed. Timeout or Ctrl+C ends only the watch; it does not stop the Workflow.',
-        example: 'tapicker workflow watch <workflowId> [--timeout <milliseconds>]',
+    log: {
+        summary: 'Read one latest-run log with full details.',
+        description: 'Return one log by workflowId and logId without preview truncation. run-at optionally checks the run identity.',
+        example: 'tapicker workflow log <workflowId> <logId> [--run-at <timestamp>]',
     },
 };
 const dataActions = {
+    list: {
+        summary: 'List saved data tables.',
+        description: 'Filter by table name or owning Workflow ID. Returns table metadata without using export quota.',
+        example: 'tapicker data list --table-name products --page 1',
+    },
+    preview: {
+        summary: 'Preview up to 10 rows without using export quota.',
+        description: 'Inspect the oldest or latest inserted rows. A size-limited response can contain fewer rows.',
+        example: 'tapicker data preview <tableId> --sample latest',
+    },
     get: {
-        summary: 'Get all rows from an extracted data table; consumes export quota.',
-        description: 'Retrieve the complete data table identified by tableId. The row count is charged against the connected Extension account export quota.',
+        summary: 'Read a page or all rows from an extracted data table.',
+        description: 'Read page 1 with 50 rows by default, or use --all to read the full table. Returned rows consume export quota. If the response is lost, quota may already have been deducted.',
         example: 'tapicker data get <tableId>',
     },
+    export: {
+        summary: 'Export a saved data table to a local file.',
+        description: 'Export the entire table. Returned rows count against export quota. Use --output to choose a new file or an existing directory.',
+        example: 'tapicker data export <tableId> --format xlsx --output ./products.xlsx',
+    },
     delete: {
-        summary: 'Delete an extracted data table.',
-        description: 'Delete the data table identified by tableId and remove it from Tapicker Data.',
+        summary: 'Delete a saved table and all its rows.',
+        description: 'Delete the saved table and all its rows. Use the ID from Copy ID in Tapicker Data.',
         example: 'tapicker data delete <tableId>',
     },
 };
 const workflowCommonOptions = [
-    ['--host <host>', `Bridge host (default: ${DEFAULT_HOST})`],
-    ['--port <port>', `Bridge port (default: ${DEFAULT_PORT})`],
-    ['--token <token>', 'Bridge Bearer token'],
-    ['--client-id <clientId>', 'Select an Extension; required when multiple are ready'],
-    ['--https', 'Use HTTPS/WSS instead of HTTP/WS'],
-];
-const dataCommonOptions = [
-    ['--host <host>', `Bridge host (default: ${DEFAULT_HOST})`],
-    ['--port <port>', `Bridge port (default: ${DEFAULT_PORT})`],
-    ['--token <token>', 'Bridge Bearer token'],
+    ['--url <url>', `Bridge HTTP(S) URL (TAPICKER_BRIDGE_URL or http://${DEFAULT_HOST}:${DEFAULT_PORT})`],
+    ['--token <token>', 'Bridge Bearer token (or TAPICKER_BRIDGE_TOKEN)'],
     ['--client-id <clientId>', 'Select an Extension; required when multiple are ready'],
-    ['--https', 'Use HTTPS instead of HTTP'],
 ];
+const dataCommonOptions = workflowCommonOptions;
+const dataActionOptions = {
+    list: [
+        ['--table-name <name>', 'Match a case-insensitive substring of table names'],
+        ['--workflow-id <workflowId>', 'Match the owning Workflow ID'],
+        ['--page <page>', 'Page number (default: 1)'],
+        ['--page-size <count>', 'Tables per page (default: 20, max: 100)'],
+    ],
+    preview: [['--sample <sample>', 'oldest or latest (default: oldest)']],
+    get: [
+        ['--all', 'Read the full table; omit pagination options'],
+        ['--page <page>', 'Page number (default: 1)'],
+        ['--page-size <count>', 'Rows per page (default: 50, max: 500)'],
+    ],
+    export: [
+        ['--format <format>', 'xlsx, xls, csv, json, xml, or txt (default: csv)'],
+        ['--output <path>', 'Destination file or existing directory (required)'],
+    ],
+    delete: [],
+};
+const workflowJsonOptions = [['--json <json>', 'Inline JSON input; use instead of a file or -']];
 const workflowActionOptions = {
+    guide: [],
+    schema: [['--node-types <types>', 'Comma-separated node types to use; omit for all business nodes']],
+    validate: workflowJsonOptions,
+    list: [
+        ['--scope <scope>', 'own (default), shared or pinned'],
+        ['--name <name>', 'Match a substring of full names'],
+        ['--host <host>', 'Match host exactly; omit for all sites'],
+        ['--page <page>', 'Page number (default: 1)'],
+        ['--page-size <count>', 'Page size, 1–100 (default: 20)'],
+    ],
+    get: [],
+    create: workflowJsonOptions,
+    update: workflowJsonOptions,
     start: [
         ['--args <json>', 'Workflow input object (default: {})'],
-        ['--tab <target>', 'Target tab: active (default), new, or id:<positive-tabId>'],
         ['--watch', 'Stream status updates after starting, until a terminal state'],
         ['--timeout <milliseconds>', 'Limit the --watch duration; does not stop the Workflow'],
     ],
     pause: [],
     resume: [],
     stop: [],
-    status: [],
-    watch: [['--timeout <milliseconds>', 'Limit how long to wait; does not stop the Workflow']],
+    status: [
+        ['--run-at <timestamp>', 'Require the saved runAt to match (single query only)'],
+        ['--include-data-summary', 'Include saved data changes (single query only)'],
+        ['--watch', 'Wait for status updates without starting the Workflow; return immediately if stopped'],
+        ['--timeout <milliseconds>', 'Limit the --watch duration; does not stop the Workflow'],
+    ],
+    logs: [
+        ['--levels <levels>', 'Comma-separated exact levels: trace,debug,info,warn,error'],
+        ['--limit <count>', 'Matching records per page, 1–500 (default: 100)'],
+        ['--before <id>', 'Read older matching logs before this ID (exclusive)'],
+        ['--after <id>', 'Read newer matching logs after this ID (exclusive)'],
+        ['--run-at <timestamp>', 'Require the saved runAt to match'],
+    ],
+    log: [['--run-at <timestamp>', 'Require the saved runAt to match']],
 };
 const workflowGeneralOptions = [
     ...workflowCommonOptions,
+    ...workflowActionOptions.schema,
+    ...workflowActionOptions.list,
+    ['--json <json>', 'Inline JSON input (validate, create or update only)'],
     ['--args <json>', 'Workflow input object (default: {}; start only)'],
-    ['--tab <target>', 'Target tab: active (default), new, or id:<positive-tabId> (start only)'],
-    ['--watch', 'Stream status after start until a terminal state (start only)'],
-    ['--timeout <milliseconds>', 'Limit watch duration (watch or start --watch); does not stop the Workflow'],
+    ['--watch', 'Wait for status updates until stopped (start or status only)'],
+    ['--timeout <milliseconds>', 'Limit --watch duration; does not stop the Workflow'],
+    ...workflowActionOptions.logs,
+    ['--include-data-summary', 'Include saved data changes (status without --watch only)'],
 ];
 const bridgeCommonOptions = [['--data-dir <path>', 'Bridge state directory (TAPICKER_DATA_DIR or ~/.tapicker)']];
 const bridgeActionOptions = {
@@ -229,8 +408,32 @@ const bridgeActionOptions = {
     code: [['--refresh', 'Rotate the pairing code and unlock pairing after rate limiting']],
     extensions: [],
 };
+/**
+ * 按动作限制参数，避免注册在同一 CLI 分组上的选项被静默忽略。
+ */
+function validateActionOptions(action, options, common, actions) {
+    if (!Object.hasOwn(actions, action)) {
+        throw new BridgeError('CommandNotFound', `Unsupported action: ${action}`, { status: 404 });
+    }
+    const allowed = new Set([...common, ...actions[action]].map(([flag]) => flag
+        .split(' ')[0]
+        .slice(2)
+        .replace(/-([a-z])/g, (_, letter) => letter.toUpperCase())));
+    for (const [key, value] of Object.entries(options)) {
+        if (key === '--' || value === undefined || allowed.has(key))
+            continue;
+        const flag = key.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+        throw new BridgeError('InvalidArguments', `--${flag} is not valid for ${action}`, { status: 400 });
+    }
+}
 function formatCliHelp(sections) {
     const command = cli.matchedCommandName;
+    if (command === 'user') {
+        const usage = sections.find((section) => section.title === 'Usage');
+        if (usage)
+            usage.body = '  $ tapicker user me [options]';
+        return sections;
+    }
     if (command === 'mcp') {
         const usage = sections.find((section) => section.title === 'Usage');
         if (usage)
@@ -247,21 +450,28 @@ function formatCliHelp(sections) {
     const action = cli.args[0];
     const actionMap = command === 'workflow' ? workflowActions : command === 'bridge' ? bridgeActions : dataActions;
     const actionInfo = actionMap[action];
-    const actionOptions = command === 'workflow' ? workflowActionOptions : command === 'bridge' ? bridgeActionOptions : {};
+    const actionOptions = command === 'workflow' ? workflowActionOptions : command === 'bridge' ? bridgeActionOptions : dataActionOptions;
     const commonOptions = command === 'workflow' ? workflowCommonOptions : command === 'bridge' ? bridgeCommonOptions : dataCommonOptions;
     const usage = sections.find((section) => section.title === 'Usage');
     if (usage) {
         if (actionInfo && command === 'workflow') {
-            usage.body = `  $ tapicker workflow ${action} <workflowId> [options]`;
+            const target = action === 'guide'
+                ? ' [topic]'
+                : action === 'schema' || action === 'list'
+                    ? ''
+                    : action === 'validate' || action === 'create' || action === 'update'
+                        ? ' <file|-|--json JSON>'
+                        : ' <workflowId>';
+            usage.body = `  $ tapicker workflow ${action}${target}${action === 'log' ? ' <logId>' : ''} [options]`;
         }
         else if (actionInfo && command === 'data') {
-            usage.body = `  $ tapicker data ${action} <tableId> [options]`;
+            usage.body = `  $ tapicker data ${action}${action === 'list' ? '' : ' <tableId>'} [options]`;
         }
         else if (actionInfo) {
             usage.body = `  $ tapicker bridge ${action} [options]`;
         }
         else {
-            const target = command === 'workflow' ? ' <workflowId>' : command === 'data' ? ' <tableId>' : '';
+            const target = command === 'workflow' ? ' [target]' : command === 'data' ? ' [tableId]' : '';
             usage.body = `  $ tapicker ${command} <action>${target} [options]`;
         }
     }
@@ -274,7 +484,15 @@ function formatCliHelp(sections) {
                     ...commonOptions,
                     ...Object.entries(actionOptions).flatMap(([name, entries]) => entries.map(([option, description]) => [option, `${description} (${name} only)`])),
                 ]
-                : commonOptions;
+                : [
+                    ...commonOptions,
+                    ...dataActionOptions.list.slice(0, 2),
+                    ...dataActionOptions.preview,
+                    dataActionOptions.get[0],
+                    ...dataActionOptions.export,
+                    ['--page <page>', 'Page number (list or get)'],
+                    ['--page-size <count>', 'Page size (list or get)'],
+                ];
     const optionsSection = sections.find((section) => section.title === 'Options');
     if (optionsSection)
         optionsSection.body = formatOptionRows(options);
@@ -339,8 +557,12 @@ async function startBridge(options) {
         }
         process.exit(0);
     };
-    process.once('SIGINT', () => void shutdown());
-    process.once('SIGTERM', () => void shutdown());
+    process.once('SIGINT', () => {
+        shutdown();
+    });
+    process.once('SIGTERM', () => {
+        shutdown();
+    });
     try {
         controlServer = await startBridgeControlServer(dataDir, async (action) => {
             if (action === 'code.get') {
@@ -353,7 +575,9 @@ async function startBridge(options) {
             if (action === 'extensions.list') {
                 return server.bridge.getExtensionStatuses();
             }
-            setTimeout(() => void shutdown(), 50);
+            setTimeout(() => {
+                shutdown();
+            }, 50);
             return { pid: process.pid, bridgeId: server.bridgeId };
         });
         if (isDaemonChild) {
@@ -397,7 +621,7 @@ async function startBridge(options) {
             bridgeId: server.bridgeId,
             httpUrl: address.httpUrl,
             wsUrl: address.wsUrl,
-            workflowWatchWsUrl: address.workflowWatchWsUrl,
+            workflowStatusWatchWsUrl: address.workflowStatusWatchWsUrl,
             dataDir,
             logPath: getBridgeDaemonLogPath(dataDir),
             pairingCode,
@@ -591,7 +815,7 @@ function isDaemonReadyMessage(value) {
         typeof message.bridgeId === 'string' &&
         typeof message.httpUrl === 'string' &&
         typeof message.wsUrl === 'string' &&
-        typeof message.workflowWatchWsUrl === 'string' &&
+        typeof message.workflowStatusWatchWsUrl === 'string' &&
         typeof message.dataDir === 'string' &&
         typeof message.logPath === 'string' &&
         typeof message.authenticationEnabled === 'boolean');
@@ -632,16 +856,16 @@ async function isManagedBridgeRunning(state) {
 async function startWorkflow(workflowId, options) {
     let args;
     try {
-        args = JSON.parse(options.args);
+        args = JSON.parse(options.args ?? '{}');
     }
     catch (error) {
         throw new BridgeError('InvalidArguments', '--args must be valid JSON', { status: 400, cause: error });
     }
-    const parsed = WorkflowStartInputSchema.safeParse({ workflowId, args, tab: parseTabTarget(options.tab) });
+    const parsed = WorkflowStartInputSchema.safeParse({ workflowId, args });
     if (!parsed.success) {
         throw new BridgeError('InvalidArguments', 'Invalid Workflow start arguments', {
             status: 400,
-            details: parsed.error.issues,
+            details: { issues: parsed.error.issues },
         });
     }
     if (!options.watch) {
@@ -649,51 +873,60 @@ async function startWorkflow(workflowId, options) {
         return;
     }
     const timeoutMs = parseWatchTimeout(options.timeout);
-    const connection = await openWorkflowWatch(workflowId, options);
+    const connection = await openWorkflowStatusWatch(parsed.data.workflowId, options);
     try {
-        const startResult = await requestBridgeCommand('workflow.start', parsed.data, {
+        const receipt = await requestBridgeCommand('workflow.start', parsed.data, {
             ...options,
             clientId: connection.clientId,
         });
-        console.log(JSON.stringify({ type: 'workflow.start', data: startResult }));
+        const startResult = WorkflowStartResultSchema.safeParse(receipt);
+        if (!startResult.success ||
+            startResult.data.workflowId !== parsed.data.workflowId ||
+            startResult.data.clientId !== connection.clientId) {
+            throw new BridgeError('InvalidBridgeResponse', 'Bridge returned an invalid Workflow start receipt', {
+                status: 502,
+            });
+        }
+        const { runAt } = startResult.data;
+        console.log(JSON.stringify({ type: 'workflow.start', data: startResult.data }));
         const result = await waitForWorkflowStatus({
             clientId: connection.clientId,
-            workflowId,
-            subscribe: (onStatus, onClose) => subscribeToWorkflowWatch(connection, onStatus, onClose),
-            readStatus: () => readWorkflowStatus(workflowId, connection.clientId, options),
+            workflowId: parsed.data.workflowId,
+            runAt,
+            subscribe: (onStatus, onClose) => subscribeToWorkflowStatusWatch(connection, onStatus, onClose),
+            readStatus: () => readWorkflowStatus(parsed.data.workflowId, connection.clientId, options, runAt),
             onStatus: printWorkflowStatus,
             timeoutMs,
         });
-        printWatchTimeout(result);
+        printWatchResult(result);
     }
     finally {
         connection.close();
     }
 }
-async function watchWorkflow(workflowId, options) {
+async function watchWorkflowStatus(workflowId, options) {
     const timeoutMs = parseWatchTimeout(options.timeout);
-    const connection = await openWorkflowWatch(workflowId, options);
+    const connection = await openWorkflowStatusWatch(workflowId, options);
     try {
         const result = await waitForWorkflowStatus({
             clientId: connection.clientId,
             workflowId,
-            subscribe: (onStatus, onClose) => subscribeToWorkflowWatch(connection, onStatus, onClose),
+            subscribe: (onStatus, onClose) => subscribeToWorkflowStatusWatch(connection, onStatus, onClose),
             readStatus: () => readWorkflowStatus(workflowId, connection.clientId, options),
             onStatus: printWorkflowStatus,
             timeoutMs,
         });
-        printWatchTimeout(result);
+        printWatchResult(result);
     }
     finally {
         connection.close();
     }
 }
-async function openWorkflowWatch(workflowId, options) {
-    const protocol = options.https ? 'https' : 'http';
-    const bridgeUrl = new URL(`${protocol}://${options.host}:${parsePort(options.port)}`);
-    return connectWorkflowWatch(workflowWatchWebSocketUrl(bridgeUrl), { clientId: options.clientId, workflowId }, options.token);
+async function openWorkflowStatusWatch(workflowId, options) {
+    const bridgeUrl = parseBridgeUrl(options.url);
+    return connectWorkflowStatusWatch(workflowStatusWatchWebSocketUrl(bridgeUrl), { clientId: options.clientId, workflowId }, options.token ?? process.env.TAPICKER_BRIDGE_TOKEN);
 }
-function subscribeToWorkflowWatch(connection, onStatus, onClose) {
+function subscribeToWorkflowStatusWatch(connection, onStatus, onClose) {
     const removeStatusListener = connection.onStatus(onStatus);
     const removeCloseListener = connection.onClose(onClose);
     return () => {
@@ -701,15 +934,15 @@ function subscribeToWorkflowWatch(connection, onStatus, onClose) {
         removeCloseListener();
     };
 }
-function printWatchTimeout(result) {
-    if (result.timedOut) {
-        console.log(JSON.stringify({ type: 'workflow.watch:res', data: { ok: true, data: result } }));
-    }
+function printWatchResult(result) {
+    console.log(JSON.stringify({ type: 'workflow.status.watch', data: result }));
 }
-async function readWorkflowStatus(workflowId, clientId, options) {
-    const result = await requestBridgeCommand('workflow.status', { workflowId }, { ...options, clientId });
-    const parsed = WorkflowStatusEventSchema.safeParse({ ...result, clientId });
-    if (!parsed.success || parsed.data.workflowId !== workflowId) {
+async function readWorkflowStatus(workflowId, clientId, options, runAt) {
+    const result = await requestBridgeCommand('workflow.status', { workflowId, runAt }, { ...options, clientId });
+    const parsed = WorkflowStatusEventSchema.strip().safeParse({ ...result, clientId });
+    if (!parsed.success ||
+        parsed.data.workflowId !== workflowId ||
+        (runAt !== undefined && parsed.data.runAt !== runAt)) {
         throw new BridgeError('InvalidBridgeResponse', 'Bridge returned an invalid Workflow status response', {
             status: 502,
             details: parsed.success ? undefined : parsed.error.issues,
@@ -718,7 +951,7 @@ async function readWorkflowStatus(workflowId, clientId, options) {
     return parsed.data;
 }
 function printWorkflowStatus(status) {
-    console.log(JSON.stringify({ type: 'workflow.status', data: status }));
+    console.log(JSON.stringify({ type: 'workflow.status.changed', data: status }));
 }
 function parseWatchTimeout(value) {
     if (value === undefined)
@@ -731,28 +964,129 @@ function parseWatchTimeout(value) {
     }
     return timeoutMs;
 }
-function parseTabTarget(value) {
-    if (value === undefined || value === 'active') {
-        return undefined;
+/**
+ * 编写命令复用既有 HTTP 协议，只在 CLI 层读取片段文件和转换参数。
+ */
+async function queryWorkflowAuthoring(action, target, extra, options) {
+    if (extra !== undefined || ((action === 'schema' || action === 'list') && target !== undefined)) {
+        throw new BridgeError('InvalidArguments', `Unexpected positional argument for workflow ${action}`, { status: 400 });
+    }
+    if ([options.levels, options.limit, options.before, options.after, options.runAt].some((value) => value !== undefined)) {
+        throw new BridgeError('InvalidArguments', 'Log query options are not valid for authoring commands', { status: 400 });
+    }
+    let input;
+    if (action === 'guide')
+        input = { topic: target };
+    else if (action === 'schema') {
+        if (options.nodeTypes !== undefined && typeof options.nodeTypes !== 'string') {
+            throw new BridgeError('InvalidArguments', 'Provide --node-types once with comma-separated node type names', {
+                status: 400,
+            });
+        }
+        input = { nodeTypes: options.nodeTypes?.split(',').map((type) => type.trim()) };
+    }
+    else if (action === 'list')
+        input = {
+            scope: options.scope,
+            name: options.name,
+            host: options.host,
+            page: options.page === undefined ? undefined : Number(options.page),
+            pageSize: options.pageSize === undefined ? undefined : Number(options.pageSize),
+        };
+    else if (action === 'get')
+        input = { workflowId: target };
+    else {
+        const inline = options.json;
+        if (inline !== undefined && (typeof inline !== 'string' || target !== undefined)) {
+            throw new BridgeError('InvalidArguments', 'Use --json once, without a file path or -', { status: 400 });
+        }
+        if (inline === undefined && !target) {
+            throw new BridgeError('InvalidArguments', 'Provide --json, a JSON file path, or - for stdin', { status: 400 });
+        }
+        try {
+            const value = JSON.parse(inline ?? readFileSync(target === '-' ? 0 : target, 'utf8'));
+            input = action === 'validate' ? { fragment: value } : value;
+        }
+        catch (cause) {
+            throw new BridgeError('InvalidArguments', inline === undefined ? 'Unable to read Workflow JSON' : '--json must be valid JSON', {
+                status: 400,
+                cause,
+            });
+        }
     }
-    if (value === 'new') {
-        return { mode: 'new' };
+    const schema = action === 'guide'
+        ? WorkflowGuideInputSchema
+        : action === 'schema'
+            ? WorkflowSchemaInputSchema
+            : action === 'validate'
+                ? WorkflowValidateInputSchema
+                : action === 'list'
+                    ? WorkflowListInputSchema
+                    : action === 'get'
+                        ? WorkflowGetInputSchema
+                        : action === 'create'
+                            ? WorkflowCreateInputSchema
+                            : WorkflowUpdateInputSchema;
+    const parsed = schema.safeParse(input);
+    if (!parsed.success) {
+        throw new BridgeError('InvalidArguments', `Invalid workflow.${action} arguments`, {
+            status: 400,
+            details: { issues: parsed.error.issues },
+        });
     }
-    const match = /^id:(\d+)$/.exec(value);
-    const tabId = match ? Number(match[1]) : Number.NaN;
-    if (!Number.isSafeInteger(tabId) || tabId <= 0) {
-        throw new BridgeError('InvalidArguments', '--tab must be "active", "new", or "id:<positive-tabId>"', {
+    await sendWorkflowCommand(`workflow.${action}`, parsed.data, options);
+}
+/**
+ * 将命令行参数转换为统一日志查询协议，发出请求前校验分页约束。
+ */
+async function queryWorkflowLogs(action, workflowId, logId, options) {
+    if (action === 'logs' && logId !== undefined)
+        throw new BridgeError('InvalidArguments', 'logId is only valid for workflow log', { status: 400 });
+    if (action === 'log' &&
+        [options.levels, options.limit, options.before, options.after].some((value) => value !== undefined)) {
+        throw new BridgeError('InvalidArguments', 'Log filters and pagination are only valid for workflow logs', {
             status: 400,
         });
     }
-    return { mode: 'id', tabId };
+    if (options.levels !== undefined && typeof options.levels !== 'string') {
+        throw new BridgeError('InvalidArguments', 'Provide --levels once with comma-separated levels, such as --levels warn,error', {
+            status: 400,
+        });
+    }
+    const input = action === 'log'
+        ? {
+            workflowId,
+            logId: Number(logId),
+            runAt: options.runAt,
+        }
+        : {
+            workflowId,
+            runAt: options.runAt,
+            levels: options.levels?.split(',').map((level) => level.trim()),
+            limit: options.limit === undefined ? undefined : Number(options.limit),
+            before: options.before === undefined ? undefined : Number(options.before),
+            after: options.after === undefined ? undefined : Number(options.after),
+        };
+    const parsed = (action === 'log' ? WorkflowLogInputSchema : WorkflowLogsInputSchema).safeParse(input);
+    if (!parsed.success)
+        throw new BridgeError('InvalidArguments', `Invalid workflow.${action} arguments`, {
+            status: 400,
+            details: { issues: parsed.error.issues },
+        });
+    await sendWorkflowCommand(`workflow.${action}`, parsed.data, options);
 }
 async function controlWorkflow(action, workflowId, options) {
-    const parsed = WorkflowControlInputSchema.safeParse({ workflowId });
+    const parsed = action === 'status'
+        ? WorkflowStatusInputSchema.safeParse({
+            workflowId,
+            runAt: options.runAt,
+            includeDataSummary: options.includeDataSummary,
+        })
+        : WorkflowControlInputSchema.safeParse({ workflowId });
     if (!parsed.success) {
         throw new BridgeError('InvalidArguments', `Invalid Workflow ${action} arguments`, {
             status: 400,
-            details: parsed.error.issues,
+            details: { issues: parsed.error.issues },
         });
     }
     await sendWorkflowCommand(`workflow.${action}`, parsed.data, options);
@@ -762,31 +1096,103 @@ async function sendWorkflowCommand(command, input, options) {
     console.log(JSON.stringify(result, null, 2));
     return result;
 }
-async function sendDataCommand(command, input, options) {
+/**
+ * 先验证目标路径，再发起导出；目录模式使用回执文件名并避开重名。
+ */
+async function exportDataTable(tableId, options) {
+    const input = DataExportInputSchema.safeParse({ tableId, format: options.format });
+    if (!input.success || typeof options.output !== 'string' || !options.output.trim()) {
+        throw new BridgeError('InvalidArguments', 'Provide a tableId, --output, and a supported --format', { status: 400 });
+    }
+    const output = resolve(options.output);
+    const directory = await stat(output)
+        .then((entry) => entry.isDirectory())
+        .catch((cause) => {
+        if (cause.code === 'ENOENT' && !options.output?.endsWith(sep) && !options.output?.endsWith('/'))
+            return false;
+        throw new BridgeError('ExportDestinationUnavailable', 'Cannot access the destination path', {
+            status: 400,
+            details: { output },
+            cause,
+        });
+    });
+    if (directory) {
+        await access(output, constants.W_OK).catch((cause) => {
+            throw new BridgeError('ExportDestinationUnavailable', 'Cannot write to the destination directory', {
+                status: 400,
+                details: { output },
+                cause,
+            });
+        });
+    }
+    let target = directory ? undefined : await openExportOutput(output);
+    let saved = false;
+    try {
+        const receipt = DataExportResultSchema.safeParse(await requestBridgeCommand('data.export', input.data, options));
+        if (!receipt.success)
+            throw new BridgeError('InvalidBridgeResponse', 'Bridge returned an invalid export receipt', { status: 502 });
+        const token = options.token ?? process.env.TAPICKER_BRIDGE_TOKEN;
+        try {
+            target ??= await openExportOutput(output, receipt.data.filename);
+            const response = await fetch(new URL(receipt.data.downloadPath, parseBridgeUrl(options.url)), {
+                headers: token ? { Authorization: `Bearer ${token}` } : undefined,
+                redirect: 'error',
+                signal: AbortSignal.timeout(120_000),
+            });
+            if (!response.ok || !response.body)
+                throw new Error(`HTTP ${response.status}`);
+            await pipeline(Readable.fromWeb(response.body), target.file.createWriteStream());
+        }
+        catch (cause) {
+            throw new BridgeError('ExportDownloadFailed', 'Failed to save the export. The file can be downloaded again before it expires.', {
+                status: 502,
+                details: { downloadPath: receipt.data.downloadPath, expiresAt: receipt.data.expiresAt },
+                cause,
+            });
+        }
+        saved = true;
+        console.log(JSON.stringify({
+            ...receipt.data,
+            output: target.path,
+        }, null, 2));
+    }
+    finally {
+        if (target) {
+            await target.file.close();
+            if (!saved)
+                await rm(target.path, { force: true });
+        }
+    }
+}
+/**
+ * 以独占方式创建文件，目录模式在同名时追加编号。
+ */
+async function openExportOutput(output, filename) {
+    if (filename !== undefined && (filename === '.' || filename === '..' || /[\\/:\x00-\x1F]/.test(filename))) {
+        throw new BridgeError('InvalidBridgeResponse', 'Bridge returned an invalid filename', { status: 502 });
+    }
+    const { name, ext } = parse(filename ?? '');
+    for (let suffix = 0;; suffix++) {
+        const path = filename === undefined ? output : join(output, suffix ? `${name} (${suffix})${ext}` : filename);
+        try {
+            return { path, file: await open(path, 'wx') };
+        }
+        catch (error) {
+            const cause = error;
+            if (cause.code === 'EEXIST' && filename !== undefined)
+                continue;
+            throw new BridgeError(cause.code === 'EEXIST' ? 'ExportDestinationExists' : 'ExportDestinationUnavailable', cause.code === 'EEXIST' ? 'The destination file already exists' : 'Cannot open the destination file', { status: 400, details: { output: path }, cause });
+        }
+    }
+}
+async function printBridgeCommandResult(command, input, options) {
     const result = await requestBridgeCommand(command, input, options);
     console.log(JSON.stringify(result, null, 2));
     return result;
 }
 async function requestBridgeCommand(command, input, options) {
-    const protocol = options.https ? 'https' : 'http';
-    const url = `${protocol}://${options.host}:${parsePort(options.port)}/v1/commands/${command}`;
-    const headers = { 'Content-Type': 'application/json' };
-    if (options.token) {
-        headers.Authorization = `Bearer ${options.token}`;
-    }
-    const response = await fetch(url, {
-        method: 'POST',
-        headers,
-        body: JSON.stringify({ clientId: options.clientId, input }),
-    });
-    const body = await readResponseBody(response);
-    if (!response.ok) {
-        throw new BridgeError(body.error?.code || 'BridgeRequestFailed', body.error?.message || response.statusText, {
-            status: response.status,
-            details: body.error?.details,
-        });
-    }
-    return body.data ?? body;
+    const api = createHttpBridgeApi(options.url, options.token ?? process.env.TAPICKER_BRIDGE_TOKEN);
+    return api.executeCommand(command, { clientId: options.clientId, input });
 }
 function resolveTls(options) {
     if (!options.tlsKey && !options.tlsCert) {
@@ -809,27 +1215,36 @@ function parsePort(value) {
 function isLoopback(host) {
     return host === '127.0.0.1' || host === 'localhost' || host === '::1';
 }
-async function readResponseBody(response) {
-    const text = await response.text();
-    if (!text) {
-        return {};
-    }
-    try {
-        return JSON.parse(text);
-    }
-    catch {
-        return { error: { message: text } };
-    }
-}
 async function main() {
     try {
         cli.parse(process.argv, { run: false });
+        const showHelp = Boolean(cli.options.help);
+        const showVersion = cli.options.version && (showHelp || cli.matchedCommandName === undefined);
+        const isMcpStdio = cli.matchedCommandName === 'mcp' && !showHelp;
+        if ((cli.matchedCommand || showHelp || showVersion) &&
+            !isMcpStdio &&
+            process.env[DAEMON_CHILD_ENV] !== '1' &&
+            process.env.TAPICKER_NO_UPDATE_NOTIFIER !== '1' &&
+            process.stdin.isTTY &&
+            process.stdout.isTTY &&
+            process.stderr.isTTY) {
+            await showCachedUpdate();
+        }
+        if (showHelp)
+            cli.outputHelp();
+        if (showVersion)
+            cli.outputVersion();
+        if (showHelp || showVersion)
+            return;
         await cli.runMatchedCommand();
     }
     catch (error) {
-        console.error(JSON.stringify({ ok: false, error: serializeBridgeError(error) }, null, 2));
+        const failure = error instanceof Error && error.name === 'CACError'
+            ? new BridgeError('InvalidArguments', error.message, { status: 400, cause: error })
+            : error;
+        console.error(JSON.stringify({ ok: false, error: serializeBridgeError(failure) }, null, 2));
         process.exitCode = 1;
     }
 }
-void main();
+main();
 //# sourceMappingURL=cli.js.map