@mondaydotcomorg/z2h-cli 0.27.1 → 0.29.0

package/src/backend/messages.ts

@@ -0,0 +1,16 @@
+const EXAMPLE = 'async function handler(ctx) { ... }';
+
+export const messages = {
+  mustDefine: (file: string) => `${file} must define a handler — e.g. ${EXAMPLE}`,
+  notAFunction: (file: string) => `${file} declares handler but it is not a function — e.g. ${EXAMPLE}`,
+  mustNotImport: (file: string) =>
+    `${file} must not import other files or packages — handlers are self-contained; reach the outside world through ctx capabilities`,
+  mustNotExportHandler: (file: string) =>
+    `${file} must not export handler — the isolate has no module system; declare it as a plain global, e.g. ${EXAMPLE}`,
+  mustNotExport: (file: string) =>
+    `${file} must not use export — the isolate has no module system; declare handler as a plain global, e.g. ${EXAMPLE}`,
+  moduleOnlySyntax: (file: string, detail: string) =>
+    `${file} uses module-only syntax (${detail}) — handlers run as plain scripts, so top-level await and import.meta are not available`,
+  syntaxError: (file: string, line: number, column: number, detail: string) =>
+    `${file}:${line}:${column}: not valid JavaScript — ${detail}`,
+};

package/src/backend/parse.ts

@@ -0,0 +1,82 @@
+import { parse, type ExportNamedDeclaration, type ModuleDeclaration, type Program, type Statement } from 'acorn';
+import { z } from 'zod';
+import { trackEvent } from '../util/tracker';
+import { exportsHandler } from './handler-declaration';
+import { messages } from './messages';
+
+const acornLocSchema = z.object({ line: z.number(), column: z.number() });
+
+interface AcornSyntaxError extends SyntaxError {
+  loc: { line: number; column: number };
+}
+
+function isAcornSyntaxError(err: unknown): err is AcornSyntaxError {
+  return err instanceof SyntaxError && acornLocSchema.safeParse((err as { loc?: unknown }).loc).success;
+}
+
+type ParseResult = { ok: true; program: Program } | { ok: false; error: AcornSyntaxError };
+
+function tryParse(code: string, sourceType: 'script' | 'module'): ParseResult {
+  try {
+    return { ok: true, program: parse(code, { ecmaVersion: 'latest', sourceType, locations: true }) };
+  } catch (err) {
+    if (isAcornSyntaxError(err)) {
+      return { ok: false, error: err };
+    }
+    throw err;
+  }
+}
+
+/** Acorn appends ` (line:col)` to its messages; we report the position ourselves. */
+const stripPosition = (message: string): string => message.replace(/ \(\d+:\d+\)$/, '');
+
+type ImportLike = (ModuleDeclaration & { type: 'ImportDeclaration' | 'ExportAllDeclaration' }) | ExportNamedDeclaration;
+
+const isImportLike = (node: Statement | ModuleDeclaration): node is ImportLike =>
+  node.type === 'ImportDeclaration' ||
+  node.type === 'ExportAllDeclaration' ||
+  (node.type === 'ExportNamedDeclaration' && node.source != null);
+
+type ExportLike = ModuleDeclaration & { type: 'ExportNamedDeclaration' | 'ExportDefaultDeclaration' };
+
+const isExport = (node: Statement | ModuleDeclaration): node is ExportLike =>
+  node.type === 'ExportNamedDeclaration' || node.type === 'ExportDefaultDeclaration';
+
+/** Reports the failure, then returns the error for the caller to throw. */
+function parseError(message: string): Error {
+  void trackEvent('z2h_cli_handler_parse_error', { error: message });
+  return new Error(message);
+}
+
+/**
+ * The runner compiles handlers with `isolate.compileScript`, i.e. the classic
+ * *script* grammar — so that is the grammar we validate against. `import`/`export`
+ * declarations and top-level `await`/`import.meta` are only legal under the
+ * *module* grammar, so a handler using any of them fails the script parse; we
+ * re-parse it as a module purely to name which of those four things it was,
+ * instead of surfacing V8's bare "Unexpected token 'export'".
+ */
+export function parseOrThrow(file: string, code: string): Program {
+  const asScript = tryParse(code, 'script');
+  if (asScript.ok) {
+    return asScript.program;
+  }
+
+  const asModule = tryParse(code, 'module');
+  if (asModule.ok) {
+    const { body } = asModule.program;
+    if (body.some(exportsHandler)) {
+      throw parseError(messages.mustNotExportHandler(file));
+    }
+    if (body.some(isImportLike)) {
+      throw parseError(messages.mustNotImport(file));
+    }
+    if (body.some(isExport)) {
+      throw parseError(messages.mustNotExport(file));
+    }
+    throw parseError(messages.moduleOnlySyntax(file, stripPosition(asScript.error.message)));
+  }
+
+  const { line, column } = asScript.error.loc;
+  throw parseError(messages.syntaxError(file, line, column, stripPosition(asScript.error.message)));
+}

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/__tests__/create.test.ts

@@ -6,6 +6,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { runYarnInstall } from '../../util/npm/install';
 import { initRepo, defaultS3Remote } from '../../util/git/repo';
 import { prepareShadow } from '../../shadow/prepare';
+import { fetchApp, claimApp } from '../../util/broker/app';
 import { createCommand } from '../create';
 
 // Mock the install helper so `yarn install` (with its broker preflight) doesn't
@@ -28,6 +29,7 @@ vi.mock('../../shadow/prepare', () => ({
 // Mock broker app lookup — no token needed in tests; default to null (app does not exist).
 vi.mock('../../util/broker/app', () => ({
   fetchApp: vi.fn().mockResolvedValue(null),
+  claimApp: vi.fn().mockResolvedValue(undefined),
 }));
 
 async function makeWorkspace(tmp: string): Promise<void> {
@@ -50,6 +52,8 @@ describe('create', () => {
     vi.mocked(initRepo).mockClear();
     vi.mocked(defaultS3Remote).mockClear();
     vi.mocked(prepareShadow).mockClear();
+    vi.mocked(fetchApp).mockReset().mockResolvedValue(null);
+    vi.mocked(claimApp).mockReset().mockResolvedValue(undefined);
   });
 
   afterEach(async () => {
@@ -162,4 +166,46 @@ describe('create', () => {
     await createCommand('gh-app', { remote: 'github', repoUrl: 'https://github.com/acme/gh-app' });
     expect(vi.mocked(initRepo)).toHaveBeenCalledWith(path.join(tmp, 'gh-app'), 'https://github.com/acme/gh-app');
   });
+
+  it('claims the app name with the resolved gitRemote when the name is genuinely free', async () => {
+    await makeWorkspace(tmp);
+    await createCommand('my-app', { remote: 's3' });
+    expect(vi.mocked(claimApp)).toHaveBeenCalledWith(
+      'mf-my-app',
+      's3://prod-use1-bigbrain-zth-mf-assets/mf-my-app/git'
+    );
+  });
+
+  it('throws when the app already has a real release', async () => {
+    await makeWorkspace(tmp);
+    vi.mocked(fetchApp).mockResolvedValue({
+      appName: 'mf-demo-app',
+      version: 1,
+      entry: { version: 1, url: 'https://cdn/demo-app/1/' },
+      deployed: true,
+      deployedBy: 'x@x.com',
+      gitRemote: 's3://bucket/demo-app/git',
+      createdBy: 'x@x.com',
+    });
+    await expect(createCommand('demo-app', { remote: 's3' })).rejects.toThrow(/already exists/);
+    expect(claimApp).not.toHaveBeenCalled();
+  });
+
+  it('proceeds without re-claiming when the app was already claimed but never published', async () => {
+    await makeWorkspace(tmp);
+    vi.mocked(fetchApp).mockResolvedValue({
+      appName: 'mf-demo-app',
+      version: 0,
+      entry: null,
+      deployed: false,
+      deployedBy: 'x@x.com',
+      gitRemote: 's3://bucket/demo-app/git-claim',
+      createdBy: 'x@x.com',
+    });
+
+    await createCommand('demo-app', { remote: 's3' });
+
+    expect(claimApp).not.toHaveBeenCalled();
+    expect(await pathExists(path.join(tmp, 'demo-app', 'package.json'))).toBe(true);
+  });
 });