feat(cli): CLI contract for the v2 surface, incl. execution

Adds `packages/sim-cli/src/contract` — the declarative definition of how the
terminal maps onto the API — and folds in the v2 execution endpoints that just
landed on improvement/v2-endpoints.

Read it as a diff against what is already derivable, not a listing. Method,
path, path params, field types, enum values, defaults and required-ness all come
from the generated operation table (which comes from the Zod contracts), and the
command name derives from `<resource> [sub-resource] <verb>`. 23 of 47
operations therefore need no entry at all.

The 24 that do carry only what a schema cannot express:
- names, where REST overloads one path — `DELETE /rows` vs `DELETE /rows/[rowId]`
  becomes `batch-delete` vs `delete`, and `DELETE /deploy` becomes `undeploy`
- flags, where a field's type misdescribes its meaning — `workflowIds` is
  `z.string()` that the route splits on commas; no generator can infer that
- columns, which are editorial
- confirm, for the 8 destructive operations

`executeWorkflow` / `getWorkflowExecution` / `cancelWorkflowExecution` derive
badly (`/execute` and `/cancel` are verbs the deriver reads as nouns), so all
three are named explicitly: `workflows run`, `workflows executions get|cancel`.

`stream` is marked `omit`: it switches the response to SSE, which the JSON
client would try to parse. Advertising a flag that breaks the response is worse
than not offering it — a `--follow` command that renders the stream is separate
and hand-written, like `files download`.

- Drops `check:openapi-drift`. The branch landed `check:openapi`, which does the
  same path/method reconciliation plus a recursive field diff and validates doc
  examples against the real Zod schemas — mine was a strict subset.
- Surfaces the new v2 rollout gate in the CLI: it answers 404 for callers
  outside the cohort, indistinguishable from a missing resource, so a 404 now
  carries that as a possibility rather than a diagnosis.
- `executor/utils/errors.ts` widens instead of casting through `unknown`, which
  is both more honest (the value is an Error) and keeps the double-cast ratchet
  at 8.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EsThUPqZXjwuuyRjBbmVkj

Author: 2 people

apps/sim/executor/utils/errors.ts

@@ -169,7 +169,10 @@ function readAttachedBlockContext(error: unknown): {
   blockType?: string
 } {
   if (!(error instanceof Error)) return {}
-  const attached = error as unknown as AttachedBlockContext
+  // Widen rather than erase: the value is an Error, it just may carry extra
+  // fields attached at throw time. Casting through `unknown` would discard
+  // that, and trips the double-cast ratchet for no benefit.
+  const attached = error as Error & Partial<AttachedBlockContext>
   return {
     blockId: typeof attached.blockId === 'string' ? attached.blockId : undefined,
     blockName: typeof attached.blockName === 'string' ? attached.blockName : undefined,

package.json

@@ -51,7 +51,6 @@
     "check:desktop-bridge": "bun run scripts/check-desktop-bridge-contract.ts --check",
     "check:desktop-ipc": "bun run scripts/check-desktop-ipc-contract.ts",
     "check:cli-api": "bun run scripts/generate-v2-cli-api.ts --check",
-    "check:openapi-drift": "bun run scripts/generate-v2-cli-api.ts --check-openapi",
     "generate:cli-api": "bun run scripts/generate-v2-cli-api.ts",
     "desktop-bridge-contract:update": "bun run scripts/check-desktop-bridge-contract.ts --update",
     "mship-contracts:generate": "bun run scripts/sync-mothership-stream-contract.ts",

packages/sim-cli/src/contract/commands.ts

@@ -0,0 +1,176 @@
+import type { CliContract } from './types.js'
+
+/**
+ * The CLI contract for the v2 surface.
+ *
+ * Read this as a diff against what is already derivable — an operation absent
+ * from this table still gets a command, built entirely from the generated
+ * operation table. Only the entries below needed a human.
+ *
+ * Derived by default:
+ *   listTables            → sim tables list
+ *   getKnowledgeDocument  → sim knowledge documents get <id> <documentId>
+ *   upsertTableRow        → sim tables upsert <tableId>
+ */
+export const CLI_CONTRACT: CliContract = {
+  // ─── Name collisions: REST overloads one path for single and bulk ─────────
+  // The derived name is identical for both, so the bulk form is renamed. AWS's
+  // `batch-` prefix rather than a `--all` flag: the plural is a different and
+  // more dangerous operation, and it should be a different word.
+  deleteTableRows: {
+    command: 'tables rows batch-delete',
+    describe: 'Delete rows matching a filter, or an explicit list of ids',
+    flags: { rowIds: { name: 'row', list: true }, filter: { json: true } },
+    confirm: 'This deletes every matching row and cannot be undone.',
+  },
+  updateRowsByFilter: {
+    command: 'tables rows batch-update',
+    describe: 'Update every row matching a filter',
+    flags: { filter: { json: true }, data: { json: true } },
+    confirm: 'This updates every matching row and cannot be undone.',
+  },
+  // `DELETE /workflows/[id]/deploy` is an undeploy, not a delete.
+  undeployWorkflow: {
+    command: 'workflows undeploy',
+    describe: 'Take a workflow out of deployment',
+  },
+
+  // ─── Destructive single-resource operations ───────────────────────────────
+  deleteTable: { confirm: 'This deletes the table and all of its rows.' },
+  deleteTableRow: { confirm: 'This deletes the row.' },
+  deleteTableColumn: { confirm: 'This deletes the column and its values in every row.' },
+  deleteKnowledgeBase: { confirm: 'This deletes the knowledge base and every document in it.' },
+  deleteKnowledgeDocument: { confirm: 'This deletes the document and its embeddings.' },
+  deleteFile: { confirm: 'This archives the file.' },
+
+  // ─── Fields whose type misdescribes their meaning ─────────────────────────
+  // `z.string()` that the route splits on commas. No generator can infer this.
+  listLogs: {
+    flags: {
+      workflowIds: { name: 'workflow', list: true },
+      folderIds: { name: 'folder', list: true },
+      triggers: { name: 'trigger', list: true },
+    },
+    columns: [
+      { header: 'started', path: 'startedAt', format: 'timestamp' },
+      { header: 'level' },
+      { header: 'trigger' },
+      { header: 'workflow', path: 'workflow.name' },
+      { header: 'duration', path: 'totalDurationMs', format: 'duration' },
+      { header: 'cost', path: 'cost.total', format: 'cost' },
+      { header: 'execution', path: 'executionId' },
+    ],
+  },
+  searchKnowledge: {
+    // Accepts a string or an array on the wire; the CLI always sends the array.
+    flags: { knowledgeBaseIds: { name: 'kb', list: true }, tagFilters: { json: true } },
+    columns: [
+      { header: 'score', path: 'similarity' },
+      { header: 'document', path: 'documentName' },
+      { header: 'chunk', path: 'chunkIndex' },
+      { header: 'content' },
+    ],
+  },
+
+  // ─── Friendlier flag names ────────────────────────────────────────────────
+  upsertTableRow: {
+    describe: 'Insert a row, or update the one that conflicts on a unique column',
+    flags: {
+      data: { json: true },
+      conflictTarget: { name: 'on', describe: 'Unique column to resolve the conflict against' },
+    },
+    columns: [{ header: 'id' }, { header: 'operation' }],
+  },
+  queryRows: {
+    command: 'tables rows query',
+    flags: { predicate: { name: 'filter', json: true }, sort: { json: true } },
+  },
+
+  // ─── Output columns for list commands ─────────────────────────────────────
+  listTables: {
+    columns: [
+      { header: 'id' },
+      { header: 'name' },
+      { header: 'rows', path: 'rowCount' },
+      { header: 'updated', path: 'updatedAt', format: 'timestamp' },
+    ],
+  },
+  listWorkflows: {
+    columns: [
+      { header: 'id' },
+      { header: 'name' },
+      { header: 'deployed', path: 'isDeployed', format: 'bool' },
+      { header: 'runs', path: 'runCount' },
+      { header: 'last run', path: 'lastRunAt', format: 'timestamp' },
+    ],
+  },
+  listFiles: {
+    columns: [
+      { header: 'id' },
+      { header: 'name' },
+      { header: 'size', format: 'bytes' },
+      { header: 'type' },
+      { header: 'uploaded', path: 'uploadedAt', format: 'timestamp' },
+    ],
+  },
+  listKnowledgeBases: {
+    columns: [
+      { header: 'id' },
+      { header: 'name' },
+      { header: 'docs', path: 'docCount' },
+      { header: 'tokens', path: 'tokenCount' },
+      { header: 'model', path: 'embeddingModel' },
+    ],
+  },
+  listKnowledgeDocuments: {
+    columns: [
+      { header: 'id' },
+      { header: 'filename' },
+      { header: 'size', path: 'fileSize', format: 'bytes' },
+      { header: 'status', path: 'processingStatus' },
+      { header: 'chunks', path: 'chunkCount' },
+    ],
+  },
+  listAuditLogs: {
+    columns: [
+      { header: 'at', path: 'createdAt', format: 'timestamp' },
+      { header: 'actor', path: 'actorEmail' },
+      { header: 'action' },
+      { header: 'resource', path: 'resourceName' },
+    ],
+  },
+
+  // ─── Execution ────────────────────────────────────────────────────────────
+  // The derived names land badly here: `/execute` and `/cancel` are verbs in
+  // the path, but neither is in the action list, so POST would derive
+  // `workflows execute create` and `workflows cancel create`.
+  executeWorkflow: {
+    command: 'workflows run',
+    describe: 'Run a deployed workflow and wait for the result',
+    flags: {
+      input: { json: true, describe: 'Trigger input as JSON' },
+      selectedOutputs: { name: 'output', list: true },
+      // SSE, not JSON — the generic client cannot consume it. A `sim workflows
+      // run --follow` that renders the stream is a separate, hand-written
+      // command; advertising a flag that breaks the response is worse than
+      // not offering it yet.
+      stream: { omit: true },
+    },
+  },
+  getWorkflowExecution: {
+    command: 'workflows executions get',
+    describe: 'Show the status of one execution',
+  },
+  cancelWorkflowExecution: {
+    command: 'workflows executions cancel',
+    describe: 'Cancel a running execution',
+    // Not `confirm`-gated: cancelling is recoverable (re-run it), and the
+    // whole point is to stop something that is already going wrong.
+  },
+
+  // ─── Not a terminal-shaped operation ──────────────────────────────────────
+  // Multipart upload; `sim files upload <path>` needs its own file-reading
+  // command rather than a generated flag surface.
+  uploadFile: { hidden: true },
+  uploadKnowledgeDocument: { hidden: true },
+}

packages/sim-cli/src/contract/types.ts

@@ -0,0 +1,85 @@
+import type { V2OperationName } from '../generated/v2-api.js'
+
+/**
+ * The CLI contract: how the terminal surface maps onto the v2 API.
+ *
+ * Most of a command is derivable and is NOT stated here. Method, path, path
+ * params, field types, enum values, defaults, and required-ness all come from
+ * the generated operation table, which comes from the Zod route contracts. The
+ * command name itself derives from `<resource> <sub-resource> <verb>` for 41 of
+ * the 44 operations.
+ *
+ * This file carries only what a schema cannot say:
+ *
+ * - `command` — when the derived name collides or reads badly. REST overloads
+ *   one path for single and bulk (`DELETE /rows` vs `DELETE /rows/[rowId]`), so
+ *   those need a human to pick `delete` vs `batch-delete`.
+ * - `flags` — when a field's *type* misdescribes its *meaning*. `workflowIds`
+ *   is `z.string()` that the route splits on commas; nothing in the schema says
+ *   "list". Also friendlier aliases (`conflictTarget` → `--on`).
+ * - `columns` — which of a response's fields belong in a table. Editorial.
+ * - `confirm` — which operations are destructive enough to demand `--yes`.
+ *
+ * An operation with nothing unusual needs no entry at all.
+ */
+
+/** How one request field is exposed as a flag. */
+export interface FlagSpec {
+  /** Flag name, kebab-case, without `--`. Defaults to the kebab-cased field name. */
+  name?: string
+  /** Short alias, e.g. `w` for `--workspace`. */
+  short?: string
+  /**
+   * Accept a repeated flag and send it comma-joined. For fields the schema
+   * types as `string` but the route splits — invisible to any type-driven
+   * generator, so it has to be stated.
+   */
+  list?: boolean
+  /** Take a JSON string. Implied for object/array/unknown fields. */
+  json?: boolean
+  /** Overrides the help text otherwise taken from the OpenAPI description. */
+  describe?: string
+  /**
+   * Never expose this field as a flag, and never send it.
+   *
+   * For request fields the terminal cannot honor — `stream: true` switches the
+   * response to SSE, which the JSON client would try to `JSON.parse`. Offering
+   * the flag would advertise a mode that breaks; a bespoke streaming command
+   * owns that instead.
+   */
+  omit?: boolean
+}
+
+/** A column in table-mode output. */
+export interface ColumnSpec {
+  /** Header, and the default path into the row when `value` is omitted. */
+  header: string
+  /** Dot path into the row. Defaults to `header`. */
+  path?: string
+  /** Rendering hint; `auto` inspects the value. */
+  format?: 'auto' | 'timestamp' | 'bytes' | 'duration' | 'bool' | 'cost'
+}
+
+export interface CommandSpec {
+  /**
+   * Command path, space-separated. Omit to accept the derived
+   * `<resource> [sub-resource] <verb>` name.
+   */
+  command?: string
+  /** One-line help. Falls back to the OpenAPI summary for the operation. */
+  describe?: string
+  /** Per-field flag overrides, keyed by the contract's field name. */
+  flags?: Record<string, FlagSpec>
+  /** Columns for table output. Omit on non-list commands to print a record. */
+  columns?: ColumnSpec[]
+  /**
+   * Require `--yes`. The message should say what is about to be destroyed —
+   * the point is that the caller can tell whether they meant it.
+   */
+  confirm?: string
+  /** Keep the operation out of the CLI surface entirely. */
+  hidden?: boolean
+}
+
+/** The contract: operation name → how it appears in the terminal. */
+export type CliContract = Partial<Record<V2OperationName, CommandSpec>>