@mondaydotcomorg/z2h-cli 0.27.1 → 0.29.0

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

@@ -78,6 +78,7 @@ describe('edit', () => {
       version: 3,
       gitRemote: S3_REMOTE,
       entry: {},
+      deployed: true,
       deployedBy: 'u@x.com',
       createdBy: 'u@x.com',
     });
@@ -100,6 +101,7 @@ describe('edit', () => {
       version: 3,
       gitRemote: S3_REMOTE,
       entry: {},
+      deployed: true,
       deployedBy: 'u@x.com',
       createdBy: 'u@x.com',
     });
@@ -117,6 +119,7 @@ describe('edit', () => {
       version: 3,
       gitRemote: S3_REMOTE,
       entry: {},
+      deployed: true,
       deployedBy: 'u@x.com',
       createdBy: 'u@x.com',
     });
@@ -134,6 +137,7 @@ describe('edit', () => {
       version: 3,
       gitRemote: GITHUB_REMOTE,
       entry: {},
+      deployed: true,
       deployedBy: 'u@x.com',
       createdBy: 'u@x.com',
     });
@@ -151,6 +155,7 @@ describe('edit', () => {
       version: 3,
       gitRemote: S3_REMOTE,
       entry: {},
+      deployed: true,
       deployedBy: 'u@x.com',
       createdBy: 'u@x.com',
     });
@@ -172,6 +177,7 @@ describe('edit', () => {
       version: 3,
       gitRemote: S3_REMOTE,
       entry: {},
+      deployed: true,
       deployedBy: 'u@x.com',
       createdBy: 'u@x.com',
     });

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

@@ -7,7 +7,7 @@ import { getTemplatesDir, renderTemplate, APP_TEMPLATES, type AppTemplate } from
 import { runYarnInstall } from '../util/npm/install';
 import { initRepo } from '../util/git/repo';
 import { REMOTE_TYPES, type RemoteType, validateRemoteOptions, resolveRemoteUrl } from '../util/git/remote-options';
-import { fetchApp } from '../util/broker/app';
+import { fetchApp, claimApp } from '../util/broker/app';
 import { mfAppName, validateAppName } from '../util/app-name';
 import { prepareShadow } from '../shadow/prepare';
 
@@ -69,12 +69,22 @@ export async function createCommand(appName: string, opts: CreateOptions = {}):
     throw new Error(`${appDir} is non-empty. Pick a different name or wipe it first.`);
   }
 
-  // Check the broker — fail fast if the app is already registered.
+  // Check the broker — fail fast if the app already has a real release.
+  // A claimed-but-unpublished stub (`entry: null`) is fine to proceed past:
+  // either it's this same name being re-created after a local wipe (we'd only
+  // see it at all if we still have access to it), or it genuinely doesn't
+  // exist yet and we claim it below.
   const existing = await fetchApp(mfAppName(appName));
-  if (existing) {
+  if (existing?.deployed) {
     throw new Error(`An app named "${appName}" already exists in the Z2H registry. Pick a different name.`);
   }
 
+  const gitRemote = resolveRemoteUrl(opts.remote as RemoteType, appName, opts.repoUrl);
+
+  if (!existing) {
+    await claimApp(mfAppName(appName), gitRemote);
+  }
+
   // Compute substitutions.
   const vars = {
     __APP_NAME__: appName,
@@ -105,7 +115,6 @@ export async function createCommand(appName: string, opts: CreateOptions = {}):
   }
 
   info(`initializing git repo for ${appName}...`);
-  const gitRemote = resolveRemoteUrl(opts.remote as RemoteType, appName, opts.repoUrl);
   await initRepo(appDir, gitRemote);
 
   info(`installing dependencies for ${appName}...`);

package/src/commands/generate.ts

@@ -157,8 +157,9 @@ export async function generateCommand(appName: string, opts: GenerateOptions): P
     throw new Error(`${appDir} is non-empty. Pick a different name or wipe it first.`);
   }
 
+  // A claimed-but-unpublished stub (`entry: null`) is fine to proceed past — only a real release blocks generate.
   const existing = await fetchApp(mfAppName(appName));
-  if (existing) {
+  if (existing?.deployed) {
     throw new Error(`An app named "${appName}" already exists in the Z2H registry. Pick a different name.`);
   }
 

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>')

package/src/util/broker/__tests__/app.test.ts

@@ -1,9 +1,12 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { registerOrUpdateApp } from '../app';
+import { registerOrUpdateApp, claimApp } from '../app';
 import * as promptVisibility from '../../prompt-visibility';
 import { DeployError } from '../../errors';
+import * as authStore from '../../auth/auth-store';
 import type { ManifestEntry } from '../../manifest';
 
+vi.spyOn(authStore, 'readZthAuth').mockResolvedValue({ token: 'jwt-stub' });
+
 vi.mock('../../prompt-visibility', () => ({
   resolveAppVisibility: vi.fn(),
 }));
@@ -105,3 +108,28 @@ describe('registerOrUpdateApp', () => {
     expect((err as DeployError).reason).toBe('register_error');
   });
 });
+
+describe('claimApp', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it('posts the app name and gitRemote to the claim endpoint', async () => {
+    const fetchMock = mockFetchOnce(204);
+
+    await claimApp('mf-my-app', 's3://bucket/mf-my-app/git');
+
+    const [calledUrl, init] = fetchMock.mock.calls[0] as [string, RequestInit];
+    expect(calledUrl).toContain('/z2h-cli/apps/claim');
+    expect(JSON.parse(init.body as string)).toEqual({
+      appName: 'mf-my-app',
+      gitRemote: 's3://bucket/mf-my-app/git',
+    });
+  });
+
+  it('propagates a claim failure', async () => {
+    mockFetchOnce(409);
+
+    await expect(claimApp('mf-my-app', 's3://bucket/mf-my-app/git')).rejects.toThrow(/Claiming app name failed/);
+  });
+});

package/src/util/broker/app.ts

@@ -8,7 +8,10 @@ import type { ManifestEntry } from '../manifest';
 export interface AppInfo {
   appName: string;
   version: number;
-  entry: Record<string, unknown>;
+  /** Null for a claimed-but-unpublished app — reserved via `create`, never deployed yet. */
+  entry: Record<string, unknown> | null;
+  /** True once a real release has landed (`entry` is set) — false for a claimed-but-unpublished stub. */
+  deployed: boolean;
   deployedBy: string;
   gitRemote: string;
   createdBy: string;
@@ -16,7 +19,7 @@ export interface AppInfo {
 
 /**
  * Fetches a single app's current state from the broker.
- * Returns null if the app has never been deployed (404).
+ * Returns null if the app has never even been claimed (404).
  */
 export async function fetchApp(appName: string): Promise<AppInfo | null> {
   const { token } = await readZthAuth();
@@ -42,6 +45,25 @@ export async function fetchApp(appName: string): Promise<AppInfo | null> {
   return res.json() as Promise<AppInfo>;
 }
 
+/**
+ * Reserves an app name (+ owner grant) before any deploy — called once from
+ * `create`. Idempotent from the caller's perspective: `create` only calls this
+ * when {@link fetchApp} found nothing at all, so a 409 here means someone else
+ * claimed the exact same name in the gap between the two calls.
+ */
+export async function claimApp(appName: string, gitRemote: string): Promise<void> {
+  const { token } = await readZthAuth();
+  const res = await fetch(`${brokerBaseUrl()}/z2h-cli/apps/claim`, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', ...routingHeaders() },
+    body: JSON.stringify({ appName, gitRemote }),
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Claiming app name failed (${res.status}): ${text.slice(0, 1024)}`);
+  }
+}
+
 async function registerApp(
   appName: string,
   token: string,