@mondaydotcomorg/z2h-cli 0.30.0 → 0.31.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/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/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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mondaydotcomorg/z2h-cli",
-  "version": "0.30.0",
+  "version": "0.31.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

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

@@ -3,6 +3,12 @@ import { warn } from '../../util/logger';
 import { validateHandlerSource } from '../validate';
 
 vi.mock('../../util/logger');
+vi.mock('../parser/api-signatures', () => ({
+  loadApiSignatures: () => ({
+    'snowflake.query': ['sql', 'params', 'options'],
+    'monday.query': ['query', 'variables'],
+  }),
+}));
 vi.mock('../../util/tracker', () => ({
   trackEvent: vi.fn().mockResolvedValue(undefined),
   trackDuration: vi.fn(),
@@ -203,3 +209,51 @@ describe('validateHandlerSource — ctx.api.v1 domains', () => {
     expect(warnMock).toHaveBeenCalledTimes(1);
   });
 });
+
+describe('validateHandlerSource — apiUsages (per-call domain/method/args)', () => {
+  it('records each call keyed by parameter name — static strings resolved, dynamic object values kept as source text', () => {
+    const { apiUsages } = validate(
+      'async function handler(ctx) { return ctx.api.v1.snowflake.query("SELECT 1", { userId: ctx.caller.id }); }'
+    );
+    expect(apiUsages).toEqual({ snowflake: { query: [{ sql: 'SELECT 1', params: { userId: 'ctx.caller.id' } }] } });
+  });
+
+  it('keeps multiple calls to the same method as separate entries', () => {
+    const { apiUsages } = validate(
+      'async function handler(ctx) { await ctx.api.v1.snowflake.query("SELECT 1"); return ctx.api.v1.snowflake.query("SELECT 2"); }'
+    );
+    expect(apiUsages.snowflake.query).toEqual([{ sql: 'SELECT 1' }, { sql: 'SELECT 2' }]);
+  });
+
+  it('falls back to source text for a dynamic argument and a dynamic array element', () => {
+    const { apiUsages } = validate(
+      'async function handler(ctx) { const q = ctx.input.q; return ctx.api.v1.monday.query(q, [ctx.input.id]); }'
+    );
+    expect(apiUsages.monday.query).toEqual([{ query: 'ctx.input.q', variables: ['ctx.input.id'] }]);
+  });
+
+  it('resolves a same-scope const alias back to its ctx.api.v1 chain', () => {
+    const { apiUsages } = validate(
+      'async function handler(ctx) { const d = ctx.api.v1.snowflake; return d.query("SELECT 1"); }'
+    );
+    expect(apiUsages).toEqual({ snowflake: { query: [{ sql: 'SELECT 1' }] } });
+  });
+
+  it('returns {} for a handler with no ctx.api.v1 calls', () => {
+    expect(validate('async function handler(ctx) { return ctx.input; }').apiUsages).toEqual({});
+  });
+
+  it('tracks a call reached through a computed string-literal member access', () => {
+    const { apiUsages } = validate(
+      'async function handler(ctx) { return ctx.api.v1.snowflake[\'query\']("SELECT 1"); }'
+    );
+    expect(apiUsages).toEqual({ snowflake: { query: [{ sql: 'SELECT 1' }] } });
+  });
+
+  it('does not track a call reached through a dynamic member access', () => {
+    const { apiUsages } = validate(
+      'async function handler(ctx) { const m = "query"; return ctx.api.v1.snowflake[m]("SELECT 1"); }'
+    );
+    expect(apiUsages).toEqual({});
+  });
+});

package/src/backend/handlers.ts

@@ -1,7 +1,7 @@
 import path from 'node:path';
 import { readdir, readFile } from 'node:fs/promises';
 import { pathExists } from 'fs-extra';
-import { validateHandlerSource } from './validate';
+import { validateHandlerSource, type ApiUsage } from './validate';
 
 const HANDLERS_DIR = path.join('backend', 'handlers');
 
@@ -10,6 +10,8 @@ export interface ReadHandlersResult {
   handlers: Record<string, string>;
   /** Every `ctx.api.v1.<domain>` any handler touches, sorted and unique. */
   apiDomains: string[];
+  /** handler name → per-call `ctx.api.v1` usage, for `usage.json`. */
+  apiUsages: Record<string, ApiUsage>;
 }
 
 /**
@@ -20,7 +22,7 @@ export interface ReadHandlersResult {
 export async function readHandlers(consumerDir: string): Promise<ReadHandlersResult> {
   const handlersDir = path.join(consumerDir, HANDLERS_DIR);
   if (!(await pathExists(handlersDir))) {
-    return { handlers: {}, apiDomains: [] };
+    return { handlers: {}, apiDomains: [], apiUsages: {} };
   }
 
   const entries = await readdir(handlersDir);
@@ -28,13 +30,15 @@ export async function readHandlers(consumerDir: string): Promise<ReadHandlersRes
   if (tsFiles.length > 0) {
     throw new Error(`TypeScript handlers are not yet supported (${tsFiles.join(', ')}). Compile to .js first.`);
   }
-  const jsFiles = entries.filter(f => f.endsWith('.js'));
+  // Sorted so usage.json's key order is deterministic across machines, not readdir()'s.
+  const jsFiles = entries.filter(f => f.endsWith('.js')).sort();
   if (jsFiles.length === 0) {
-    return { handlers: {}, apiDomains: [] };
+    return { handlers: {}, apiDomains: [], apiUsages: {} };
   }
 
   const handlers: Record<string, string> = {};
   const apiDomains = new Set<string>();
+  const apiUsages: Record<string, ApiUsage> = {};
   for (const file of jsFiles) {
     const handlerName = path.parse(file).name;
     const source = await readFile(path.join(handlersDir, file), 'utf8');
@@ -42,6 +46,7 @@ export async function readHandlers(consumerDir: string): Promise<ReadHandlersRes
     const validation = validateHandlerSource(file, source);
     validation.apiDomains.forEach(d => apiDomains.add(d));
     handlers[handlerName] = source;
+    apiUsages[handlerName] = validation.apiUsages;
   }
-  return { handlers, apiDomains: [...apiDomains].sort() };
+  return { handlers, apiDomains: [...apiDomains].sort(), apiUsages };
 }