@mondaydotcomorg/z2h-cli 0.30.0 → 0.31.0

package/src/backend/parser/types.ts

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

package/src/backend/parser/utils.ts

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

package/src/backend/validate.ts

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

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

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

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

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

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

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

package/src/commands/backend.ts

@@ -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 { info, output } from '../util/logger';
 import { mfAppName, getCwdAppName } from '../util/app-name';
+import { whoAmI } from '../util/machine-identity';
 import { readHandlers } from '../backend/handlers';
 import { detectIntegrations } from '../backend/detect-integrations';
 import { getS3Client } from '../util/s3/client';
@@ -18,24 +20,36 @@ function currentAppName(): string {
   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.
- */
 export function hasHandlers(appDir: string): boolean {
   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: string): Promise<Record<string, unknown>> {
+  try {
+    return (await readJson(path.join(appDir, 'usage.json'))) as Record<string, unknown>;
+  } catch (err) {
+    if ((err as { code?: string }).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: string, patch: Record<string, unknown>): Promise<void> {
+  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: string,
   prefix: string,
+  appName: string,
   version: number,
   deployedBy: string,
   logLabel: string
@@ -44,11 +58,12 @@ async function readDetectAndUpload(
     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: string, body: string, contentType: string) =>
@@ -65,11 +80,6 @@ async function readDetectAndUpload(
  * 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
@@ -88,25 +98,26 @@ export 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.
  */
 export async function backendValidateCommand(appDir: string = process.cwd()): Promise<void> {
   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'))) as { name?: string };
+  await writeUsageJson(appDir, { appName: name ? mfAppName(name) : undefined, deployedBy: whoAmI(), apiUsages });
   const list = (xs: string[]) => (xs.length ? xs.join(', ') : 'none');
   output(`[z2h-cli] ${names.length} handler(s) valid: ${list(names)}\n[z2h-cli] integrations: ${list(integrations)}`, {
     handlers: names,

package/src/commands/create.ts

@@ -108,6 +108,7 @@ export async function createCommand(appName: string, opts: CreateOptions = {}):
   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) {

package/src/commands/deploy.ts

@@ -1,4 +1,3 @@
-import os from 'node:os';
 import path from 'node:path';
 import { copy, ensureDir, readJson } from 'fs-extra';
 import { info, warn, output, getOutputMode } from '../util/logger';
@@ -19,7 +18,7 @@ import { getRemoteUrl, guardCleanTree, pullAndResolve, pushToRemote, initRepo }
 import { resolveGitEnv } from '../util/git/git-env';
 import { type RemoteType, validateRemoteOptions, resolveRemoteUrl } from '../util/git/remote-options';
 import { setupS3Client } from '../util/s3/client';
-import { getMachineAppName } from '../util/machine-identity';
+import { whoAmI } from '../util/machine-identity';
 import { fetchApp, registerOrUpdateApp } from '../util/broker/app';
 import { openInBrowser } from '../util/open-browser';
 import { resolvePortAndMetadata } from '../shadow/prepare';
@@ -30,11 +29,6 @@ import { promptForTags } from './tag';
 import type { ConsumerPaths, DeployFailureReason } from '../types';
 import type { ManifestEntry, AssetManifestFile } from '../util/manifest';
 
-/** Who is publishing this version — the machine identity, else the OS user. */
-function whoDeployed(): string {
-  return getMachineAppName() ?? os.userInfo().username;
-}
-
 export interface DeployOptions {
   dryRun?: boolean;
   remote?: RemoteType;
@@ -106,7 +100,7 @@ async function buildAndStamp(opts: {
   } else {
     ({ assetManifest } = await buildCommand({ publicUrl: opts.publicUrl }));
   }
-  const deployedBy = whoDeployed();
+  const deployedBy = whoAmI();
 
   return {
     ...assetManifest,
@@ -148,7 +142,7 @@ async function uploadAndRegister(opts: {
     appName,
     mfKeyPrefix: keyPrefix,
     version: nextVersion,
-    deployedBy: whoDeployed(),
+    deployedBy: whoAmI(),
     isPreview,
   });
 

package/src/templates/app/usage.json

@@ -0,0 +1 @@
+{}

package/src/util/machine-identity.ts

@@ -1,10 +1,14 @@
+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.
  */
 export function getMachineAppName(): string | undefined {
   return process.env.APP_NAME || undefined;
 }
+
+export function whoAmI(): string {
+  return getMachineAppName() ?? os.userInfo().username;
+}

package/dist/backend/__tests__/ast.test.d.ts.map

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

package/dist/backend/__tests__/parse.test.d.ts.map

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

package/dist/backend/ast.d.ts

@@ -1,39 +0,0 @@
-import type { AnyNode, Expression, Pattern, Program, VariableDeclaration } from 'acorn';
-export interface Declaration {
-    kind: VariableDeclaration['kind'];
-    init: Expression | null | undefined;
-    /**
-     * Property path from `init` to this binding: `[]` for `const x = init`,
-     * `['a', 'b']` for `const { a: { b: x } } = init`, `undefined` when the value
-     * is not a plain property read (array/rest/default patterns).
-     */
-    path: string[] | undefined;
-}
-export interface Bindings {
-    /** Every `var|let|const <name> = …` in the file, by name. */
-    declarations: Map<string, Declaration[]>;
-    /** Names whose value cannot be pinned: reassigned, updated, or bound as parameters. */
-    unpinnable: Set<string>;
-}
-/** Every identifier a binding pattern introduces (`{ a, b: [c] } = …` → a, c). */
-export declare const patternNames: (pattern: Pattern) => string[];
-export declare function collectBindings(program: Program): Bindings;
-export interface PathResolver {
-    /**
-     * Dotted path of a member chain, following `const` aliases back to their
-     * source: with `const sf = ctx.api.v1.snowflake`, `sf.query` resolves to
-     * `ctx.api.v1.snowflake.query`. Destructuring counts too
-     * (`const { snowflake: sf } = ctx.api.v1`). `undefined` if any link is dynamic.
-     *
-     * Only single, never-reassigned, never-shadowed `const` bindings are followed —
-     * anything else is left as written, so a `let` alias or a parameter of the same
-     * name is never mistaken for the channel. The handler's first parameter is
-     * treated as `ctx` even when renamed (`handler(context)` → `context.api.v1.db`
-     * resolves as `ctx.api.v1.db`).
-     */
-    pathOf(node: AnyNode): string | undefined;
-}
-export declare function createPathResolver(bindings: Bindings, contextParam?: string): PathResolver;
-/** Every `ctx.api.v1.<domain>` the program touches (known or not), through `paths`. */
-export declare function collectApiDomains(program: Program, paths: PathResolver): Set<string>;
-//# sourceMappingURL=ast.d.ts.map

package/dist/backend/ast.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"ast.d.ts","sourceRoot":"","sources":["../../src/backend/ast.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE,mBAAmB,EAAE,MAAM,OAAO,CAAC;AAKxF,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAClC,IAAI,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,CAAC;IACpC;;;;OAIG;IACH,IAAI,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;CAC5B;AAED,MAAM,WAAW,QAAQ;IACvB,6DAA6D;IAC7D,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC;IACzC,uFAAuF;IACvF,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACzB;AA8CD,kFAAkF;AAClF,eAAO,MAAM,YAAY,GAAI,SAAS,OAAO,KAAG,MAAM,EAAmD,CAAC;AAE1G,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,QAAQ,CA4C1D;AA2BD,MAAM,WAAW,YAAY;IAC3B;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;CAC3C;AAED,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,YAAY,CA6B1F;AAED,uFAAuF;AACvF,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,YAAY,GAAG,GAAG,CAAC,MAAM,CAAC,CAWpF"}