@mondaydotcomorg/z2h-cli 0.1.0

package/src/shadow/sync.ts

@@ -0,0 +1,30 @@
+import { pathExists, readFile, writeFile } from 'fs-extra';
+import { execa } from 'execa';
+import { info } from '../util/logger';
+import { buildShadowPkg, hashConsumerDeps, writeShadowPkg } from './merge-package-json';
+import type { ConsumerPaths, ConsumerPkg } from '../types';
+
+/**
+ * Regenerate the shadow package.json from the current CLI template and
+ * run `yarn install` at the consumer dir iff the consumer's declared deps
+ * have changed since the last install. Idempotent — safe to call on every
+ * build, dev start, or consumer package.json edit.
+ */
+export async function syncShadow(paths: ConsumerPaths, consumerPkg: ConsumerPkg): Promise<void> {
+  const shadow = buildShadowPkg(consumerPkg);
+  await writeShadowPkg(paths.shadowPkg, shadow);
+
+  const newHash = hashConsumerDeps(consumerPkg);
+  const oldHash = (await pathExists(paths.shadowDepsHash)) ? await readFile(paths.shadowDepsHash, 'utf8') : null;
+
+  if (oldHash !== newHash) {
+    info(oldHash ? 'consumer deps changed — yarn install' : 'first run — yarn install');
+    // Yarn 4 is cache-first and non-interactive by default
+    // in non-TTY contexts, so no flags are needed
+    await execa('yarn', ['install'], {
+      cwd: paths.consumerDir,
+      stdio: 'inherit',
+    });
+    await writeFile(paths.shadowDepsHash, newHash);
+  }
+}

package/src/shadow/yarnrc.ts

@@ -0,0 +1,29 @@
+import path from 'node:path';
+import { pathExists, readFile, writeFile } from 'fs-extra';
+import { YARNRC_LINES } from '../constants';
+
+/**
+ * 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.
+ */
+
+export async function ensureYarnRc(consumerDir: string): Promise<void> {
+  const yarnrcPath = path.join(consumerDir, '.yarnrc.yml');
+
+  if (!(await pathExists(yarnrcPath))) {
+    await writeFile(yarnrcPath, YARNRC_LINES.join('\n\n') + '\n');
+    return;
+  }
+
+  const body = await readFile(yarnrcPath, 'utf8');
+  if (/^\s*nodeLinker\s*:/m.test(body)) {
+    return;
+  }
+
+  const prefix = body.length && !body.endsWith('\n') ? '\n' : '';
+  await writeFile(yarnrcPath, body + prefix + 'nodeLinker: node-modules\n');
+}

package/src/types.ts

@@ -0,0 +1,60 @@
+/**
+ * Shared domain types for the Z2H CLI. Command-scoped option types live
+ * with their command; narrow single-use types stay local to their file.
+ */
+
+// ─────────── Consumer pkg management ───────────
+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;
+}
+
+// ─────────── Shadow pkg (generated by CLI, lives at .zth/package.json) ───
+export interface ShadowPkg {
+  name: string;
+  version: string;
+  private: true;
+  scripts: Record<string, string>;
+  peerDependencies: Record<string, string>;
+  devDependencies: Record<string, string>;
+}
+
+// ─────────── Persisted shadow metadata (.zth/metadata.json) ───────
+export interface ShadowMetadata {
+  createdAt: string;
+  appName: string;
+  port: number;
+}
+
+// ─────────── Filesystem paths, resolved once per invocation ─────
+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;
+}
+
+// ─────────── prepareShadow result ───────────
+export interface PreparedShadow {
+  appName: string;
+  port: number;
+  paths: ConsumerPaths;
+}

package/src/util/app-name.ts

@@ -0,0 +1,16 @@
+/**
+ * Strip any npm scope (`@scope/`) from a package name.
+ * e.g. `@trident/customer-viewer` → `customer-viewer`, `foo` → `foo`.
+ */
+export function cleanAppName(name: string): string {
+  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>`).
+ */
+export function mfAppName(name: string): string {
+  return `mf-${cleanAppName(name)}`;
+}

package/src/util/logger.ts

@@ -0,0 +1,64 @@
+import pc from 'picocolors';
+
+export type OutputMode = 'human' | 'json';
+
+let mode: OutputMode = 'human';
+
+export function setOutputMode(next: OutputMode): void {
+  mode = next;
+}
+
+export function getOutputMode(): OutputMode {
+  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).
+ */
+export function info(msg: string): void {
+  if (mode === 'human') {
+    process.stderr.write(pc.cyan(`[z2h-cli] ${msg}\n`));
+  }
+}
+
+export function warn(msg: string): void {
+  if (mode === 'human') {
+    process.stderr.write(pc.yellow(`[z2h-cli] ${msg}\n`));
+  }
+}
+
+export function errorLog(msg: string): void {
+  if (mode === 'human') {
+    process.stderr.write(pc.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.
+ */
+export function output(human: string, data: unknown): void {
+  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.
+ */
+export function fail(message: string, payload: Record<string, unknown>, exitCode = 1): never {
+  if (mode === 'json') {
+    process.stdout.write(`${JSON.stringify({ ok: false, error: message, ...payload })}\n`);
+  } else {
+    process.stderr.write(pc.red(`[z2h-cli] ${message}\n`));
+    if (typeof payload.suggestedCommand === 'string') {
+      process.stderr.write(pc.dim(`  → ${payload.suggestedCommand}\n`));
+    }
+  }
+  process.exit(exitCode);
+}

package/src/util/manifest.ts

@@ -0,0 +1,65 @@
+import { PutObjectCommand } from '@aws-sdk/client-s3';
+import { BUCKET_WRITE_NAME, MANIFEST_KEY, MANIFEST_READ_URL, getS3Client } from './s3/client';
+
+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 async function readManifest(): Promise<Manifest> {
+  // Read via the public CDN endpoint, no AWS auth required.
+  const res = await fetch(MANIFEST_READ_URL);
+
+  if (!res.ok) {
+    throw new Error(`failed to read manifest from ${MANIFEST_READ_URL}: HTTP ${res.status}`);
+  }
+  return (await res.json()) as Manifest;
+}
+
+export function nextVersion(manifest: Manifest, app: string) {
+  const current = manifest[app]?.version;
+  const n = current ? Number(current) : 0;
+  return (Number.isNaN(n) ? 0 : n) + 1;
+}
+
+export function upsertEntry(manifest: Manifest, app: string, entry: ManifestEntry): Manifest {
+  return { ...manifest, [app]: entry };
+}
+
+export async function writeManifest(manifest: Manifest): Promise<void> {
+  const s3 = getS3Client();
+  await s3.send(
+    new PutObjectCommand({
+      Bucket: BUCKET_WRITE_NAME,
+      Key: MANIFEST_KEY,
+      Body: JSON.stringify(manifest, null, 2),
+      ContentType: 'application/json',
+      CacheControl: 'no-cache',
+    })
+  );
+}

package/src/util/s3/client.ts

@@ -0,0 +1,40 @@
+import { HeadBucketCommand, S3Client, S3ServiceException } from '@aws-sdk/client-s3';
+
+export const BUCKET_WRITE_NAME = 'prod-use1-bigbrain-zth-mf-assets';
+export const REGION = 'us-east-1';
+export const BUCKET_WRITE_URL = `https://${BUCKET_WRITE_NAME}.s3.${REGION}.amazonaws.com`;
+
+export const BUCKET_READ_DNS_NAME = 'bigbrain-zth-mf-assets';
+export 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.
+export const MANIFEST_KEY = 'mf-assets';
+export const MANIFEST_READ_URL = `${BUCKET_READ_DNS_URL}/${MANIFEST_KEY}`;
+
+let client: S3Client | null = null;
+
+export function getS3Client(): S3Client {
+  if (!client) {
+    client = new S3Client({ region: REGION });
+  }
+  return client;
+}
+
+export async function assertBucketExists(): Promise<void> {
+  try {
+    await getS3Client().send(new HeadBucketCommand({ Bucket: BUCKET_WRITE_NAME }));
+  } catch (err) {
+    if (err instanceof 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;
+  }
+}

package/src/util/s3/upload.ts

@@ -0,0 +1,41 @@
+import path from 'node:path';
+import { readFile } from 'fs-extra';
+import { readdir } from 'node:fs/promises';
+import { lookup as lookupMime } from 'mime-types';
+import pMap from 'p-map';
+import { PutObjectCommand } from '@aws-sdk/client-s3';
+import { BUCKET_WRITE_NAME, getS3Client } from './client';
+
+// 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;
+
+export async function uploadDir(localDir: string, keyPrefix: string): Promise<string[]> {
+  const entries = await readdir(localDir, { recursive: true, withFileTypes: true });
+  const files = entries.filter(e => e.isFile()).map(e => path.relative(localDir, path.join(e.parentPath, e.name)));
+
+  const s3 = getS3Client();
+
+  await pMap(
+    files,
+    async rel => {
+      const body = await readFile(path.join(localDir, rel));
+      const contentType = lookupMime(rel) || 'application/octet-stream';
+      const key = `${keyPrefix}/${rel.split(path.sep).join('/')}`;
+      await s3.send(
+        new PutObjectCommand({
+          Bucket: BUCKET_WRITE_NAME,
+          Key: key,
+          Body: body,
+          ContentType: contentType,
+          CacheControl: FOREVER,
+        })
+      );
+    },
+    { concurrency: UPLOAD_CONCURRENCY }
+  );
+
+  return files.map(f => f.split(path.sep).join('/'));
+}