improvement(cli): name the metadata command when an embedded download refuses binary output

Author: waleedlatif1

packages/sim-cli/src/commands/protocol/download-refusal.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from 'vitest'
+import { runEmbeddedCli } from '#sim-cli/embed'
+
+const identity = { endpoint: 'https://sim.test', apiKey: 'fixture', workspaceId: 'workspace' }
+
+describe('an embedded binary refusal names the metadata command', () => {
+  it.each([
+    [['files', 'get', 'wf_a'], 'sim files describe wf_a'],
+    [['knowledge', 'export', 'kb_a', '-o', '-'], 'sim knowledge get kb_a'],
+  ])('%j points at %s', async (argv, metadataCommand) => {
+    const result = await runEmbeddedCli(argv, {
+      ...identity,
+      transport: async () =>
+        new Response(new Uint8Array([0x89, 0x50]), { headers: { 'content-type': 'image/png' } }),
+    })
+    expect(result.exitCode).toBe(1)
+    expect(result.stderr).toContain('Use --output-file <path>')
+    expect(result.stderr).toContain(`run \`${metadataCommand}\` for its metadata`)
+  })
+})

packages/sim-cli/src/commands/protocol/files-get.ts

@@ -289,6 +289,14 @@ interface DownloadOutputOptions {
   force?: boolean
 }
 
+/**
+ * Where an embedded caller refused binary bytes on stdout should go instead. A model that asked
+ * for a file's content usually wanted its metadata, so the refusal names the command that has it.
+ */
+interface DownloadRefusalHint {
+  metadataCommand?: string
+}
+
 type DownloadOperation =
   | 'downloadFile'
   | 'downloadFileVersion'
@@ -307,7 +315,8 @@ async function downloadToOutput<Operation extends DownloadOperation>(
   pathParams: Record<string, string>,
   options: DownloadOutputOptions,
   scope: 'workspace' | 'owner',
-  requestInput: Pick<RequestOptions, 'query' | 'body'> = {}
+  requestInput: Pick<RequestOptions, 'query' | 'body'> = {},
+  { metadataCommand }: DownloadRefusalHint = {}
 ): Promise<void> {
   const target = options.outputFile
   const writesToStdout = target === undefined || target === '-'
@@ -332,7 +341,7 @@ async function downloadToOutput<Operation extends DownloadOperation>(
       await response.body.cancel()
       throw new SimApiError(
         embedded
-          ? `Refusing to put ${contentType ?? 'unknown content'} in a text result. Use --output-file <path>.`
+          ? `Refusing to put ${contentType ?? 'unknown content'} in a text result. Use --output-file <path>${metadataCommand ? `, or run \`sim ${metadataCommand}\` for its metadata` : ''}.`
           : `Refusing to write ${contentType ?? 'unknown content'} to an interactive terminal. Use --output-file <path> or pipe stdout.`,
         0
       )
@@ -426,7 +435,15 @@ export function attachFileGet(files: Command): void {
     .option('-o, --output-file <path>', 'Write content to a file instead of stdout')
     .option('--force', 'Overwrite --output-file if it already exists')
     .action((fileId: string, options: DownloadOutputOptions) =>
-      downloadToOutput(connect, 'downloadFile', { fileId }, options, 'workspace')
+      downloadToOutput(
+        connect,
+        'downloadFile',
+        { fileId },
+        options,
+        'workspace',
+        {},
+        { metadataCommand: `files describe ${fileId}` }
+      )
     )
 }
 

packages/sim-cli/src/commands/protocol/knowledge-export.ts

@@ -80,7 +80,7 @@ export function attachKnowledgeExport(knowledge: Command): void {
           await response.body.cancel()
           throw new SimApiError(
             embedded
-              ? `Refusing to put ${contentType ?? 'unknown content'} in a text result. Use --output-file <path>.`
+              ? `Refusing to put ${contentType ?? 'unknown content'} in a text result. Use --output-file <path>, or run \`sim knowledge get ${knowledgeBaseId}\` for its metadata.`
               : `Refusing to write ${contentType ?? 'unknown content'} to an interactive terminal. Use --output-file <path> or pipe stdout.`,
             0
           )