Phase A1–A4 (sim half): inventory printer, universal grep, docs search, jq/outline pipes

packages/sim-cli/scripts/print-command-inventory.ts prints the public CLI
inventory for the worker card — walks buildProgram(), the same tree --help
and the docs read, and resolves each command response shape from the v2
OpenAPI documents. lib/mothership/agent-cli gains the universal-grep
engine (every world, pretty-printed as its get returns it, block catalog
LRU-cached per workspace, secrets names only), the docs-search engine
(wrapping searchDocsServerTool), and typed jq (jq-wasm 1.8.2) and outline
pipe stages; a stage that cannot apply fails the invocation with the
reason. Still primitives only: no grammar, no flag interpretation.

https://claude.ai/code/session_01HFVhPDtRZuCgupPco633w8

Author: Sg312

apps/sim/lib/mothership/agent-cli/engines/docs-search.test.ts

@@ -0,0 +1,42 @@
+/**
+ * @vitest-environment node
+ */
+import { describe, expect, it, vi } from 'vitest'
+
+const { execute } = vi.hoisted(() => ({
+  execute: vi
+    .fn()
+    .mockResolvedValue({ results: [{ path: 'docs/integrations/slack.mdx' }], query: 'q' }),
+}))
+vi.mock('@/lib/mothership/tools/server/docs/search-docs', () => ({
+  searchDocsServerTool: { execute },
+}))
+
+import { runEngine } from '@/lib/mothership/agent-cli/engines'
+import type { AgentCliRuntime } from '@/lib/mothership/agent-cli/types'
+
+const runtime: AgentCliRuntime = {
+  workspaceId: 'ws-1',
+  userId: 'user-1',
+  client: { request: async () => ({}) as never },
+}
+
+describe('docs search engine', () => {
+  it('joins the query words and maps --top/--path onto the docs search tool', async () => {
+    const result = await runEngine('docs search', ['slack', 'streaming'], runtime, {
+      top: '3',
+      path: 'docs/integrations',
+    })
+    expect(result.exitCode).toBe(0)
+    expect(execute).toHaveBeenCalledWith(
+      { query: 'slack streaming', topK: 3, path: 'docs/integrations' },
+      { userId: 'user-1', workspaceId: 'ws-1' }
+    )
+    expect(JSON.parse(result.stdout).results[0].path).toBe('docs/integrations/slack.mdx')
+  })
+
+  it('fails usefully without a query or with a bad --top', async () => {
+    expect((await runEngine('docs search', [], runtime, {})).exitCode).toBe(1)
+    expect((await runEngine('docs search', ['x'], runtime, { top: 'many' })).exitCode).toBe(1)
+  })
+})

apps/sim/lib/mothership/agent-cli/engines/docs-search.ts

@@ -0,0 +1,38 @@
+import {
+  type AgentCliEngine,
+  type AgentCliFlags,
+  agentCliFail,
+  agentCliOk,
+} from '@/lib/mothership/agent-cli/types'
+import { searchDocsServerTool } from '@/lib/mothership/tools/server/docs/search-docs'
+
+const DEFAULT_TOP = 6
+const MAX_TOP = 20
+
+function topFrom(flags: AgentCliFlags): number | string {
+  const raw = flags.top
+  if (raw === undefined || raw === true) return DEFAULT_TOP
+  const n = Number.parseInt(raw, 10)
+  if (!Number.isFinite(n) || n < 1) return '--top needs a positive number'
+  return Math.min(n, MAX_TOP)
+}
+
+/**
+ * `docs search <query> [--top n] [--path prefix]` — the product docs, through the same
+ * engine the `search_docs` tool used, as a noun in the CLI grammar (18-agent-surface.md
+ * A3). One knowledge surface: the tips corpus merges into these pages over time.
+ */
+export const docsSearchCommand: AgentCliEngine = {
+  async execute(positionals, runtime, flags) {
+    const query = positionals.join(' ').trim()
+    if (!query) return agentCliFail('Usage: sim docs search <query> [--top n] [--path prefix]')
+    const top = topFrom(flags)
+    if (typeof top === 'string') return agentCliFail(top)
+    const path = typeof flags.path === 'string' ? flags.path : undefined
+    const output = await searchDocsServerTool.execute(
+      { query, topK: top, ...(path ? { path } : {}) },
+      { userId: runtime.userId, workspaceId: runtime.workspaceId }
+    )
+    return agentCliOk(JSON.stringify(output, null, 2))
+  },
+}

apps/sim/lib/mothership/agent-cli/engines/index.ts

@@ -1,10 +1,12 @@
 import { getErrorMessage } from '@sim/utils/errors'
 import { workflowDepsCommand } from '@/lib/mothership/agent-cli/engines/deps'
+import { docsSearchCommand } from '@/lib/mothership/agent-cli/engines/docs-search'
 import { filesGrepCommand } from '@/lib/mothership/agent-cli/engines/files-grep'
 import { workflowGrepCommand, workflowsGrepCommand } from '@/lib/mothership/agent-cli/engines/grep'
 import { workflowLintCommand } from '@/lib/mothership/agent-cli/engines/lint'
 import { logsQueryCommand } from '@/lib/mothership/agent-cli/engines/query'
 import { workflowTraceCommand } from '@/lib/mothership/agent-cli/engines/trace'
+import { universalGrepCommand } from '@/lib/mothership/agent-cli/engines/universal-grep'
 import {
   workflowBlocksCommand,
   workflowEdgesCommand,
@@ -23,7 +25,9 @@ import {
  * augmentation-drift check reads these keys.
  */
 export const AUGMENTATION_ENGINES: Readonly<Record<string, AgentCliEngine>> = {
+  'docs search': docsSearchCommand,
   'files grep': filesGrepCommand,
+  grep: universalGrepCommand,
   'logs query': logsQueryCommand,
   'workflow blocks': workflowBlocksCommand,
   'workflow deps': workflowDepsCommand,

apps/sim/lib/mothership/agent-cli/engines/universal-grep.test.ts

@@ -0,0 +1,89 @@
+/**
+ * @vitest-environment node
+ */
+import { describe, expect, it } from 'vitest'
+import { runEngine } from '@/lib/mothership/agent-cli/engines'
+import type { AgentCliRuntime } from '@/lib/mothership/agent-cli/types'
+
+const SLACK_V2 = {
+  id: 'slack_v2',
+  name: 'Slack',
+  triggers: [{ id: 'slack_webhook', configFields: { streamOutputs: { type: 'boolean' } } }],
+  operations: { send_message: { toolId: 'slack_send' } },
+}
+
+function runtimeWith(responses: Record<string, unknown>): AgentCliRuntime {
+  return {
+    workspaceId: `ws-${Math.random().toString(36).slice(2)}`,
+    userId: 'user-1',
+    client: {
+      request: async <T>(path: string): Promise<T> => {
+        const hit = responses[path]
+        if (hit === undefined) throw new Error(`Unexpected request: ${path}`)
+        return hit as T
+      },
+    },
+  }
+}
+
+const CATALOG = {
+  '/api/v2/blocks': { data: [{ id: 'slack_v2' }, { id: 'agent' }], nextCursor: null },
+  '/api/v2/blocks/slack_v2': { data: SLACK_V2 },
+  '/api/v2/blocks/agent': { data: { id: 'agent', name: 'Agent', inputSchema: [{ id: 'model' }] } },
+}
+
+describe('universal grep', () => {
+  it('finds field ids inside block definitions and names the path-shaped line', async () => {
+    const result = await runEngine('grep', ['stream'], runtimeWith(CATALOG), {
+      scope: 'blocks',
+      i: true,
+    })
+    expect(result.exitCode).toBe(0)
+    expect(result.stdout).toContain('blocks/slack_v2:')
+    expect(result.stdout).toContain('"streamOutputs"')
+    expect(result.stdout).not.toContain('blocks/agent:')
+  })
+
+  it('narrows to one resource with --in and counts with --count', async () => {
+    const within = await runEngine('grep', ['id'], runtimeWith(CATALOG), {
+      scope: 'blocks',
+      in: 'agent',
+    })
+    expect(within.stdout).toContain('blocks/agent:')
+    expect(within.stdout).not.toContain('blocks/slack_v2:')
+    const count = await runEngine('grep', ['id'], runtimeWith(CATALOG), {
+      scope: 'blocks',
+      count: true,
+    })
+    expect(count.stdout).toMatch(/^\d+ \(blocks=\d+\)$/)
+  })
+
+  it('refuses an unknown scope with a did-you-mean and the scope list', async () => {
+    const result = await runEngine('grep', ['x'], runtimeWith({}), { scope: 'block' })
+    expect(result.exitCode).toBe(1)
+    expect(result.stderr).toContain('Did you mean blocks')
+    expect(result.stderr).toContain('workflows, blocks, tools')
+  })
+
+  it('materializes secrets as names only', async () => {
+    const result = await runEngine(
+      'grep',
+      ['OPENAI'],
+      runtimeWith({
+        '/api/v2/secrets': {
+          data: [{ name: 'OPENAI_API_KEY', value: 'sk-should-never-appear' }],
+          nextCursor: null,
+        },
+      }),
+      { scope: 'secrets' }
+    )
+    expect(result.stdout).toContain('OPENAI_API_KEY')
+    expect(result.stdout).not.toContain('sk-should-never-appear')
+  })
+
+  it('reports no matches honestly', async () => {
+    const result = await runEngine('grep', ['zzz-nope'], runtimeWith(CATALOG), { scope: 'blocks' })
+    expect(result.exitCode).toBe(0)
+    expect(result.stdout).toContain('No matches for "zzz-nope" in blocks')
+  })
+})