@mondaydotcomorg/z2h-cli 0.10.1 → 0.11.1

package/dist/util/git/git-env.js

@@ -0,0 +1,24 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const util_auth_brokerCredentialProvider = require('../auth/broker-credential-provider.js');
+
+/**
+ * Builds the AWS_* environment that `git-remote-s3` needs to talk to an S3-backed
+ * git remote, by minting short-lived broker credentials scoped to the app.
+ *
+ * Returns `undefined` for non-S3 remotes (GitHub apps ride the user's own git
+ * credential helper) and when there is no remote at all.
+ */
+async function resolveGitEnv(appName, gitRemote) {
+    if (!gitRemote?.startsWith('s3://')) {
+        return undefined;
+    }
+    const creds = await util_auth_brokerCredentialProvider.brokerCredentialProvider({ appName })();
+    return {
+        AWS_ACCESS_KEY_ID: creds.accessKeyId,
+        AWS_SECRET_ACCESS_KEY: creds.secretAccessKey,
+        AWS_SESSION_TOKEN: creds.sessionToken ?? '',
+    };
+}
+
+exports.resolveGitEnv = resolveGitEnv;

package/dist/util/git/remote-options.d.ts

@@ -0,0 +1,17 @@
+export declare const REMOTE_TYPES: readonly ["s3", "github"];
+export type RemoteType = (typeof REMOTE_TYPES)[number];
+export interface RemoteOptions {
+    remote?: RemoteType;
+    repoUrl?: string;
+}
+/**
+ * Validates --remote and --repo-url option values.
+ * Pass `requireRemote: true` when the flag is mandatory (e.g. create).
+ */
+export declare function validateRemoteOptions(opts: RemoteOptions, requireRemote?: boolean): void;
+/**
+ * Resolves the git remote URL from --remote / --repo-url options.
+ * Call after validateRemoteOptions.
+ */
+export declare function resolveRemoteUrl(remote: RemoteType, appName: string, repoUrl?: string): string;
+//# sourceMappingURL=remote-options.d.ts.map

package/dist/util/git/remote-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-options.d.ts","sourceRoot":"","sources":["../../../src/util/git/remote-options.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,YAAY,2BAA4B,CAAC;AAEtD,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvD,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,aAAa,EAAE,aAAa,UAAQ,GAAG,IAAI,CAatF;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAE9F"}

package/dist/util/git/remote-options.js

@@ -0,0 +1,34 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const util_git_repo = require('./repo.js');
+
+const REMOTE_TYPES = ['s3', 'github'];
+/**
+ * Validates --remote and --repo-url option values.
+ * Pass `requireRemote: true` when the flag is mandatory (e.g. create).
+ */
+function validateRemoteOptions(opts, requireRemote = false) {
+    if (!opts.remote) {
+        if (requireRemote) {
+            throw new Error(`--remote is required. Use --remote=s3 (shared storage) or --remote=github (your GitHub repo).`);
+        }
+        return;
+    }
+    if (!REMOTE_TYPES.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.');
+    }
+}
+/**
+ * Resolves the git remote URL from --remote / --repo-url options.
+ * Call after validateRemoteOptions.
+ */
+function resolveRemoteUrl(remote, appName, repoUrl) {
+    return remote === 's3' ? util_git_repo.defaultS3Remote(appName) : repoUrl;
+}
+
+exports.REMOTE_TYPES = REMOTE_TYPES;
+exports.resolveRemoteUrl = resolveRemoteUrl;
+exports.validateRemoteOptions = validateRemoteOptions;

package/dist/util/git/repo.d.ts

@@ -1,13 +1,31 @@
 export declare class GitConflictError extends Error {
     constructor(message: string);
 }
+export interface ConflictInfo {
+    localCommits: string[];
+    remoteCommits: string[];
+    conflictingFiles: string[];
+}
 export declare function defaultS3Remote(app: string): string;
 export declare function initRepo(dir: string, remote: string): Promise<void>;
 export declare function getRemoteUrl(dir: string): Promise<string | undefined>;
-export declare function cloneRepo(remote: string, dir: string): Promise<void>;
+/**
+ * Throws if the working tree has uncommitted changes. Call only on a known git
+ * repo (e.g. guarded by a resolved remote) — a failing `git status` propagates
+ * rather than being silently treated as "clean".
+ */
+export declare function guardCleanTree(dir: string): Promise<void>;
+export declare function cloneRepo(remote: string, dir: string, env?: Record<string, string>): Promise<void>;
 export declare function safeBackupIfDirty(dir: string): Promise<void>;
-export declare function pullAndResolve(dir: string): Promise<void>;
+export declare function pullAndResolve(dir: string, env?: Record<string, string>): Promise<void>;
+/**
+ * Pushes the local master branch to origin. On a rejected (non-fast-forward) push —
+ * i.e. a deploy landed while we were building — gathers structured conflict info and
+ * throws GitConflictError so the deploy stops before anything goes live (spec: push
+ * must stop the deploy before the bundle upload). The skill re-resolves and re-runs,
+ * which rebuilds against the latest. Non-conflict push errors re-throw as-is.
+ */
+export declare function pushToRemote(dir: string, env?: Record<string, string>): Promise<void>;
 export declare function remoteHead(dir: string): Promise<string>;
 export declare function localHead(dir: string): Promise<string>;
-export declare function commitDetailedAndPush(dir: string, version: number): Promise<void>;
 //# sourceMappingURL=repo.d.ts.map

package/dist/util/git/repo.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"repo.d.ts","sourceRoot":"","sources":["../../../src/util/git/repo.ts"],"names":[],"mappings":"AAMA,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,OAAO,EAAE,MAAM;CAI5B;AAID,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,wBAAsB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMzE;AAED,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAI3E;AAED,wBAAsB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE1E;AAED,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAclE;AAED,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAS/D;AAED,wBAAsB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAO7D;AAED,wBAAsB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAG5D;AAED,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAoBvF"}
+{"version":3,"file":"repo.d.ts","sourceRoot":"","sources":["../../../src/util/git/repo.ts"],"names":[],"mappings":"AAkBA,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,WAAW,YAAY;IAC3B,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,gBAAgB,EAAE,MAAM,EAAE,CAAC;CAC5B;AAKD,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,wBAAsB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAOzE;AAED,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAI3E;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAK/D;AAED,wBAAsB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAG5G;AAED,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAclE;AAED,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAe7F;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAqB3F;AAED,wBAAsB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAO7D;AAED,wBAAsB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAG5D"}

package/dist/util/git/repo.js

@@ -11,6 +11,14 @@ const _interopDefault = e => e && e.__esModule ? e : { default: e };
 const path__default = /*#__PURE__*/_interopDefault(path);
 const fs__default = /*#__PURE__*/_interopDefault(fs);
 
+function execGit(args, dir, env) {
+    return execa.execa('git', args, { cwd: dir, env });
+}
+async function execGitLines(args, dir, env) {
+    return execGit(args, dir, env)
+        .then(r => r.stdout.split('\n').filter(Boolean))
+        .catch(() => []);
+}
 class GitConflictError extends Error {
     constructor(message) {
         super(message);
@@ -18,28 +26,42 @@ class GitConflictError extends Error {
     }
 }
 const REQUIRED_GITIGNORE_ENTRIES = ['node_modules/', '.zth/', 'build/'];
+const LOCAL_HOOKS_DIR = '.zth/hooks';
 function defaultS3Remote(app) {
     return `s3://${constants.BUCKET_WRITE_NAME}/${util_appName.mfAppName(app)}/git`;
 }
 async function initRepo(dir, remote) {
     await ensureGitignore(dir);
-    await execa.execa('git', ['init', '-b', 'master'], { cwd: dir });
-    await execa.execa('git', ['add', '.'], { cwd: dir });
-    await execa.execa('git', ['commit', '-m', 'Initial commit'], { cwd: dir });
-    await execa.execa('git', ['remote', 'add', 'origin', remote], { cwd: dir });
+    await execGit(['init', '-b', 'master'], dir);
+    await disableLocalHooks(dir);
+    await execGit(['add', '.'], dir);
+    await execGit(['commit', '-m', 'Initial commit'], dir);
+    await execGit(['remote', 'add', 'origin', remote], dir);
 }
 async function getRemoteUrl(dir) {
-    return execa.execa('git', ['remote', 'get-url', 'origin'], { cwd: dir })
+    return execGit(['remote', 'get-url', 'origin'], dir)
         .then(r => r.stdout.trim() || undefined)
         .catch(() => undefined);
 }
-async function cloneRepo(remote, dir) {
-    await execa.execa('git', ['clone', remote, dir]);
+/**
+ * Throws if the working tree has uncommitted changes. Call only on a known git
+ * repo (e.g. guarded by a resolved remote) — a failing `git status` propagates
+ * rather than being silently treated as "clean".
+ */
+async function guardCleanTree(dir) {
+    const { stdout } = await execGit(['status', '--porcelain'], dir);
+    if (stdout.trim()) {
+        throw new Error('You have uncommitted changes — commit your changes before deploying.');
+    }
+}
+async function cloneRepo(remote, dir, env = {}) {
+    await execa.execa('git', ['clone', remote, dir], { env: { ...process.env, ...env } });
+    await disableLocalHooks(dir);
 }
 async function safeBackupIfDirty(dir) {
     let status;
     try {
-        ({ stdout: status } = await execa.execa('git', ['status', '--porcelain'], { cwd: dir }));
+        ({ stdout: status } = await execGit(['status', '--porcelain'], dir));
     }
     catch {
         return;
@@ -52,17 +74,55 @@ async function safeBackupIfDirty(dir) {
     const backupDir = path__default.default.join(path__default.default.dirname(dir), `${appName}.backup-${sha}`);
     await fs__default.default.copy(dir, backupDir, { overwrite: false });
 }
-async function pullAndResolve(dir) {
+async function pullAndResolve(dir, env) {
+    const gitEnv = env ? { ...process.env, ...env } : undefined;
     try {
-        await execa.execa('git', ['pull', '--ff-only'], { cwd: dir });
+        await execGit(['pull', '--ff-only'], dir, gitEnv);
     }
-    catch {
-        // TODO(Phase 7): safeBackupIfDirty(dir) → resolveDivergence(dir) instead of throwing
-        throw new GitConflictError('This app changed while you were working — please re-open it to get the latest version.');
+    catch (err) {
+        // First deploy: remote exists but has no commits yet — not a conflict.
+        const e = err;
+        const msg = `${e.message ?? ''} ${e.stderr ?? ''}`;
+        if (/couldn't find remote ref|no tracking information|does not appear to be a git repository/i.test(msg)) {
+            return;
+        }
+        await safeBackupIfDirty(dir);
+        const info = await gatherConflictInfo(dir, gitEnv);
+        throw new GitConflictError(JSON.stringify(info));
+    }
+}
+/**
+ * Pushes the local master branch to origin. On a rejected (non-fast-forward) push —
+ * i.e. a deploy landed while we were building — gathers structured conflict info and
+ * throws GitConflictError so the deploy stops before anything goes live (spec: push
+ * must stop the deploy before the bundle upload). The skill re-resolves and re-runs,
+ * which rebuilds against the latest. Non-conflict push errors re-throw as-is.
+ */
+async function pushToRemote(dir, env) {
+    const gitEnv = env ? { ...process.env, ...env } : undefined;
+    try {
+        await execGit(['push', '-u', 'origin', 'master'], dir, gitEnv);
+    }
+    catch (err) {
+        // execa puts the command in message but stderr in a separate field.
+        const e = err;
+        const msg = `${e.message ?? ''} ${e.stderr ?? ''}`;
+        const isRejected = /\[rejected\]|non-fast-forward/.test(msg);
+        // git-remote-s3 emits EPIPE when git closes its stdin after a completed
+        // push (new commits or already-up-to-date). Treat EPIPE without a
+        // rejection marker as success — the push went through.
+        if (/EPIPE/.test(msg) && !isRejected) {
+            return;
+        }
+        if (isRejected) {
+            const info = await gatherConflictInfo(dir, gitEnv);
+            throw new GitConflictError(JSON.stringify(info));
+        }
+        throw err;
     }
 }
 async function remoteHead(dir) {
-    const { stdout } = await execa.execa('git', ['ls-remote', 'origin', 'refs/heads/master'], { cwd: dir });
+    const { stdout } = await execGit(['ls-remote', 'origin', 'refs/heads/master'], dir);
     const sha = stdout.split('\t')[0]?.trim();
     if (!sha) {
         throw new Error('could not read remote head — is the remote reachable?');
@@ -70,42 +130,30 @@ async function remoteHead(dir) {
     return sha;
 }
 async function localHead(dir) {
-    const { stdout } = await execa.execa('git', ['rev-parse', 'HEAD'], { cwd: dir });
+    const { stdout } = await execGit(['rev-parse', 'HEAD'], dir);
     return stdout.trim();
 }
-async function commitDetailedAndPush(dir, version) {
-    const { stdout: branch } = await execa.execa('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: dir });
-    if (branch.trim() !== 'master') {
-        throw new Error(`expected branch "master" but you are on "${branch.trim()}" — switch back before deploying.`);
-    }
-    await execa.execa('git', ['add', '.'], { cwd: dir });
-    const { stdout: staged } = await execa.execa('git', ['diff', '--cached', '--name-only'], { cwd: dir });
-    if (!staged.trim()) {
-        throw new Error('Nothing new to deploy — no files have changed since the last deploy.');
-    }
-    const message = await buildCommitMessage(dir, version);
-    await execa.execa('git', ['commit', '-m', message], { cwd: dir });
-    try {
-        await execa.execa('git', ['push', '-u', 'origin', 'master'], { cwd: dir });
-    }
-    catch (err) {
-        if (/\[rejected\]|non-fast-forward/.test(err.message)) {
-            throw new GitConflictError('push rejected — remote has new commits');
-        }
-        throw err;
-    }
+async function gatherConflictInfo(dir, gitEnv) {
+    await execGit(['fetch', 'origin'], dir, gitEnv).catch(() => { });
+    const [localCommits, remoteCommits, conflictingFiles] = await Promise.all([
+        execGitLines(['log', 'origin/master..HEAD', '--oneline'], dir, gitEnv),
+        execGitLines(['log', 'HEAD..origin/master', '--oneline'], dir, gitEnv),
+        execGitLines(['diff', '--name-only', 'HEAD', 'origin/master'], dir, gitEnv),
+    ]);
+    return { localCommits, remoteCommits, conflictingFiles };
 }
-async function buildCommitMessage(dir, version) {
-    // TODO(Phase 7): replace with LLM-generated summary using git diff + commit messages
-    const { stdout } = await execa.execa('git', ['status', '--short'], { cwd: dir });
-    const files = stdout
-        .split('\n')
-        .map(line => line.slice(3).trim())
-        .filter(Boolean);
-    const fileList = files.length
-        ? files.slice(0, 5).join(', ') + (files.length > 5 ? ` (+${files.length - 5} more)` : '')
-        : 'no changes';
-    return `v${version}: deploy — ${fileList}`;
+/**
+ * Z2H repos are agent-driven and non-interactive — git hooks (whether from
+ * global core.hooksPath, init.templateDir, or manually placed .git/hooks/*)
+ * serve no purpose and break non-interactive pushes. Point core.hooksPath to an
+ * empty local directory so all hook sources are bypassed for this repo only.
+ */
+async function disableLocalHooks(dir) {
+    if (await fs__default.default.pathExists(path__default.default.join(dir, LOCAL_HOOKS_DIR))) {
+        return;
+    }
+    await fs__default.default.ensureDir(path__default.default.join(dir, LOCAL_HOOKS_DIR));
+    await execGit(['config', '--local', 'core.hooksPath', LOCAL_HOOKS_DIR], dir);
 }
 async function ensureGitignore(dir) {
     const gitignorePath = path__default.default.join(dir, '.gitignore');
@@ -127,11 +175,12 @@ async function ensureGitignore(dir) {
 
 exports.GitConflictError = GitConflictError;
 exports.cloneRepo = cloneRepo;
-exports.commitDetailedAndPush = commitDetailedAndPush;
 exports.defaultS3Remote = defaultS3Remote;
 exports.getRemoteUrl = getRemoteUrl;
+exports.guardCleanTree = guardCleanTree;
 exports.initRepo = initRepo;
 exports.localHead = localHead;
 exports.pullAndResolve = pullAndResolve;
+exports.pushToRemote = pushToRemote;
 exports.remoteHead = remoteHead;
 exports.safeBackupIfDirty = safeBackupIfDirty;

package/dist/util/s3/client.d.ts

@@ -1,10 +1,5 @@
 import { S3Client } from '@aws-sdk/client-s3';
-/**
- * Initialize the per-process S3 client with broker-issued credentials scoped
- * to the given app's S3 prefix. Must be called once before any `getS3Client`.
- */
-export declare function setupS3Client({ appName }: {
-    appName: string;
-}): void;
+import type { AwsCredentialIdentity } from '@aws-sdk/types';
+export declare function setupS3Client(credentials: AwsCredentialIdentity): void;
 export declare function getS3Client(): S3Client;
 //# sourceMappingURL=client.d.ts.map

package/dist/util/s3/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/util/s3/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAM9C;;;GAGG;AACH,wBAAgB,aAAa,CAAC,EAAE,OAAO,EAAE,EAAE;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAKpE;AAED,wBAAgB,WAAW,IAAI,QAAQ,CAKtC"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/util/s3/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE9C,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAI5D,wBAAgB,aAAa,CAAC,WAAW,EAAE,qBAAqB,GAAG,IAAI,CAEtE;AAED,wBAAgB,WAAW,IAAI,QAAQ,CAKtC"}

package/dist/util/s3/client.js

@@ -1,23 +1,15 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
 const clientS3 = require('@aws-sdk/client-s3');
-const util_auth_brokerCredentialProvider = require('../auth/broker-credential-provider.js');
 const constants = require('../../constants.js');
 
 let client = null;
-/**
- * Initialize the per-process S3 client with broker-issued credentials scoped
- * to the given app's S3 prefix. Must be called once before any `getS3Client`.
- */
-function setupS3Client({ appName }) {
-    client = new clientS3.S3Client({
-        region: constants.REGION,
-        credentials: util_auth_brokerCredentialProvider.brokerCredentialProvider({ appName }),
-    });
+function setupS3Client(credentials) {
+    client = new clientS3.S3Client({ region: constants.REGION, credentials });
 }
 function getS3Client() {
     if (!client) {
-        throw new Error('S3 client not initialized — call setupS3Client({ appName }) first.');
+        throw new Error('S3 client not initialized — call setupS3Client(credentials) first.');
     }
     return client;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mondaydotcomorg/z2h-cli",
-  "version": "0.10.1",
+  "version": "0.11.1",
   "bin": "./bin/z2h-cli.js",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

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

@@ -5,9 +5,8 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { runYarnInstall } from '../../util/npm/install';
 import { initRepo, defaultS3Remote } from '../../util/git/repo';
-import { buildCommand } from '../build';
+import { prepareShadow } from '../../shadow/prepare';
 import { createCommand } from '../create';
-import * as manifest from '../../util/manifest';
 
 // Mock the install helper so `yarn install` (with its broker preflight) doesn't
 // actually run. Token-injection + 401 re-auth is covered in
@@ -21,12 +20,15 @@ vi.mock('../../util/git/repo', () => ({
   defaultS3Remote: vi.fn((app: string) => `s3://prod-use1-bigbrain-zth-mf-assets/mf-${app}/git`),
 }));
 
-// Mock build so tsc/yarn build don't run in tests.
-vi.mock('../build', () => ({
-  buildCommand: vi.fn().mockResolvedValue(undefined),
+// Mock shadow prep so the fs scaffolding doesn't run in tests.
+vi.mock('../../shadow/prepare', () => ({
+  prepareShadow: vi.fn().mockResolvedValue(undefined),
 }));
 
-vi.spyOn(manifest, 'readManifest').mockResolvedValue({});
+// 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),
+}));
 
 async function makeWorkspace(tmp: string): Promise<void> {
   await ensureDir(tmp);
@@ -47,7 +49,7 @@ describe('create', () => {
     vi.mocked(runYarnInstall).mockClear();
     vi.mocked(initRepo).mockClear();
     vi.mocked(defaultS3Remote).mockClear();
-    vi.mocked(buildCommand).mockClear();
+    vi.mocked(prepareShadow).mockClear();
   });
 
   afterEach(async () => {

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();
+  });
+});