@mondaydotcomorg/z2h-cli 0.31.0 → 0.32.0

package/dist/commands/__tests__/llm-migration.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=llm-migration.test.d.ts.map

package/dist/commands/__tests__/llm-migration.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-migration.test.d.ts","sourceRoot":"","sources":["../../../src/commands/__tests__/llm-migration.test.ts"],"names":[],"mappings":""}

package/dist/commands/llm-migration.d.ts

@@ -0,0 +1,6 @@
+export interface LlmMigrationOptions {
+    /** Omit to list every LLM migration instead of printing one guide. */
+    migration?: string;
+}
+export declare function llmMigrationCommand(opts: LlmMigrationOptions): Promise<void>;
+//# sourceMappingURL=llm-migration.d.ts.map

package/dist/commands/llm-migration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-migration.d.ts","sourceRoot":"","sources":["../../src/commands/llm-migration.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,mBAAmB;IAClC,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAsBlF"}

package/dist/commands/llm-migration.js

@@ -0,0 +1,33 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const path = require('node:path');
+const fs = require('fs-extra');
+const util_logger = require('../util/logger.js');
+const util_migrationsJson = require('../util/migrations-json.js');
+
+const _interopDefault = e => e && e.__esModule ? e : { default: e };
+
+const path__default = /*#__PURE__*/_interopDefault(path);
+
+async function llmMigrationCommand(opts) {
+    const resolved = await util_migrationsJson.resolveMigrationsJson();
+    if (!resolved) {
+        throw new Error('migrations.json not found');
+    }
+    const { migrationsJson, migrationsDir } = resolved;
+    if (!opts.migration) {
+        const migrations = Object.entries(migrationsJson.migrations)
+            .filter(([, entry]) => entry.type === util_migrationsJson.LLM_MIGRATION_TYPE)
+            .map(([name, entry]) => ({ name, description: entry.description }));
+        util_logger.output(migrations.map(m => `${m.name}\n  ${m.description}`).join('\n'), { ok: true, migrations });
+        return;
+    }
+    const entry = migrationsJson.migrations[opts.migration];
+    if (entry?.type !== util_migrationsJson.LLM_MIGRATION_TYPE) {
+        throw new Error(`no LLM migration named "${opts.migration}"`);
+    }
+    const guide = await fs.readFile(path__default.default.resolve(migrationsDir, entry.guide), 'utf8');
+    util_logger.output(guide, { ok: true, description: entry.description, guide });
+}
+
+exports.llmMigrationCommand = llmMigrationCommand;

package/dist/commands/migrate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../src/commands/migrate.ts"],"names":[],"mappings":"AA4BA,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAMnD;AAqBD,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,wBAAsB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAmGjG"}
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../src/commands/migrate.ts"],"names":[],"mappings":"AAiBA,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAMnD;AAqBD,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,wBAAsB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CA4FjG"}

package/dist/commands/migrate.js

@@ -2,20 +2,18 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
 const node_module = require('node:module');
 const path = require('node:path');
-const node_url = require('node:url');
 const fs = require('fs-extra');
 const semver = require('semver');
 const util_logger = require('../util/logger.js');
 const util_workspace = require('../util/workspace.js');
+const util_migrationsJson = require('../util/migrations-json.js');
 
-var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 const _interopDefault = e => e && e.__esModule ? e : { default: e };
 
 const path__default = /*#__PURE__*/_interopDefault(path);
 const semver__default = /*#__PURE__*/_interopDefault(semver);
 
 const STATE_FILE = '.z2h-migrations-state.json';
-// ─── Helpers ───
 // A prerelease sorts BELOW its own release under plain semver ordering, so
 // comparing raw beta versions here would skip migrations the beta introduced.
 function baseVersion(version) {
@@ -55,19 +53,14 @@ async function migrateCommand(cliVersion, opts = {}) {
         return;
     }
     util_logger.info(`migrating workspace from v${lastVersion} → v${targetVersion}...`);
-    // migrations.json is at the package root — two dirs up from dist/migrations/
-    const thisDir = path__default.default.dirname(node_url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('commands/migrate.js', document.baseURI).href))));
-    const migrationsJsonPath = path__default.default.resolve(thisDir, '..', '..', 'migrations.json');
-    if (!(await fs.pathExists(migrationsJsonPath))) {
+    const resolved = await util_migrationsJson.resolveMigrationsJson();
+    if (!resolved) {
         util_logger.warn('migrations.json not found — skipping migrations');
         return;
     }
-    const migrationsJson = (await fs.readJson(migrationsJsonPath));
-    // Filter to pending migrations (version > lastVersion AND <= targetVersion).
-    // CONVENTION: a migration's `version` field must equal the CLI release it
-    // ships with (not the feature branch version). This ensures the `gt` check
-    // always catches a migration on the exact upgrade that introduces it.
+    const { migrationsJson, migrationsDir } = resolved;
     const pending = Object.entries(migrationsJson.migrations)
+        .filter((pair) => pair[1].type !== util_migrationsJson.LLM_MIGRATION_TYPE)
         .filter(([, entry]) => semver__default.default.gt(entry.version, lastVersion) && semver__default.default.lte(entry.version, targetVersion))
         .sort(([, a], [, b]) => semver__default.default.compare(a.version, b.version));
     if (opts.dryRun) {
@@ -93,7 +86,7 @@ async function migrateCommand(cliVersion, opts = {}) {
     for (const [name, entry] of pending) {
         const tree = new FsTree(workspaceHome, false);
         try {
-            const factoryPath = path__default.default.resolve(path__default.default.dirname(migrationsJsonPath), entry.migrate);
+            const factoryPath = path__default.default.resolve(migrationsDir, entry.migrate);
             const mod = require(factoryPath);
             const fn = mod.default || mod;
             fn(tree);

package/dist/esm/commands/__tests__/llm-migration.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=llm-migration.test.d.ts.map

package/dist/esm/commands/__tests__/llm-migration.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-migration.test.d.ts","sourceRoot":"","sources":["../../../../src/commands/__tests__/llm-migration.test.ts"],"names":[],"mappings":""}

package/dist/esm/commands/llm-migration.d.ts

@@ -0,0 +1,6 @@
+export interface LlmMigrationOptions {
+    /** Omit to list every LLM migration instead of printing one guide. */
+    migration?: string;
+}
+export declare function llmMigrationCommand(opts: LlmMigrationOptions): Promise<void>;
+//# sourceMappingURL=llm-migration.d.ts.map

package/dist/esm/commands/llm-migration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-migration.d.ts","sourceRoot":"","sources":["../../../src/commands/llm-migration.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,mBAAmB;IAClC,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAsBlF"}

package/dist/esm/commands/llm-migration.mjs

@@ -0,0 +1,27 @@
+import path from 'node:path';
+import { readFile } from 'fs-extra';
+import { output } from '../util/logger.mjs';
+import { resolveMigrationsJson, LLM_MIGRATION_TYPE } from '../util/migrations-json.mjs';
+
+async function llmMigrationCommand(opts) {
+    const resolved = await resolveMigrationsJson();
+    if (!resolved) {
+        throw new Error('migrations.json not found');
+    }
+    const { migrationsJson, migrationsDir } = resolved;
+    if (!opts.migration) {
+        const migrations = Object.entries(migrationsJson.migrations)
+            .filter(([, entry]) => entry.type === LLM_MIGRATION_TYPE)
+            .map(([name, entry]) => ({ name, description: entry.description }));
+        output(migrations.map(m => `${m.name}\n  ${m.description}`).join('\n'), { ok: true, migrations });
+        return;
+    }
+    const entry = migrationsJson.migrations[opts.migration];
+    if (entry?.type !== LLM_MIGRATION_TYPE) {
+        throw new Error(`no LLM migration named "${opts.migration}"`);
+    }
+    const guide = await readFile(path.resolve(migrationsDir, entry.guide), 'utf8');
+    output(guide, { ok: true, description: entry.description, guide });
+}
+
+export { llmMigrationCommand };

package/dist/esm/commands/migrate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../../src/commands/migrate.ts"],"names":[],"mappings":"AA4BA,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAMnD;AAqBD,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,wBAAsB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAmGjG"}
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../../src/commands/migrate.ts"],"names":[],"mappings":"AAiBA,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAMnD;AAqBD,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,wBAAsB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CA4FjG"}

package/dist/esm/commands/migrate.mjs

@@ -1,13 +1,12 @@
 import { createRequire } from 'node:module';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { pathExists, readJson, writeJson } from 'fs-extra';
 import semver from 'semver';
 import { warn, info, errorLog } from '../util/logger.mjs';
 import { getWorkspaceHome, isZ2hWorkspace, ensureWorkspaceNx, runYarnInstall } from '../util/workspace.mjs';
+import { resolveMigrationsJson, LLM_MIGRATION_TYPE } from '../util/migrations-json.mjs';
 
 const STATE_FILE = '.z2h-migrations-state.json';
-// ─── Helpers ───
 // A prerelease sorts BELOW its own release under plain semver ordering, so
 // comparing raw beta versions here would skip migrations the beta introduced.
 function baseVersion(version) {
@@ -47,19 +46,14 @@ async function migrateCommand(cliVersion, opts = {}) {
         return;
     }
     info(`migrating workspace from v${lastVersion} → v${targetVersion}...`);
-    // migrations.json is at the package root — two dirs up from dist/migrations/
-    const thisDir = path.dirname(fileURLToPath(import.meta.url));
-    const migrationsJsonPath = path.resolve(thisDir, '..', '..', 'migrations.json');
-    if (!(await pathExists(migrationsJsonPath))) {
+    const resolved = await resolveMigrationsJson();
+    if (!resolved) {
         warn('migrations.json not found — skipping migrations');
         return;
     }
-    const migrationsJson = (await readJson(migrationsJsonPath));
-    // Filter to pending migrations (version > lastVersion AND <= targetVersion).
-    // CONVENTION: a migration's `version` field must equal the CLI release it
-    // ships with (not the feature branch version). This ensures the `gt` check
-    // always catches a migration on the exact upgrade that introduces it.
+    const { migrationsJson, migrationsDir } = resolved;
     const pending = Object.entries(migrationsJson.migrations)
+        .filter((pair) => pair[1].type !== LLM_MIGRATION_TYPE)
         .filter(([, entry]) => semver.gt(entry.version, lastVersion) && semver.lte(entry.version, targetVersion))
         .sort(([, a], [, b]) => semver.compare(a.version, b.version));
     if (opts.dryRun) {
@@ -85,7 +79,7 @@ async function migrateCommand(cliVersion, opts = {}) {
     for (const [name, entry] of pending) {
         const tree = new FsTree(workspaceHome, false);
         try {
-            const factoryPath = path.resolve(path.dirname(migrationsJsonPath), entry.migrate);
+            const factoryPath = path.resolve(migrationsDir, entry.migrate);
             const mod = require(factoryPath);
             const fn = mod.default || mod;
             fn(tree);

package/dist/esm/index.mjs

@@ -15,6 +15,7 @@ import { generateCommand } from './commands/generate.mjs';
 import { templatesCommand } from './commands/templates.mjs';
 import { generateZ2HTokenCommand } from './commands/generate-z2h-token.mjs';
 import { migrateCommand } from './commands/migrate.mjs';
+import { llmMigrationCommand } from './commands/llm-migration.mjs';
 import { tagCommand } from './commands/tag.mjs';
 import { editCommand } from './commands/edit.mjs';
 import { backendValidateCommand, backendInvokeCommand } from './commands/backend.mjs';
@@ -187,6 +188,11 @@ async function main() {
         .description('Run pending workspace migrations')
         .option('--dry-run', 'show pending migrations without applying any changes')
         .action(runCommand({}, (opts) => migrateCommand(version, opts)));
+    program
+        .command('llm-migration')
+        .description('List agent-guided (LLM) migrations, or print one migration guide with --migration')
+        .option('--migration <name>', 'name of the LLM migration to print; omit to list all')
+        .action(runCommand({}, (opts) => llmMigrationCommand(opts)));
     program
         .command('doctor')
         .description('Check that all Z2H tools, auth, workspace, and plugins are correctly set up')

package/dist/esm/util/migrations-json.d.ts

@@ -0,0 +1,28 @@
+export interface DeterministicMigrationEntry {
+    type?: never;
+    /** Must equal the CLI release it ships with (not the feature branch version),
+     *  so the `gt` check in migrate.ts always catches it on the exact upgrade that introduces it. */
+    version: string;
+    description: string;
+    migrate: string;
+}
+export declare const LLM_MIGRATION_TYPE: "llm";
+/** Applied by handing `guide`'s contents to the calling agent. The guide owns detection too:
+ *  it tells the agent how to find the old pattern and to report "not relevant" if absent. */
+export interface LlmMigrationEntry {
+    type: typeof LLM_MIGRATION_TYPE;
+    /** Version of the CLI this migration was added at. */
+    version: string;
+    description: string;
+    /** Path (relative to migrations.json) to the markdown guideline for the agent applying this migration. */
+    guide: string;
+}
+export type MigrationEntry = DeterministicMigrationEntry | LlmMigrationEntry;
+export interface MigrationsJson {
+    migrations: Record<string, MigrationEntry>;
+}
+export declare function resolveMigrationsJson(): Promise<{
+    migrationsJson: MigrationsJson;
+    migrationsDir: string;
+} | null>;
+//# sourceMappingURL=migrations-json.d.ts.map

package/dist/esm/util/migrations-json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrations-json.d.ts","sourceRoot":"","sources":["../../../src/util/migrations-json.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,2BAA2B;IAC1C,IAAI,CAAC,EAAE,KAAK,CAAC;IACb;qGACiG;IACjG,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,eAAO,MAAM,kBAAkB,EAAG,KAAc,CAAC;AAEjD;6FAC6F;AAC7F,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,OAAO,kBAAkB,CAAC;IAChC,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,0GAA0G;IAC1G,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,cAAc,GAAG,2BAA2B,GAAG,iBAAiB,CAAC;AAE7E,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CAC5C;AAED,wBAAsB,qBAAqB,IAAI,OAAO,CAAC;IACrD,cAAc,EAAE,cAAc,CAAC;IAC/B,aAAa,EAAE,MAAM,CAAC;CACvB,GAAG,IAAI,CAAC,CASR"}

package/dist/esm/util/migrations-json.mjs

@@ -0,0 +1,17 @@
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { pathExists, readJson } from 'fs-extra';
+
+const LLM_MIGRATION_TYPE = 'llm';
+async function resolveMigrationsJson() {
+    const pkgJsonPath = createRequire(import.meta.url).resolve('@mondaydotcomorg/z2h-cli/package.json');
+    const migrationsDir = path.dirname(pkgJsonPath);
+    const migrationsJsonPath = path.join(migrationsDir, 'migrations.json');
+    if (!(await pathExists(migrationsJsonPath))) {
+        return null;
+    }
+    const migrationsJson = (await readJson(migrationsJsonPath));
+    return { migrationsJson, migrationsDir };
+}
+
+export { LLM_MIGRATION_TYPE, resolveMigrationsJson };

package/dist/index.js

@@ -15,6 +15,7 @@ const commands_generate = require('./commands/generate.js');
 const commands_templates = require('./commands/templates.js');
 const commands_generateZ2hToken = require('./commands/generate-z2h-token.js');
 const commands_migrate = require('./commands/migrate.js');
+const commands_llmMigration = require('./commands/llm-migration.js');
 const commands_tag = require('./commands/tag.js');
 const commands_edit = require('./commands/edit.js');
 const commands_backend = require('./commands/backend.js');
@@ -193,6 +194,11 @@ async function main() {
         .description('Run pending workspace migrations')
         .option('--dry-run', 'show pending migrations without applying any changes')
         .action(util_runCommand.runCommand({}, (opts) => commands_migrate.migrateCommand(version, opts)));
+    program
+        .command('llm-migration')
+        .description('List agent-guided (LLM) migrations, or print one migration guide with --migration')
+        .option('--migration <name>', 'name of the LLM migration to print; omit to list all')
+        .action(util_runCommand.runCommand({}, (opts) => commands_llmMigration.llmMigrationCommand(opts)));
     program
         .command('doctor')
         .description('Check that all Z2H tools, auth, workspace, and plugins are correctly set up')

package/dist/util/migrations-json.d.ts

@@ -0,0 +1,28 @@
+export interface DeterministicMigrationEntry {
+    type?: never;
+    /** Must equal the CLI release it ships with (not the feature branch version),
+     *  so the `gt` check in migrate.ts always catches it on the exact upgrade that introduces it. */
+    version: string;
+    description: string;
+    migrate: string;
+}
+export declare const LLM_MIGRATION_TYPE: "llm";
+/** Applied by handing `guide`'s contents to the calling agent. The guide owns detection too:
+ *  it tells the agent how to find the old pattern and to report "not relevant" if absent. */
+export interface LlmMigrationEntry {
+    type: typeof LLM_MIGRATION_TYPE;
+    /** Version of the CLI this migration was added at. */
+    version: string;
+    description: string;
+    /** Path (relative to migrations.json) to the markdown guideline for the agent applying this migration. */
+    guide: string;
+}
+export type MigrationEntry = DeterministicMigrationEntry | LlmMigrationEntry;
+export interface MigrationsJson {
+    migrations: Record<string, MigrationEntry>;
+}
+export declare function resolveMigrationsJson(): Promise<{
+    migrationsJson: MigrationsJson;
+    migrationsDir: string;
+} | null>;
+//# sourceMappingURL=migrations-json.d.ts.map

package/dist/util/migrations-json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrations-json.d.ts","sourceRoot":"","sources":["../../src/util/migrations-json.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,2BAA2B;IAC1C,IAAI,CAAC,EAAE,KAAK,CAAC;IACb;qGACiG;IACjG,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,eAAO,MAAM,kBAAkB,EAAG,KAAc,CAAC;AAEjD;6FAC6F;AAC7F,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,OAAO,kBAAkB,CAAC;IAChC,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,0GAA0G;IAC1G,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,cAAc,GAAG,2BAA2B,GAAG,iBAAiB,CAAC;AAE7E,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CAC5C;AAED,wBAAsB,qBAAqB,IAAI,OAAO,CAAC;IACrD,cAAc,EAAE,cAAc,CAAC;IAC/B,aAAa,EAAE,MAAM,CAAC;CACvB,GAAG,IAAI,CAAC,CASR"}

package/dist/util/migrations-json.js

@@ -0,0 +1,25 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const node_module = require('node:module');
+const path = require('node:path');
+const fs = require('fs-extra');
+
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+const _interopDefault = e => e && e.__esModule ? e : { default: e };
+
+const path__default = /*#__PURE__*/_interopDefault(path);
+
+const LLM_MIGRATION_TYPE = 'llm';
+async function resolveMigrationsJson() {
+    const pkgJsonPath = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('util/migrations-json.js', document.baseURI).href))).resolve('@mondaydotcomorg/z2h-cli/package.json');
+    const migrationsDir = path__default.default.dirname(pkgJsonPath);
+    const migrationsJsonPath = path__default.default.join(migrationsDir, 'migrations.json');
+    if (!(await fs.pathExists(migrationsJsonPath))) {
+        return null;
+    }
+    const migrationsJson = (await fs.readJson(migrationsJsonPath));
+    return { migrationsJson, migrationsDir };
+}
+
+exports.LLM_MIGRATION_TYPE = LLM_MIGRATION_TYPE;
+exports.resolveMigrationsJson = resolveMigrationsJson;

package/migrations.json

@@ -34,6 +34,12 @@
       "version": "0.19.0",
       "description": "Rewrite html-embed apps' iframe src to go through the host's same-origin /z2h-assets proxy instead of the raw CDN bucket URL",
       "migrate": "./dist/migrations/007-proxy-iframe-src"
+    },
+    "snowflake-service-to-backend-runner": {
+      "type": "llm",
+      "version": "0.29.3",
+      "description": "Migrate off the deprecated direct bigbrain-zth /snowflake/query pattern onto a zth-backend-runner handler (ctx.api.v1.snowflake)",
+      "guide": "./src/migrations-llm/snowflake-service-to-backend-runner.md"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mondaydotcomorg/z2h-cli",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "bin": "./bin/z2h-cli.js",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

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();
+  });
+});

package/src/commands/llm-migration.ts

@@ -0,0 +1,33 @@
+import path from 'node:path';
+import { readFile } from 'fs-extra';
+import { output } from '../util/logger';
+import { resolveMigrationsJson, LLM_MIGRATION_TYPE } from '../util/migrations-json';
+
+export interface LlmMigrationOptions {
+  /** Omit to list every LLM migration instead of printing one guide. */
+  migration?: string;
+}
+
+export async function llmMigrationCommand(opts: LlmMigrationOptions): Promise<void> {
+  const resolved = await resolveMigrationsJson();
+  if (!resolved) {
+    throw new Error('migrations.json not found');
+  }
+  const { migrationsJson, migrationsDir } = resolved;
+
+  if (!opts.migration) {
+    const migrations = Object.entries(migrationsJson.migrations)
+      .filter(([, entry]) => entry.type === LLM_MIGRATION_TYPE)
+      .map(([name, entry]) => ({ name, description: entry.description }));
+    output(migrations.map(m => `${m.name}\n  ${m.description}`).join('\n'), { ok: true, migrations });
+    return;
+  }
+
+  const entry = migrationsJson.migrations[opts.migration];
+  if (entry?.type !== LLM_MIGRATION_TYPE) {
+    throw new Error(`no LLM migration named "${opts.migration}"`);
+  }
+
+  const guide = await readFile(path.resolve(migrationsDir, entry.guide), 'utf8');
+  output(guide, { ok: true, description: entry.description, guide });
+}

package/src/commands/migrate.ts

@@ -1,10 +1,11 @@
 import { createRequire } from 'node:module';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { pathExists, readJson, writeJson } from 'fs-extra';
 import semver from 'semver';
 import { errorLog, info, warn } from '../util/logger';
 import { getWorkspaceHome, isZ2hWorkspace, ensureWorkspaceNx, runYarnInstall } from '../util/workspace';
+import { resolveMigrationsJson, LLM_MIGRATION_TYPE } from '../util/migrations-json';
+import type { DeterministicMigrationEntry } from '../util/migrations-json';
 
 const STATE_FILE = '.z2h-migrations-state.json';
 
@@ -12,18 +13,6 @@ interface MigrationState {
   lastMigratedVersion: string;
 }
 
-interface MigrationEntry {
-  version: string;
-  description: string;
-  migrate: string;
-}
-
-interface MigrationsJson {
-  migrations: Record<string, MigrationEntry>;
-}
-
-// ─── Helpers ───
-
 // A prerelease sorts BELOW its own release under plain semver ordering, so
 // comparing raw beta versions here would skip migrations the beta introduced.
 export function baseVersion(version: string): string {
@@ -75,22 +64,15 @@ export async function migrateCommand(cliVersion: string, opts: MigrateOptions =
 
   info(`migrating workspace from v${lastVersion} → v${targetVersion}...`);
 
-  // migrations.json is at the package root — two dirs up from dist/migrations/
-  const thisDir = path.dirname(fileURLToPath(import.meta.url));
-  const migrationsJsonPath = path.resolve(thisDir, '..', '..', 'migrations.json');
-
-  if (!(await pathExists(migrationsJsonPath))) {
+  const resolved = await resolveMigrationsJson();
+  if (!resolved) {
     warn('migrations.json not found — skipping migrations');
     return;
   }
+  const { migrationsJson, migrationsDir } = resolved;
 
-  const migrationsJson = (await readJson(migrationsJsonPath)) as MigrationsJson;
-
-  // Filter to pending migrations (version > lastVersion AND <= targetVersion).
-  // CONVENTION: a migration's `version` field must equal the CLI release it
-  // ships with (not the feature branch version). This ensures the `gt` check
-  // always catches a migration on the exact upgrade that introduces it.
   const pending = Object.entries(migrationsJson.migrations)
+    .filter((pair): pair is [string, DeterministicMigrationEntry] => pair[1].type !== LLM_MIGRATION_TYPE)
     .filter(([, entry]) => semver.gt(entry.version, lastVersion) && semver.lte(entry.version, targetVersion))
     .sort(([, a], [, b]) => semver.compare(a.version, b.version));
 
@@ -128,7 +110,7 @@ export async function migrateCommand(cliVersion: string, opts: MigrateOptions =
   for (const [name, entry] of pending) {
     const tree = new FsTree(workspaceHome, false);
     try {
-      const factoryPath = path.resolve(path.dirname(migrationsJsonPath), entry.migrate);
+      const factoryPath = path.resolve(migrationsDir, entry.migrate);
       const mod = require(factoryPath);
       const fn = mod.default || mod;
       fn(tree);

package/src/index.ts

@@ -15,6 +15,7 @@ import { generateCommand, GenerateOptions } from './commands/generate';
 import { templatesCommand } from './commands/templates';
 import { generateZ2HTokenCommand } from './commands/generate-z2h-token';
 import { migrateCommand } from './commands/migrate';
+import { llmMigrationCommand } from './commands/llm-migration';
 import { tagCommand } from './commands/tag';
 import { editCommand } from './commands/edit';
 import { backendInvokeCommand, backendValidateCommand } from './commands/backend';
@@ -297,6 +298,12 @@ async function main(): Promise<void> {
     .option('--dry-run', 'show pending migrations without applying any changes')
     .action(runCommand({}, (opts: { dryRun?: boolean }) => migrateCommand(version, opts)));
 
+  program
+    .command('llm-migration')
+    .description('List agent-guided (LLM) migrations, or print one migration guide with --migration')
+    .option('--migration <name>', 'name of the LLM migration to print; omit to list all')
+    .action(runCommand({}, (opts: { migration?: string }) => llmMigrationCommand(opts)));
+
   program
     .command('doctor')
     .description('Check that all Z2H tools, auth, workspace, and plugins are correctly set up')

package/src/migrations-llm/snowflake-service-to-backend-runner.md

@@ -0,0 +1,168 @@
+# Migration: snowflake-service-to-backend-runner
+
+You are migrating one Z2H consumer app off a deprecated data-fetching pattern. Detection is
+your job too: find the old pattern first (see Detect), then rewrite, verify, and check for edit
+collisions before reporting done (see Verify).
+
+## Detect (do this first)
+
+Grep the app's `src/` for the endpoint path:
+
+```bash
+cd "$APP_DIR"
+grep -rn --include='*.ts' --include='*.tsx' --include='*.js' --include='*.jsx' --include='*.html' \
+  '/snowflake/query' src/
+```
+
+- **No matches** → the app does not use the deprecated pattern (or is already migrated). Do
+  nothing and report **not applicable**.
+- **Matches** → the app is in scope. The base URL is built one of three ways; grep for whichever
+  the matched files use so you find every file involved (helper and fetch often live apart):
+  - `getBigBrainAPI(` — React apps, via `bigbrainBaseUrl` (often wrapped in a `getBaseUrl()`)
+  - `window.location.origin` — html-embed apps (`getBigBrainAPI` is unavailable in iframes)
+  - a hardcoded `https://…/snowflake/query` URL
+
+## Read first: `z2h:backend-development`
+
+The target pattern is an app backend handler, and the authoritative guide for writing one is the
+`z2h:backend-development` skill. Read it before touching any file — invoke the skill if you have
+the Skill tool, otherwise read `z2h/skills/backend-development/SKILL.md` from the Z2H plugin
+checkout. This document only tells you *what* to move; that skill tells you *how* handlers must
+be written (file layout, the `ctx` surface, hard rules, how the frontend calls them, error
+handling). Where the two disagree, the skill wins.
+
+Two sections there matter most for this migration:
+
+- **Hard rules for handler code** — one file per operation, a plain global `handler(ctx)` with no
+  `export`/`module.exports`, no imports of any kind, JSON in / JSON out.
+- **The `ctx` API** — the exact `ctx.api.v1.snowflake.*` signature lives in
+  `packages/z2h-cli/handler-api/backend-runner/channels/snowflake-channel/snowflake.channel.ts`.
+  Read it rather than guessing the method name or return shape.
+
+## Idempotency (required)
+
+This migration must be safe to run on an app in any state — untouched, partially migrated by an
+earlier interrupted run, or already fully migrated. Concretely:
+
+- Work from what's in the code now, not from assumptions about the "before" shape. If a handler
+  for a query already exists under `backend/handlers/`, reuse it instead of creating a duplicate.
+  If some call sites already go through `callBackend`, leave them alone.
+- Never leave a half-state behind. Either every step below completes or you report failed — don't
+  report done with the old `runQuery` still in place "for later".
+- Rewrite every call site the Detect step found, not just the first.
+- Done means: **the Detect grep returns nothing.** Re-run it before reporting done.
+
+## Old pattern (remove)
+
+The app fetches Snowflake data directly from the frontend via the generic `bigbrain-zth` endpoint:
+
+```typescript
+// src/queries.ts (or similar) — DEPRECATED
+import { getBigBrainAPI } from '@mondaydotcomorg/trident-runtime';
+
+export async function runQuery(sql: string) {
+  const baseUrl = getBigBrainAPI()?.contextService?.bigbrainBaseUrl;
+  const res = await fetch(`${baseUrl}/snowflake/query`, {
+    method: 'POST',
+    body: JSON.stringify({ sql }),
+  });
+  return res.json();
+}
+```
+
+This pattern is banned for new code (see `z2h:feature-development`'s data-fetching hierarchy) and
+is not available at all inside html-embed iframes.
+
+## New pattern (target)
+
+SQL moves server-side into an app backend handler, called from the frontend through the Z2H SDK.
+
+1. **Create a handler** at `backend/handlers/<name>.js`, following the handler rules in
+   `z2h:backend-development`. Move the SQL that was in `queries.ts` into it, and query through
+   `ctx.api.v1.snowflake`:
+
+   ```javascript
+   // backend/handlers/<name>.js — plain global `handler`, no export, no imports
+   async function handler(ctx) {
+     const rows = await ctx.api.v1.snowflake.query('SELECT ...', undefined, { identifier: '<name>' });
+     return rows;
+   }
+   ```
+
+   Pick `<name>` from what the query returns (e.g. `get_encounter`, `list_boards`) — not `runQuery`
+   or anything generic; one handler per distinct query/shape, matching existing app conventions.
+   The filename (without `.js`) is exactly what the frontend passes to `callBackend`. No scaffold
+   command exists — if the app has no `backend/` folder yet, just create `backend/handlers/`.
+
+   Always pass `identifier` — a short kebab-case string (`[a-z0-9-_]`, max 64 chars), not a
+   number; the handler name is a good default. `z2h:backend-development`'s hard rules require it
+   on every `ctx.api.v1.snowflake.query` call — it's optional in the API signature, but skipping
+   it leaves the query identified by a hash of its SQL, so every later edit to the query makes it
+   a new query in logs and metrics. A stable identifier keeps its history across edits.
+
+2. **Replace every call site.** Wherever the frontend called `runQuery(sql)` (or equivalent),
+   call the handler through the SDK instead (see *Calling the backend from the frontend* in
+   `z2h:backend-development` for error handling with `isBackendError`):
+
+   **React apps:**
+   ```typescript
+   import { createZ2HSDK } from '@mondaydotcomorg/z2h-runtime-sdk';
+
+   const rows = await createZ2HSDK().callBackend('<name>', { /* params, not raw SQL */ });
+   ```
+
+   **html-embed apps (`page.html`):**
+   ```javascript
+   const rows = await window.__z2hSdk__.callBackend('<name>', { /* params */ });
+   ```
+
+3. **Delete the old file** (`src/queries.ts` or equivalent) once nothing imports it, and remove
+   the now-unused `getBigBrainAPI` import from anywhere else in `src/`.
+
+4. **Parameterize, don't template.** If the old `runQuery` took a raw SQL string built from
+   variables (string interpolation), do NOT ship the handler taking raw SQL from the frontend —
+   that's the same trust boundary the old pattern already had, just moved. Have the frontend pass
+   structured params (ids, filters) and build/parameterize the SQL inside the handler.
+
+## Verify
+
+Two checks, in order. Fix any failure before moving on.
+
+1. **Handler validation** — validates every handler under `backend/handlers/` (syntax, isolate
+   rules, known integrations, static-SQL check) without deploying:
+
+   ```bash
+   cd "$APP_DIR"
+   z2h-cli backend validate
+   ```
+
+   Fix any error it reports (minimal fix, re-run).
+
+   Also confirm every `ctx.api.v1.snowflake.query` call you wrote passes `options.identifier` —
+   `z2h-cli backend validate` does not check for this, so grep for it yourself:
+
+   ```bash
+   grep -n 'snowflake.query' backend/handlers/*.js
+   ```
+
+   For each match, check the call includes an `identifier` in its `options` argument. Add one if
+   missing before moving on.
+
+2. **Build** — confirms the frontend typechecks and bundles after the rewrite:
+
+   ```bash
+   z2h-cli deploy --dry-run
+   ```
+
+   Fix any typecheck/lint failure (minimal fix, re-run).
+
+3. **Collision check (required, run last)** — for every file you edited during this migration,
+   re-read its current contents and compare against what you last wrote there. If anything
+   differs from what you expect — the app owner edited that file while you were working —
+   discard your changes for this run and report "failed" with the reason: "The app was edited
+   while the update was in progress, so it wasn't applied — run this update again once things
+   have settled." Do not attempt to reconcile or partially apply; the idempotency contract above
+   means this migration is always safe to retry cleanly from scratch on the next touch.
+
+Do not deploy or commit as part of this migration — that's the normal feature-development flow's
+job, once the person driving this session is ready to ship.

package/src/util/migrations-json.ts

@@ -0,0 +1,45 @@
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { pathExists, readJson } from 'fs-extra';
+
+export interface DeterministicMigrationEntry {
+  type?: never;
+  /** Must equal the CLI release it ships with (not the feature branch version),
+   *  so the `gt` check in migrate.ts always catches it on the exact upgrade that introduces it. */
+  version: string;
+  description: string;
+  migrate: string;
+}
+
+export const LLM_MIGRATION_TYPE = 'llm' as const;
+
+/** Applied by handing `guide`'s contents to the calling agent. The guide owns detection too:
+ *  it tells the agent how to find the old pattern and to report "not relevant" if absent. */
+export interface LlmMigrationEntry {
+  type: typeof LLM_MIGRATION_TYPE;
+  /** Version of the CLI this migration was added at. */
+  version: string;
+  description: string;
+  /** Path (relative to migrations.json) to the markdown guideline for the agent applying this migration. */
+  guide: string;
+}
+
+export type MigrationEntry = DeterministicMigrationEntry | LlmMigrationEntry;
+
+export interface MigrationsJson {
+  migrations: Record<string, MigrationEntry>;
+}
+
+export async function resolveMigrationsJson(): Promise<{
+  migrationsJson: MigrationsJson;
+  migrationsDir: string;
+} | null> {
+  const pkgJsonPath = createRequire(import.meta.url).resolve('@mondaydotcomorg/z2h-cli/package.json');
+  const migrationsDir = path.dirname(pkgJsonPath);
+  const migrationsJsonPath = path.join(migrationsDir, 'migrations.json');
+  if (!(await pathExists(migrationsJsonPath))) {
+    return null;
+  }
+  const migrationsJson = (await readJson(migrationsJsonPath)) as MigrationsJson;
+  return { migrationsJson, migrationsDir };
+}