@mondaydotcomorg/z2h-cli 0.10.0 → 0.11.0

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

@@ -0,0 +1,184 @@
+import path from 'node:path';
+import os from 'node:os';
+import { mkdtemp, rm, ensureDir, writeJson } from 'fs-extra';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { runYarnInstall } from '../../util/npm/install';
+import { prepareShadow } from '../../shadow/prepare';
+import { editCommand } from '../edit';
+import * as brokerApp from '../../util/broker/app';
+import * as repo from '../../util/git/repo';
+import * as brokerProvider from '../../util/auth/broker-credential-provider';
+
+vi.mock('../../util/npm/install', () => ({
+  runYarnInstall: vi.fn().mockResolvedValue(undefined),
+}));
+
+vi.mock('../../shadow/prepare', () => ({
+  prepareShadow: vi.fn().mockResolvedValue(undefined),
+}));
+
+vi.mock('../../util/git/repo', () => ({
+  cloneRepo: vi.fn().mockResolvedValue(undefined),
+  pullAndResolve: vi.fn().mockResolvedValue(undefined),
+  GitConflictError: class GitConflictError extends Error {},
+}));
+
+const FAKE_CREDS = { accessKeyId: 'AKID', secretAccessKey: 'SECRET', sessionToken: 'TOKEN' };
+const FAKE_GIT_ENV = { AWS_ACCESS_KEY_ID: 'AKID', AWS_SECRET_ACCESS_KEY: 'SECRET', AWS_SESSION_TOKEN: 'TOKEN' };
+
+vi.mock('../../util/auth/broker-credential-provider', () => ({
+  brokerCredentialProvider: vi.fn(() => vi.fn().mockResolvedValue(FAKE_CREDS)),
+}));
+
+const S3_REMOTE = 's3://prod-use1-bigbrain-zth-mf-assets/mf-demo/git';
+const GITHUB_REMOTE = 'https://github.com/org/demo-app.git';
+
+async function makeWorkspace(tmp: string): Promise<void> {
+  await ensureDir(tmp);
+  await writeJson(path.join(tmp, 'package.json'), {
+    name: '@mondaydotcomorg/zth-projects-workspace',
+    private: true,
+    z2hWorkspace: true,
+    workspaces: ['*', '*/.zth'],
+  });
+}
+
+describe('edit', () => {
+  let tmp: string;
+
+  beforeEach(async () => {
+    tmp = await mkdtemp(path.join(os.tmpdir(), 'z2h-e-'));
+    vi.stubEnv('Z2H_WORKSPACE_HOME', tmp);
+    vi.mocked(runYarnInstall).mockClear();
+    vi.mocked(prepareShadow).mockClear();
+    vi.mocked(repo.cloneRepo).mockClear();
+    vi.mocked(repo.pullAndResolve).mockClear();
+    vi.mocked(brokerProvider.brokerCredentialProvider).mockClear();
+  });
+
+  afterEach(async () => {
+    vi.unstubAllEnvs();
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  it('skips cleanly when the app has no gitRemote', async () => {
+    await makeWorkspace(tmp);
+    vi.spyOn(brokerApp, 'fetchApp').mockResolvedValue(null);
+
+    await expect(editCommand('demo')).resolves.toBeUndefined();
+    expect(repo.cloneRepo).not.toHaveBeenCalled();
+    expect(repo.pullAndResolve).not.toHaveBeenCalled();
+  });
+
+  it('clones when the app dir does not exist locally', async () => {
+    await makeWorkspace(tmp);
+    vi.spyOn(brokerApp, 'fetchApp').mockResolvedValue({
+      appName: 'mf-demo',
+      version: 3,
+      gitRemote: S3_REMOTE,
+      entry: {},
+      deployedBy: 'u@x.com',
+      createdBy: 'u@x.com',
+    });
+
+    await editCommand('demo');
+
+    expect(repo.cloneRepo).toHaveBeenCalledWith(
+      S3_REMOTE,
+      path.join(tmp, 'demo'),
+      expect.objectContaining(FAKE_GIT_ENV)
+    );
+    expect(repo.pullAndResolve).not.toHaveBeenCalled();
+  });
+
+  it('pulls when the app dir already exists locally', async () => {
+    await makeWorkspace(tmp);
+    await ensureDir(path.join(tmp, 'demo'));
+    vi.spyOn(brokerApp, 'fetchApp').mockResolvedValue({
+      appName: 'mf-demo',
+      version: 3,
+      gitRemote: S3_REMOTE,
+      entry: {},
+      deployedBy: 'u@x.com',
+      createdBy: 'u@x.com',
+    });
+
+    await editCommand('demo');
+
+    expect(repo.pullAndResolve).toHaveBeenCalledWith(path.join(tmp, 'demo'), expect.objectContaining(FAKE_GIT_ENV));
+    expect(repo.cloneRepo).not.toHaveBeenCalled();
+  });
+
+  it('injects AWS credentials for S3 remotes', async () => {
+    await makeWorkspace(tmp);
+    vi.spyOn(brokerApp, 'fetchApp').mockResolvedValue({
+      appName: 'mf-demo',
+      version: 3,
+      gitRemote: S3_REMOTE,
+      entry: {},
+      deployedBy: 'u@x.com',
+      createdBy: 'u@x.com',
+    });
+
+    await editCommand('demo');
+
+    expect(brokerProvider.brokerCredentialProvider).toHaveBeenCalledWith({ appName: 'mf-demo' });
+    expect(repo.cloneRepo).toHaveBeenCalledWith(S3_REMOTE, expect.any(String), expect.objectContaining(FAKE_GIT_ENV));
+  });
+
+  it('does not inject AWS credentials for GitHub remotes', async () => {
+    await makeWorkspace(tmp);
+    vi.spyOn(brokerApp, 'fetchApp').mockResolvedValue({
+      appName: 'mf-demo',
+      version: 3,
+      gitRemote: GITHUB_REMOTE,
+      entry: {},
+      deployedBy: 'u@x.com',
+      createdBy: 'u@x.com',
+    });
+
+    await editCommand('demo');
+
+    expect(brokerProvider.brokerCredentialProvider).not.toHaveBeenCalled();
+    expect(repo.cloneRepo).toHaveBeenCalledWith(GITHUB_REMOTE, expect.any(String), undefined);
+  });
+
+  it('re-wires the workspace after a fresh clone', async () => {
+    await makeWorkspace(tmp);
+    vi.spyOn(brokerApp, 'fetchApp').mockResolvedValue({
+      appName: 'mf-demo',
+      version: 3,
+      gitRemote: S3_REMOTE,
+      entry: {},
+      deployedBy: 'u@x.com',
+      createdBy: 'u@x.com',
+    });
+    vi.mocked(repo.cloneRepo).mockImplementationOnce(async (_remote, dir) => {
+      await ensureDir(dir);
+    });
+
+    await editCommand('demo');
+
+    expect(runYarnInstall).toHaveBeenCalledWith(expect.objectContaining({ cwd: tmp }));
+    expect(prepareShadow).toHaveBeenCalledWith(path.join(tmp, 'demo'));
+  });
+
+  it('does not re-wire the workspace on a pull', async () => {
+    await makeWorkspace(tmp);
+    await ensureDir(path.join(tmp, 'demo'));
+    vi.spyOn(brokerApp, 'fetchApp').mockResolvedValue({
+      appName: 'mf-demo',
+      version: 3,
+      gitRemote: S3_REMOTE,
+      entry: {},
+      deployedBy: 'u@x.com',
+      createdBy: 'u@x.com',
+    });
+
+    await editCommand('demo');
+
+    expect(runYarnInstall).not.toHaveBeenCalled();
+    expect(prepareShadow).not.toHaveBeenCalled();
+  });
+});

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,27 +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, 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';
-import { getRemoteUrl } from '../util/git/repo';
 
 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.
@@ -40,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');
@@ -62,12 +101,10 @@ export async function deployCommand(opts: DeployOptions = {}): Promise<void> {
   }
   const assetManifest = (await readJson(assetManifestPath)) as AssetManifestFile;
 
-  const deployedBy = os.userInfo().username;
-  const gitRemote = await getRemoteUrl(process.cwd());
-
+  const deployedBy = getMachineAppName() ?? os.userInfo().username;
   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,
+  });
+}