@mondaydotcomorg/z2h-cli 0.27.0 → 0.28.0

package/src/backend/rules/__tests__/snowflake-static-sql.test.ts

@@ -0,0 +1,175 @@
+import { parse } from 'acorn';
+import { describe, expect, it } from 'vitest';
+import { collectBindings, createPathResolver } from '../../ast';
+import { findHandlerDeclaration, handlerContextParamName } from '../../handler-declaration';
+import { SnowflakeStaticSqlRule } from '../snowflake-static-sql';
+
+const rule = new SnowflakeStaticSqlRule();
+
+const check = (source: string) => {
+  const program = parse(source, { ecmaVersion: 'latest', sourceType: 'script', locations: true });
+  const bindings = collectBindings(program);
+  const declaration = findHandlerDeclaration(program.body);
+  return rule.check({
+    file: 'h.js',
+    program,
+    bindings,
+    paths: createPathResolver(bindings, declaration && handlerContextParamName(declaration)),
+  });
+};
+
+const inHandler = (body: string) => `async function handler(ctx) {\n${body}\n}`;
+
+describe('snowflake/static-sql — accepted', () => {
+  it.each([
+    ['a string literal', 'return ctx.api.v1.snowflake.query("select 1");'],
+    ['a template literal without holes', 'return ctx.api.v1.snowflake.query(`select 1`);'],
+    [
+      'a template literal whose holes are static',
+      'const t = "items"; return ctx.api.v1.snowflake.query(`select * from ${t}`);',
+    ],
+    ['a local const', 'const sql = "select 1"; return ctx.api.v1.snowflake.query(sql);'],
+    [
+      'a var declared before use',
+      'var sql = "select 1"; return ctx.api.v1.snowflake.query(sql, undefined, { identifier: "x" });',
+    ],
+    ['concatenated literals', 'return ctx.api.v1.snowflake.query("select 1" + " from dual");'],
+    [
+      'a variable chain',
+      'const base = "select 1"; const sql = base + " limit 1"; return ctx.api.v1.snowflake.query(sql);',
+    ],
+    [
+      'a conditional between two static queries',
+      'const sql = ctx.input.all ? "select 1" : "select 2"; return ctx.api.v1.snowflake.query(sql);',
+    ],
+    [
+      'a nullish fallback between static queries',
+      'return ctx.api.v1.snowflake.query(A ?? "select 1"); const A = "select 2";',
+    ],
+    [
+      'client values in params and options',
+      'return ctx.api.v1.snowflake.query("select :id", { id: ctx.input.id }, { timeoutMs: ctx.input.t });',
+    ],
+    ['optional chaining on the channel', 'return ctx?.api?.v1?.snowflake?.query("select 1");'],
+  ])('accepts %s', (_label, body) => {
+    expect(check(inHandler(body))).toEqual([]);
+  });
+
+  it('accepts a top-level const shared by several calls', () => {
+    expect(
+      check(
+        `const SQL = "select 1";\n${inHandler(
+          'await ctx.api.v1.snowflake.query(SQL); return ctx.api.v1.snowflake.query(SQL);'
+        )}`
+      )
+    ).toEqual([]);
+  });
+
+  it('ignores other snowflake members and other channels', () => {
+    expect(
+      check(inHandler('ctx.api.v1.snowflake.other(ctx.input.sql); return ctx.api.v1.monday.query(ctx.input.q);'))
+    ).toEqual([]);
+  });
+
+  it('accepts static SQL through a const alias of the channel', () => {
+    expect(
+      check(inHandler('const sf = ctx.api.v1.snowflake; return sf.query("select 1", { id: ctx.input.id });'))
+    ).toEqual([]);
+  });
+});
+
+describe('snowflake/static-sql — channel aliases', () => {
+  it.each([
+    ['a const alias of the channel', 'const sf = ctx.api.v1.snowflake; return sf.query(ctx.input.sql);'],
+    ['a const alias of the api root', 'const api = ctx.api.v1; return api.snowflake.query(ctx.input.sql);'],
+    ['a chain of const aliases', 'const api = ctx.api; const sf = api.v1.snowflake; return sf.query(ctx.input.sql);'],
+    ['a destructured channel', 'const { snowflake } = ctx.api.v1; return snowflake.query(ctx.input.sql);'],
+    ['a renamed destructured channel', 'const { snowflake: sf } = ctx.api.v1; return sf.query(ctx.input.sql);'],
+    ['a nested destructuring', 'const { api: { v1: { snowflake } } } = ctx; return snowflake.query(ctx.input.sql);'],
+    ['a destructured method', 'const { query } = ctx.api.v1.snowflake; return query(ctx.input.sql);'],
+    ['an optional-chained alias', 'const sf = ctx?.api?.v1?.snowflake; return sf.query(ctx.input.sql);'],
+    ['a computed string-literal channel', 'return ctx.api.v1["snowflake"].query(ctx.input.sql);'],
+    ['a computed alias', 'const sf = ctx.api.v1["snowflake"]; return sf.query(ctx.input.sql);'],
+  ])('sees through %s', (_label, body) => {
+    expect(check(inHandler(body))).toHaveLength(1);
+  });
+
+  it('follows a top-level const alias into the handler', () => {
+    expect(check(`const sf = ctx.api.v1.snowflake;\n${inHandler('return sf.query(ctx.input.sql);')}`)).toHaveLength(1);
+  });
+
+  it('sees through a renamed handler parameter', () => {
+    expect(
+      check('async function handler(context) { return context.api.v1.snowflake.query(context.input.sql); }')
+    ).toHaveLength(1);
+  });
+
+  it.each([
+    ['a let alias', 'let sf = ctx.api.v1.snowflake; return sf.query(ctx.input.sql);'],
+    ['a reassigned alias', 'var sf = ctx.api.v1.snowflake; sf = other; return sf.query(ctx.input.sql);'],
+    [
+      'an alias shadowed by a parameter',
+      'const sf = ctx.api.v1.snowflake; const run = (sf) => sf.query(ctx.input.sql); return run(fake);',
+    ],
+    [
+      'an alias declared twice',
+      'const sf = ctx.api.v1.snowflake; { const sf = fake; return sf.query(ctx.input.sql); }',
+    ],
+    ['an alias with a default value', 'const { snowflake: sf = fake } = ctx.api.v1; return sf.query(ctx.input.sql);'],
+  ])('does not follow %s — the binding cannot be pinned', (_label, body) => {
+    expect(check(inHandler(body))).toEqual([]);
+  });
+});
+
+describe('snowflake/static-sql — rejected', () => {
+  it.each([
+    ['ctx.input directly', 'return ctx.api.v1.snowflake.query(ctx.input.sql);'],
+    ['a variable bound to ctx.input', 'const sql = ctx.input.sql; return ctx.api.v1.snowflake.query(sql);'],
+    [
+      'a template literal with a ctx.input hole',
+      'return ctx.api.v1.snowflake.query(`select * from ${ctx.input.table}`);',
+    ],
+    ['concatenation with ctx.input', 'return ctx.api.v1.snowflake.query("select * from " + ctx.input.table);'],
+    [
+      'a conditional with one dynamic branch',
+      'return ctx.api.v1.snowflake.query(ctx.input.x ? "select 1" : ctx.input.sql);',
+    ],
+    ['a call result', 'return ctx.api.v1.snowflake.query(buildSql(ctx.input));'],
+    ['a destructured binding', 'const { sql } = ctx.input; return ctx.api.v1.snowflake.query(sql);'],
+    ['a reassigned variable', 'let sql = "select 1"; sql = ctx.input.sql; return ctx.api.v1.snowflake.query(sql);'],
+    [
+      'a compound-assigned variable',
+      'let sql = "select 1"; sql += ctx.input.where; return ctx.api.v1.snowflake.query(sql);',
+    ],
+    ['a function parameter', 'const run = (sql) => ctx.api.v1.snowflake.query(sql); return run(ctx.input.sql);'],
+    ['an undeclared identifier', 'return ctx.api.v1.snowflake.query(sql);'],
+    ['a spread argument', 'return ctx.api.v1.snowflake.query(...ctx.input.args);'],
+    ['a non-string literal', 'return ctx.api.v1.snowflake.query(1);'],
+    ['no arguments', 'return ctx.api.v1.snowflake.query();'],
+  ])('rejects %s', (_label, body) => {
+    const violations = check(inHandler(body));
+    expect(violations).toHaveLength(1);
+    expect(violations[0]).toMatch(/^h\.js:2: ctx\.api\.v1\.snowflake\.query must receive SQL written in the handler/);
+  });
+
+  it('rejects a variable shadowed by a parameter anywhere in the file', () => {
+    expect(
+      check(
+        `const sql = "select 1";\nfunction run(sql) { return ctx.api.v1.snowflake.query(sql); }\n${inHandler(
+          'return run(ctx.input.sql);'
+        )}`
+      )
+    ).toHaveLength(1);
+  });
+
+  it('does not loop on self-referential bindings', () => {
+    expect(check(inHandler('const a = b; const b = a; return ctx.api.v1.snowflake.query(a);'))).toHaveLength(1);
+  });
+
+  it('reports every offending call with its own line', () => {
+    const violations = check(
+      inHandler('await ctx.api.v1.snowflake.query(ctx.input.a);\nreturn ctx.api.v1.snowflake.query(ctx.input.b);')
+    );
+    expect(violations.map(v => v.slice(0, 6))).toEqual(['h.js:2', 'h.js:3']);
+  });
+});

package/src/backend/rules/index.ts

@@ -0,0 +1,7 @@
+import type { HandlerRule } from './types';
+import { SnowflakeStaticSqlRule } from './snowflake-static-sql';
+
+export type { HandlerRule, RuleContext } from './types';
+
+/** Every rule the validator runs, in order. Add new capability rules here. */
+export const HANDLER_RULES: readonly HandlerRule[] = [new SnowflakeStaticSqlRule()];

package/src/backend/rules/snowflake-static-sql.ts

@@ -0,0 +1,78 @@
+import type { AnyNode } from 'acorn';
+import { simple as walkSimple } from 'acorn-walk';
+import { type Bindings, lineOf } from '../ast';
+import type { HandlerRule, RuleContext } from './types';
+
+const SNOWFLAKE_QUERY = 'ctx.api.v1.snowflake.query';
+
+const message = (file: string, line: number | undefined) =>
+  `${file}${line ? `:${line}` : ''}: ${SNOWFLAKE_QUERY} must receive SQL written in the handler — a string literal, ` +
+  `or a variable bound to one. Client-supplied values go through params (\`:name\` bindings) and options, never into the SQL text.`;
+
+/**
+ * True when every possible value of `node` is text authored in this file:
+ * string literals, templates whose holes are themselves static, `+`
+ * concatenation, either branch of a conditional, and identifiers that resolve
+ * (within the file) to such values. Anything reaching outside the file —
+ * `ctx.input`, calls, member reads, destructuring — is not static.
+ */
+function isStaticSql(node: AnyNode | null | undefined, bindings: Bindings, resolving: ReadonlySet<string>): boolean {
+  if (!node) {
+    return false;
+  }
+  const staticChild = (child: AnyNode | null | undefined) => isStaticSql(child, bindings, resolving);
+  switch (node.type) {
+    case 'Literal':
+      return typeof node.value === 'string';
+    case 'TemplateLiteral':
+      return node.expressions.every(staticChild);
+    case 'BinaryExpression':
+      return node.operator === '+' && staticChild(node.left) && staticChild(node.right);
+    case 'ConditionalExpression':
+      return staticChild(node.consequent) && staticChild(node.alternate);
+    case 'LogicalExpression':
+      return staticChild(node.left) && staticChild(node.right);
+    case 'Identifier': {
+      const { name } = node;
+      if (bindings.unpinnable.has(name) || resolving.has(name)) {
+        return false;
+      }
+      const decls = bindings.declarations.get(name);
+      if (!decls || decls.length === 0) {
+        return false;
+      }
+      const next = new Set(resolving).add(name);
+      return decls.every(d => d.path?.length === 0 && isStaticSql(d.init, bindings, next));
+    }
+    default:
+      return false;
+  }
+}
+
+/**
+ * `ctx.api.v1.snowflake.query(sql, params?, options?)` — the SQL text must live
+ * in the handler. The frontend chooses *which* handler to call and supplies
+ * `params` / `options`; it never ships SQL. Binding placeholders (`:name`) are
+ * how client values reach the query.
+ *
+ * The call is matched through `const` aliases of the channel
+ * (`const sf = ctx.api.v1.snowflake; sf.query(…)`), see `PathResolver`.
+ */
+export class SnowflakeStaticSqlRule implements HandlerRule {
+  readonly name = 'snowflake/static-sql';
+
+  check({ file, program, bindings, paths }: RuleContext): string[] {
+    const violations: string[] = [];
+    walkSimple(program, {
+      CallExpression(node) {
+        if (paths.pathOf(node.callee) !== SNOWFLAKE_QUERY) {
+          return;
+        }
+        if (!isStaticSql(node.arguments[0], bindings, new Set())) {
+          violations.push(message(file, lineOf(node)));
+        }
+      },
+    });
+    return violations;
+  }
+}

package/src/backend/rules/types.ts

@@ -0,0 +1,30 @@
+import type { Program } from 'acorn';
+import type { Bindings, PathResolver } from '../ast';
+
+export interface RuleContext {
+  /** Handler file name, used to prefix messages. */
+  file: string;
+  /** Parsed with `locations: true`, so rules can point at a line. */
+  program: Program;
+  /** Every variable binding in the file — see `collectBindings`. */
+  bindings: Bindings;
+  /** Resolves member chains through `const` aliases — see `createPathResolver`. */
+  paths: PathResolver;
+}
+
+/**
+ * A capability-specific check that runs once the handler is structurally valid
+ * (parses as a script, defines `handler`, imports nothing).
+ *
+ * Rules return human-readable violations rather than throwing so the validator
+ * can report every problem in one pass — agent-generated handlers are fixed in
+ * a loop, and one round-trip per violation is slow.
+ *
+ * Implement as a class (see `SnowflakeStaticSqlRule`) and add an instance to
+ * `HANDLER_RULES` in `./index.ts` — keeps every rule the same shape to read.
+ */
+export interface HandlerRule {
+  /** Stable identifier, e.g. `snowflake/static-sql`. */
+  name: string;
+  check(ctx: RuleContext): string[];
+}

package/src/backend/validate.ts

@@ -0,0 +1,73 @@
+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 { HANDLER_RULES } from './rules';
+
+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[];
+}
+
+/**
+ * Validates a handler's source before upload: real parsing (via acorn) catches
+ * syntax errors at build time instead of an opaque failure inside the isolate.
+ * Handlers run with no module system and no bundler — `handler` must be a plain
+ * top-level global, and imports/requires (which would resolve to nothing at
+ * runtime) are rejected.
+ *
+ * Once the handler is structurally sound, capability-specific rules from
+ * `./rules` run and every violation is reported at once.
+ *
+ * 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);
+
+  const bindings = collectBindings(program);
+
+  walkSimple(program, {
+    CallExpression(node) {
+      if (node.callee.type === 'Identifier' && node.callee.name === 'require') {
+        throw new Error(messages.mustNotImport(file));
+      }
+    },
+    ImportExpression() {
+      throw new Error(messages.mustNotImport(file));
+    },
+  });
+
+  const declaration = findHandlerDeclaration(program.body);
+  if (!declaration) {
+    throw new Error(messages.mustDefine(file));
+  }
+  if (declaration.kind === 'variable' && (!declaration.init || NEVER_A_FUNCTION.has(declaration.init.type))) {
+    throw new Error(messages.notAFunction(file));
+  }
+
+  const paths = createPathResolver(bindings, handlerContextParamName(declaration));
+  const apiDomains = collectApiDomains(program, paths);
+
+  const violations = HANDLER_RULES.flatMap(rule => rule.check({ file, program, bindings, paths }));
+  if (violations.length > 0) {
+    throw new Error(violations.join('\n'));
+  }
+
+  for (const domain of apiDomains) {
+    if (!KNOWN_API_DOMAINS.includes(domain)) {
+      warn(`${file}: ctx.api.v1.${domain} is not a known capability (available: ${KNOWN_API_DOMAINS.join(', ')})`);
+    }
+  }
+
+  return { apiDomains: [...apiDomains].sort() };
+}

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

@@ -23,7 +23,7 @@ const readHandlersMock = vi.mocked(readHandlers);
 // handlers directory is known to exist.
 beforeEach(() => {
   readHandlersMock.mockReset();
-  readHandlersMock.mockResolvedValue({ handlers: { call_snowflake: '// code' } });
+  readHandlersMock.mockResolvedValue({ handlers: { call_snowflake: '// code' }, apiDomains: [] });
 });
 
 describe('hasHandlers', () => {
@@ -60,7 +60,7 @@ describe('deployBackend (live)', () => {
   });
 
   it('skips upload when the handlers directory holds nothing', async () => {
-    readHandlersMock.mockResolvedValue({ handlers: {} });
+    readHandlersMock.mockResolvedValue({ handlers: {}, apiDomains: [] });
 
     await expect(
       deployBackend({
@@ -80,6 +80,7 @@ describe('deployBackend (live)', () => {
     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"); }' },
+      apiDomains: ['snowflake'],
     });
 
     // snowflake is always-on — not a declared integration
@@ -129,7 +130,7 @@ describe('deployBackend (preview)', () => {
   });
 
   it('skips upload when the handlers directory holds nothing', async () => {
-    readHandlersMock.mockResolvedValue({ handlers: {} });
+    readHandlersMock.mockResolvedValue({ handlers: {}, apiDomains: [] });
 
     await expect(
       deployBackend({
@@ -149,6 +150,7 @@ describe('deployBackend (preview)', () => {
     await writeFile(path.join(tmp, 'backend', 'handlers', 'call_snowflake.ts'), '// placeholder');
     readHandlersMock.mockResolvedValue({
       handlers: { call_snowflake: 'async function handler(ctx) { return ctx.api.v1.monday.query("x"); }' },
+      apiDomains: ['monday'],
     });
 
     await expect(

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

@@ -0,0 +1,71 @@
+import path from 'node:path';
+import os from 'node:os';
+import { mkdtemp, rm, ensureDir, writeFile } from 'fs-extra';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { backendValidateCommand } from '../backend';
+import { output } from '../../util/logger';
+
+vi.mock('../../util/logger', () => ({
+  info: vi.fn(),
+  output: vi.fn(),
+}));
+vi.mock('../../util/tracker', () => ({
+  trackEvent: vi.fn().mockResolvedValue(undefined),
+  trackDuration: vi.fn(),
+}));
+
+const mockSend = vi.fn();
+vi.mock('../../util/s3/client', () => ({
+  getS3Client: vi.fn(() => ({ send: mockSend })),
+}));
+
+const outputMock = vi.mocked(output);
+
+describe('backendValidateCommand', () => {
+  let tmp: string;
+
+  beforeEach(async () => {
+    tmp = await mkdtemp(path.join(os.tmpdir(), 'z2h-backend-validate-'));
+    outputMock.mockClear();
+    mockSend.mockClear();
+  });
+
+  afterEach(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  it('reports nothing to validate when there is no handlers directory', async () => {
+    await backendValidateCommand(tmp);
+    expect(outputMock).toHaveBeenCalledWith(expect.stringContaining('nothing to validate'), {
+      handlers: [],
+      integrations: [],
+    });
+  });
+
+  it('reports valid handlers and detected integrations without uploading', async () => {
+    const dir = path.join(tmp, 'backend', 'handlers');
+    await ensureDir(dir);
+    await writeFile(
+      path.join(dir, 'list_items.js'),
+      'async function handler(ctx) { return ctx.api.v1.monday.query("query { me { id } }"); }'
+    );
+
+    await backendValidateCommand(tmp);
+
+    expect(outputMock).toHaveBeenCalledWith(expect.stringContaining('1 handler(s) valid: list_items'), {
+      handlers: ['list_items'],
+      integrations: ['monday'],
+    });
+    expect(mockSend).not.toHaveBeenCalled();
+  });
+
+  it('throws the same validation error deploy would', async () => {
+    const dir = path.join(tmp, 'backend', 'handlers');
+    await ensureDir(dir);
+    await writeFile(path.join(dir, 'bad.js'), 'export async function handler(ctx) { return 1; }');
+
+    await expect(backendValidateCommand(tmp)).rejects.toThrow(/must not (use )?export/);
+    expect(outputMock).not.toHaveBeenCalled();
+  });
+});

package/src/commands/backend.ts

@@ -4,7 +4,7 @@ import { PutObjectCommand } from '@aws-sdk/client-s3';
 import { info, output } from '../util/logger';
 import { mfAppName, getCwdAppName } from '../util/app-name';
 import { readHandlers } from '../backend/handlers';
-import { detectIntegrationsFromHandlers } from '../backend/detect-integrations';
+import { detectIntegrations } from '../backend/detect-integrations';
 import { getS3Client } from '../util/s3/client';
 import { BUCKET_WRITE_NAME } from '../constants';
 import { invokeBackend } from '../backend/client';
@@ -44,8 +44,8 @@ async function readDetectAndUpload(
     return [];
   }
   info(`reading backend handlers ${logLabel}`);
-  const { handlers } = await readHandlers(appDir);
-  const integrations = detectIntegrationsFromHandlers(handlers);
+  const { handlers, apiDomains } = await readHandlers(appDir);
+  const integrations = detectIntegrations(apiDomains);
   if (Object.keys(handlers).length === 0) {
     return integrations;
   }
@@ -94,6 +94,26 @@ export async function deployBackend(opts: {
   }
 }
 
+/**
+ * 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.
+ */
+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 names = Object.keys(handlers).sort();
+  const integrations = detectIntegrations(apiDomains);
+  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,
+    integrations,
+  });
+}
+
 export async function backendInvokeCommand(handlerName: string, opts: { input?: string } = {}): Promise<void> {
   const appName = currentAppName();
   let input: unknown = null;

package/src/constants.ts

@@ -70,12 +70,11 @@ export const APP_NAME_PATTERN = /^[a-z][a-z0-9-]{1,49}$/;
 
 export const PREVIEW_APP_NAME_PREFIX = 'zth-preview-';
 
-// ─────────── Declared (OAuth-gated) backend integrations ─────
-// Closed set the CLI detects from handler sources and the broker validates on
-// register/update. Always-on channels (`db`, `llm`, `snowflake`) are not listed —
-// the runner builds those regardless. Shared via `@mondaydotcomorg/z2h-cli/constants`.
-export const DECLARED_INTEGRATIONS = ['monday'] as const;
-export type DeclaredIntegration = (typeof DECLARED_INTEGRATIONS)[number];
+// ─────────── Backend channels — re-exported from shared-utils ─────
+// Single source of truth lives in `@mondaydotcomorg/z2h-shared-utils` so the
+// CLI detector and broker stay in lockstep. Kept here for existing
+// `@mondaydotcomorg/z2h-cli/constants` consumers.
+export { ALWAYS_ON_CHANNELS, DECLARED_INTEGRATIONS, type DeclaredIntegration } from '@mondaydotcomorg/z2h-shared-utils';
 
 // ─────────── Broker origin + npm registry (shared §3 contract) ─────
 // The bigbrain-zth broker fronts both the STS credential route and the npm

package/src/index.ts

@@ -17,7 +17,7 @@ import { generateZ2HTokenCommand } from './commands/generate-z2h-token';
 import { migrateCommand } from './commands/migrate';
 import { tagCommand } from './commands/tag';
 import { editCommand } from './commands/edit';
-import { backendInvokeCommand } from './commands/backend';
+import { backendInvokeCommand, backendValidateCommand } from './commands/backend';
 import { doctorCommand } from './commands/doctor';
 import { errorLog, fail, getOutputMode, setOutputMode } from './util/logger';
 import { runCommand } from './util/run-command';
@@ -267,7 +267,14 @@ async function main(): Promise<void> {
 
   const backend = program
     .command('backend')
-    .description("Inspect the app's backend: invoke a deployed handler by name");
+    .description("Inspect the app's backend: validate handler sources or invoke a deployed handler by name");
+
+  backend
+    .command('validate')
+    .description(
+      'Validate backend/handlers/*.js exactly as deploy would (syntax, isolate rules, integrations) without uploading'
+    )
+    .action(runCommand({ data: cwdApp }, () => backendValidateCommand()));
 
   backend
     .command('invoke <handlerName>')