cli: show world-specific run fields in inspect output via World.describeRun

.changeset/inspect-region-column.md

@@ -0,0 +1,7 @@
+---
+'@workflow/world': patch
+'@workflow/world-vercel': patch
+'@workflow/cli': patch
+---
+
+Show world-specific run fields (e.g. region on Vercel) in `workflow inspect` output via the new optional `World.describeRun` hook.

packages/cli/src/lib/inspect/output.test.ts

@@ -190,6 +190,289 @@ describe('listRuns', () => {
       },
     });
   });
+
+  it('includes world-specific fields when the world defines describeRun', async () => {
+    const run = {
+      runId: 'wrun_41KX206BTK10M0C31CMN2AS1JS',
+      status: 'running',
+      deploymentId: 'dep-1',
+      workflowName: 'workflow//./src/workflows/test//myWorkflow',
+      specVersion: 2,
+      attributes: {},
+      createdAt: new Date('2026-06-30T00:00:00.000Z'),
+      updatedAt: new Date('2026-06-30T00:00:00.000Z'),
+      startedAt: new Date('2026-06-30T00:00:01.000Z'),
+      completedAt: null,
+      errorCode: null,
+      workflowCoreVersion: null,
+      workflowEncryptionEnabled: false,
+    } satisfies AnalyticsRun;
+    const describeRun = vi.fn().mockReturnValue({ region: 'sfo1', shard: 'a' });
+    const world = {
+      describeRun,
+      analytics: {
+        runs: {
+          list: vi.fn().mockResolvedValue({
+            data: [run],
+            cursor: null,
+            hasMore: false,
+          }),
+        },
+      },
+    } as unknown as World;
+    const write = vi
+      .spyOn(process.stdout, 'write')
+      .mockImplementation(() => true);
+
+    await listRuns(world, { json: true });
+
+    expect(describeRun).toHaveBeenCalledWith(
+      expect.objectContaining({ runId: run.runId })
+    );
+    const output = JSON.parse(String(write.mock.calls[0][0]));
+    expect(output.data[0].region).toBe('sfo1');
+    expect(output.data[0].shard).toBe('a');
+  });
+
+  it('preserves null field values from describeRun in JSON output', async () => {
+    // null means "applicable but undeterminable" — distinguishable from
+    // the hook being absent (key missing entirely).
+    const run = {
+      runId: 'wrun_malformed',
+      status: 'running',
+      deploymentId: 'dep-1',
+      workflowName: 'workflow//./src/workflows/test//myWorkflow',
+      specVersion: 2,
+      attributes: {},
+      createdAt: new Date('2026-06-30T00:00:00.000Z'),
+      updatedAt: new Date('2026-06-30T00:00:00.000Z'),
+      startedAt: new Date('2026-06-30T00:00:01.000Z'),
+      completedAt: null,
+      errorCode: null,
+      workflowCoreVersion: null,
+      workflowEncryptionEnabled: false,
+    } satisfies AnalyticsRun;
+    const world = {
+      describeRun: vi.fn().mockReturnValue({ region: null }),
+      analytics: {
+        runs: {
+          list: vi.fn().mockResolvedValue({
+            data: [run],
+            cursor: null,
+            hasMore: false,
+          }),
+        },
+      },
+    } as unknown as World;
+    const write = vi
+      .spyOn(process.stdout, 'write')
+      .mockImplementation(() => true);
+
+    await listRuns(world, { json: true });
+
+    const output = JSON.parse(String(write.mock.calls[0][0]));
+    expect('region' in output.data[0]).toBe(true);
+    expect(output.data[0].region).toBeNull();
+  });
+
+  it('never lets describeRun overwrite canonical run fields', async () => {
+    const run = {
+      runId: 'wrun_41KX206BTK10M0C31CMN2AS1JS',
+      status: 'running',
+      deploymentId: 'dep-1',
+      workflowName: 'workflow//./src/workflows/test//myWorkflow',
+      specVersion: 2,
+      attributes: {},
+      createdAt: new Date('2026-06-30T00:00:00.000Z'),
+      updatedAt: new Date('2026-06-30T00:00:00.000Z'),
+      startedAt: new Date('2026-06-30T00:00:01.000Z'),
+      completedAt: null,
+      errorCode: null,
+      workflowCoreVersion: null,
+      workflowEncryptionEnabled: false,
+    } satisfies AnalyticsRun;
+    const world = {
+      // Hostile/buggy world: tries to clobber canonical fields.
+      describeRun: vi
+        .fn()
+        .mockReturnValue({ status: 'hacked', runId: 'nope', region: 'sfo1' }),
+      analytics: {
+        runs: {
+          list: vi.fn().mockResolvedValue({
+            data: [run],
+            cursor: null,
+            hasMore: false,
+          }),
+        },
+      },
+    } as unknown as World;
+    const write = vi
+      .spyOn(process.stdout, 'write')
+      .mockImplementation(() => true);
+
+    await listRuns(world, { json: true });
+
+    const output = JSON.parse(String(write.mock.calls[0][0]));
+    expect(output.data[0].status).toBe('running');
+    expect(output.data[0].runId).toBe(run.runId);
+    expect(output.data[0].region).toBe('sfo1');
+  });
+
+  it('treats a throwing describeRun as contributing no fields', async () => {
+    const run = {
+      runId: 'wrun_41KX206BTK10M0C31CMN2AS1JS',
+      status: 'running',
+      deploymentId: 'dep-1',
+      workflowName: 'workflow//./src/workflows/test//myWorkflow',
+      specVersion: 2,
+      attributes: {},
+      createdAt: new Date('2026-06-30T00:00:00.000Z'),
+      updatedAt: new Date('2026-06-30T00:00:00.000Z'),
+      startedAt: new Date('2026-06-30T00:00:01.000Z'),
+      completedAt: null,
+      errorCode: null,
+      workflowCoreVersion: null,
+      workflowEncryptionEnabled: false,
+    } satisfies AnalyticsRun;
+    const world = {
+      describeRun: vi.fn().mockImplementation(() => {
+        throw new Error('buggy world');
+      }),
+      analytics: {
+        runs: {
+          list: vi.fn().mockResolvedValue({
+            data: [run],
+            cursor: null,
+            hasMore: false,
+          }),
+        },
+      },
+    } as unknown as World;
+    const write = vi
+      .spyOn(process.stdout, 'write')
+      .mockImplementation(() => true);
+
+    // Must not throw despite the world violating the no-throw contract.
+    await listRuns(world, { json: true });
+
+    const output = JSON.parse(String(write.mock.calls[0][0]));
+    expect(output.data[0].status).toBe('running');
+    expect('region' in output.data[0]).toBe(false);
+  });
+
+  it('supports async describeRun implementations', async () => {
+    const run = {
+      runId: 'wrun_41KX206BTK10M0C31CMN2AS1JS',
+      status: 'running',
+      deploymentId: 'dep-1',
+      workflowName: 'workflow//./src/workflows/test//myWorkflow',
+      specVersion: 2,
+      attributes: {},
+      createdAt: new Date('2026-06-30T00:00:00.000Z'),
+      updatedAt: new Date('2026-06-30T00:00:00.000Z'),
+      startedAt: new Date('2026-06-30T00:00:01.000Z'),
+      completedAt: null,
+      errorCode: null,
+      workflowCoreVersion: null,
+      workflowEncryptionEnabled: false,
+    } satisfies AnalyticsRun;
+    const world = {
+      describeRun: vi.fn().mockResolvedValue({ region: 'sfo1' }),
+      analytics: {
+        runs: {
+          list: vi.fn().mockResolvedValue({
+            data: [run],
+            cursor: null,
+            hasMore: false,
+          }),
+        },
+      },
+    } as unknown as World;
+    const write = vi
+      .spyOn(process.stdout, 'write')
+      .mockImplementation(() => true);
+
+    await listRuns(world, { json: true });
+
+    const output = JSON.parse(String(write.mock.calls[0][0]));
+    expect(output.data[0].region).toBe('sfo1');
+  });
+
+  it('treats a rejecting async describeRun as contributing no fields', async () => {
+    const run = {
+      runId: 'wrun_41KX206BTK10M0C31CMN2AS1JS',
+      status: 'running',
+      deploymentId: 'dep-1',
+      workflowName: 'workflow//./src/workflows/test//myWorkflow',
+      specVersion: 2,
+      attributes: {},
+      createdAt: new Date('2026-06-30T00:00:00.000Z'),
+      updatedAt: new Date('2026-06-30T00:00:00.000Z'),
+      startedAt: new Date('2026-06-30T00:00:01.000Z'),
+      completedAt: null,
+      errorCode: null,
+      workflowCoreVersion: null,
+      workflowEncryptionEnabled: false,
+    } satisfies AnalyticsRun;
+    const world = {
+      describeRun: vi.fn().mockRejectedValue(new Error('async buggy world')),
+      analytics: {
+        runs: {
+          list: vi.fn().mockResolvedValue({
+            data: [run],
+            cursor: null,
+            hasMore: false,
+          }),
+        },
+      },
+    } as unknown as World;
+    const write = vi
+      .spyOn(process.stdout, 'write')
+      .mockImplementation(() => true);
+
+    await listRuns(world, { json: true });
+
+    const output = JSON.parse(String(write.mock.calls[0][0]));
+    expect(output.data[0].status).toBe('running');
+    expect('region' in output.data[0]).toBe(false);
+  });
+
+  it('adds no world fields when the world lacks describeRun', async () => {
+    const run = {
+      runId: 'wrun_01KX2M5N3RBNC12RYWYYH4WWQJ',
+      status: 'running',
+      deploymentId: 'dep-1',
+      workflowName: 'workflow//./src/workflows/test//myWorkflow',
+      specVersion: 2,
+      attributes: {},
+      createdAt: new Date('2026-06-30T00:00:00.000Z'),
+      updatedAt: new Date('2026-06-30T00:00:00.000Z'),
+      startedAt: new Date('2026-06-30T00:00:01.000Z'),
+      completedAt: null,
+      errorCode: null,
+      workflowCoreVersion: null,
+      workflowEncryptionEnabled: false,
+    } satisfies AnalyticsRun;
+    const world = {
+      analytics: {
+        runs: {
+          list: vi.fn().mockResolvedValue({
+            data: [run],
+            cursor: null,
+            hasMore: false,
+          }),
+        },
+      },
+    } as unknown as World;
+    const write = vi
+      .spyOn(process.stdout, 'write')
+      .mockImplementation(() => true);
+
+    await listRuns(world, { json: true });
+
+    const output = JSON.parse(String(write.mock.calls[0][0]));
+    expect('region' in output.data[0]).toBe(false);
+  });
 });
 
 describe('listSteps', () => {