@mondaydotcomorg/z2h-cli 0.1.0

package/dist/shadow/yarnrc.js

@@ -0,0 +1,33 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const path = require('node:path');
+const fsExtra = require('fs-extra');
+const constants = require('../constants.js');
+
+const _interopDefault = e => e && e.__esModule ? e : { default: e };
+
+const path__default = /*#__PURE__*/_interopDefault(path);
+
+/**
+ * Ensure the consumer has a `.yarnrc.yml` that pins `nodeLinker: node-modules`.
+ *
+ * Yarn 4 defaults to PnP, which trident-toolkit's webpack pipeline doesn't
+ * support cleanly (webpack expects a flat node_modules). We force the
+ * classic linker so installs produce a real `node_modules/`. Idempotent —
+ * leaves any other settings the user added alone.
+ */
+async function ensureYarnRc(consumerDir) {
+    const yarnrcPath = path__default.default.join(consumerDir, '.yarnrc.yml');
+    if (!(await fsExtra.pathExists(yarnrcPath))) {
+        await fsExtra.writeFile(yarnrcPath, constants.YARNRC_LINES.join('\n\n') + '\n');
+        return;
+    }
+    const body = await fsExtra.readFile(yarnrcPath, 'utf8');
+    if (/^\s*nodeLinker\s*:/m.test(body)) {
+        return;
+    }
+    const prefix = body.length && !body.endsWith('\n') ? '\n' : '';
+    await fsExtra.writeFile(yarnrcPath, body + prefix + 'nodeLinker: node-modules\n');
+}
+
+exports.ensureYarnRc = ensureYarnRc;

package/dist/types.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Shared domain types for the Z2H CLI. Command-scoped option types live
+ * with their command; narrow single-use types stay local to their file.
+ */
+export interface ConsumerPkg {
+    name: string;
+    version?: string;
+    private?: boolean;
+    workspaces?: string[] | {
+        packages?: string[];
+    };
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+    peerDependencies?: Record<string, string>;
+    scripts?: Record<string, string>;
+    [k: string]: unknown;
+}
+export interface ShadowPkg {
+    name: string;
+    version: string;
+    private: true;
+    scripts: Record<string, string>;
+    peerDependencies: Record<string, string>;
+    devDependencies: Record<string, string>;
+}
+export interface ShadowMetadata {
+    createdAt: string;
+    appName: string;
+    port: number;
+}
+export interface ConsumerPaths {
+    consumerDir: string;
+    consumerPkg: string;
+    consumerSrc: string;
+    consumerSrcEntry: string;
+    shadowDir: string;
+    shadowPkg: string;
+    shadowSrc: string;
+    shadowWrapper: string;
+    shadowTridentrc: string;
+    shadowNvmrc: string;
+    shadowDts: string;
+    shadowTsconfig: string;
+    shadowBuild: string;
+    shadowDepsHash: string;
+    shadowMetadata: string;
+}
+export interface PreparedShadow {
+    appName: string;
+    port: number;
+    paths: ConsumerPaths;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,EAAE,GAAG;QAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAChD,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAGD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,IAAI,CAAC;IACd,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzC;AAGD,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AAGD,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;CACxB;AAGD,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,aAAa,CAAC;CACtB"}

package/dist/types.js

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,12 @@
+/**
+ * Strip any npm scope (`@scope/`) from a package name.
+ * e.g. `@trident/customer-viewer` → `customer-viewer`, `foo` → `foo`.
+ */
+export declare function cleanAppName(name: string): string;
+/**
+ * Canonical MF bundle name: the de-scoped app name with an `mf-` prefix.
+ * This matches the trident convention (shadow pkg is `@trident/mf-<app>`,
+ * emitted bundle is `MF-mf-<app>`).
+ */
+export declare function mfAppName(name: string): string;
+//# sourceMappingURL=app-name.d.ts.map

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

@@ -0,0 +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"}

package/dist/util/app-name.js

@@ -0,0 +1,20 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+/**
+ * Strip any npm scope (`@scope/`) from a package name.
+ * e.g. `@trident/customer-viewer` → `customer-viewer`, `foo` → `foo`.
+ */
+function cleanAppName(name) {
+    return name.replace(/^@[^/]+\//, '');
+}
+/**
+ * Canonical MF bundle name: the de-scoped app name with an `mf-` prefix.
+ * This matches the trident convention (shadow pkg is `@trident/mf-<app>`,
+ * emitted bundle is `MF-mf-<app>`).
+ */
+function mfAppName(name) {
+    return `mf-${cleanAppName(name)}`;
+}
+
+exports.cleanAppName = cleanAppName;
+exports.mfAppName = mfAppName;

package/dist/util/logger.d.ts

@@ -0,0 +1,22 @@
+export type OutputMode = 'human' | 'json';
+export declare function setOutputMode(next: OutputMode): void;
+export declare function getOutputMode(): OutputMode;
+/**
+ * Progress, info, and warnings go to stderr so stdout stays clean
+ * for machine-readable output. Always suppressed in JSON mode except
+ * when the consumer explicitly wants chatty progress (e.g. setup).
+ */
+export declare function info(msg: string): void;
+export declare function warn(msg: string): void;
+export declare function errorLog(msg: string): void;
+/**
+ * Data output. In human mode writes `human` to stdout; in JSON mode writes
+ * JSON-stringified `data` to stdout. Exactly one line of stdout per call.
+ */
+export declare function output(human: string, data: unknown): void;
+/**
+ * Emit a structured failure payload (JSON mode) or a red error line (human mode),
+ * then exit with the given code.
+ */
+export declare function fail(message: string, payload: Record<string, unknown>, exitCode?: number): never;
+//# sourceMappingURL=logger.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/util/logger.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,MAAM,CAAC;AAI1C,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAEpD;AAED,wBAAgB,aAAa,IAAI,UAAU,CAE1C;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAItC;AAED,wBAAgB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAItC;AAED,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAI1C;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAMzD;AAED;;;GAGG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,SAAI,GAAG,KAAK,CAU3F"}

package/dist/util/logger.js

@@ -0,0 +1,71 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const pc = require('picocolors');
+
+const _interopDefault = e => e && e.__esModule ? e : { default: e };
+
+const pc__default = /*#__PURE__*/_interopDefault(pc);
+
+let mode = 'human';
+function setOutputMode(next) {
+    mode = next;
+}
+function getOutputMode() {
+    return mode;
+}
+/**
+ * Progress, info, and warnings go to stderr so stdout stays clean
+ * for machine-readable output. Always suppressed in JSON mode except
+ * when the consumer explicitly wants chatty progress (e.g. setup).
+ */
+function info(msg) {
+    if (mode === 'human') {
+        process.stderr.write(pc__default.default.cyan(`[z2h-cli] ${msg}\n`));
+    }
+}
+function warn(msg) {
+    if (mode === 'human') {
+        process.stderr.write(pc__default.default.yellow(`[z2h-cli] ${msg}\n`));
+    }
+}
+function errorLog(msg) {
+    if (mode === 'human') {
+        process.stderr.write(pc__default.default.red(`[z2h-cli] ${msg}\n`));
+    }
+}
+/**
+ * Data output. In human mode writes `human` to stdout; in JSON mode writes
+ * JSON-stringified `data` to stdout. Exactly one line of stdout per call.
+ */
+function output(human, data) {
+    if (mode === 'json') {
+        process.stdout.write(`${JSON.stringify(data)}\n`);
+    }
+    else {
+        process.stdout.write(`${human}\n`);
+    }
+}
+/**
+ * Emit a structured failure payload (JSON mode) or a red error line (human mode),
+ * then exit with the given code.
+ */
+function fail(message, payload, exitCode = 1) {
+    if (mode === 'json') {
+        process.stdout.write(`${JSON.stringify({ ok: false, error: message, ...payload })}\n`);
+    }
+    else {
+        process.stderr.write(pc__default.default.red(`[z2h-cli] ${message}\n`));
+        if (typeof payload.suggestedCommand === 'string') {
+            process.stderr.write(pc__default.default.dim(`  → ${payload.suggestedCommand}\n`));
+        }
+    }
+    process.exit(exitCode);
+}
+
+exports.errorLog = errorLog;
+exports.fail = fail;
+exports.getOutputMode = getOutputMode;
+exports.info = info;
+exports.output = output;
+exports.setOutputMode = setOutputMode;
+exports.warn = warn;

package/dist/util/manifest.d.ts

@@ -0,0 +1,31 @@
+export interface SharedDep {
+    name?: string;
+    globalName: string;
+    url?: string;
+    minVersion?: string;
+    dependencies: Record<string, number>;
+}
+/**
+ * Shape of the `asset-manifest.json` trident-toolkit emits alongside the
+ * bundle. We consume this file directly as the base for a Z2H registry
+ * entry — deploy.ts only overlays `version` and `url`.
+ */
+export interface AssetManifestFile {
+    sameAsHost: boolean;
+    skipTranslationFetch: boolean;
+    shared: SharedDep[];
+    entrypoints: string[];
+    nonExternalsEntrypoints?: string[];
+    scriptType?: 'module' | 'classic';
+    mfs?: string[];
+}
+export interface ManifestEntry extends AssetManifestFile {
+    version: number;
+    url: string;
+}
+export type Manifest = Record<string, ManifestEntry>;
+export declare function readManifest(): Promise<Manifest>;
+export declare function nextVersion(manifest: Manifest, app: string): number;
+export declare function upsertEntry(manifest: Manifest, app: string, entry: ManifestEntry): Manifest;
+export declare function writeManifest(manifest: Manifest): Promise<void>;
+//# sourceMappingURL=manifest.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/util/manifest.ts"],"names":[],"mappings":"AAGA,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;CACb;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/manifest.js

@@ -0,0 +1,36 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const clientS3 = require('@aws-sdk/client-s3');
+const util_s3_client = require('./s3/client.js');
+
+async function readManifest() {
+    // Read via the public CDN endpoint, no AWS auth required.
+    const res = await fetch(util_s3_client.MANIFEST_READ_URL);
+    if (!res.ok) {
+        throw new Error(`failed to read manifest from ${util_s3_client.MANIFEST_READ_URL}: HTTP ${res.status}`);
+    }
+    return (await res.json());
+}
+function nextVersion(manifest, app) {
+    const current = manifest[app]?.version;
+    const n = current ? Number(current) : 0;
+    return (Number.isNaN(n) ? 0 : n) + 1;
+}
+function upsertEntry(manifest, app, entry) {
+    return { ...manifest, [app]: entry };
+}
+async function writeManifest(manifest) {
+    const s3 = util_s3_client.getS3Client();
+    await s3.send(new clientS3.PutObjectCommand({
+        Bucket: util_s3_client.BUCKET_WRITE_NAME,
+        Key: util_s3_client.MANIFEST_KEY,
+        Body: JSON.stringify(manifest, null, 2),
+        ContentType: 'application/json',
+        CacheControl: 'no-cache',
+    }));
+}
+
+exports.nextVersion = nextVersion;
+exports.readManifest = readManifest;
+exports.upsertEntry = upsertEntry;
+exports.writeManifest = writeManifest;

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

@@ -0,0 +1,11 @@
+import { S3Client } from '@aws-sdk/client-s3';
+export declare const BUCKET_WRITE_NAME = "prod-use1-bigbrain-zth-mf-assets";
+export declare const REGION = "us-east-1";
+export declare const BUCKET_WRITE_URL = "https://prod-use1-bigbrain-zth-mf-assets.s3.us-east-1.amazonaws.com";
+export declare const BUCKET_READ_DNS_NAME = "bigbrain-zth-mf-assets";
+export declare const BUCKET_READ_DNS_URL = "https://bigbrain-zth-mf-assets.bigbrain.me";
+export declare const MANIFEST_KEY = "mf-assets";
+export declare const MANIFEST_READ_URL = "https://bigbrain-zth-mf-assets.bigbrain.me/mf-assets";
+export declare function getS3Client(): S3Client;
+export declare function assertBucketExists(): Promise<void>;
+//# sourceMappingURL=client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/util/s3/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,QAAQ,EAAsB,MAAM,oBAAoB,CAAC;AAErF,eAAO,MAAM,iBAAiB,qCAAqC,CAAC;AACpE,eAAO,MAAM,MAAM,cAAc,CAAC;AAClC,eAAO,MAAM,gBAAgB,wEAA4D,CAAC;AAE1F,eAAO,MAAM,oBAAoB,2BAA2B,CAAC;AAC7D,eAAO,MAAM,mBAAmB,+CAAgD,CAAC;AAKjF,eAAO,MAAM,YAAY,cAAc,CAAC;AACxC,eAAO,MAAM,iBAAiB,yDAA2C,CAAC;AAI1E,wBAAgB,WAAW,IAAI,QAAQ,CAKtC;AAED,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC,CAexD"}

package/dist/util/s3/client.js

@@ -0,0 +1,48 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const clientS3 = require('@aws-sdk/client-s3');
+
+const BUCKET_WRITE_NAME = 'prod-use1-bigbrain-zth-mf-assets';
+const REGION = 'us-east-1';
+const BUCKET_WRITE_URL = `https://${BUCKET_WRITE_NAME}.s3.${REGION}.amazonaws.com`;
+const BUCKET_READ_DNS_NAME = 'bigbrain-zth-mf-assets';
+const BUCKET_READ_DNS_URL = `https://${BUCKET_READ_DNS_NAME}.bigbrain.me`;
+// No `.json` extension — TridentSkeleton's `mfUrl` API appends `/mf-assets`
+// to the bucket base when fetching, so the manifest must live at this exact
+// key. See microfrontends/mf-bigbrain-zth/.../ZeroToHeroHost.tsx.
+const MANIFEST_KEY = 'mf-assets';
+const MANIFEST_READ_URL = `${BUCKET_READ_DNS_URL}/${MANIFEST_KEY}`;
+let client = null;
+function getS3Client() {
+    if (!client) {
+        client = new clientS3.S3Client({ region: REGION });
+    }
+    return client;
+}
+async function assertBucketExists() {
+    try {
+        await getS3Client().send(new clientS3.HeadBucketCommand({ Bucket: BUCKET_WRITE_NAME }));
+    }
+    catch (err) {
+        if (err instanceof clientS3.S3ServiceException) {
+            const status = err.$metadata.httpStatusCode;
+            if (status === 404 || err.name === 'NotFound' || err.name === 'NoSuchBucket') {
+                throw new Error(`S3 bucket "${BUCKET_WRITE_NAME}" does not exist (region: ${REGION}).`);
+            }
+            if (status === 403) {
+                throw new Error(`No access to S3 bucket "${BUCKET_WRITE_NAME}" (region: ${REGION}). Check AWS credentials.`);
+            }
+        }
+        throw err;
+    }
+}
+
+exports.BUCKET_READ_DNS_NAME = BUCKET_READ_DNS_NAME;
+exports.BUCKET_READ_DNS_URL = BUCKET_READ_DNS_URL;
+exports.BUCKET_WRITE_NAME = BUCKET_WRITE_NAME;
+exports.BUCKET_WRITE_URL = BUCKET_WRITE_URL;
+exports.MANIFEST_KEY = MANIFEST_KEY;
+exports.MANIFEST_READ_URL = MANIFEST_READ_URL;
+exports.REGION = REGION;
+exports.assertBucketExists = assertBucketExists;
+exports.getS3Client = getS3Client;

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

@@ -0,0 +1,2 @@
+export declare function uploadDir(localDir: string, keyPrefix: string): Promise<string[]>;
+//# sourceMappingURL=upload.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"upload.d.ts","sourceRoot":"","sources":["../../../src/util/s3/upload.ts"],"names":[],"mappings":"AAcA,wBAAsB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CA0BtF"}

package/dist/util/s3/upload.js

@@ -0,0 +1,39 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const path = require('node:path');
+const fsExtra = require('fs-extra');
+const promises = require('node:fs/promises');
+const mimeTypes = require('mime-types');
+const pMap = require('p-map');
+const clientS3 = require('@aws-sdk/client-s3');
+const util_s3_client = require('./client.js');
+
+const _interopDefault = e => e && e.__esModule ? e : { default: e };
+
+const path__default = /*#__PURE__*/_interopDefault(path);
+const pMap__default = /*#__PURE__*/_interopDefault(pMap);
+
+// Each deploy uploads to a version-prefixed path (<app>/<version>/...), so
+// the URL itself is the cache key. Assets never need to be revalidated.
+const FOREVER = 'public, immutable';
+const UPLOAD_CONCURRENCY = 5;
+async function uploadDir(localDir, keyPrefix) {
+    const entries = await promises.readdir(localDir, { recursive: true, withFileTypes: true });
+    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 contentType = mimeTypes.lookup(rel) || 'application/octet-stream';
+        const key = `${keyPrefix}/${rel.split(path__default.default.sep).join('/')}`;
+        await s3.send(new clientS3.PutObjectCommand({
+            Bucket: util_s3_client.BUCKET_WRITE_NAME,
+            Key: key,
+            Body: body,
+            ContentType: contentType,
+            CacheControl: FOREVER,
+        }));
+    }, { concurrency: UPLOAD_CONCURRENCY });
+    return files.map(f => f.split(path__default.default.sep).join('/'));
+}
+
+exports.uploadDir = uploadDir;

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@mondaydotcomorg/z2h-cli",
+  "version": "0.1.0",
+  "bin": "./bin/z2h-cli.js",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "nx": {
+    "name": "z2h-cli",
+    "tags": [
+      "type:package",
+      "package"
+    ]
+  },
+  "scripts": {
+    "test": "echo noop",
+    "lint": "trident-library lint",
+    "build": "trident-library build",
+    "watch": "trident-library build -w"
+  },
+  "files": [
+    "bin/",
+    "dist/",
+    "src/"
+  ],
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.706.0",
+    "chokidar": "^3.6.0",
+    "commander": "^12.1.0",
+    "execa": "^9.5.1",
+    "fs-extra": "^11.2.0",
+    "mime-types": "^2.1.35",
+    "p-map": "^7.0.2",
+    "picocolors": "^1.1.1",
+    "tsx": "^4.19.2"
+  },
+  "devDependencies": {
+    "@mondaydotcomorg/trident-library": "^1.2.7",
+    "@types/fs-extra": "^11.0.4",
+    "@types/mime-types": "^2.1.4",
+    "@types/node": "^22.19.0",
+    "typescript": "^5.7.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/DaPulse/bigbrain-z2h.git",
+    "directory": "packages/z2h-cli"
+  }
+}

package/src/commands/build.ts

@@ -0,0 +1,42 @@
+import { pathExists } from 'fs-extra';
+import { execa } from 'execa';
+import { info, output, setOutputMode } from '../util/logger';
+import { prepareShadow } from '../shadow/prepare';
+
+export interface BuildOptions {
+  json?: boolean;
+}
+
+export async function buildCommand(opts: BuildOptions): Promise<void> {
+  if (opts.json) {
+    setOutputMode('json');
+  }
+
+  const ctx = await prepareShadow();
+
+  // Typecheck against the shadow's tsconfig (the consumer dir has none).
+  // Errors fail the build before we waste time on the Trident pipeline.
+  // preferLocal=true makes execa prepend the consumer's node_modules/.bin
+  // to PATH, so `tsc` resolves to the version hoisted from .zth's
+  // trident-toolkit dep — no npx overhead, no extra template deps.
+  info(`type-checking "${ctx.appName}"`);
+  await execa('tsc', ['--noEmit', '-p', ctx.paths.shadowTsconfig], {
+    cwd: ctx.paths.consumerDir,
+    preferLocal: true,
+    stdio: 'inherit',
+  });
+
+  info(`building "${ctx.appName}" via trident`);
+  await execa('yarn', ['build'], { cwd: ctx.paths.shadowDir, stdio: 'inherit' });
+
+  if (!(await pathExists(ctx.paths.shadowBuild))) {
+    throw new Error(`Expected build output at ${ctx.paths.shadowBuild} — not found.`);
+  }
+
+  output(`[z2h-cli] build complete — artifacts at ${ctx.paths.shadowBuild}`, {
+    ok: true,
+    appName: ctx.appName,
+    port: ctx.port,
+    buildDir: ctx.paths.shadowBuild,
+  });
+}

package/src/commands/clean.ts

@@ -0,0 +1,26 @@
+import { pathExists, remove } from 'fs-extra';
+import { info, output, setOutputMode } from '../util/logger';
+import { resolveConsumerPaths } from '../shadow/paths';
+
+export interface CleanOptions {
+  json?: boolean;
+}
+
+export async function cleanCommand(opts: CleanOptions): Promise<void> {
+  if (opts.json) {
+    setOutputMode('json');
+  }
+  const paths = resolveConsumerPaths(process.cwd());
+
+  const existed = await pathExists(paths.shadowDir);
+  if (existed) {
+    info(`removing ${paths.shadowDir}`);
+    await remove(paths.shadowDir);
+  }
+
+  output(existed ? `[z2h-cli] cleaned shadow at ${paths.shadowDir}` : '[z2h-cli] nothing to clean', {
+    ok: true,
+    shadowDir: paths.shadowDir,
+    removed: existed,
+  });
+}

package/src/commands/deploy.ts

@@ -0,0 +1,114 @@
+import path from 'node:path';
+import { pathExists, readJson } from 'fs-extra';
+import { execa } from 'execa';
+import { info, warn, output, setOutputMode } from '../util/logger';
+import { resolveConsumerPaths } from '../shadow/paths';
+import {
+  nextVersion,
+  readManifest,
+  upsertEntry,
+  writeManifest,
+  type AssetManifestFile,
+  type ManifestEntry,
+} from '../util/manifest';
+import { uploadDir } from '../util/s3/upload';
+import { assertBucketExists, BUCKET_WRITE_NAME, BUCKET_READ_DNS_URL } from '../util/s3/client';
+import { cleanAppName, mfAppName } from '../util/app-name';
+import { buildCommand } from './build';
+
+const APONO_BUNDLE = '<APONO_BUNDLE_NAME>'; // TODO: replace with actual bundle name once infra setup is complete
+
+export interface DeployOptions {
+  dryRun?: boolean;
+  json?: boolean;
+}
+
+async function requestAponoAccess(): Promise<void> {
+  if (APONO_BUNDLE === '<APONO_BUNDLE_NAME>') {
+    warn(
+      `skipping Apono request — APONO_BUNDLE is still a placeholder ("${APONO_BUNDLE}"). Set it in deploy.ts before relying on auto-grant.`
+    );
+    return;
+  }
+  info(`requesting Apono access for bundle "${APONO_BUNDLE}"`);
+  await execa('apono', ['bundles', 'grant', APONO_BUNDLE], { stdio: 'inherit' });
+}
+
+export async function deployCommand(opts: DeployOptions): Promise<void> {
+  if (opts.json) {
+    setOutputMode('json');
+  }
+
+  info('checking S3 bucket');
+  await assertBucketExists();
+
+  info('building');
+  await buildCommand({ json: opts.json });
+
+  const paths = resolveConsumerPaths(process.cwd());
+  const consumerPkg = (await readJson(paths.consumerPkg)) as { name?: string };
+  if (!consumerPkg.name) {
+    throw new Error('Consumer package.json must have a "name" field');
+  }
+  const appName = mfAppName(consumerPkg.name);
+
+  if (!(await pathExists(paths.shadowBuild))) {
+    throw new Error(`No build output at ${paths.shadowBuild} after build step.`);
+  }
+
+  // Trident emits the canonical per-MF manifest at build/asset-manifest.json.
+  const assetManifestPath = path.join(paths.shadowBuild, 'asset-manifest.json');
+  if (!(await pathExists(assetManifestPath))) {
+    throw new Error(`Missing asset-manifest.json at ${assetManifestPath}.`);
+  }
+  const assetManifest = (await readJson(assetManifestPath)) as AssetManifestFile;
+
+  info('reading current Z2H manifest');
+  const manifest = await readManifest();
+  const version = nextVersion(manifest, appName);
+  const keyPrefix = `${appName}/${version}`;
+  const url = `${BUCKET_READ_DNS_URL}/${keyPrefix}`;
+
+  if (opts.dryRun) {
+    output(`[z2h-cli] dry-run: would upload to s3://${BUCKET_WRITE_NAME}/${keyPrefix}/ as v${version}`, {
+      ok: true,
+      dryRun: true,
+      appName,
+      version,
+      bucket: BUCKET_WRITE_NAME,
+      keyPrefix,
+      url,
+      entry: { ...assetManifest, version, url },
+    });
+    return;
+  }
+
+  await requestAponoAccess();
+
+  info(`uploading build → s3://${BUCKET_WRITE_NAME}/${keyPrefix}/`);
+  await uploadDir(paths.shadowBuild, keyPrefix);
+
+  const entry: ManifestEntry = {
+    ...assetManifest,
+    version,
+    url,
+  };
+
+  info(`updating manifest entry "${appName}" → v${version}`);
+  await writeManifest(upsertEntry(manifest, appName, entry));
+
+  // 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
+  // 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}`, {
+    ok: true,
+    appName,
+    version,
+    bucket: BUCKET_WRITE_NAME,
+    keyPrefix,
+    url,
+    liveUrl,
+    entry,
+  });
+}