@mondaydotcomorg/z2h-cli 0.10.0 → 0.11.0

package/dist/esm/util/git/repo.mjs

@@ -4,6 +4,14 @@ import { execa } from 'execa';
 import { BUCKET_WRITE_NAME } from '../../constants.mjs';
 import { mfAppName } from '../app-name.mjs';
 
+function execGit(args, dir, env) {
+    return 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);
@@ -11,28 +19,42 @@ class GitConflictError extends Error {
     }
 }
 const REQUIRED_GITIGNORE_ENTRIES = ['node_modules/', '.zth/', 'build/'];
+const LOCAL_HOOKS_DIR = '.zth/hooks';
 function defaultS3Remote(app) {
     return `s3://${BUCKET_WRITE_NAME}/${mfAppName(app)}/git`;
 }
 async function initRepo(dir, remote) {
     await ensureGitignore(dir);
-    await execa('git', ['init', '-b', 'master'], { cwd: dir });
-    await execa('git', ['add', '.'], { cwd: dir });
-    await execa('git', ['commit', '-m', 'Initial commit'], { cwd: dir });
-    await execa('git', ['remote', 'add', 'origin', remote], { cwd: dir });
+    await execGit(['init', '-b', 'master'], dir);
+    await overrideGlobalHooks(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('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('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('git', ['clone', remote, dir], { env: { ...process.env, ...env } });
+    await overrideGlobalHooks(dir);
 }
 async function safeBackupIfDirty(dir) {
     let status;
     try {
-        ({ stdout: status } = await execa('git', ['status', '--porcelain'], { cwd: dir }));
+        ({ stdout: status } = await execGit(['status', '--porcelain'], dir));
     }
     catch {
         return;
@@ -45,17 +67,55 @@ async function safeBackupIfDirty(dir) {
     const backupDir = path.join(path.dirname(dir), `${appName}.backup-${sha}`);
     await fs.copy(dir, backupDir, { overwrite: false });
 }
-async function pullAndResolve(dir) {
+async function pullAndResolve(dir, env) {
+    const gitEnv = env ? { ...process.env, ...env } : undefined;
     try {
-        await 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('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?');
@@ -63,42 +123,38 @@ async function remoteHead(dir) {
     return sha;
 }
 async function localHead(dir) {
-    const { stdout } = await 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('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('git', ['add', '.'], { cwd: dir });
-    const { stdout: staged } = await 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('git', ['commit', '-m', message], { cwd: dir });
-    try {
-        await execa('git', ['push', '-u', 'origin', 'master'], { cwd: dir });
+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 };
+}
+/**
+ * If the user has a global core.hooksPath (e.g. ~/.global-git-hooks with a
+ * prevent-push-to-master script), override it locally so Z2H's non-interactive
+ * pushes aren't blocked. Other repos on the machine stay protected.
+ */
+async function overrideGlobalHooks(dir) {
+    if (await fs.pathExists(path.join(dir, LOCAL_HOOKS_DIR))) {
+        return;
     }
-    catch (err) {
-        if (/\[rejected\]|non-fast-forward/.test(err.message)) {
-            throw new GitConflictError('push rejected — remote has new commits');
-        }
-        throw err;
+    const globalHooksPath = await execGit(['config', '--global', 'core.hooksPath'], dir)
+        .then(r => r.stdout.trim())
+        .catch(() => '');
+    if (!globalHooksPath) {
+        return;
     }
-}
-async function buildCommitMessage(dir, version) {
-    // TODO(Phase 7): replace with LLM-generated summary using git diff + commit messages
-    const { stdout } = await 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}`;
+    await fs.ensureDir(path.join(dir, LOCAL_HOOKS_DIR));
+    await execGit(['config', '--local', 'core.hooksPath', LOCAL_HOOKS_DIR], dir);
+    // eslint-disable-next-line no-console
+    console.warn(`⚠️  Detected global git hooks at ${globalHooksPath}\n` +
+        `   Overriding locally for this Z2H project (your other repos are unaffected).`);
 }
 async function ensureGitignore(dir) {
     const gitignorePath = path.join(dir, '.gitignore');
@@ -118,4 +174,4 @@ async function ensureGitignore(dir) {
     await fs.outputFile(gitignorePath, content + separator + missing.join('\n') + '\n');
 }
 
-export { GitConflictError, cloneRepo, commitDetailedAndPush, defaultS3Remote, getRemoteUrl, initRepo, localHead, pullAndResolve, remoteHead, safeBackupIfDirty };
+export { GitConflictError, cloneRepo, defaultS3Remote, getRemoteUrl, guardCleanTree, initRepo, localHead, pullAndResolve, pushToRemote, remoteHead, safeBackupIfDirty };

package/dist/esm/util/machine-identity.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Returns the machine app name when running as a service (e.g. agent-runner).
+ * Available when the process is a monday.com microservice with `APP_NAME` set
+ * by the platform runtime.
+ *
+ * Returns `undefined` for interactive human users (fallback to os.userInfo).
+ */
+export declare function getMachineAppName(): string | undefined;
+//# sourceMappingURL=machine-identity.d.ts.map

package/dist/esm/util/machine-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"machine-identity.d.ts","sourceRoot":"","sources":["../../../src/util/machine-identity.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,GAAG,SAAS,CAEtD"}

package/dist/esm/util/machine-identity.mjs

@@ -0,0 +1,12 @@
+/**
+ * Returns the machine app name when running as a service (e.g. agent-runner).
+ * Available when the process is a monday.com microservice with `APP_NAME` set
+ * by the platform runtime.
+ *
+ * Returns `undefined` for interactive human users (fallback to os.userInfo).
+ */
+function getMachineAppName() {
+    return process.env.APP_NAME || undefined;
+}
+
+export { getMachineAppName };

package/dist/esm/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/esm/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/esm/util/s3/client.mjs

@@ -1,21 +1,13 @@
 import { S3Client } from '@aws-sdk/client-s3';
-import { brokerCredentialProvider } from '../auth/broker-credential-provider.mjs';
 import { REGION } from '../../constants.mjs';
 
 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 S3Client({
-        region: REGION,
-        credentials: brokerCredentialProvider({ appName }),
-    });
+function setupS3Client(credentials) {
+    client = new S3Client({ region: 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/dist/index.js

@@ -1,19 +1,22 @@
 const node_module = require('node:module');
-const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 const commander = require('commander');
 const execa = require('execa');
+const util_workspace = require('./util/workspace.js');
 const commands_dev = require('./commands/dev.js');
 const commands_build = require('./commands/build.js');
 const commands_clean = require('./commands/clean.js');
 const commands_deploy = require('./commands/deploy.js');
+const commands_grant = require('./commands/grant.js');
 const commands_createWorkspace = require('./commands/create-workspace.js');
 const commands_create = require('./commands/create.js');
 const commands_generateZ2hToken = require('./commands/generate-z2h-token.js');
 const commands_migrate = require('./commands/migrate.js');
+const commands_edit = require('./commands/edit.js');
 const util_logger = require('./util/logger.js');
 const util_tracker = require('./util/tracker.js');
+const util_appName = require('./util/app-name.js');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 const _interopDefault = e => e && e.__esModule ? e : { default: e };
@@ -34,15 +37,14 @@ function selfUpdate() {
         util_logger.errorLog(`Z2H auto-update failed to start: ${err.message}`);
     }
 }
-function getCwdAppName() {
-    try {
-        return JSON.parse(fs.readFileSync('package.json', 'utf8')).name;
-    }
-    catch {
-        return undefined;
+const CONFLICTING_ENV_VARS = ['AWS_PROFILE'];
+function stripConflictingEnvVars() {
+    for (const name of CONFLICTING_ENV_VARS) {
+        delete process.env[name];
     }
 }
 async function main() {
+    stripConflictingEnvVars();
     const program = new commander.Command();
     program
         .name('z2h-cli')
@@ -65,7 +67,7 @@ async function main() {
         .option('--json', 'emit structured JSON on stdout')
         .action(async (opts) => {
         try {
-            await util_tracker.trackDuration('z2h_app_build_success', () => commands_build.buildCommand(opts), { app_name: getCwdAppName() });
+            await util_tracker.trackDuration('z2h_app_build_success', () => commands_build.buildCommand(opts), { app_name: util_appName.getCwdAppName() });
         }
         catch (err) {
             await util_logger.fail(`build failed: ${err.message}`, { command: 'build' }, 2);
@@ -97,13 +99,15 @@ async function main() {
     });
     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')
+        .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) => {
         try {
             await util_tracker.trackDuration('z2h_app_deploy_success', () => commands_deploy.deployCommand(opts), {
-                app_name: getCwdAppName(),
+                app_name: util_appName.getCwdAppName(),
             });
         }
         catch (err) {
@@ -112,7 +116,7 @@ async function main() {
     });
     program
         .command('create-workspace')
-        .description('Bootstrap the ~/zth-projects/ yarn workspace (one-time setup)')
+        .description(`Bootstrap the ${util_workspace.getWorkspaceHome()}/ yarn workspace (one-time setup)`)
         .option('--json', 'emit structured JSON on stdout')
         .action(async (opts) => {
         try {
@@ -138,7 +142,7 @@ async function main() {
     });
     program
         .command('create <app-name>')
-        .description('Scaffold a new Z2H consumer app inside ~/zth-projects/')
+        .description(`Scaffold a new Z2H consumer app inside ${util_workspace.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)')
@@ -156,6 +160,59 @@ async function main() {
             await util_logger.fail(`create failed: ${err.message}`, { command: 'create' }, 1);
         }
     });
+    program
+        .command('edit <app-name>')
+        .description(`Pull the latest version of an app into ${util_workspace.getWorkspaceHome()}/<app-name>, cloning it first if needed`)
+        .option('--json', 'emit structured JSON on stdout')
+        .action(async (appName, opts) => {
+        try {
+            await util_tracker.trackDuration('z2h_app_edit_pulled', () => commands_edit.editCommand(appName, opts), {
+                app_name: appName,
+            });
+        }
+        catch (err) {
+            await util_logger.fail(`edit failed: ${err.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, opts) => {
+        try {
+            await commands_grant.grantCommand(email, opts);
+        }
+        catch (err) {
+            await util_logger.fail(`grant failed: ${err.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, opts) => {
+        try {
+            await commands_grant.revokeCommand(email, opts);
+        }
+        catch (err) {
+            await util_logger.fail(`revoke failed: ${err.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, opts) => {
+        try {
+            await commands_grant.transferOwnerCommand(email, opts);
+        }
+        catch (err) {
+            await util_logger.fail(`transfer-owner failed: ${err.message}`, { command: 'transfer-owner' }, 1);
+        }
+    });
     program
         .command('migrate')
         .description('Run pending workspace migrations')

package/dist/shadow/prepare.d.ts

@@ -1,3 +1,3 @@
 import type { PreparedShadow } from '../types';
-export declare function prepareShadow(): Promise<PreparedShadow>;
+export declare function prepareShadow(consumerDir?: string): Promise<PreparedShadow>;
 //# sourceMappingURL=prepare.d.ts.map

package/dist/shadow/prepare.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prepare.d.ts","sourceRoot":"","sources":["../../src/shadow/prepare.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAA8B,cAAc,EAAkB,MAAM,UAAU,CAAC;AAE3F,wBAAsB,aAAa,IAAI,OAAO,CAAC,cAAc,CAAC,CAgC7D"}
+{"version":3,"file":"prepare.d.ts","sourceRoot":"","sources":["../../src/shadow/prepare.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAA8B,cAAc,EAAkB,MAAM,UAAU,CAAC;AAE3F,wBAAsB,aAAa,CAAC,WAAW,GAAE,MAAsB,GAAG,OAAO,CAAC,cAAc,CAAC,CAgChG"}

package/dist/shadow/prepare.js

@@ -11,8 +11,8 @@ const shadow_metadata = require('./metadata.js');
 const shadow_port = require('./port.js');
 const shadow_sync = require('./sync.js');
 
-async function prepareShadow() {
-    const paths = shadow_paths.resolveConsumerPaths(process.cwd());
+async function prepareShadow(consumerDir = process.cwd()) {
+    const paths = shadow_paths.resolveConsumerPaths(consumerDir);
     if (!(await fs.pathExists(paths.consumerPkg))) {
         throw new Error(`No package.json found in ${paths.consumerDir}`);
     }

package/dist/util/app-name.d.ts

@@ -3,6 +3,7 @@
  * e.g. `@trident/customer-viewer` → `customer-viewer`, `foo` → `foo`.
  */
 export declare function cleanAppName(name: string): string;
+export declare function getCwdAppName(): string | 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/dist/util/app-name.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app-name.d.ts","sourceRoot":"","sources":["../../src/util/app-name.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C"}
+{"version":3,"file":"app-name.d.ts","sourceRoot":"","sources":["../../src/util/app-name.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,wBAAgB,aAAa,IAAI,MAAM,GAAG,SAAS,CAMlD;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C"}

package/dist/util/app-name.js

@@ -1,5 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
+const fs = require('node:fs');
+
 /**
  * Strip any npm scope (`@scope/`) from a package name.
  * e.g. `@trident/customer-viewer` → `customer-viewer`, `foo` → `foo`.
@@ -7,6 +9,14 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 function cleanAppName(name) {
     return name.replace(/^@[^/]+\//, '');
 }
+function getCwdAppName() {
+    try {
+        return JSON.parse(fs.readFileSync('package.json', 'utf8')).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>`,
@@ -17,4 +27,5 @@ function mfAppName(name) {
 }
 
 exports.cleanAppName = cleanAppName;
+exports.getCwdAppName = getCwdAppName;
 exports.mfAppName = mfAppName;

package/dist/util/auth/auth-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth-store.d.ts","sourceRoot":"","sources":["../../../src/util/auth/auth-store.ts"],"names":[],"mappings":"AAOA,eAAO,MAAM,YAAY,QAAkC,CAAC;AAC5D,eAAO,MAAM,aAAa,QAAuC,CAAC;AAElE,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,qBAAa,mBAAoB,SAAQ,KAAK;aAChB,YAAY,EAAE,MAAM;gBAApB,YAAY,EAAE,MAAM;CAIjD;AAED,wBAAsB,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,CASpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,GAAG,IAAI,CAOpD"}
+{"version":3,"file":"auth-store.d.ts","sourceRoot":"","sources":["../../../src/util/auth/auth-store.ts"],"names":[],"mappings":"AAOA,eAAO,MAAM,YAAY,QAAkC,CAAC;AAC5D,eAAO,MAAM,aAAa,QAAuC,CAAC;AAElE,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,qBAAa,mBAAoB,SAAQ,KAAK;aAChB,YAAY,EAAE,MAAM;gBAApB,YAAY,EAAE,MAAM;CAIjD;AAED,wBAAsB,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,CAkBpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,GAAG,IAAI,CAUpD"}

package/dist/util/auth/auth-store.js

@@ -23,6 +23,13 @@ class Z2hAuthMissingError extends Error {
     }
 }
 async function readZthAuth() {
+    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 fs.pathExists(Z2H_AUTH_FILE))) {
         throw new Z2hAuthMissingError(Z2H_AUTH_FILE);
     }
@@ -42,6 +49,9 @@ async function readZthAuth() {
  * blow up — and where an inline sync read keeps the spawn call site simple.
  */
 function tryReadAuthTokenSync() {
+    if (process.env.Z2H_AUTH_TOKEN) {
+        return process.env.Z2H_AUTH_TOKEN;
+    }
     try {
         const parsed = fs.readJsonSync(Z2H_AUTH_FILE);
         return parsed?.token ?? null;

package/dist/util/auth/broker-credential-provider.d.ts

@@ -1,9 +1,17 @@
 import type { AwsCredentialIdentityProvider } from '@aws-sdk/types';
 export declare const STS_BROKER_PATH = "/z2h-cli/sts/credentials";
+export declare const DEPLOY_VERSION_PATH = "/z2h-cli/apps/version";
+/**
+ * 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 declare function fetchDeployVersion(appName: string): Promise<number>;
 /**
  * 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 declare function brokerCredentialProvider({ appName }: {
     appName: string;

package/dist/util/auth/broker-credential-provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"broker-credential-provider.d.ts","sourceRoot":"","sources":["../../../src/util/auth/broker-credential-provider.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAyB,6BAA6B,EAAE,MAAM,gBAAgB,CAAC;AAE3F,eAAO,MAAM,eAAe,6BAA6B,CAAC;AAwD1D;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,OAAO,EAAE,EAAE;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,6BAA6B,CAuBxG"}
+{"version":3,"file":"broker-credential-provider.d.ts","sourceRoot":"","sources":["../../../src/util/auth/broker-credential-provider.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAyB,6BAA6B,EAAE,MAAM,gBAAgB,CAAC;AAE3F,eAAO,MAAM,eAAe,6BAA6B,CAAC;AAC1D,eAAO,MAAM,mBAAmB,0BAA0B,CAAC;AA4C3D;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAUzE;AAuBD;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,OAAO,EAAE,EAAE;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,6BAA6B,CAuBxG"}

package/dist/util/auth/broker-credential-provider.js

@@ -4,31 +4,52 @@ const constants = require('../../constants.js');
 const util_auth_authStore = require('./auth-store.js');
 
 const STS_BROKER_PATH = '/z2h-cli/sts/credentials';
+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;
-async function fetchCredentialsOnce(appName) {
+async function postToBroker(path, body) {
     const { token } = await util_auth_authStore.readZthAuth();
-    const url = `${constants.brokerBaseUrl()}${STS_BROKER_PATH}`;
-    let res;
     try {
-        res = await fetch(url, {
+        return await fetch(`${constants.brokerBaseUrl()}${path}`, {
             method: 'POST',
             headers: {
                 Authorization: `Bearer ${token}`,
                 'Content-Type': 'application/json',
                 Accept: 'application/json',
+                ...constants.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) {
     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.
+ */
+async function fetchDeployVersion(appName) {
+    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());
+    return body.version ?? 0;
+}
+async function fetchStsOnce(appName) {
+    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)}`);
@@ -46,8 +67,9 @@ async function fetchCredentialsOnce(appName) {
 }
 /**
  * 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.
  */
 function brokerCredentialProvider({ appName }) {
     let cached;
@@ -60,10 +82,10 @@ function brokerCredentialProvider({ appName }) {
         if (inflight) {
             return inflight;
         }
-        inflight = fetchCredentialsOnce(appName)
-            .then(creds => {
-            cached = creds;
-            return creds;
+        inflight = fetchStsOnce(appName)
+            .then(credentials => {
+            cached = credentials;
+            return credentials;
         })
             .finally(() => {
             inflight = undefined;
@@ -72,5 +94,7 @@ function brokerCredentialProvider({ appName }) {
     };
 }
 
+exports.DEPLOY_VERSION_PATH = DEPLOY_VERSION_PATH;
 exports.STS_BROKER_PATH = STS_BROKER_PATH;
 exports.brokerCredentialProvider = brokerCredentialProvider;
+exports.fetchDeployVersion = fetchDeployVersion;