@mondaydotcomorg/z2h-cli 0.30.0 → 0.32.0

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/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/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/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 };
+}

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"}