@mondaydotcomorg/z2h-cli 0.7.2 → 0.9.1

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

@@ -1,15 +1,15 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
 const promises = require('node:fs/promises');
-const fsExtra = require('fs-extra');
+const fs = require('fs-extra');
 const util_auth_authStore = require('./auth-store.js');
 
 // 0o600 — owner read/write only. The file holds a long-lived bearer token,
 // so other local users on the machine must not be able to read it.
 const OWNER_READ_WRITE_FILE_MODE = 0o600;
 async function writeZthAuth(auth) {
-    await fsExtra.ensureDir(util_auth_authStore.Z2H_AUTH_DIR);
-    await fsExtra.writeFile(util_auth_authStore.Z2H_AUTH_FILE, `${JSON.stringify(auth, null, 2)}\n`);
+    await fs.ensureDir(util_auth_authStore.Z2H_AUTH_DIR);
+    await fs.writeFile(util_auth_authStore.Z2H_AUTH_FILE, `${JSON.stringify(auth, null, 2)}\n`);
     await promises.chmod(util_auth_authStore.Z2H_AUTH_FILE, OWNER_READ_WRITE_FILE_MODE);
     return { filePath: util_auth_authStore.Z2H_AUTH_FILE };
 }

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=repo.test.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"repo.test.d.ts","sourceRoot":"","sources":["../../../../src/util/git/__tests__/repo.test.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,12 @@
+export declare class GitConflictError extends Error {
+    constructor(message: string);
+}
+export declare function defaultS3Remote(app: string): string;
+export declare function initAndPush(dir: string, remote: string): Promise<void>;
+export declare function cloneRepo(remote: string, dir: string): Promise<void>;
+export declare function safeBackupIfDirty(dir: string): Promise<void>;
+export declare function pullAndResolve(dir: 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

@@ -0,0 +1 @@
+{"version":3,"file":"repo.d.ts","sourceRoot":"","sources":["../../../src/util/git/repo.ts"],"names":[],"mappings":"AAKA,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,OAAO,EAAE,MAAM;CAI5B;AAID,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,wBAAsB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAO5E;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,CASvF"}

package/dist/util/git/repo.js

@@ -0,0 +1,120 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const path = require('node:path');
+const fs = require('fs-extra');
+const execa = require('execa');
+const constants = require('../../constants.js');
+
+const _interopDefault = e => e && e.__esModule ? e : { default: e };
+
+const path__default = /*#__PURE__*/_interopDefault(path);
+const fs__default = /*#__PURE__*/_interopDefault(fs);
+
+class GitConflictError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'GitConflictError';
+    }
+}
+const REQUIRED_GITIGNORE_ENTRIES = ['node_modules/', '.zth/', 'build/'];
+function defaultS3Remote(app) {
+    return `s3://${constants.BUCKET_WRITE_NAME}/${app}/git`;
+}
+async function initAndPush(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 execa.execa('git', ['push', '-u', 'origin', 'master'], { cwd: dir });
+}
+async function cloneRepo(remote, dir) {
+    await execa.execa('git', ['clone', remote, dir]);
+}
+async function safeBackupIfDirty(dir) {
+    let status;
+    try {
+        ({ stdout: status } = await execa.execa('git', ['status', '--porcelain'], { cwd: dir }));
+    }
+    catch {
+        return;
+    }
+    if (!status.trim()) {
+        return;
+    }
+    const sha = await localHead(dir).catch(() => 'unknown');
+    const appName = path__default.default.basename(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) {
+    try {
+        await execa.execa('git', ['pull', '--ff-only'], { cwd: dir });
+    }
+    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.');
+    }
+}
+async function remoteHead(dir) {
+    const { stdout } = await execa.execa('git', ['ls-remote', 'origin', 'refs/heads/master'], { cwd: dir });
+    const sha = stdout.split('\t')[0]?.trim();
+    if (!sha) {
+        throw new Error('could not read remote head — is the remote reachable?');
+    }
+    return sha;
+}
+async function localHead(dir) {
+    const { stdout } = await execa.execa('git', ['rev-parse', 'HEAD'], { cwd: dir });
+    return stdout.trim();
+}
+async function commitDetailedAndPush(dir, version) {
+    const message = await buildCommitMessage(dir, version);
+    await execa.execa('git', ['add', '.'], { cwd: dir });
+    await execa.execa('git', ['commit', '-m', message], { cwd: dir });
+    try {
+        await execa.execa('git', ['push'], { cwd: dir });
+    }
+    catch {
+        throw new GitConflictError('push rejected — remote has new commits');
+    }
+}
+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}`;
+}
+async function ensureGitignore(dir) {
+    const gitignorePath = path__default.default.join(dir, '.gitignore');
+    let content = '';
+    try {
+        content = await fs__default.default.readFile(gitignorePath, 'utf8');
+    }
+    catch {
+        // file doesn't exist yet
+    }
+    const lines = content.split('\n').map(l => l.trim());
+    const missing = REQUIRED_GITIGNORE_ENTRIES.filter(entry => !lines.includes(entry));
+    if (missing.length === 0) {
+        return;
+    }
+    const separator = content && !content.endsWith('\n') ? '\n' : '';
+    await fs__default.default.outputFile(gitignorePath, content + separator + missing.join('\n') + '\n');
+}
+
+exports.GitConflictError = GitConflictError;
+exports.cloneRepo = cloneRepo;
+exports.commitDetailedAndPush = commitDetailedAndPush;
+exports.defaultS3Remote = defaultS3Remote;
+exports.initAndPush = initAndPush;
+exports.localHead = localHead;
+exports.pullAndResolve = pullAndResolve;
+exports.remoteHead = remoteHead;
+exports.safeBackupIfDirty = safeBackupIfDirty;

package/dist/util/manifest.d.ts

@@ -18,6 +18,7 @@ export interface AssetManifestFile {
     nonExternalsEntrypoints?: string[];
     scriptType?: 'module' | 'classic';
     mfs?: string[];
+    gitRemote: string;
 }
 export interface ManifestEntry extends AssetManifestFile {
     version: number;

package/dist/util/manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/util/manifest.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,SAAS;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,OAAO,CAAC;IACpB,oBAAoB,EAAE,OAAO,CAAC;IAC9B,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,uBAAuB,CAAC,EAAE,MAAM,EAAE,CAAC;IACnC,UAAU,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;IAClC,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,MAAM,WAAW,aAAc,SAAQ,iBAAiB;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAErD,wBAAsB,YAAY,IAAI,OAAO,CAAC,QAAQ,CAAC,CAQtD;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,UAI1D;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,QAAQ,CAE3F;AAED,wBAAsB,aAAa,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAWrE"}
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/util/manifest.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,SAAS;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,OAAO,CAAC;IACpB,oBAAoB,EAAE,OAAO,CAAC;IAC9B,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,uBAAuB,CAAC,EAAE,MAAM,EAAE,CAAC;IACnC,UAAU,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;IAClC,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,aAAc,SAAQ,iBAAiB;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAErD,wBAAsB,YAAY,IAAI,OAAO,CAAC,QAAQ,CAAC,CAQtD;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,UAI1D;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,QAAQ,CAE3F;AAED,wBAAsB,aAAa,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAWrE"}

package/dist/util/s3/upload.js

@@ -2,7 +2,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
 const path = require('node:path');
 const promises = require('node:fs/promises');
-const fsExtra = require('fs-extra');
+const fs = require('fs-extra');
 const mimeTypes = require('mime-types');
 const pMap = require('p-map');
 const clientS3 = require('@aws-sdk/client-s3');
@@ -23,7 +23,7 @@ async function uploadDir(localDir, keyPrefix) {
     const files = entries.filter(e => e.isFile()).map(e => path__default.default.relative(localDir, path__default.default.join(e.parentPath, e.name)));
     const s3 = util_s3_client.getS3Client();
     await pMap__default.default(files, async (rel) => {
-        const body = await fsExtra.readFile(path__default.default.join(localDir, rel));
+        const body = await fs.readFile(path__default.default.join(localDir, rel));
         const contentType = mimeTypes.lookup(rel) || 'application/octet-stream';
         const key = `${keyPrefix}/${rel.split(path__default.default.sep).join('/')}`;
         await s3.send(new clientS3.PutObjectCommand({

package/dist/util/workspace.js

@@ -2,7 +2,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
 const path = require('node:path');
 const os = require('node:os');
-const fsExtra = require('fs-extra');
+const fs = require('fs-extra');
 
 const _interopDefault = e => e && e.__esModule ? e : { default: e };
 
@@ -26,11 +26,11 @@ function getWorkspaceHome() {
  */
 async function isZ2hWorkspace(dir) {
     const pkgPath = path__default.default.join(dir, 'package.json');
-    if (!(await fsExtra.pathExists(pkgPath))) {
+    if (!(await fs.pathExists(pkgPath))) {
         return false;
     }
     try {
-        const pkg = (await fsExtra.readJson(pkgPath));
+        const pkg = (await fs.readJson(pkgPath));
         return pkg[WORKSPACE_MARKER_FIELD] === true;
     }
     catch {

package/package.json

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

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

@@ -31,7 +31,7 @@ describe('create-workspace', () => {
   });
 
   it('creates package.json with the marker, gitignore, README, then runs yarn install', async () => {
-    await createWorkspaceCommand({});
+    await createWorkspaceCommand();
 
     const pkgPath = path.join(tmp, 'package.json');
     expect(await pathExists(pkgPath)).toBe(true);
@@ -55,19 +55,19 @@ describe('create-workspace', () => {
     await ensureDir(tmp);
     await writeJson(path.join(tmp, 'somefile.json'), { hello: 'world' });
 
-    await expect(createWorkspaceCommand({})).rejects.toThrow(/Workspace already exists/);
+    await expect(createWorkspaceCommand()).rejects.toThrow(/Workspace already exists/);
     expect(runYarnInstall).not.toHaveBeenCalled();
   });
 
   it('does not include z2h-cli in workspace devDeps (managed globally)', async () => {
-    await createWorkspaceCommand({});
+    await createWorkspaceCommand();
 
     const pkg = await readJson(path.join(tmp, 'package.json'));
     expect(pkg.devDependencies['@mondaydotcomorg/z2h-cli']).toBeUndefined();
   });
 
   it('ships the yarn berry release inline so any `yarn` invocation runs 4.x without corepack', async () => {
-    await createWorkspaceCommand({});
+    await createWorkspaceCommand();
 
     expect(await pathExists(path.join(tmp, '.yarn', 'releases', 'yarn-4.5.1.cjs'))).toBe(true);
   });

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

@@ -4,6 +4,7 @@ import { mkdtemp, rm, writeJson, readJson, ensureDir, pathExists, writeFile } fr
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { runYarnInstall } from '../../util/npm/install';
+import { buildCommand } from '../build';
 import { createCommand } from '../create';
 import * as manifest from '../../util/manifest';
 
@@ -14,6 +15,11 @@ vi.mock('../../util/npm/install', () => ({
   runYarnInstall: vi.fn().mockResolvedValue(undefined),
 }));
 
+// Mock build so tsc/yarn build don't run in tests.
+vi.mock('../build', () => ({
+  buildCommand: vi.fn().mockResolvedValue(undefined),
+}));
+
 vi.spyOn(manifest, 'readManifest').mockResolvedValue({});
 
 async function makeWorkspace(tmp: string): Promise<void> {
@@ -33,6 +39,7 @@ describe('create', () => {
     tmp = await mkdtemp(path.join(os.tmpdir(), 'z2h-c-'));
     process.env.Z2H_WORKSPACE_HOME = tmp;
     vi.mocked(runYarnInstall).mockClear();
+    vi.mocked(buildCommand).mockClear();
   });
 
   afterEach(async () => {
@@ -41,14 +48,14 @@ describe('create', () => {
   });
 
   it('refuses when there is no workspace marker', async () => {
-    await expect(createCommand('demo-app', {})).rejects.toThrow(/create-workspace/);
+    await expect(createCommand('demo-app')).rejects.toThrow(/create-workspace/);
     expect(runYarnInstall).not.toHaveBeenCalled();
   });
 
   it('rejects invalid app names', async () => {
     await makeWorkspace(tmp);
-    await expect(createCommand('Invalid_Name', {})).rejects.toThrow(/lowercase kebab-case/);
-    await expect(createCommand('1starts-with-digit', {})).rejects.toThrow(/lowercase kebab-case/);
+    await expect(createCommand('Invalid_Name')).rejects.toThrow(/lowercase kebab-case/);
+    await expect(createCommand('1starts-with-digit')).rejects.toThrow(/lowercase kebab-case/);
   });
 
   it('refuses when the target app dir already exists and is non-empty', async () => {
@@ -56,12 +63,12 @@ describe('create', () => {
     const appDir = path.join(tmp, 'demo-app');
     await ensureDir(appDir);
     await writeFile(path.join(appDir, 'something.txt'), 'hi');
-    await expect(createCommand('demo-app', {})).rejects.toThrow(/non-empty/);
+    await expect(createCommand('demo-app')).rejects.toThrow(/non-empty/);
   });
 
   it('scaffolds an app with the default React template', async () => {
     await makeWorkspace(tmp);
-    await createCommand('demo-app', {});
+    await createCommand('demo-app');
 
     const appDir = path.join(tmp, 'demo-app');
     expect(await pathExists(path.join(appDir, 'package.json'))).toBe(true);

package/src/commands/build.ts

@@ -8,7 +8,8 @@ export interface BuildOptions {
   publicUrl?: string;
 }
 
-export async function buildCommand(opts: BuildOptions): Promise<void> {
+// Should be run from the consumer app directory — uses process.cwd() to locate it.
+export async function buildCommand(opts: BuildOptions = {}): Promise<void> {
   if (opts.json) {
     setOutputMode('json');
   }

package/src/commands/clean.ts

@@ -6,7 +6,8 @@ export interface CleanOptions {
   json?: boolean;
 }
 
-export async function cleanCommand(opts: CleanOptions): Promise<void> {
+// Should be run from the consumer app directory — uses process.cwd() to locate it.
+export async function cleanCommand(opts: CleanOptions = {}): Promise<void> {
   if (opts.json) {
     setOutputMode('json');
   }

package/src/commands/create-workspace.ts

@@ -10,7 +10,7 @@ export interface CreateWorkspaceOptions {
   json?: boolean;
 }
 
-export async function createWorkspaceCommand(opts: CreateWorkspaceOptions): Promise<void> {
+export async function createWorkspaceCommand(opts: CreateWorkspaceOptions = {}): Promise<void> {
   if (opts.json) {
     setOutputMode('json');
   }

package/src/commands/create.ts

@@ -1,13 +1,14 @@
 import path from 'node:path';
 import { readFile } from 'node:fs/promises';
 import { ensureDir, pathExists, readdir, writeFile, copy } from 'fs-extra';
-import { info, output, setOutputMode } from '../util/logger';
+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 { buildCommand } from './build';
 
 export interface CreateOptions {
   template?: string;
@@ -42,7 +43,7 @@ async function isDirEmpty(dir: string): Promise<boolean> {
   return entries.length === 0;
 }
 
-export async function createCommand(appName: string, opts: CreateOptions): Promise<void> {
+export async function createCommand(appName: string, opts: CreateOptions = {}): Promise<void> {
   if (opts.json) {
     setOutputMode('json');
   }
@@ -118,6 +119,18 @@ export async function createCommand(appName: string, opts: CreateOptions): Promi
   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();
+  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);
+  }
+
   output(`[z2h-cli] app ready at ${appDir}`, {
     ok: true,
     appDir,

package/src/commands/deploy.ts

@@ -1,7 +1,7 @@
 import path from 'node:path';
 import os from 'node:os';
 import { pathExists, readJson } from 'fs-extra';
-import { info, output, setOutputMode } from '../util/logger';
+import { info, output, setOutputMode, warn } from '../util/logger';
 import { resolveConsumerPaths } from '../shadow/paths';
 import {
   nextVersion,
@@ -12,7 +12,7 @@ import {
   type ManifestEntry,
 } from '../util/manifest';
 import { uploadDir } from '../util/s3/upload';
-import { BUCKET_WRITE_NAME, BUCKET_READ_DNS_URL } from '../constants';
+import { BUCKET_WRITE_NAME, BUCKET_READ_DNS_URL, brokerBaseUrl } from '../constants';
 import { setupS3Client } from '../util/s3/client';
 import { readZthAuth } from '../util/auth/auth-store';
 import { cleanAppName, mfAppName } from '../util/app-name';
@@ -23,7 +23,8 @@ export interface DeployOptions {
   json?: boolean;
 }
 
-export async function deployCommand(opts: DeployOptions): Promise<void> {
+// Should be run from the consumer app directory — uses process.cwd() to locate it.
+export async function deployCommand(opts: DeployOptions = {}): Promise<void> {
   if (opts.json) {
     setOutputMode('json');
   }
@@ -37,7 +38,7 @@ 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.
-  await readZthAuth();
+  const { token } = await readZthAuth();
   setupS3Client({ appName });
 
   info('reading current Z2H manifest');
@@ -82,11 +83,19 @@ export async function deployCommand(opts: DeployOptions): Promise<void> {
     return;
   }
 
-  info(`uploading build → s3://${BUCKET_WRITE_NAME}/${keyPrefix}/`);
-  await uploadDir(paths.shadowBuild, keyPrefix);
+  try {
+    // Lock is acquired here — uploadDir triggers the STS credential provider on first S3 call
+    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(`updating manifest entry "${appName}" → v${version}`);
+    await writeManifest(upsertEntry(manifest, appName, entry));
+
+    info(`registering app "${appName}" → v${version}`);
+    await registerApp(appName, token, version, entry);
+  } finally {
+    await releaseLockBestEffort(appName, token);
+  }
 
   // The host MF parses the app name from the URL and prepends `mf-` itself
   // before looking it up in the manifest. So the user-facing URL must use
@@ -103,3 +112,29 @@ export async function deployCommand(opts: DeployOptions): Promise<void> {
     entry,
   });
 }
+
+async function registerApp(appName: string, token: string, version: number, entry: ManifestEntry): 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 }),
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`App registration failed (${res.status}): ${text.slice(0, 1024)}`);
+  }
+}
+
+// best-effort — the 5-min TTL backstop handles failures
+async function releaseLockBestEffort(appName: string, token: string): Promise<void> {
+  try {
+    await fetch(`${brokerBaseUrl()}/z2h-cli/lock/release`, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify({ appName }),
+    });
+    info(`lock released for ${appName}`);
+  } catch {
+    warn(`failed to release lock for ${appName}`);
+  }
+}

package/src/commands/dev.ts

@@ -15,7 +15,8 @@ export interface DevOptions {
 
 const TRIDENT_READY_PATTERN = /Server started at/i;
 
-export async function devCommand(opts: DevOptions): Promise<void> {
+// Should be run from the consumer app directory — uses process.cwd() to locate it.
+export async function devCommand(opts: DevOptions = {}): Promise<void> {
   if (opts.json) {
     setOutputMode('json');
   }
@@ -31,6 +32,9 @@ export async function devCommand(opts: DevOptions): Promise<void> {
   const server = execa('yarn', ['start'], {
     cwd: ctx.paths.shadowDir,
     stdio: ['inherit', 'pipe', 'inherit'],
+    // Trident requires NPM_TOKEN to be set or it refuses to start; 'FAKE_TOKEN' satisfies the check without real credentials.
+    // we always pass a fake token for same behavior for all users (no matter if they have a token or not)
+    env: { ...process.env, NPM_TOKEN: 'FAKE_TOKEN' },
   });
 
   const pidFile = path.join(ctx.paths.shadowDir, 'dev.pid');

package/src/commands/migrate.ts

@@ -6,7 +6,7 @@ export interface MigrateOptions {
   json?: boolean;
 }
 
-export async function migrateCommand(cliVersion: string, opts: MigrateOptions): Promise<void> {
+export async function migrateCommand(cliVersion: string, opts: MigrateOptions = {}): Promise<void> {
   if (opts.json) {
     setOutputMode('json');
   }

package/src/index.ts

@@ -21,7 +21,10 @@ const UPDATE_SCRIPT = path.join(os.homedir(), 'Development', 'bigbrain-z2h', 'z2
 
 function selfUpdate(): void {
   try {
-    execa('bash', [UPDATE_SCRIPT], { detached: true, stdio: 'ignore' }).unref();
+    execa('bash', [UPDATE_SCRIPT], {
+      detached: true,
+      stdio: 'ignore',
+    }).unref();
   } catch (err) {
     errorLog(`Z2H auto-update failed to start: ${(err as Error).message}`);
   }

package/src/migrations/auto-migrate.ts

@@ -1,10 +1,10 @@
-import path from 'node:path';
 import { createRequire } from 'node:module';
+import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { pathExists, readJson, writeJson, writeFile } from 'fs-extra';
+import { pathExists, readJson, writeFile, writeJson } from 'fs-extra';
 import { execa } from 'execa';
 import semver from 'semver';
-import { info, warn, errorLog } from '../util/logger';
+import { errorLog, info, warn } from '../util/logger';
 import { getWorkspaceHome, isZ2hWorkspace } from '../util/workspace';
 
 const STATE_FILE = '.z2h-migrations-state.json';

package/src/templates/app/CLAUDE.md

@@ -27,7 +27,9 @@ The orchestrator routes to `z2h:feature-development`, which handles the typechec
 
 ## 🌟 Data-Fetching Hierarchy
 
-When a request needs data, follow `z2h:coding-standards-mf` §0: write a `runQuery` helper for Snowflake data (TS module using `getBigBrainAPI()` for React apps; vanilla `<script>` using `window.location.origin` for html-embed apps), write a client-side fetch for other browser-accessible sources, or tell the user to reach out at `#ask-zero-to-hero` if the data needs an API key or server-side access. Backend changes to `bigbrain-zth` are not in scope.
+When a request needs data, follow `z2h:coding-standards-mf` §0: write a `runQuery` helper for Snowflake data (TS module using `getBigBrainAPI()` for React apps; vanilla `<script>` using `window.location.origin` for html-embed apps), write a client-side fetch for other browser-accessible sources, or tell the user to reach out at `#ask-zero-to-hero` if the data needs an API key or server-side access. Backend changes to `bigbrain-zth` are not in scope — no modifications, no suggestions, no workarounds.
+
+**Query storage:** All SQL query strings go in `src/queries.ts`, not inline in components or hooks. Import from there.
 
 ---
 

package/src/templates/app/claude-settings.json

@@ -10,7 +10,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "if [ -f .zth/dev.pid ]; then kill $(cat .zth/dev.pid) 2>/dev/null; rm .zth/dev.pid; fi"
+            "command": "if [ -f .zth/dev.pid ]; then PGID=$(ps -o pgid= -p $(cat .zth/dev.pid) 2>/dev/null | tr -d ' '); [ -n \"$PGID\" ] && kill -- -$PGID 2>/dev/null; rm -f .zth/dev.pid; fi"
           }
         ]
       }