@mondaydotcomorg/z2h-cli 0.30.0 → 0.32.0

package/src/backend/parser/static-value.ts

@@ -0,0 +1,145 @@
+import { displayText, propertyKey, resolveOrSourceText, sourceTextOf } from './utils';
+import { declarationAt } from './bindings';
+import type { AnyNode } from 'acorn';
+import type { Bindings, JsonValue, Resolved } from './types';
+
+type Inner = (child: AnyNode) => Resolved<JsonValue> | undefined;
+
+function resolveLiteral(node: AnyNode & { type: 'Literal' }): Resolved<JsonValue> | undefined {
+  return typeof node.value === 'string' ||
+    typeof node.value === 'number' ||
+    typeof node.value === 'boolean' ||
+    node.value === null
+    ? { value: node.value }
+    : undefined;
+}
+
+/** Template holes only interpolate scalars; a resolved object/array (e.g. `$or`) is shown unresolved instead of glued inline. */
+function resolveTemplate(
+  node: AnyNode & { type: 'TemplateLiteral' },
+  source: string,
+  inner: Inner
+): Resolved<JsonValue> {
+  const text = node.quasis
+    .map((quasi, i) => {
+      const literalText = quasi.value.cooked ?? quasi.value.raw;
+      const hole = node.expressions[i];
+      if (!hole) {
+        return literalText;
+      }
+      const resolved = inner(hole);
+      const scalar =
+        resolved !== undefined &&
+        (typeof resolved.value === 'string' ||
+          typeof resolved.value === 'number' ||
+          typeof resolved.value === 'boolean' ||
+          resolved.value === null);
+      return literalText + (scalar ? displayText(resolved!.value) : `\${${sourceTextOf(hole, source)}}`);
+    })
+    .join('');
+  return { value: text };
+}
+
+/**
+ * Each element/property resolves independently, falling back to source text. A spread is kept
+ * visible under a `...`-prefixed key/value pair rather than silently dropped.
+ */
+function resolveContainer(
+  node: AnyNode & { type: 'ArrayExpression' | 'ObjectExpression' },
+  source: string,
+  bindings: Bindings,
+  inner: Inner
+): Resolved<JsonValue> {
+  const fallbackText = (n: AnyNode) => bestSourceText(n, source, bindings);
+  if (node.type === 'ArrayExpression') {
+    return {
+      value: node.elements.map(element => (element ? resolveOrSourceText(element, source, inner, fallbackText) : null)),
+    };
+  }
+  const result: { [key: string]: JsonValue } = {};
+  for (const prop of node.properties) {
+    if (prop.type === 'SpreadElement') {
+      const spreadText = sourceTextOf(prop.argument, source);
+      result[`...${spreadText}`] = spreadText;
+      continue;
+    }
+    if (prop.type !== 'Property') {
+      continue;
+    }
+    const key = prop.computed
+      ? sourceTextOf(prop.key, source)
+      : propertyKey(prop.key, false) ?? sourceTextOf(prop.key, source);
+    result[key] = resolveOrSourceText(prop.value, source, inner, fallbackText);
+  }
+  return { value: result };
+}
+
+function joinBranches(
+  left: Resolved<JsonValue> | undefined,
+  right: Resolved<JsonValue> | undefined
+): Resolved<JsonValue> | undefined {
+  return left !== undefined && right !== undefined ? { value: { $or: [left.value, right.value] } } : undefined;
+}
+
+function resolveIdentifier(
+  node: AnyNode & { type: 'Identifier' },
+  bindings: Bindings,
+  source: string,
+  resolving: ReadonlySet<string>
+): Resolved<JsonValue> | undefined {
+  if (resolving.has(node.name)) {
+    return undefined;
+  }
+  const decl = declarationAt(bindings, node.name, node.start);
+  if (!decl || decl.kind !== 'const' || !decl.init || decl.path?.length !== 0) {
+    return undefined;
+  }
+  return staticValue(decl.init, bindings, source, new Set(resolving).add(node.name));
+}
+
+/** Source text for a node that failed to resolve — the const declaration's init when the node names one, else the node itself. */
+export function bestSourceText(node: AnyNode, source: string, bindings: Bindings): string {
+  if (node.type === 'Identifier') {
+    const decl = declarationAt(bindings, node.name, node.start);
+    if (decl && decl.kind === 'const' && decl.init && decl.path?.length === 0) {
+      return sourceTextOf(decl.init, source);
+    }
+  }
+  return sourceTextOf(node, source);
+}
+
+export function staticValue(
+  node: AnyNode,
+  bindings: Bindings,
+  source: string,
+  resolving: ReadonlySet<string>
+): Resolved<JsonValue> | undefined {
+  const inner: Inner = child => staticValue(child, bindings, source, resolving);
+  switch (node.type) {
+    case 'Literal':
+      return resolveLiteral(node);
+    case 'TemplateLiteral':
+      return resolveTemplate(node, source, inner);
+    case 'ArrayExpression':
+    case 'ObjectExpression':
+      return resolveContainer(node, source, bindings, inner);
+    case 'BinaryExpression': {
+      if (node.operator !== '+') {
+        return undefined;
+      }
+      const left = inner(node.left);
+      const right = inner(node.right);
+      return typeof left?.value === 'string' && typeof right?.value === 'string'
+        ? { value: left.value + right.value }
+        : undefined;
+    }
+    case 'ConditionalExpression':
+      return joinBranches(inner(node.consequent), inner(node.alternate));
+    case 'LogicalExpression':
+      return joinBranches(inner(node.left), inner(node.right));
+    case 'Identifier':
+      return resolveIdentifier(node, bindings, source, resolving);
+    default:
+      return undefined;
+  }
+}

package/src/backend/parser/types.ts

@@ -0,0 +1,66 @@
+import type { AnyNode, Expression, Node, VariableDeclaration } from 'acorn';
+
+/** `"<domain>.<method>"` → parameter names by position, as documented for handler authors. */
+export type ApiSignatures = Record<string, readonly string[]>;
+
+// ─────────── Bindings ───────────
+
+export interface Declaration {
+  kind: VariableDeclaration['kind'] | 'param';
+  init: Expression | null | undefined;
+  /**
+   * Property path from `init` to this binding: `[]` for `const x = init`,
+   * `['a', 'b']` for `const { a: { b: x } } = init`, `undefined` when the value
+   * is not a plain property read (array/rest/default patterns).
+   */
+  path: string[] | undefined;
+  scope: Node;
+}
+
+export interface Bindings {
+  declarations: Map<string, Declaration[]>;
+  /** Names reassigned or updated after declaration — never followed as a stable alias. */
+  unpinnable: Set<string>;
+}
+
+export interface PatternBinding {
+  name: string;
+  path: string[] | undefined;
+}
+
+// ─────────── Static values ───────────
+
+export type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };
+
+/** Wraps a resolved value so "resolved to null" is distinguishable from "unresolved" (`undefined`). */
+export type Resolved<T> = { readonly value: T };
+
+// ─────────── Member paths ───────────
+
+export interface MemberChain {
+  root: string;
+  parts: string[];
+}
+
+export interface PathResolver {
+  /**
+   * Dotted path of a member chain, following `const` aliases back to their
+   * source: with `const sf = ctx.api.v1.snowflake`, `sf.query` resolves to
+   * `ctx.api.v1.snowflake.query`. Destructuring counts too
+   * (`const { snowflake: sf } = ctx.api.v1`). `undefined` if any link is dynamic.
+   *
+   * Only single, never-reassigned, never-shadowed `const` bindings are followed —
+   * anything else is left as written. The handler's first parameter is treated as
+   * `ctx` even when renamed (`handler(context)` → `context.api.v1.db` resolves as
+   * `ctx.api.v1.db`).
+   */
+  pathOf(node: AnyNode): string | undefined;
+}
+
+// ─────────── API usage ───────────
+
+/** Undocumented arguments or methods fall back to `arg<index>` keys. */
+export type ApiCall = Record<string, JsonValue>;
+
+/** `domain -> method -> calls`, later written into `usage.json` by deploy. */
+export type ApiUsage = Record<string, Record<string, ApiCall[]>>;

package/src/backend/parser/utils.ts

@@ -0,0 +1,106 @@
+import type { AnyNode, Node, Pattern } from 'acorn';
+import type { JsonValue, MemberChain, PatternBinding, Resolved } from './types';
+
+// ─────────── Source text ───────────
+
+export const sourceTextOf = (node: AnyNode, source: string): string => source.slice(node.start, node.end);
+
+export function displayText(value: JsonValue): string {
+  return typeof value === 'string' ? value : JSON.stringify(value);
+}
+
+export function resolveOrSourceText(
+  node: AnyNode,
+  source: string,
+  resolve: (node: AnyNode) => Resolved<JsonValue> | undefined,
+  fallbackText: (node: AnyNode) => string = n => sourceTextOf(n, source)
+): JsonValue {
+  const resolved = resolve(node);
+  return resolved !== undefined ? resolved.value : fallbackText(node);
+}
+
+// ─────────── Keys and member chains ───────────
+
+/** Static property key of `obj.key` / `obj['key']` / `{ key: … }`; `undefined` when computed from a non-literal. */
+export function propertyKey(key: AnyNode, computed: boolean): string | undefined {
+  if (key.type === 'Literal' && typeof key.value === 'string') {
+    return key.value;
+  }
+  if (!computed && key.type === 'Identifier') {
+    return key.name;
+  }
+  return undefined;
+}
+
+/** `a.b.c` / `a['b'].c` → root `a`, parts `[b, c]`; `undefined` if any link is dynamic or the root is not an identifier. */
+export function memberChain(node: AnyNode): MemberChain | undefined {
+  if (node.type === 'ChainExpression') {
+    return memberChain(node.expression);
+  }
+  const parts: string[] = [];
+  let cur: AnyNode = node;
+  while (cur.type === 'MemberExpression') {
+    const key = propertyKey(cur.property, cur.computed);
+    if (key === undefined) {
+      return undefined;
+    }
+    parts.unshift(key);
+    cur = cur.object;
+  }
+  return cur.type === 'Identifier' ? { root: cur.name, parts } : undefined;
+}
+
+// ─────────── Binding patterns ───────────
+
+/**
+ * Every identifier a binding pattern introduces, with its property path from the
+ * pattern's value. `path` is deliberately not defaulted: callers pass `[]` for
+ * the root and `undefined` once the pattern stops being a plain property read.
+ */
+export function patternBindings(pattern: Pattern, path: string[] | undefined): PatternBinding[] {
+  switch (pattern.type) {
+    case 'Identifier':
+      return [{ name: pattern.name, path }];
+    case 'ObjectPattern':
+      return pattern.properties.flatMap(p => {
+        if (p.type === 'RestElement') {
+          return patternBindings(p.argument, undefined);
+        }
+        const key = propertyKey(p.key, p.computed);
+        return patternBindings(p.value, path && key !== undefined ? [...path, key] : undefined);
+      });
+    case 'ArrayPattern':
+      return pattern.elements.flatMap(e => (e ? patternBindings(e, undefined) : []));
+    case 'AssignmentPattern':
+      return patternBindings(pattern.left, undefined);
+    case 'RestElement':
+      return patternBindings(pattern.argument, undefined);
+    default:
+      // MemberExpression targets (`obj.x = …`) bind no names.
+      return [];
+  }
+}
+
+export const patternNames = (pattern: Pattern): string[] => patternBindings(pattern, []).map(b => b.name);
+
+// ─────────── Scopes ───────────
+
+const SCOPE_TYPES: ReadonlySet<string> = new Set([
+  'Program',
+  'BlockStatement',
+  'StaticBlock',
+  'SwitchStatement',
+  'ForStatement',
+  'ForInStatement',
+  'ForOfStatement',
+]);
+
+/** Nearest scope enclosing the last node of `ancestors` (which `fullAncestor` includes in the list). */
+export function enclosingScope(ancestors: AnyNode[]): Node {
+  for (let i = ancestors.length - 2; i > 0; i--) {
+    if (SCOPE_TYPES.has(ancestors[i].type)) {
+      return ancestors[i];
+    }
+  }
+  return ancestors[0];
+}

package/src/backend/validate.ts

@@ -1,16 +1,22 @@
 import { simple as walkSimple } from 'acorn-walk';
 import { ALWAYS_ON_CHANNELS, DECLARED_INTEGRATIONS } from '@mondaydotcomorg/z2h-shared-utils';
 import { warn } from '../util/logger';
-import { collectApiDomains, collectBindings, createPathResolver } from './ast';
-import { findHandlerDeclaration, handlerContextParamName, NEVER_A_FUNCTION } from './handler-declaration';
-import { messages } from './messages';
-import { parseOrThrow } from './parse';
+import { collectApiDomains, collectApiUsages } from './parser/api-usage';
+import { collectBindings } from './parser/bindings';
+import { findHandlerDeclaration, handlerContextParamName, NEVER_A_FUNCTION } from './parser/handler-declaration';
+import { createPathResolver } from './parser/member-path';
+import { messages } from './parser/messages';
+import { parseOrThrow } from './parser/parse';
+import type { ApiUsage } from './parser/types';
+
+export type { ApiCall, ApiUsage } from './parser/types';
 
 const KNOWN_API_DOMAINS: readonly string[] = [...ALWAYS_ON_CHANNELS, ...DECLARED_INTEGRATIONS];
 
 export interface HandlerValidation {
   /** Every `ctx.api.v1.<domain>` the handler touches (known or not), sorted and unique. */
   apiDomains: string[];
+  apiUsages: ApiUsage;
 }
 
 /**
@@ -23,9 +29,6 @@ export interface HandlerValidation {
  * Unknown `ctx.api.v1.<domain>` usage is a warning, not a failure: this pass is
  * build-time DX feedback for agent-generated code, never a security boundary —
  * the isolate has no ambient capabilities regardless of what a handler contains.
- *
- * Returns the `ctx.api.v1.*` domains the handler touches so callers (integration
- * detection) can reuse the parse instead of re-scanning the source.
  */
 export function validateHandlerSource(file: string, source: string): HandlerValidation {
   const program = parseOrThrow(file, source);
@@ -53,6 +56,7 @@ export function validateHandlerSource(file: string, source: string): HandlerVali
 
   const paths = createPathResolver(bindings, handlerContextParamName(declaration));
   const apiDomains = collectApiDomains(program, paths);
+  const apiUsages = collectApiUsages(program, bindings, paths, source);
 
   for (const domain of apiDomains) {
     if (!KNOWN_API_DOMAINS.includes(domain)) {
@@ -60,5 +64,5 @@ export function validateHandlerSource(file: string, source: string): HandlerVali
     }
   }
 
-  return { apiDomains: [...apiDomains].sort() };
+  return { apiDomains: [...apiDomains].sort(), apiUsages };
 }

package/src/commands/__tests__/backend-deploy.test.ts

@@ -1,6 +1,6 @@
 import path from 'node:path';
 import os from 'node:os';
-import { mkdtemp, rm, ensureDir, writeFile } from 'fs-extra';
+import { mkdtemp, rm, ensureDir, writeFile, writeJson, readJson, pathExists } from 'fs-extra';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { deployBackend, hasHandlers } from '../backend';
@@ -23,7 +23,11 @@ const readHandlersMock = vi.mocked(readHandlers);
 // handlers directory is known to exist.
 beforeEach(() => {
   readHandlersMock.mockReset();
-  readHandlersMock.mockResolvedValue({ handlers: { call_snowflake: '// code' }, apiDomains: [] });
+  readHandlersMock.mockResolvedValue({
+    handlers: { call_snowflake: '// code' },
+    apiDomains: [],
+    apiUsages: { call_snowflake: {} },
+  });
 });
 
 describe('hasHandlers', () => {
@@ -60,7 +64,7 @@ describe('deployBackend (live)', () => {
   });
 
   it('skips upload when the handlers directory holds nothing', async () => {
-    readHandlersMock.mockResolvedValue({ handlers: {}, apiDomains: [] });
+    readHandlersMock.mockResolvedValue({ handlers: {}, apiDomains: [], apiUsages: {} });
 
     await expect(
       deployBackend({
@@ -79,8 +83,9 @@ describe('deployBackend (live)', () => {
     await ensureDir(path.join(tmp, 'backend', 'handlers'));
     await writeFile(path.join(tmp, 'backend', 'handlers', 'call_snowflake.ts'), '// placeholder');
     readHandlersMock.mockResolvedValue({
-      handlers: { call_snowflake: 'async function handler(ctx) { return ctx.api.v1.snowflake.runQuery("x"); }' },
+      handlers: { call_snowflake: 'async function handler(ctx) { return ctx.api.v1.snowflake.query("x"); }' },
       apiDomains: ['snowflake'],
+      apiUsages: { call_snowflake: { snowflake: { query: [{ sql: 'x' }] } } },
     });
 
     // snowflake is always-on — not a declared integration
@@ -97,6 +102,63 @@ describe('deployBackend (live)', () => {
     expect(mockSend).toHaveBeenCalled();
     const keys: string[] = mockSend.mock.calls.map((c: unknown[]) => (c[0] as { input: { Key: string } }).input.Key);
     expect(keys.some(k => k.includes('/backend-1/'))).toBe(true);
+    // usage.json stays local-only — the runner's S3 discovery still comes from meta.json.
+    expect(keys.some(k => k.endsWith('/usage.json'))).toBe(false);
+    expect(keys.some(k => k.endsWith('/meta.json'))).toBe(true);
+
+    const metaCall = mockSend.mock.calls.find((c: unknown[]) =>
+      (c[0] as { input: { Key: string } }).input.Key.endsWith('/meta.json')
+    );
+    const meta = JSON.parse((metaCall![0] as { input: { Body: string } }).input.Body);
+    expect(meta).toEqual({ version: 1, deployedBy: 'test-user', handlers: ['call_snowflake'] });
+
+    await expect(readJson(path.join(tmp, 'usage.json'))).resolves.toEqual({
+      appName: 'mf-my-app',
+      deployedBy: 'test-user',
+      apiUsages: { call_snowflake: { snowflake: { query: [{ sql: 'x' }] } } },
+    });
+  });
+
+  it('writes usage.json locally even for apps that had none yet', async () => {
+    await ensureDir(path.join(tmp, 'backend', 'handlers'));
+    await expect(pathExists(path.join(tmp, 'usage.json'))).resolves.toBe(false);
+
+    await deployBackend({
+      appDir: tmp,
+      appName: 'mf-my-app',
+      mfKeyPrefix: 'mf-my-app/1',
+      version: 1,
+      deployedBy: 'test-user',
+      isPreview: false,
+    });
+
+    expect(mockSend).toHaveBeenCalled();
+    await expect(readJson(path.join(tmp, 'usage.json'))).resolves.toEqual({
+      appName: 'mf-my-app',
+      deployedBy: 'test-user',
+      apiUsages: { call_snowflake: {} },
+    });
+  });
+
+  it('merges the local usage.json instead of overwriting it, and writes the merged result back locally', async () => {
+    await ensureDir(path.join(tmp, 'backend', 'handlers'));
+    await writeJson(path.join(tmp, 'usage.json'), { someOtherFeatureField: 'keep-me' });
+
+    await deployBackend({
+      appDir: tmp,
+      appName: 'mf-my-app',
+      mfKeyPrefix: 'mf-my-app/1',
+      version: 1,
+      deployedBy: 'test-user',
+      isPreview: false,
+    });
+
+    await expect(readJson(path.join(tmp, 'usage.json'))).resolves.toEqual({
+      someOtherFeatureField: 'keep-me',
+      appName: 'mf-my-app',
+      deployedBy: 'test-user',
+      apiUsages: { call_snowflake: {} },
+    });
   });
 
   it('tags a handler upload failure as deploy_backend_error, not register_error', async () => {
@@ -130,7 +192,7 @@ describe('deployBackend (preview)', () => {
   });
 
   it('skips upload when the handlers directory holds nothing', async () => {
-    readHandlersMock.mockResolvedValue({ handlers: {}, apiDomains: [] });
+    readHandlersMock.mockResolvedValue({ handlers: {}, apiDomains: [], apiUsages: {} });
 
     await expect(
       deployBackend({
@@ -151,6 +213,7 @@ describe('deployBackend (preview)', () => {
     readHandlersMock.mockResolvedValue({
       handlers: { call_snowflake: 'async function handler(ctx) { return ctx.api.v1.monday.query("x"); }' },
       apiDomains: ['monday'],
+      apiUsages: { call_snowflake: { monday: { query: [{ query: 'x' }] } } },
     });
 
     await expect(
@@ -166,5 +229,7 @@ describe('deployBackend (preview)', () => {
     expect(mockSend).toHaveBeenCalled();
     const keys: string[] = mockSend.mock.calls.map((c: unknown[]) => (c[0] as { input: { Key: string } }).input.Key);
     expect(keys.some(k => k.includes('/MS/'))).toBe(true);
+    expect(keys.some(k => k.endsWith('/usage.json'))).toBe(false);
+    expect(keys.some(k => k.endsWith('/meta.json'))).toBe(true);
   });
 });

package/src/commands/__tests__/backend-validate.test.ts

@@ -1,6 +1,6 @@
 import path from 'node:path';
 import os from 'node:os';
-import { mkdtemp, rm, ensureDir, writeFile } from 'fs-extra';
+import { mkdtemp, rm, ensureDir, writeFile, writeJson, readJson } from 'fs-extra';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { backendValidateCommand } from '../backend';
@@ -14,6 +14,9 @@ vi.mock('../../util/tracker', () => ({
   trackEvent: vi.fn().mockResolvedValue(undefined),
   trackDuration: vi.fn(),
 }));
+vi.mock('../../util/machine-identity', () => ({
+  whoAmI: () => 'test-user',
+}));
 
 const mockSend = vi.fn();
 vi.mock('../../util/s3/client', () => ({
@@ -44,6 +47,7 @@ describe('backendValidateCommand', () => {
   });
 
   it('reports valid handlers and detected integrations without uploading', async () => {
+    await writeJson(path.join(tmp, 'package.json'), { name: 'my-app' });
     const dir = path.join(tmp, 'backend', 'handlers');
     await ensureDir(dir);
     await writeFile(
@@ -58,6 +62,12 @@ describe('backendValidateCommand', () => {
       integrations: ['monday'],
     });
     expect(mockSend).not.toHaveBeenCalled();
+
+    await expect(readJson(path.join(tmp, 'usage.json'))).resolves.toEqual({
+      appName: 'mf-my-app',
+      deployedBy: 'test-user',
+      apiUsages: { list_items: { monday: { query: [{ query: 'query { me { id } }' }] } } },
+    });
   });
 
   it('throws the same validation error deploy would', async () => {

package/src/commands/__tests__/create.test.ts

@@ -95,6 +95,7 @@ describe('create', () => {
     expect(await pathExists(path.join(appDir, '.gitignore'))).toBe(true);
     expect(await pathExists(path.join(appDir, '.claude', 'settings.json'))).toBe(true);
     expect(await pathExists(path.join(appDir, 'CLAUDE.md'))).toBe(true);
+    await expect(readJson(path.join(appDir, 'usage.json'))).resolves.toEqual({});
 
     const pkg = await readJson(path.join(appDir, 'package.json'));
     expect(pkg.name).toBe('demo-app');

package/src/commands/__tests__/llm-migration.test.ts

@@ -0,0 +1,98 @@
+import path from 'node:path';
+import os from 'node:os';
+import { mkdtemp, rm, writeFile } from 'fs-extra';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { llmMigrationCommand } from '../llm-migration';
+import { output } from '../../util/logger';
+import { resolveMigrationsJson } from '../../util/migrations-json';
+
+vi.mock('../../util/logger', () => ({
+  output: vi.fn(),
+}));
+vi.mock('../../util/migrations-json', () => ({
+  resolveMigrationsJson: vi.fn(),
+  LLM_MIGRATION_TYPE: 'llm',
+}));
+
+const outputMock = vi.mocked(output);
+const resolveMock = vi.mocked(resolveMigrationsJson);
+
+describe('llmMigrationCommand', () => {
+  let tmp: string;
+
+  beforeEach(async () => {
+    tmp = await mkdtemp(path.join(os.tmpdir(), 'z2h-llm-migration-'));
+    outputMock.mockClear();
+    resolveMock.mockReset();
+  });
+
+  afterEach(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  it('throws when migrations.json is missing', async () => {
+    resolveMock.mockResolvedValue(null);
+
+    await expect(llmMigrationCommand({ migration: 'any' })).rejects.toThrow(/migrations.json not found/);
+  });
+
+  it('throws when there is no entry, or the entry is not an llm migration', async () => {
+    resolveMock.mockResolvedValue({
+      migrationsJson: { migrations: { 'deterministic-one': { version: '0.1.0', description: 'd', migrate: 'x.js' } } },
+      migrationsDir: tmp,
+    });
+
+    await expect(llmMigrationCommand({ migration: 'missing' })).rejects.toThrow(/no LLM migration named/);
+    await expect(llmMigrationCommand({ migration: 'deterministic-one' })).rejects.toThrow(/no LLM migration named/);
+  });
+
+  it('lists only llm migrations when --migration is omitted', async () => {
+    resolveMock.mockResolvedValue({
+      migrationsJson: {
+        migrations: {
+          'deterministic-one': { version: '0.1.0', description: 'd', migrate: 'x.js' },
+          alpha: { type: 'llm', version: '0.30.0', description: 'first', guide: 'a.md' },
+          beta: { type: 'llm', version: '0.30.0', description: 'second', guide: 'b.md' },
+        },
+      },
+      migrationsDir: tmp,
+    });
+
+    await llmMigrationCommand({});
+
+    expect(outputMock).toHaveBeenCalledWith(expect.stringContaining('alpha\n  first'), {
+      ok: true,
+      migrations: [
+        { name: 'alpha', description: 'first' },
+        { name: 'beta', description: 'second' },
+      ],
+    });
+  });
+
+  it('outputs the guide resolved relative to migrations.json', async () => {
+    await writeFile(path.join(tmp, 'guide.md'), 'guide contents');
+    resolveMock.mockResolvedValue({
+      migrationsJson: {
+        migrations: { on: { type: 'llm', version: '0.30.0', description: 'on', guide: 'guide.md' } },
+      },
+      migrationsDir: tmp,
+    });
+
+    await llmMigrationCommand({ migration: 'on' });
+
+    expect(outputMock).toHaveBeenCalledWith('guide contents', { ok: true, description: 'on', guide: 'guide contents' });
+  });
+
+  it('propagates a missing guide file', async () => {
+    resolveMock.mockResolvedValue({
+      migrationsJson: {
+        migrations: { broken: { type: 'llm', version: '0.30.0', description: 'broken', guide: 'nope.md' } },
+      },
+      migrationsDir: tmp,
+    });
+
+    await expect(llmMigrationCommand({ migration: 'broken' })).rejects.toThrow(/ENOENT/);
+    expect(outputMock).not.toHaveBeenCalled();
+  });
+});