@mondaydotcomorg/z2h-cli 0.10.0 → 0.11.0

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.

package/src/index.ts

@@ -1,19 +1,22 @@
 import { createRequire } from 'node:module';
-import { readFileSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { Command } from 'commander';
 import { execa } from 'execa';
+import { getWorkspaceHome } from './util/workspace';
 import { devCommand } from './commands/dev';
 import { buildCommand } from './commands/build';
 import { cleanCommand } from './commands/clean';
 import { deployCommand } from './commands/deploy';
+import { grantCommand, revokeCommand, transferOwnerCommand } from './commands/grant';
 import { createWorkspaceCommand } from './commands/create-workspace';
 import { createCommand, CreateOptions } from './commands/create';
 import { generateZ2HTokenCommand } from './commands/generate-z2h-token';
 import { migrateCommand } from './commands/migrate';
+import { editCommand } from './commands/edit';
 import { errorLog, fail, getOutputMode } from './util/logger';
 import { trackDuration } from './util/tracker';
+import { getCwdAppName } from './util/app-name';
 
 const { version } = createRequire(import.meta.url)('../package.json') as { version: string };
 
@@ -30,15 +33,17 @@ function selfUpdate(): void {
   }
 }
 
-function getCwdAppName(): string | undefined {
-  try {
-    return (JSON.parse(readFileSync('package.json', 'utf8')) as { name?: string }).name;
-  } catch {
-    return undefined;
+const CONFLICTING_ENV_VARS = ['AWS_PROFILE'];
+
+function stripConflictingEnvVars(): void {
+  for (const name of CONFLICTING_ENV_VARS) {
+    delete process.env[name];
   }
 }
 
 async function main(): Promise<void> {
+  stripConflictingEnvVars();
+
   const program = new Command();
   program
     .name('z2h-cli')
@@ -96,14 +101,26 @@ async function main(): Promise<void> {
 
   program
     .command('deploy')
-    .description('Build, upload artifacts to S3, and update the Z2H manifest')
+    .description('Build, upload to S3, and register the app with the Z2H backend')
     .option('--dry-run', 'print what would happen without uploading anything')
     .option('--json', 'emit structured JSON on stdout')
-    .action(async (opts: { dryRun?: boolean; json?: boolean }) => {
+    .option(
+      '--remote <type>',
+      'First deploy only: source control remote to initialise — s3 (shared storage) or github (your repo). Error if the app already has a git remote.'
+    )
+    .option(
+      '--repo-url <url>',
+      'First deploy only: GitHub repo URL — required when --remote=github. Error if the app already has a git remote.'
+    )
+    .action(async (opts: { dryRun?: boolean; json?: boolean; remote?: string; repoUrl?: string }) => {
       try {
-        await trackDuration('z2h_app_deploy_success', () => deployCommand(opts), {
-          app_name: getCwdAppName(),
-        });
+        await trackDuration(
+          'z2h_app_deploy_success',
+          () => deployCommand(opts as Parameters<typeof deployCommand>[0]),
+          {
+            app_name: getCwdAppName(),
+          }
+        );
       } catch (err) {
         await fail(`deploy failed: ${(err as Error).message}`, { command: 'deploy' }, 2);
       }
@@ -111,7 +128,7 @@ async function main(): Promise<void> {
 
   program
     .command('create-workspace')
-    .description('Bootstrap the ~/zth-projects/ yarn workspace (one-time setup)')
+    .description(`Bootstrap the ${getWorkspaceHome()}/ yarn workspace (one-time setup)`)
     .option('--json', 'emit structured JSON on stdout')
     .action(async (opts: { json?: boolean }) => {
       try {
@@ -139,7 +156,7 @@ async function main(): Promise<void> {
 
   program
     .command('create <app-name>')
-    .description('Scaffold a new Z2H consumer app inside ~/zth-projects/')
+    .description(`Scaffold a new Z2H consumer app inside ${getWorkspaceHome()}/`)
     .option('--template <name>', 'Template name (default | html-embed)')
     .option('--html-file <path>', 'Path to an HTML file to embed (implies --template html-embed)')
     .option('--remote <type>', 'Source control remote: s3 (shared storage) or github (your repo)')
@@ -162,6 +179,59 @@ async function main(): Promise<void> {
       }
     );
 
+  program
+    .command('edit <app-name>')
+    .description(`Pull the latest version of an app into ${getWorkspaceHome()}/<app-name>, cloning it first if needed`)
+    .option('--json', 'emit structured JSON on stdout')
+    .action(async (appName: string, opts: { json?: boolean }) => {
+      try {
+        await trackDuration('z2h_app_edit_pulled', () => editCommand(appName, opts), {
+          app_name: appName,
+        });
+      } catch (err) {
+        await fail(`edit failed: ${(err as Error).message}`, { command: 'edit' }, 1);
+      }
+    });
+
+  program
+    .command('grant [email]')
+    .description('Grant access to the current app (email, --public, or both)')
+    .option('--public', 'make the app visible to all monday.com employees')
+    .option('--level <level>', 'access level for user grants: owner, editor, or viewer (default: viewer)')
+    .option('--json', 'emit structured JSON on stdout')
+    .action(async (email: string | undefined, opts: { public?: boolean; level?: string; json?: boolean }) => {
+      try {
+        await grantCommand(email, opts as Parameters<typeof grantCommand>[1]);
+      } catch (err) {
+        await fail(`grant failed: ${(err as Error).message}`, { command: 'grant' }, 1);
+      }
+    });
+
+  program
+    .command('revoke [email]')
+    .description('Revoke access to the current app (email or --public; owners/admins only)')
+    .option('--public', 'remove the public grant, making the app visible to owners/admins only')
+    .option('--json', 'emit structured JSON on stdout')
+    .action(async (email: string | undefined, opts: { public?: boolean; json?: boolean }) => {
+      try {
+        await revokeCommand(email, opts as Parameters<typeof revokeCommand>[1]);
+      } catch (err) {
+        await fail(`revoke failed: ${(err as Error).message}`, { command: 'revoke' }, 1);
+      }
+    });
+
+  program
+    .command('transfer-owner [email]')
+    .description('Transfer ownership of the current app to another monday.com user')
+    .option('--json', 'emit structured JSON on stdout')
+    .action(async (email: string | undefined, opts: { json?: boolean }) => {
+      try {
+        await transferOwnerCommand(email, opts);
+      } catch (err) {
+        await fail(`transfer-owner failed: ${(err as Error).message}`, { command: 'transfer-owner' }, 1);
+      }
+    });
+
   program
     .command('migrate')
     .description('Run pending workspace migrations')

package/src/shadow/prepare.ts

@@ -10,8 +10,8 @@ import { isPortFree, pickPort } from './port';
 import { syncShadow } from './sync';
 import type { ConsumerPaths, ConsumerPkg, PreparedShadow, ShadowMetadata } from '../types';
 
-export async function prepareShadow(): Promise<PreparedShadow> {
-  const paths = resolveConsumerPaths(process.cwd());
+export async function prepareShadow(consumerDir: string = process.cwd()): Promise<PreparedShadow> {
+  const paths = resolveConsumerPaths(consumerDir);
 
   if (!(await pathExists(paths.consumerPkg))) {
     throw new Error(`No package.json found in ${paths.consumerDir}`);

package/src/templates/app/CLAUDE.md

@@ -45,6 +45,21 @@ When a request needs data, follow `z2h:coding-standards-mf` §0: write a `runQue
 
 ---
 
+## App Visibility
+
+Apps are **private by default** — only you can view them. After the first deploy the `z2h:feature-development` skill automatically asks whether to open it up:
+
+> "Should this app be visible to everyone at monday.com, or just you for now?"
+
+To change visibility at any time:
+
+```
+npx z2h-cli grant --public   # open to all monday.com employees
+npx z2h-cli revoke --public  # back to private
+```
+
+---
+
 ## ⛔ No Agent Visual Testing
 
 When you make a change, **do not screenshot, do not run `axcli chrome`, do not run `playwright-cli`, do not open browser tabs**. The user is sitting in front of the live preview and verifies with their own eyes — HMR updates instantly. Edit → tell the user → wait for their approval. Agent-side visual checks have proven slow and unreliable in this flow.

package/src/util/app-name.ts

@@ -1,3 +1,5 @@
+import { readFileSync } from 'node:fs';
+
 /**
  * Strip any npm scope (`@scope/`) from a package name.
  * e.g. `@trident/customer-viewer` → `customer-viewer`, `foo` → `foo`.
@@ -6,6 +8,14 @@ export function cleanAppName(name: string): string {
   return name.replace(/^@[^/]+\//, '');
 }
 
+export function getCwdAppName(): string | undefined {
+  try {
+    return (JSON.parse(readFileSync('package.json', 'utf8')) as { name?: string }).name;
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Canonical MF bundle name: the de-scoped app name with an `mf-` prefix.
  * This matches the trident convention (shadow pkg is `@trident/mf-<app>`,

package/src/util/auth/__tests__/broker-credential-provider.test.ts

@@ -1,5 +1,10 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { brokerCredentialProvider, STS_BROKER_PATH } from '../broker-credential-provider';
+import {
+  brokerCredentialProvider,
+  fetchDeployVersion,
+  DEPLOY_VERSION_PATH,
+  STS_BROKER_PATH,
+} from '../broker-credential-provider';
 import { DEFAULT_BROKER_BASE_URL } from '../../../constants';
 import * as authStore from '../auth-store';
 
@@ -32,8 +37,35 @@ function mockFetchOnce(body: unknown, init: { status?: number; text?: string } =
   return fetchMock;
 }
 
+describe('fetchDeployVersion', () => {
+  it('POSTs the appName to the version endpoint and returns the version', async () => {
+    const fetchMock = mockFetchOnce({ version: 4 });
+
+    const version = await fetchDeployVersion('my-app');
+
+    expect(version).toBe(4);
+    expect(fetchMock).toHaveBeenCalledWith(
+      `${DEFAULT_BROKER_BASE_URL}${DEPLOY_VERSION_PATH}`,
+      expect.objectContaining({
+        method: 'POST',
+        body: JSON.stringify({ appName: 'my-app' }),
+      })
+    );
+  });
+
+  it('returns 0 when the broker returns no version field (new app)', async () => {
+    mockFetchOnce({});
+    await expect(fetchDeployVersion('my-app')).resolves.toBe(0);
+  });
+
+  it('surfaces a remediation hint on 401', async () => {
+    mockFetchOnce({}, { status: 401, text: 'Unauthorized' });
+    await expect(fetchDeployVersion('my-app')).rejects.toThrow(/token rejected by the broker/);
+  });
+});
+
 describe('brokerCredentialProvider', () => {
-  it('POSTs the appName to the broker with a Bearer token + parses the response', async () => {
+  it('POSTs the appName + version to the broker with a Bearer token + parses the response', async () => {
     const fetchMock = mockFetchOnce({ ...STUB_CREDS, expiration: FAR_FUTURE_EXPIRY });
     const provider = brokerCredentialProvider({ appName: 'my-app' });
     const creds = await provider();

package/src/util/auth/auth-store.ts

@@ -20,6 +20,15 @@ export class Z2hAuthMissingError extends Error {
 }
 
 export async function readZthAuth(): Promise<ZthAuth> {
+  if (process.env.Z2H_AUTH_TOKEN) {
+    const token = process.env.Z2H_AUTH_TOKEN;
+    if (!/^[\w-]+\.[\w-]+\.[\w-]+$/.test(token)) {
+      throw new Error(
+        'Z2H_AUTH_TOKEN is not a valid JWT (expected three dot-separated segments). Please re-set the environment variable.'
+      );
+    }
+    return { token };
+  }
   if (!(await pathExists(Z2H_AUTH_FILE))) {
     throw new Z2hAuthMissingError(Z2H_AUTH_FILE);
   }
@@ -40,6 +49,9 @@ export async function readZthAuth(): Promise<ZthAuth> {
  * blow up — and where an inline sync read keeps the spawn call site simple.
  */
 export function tryReadAuthTokenSync(): string | null {
+  if (process.env.Z2H_AUTH_TOKEN) {
+    return process.env.Z2H_AUTH_TOKEN;
+  }
   try {
     const parsed = readJsonSync(Z2H_AUTH_FILE) as Partial<ZthAuth> | null;
     return parsed?.token ?? null;

package/src/util/auth/broker-credential-provider.ts

@@ -1,51 +1,78 @@
-import { brokerBaseUrl } from '../../constants';
+import { brokerBaseUrl, routingHeaders } from '../../constants';
 import { readZthAuth } from './auth-store';
 import type { AwsCredentialIdentity, AwsCredentialIdentityProvider } from '@aws-sdk/types';
 
 export const STS_BROKER_PATH = '/z2h-cli/sts/credentials';
+export const DEPLOY_VERSION_PATH = '/z2h-cli/apps/version';
 
 // Refresh the cached credentials this many ms before they expire so the next
 // AWS API call doesn't race the broker round-trip against a hard expiry.
 const REFRESH_BUFFER_MS = 5 * 60 * 1000;
 
-interface BrokerResponse {
+interface CredentialsResponse {
   accessKeyId?: string;
   secretAccessKey?: string;
   sessionToken?: string;
   expiration?: string;
 }
 
-async function fetchCredentialsOnce(appName: string): Promise<AwsCredentialIdentity> {
-  const { token } = await readZthAuth();
-  const url = `${brokerBaseUrl()}${STS_BROKER_PATH}`;
+interface VersionResponse {
+  version?: number;
+}
 
-  let res: Response;
+async function postToBroker(path: string, body: unknown): Promise<Response> {
+  const { token } = await readZthAuth();
   try {
-    res = await fetch(url, {
+    return await fetch(`${brokerBaseUrl()}${path}`, {
       method: 'POST',
       headers: {
         Authorization: `Bearer ${token}`,
         'Content-Type': 'application/json',
         Accept: 'application/json',
+        ...routingHeaders(),
       },
-      body: JSON.stringify({ appName }),
+      body: JSON.stringify(body),
     });
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     throw new Error(`Z2H deploy broker request failed: ${message}`);
   }
+}
 
+function assertBrokerOk(res: Response): void {
   if (res.status === 401 || res.status === 403) {
     throw new Error(
       `Z2H deploy token rejected by the broker (${res.status}). Refresh user token by running 'z2h-cli generate-z2h-token'.`
     );
   }
+}
+
+/**
+ * Reserve the version this deploy will write to. Split out of the STS
+ * credentials call so version derivation lives on its own endpoint — the CLI
+ * asks for the version first, then requests credentials scoped to it.
+ */
+export async function fetchDeployVersion(appName: string): Promise<number> {
+  const res = await postToBroker(DEPLOY_VERSION_PATH, { appName });
+  assertBrokerOk(res);
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Z2H deploy broker returned ${res.status}: ${text.slice(0, 1024)}`);
+  }
+  const body = (await res.json()) as VersionResponse;
+
+  return body.version ?? 0;
+}
+
+async function fetchStsOnce(appName: string): Promise<AwsCredentialIdentity> {
+  const res = await postToBroker(STS_BROKER_PATH, { appName });
+  assertBrokerOk(res);
   if (!res.ok) {
     const text = await res.text();
     throw new Error(`Z2H deploy broker returned ${res.status}: ${text.slice(0, 1024)}`);
   }
 
-  const body = (await res.json()) as BrokerResponse;
+  const body = (await res.json()) as CredentialsResponse;
   if (!body.accessKeyId || !body.secretAccessKey || !body.sessionToken || !body.expiration) {
     throw new Error('Z2H deploy broker response missing required credential fields');
   }
@@ -60,8 +87,9 @@ async function fetchCredentialsOnce(appName: string): Promise<AwsCredentialIdent
 
 /**
  * AWS SDK credential provider that fetches short-lived deploy credentials
- * from the bigbrain-zth STS broker. Credentials are cached in memory until
- * 5 minutes before expiry; concurrent calls share a single in-flight fetch.
+ * from the bigbrain-zth STS broker for a specific version. Credentials are
+ * cached in memory until 5 minutes before expiry; concurrent calls share a
+ * single in-flight fetch.
  */
 export function brokerCredentialProvider({ appName }: { appName: string }): AwsCredentialIdentityProvider {
   let cached: AwsCredentialIdentity | undefined;
@@ -76,10 +104,10 @@ export function brokerCredentialProvider({ appName }: { appName: string }): AwsC
       return inflight;
     }
 
-    inflight = fetchCredentialsOnce(appName)
-      .then(creds => {
-        cached = creds;
-        return creds;
+    inflight = fetchStsOnce(appName)
+      .then(credentials => {
+        cached = credentials;
+        return credentials;
       })
       .finally(() => {
         inflight = undefined;

package/src/util/broker/app.ts

@@ -0,0 +1,34 @@
+import { brokerBaseUrl, routingHeaders } from '../../constants';
+import { readZthAuth } from '../auth/auth-store';
+
+export interface AppInfo {
+  appName: string;
+  version: number;
+  entry: Record<string, unknown>;
+  deployedBy: string;
+  gitRemote: string;
+  createdBy: string;
+}
+
+/**
+ * Fetches a single app's current state from the broker.
+ * Returns null if the app has never been deployed (404).
+ */
+export async function fetchApp(appName: string): Promise<AppInfo | null> {
+  const { token } = await readZthAuth();
+  const res = await fetch(`${brokerBaseUrl()}/z2h-cli/apps/${encodeURIComponent(appName)}`, {
+    headers: {
+      Authorization: `Bearer ${token}`,
+      Accept: 'application/json',
+      ...routingHeaders(),
+    },
+  });
+  if (res.status === 404) {
+    return null;
+  }
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Z2H app lookup failed (${res.status}): ${text.slice(0, 512)}`);
+  }
+  return res.json() as Promise<AppInfo>;
+}