@mondaydotcomorg/z2h-cli 0.10.1 → 0.11.1

package/src/commands/create.ts

@@ -4,15 +4,15 @@ import { ensureDir, pathExists, readdir, writeFile, copy } from 'fs-extra';
 import { info, warn, output, setOutputMode } from '../util/logger';
 import { assertWorkspace } from '../util/workspace';
 import { getTemplatesDir, renderTemplate, APP_TEMPLATES, type AppTemplate } from '../util/templates';
-import { readManifest } from '../util/manifest';
-import { mfAppName } from '../util/app-name';
 import { APP_NAME_PATTERN } from '../constants';
 import { runYarnInstall } from '../util/npm/install';
-import { initRepo, defaultS3Remote } from '../util/git/repo';
-import { buildCommand } from './build';
+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 { mfAppName } from '../util/app-name';
+import { prepareShadow } from '../shadow/prepare';
 
-export const REMOTE_TYPES = ['s3', 'github'] as const;
-export type RemoteType = (typeof REMOTE_TYPES)[number];
+export { REMOTE_TYPES, type RemoteType };
 
 export interface CreateOptions {
   template?: string;
@@ -71,15 +71,7 @@ export async function createCommand(appName: string, opts: CreateOptions = {}):
   }
 
   // Validate --remote up front before any file I/O.
-  if (!opts.remote) {
-    throw new Error('--remote is required. Use --remote=s3 (shared storage) or --remote=github (your GitHub repo).');
-  }
-  if (!(REMOTE_TYPES as readonly string[]).includes(opts.remote)) {
-    throw new Error(`Unknown remote "${opts.remote}". Use ${REMOTE_TYPES.join(' or ')}.`);
-  }
-  if (opts.remote === 'github' && !opts.repoUrl) {
-    throw new Error('--repo-url is required when using --remote=github.');
-  }
+  validateRemoteOptions(opts, true);
 
   // Resolve template.
   // `--html-file` implies `--template html-embed` unless the user already picked one.
@@ -98,9 +90,9 @@ export async function createCommand(appName: string, opts: CreateOptions = {}):
     throw new Error(`${appDir} is non-empty. Pick a different name or wipe it first.`);
   }
 
-  // Check for manifest collision (network call — after all local checks).
-  const manifest = await readManifest();
-  if (manifest[mfAppName(appName)]) {
+  // Check the broker — fail fast if the app is already registered.
+  const existing = await fetchApp(mfAppName(appName));
+  if (existing) {
     throw new Error(`An app named "${appName}" already exists in the Z2H registry. Pick a different name.`);
   }
 
@@ -134,27 +126,17 @@ export async function createCommand(appName: string, opts: CreateOptions = {}):
   }
 
   info(`initializing git repo for ${appName}...`);
-  let gitRemote: string;
-  if (opts.remote === 's3') {
-    gitRemote = defaultS3Remote(appName);
-  } else {
-    gitRemote = opts.repoUrl as string;
-  }
+  const gitRemote = resolveRemoteUrl(opts.remote as RemoteType, appName, opts.repoUrl);
   await initRepo(appDir, gitRemote);
 
   info(`installing dependencies for ${appName}...`);
   await runYarnInstall({ cwd: workspace });
 
-  // build/dev/deploy all locate the consumer via process.cwd() — chdir before calling them.
-  const prevCwd = process.cwd();
+  // Best-effort workspace wiring (.zth shadow). Non-fatal — dev/deploy re-run it.
   try {
-    info(`pre-building ${appName}`);
-    process.chdir(appDir);
-    await buildCommand();
-  } catch {
-    warn(`pre-build failed. No worries — it will run again when needed.`);
-  } finally {
-    process.chdir(prevCwd);
+    await prepareShadow(appDir);
+  } catch (err) {
+    warn(`prepare shadow failed: ${(err as Error).message} — it will run again when needed.`);
   }
 
   output(`[z2h-cli] app ready at ${appDir}`, {

package/src/commands/deploy.ts

@@ -1,28 +1,27 @@
 import path from 'node:path';
 import os from 'node:os';
+import { createInterface } from 'node:readline';
 import { pathExists, readJson } from 'fs-extra';
 import { info, output, setOutputMode, warn } from '../util/logger';
 import { resolveConsumerPaths } from '../shadow/paths';
-import {
-  nextVersion,
-  readManifest,
-  upsertEntry,
-  writeManifest,
-  type AssetManifestFile,
-  type ManifestEntry,
-} from '../util/manifest';
+import { type AssetManifestFile, type ManifestEntry } from '../util/manifest';
 import { uploadDir } from '../util/s3/upload';
-import { BUCKET_WRITE_NAME, BUCKET_READ_DNS_URL, brokerBaseUrl } from '../constants';
-import { setupS3Client } from '../util/s3/client';
+import { BUCKET_WRITE_NAME, BUCKET_READ_DNS_URL, brokerBaseUrl, routingHeaders } from '../constants';
+import { brokerCredentialProvider, fetchDeployVersion } from '../util/auth/broker-credential-provider';
 import { readZthAuth } from '../util/auth/auth-store';
 import { cleanAppName, mfAppName } from '../util/app-name';
 import { getMachineAppName } from '../util/machine-identity';
-import { getRemoteUrl } from '../util/git/repo';
+import { getRemoteUrl, guardCleanTree, pullAndResolve, pushToRemote, initRepo } from '../util/git/repo';
+import { resolveGitEnv } from '../util/git/git-env';
+import { type RemoteType, validateRemoteOptions, resolveRemoteUrl } from '../util/git/remote-options';
+import { setupS3Client } from '../util/s3/client';
 import { buildCommand } from './build';
 
 export interface DeployOptions {
   dryRun?: boolean;
   json?: boolean;
+  remote?: RemoteType;
+  repoUrl?: string;
 }
 
 // Should be run from the consumer app directory — uses process.cwd() to locate it.
@@ -41,12 +40,51 @@ export async function deployCommand(opts: DeployOptions = {}): Promise<void> {
   // Validate the user's deploy token is on disk before doing any expensive
   // work. Throws Z2hAuthMissingError with a remediation hint if not.
   const { token } = await readZthAuth();
-  setupS3Client({ appName });
+
+  let gitRemote = await getRemoteUrl(process.cwd());
+
+  if (gitRemote) {
+    if (opts.remote || opts.repoUrl) {
+      throw new Error(
+        `--remote and --repo-url only apply on the first deploy of an app with no git remote.\n` +
+          `This app already tracks source at: ${gitRemote}`
+      );
+    }
+  } else {
+    if (!opts.remote) {
+      throw new Error(
+        `This app has no git remote. On first deploy, tell Z2H how to track source:\n\n` +
+          `  z2h-cli deploy --remote s3 (default)\n` +
+          `      Stores source history in S3 alongside your app. No extra setup.\n\n` +
+          `  z2h-cli deploy --remote github --repo-url https://github.com/org/repo.git\n` +
+          `      Uses an existing GitHub repo (must exist before deploying).`
+      );
+    }
+    validateRemoteOptions(opts);
+    // Pass the raw consumer name (not the mf-prefixed appName) so defaultS3Remote
+    // produces the correct s3://bucket/mf-<name>/git path without double prefix.
+    const remote = resolveRemoteUrl(opts.remote as RemoteType, consumerPkg.name, opts.repoUrl);
+    info(`initializing git repo with ${opts.remote} remote...`);
+    await initRepo(process.cwd(), remote);
+    gitRemote = remote;
+  }
+
+  const version = await fetchDeployVersion(appName);
+  const nextVersion = version + 1;
+
+  const gitEnv = await resolveGitEnv(appName, gitRemote);
+
+  // Sync git first so a divergence (GitConflictError) stops us.
+  // The skill commits the working tree (with an LLM-authored message) before
+  // invoking deploy, so the tree should be clean here.
+  if (gitRemote) {
+    await guardCleanTree(process.cwd());
+    info('syncing with git remote');
+    await pullAndResolve(process.cwd(), gitEnv);
+  }
 
   info('reading current Z2H manifest');
-  const manifest = await readManifest();
-  const version = nextVersion(manifest, appName);
-  const keyPrefix = `${appName}/${version}`;
+  const keyPrefix = `${appName}/${nextVersion}`;
   const url = `${BUCKET_READ_DNS_URL}/${keyPrefix}`;
 
   info('building');
@@ -64,10 +102,9 @@ export async function deployCommand(opts: DeployOptions = {}): Promise<void> {
   const assetManifest = (await readJson(assetManifestPath)) as AssetManifestFile;
 
   const deployedBy = getMachineAppName() ?? os.userInfo().username;
-  const gitRemote = await getRemoteUrl(process.cwd());
   const entry: ManifestEntry = {
     ...assetManifest,
-    version,
+    version: nextVersion,
     url,
     deployedBy,
     gitRemote,
@@ -87,16 +124,36 @@ export async function deployCommand(opts: DeployOptions = {}): Promise<void> {
     return;
   }
 
+  // lock → git push → bundle upload → manifest PUT (the manifest write is the single commit point).
   try {
-    // Lock is acquired here — uploadDir triggers the STS credential provider on first S3 call
+    // Acquire the deploy lock explicitly. Done after the build
+    // so the lock hold stays tiny — it wraps only push → upload → manifest.
+    // A 409 here means someone else is mid-deploy;
+    const creds = await brokerCredentialProvider({ appName })();
+    setupS3Client(creds);
+    await acquireDeployLock(appName, token);
+
+    // Push before any S3 write so a rejected push (someone deployed during our
+    // build) stops the deploy before the bundle/manifest go live
+    if (gitRemote) {
+      info('pushing to git remote');
+      await pushToRemote(process.cwd(), gitEnv);
+    }
+
     info(`uploading build → s3://${BUCKET_WRITE_NAME}/${keyPrefix}/`);
     await uploadDir(paths.shadowBuild, keyPrefix);
 
-    info(`updating manifest entry "${appName}" → v${version}`);
-    await writeManifest(upsertEntry(manifest, appName, entry));
-
-    info(`registering app "${appName}" → v${version}`);
-    await registerApp(appName, token, version, entry);
+    // v1 creates the app row (+ owner grant); later versions release onto it.
+    // The two are separate endpoints, so the CLI picks based on the version it
+    // was handed.
+    if (nextVersion === 1) {
+      const visibility = await resolveFirstDeployVisibility(appName, opts.json);
+      info(`registering app "${appName}" → v${nextVersion} (${visibility})`);
+      await registerApp(appName, token, nextVersion, entry, visibility, gitRemote);
+    } else {
+      info(`releasing "${appName}" → v${nextVersion}`);
+      await updateApp(appName, token, nextVersion, entry);
+    }
   } finally {
     await releaseLockBestEffort(appName, token);
   }
@@ -105,10 +162,10 @@ export async function deployCommand(opts: DeployOptions = {}): Promise<void> {
   // before looking it up in the manifest. So the user-facing URL must use
   // the consumer's de-scoped package name (no `mf-` prefix, no `@scope/`).
   const liveUrl = `https://bigbrain.me/bigbrain-vibe/${cleanAppName(consumerPkg.name)}`;
-  output(`[z2h-cli] deployed ✅\n  app:     ${appName}\n  version: ${version}\n  open:    ${liveUrl}`, {
+  output(`[z2h-cli] deployed ✅\n  app:     ${appName}\n  version: ${nextVersion}\n  open:    ${liveUrl}`, {
     ok: true,
     appName,
-    version,
+    version: nextVersion,
     bucket: BUCKET_WRITE_NAME,
     keyPrefix,
     url,
@@ -117,11 +174,18 @@ export async function deployCommand(opts: DeployOptions = {}): Promise<void> {
   });
 }
 
-async function registerApp(appName: string, token: string, version: number, entry: ManifestEntry): Promise<void> {
+async function registerApp(
+  appName: string,
+  token: string,
+  version: number,
+  entry: ManifestEntry,
+  visibility: 'public' | 'private',
+  gitRemote: string
+): Promise<void> {
   const res = await fetch(`${brokerBaseUrl()}/z2h-cli/apps/register`, {
     method: 'POST',
-    headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
-    body: JSON.stringify({ appName, version, entry }),
+    headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', ...routingHeaders() },
+    body: JSON.stringify({ appName, version, entry, visibility, gitRemote }),
   });
   if (!res.ok) {
     const text = await res.text();
@@ -129,14 +193,64 @@ async function registerApp(appName: string, token: string, version: number, entr
   }
 }
 
-// best-effort — the 5-min TTL backstop handles failures
+// Acquire the per-app deploy lock. Throws a friendly error on 409 (someone else is deploying)
+// so the deploy stops and the caller can retry; the backend TTL backstops a crashed holder.
+async function acquireDeployLock(appName: string, token: string): Promise<void> {
+  const res = await fetch(`${brokerBaseUrl()}/z2h-cli/lock/acquire`, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', ...routingHeaders() },
+    body: JSON.stringify({ appName }),
+  });
+  if (res.status === 409) {
+    throw new Error(`Someone is deploying "${appName}" right now — try again in a moment.`);
+  }
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Failed to acquire deploy lock (${res.status}): ${text.slice(0, 512)}`);
+  }
+  info(`deploy lock acquired for ${appName}`);
+}
+
+async function updateApp(appName: string, token: string, version: number, entry: ManifestEntry): Promise<void> {
+  const res = await fetch(`${brokerBaseUrl()}/z2h-cli/apps/update`, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', ...routingHeaders() },
+    body: JSON.stringify({ appName, version, entry }),
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`App update failed (${res.status}): ${text.slice(0, 1024)}`);
+  }
+}
+
+// First deploy only: decide whether the app is born public or private. The
+// choice is passed to the register endpoint (default private). Non-interactive
+// runs (--json or no TTY) always default to private.
+async function resolveFirstDeployVisibility(appName: string, json?: boolean): Promise<'public' | 'private'> {
+  if (json || !process.stdout.isTTY) {
+    return 'private';
+  }
+
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const answer = await new Promise<string>(resolve => {
+    rl.question(`Make "${appName}" public to all monday.com employees? (y/N) `, resolve);
+  });
+  rl.close();
+  return answer.trim().toLowerCase() === 'y' ? 'public' : 'private';
+}
+
+// best-effort — the 2-min TTL backstop handles failures
 async function releaseLockBestEffort(appName: string, token: string): Promise<void> {
   try {
-    await fetch(`${brokerBaseUrl()}/z2h-cli/lock/release`, {
+    const res = await fetch(`${brokerBaseUrl()}/z2h-cli/lock/release`, {
       method: 'POST',
-      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', ...routingHeaders() },
       body: JSON.stringify({ appName }),
     });
+    if (!res.ok) {
+      warn(`failed to release lock for ${appName} (${res.status})`);
+      return;
+    }
     info(`lock released for ${appName}`);
   } catch {
     warn(`failed to release lock for ${appName}`);

package/src/commands/edit.ts

@@ -0,0 +1,63 @@
+import path from 'node:path';
+import { pathExists } from 'fs-extra';
+import { info, warn, output, setOutputMode } from '../util/logger';
+import { assertWorkspace } from '../util/workspace';
+import { mfAppName } from '../util/app-name';
+import { fetchApp } from '../util/broker/app';
+import { resolveGitEnv } from '../util/git/git-env';
+import { cloneRepo, pullAndResolve } from '../util/git/repo';
+import { runYarnInstall } from '../util/npm/install';
+import { prepareShadow } from '../shadow/prepare';
+
+export interface EditOptions {
+  json?: boolean;
+}
+
+export async function editCommand(appName: string, opts: EditOptions = {}): Promise<void> {
+  if (opts.json) {
+    setOutputMode('json');
+  }
+
+  const workspace = await assertWorkspace();
+  const mfName = mfAppName(appName);
+
+  const app = await fetchApp(mfName);
+  if (!app?.gitRemote) {
+    output(`[z2h-cli] ${appName} was deployed without git tracking — run "z2h-cli deploy" to set up a git remote`, {
+      ok: true,
+      appName,
+    });
+    return;
+  }
+  const { gitRemote } = app;
+
+  const gitEnv = await resolveGitEnv(mfName, gitRemote);
+
+  const appDir = path.join(workspace, appName);
+  const hasLocal = await pathExists(appDir);
+
+  if (!hasLocal) {
+    info(`cloning ${appName}...`);
+    await cloneRepo(gitRemote, appDir, gitEnv);
+
+    info(`installing dependencies for ${appName}...`);
+    await runYarnInstall({ cwd: workspace });
+
+    // Best-effort workspace wiring (.zth shadow). Non-fatal — dev/deploy re-run it.
+    try {
+      await prepareShadow(appDir);
+    } catch (err) {
+      warn(`prepare shadow failed: ${(err as Error).message} — it will run again when needed.`);
+    }
+  } else {
+    info(`pulling latest ${appName}...`);
+    await pullAndResolve(appDir, gitEnv);
+  }
+
+  output(`[z2h-cli] ${appName} is ready at ${appDir}`, {
+    ok: true,
+    appDir,
+    appName,
+    gitRemote,
+  });
+}

package/src/commands/grant.ts

@@ -0,0 +1,115 @@
+import { output, setOutputMode } from '../util/logger';
+import { getCwdAppName, mfAppName } from '../util/app-name';
+import { brokerBaseUrl, routingHeaders } from '../constants';
+import { readZthAuth } from '../util/auth/auth-store';
+
+export interface GrantOptions {
+  public?: boolean;
+  level?: 'owner' | 'editor' | 'viewer';
+  json?: boolean;
+}
+
+async function postGrant(
+  appName: string,
+  token: string,
+  body: { type: string; value?: string; accessLevel: string }
+): Promise<void> {
+  const res = await fetch(`${brokerBaseUrl()}/z2h-apps/${appName}/grants`, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', ...routingHeaders() },
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Grant failed (${res.status}): ${text.slice(0, 1024)}`);
+  }
+}
+
+export async function grantCommand(email: string | undefined, opts: GrantOptions): Promise<void> {
+  if (opts.json) {
+    setOutputMode('json');
+  }
+  if (!opts.public && !email) {
+    throw new Error('Specify what to grant — e.g. --public or provide an email');
+  }
+
+  const level = opts.level ?? 'viewer';
+  if (!['owner', 'editor', 'viewer'].includes(level)) {
+    throw new Error(`Invalid --level "${level}". Must be owner, editor, or viewer`);
+  }
+
+  const appName = mfAppName(getCwdAppName()!);
+  const { token } = await readZthAuth();
+
+  if (email) {
+    await postGrant(appName, token, { type: 'user', value: email, accessLevel: level });
+  }
+  if (opts.public) {
+    await postGrant(appName, token, { type: 'global', accessLevel: 'viewer' });
+  }
+
+  const parts: string[] = [];
+  if (email) {
+    parts.push(`${email} (${level})`);
+  }
+  if (opts.public) {
+    parts.push('public');
+  }
+  output(`[z2h-cli] "${appName}" granted to: ${parts.join(', ')}`, { ok: true, appName, granted: parts });
+}
+
+export async function revokeCommand(email: string | undefined, opts: GrantOptions): Promise<void> {
+  if (opts.json) {
+    setOutputMode('json');
+  }
+  if (!opts.public && !email) {
+    throw new Error('Specify what to revoke — e.g. --public or provide an email');
+  }
+
+  const appName = mfAppName(getCwdAppName()!);
+  const { token } = await readZthAuth();
+
+  const target = email ? `user/${encodeURIComponent(email)}` : 'global';
+  const res = await fetch(`${brokerBaseUrl()}/z2h-apps/${appName}/grants/${target}`, {
+    method: 'DELETE',
+    headers: { Authorization: `Bearer ${token}`, ...routingHeaders() },
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Revoke failed (${res.status}): ${text.slice(0, 1024)}`);
+  }
+
+  const revoked = email ?? 'public';
+  const msg = email
+    ? `[z2h-cli] "${appName}" access revoked from ${email}`
+    : `[z2h-cli] "${appName}" is now private (owners/admins only)`;
+  output(msg, { ok: true, appName, revoked });
+}
+
+export interface TransferOwnerOptions {
+  json?: boolean;
+}
+
+export async function transferOwnerCommand(email: string | undefined, opts: TransferOwnerOptions): Promise<void> {
+  if (opts.json) {
+    setOutputMode('json');
+  }
+  if (!email) {
+    throw new Error('Specify the new owner — e.g. z2h-cli transfer-owner someone@monday.com');
+  }
+
+  const appName = mfAppName(getCwdAppName()!);
+  const { token } = await readZthAuth();
+
+  const res = await fetch(`${brokerBaseUrl()}/z2h-apps/${appName}/transfer-owner`, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', ...routingHeaders() },
+    body: JSON.stringify({ email }),
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Transfer owner failed (${res.status}): ${text.slice(0, 1024)}`);
+  }
+
+  output(`[z2h-cli] "${appName}" ownership transferred to ${email}`, { ok: true, appName, newOwner: email });
+}

package/src/constants.ts

@@ -71,6 +71,13 @@ export function brokerBaseUrl(): string {
   return process.env.Z2H_BROKER_BASE_URL || DEFAULT_BROKER_BASE_URL;
 }
 
+// Returns Baggage header for monday-mirror routing when Z2H_ROUTING_KEY is set.
+// No-op in production (returns {}) — only activates when the env var is set.
+export function routingHeaders(): Record<string, string> {
+  const key = process.env.Z2H_ROUTING_KEY;
+  return key ? { Baggage: `routingKey=${key}` } : {};
+}
+
 // The authenticated npm reverse-proxy is mounted here on the broker. Only the
 // `@mondaydotcomorg` scope is served; everything else resolves from npmjs
 // directly. See docs/superpowers/specs/2026-06-03-npm-brokering-design.md §3.