fix(cli): seven defects found by live-testing the CLI against staging (#7176)

* fix(catalog): resolve an unversioned tool id against the visible set

`tools get github_comment` answered NOT_FOUND while `github_comment_v2` worked,
though the toolId help promises an unversioned name resolves to the newest
version. A superseded tool stays in the registry, so `resolveToolId`
short-circuits on the exact hit and returns it unchanged; the visibility gate
then refuses it because no visible block exposes a v1 tool. 204 base names were
unresolvable this way.

Resolution now walks the visible set newest-first, the way blocks already do.
`resolveToolId` is untouched — execution depends on an exact id returning that
exact id, and none of the 5182 visible ids change under the new path.

* fix(files): resolve an archived folder path through its active ancestors

The archived folder listing built its path map from the archived rows alone, so
a folder whose parent is still active came back as its own name. Deleting
`a/sub` and restoring `a/sub` therefore disagreed — restore only matched the
truncated `sub` — and the path and parentPath fields were wrong.

The extra read is taken only for the archived scope; active and all keep their
single query, which a test now pins.

Restoring by path also stopped guessing. Archiving, recreating and archiving
again leaves two archived folders with the same canonical path, and the resolver
took the first match, silently restoring the wrong one. It now refuses and names
the folder-id form.

* fix(v2): answer a folder-list miss with an empty page

A parentPath naming no folder returned 404 on the workflow, table and knowledge
folder lists, and an empty page on files. The rule the codebase already
publishes is the empty page: V2_FOLDER_FILTER_MISS is appended to the folderPath
filter on six list surfaces, and resolveFolderPathFilter documents why a list
must not become an existence oracle — a 404 claims the collection is missing and
breaks a walk when a folder is deleted mid-pagination.

Both TSDocs asserted the sibling folder lists already behaved that way. They did
not; that premise is corrected here too.

Mutations keep every 404. The miss short-circuits before the row query, because
an unfiltered parent id lists the whole workspace.

* fix(cli): gate activating a deployed version

`workflows activate create` switched which version production serves with no
confirmation, while `rollback` refused without --yes. They are the same
application operation under two transitions, so gating one and not the other was
an accident of naming.

The destructive-operation classification in the client tests listed activate as
non-destructive, which is what kept its sweep from noticing. Moved, so two
independent tests now hold the gate.

* fix(cli): name the profile in the suggestion configure prints

Refusing a root global printed a command to save it — without --profile, so
following it verbatim wrote the default profile and left the named one
untouched. The neighbouring suggestions in this file already carry the flag.

Resolution matches resolveProfile, so SIM_PROFILE is covered too, and the
profile name is redacted like the value beside it.

* fix(cli): fail a row delete that matched nothing

`tables rows batch-delete` exited 0 when none of the named rows existed, while
the table equivalent exited 1 on the same shape. Only the id-list selection is
checked: a filter answers without a requested count, so the guard self-excludes
and an idempotent sweep still exits 0 on its second run.

* fix(cli): show the -- escape for an id that opens with a dash

Short ids draw from a 64-character alphabet containing one dash, so 1 in 64 open
with one and commander reads it as an unknown option. It reaches `audit-logs
get` and the custom-tool commands, and the escape was documented nowhere.

The hint is appended only for a lone dash followed by two or more characters
carrying an uppercase letter or digit — a shape no flag on this surface has — so
a misspelt flag keeps commander's own suggestion.

* chore: regenerate the API reference and CLI surface

* fix(cli): quote a profile name a pasted command would otherwise split

The suggestion configure prints is meant to be pasted, and it interpolated the
profile name bare. Profile-name validation is creation-only by design — the
validator says so, because a hand-written `[profile my stack]` has to keep
resolving — so a name carrying whitespace, or a `;` that would end the pasted
command and start another, reaches this message unchecked.

Names that already satisfy the creation rule stay bare; the rest are single
quoted, embedded quotes included. Redaction runs first, so a control character
becomes a space and is then quoted rather than splitting the command.

Author: waleedlatif1

apps/docs/content/docs/en/cli/reference.mdx

@@ -4615,7 +4615,7 @@ Also spelled `sim workflow`.
 Activate Workflow Version (personal API key required)
 
 ```bash
-sim workflows activate create <workflowId> <version>
+sim workflows activate create <workflowId> <version> [options]
 ```
 
 **Arguments**
@@ -4629,6 +4629,16 @@ sim workflows activate create <workflowId> <version>
 
 </CommandTable>
 
+**Options**
+
+<CommandTable>
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `-y, --yes` | Yes | Confirm this operation. |
+
+</CommandTable>
+
 ### sim workflows operations apply
 
 Apply Workflow Operations (personal API key required)

apps/docs/content/docs/en/cli/workflows.mdx

@@ -12,7 +12,7 @@ Every command below also accepts the [global options](/cli/commands#global-optio
 ## Activate workflow version
 
 ```bash
-sim workflows activate create <workflowId> <version>
+sim workflows activate create <workflowId> <version> [options]
 ```
 
 Activate Workflow Version (personal API key required)
@@ -28,6 +28,16 @@ Activate Workflow Version (personal API key required)
 
 </CommandTable>
 
+**Options**
+
+<CommandTable>
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `-y, --yes` | Yes | Confirm this operation. |
+
+</CommandTable>
+
 ## Apply workflow operations
 
 ```bash

apps/docs/openapi-v2-files-audit.json

@@ -2098,9 +2098,9 @@
             "name": "parentPath",
             "in": "query",
             "required": false,
-            "description": "Restrict results to direct children of this parent path.",
+            "description": "Restrict results to direct children of this parent path. A path that names no folder narrows the result to nothing, so the response is an empty page rather than an error.",
             "schema": {
-              "description": "Restrict results to direct children of this parent path.",
+              "description": "Restrict results to direct children of this parent path. A path that names no folder narrows the result to nothing, so the response is an empty page rather than an error.",
               "$ref": "#/components/schemas/FolderPathInput"
             }
           },

apps/docs/openapi-v2-knowledge.json

@@ -2718,9 +2718,9 @@
             "name": "parentPath",
             "in": "query",
             "required": false,
-            "description": "Restrict results to direct children of this parent path.",
+            "description": "Restrict results to direct children of this parent path. A path that names no folder narrows the result to nothing, so the response is an empty page rather than an error.",
             "schema": {
-              "description": "Restrict results to direct children of this parent path.",
+              "description": "Restrict results to direct children of this parent path. A path that names no folder narrows the result to nothing, so the response is an empty page rather than an error.",
               "$ref": "#/components/schemas/FolderPathInput"
             }
           },

apps/docs/openapi-v2-tables.json

@@ -3726,9 +3726,9 @@
             "name": "parentPath",
             "in": "query",
             "required": false,
-            "description": "Restrict results to direct children of this parent path.",
+            "description": "Restrict results to direct children of this parent path. A path that names no folder narrows the result to nothing, so the response is an empty page rather than an error.",
             "schema": {
-              "description": "Restrict results to direct children of this parent path.",
+              "description": "Restrict results to direct children of this parent path. A path that names no folder narrows the result to nothing, so the response is an empty page rather than an error.",
               "$ref": "#/components/schemas/FolderPathInput"
             }
           },

apps/docs/openapi-v2-workflows.json

@@ -3206,9 +3206,9 @@
             "name": "parentPath",
             "in": "query",
             "required": false,
-            "description": "Restrict results to direct children of this parent path.",
+            "description": "Restrict results to direct children of this parent path. A path that names no folder narrows the result to nothing, so the response is an empty page rather than an error.",
             "schema": {
-              "description": "Restrict results to direct children of this parent path.",
+              "description": "Restrict results to direct children of this parent path. A path that names no folder narrows the result to nothing, so the response is an empty page rather than an error.",
               "$ref": "#/components/schemas/FolderPathInput"
             }
           },

apps/sim/lib/api/contracts/v2/shared.ts

@@ -471,10 +471,10 @@ export const v2SearchSchema = z
  * to nothing, exactly as `workflowIds` naming no workflow does. These lists used
  * to answer `404 Folder not found` instead, which reported a missing collection
  * for a collection that exists, broke a pagination walk when a folder was
- * deleted mid-walk, and made a list a folder-existence oracle. The sibling
- * folder lists already answered a non-matching `parentPath` with an empty page.
- * Mutations keep their 404 — creating into or moving to a folder that does not
- * exist has no empty-set reading.
+ * deleted mid-walk, and made a list a folder-existence oracle. The folder lists
+ * answer a non-matching `parentPath` the same way, so one rule covers every
+ * folder filter in the family. Mutations keep their 404 — creating into or
+ * moving to a folder that does not exist has no empty-set reading.
  */
 export const V2_FOLDER_FILTER_MISS =
   'A path that names no folder narrows the result to nothing, so the response is an empty page rather than an error.'
@@ -593,7 +593,9 @@ export const v2ListFoldersQuerySchema = z
     workspaceId: workspaceIdSchema.describe('Workspace whose folders should be listed.'),
     parentPath: v2FolderPathInputSchema
       .optional()
-      .describe('Restrict results to direct children of this parent path.'),
+      .describe(
+        `Restrict results to direct children of this parent path. ${V2_FOLDER_FILTER_MISS}`
+      ),
     search: v2SearchSchema.describe('Case-insensitive substring match against the folder name.'),
     ...v2SortFields(v2FolderSortFields, { sortBy: 'name', sortOrder: 'asc' }),
   })

apps/sim/lib/catalog/application/catalog-reads.test.ts

@@ -107,6 +107,22 @@ const TOOL_METADATA: Record<string, Record<string, unknown>> = {
     params: {},
     hostedApiKey: 'always',
   },
+  confluence_read: {
+    id: 'confluence_read',
+    name: 'Confluence Read',
+    description: 'Read a Confluence page.',
+    version: '1.0.0',
+    params: {},
+    hostedApiKey: 'none',
+  },
+  confluence_read_v2: {
+    id: 'confluence_read_v2',
+    name: 'Confluence Read',
+    description: 'Read a Confluence page.',
+    version: '2.0.0',
+    params: {},
+    hostedApiKey: 'none',
+  },
 }
 
 const WORKSPACE_ID = 'workspace-1'
@@ -186,6 +202,7 @@ const confluenceV2 = block({
   type: 'confluence_v2',
   name: 'Confluence',
   description: 'Read Confluence pages.',
+  tools: { access: ['confluence_read_v2'] },
 })
 
 interface Visibility {
@@ -566,6 +583,34 @@ describe('catalog block and tool reads', () => {
     expect(listed.entries.map((entry) => entry.hostedApiKey)).toEqual(['none', 'none'])
   })
 
+  /**
+   * A superseded v1 tool stays registered so execution of a stored id keeps
+   * working, so `resolveToolId('confluence_read')` answers with the v1 id no
+   * visible block exposes — and `GET /v2/tools/confluence_read` 404'd while the
+   * list published `confluence_read_v2`.
+   */
+  it('resolves an unversioned tool name to its newest visible version and echoes the resolved id', async () => {
+    mocks.getAllBlocks.mockReturnValue([confluenceV2])
+
+    const { tool } = await getCatalogTool.execute({
+      principal: session,
+      input: { workspaceId: WORKSPACE_ID, toolId: 'confluence_read' },
+    })
+
+    expect(tool.id).toBe('confluence_read_v2')
+  })
+
+  it('echoes an exact versioned tool id unchanged', async () => {
+    mocks.getAllBlocks.mockReturnValue([confluenceV2])
+
+    const { tool } = await getCatalogTool.execute({
+      principal: session,
+      input: { workspaceId: WORKSPACE_ID, toolId: 'confluence_read_v2' },
+    })
+
+    expect(tool.id).toBe('confluence_read_v2')
+  })
+
   it('reads one tool with its params and outputs', async () => {
     const { tool } = await getCatalogTool.execute({
       principal: session,

apps/sim/lib/catalog/application/get-tool.ts

@@ -3,12 +3,11 @@ import {
   resolveCatalogGate,
 } from '@/lib/catalog/application/catalog-context'
 import { catalogOperations } from '@/lib/catalog/application/operations'
-import { resolveVisibleToolIds } from '@/lib/catalog/application/tool-scope'
+import { resolveVisibleToolId, resolveVisibleToolIds } from '@/lib/catalog/application/tool-scope'
 import { type CatalogToolDetail, projectToolDetail } from '@/lib/catalog/projection/tool'
 import { defineAuthorizedWorkspaceUseCase } from '@/lib/core/application'
 import { isHosted } from '@/lib/core/config/env-flags'
 import { OrchestrationError } from '@/lib/core/orchestration/types'
-import { resolveToolId } from '@/tools/tool-ids'
 
 export interface GetCatalogToolInput {
   workspaceId: string
@@ -22,27 +21,31 @@ export interface GetCatalogToolResult {
 /**
  * One built-in tool's parameters and outputs.
  *
- * An unversioned name resolves to the newest version exactly as execution does,
- * and the returned `id` is the resolved one so a caller can see which version
- * answered. A tool the workspace's blocks do not expose answers 404 rather than
- * 403, for the same enumeration reason as the block detail read.
+ * An unversioned name resolves to the newest version this caller can see, the
+ * way the block detail read does, and the returned `id` is the resolved one so
+ * a caller can see which version answered. Resolving through
+ * `@/tools/tool-ids` instead would answer with the superseded v1 that stays
+ * registered for execution's sake, which no visible block exposes — so every
+ * versioned family 404'd on the base name. A tool the workspace's blocks do not
+ * expose answers 404 rather than 403, for the same enumeration reason as the
+ * block detail read.
  */
 export const getCatalogTool = defineAuthorizedWorkspaceUseCase({
   operation: catalogOperations.readTool,
   resolveContext: ({ input }: { input: GetCatalogToolInput }) =>
     loadCatalogWorkspaceContext(input.workspaceId),
   authorizationOptions: {},
   execute: async ({ principal, input, context }): Promise<GetCatalogToolResult> => {
-    const resolvedToolId = resolveToolId(input.toolId)
-    const tool = projectToolDetail(resolvedToolId, { hostedKeys: isHosted })
-    if (!tool) throw new OrchestrationError('not_found', 'Tool not found')
-
     const gate = await resolveCatalogGate(principal, context)
     const visibleToolIds = await resolveVisibleToolIds(gate)
+    const resolvedToolId = resolveVisibleToolId(input.toolId, visibleToolIds)
     if (!visibleToolIds.has(resolvedToolId)) {
       throw new OrchestrationError('not_found', 'Tool not found')
     }
 
+    const tool = projectToolDetail(resolvedToolId, { hostedKeys: isHosted })
+    if (!tool) throw new OrchestrationError('not_found', 'Tool not found')
+
     return { tool }
   },
 })

apps/sim/lib/catalog/application/tool-scope.ts

@@ -6,6 +6,41 @@ import {
 import { getAllBlocks } from '@/blocks/registry'
 import { resolveToolId } from '@/tools/tool-ids'
 
+const VERSION_SUFFIX = /^\d+$/
+
+/**
+ * The newest visible version of a tool name, or the name unchanged when none is.
+ *
+ * The detail-read counterpart of {@link resolveVisibleToolIds}, and the tool
+ * analogue of `getLatestBlockForViewer`: "newest registered" and "newest visible
+ * to this caller" are different questions. `@/tools/tool-ids` answers the first
+ * — and superseded v1 tools stay registered so execution of a stored id keeps
+ * working, so `resolveToolId('github_comment')` returns `github_comment`, which
+ * no visible block exposes. Resolving against the visible set instead walks down
+ * to `github_comment_v2`, the id the tool list publishes.
+ *
+ * An id that is itself visible is returned untouched, so an exact versioned
+ * request never silently answers with a different version.
+ */
+export function resolveVisibleToolId(toolId: string, visibleToolIds: ReadonlySet<string>): string {
+  if (visibleToolIds.has(toolId)) return toolId
+
+  const prefix = `${toolId}_v`
+  let bestId: string | undefined
+  let bestVersion = 0
+  for (const candidate of visibleToolIds) {
+    if (!candidate.startsWith(prefix)) continue
+    const suffix = candidate.slice(prefix.length)
+    if (!VERSION_SUFFIX.test(suffix)) continue
+    const version = Number.parseInt(suffix, 10)
+    if (version > bestVersion) {
+      bestVersion = version
+      bestId = candidate
+    }
+  }
+  return bestId ?? toolId
+}
+
 /**
  * The built-in tools this caller may run in this workspace.
  *