improvement(sim-cli): commands reach the API only through the operations they declare

Hand-written commands called SimClient by path and declared nothing, so the command inventory could not mark one Mothership-unavailable when it calls a refused route. Every command now gets its client from callsOperations: calls name an operation, route and method come from the operation table, and the client is typed to the declared operations.

Author: waleedlatif1

packages/sim-cli/scripts/print-command-inventory.ts

@@ -142,7 +142,7 @@ const inventory: InventoryCommand[] = collectLeaves(program, []).map(
     const reference = op
       ? commandReference(OPENAPI_DOCS, op, jsonFields, cursorSlot(op) !== null)
       : {}
-    const called = calledOperations(command) ?? (operation ? [operation] : [])
+    const called = calledOperations(command) ?? []
     return {
       path: cmdPath,
       description: command.description(),

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

@@ -45,17 +45,16 @@ import {
   writeCredentialsProfile,
 } from '../config/index'
 import { ProfileOverrideError, redact } from '../config/profile'
-import { clientFrom, globalsOf, profileFrom } from '../context'
+import { globalsOf, profileFrom } from '../context'
 import { setSoftExitCode } from '../embed-context'
-import {
-  type GetMetaResponse,
-  type GetWorkspaceResponse,
-  type ListWorkspacesResponse,
-  V2_OPERATIONS,
+import type {
+  GetMetaResponse,
+  GetWorkspaceResponse,
+  ListWorkspacesResponse,
 } from '../generated/v2-api'
-import { requestAllPages, resolvePath, SimApiError, type SimClient } from '../http/client'
+import { SimApiError } from '../http/client'
 import { type Column, printList, printRecord, safeOneLine, text } from '../output/render'
-import { callsOperations } from '../runtime/called-operations'
+import { callsOperations, type OperationClient } from '../runtime/called-operations'
 
 type SelectableWorkspace = ListWorkspacesResponse['data'][number]
 
@@ -265,28 +264,26 @@ function requireStoredAuthentication(profile: ResolvedProfile): string {
 }
 
 async function getWorkspaceById(
-  client: Pick<SimClient, 'request'>,
+  client: OperationClient<'getWorkspace'>,
   workspaceId: string
 ): Promise<SelectableWorkspace> {
-  const operation = V2_OPERATIONS.getWorkspace
-  const response = await client.request<GetWorkspaceResponse>(
-    resolvePath(operation.path, { workspaceId }),
-    { method: operation.method }
-  )
+  const response = await client.request<GetWorkspaceResponse>('getWorkspace', {
+    params: { workspaceId },
+  })
   return response.data
 }
 
-async function chooseWorkspace(client: Pick<SimClient, 'request'>): Promise<SelectableWorkspace> {
+async function chooseWorkspace(
+  client: OperationClient<'listWorkspaces'>
+): Promise<SelectableWorkspace> {
   if (!process.stdin.isTTY) {
     throw new SimApiError(
       'No workspace provided. Pass --workspace <id> when creating a profile non-interactively.',
       0
     )
   }
 
-  const operation = V2_OPERATIONS.listWorkspaces
-  const workspaces = await requestAllPages<SelectableWorkspace>(client, operation.path, {
-    method: operation.method,
+  const workspaces = await client.requestAllPages<SelectableWorkspace>('listWorkspaces', {
     query: { sortBy: 'name', sortOrder: 'asc' },
     pageSize: 100,
     limit: MAX_INTERACTIVE_WORKSPACES + 1,
@@ -323,14 +320,16 @@ async function chooseWorkspace(client: Pick<SimClient, 'request'>): Promise<Sele
 }
 
 function addProfileCommand(): Command {
-  return new Command('add')
+  const add = new Command('add')
+  const connectAdd = callsOperations(add, ['getWorkspace', 'listWorkspaces'])
+  return add
     .description('Add a workspace profile that shares the active stored login')
     .argument('<name>', 'Name for the new profile')
     .option('-w, --workspace <id>', 'Existing workspace to use; omit for an interactive picker')
     .action(async (profileName: string, _options: unknown, command: Command) => {
       validateNewProfileName(profileName)
 
-      const { client, profile } = clientFrom(command)
+      const { client, profile } = connectAdd()
       const authProfile = requireStoredAuthentication(profile)
       const credential = readStoredCredential(authProfile)
       const workspaceId = globalsOf(command).workspace
@@ -866,7 +865,7 @@ const WHOAMI_EXIT_CODES = {
  * whose metadata endpoint is unavailable.
  */
 async function verifyProfile(
-  client: Pick<SimClient, 'request'>,
+  client: OperationClient<'getMeta' | 'getWorkspace'>,
   profile: ResolvedProfile
 ): Promise<Verification> {
   if (!profile.apiKey && !profile.oauth) {
@@ -881,11 +880,8 @@ async function verifyProfile(
 
   let keyType: KeyType | null = null
   let authenticated: boolean | null = null
-  const metaOperation = V2_OPERATIONS.getMeta
   try {
-    const response = await client.request<unknown>(metaOperation.path, {
-      method: metaOperation.method,
-    })
+    const response = await client.request<unknown>('getMeta')
     const reportedKeyType = toRecord(toRecord(response).data).keyType
     if (
       reportedKeyType === 'personal' ||
@@ -918,12 +914,10 @@ async function verifyProfile(
     }
   }
 
-  const operation = V2_OPERATIONS.getWorkspace
   try {
-    const response = await client.request<GetWorkspaceResponse>(
-      resolvePath(operation.path, { workspaceId: profile.workspaceId }),
-      { method: operation.method }
-    )
+    const response = await client.request<GetWorkspaceResponse>('getWorkspace', {
+      params: { workspaceId: profile.workspaceId },
+    })
     const { id, name, memberCount } = response.data
     // Projected field by field: the record carries display fields the machine
     // output has no business inventing a contract for.
@@ -969,10 +963,12 @@ function presentVerification(verification: Verification): string {
 
 export function whoamiCommand(): Command {
   const whoami = new Command('whoami')
+  const connectWhoami = callsOperations(whoami, ['getMeta', 'getWorkspace'])
+  return whoami
     .description('Show the resolved profile, where each setting came from, and whether it works')
     .option('--no-verify', 'Skip the API check and only print the resolved settings')
-    .action(async (options: { verify: boolean }, command: Command) => {
-      const { client, profile } = clientFrom(command)
+    .action(async (options: { verify: boolean }) => {
+      const { client, profile } = connectWhoami()
       const { sources } = profile
       const authentication = presentAuthentication(sources.credential)
 
@@ -1035,7 +1031,6 @@ export function whoamiCommand(): Command {
       const exitCode = WHOAMI_EXIT_CODES[verification.status]
       if (exitCode !== 0) setSoftExitCode(exitCode)
     })
-  return callsOperations(whoami, ['getMeta', 'getWorkspace'])
 }
 
 interface ProfileRow {

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

@@ -1,5 +1,4 @@
 import { type Command, Option } from 'commander'
-import { clientFrom } from '../context'
 import type { CommandSpec } from '../contract/types'
 import {
   type CreateCredentialConnectionResponse,
@@ -9,7 +8,7 @@ import {
 } from '../generated/v2-api'
 import { SimApiError } from '../http/client'
 import { describeOperation } from '../runtime/build'
-import { callsOperations, runsOperation } from '../runtime/called-operations'
+import { apiCommand, type Connection } from '../runtime/called-operations'
 import { coerce } from '../runtime/request'
 import { renderResult } from '../runtime/result'
 
@@ -108,15 +107,12 @@ async function credentialValues(
 }
 
 async function createServiceAccount(
-  command: Command,
+  { client, profile }: Connection<'listCredentialProviders' | 'createServiceAccountCredential'>,
   providerId: string,
   options: CreateServiceAccountOptions
 ): Promise<void> {
-  const { client, profile } = clientFrom(command)
   const workspaceId = client.requireWorkspace()
-  const discovery = V2_OPERATIONS.listCredentialProviders
-  const catalog = await client.request<ListCredentialProvidersResponse>(discovery.path, {
-    method: discovery.method,
+  const catalog = await client.request<ListCredentialProvidersResponse>('listCredentialProviders', {
     query: { workspaceId },
   })
   const provider = serviceAccountProvider(catalog.data, providerId)
@@ -125,19 +121,20 @@ async function createServiceAccount(
   }
 
   const credentialFields = await credentialValues(provider, options.credentials)
-  const operation = V2_OPERATIONS.createServiceAccountCredential
-  const response = await client.request<CreateServiceAccountCredentialResponse>(operation.path, {
-    method: operation.method,
-    body: {
-      workspaceId,
-      type: 'service_account',
-      providerId,
-      displayName: options.name,
-      ...(options.description ? { description: options.description } : {}),
-      ...(options.id ? { id: options.id } : {}),
-      credentials: JSON.stringify(credentialFields),
-    },
-  })
+  const response = await client.request<CreateServiceAccountCredentialResponse>(
+    'createServiceAccountCredential',
+    {
+      body: {
+        workspaceId,
+        type: 'service_account',
+        providerId,
+        displayName: options.name,
+        ...(options.description ? { description: options.description } : {}),
+        ...(options.id ? { id: options.id } : {}),
+        credentials: JSON.stringify(credentialFields),
+      },
+    }
+  )
 
   renderResult(
     'createServiceAccountCredential',
@@ -147,16 +144,19 @@ async function createServiceAccount(
   )
 }
 
-async function createConnectionLink(command: Command, body: ConnectionBody): Promise<void> {
-  const { client, profile } = clientFrom(command)
-  const operation = V2_OPERATIONS.createCredentialConnection
-  const response = await client.request<CreateCredentialConnectionResponse>(operation.path, {
-    method: operation.method,
-    body: {
-      workspaceId: client.requireWorkspace(),
-      ...body,
-    },
-  })
+async function createConnectionLink(
+  { client, profile }: Connection<'createCredentialConnection'>,
+  body: ConnectionBody
+): Promise<void> {
+  const response = await client.request<CreateCredentialConnectionResponse>(
+    'createCredentialConnection',
+    {
+      body: {
+        workspaceId: client.requireWorkspace(),
+        ...body,
+      },
+    }
+  )
 
   renderResult('createCredentialConnection', profile.output, response.data, CONNECTION_RESULT)
 }
@@ -194,8 +194,13 @@ export function attachCredentialCommands(program: Command): void {
 
   acceptNameOnUpdate(credentials)
 
-  const create = credentials
-    .command('create')
+  const [create, connectCreate] = apiCommand(
+    credentials,
+    'create',
+    ['listCredentialProviders', 'createServiceAccountCredential'],
+    { runs: 'createServiceAccountCredential' }
+  )
+  create
     .argument('<providerId>', 'Service-account provider to create a credential for')
     .description(
       describeOperation(
@@ -217,14 +222,12 @@ export function attachCredentialCommands(program: Command): void {
       '--id <credentialId>',
       'Client-generated credential ID when provider discovery requires it'
     )
-    .action((providerId: string, options: CreateServiceAccountOptions, command: Command) =>
-      createServiceAccount(command, providerId, options)
+    .action((providerId: string, options: CreateServiceAccountOptions) =>
+      createServiceAccount(connectCreate(), providerId, options)
     )
-  callsOperations(create, ['listCredentialProviders', 'createServiceAccountCredential'])
-  runsOperation(create, 'createServiceAccountCredential')
 
-  credentials
-    .command('connect')
+  const [connect, connectLink] = apiCommand(credentials, 'connect', ['createCredentialConnection'])
+  connect
     .argument('<providerId>', 'OAuth provider to connect')
     .description(
       describeOperation(
@@ -233,20 +236,20 @@ export function attachCredentialCommands(program: Command): void {
       )
     )
     .requiredOption('--name <displayName>', 'Name shown for the new credential in Sim (required)')
-    .action(async (providerId: string, options: { name: string }, command: Command) =>
-      createConnectionLink(command, { providerId, displayName: options.name })
+    .action(async (providerId: string, options: { name: string }) =>
+      createConnectionLink(connectLink(), { providerId, displayName: options.name })
     )
 
-  credentials
-    .command('reconnect')
+  const [reconnect, reconnectLink] = apiCommand(credentials, 'reconnect', [
+    'createCredentialConnection',
+  ])
+  reconnect
     .argument('<credentialId>', 'Existing OAuth credential to re-authorize')
     .description(
       describeOperation(
         V2_OPERATIONS.createCredentialConnection,
         'Create a short-lived link for reconnecting an OAuth credential'
       )
     )
-    .action((credentialId: string, _options: unknown, command: Command) =>
-      createConnectionLink(command, { credentialId })
-    )
+    .action((credentialId: string) => createConnectionLink(reconnectLink(), { credentialId }))
 }

packages/sim-cli/src/commands/protocol/chat.ts

@@ -2,12 +2,11 @@ import type { Command } from 'commander'
 import { embedStore } from '#sim-cli/embed-context'
 import { writeStderr, writeStdout } from '#sim-cli/output/io'
 import { styles } from '#sim-cli/output/presentation'
-import { clientFrom } from '../../context'
-import { type ChatResponse, V2_OPERATIONS } from '../../generated/v2-api'
+import type { ChatResponse } from '../../generated/v2-api'
 import { SimApiError } from '../../http/client'
 import { readNdjson } from '../../http/ndjson'
 import { sanitize } from '../../output/render'
-import { callsOperations } from '../../runtime/called-operations'
+import { apiCommand } from '../../runtime/called-operations'
 import { printProtocolResult } from './result'
 
 /** The final payload, as `POST /api/v2/chat` answers it. */
@@ -99,8 +98,8 @@ function ignoreBrokenPipe(stream: NodeJS.WriteStream): () => void {
  */
 
 export function attachChat(program: Command): void {
-  const chat = program
-    .command('chat')
+  const [chat, connectChat] = apiCommand(program, 'chat', ['chat'])
+  chat
     .description('Ask Sim and print the reply')
     .argument('<message>', 'What to ask Sim')
     .allowExcessArguments(false)
@@ -119,7 +118,7 @@ Examples:
   $ sim --output json chat "Summarize yesterday's failed runs" | jq -r '.content'
 `
     )
-    .action(async (message: string, options: ChatOptions, command: Command) => {
+    .action(async (message: string, options: ChatOptions) => {
       /**
        * Refused here so the refusal names what the caller typed: the route
        * answers in its own field names, and this command builds its request by
@@ -138,11 +137,10 @@ Examples:
         )
       }
 
-      const { client, profile } = clientFrom(command)
+      const { client, profile } = connectChat()
       const workspaceId = client.requireWorkspace()
 
-      const response = await client.requestRaw(V2_OPERATIONS.chat.path, {
-        method: 'POST',
+      const response = await client.requestRaw('chat', {
         body: {
           workspaceId,
           message,
@@ -198,5 +196,4 @@ Examples:
         restorePipeHandling?.()
       }
     })
-  callsOperations(chat, ['chat'])
 }