@mondaydotcomorg/z2h-cli 0.30.0 → 0.32.0

package/dist/esm/commands/backend.mjs

@@ -1,8 +1,10 @@
 import path from 'node:path';
 import { existsSync } from 'node:fs';
+import { readJson, writeJson } from 'fs-extra';
 import { PutObjectCommand } from '@aws-sdk/client-s3';
 import { output, info } from '../util/logger.mjs';
-import { getCwdAppName, mfAppName } from '../util/app-name.mjs';
+import { mfAppName, getCwdAppName } from '../util/app-name.mjs';
+import { whoAmI } from '../util/machine-identity.mjs';
 import { readHandlers } from '../backend/handlers.mjs';
 import { detectIntegrations } from '../backend/detect-integrations.mjs';
 import { getS3Client } from '../util/s3/client.mjs';
@@ -17,30 +19,41 @@ function currentAppName() {
     }
     return mfAppName(raw);
 }
-/**
- * True if the app ships an app-level backend — a `backend/handlers/` directory.
- * Callers gate on this so the deploy path is explicit about whether a backend is in
- * play.
- */
 function hasHandlers(appDir) {
     return existsSync(path.join(appDir, 'backend', 'handlers'));
 }
+/** Other features may add top-level fields, so writes below merge into this copy instead of replacing it. */
+async function readExistingUsage(appDir) {
+    try {
+        return (await readJson(path.join(appDir, 'usage.json')));
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            return {};
+        }
+        throw err;
+    }
+}
+/** Keeps the app's git-tracked `usage.json` current with every handler parse (validate or deploy). */
+async function writeUsageJson(appDir, patch) {
+    const existing = await readExistingUsage(appDir);
+    await writeJson(path.join(appDir, 'usage.json'), { ...existing, ...patch }, { spaces: 2 });
+}
 /**
- * Read handlers, detect declared integrations, and upload to `prefix` when there
- * is anything to upload. Returns `[]` when there is no `backend/handlers/` dir
- * (or it is empty of sources) so callers can always pass the result to
- * `registerOrUpdateApp` without a separate gate.
+ * Returns `[]` when there is no `backend/handlers/` dir (or it is empty of sources)
+ * so callers can always pass the result to `registerOrUpdateApp` without a separate gate.
  */
-async function readDetectAndUpload(appDir, prefix, version, deployedBy, logLabel) {
+async function readDetectAndUpload(appDir, prefix, appName, version, deployedBy, logLabel) {
     if (!hasHandlers(appDir)) {
         return [];
     }
     info(`reading backend handlers ${logLabel}`);
-    const { handlers, apiDomains } = await readHandlers(appDir);
+    const { handlers, apiDomains, apiUsages } = await readHandlers(appDir);
     const integrations = detectIntegrations(apiDomains);
     if (Object.keys(handlers).length === 0) {
         return integrations;
     }
+    await writeUsageJson(appDir, { appName, deployedBy, apiUsages });
     const s3 = getS3Client();
     const meta = JSON.stringify({ version, deployedBy, handlers: Object.keys(handlers) });
     const put = (key, body, contentType) => s3.send(new PutObjectCommand({ Bucket: BUCKET_WRITE_NAME, Key: key, Body: body, ContentType: contentType }));
@@ -55,11 +68,6 @@ async function readDetectAndUpload(appDir, prefix, version, deployedBy, logLabel
  * from their sources. Each `.js` handler is uploaded as its own flat file — no
  * compilation, no bundling, no npm deps.
  *
- * Live and preview differ only in where the handlers land, so that is the only
- * thing `isPreview` switches:
- * - live:    `<appName>/backend-<version>` — the app's immutable per-version slot.
- * - preview: `<mfKeyPrefix without /MF>/MS` — beside the preview's `/MF` frontend.
- *
  * Integration sync note: the returned set is re-derived from the CURRENT backend
  * sources on every deploy, and the platform set is reconciled to exactly match
  * it (there is no stored declaration to fall back on). A deploy therefore always
@@ -71,25 +79,26 @@ async function deployBackend(opts) {
     const prefix = isPreview ? `${mfKeyPrefix.replace(/\/MF$/, '')}/MS` : `${appName}/backend-${version}`;
     const logLabel = isPreview ? 'for preview' : `for "${appName}"`;
     try {
-        return await readDetectAndUpload(appDir, prefix, version, deployedBy, logLabel);
+        return await readDetectAndUpload(appDir, prefix, appName, version, deployedBy, logLabel);
     }
     catch (err) {
         throw tagDeployError('deploy_backend_error', err);
     }
 }
 /**
- * Run the same handler validation deploy runs (syntax, isolate constraints,
- * handler rules, integration detection) against the working tree — without
- * uploading anything. Throws on the first invalid handler.
+ * Runs the same checks deploy does against the working tree, refreshing the
+ * local `usage.json` — no upload to S3. Throws on the first invalid handler.
  */
 async function backendValidateCommand(appDir = process.cwd()) {
     if (!hasHandlers(appDir)) {
         output('[z2h-cli] no backend/handlers/ directory — nothing to validate', { handlers: [], integrations: [] });
         return;
     }
-    const { handlers, apiDomains } = await readHandlers(appDir);
+    const { handlers, apiDomains, apiUsages } = await readHandlers(appDir);
     const names = Object.keys(handlers).sort();
     const integrations = detectIntegrations(apiDomains);
+    const { name } = (await readJson(path.join(appDir, 'package.json')));
+    await writeUsageJson(appDir, { appName: name ? mfAppName(name) : undefined, deployedBy: whoAmI(), apiUsages });
     const list = (xs) => (xs.length ? xs.join(', ') : 'none');
     output(`[z2h-cli] ${names.length} handler(s) valid: ${list(names)}\n[z2h-cli] integrations: ${list(integrations)}`, {
         handlers: names,

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

@@ -1 +1 @@
-{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../../src/commands/create.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,YAAY,EAAE,KAAK,UAAU,EAA2C,MAAM,4BAA4B,CAAC;AAKpH,OAAO,EAAE,YAAY,EAAE,KAAK,UAAU,EAAE,CAAC;AAEzC,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAwBD,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CA6F5F"}
+{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../../src/commands/create.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,YAAY,EAAE,KAAK,UAAU,EAA2C,MAAM,4BAA4B,CAAC;AAKpH,OAAO,EAAE,YAAY,EAAE,KAAK,UAAU,EAAE,CAAC;AAEzC,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAwBD,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CA8F5F"}

package/dist/esm/commands/create.mjs

@@ -85,6 +85,7 @@ async function createCommand(appName, opts = {}) {
     await copy(path.join(appTemplatesDir, 'gitignore'), path.join(appDir, '.gitignore'));
     await copy(path.join(appTemplatesDir, 'claude-settings.json'), path.join(appDir, '.claude', 'settings.json'));
     await copy(path.join(appTemplatesDir, 'CLAUDE.md'), path.join(appDir, 'CLAUDE.md'));
+    await copy(path.join(appTemplatesDir, 'usage.json'), path.join(appDir, 'usage.json'));
     // html-embed: also copy the source HTML.
     if (template === 'html-embed' && opts.htmlFile) {
         await copy(opts.htmlFile, path.join(appDir, 'src', 'page.html'));

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

@@ -1 +1 @@
-{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../../src/commands/deploy.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAE,KAAK,UAAU,EAA2C,MAAM,4BAA4B,CAAC;AAkBtG,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IAIrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAWD,wBAAsB,aAAa,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAyB3E"}
+{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../../src/commands/deploy.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,KAAK,UAAU,EAA2C,MAAM,4BAA4B,CAAC;AAatG,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IAIrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAWD,wBAAsB,aAAa,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAyB3E"}

package/dist/esm/commands/deploy.mjs

@@ -1,4 +1,3 @@
-import os from 'node:os';
 import path from 'node:path';
 import { readJson, ensureDir, copy } from 'fs-extra';
 import { info, output, getOutputMode, warn } from '../util/logger.mjs';
@@ -13,7 +12,7 @@ import { getRemoteUrl, initRepo, guardCleanTree, pullAndResolve, pushToRemote }
 import { resolveGitEnv } from '../util/git/git-env.mjs';
 import { validateRemoteOptions, resolveRemoteUrl } from '../util/git/remote-options.mjs';
 import { setupS3Client } from '../util/s3/client.mjs';
-import { getMachineAppName } from '../util/machine-identity.mjs';
+import { whoAmI } from '../util/machine-identity.mjs';
 import { fetchApp, registerOrUpdateApp } from '../util/broker/app.mjs';
 import { openInBrowser } from '../util/open-browser.mjs';
 import { resolvePortAndMetadata } from '../shadow/prepare.mjs';
@@ -22,10 +21,6 @@ import { deployBackend } from './backend.mjs';
 import { buildCommand } from './build.mjs';
 import { promptForTags } from './tag.mjs';
 
-/** Who is publishing this version — the machine identity, else the OS user. */
-function whoDeployed() {
-    return getMachineAppName() ?? os.userInfo().username;
-}
 // Should be run from the consumer app directory — uses process.cwd() to locate it.
 async function deployCommand(opts = {}) {
     const paths = resolveConsumerPaths(process.cwd());
@@ -68,7 +63,7 @@ async function buildAndStamp(opts) {
     else {
         ({ assetManifest } = await buildCommand({ publicUrl: opts.publicUrl }));
     }
-    const deployedBy = whoDeployed();
+    const deployedBy = whoAmI();
     return {
         ...assetManifest,
         version: opts.nextVersion,
@@ -94,7 +89,7 @@ async function uploadAndRegister(opts) {
         appName,
         mfKeyPrefix: keyPrefix,
         version: nextVersion,
-        deployedBy: whoDeployed(),
+        deployedBy: whoAmI(),
         isPreview,
     });
     await registerOrUpdateApp({

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/templates/app/usage.mjs

@@ -0,0 +1,5 @@
+const usage = {
+	
+};
+
+export { usage as default };

package/dist/esm/util/machine-identity.d.ts

@@ -1,9 +1,8 @@
 /**
  * Returns the machine app name when running as a service (e.g. agent-runner).
  * Available when the process is a monday.com microservice with `APP_NAME` set
- * by the platform runtime.
- *
- * Returns `undefined` for interactive human users (fallback to os.userInfo).
+ * by the platform runtime. Returns `undefined` for interactive human users.
  */
 export declare function getMachineAppName(): string | undefined;
+export declare function whoAmI(): string;
 //# sourceMappingURL=machine-identity.d.ts.map

package/dist/esm/util/machine-identity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"machine-identity.d.ts","sourceRoot":"","sources":["../../../src/util/machine-identity.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,GAAG,SAAS,CAEtD"}
+{"version":3,"file":"machine-identity.d.ts","sourceRoot":"","sources":["../../../src/util/machine-identity.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,GAAG,SAAS,CAEtD;AAED,wBAAgB,MAAM,IAAI,MAAM,CAE/B"}

package/dist/esm/util/machine-identity.mjs

@@ -1,12 +1,15 @@
+import os from 'node:os';
+
 /**
  * Returns the machine app name when running as a service (e.g. agent-runner).
  * Available when the process is a monday.com microservice with `APP_NAME` set
- * by the platform runtime.
- *
- * Returns `undefined` for interactive human users (fallback to os.userInfo).
+ * by the platform runtime. Returns `undefined` for interactive human users.
  */
 function getMachineAppName() {
     return process.env.APP_NAME || undefined;
 }
+function whoAmI() {
+    return getMachineAppName() ?? os.userInfo().username;
+}
 
-export { getMachineAppName };
+export { getMachineAppName, whoAmI };

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/templates/app/usage.js

@@ -0,0 +1,7 @@
+Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toStringTag]: { value: 'Module' } });
+
+const usage = {
+	
+};
+
+exports.default = usage;

package/dist/util/machine-identity.d.ts

@@ -1,9 +1,8 @@
 /**
  * Returns the machine app name when running as a service (e.g. agent-runner).
  * Available when the process is a monday.com microservice with `APP_NAME` set
- * by the platform runtime.
- *
- * Returns `undefined` for interactive human users (fallback to os.userInfo).
+ * by the platform runtime. Returns `undefined` for interactive human users.
  */
 export declare function getMachineAppName(): string | undefined;
+export declare function whoAmI(): string;
 //# sourceMappingURL=machine-identity.d.ts.map

package/dist/util/machine-identity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"machine-identity.d.ts","sourceRoot":"","sources":["../../src/util/machine-identity.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,GAAG,SAAS,CAEtD"}
+{"version":3,"file":"machine-identity.d.ts","sourceRoot":"","sources":["../../src/util/machine-identity.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,GAAG,SAAS,CAEtD;AAED,wBAAgB,MAAM,IAAI,MAAM,CAE/B"}

package/dist/util/machine-identity.js

@@ -1,14 +1,22 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
+const os = require('node:os');
+
+const _interopDefault = e => e && e.__esModule ? e : { default: e };
+
+const os__default = /*#__PURE__*/_interopDefault(os);
+
 /**
  * Returns the machine app name when running as a service (e.g. agent-runner).
  * Available when the process is a monday.com microservice with `APP_NAME` set
- * by the platform runtime.
- *
- * Returns `undefined` for interactive human users (fallback to os.userInfo).
+ * by the platform runtime. Returns `undefined` for interactive human users.
  */
 function getMachineAppName() {
     return process.env.APP_NAME || undefined;
 }
+function whoAmI() {
+    return getMachineAppName() ?? os__default.default.userInfo().username;
+}
 
 exports.getMachineAppName = getMachineAppName;
+exports.whoAmI = whoAmI;

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/handler-api/signatures.json

@@ -0,0 +1,26 @@
+{
+  "db.delete": [
+    "key"
+  ],
+  "db.get": [
+    "key"
+  ],
+  "db.list": [],
+  "db.put": [
+    "key",
+    "value"
+  ],
+  "llm.complete": [
+    "modelId",
+    "messages"
+  ],
+  "monday.query": [
+    "query",
+    "variables"
+  ],
+  "snowflake.query": [
+    "sql",
+    "params",
+    "options"
+  ]
+}

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.30.0",
+  "version": "0.32.0",
   "bin": "./bin/z2h-cli.js",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/src/backend/__tests__/handlers.test.ts

@@ -5,6 +5,9 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { readHandlers } from '../handlers';
 
+vi.mock('../parser/api-signatures', () => ({
+  loadApiSignatures: () => ({ 'monday.query': ['query', 'variables'] }),
+}));
 vi.mock('../../util/tracker', () => ({
   trackEvent: vi.fn().mockResolvedValue(undefined),
   trackDuration: vi.fn(),
@@ -28,14 +31,14 @@ describe('readHandlers — discovery', () => {
   it('returns empty handlers when backend/handlers does not exist', async () => {
     const dir = await mkdtemp(path.join(os.tmpdir(), 'z2h-empty-'));
     try {
-      await expect(readHandlers(dir)).resolves.toEqual({ handlers: {}, apiDomains: [] });
+      await expect(readHandlers(dir)).resolves.toEqual({ handlers: {}, apiDomains: [], apiUsages: {} });
     } finally {
       await rm(dir, { recursive: true, force: true });
     }
   });
 
   it('returns empty handlers when the directory is empty', async () => {
-    await expect(readHandlers(appDir)).resolves.toEqual({ handlers: {}, apiDomains: [] });
+    await expect(readHandlers(appDir)).resolves.toEqual({ handlers: {}, apiDomains: [], apiUsages: {} });
   });
 
   it('uses the filename (without .js) as the handler name', async () => {
@@ -69,6 +72,14 @@ describe('readHandlers — output contract', () => {
     const { apiDomains } = await readHandlers(appDir);
     expect(apiDomains).toEqual(['db', 'monday']);
   });
+
+  it('attaches per-handler apiUsages keyed by handler name', async () => {
+    await writeHandler('a.js', 'async function handler(ctx) { return ctx.api.v1.monday.query("x"); }');
+    await writeHandler('c.js', 'async function handler(ctx) { return ctx.input; }');
+    const { apiUsages } = await readHandlers(appDir);
+    expect(apiUsages.a).toEqual({ monday: { query: [{ query: 'x' }] } });
+    expect(apiUsages.c).toEqual({});
+  });
 });
 
 // Per-shape validation rules are covered in validate.test.ts; here we only prove