@mondaydotcomorg/z2h-cli 0.1.0

package/src/commands/dev.ts

@@ -0,0 +1,64 @@
+import { readJson } from 'fs-extra';
+import { watch } from 'chokidar';
+import { execa } from 'execa';
+import { info, warn, errorLog, output, setOutputMode } from '../util/logger';
+import { prepareShadow } from '../shadow/prepare';
+import { ensureConsumerPkg } from '../shadow/consumer-pkg';
+import { syncShadow } from '../shadow/sync';
+import type { ConsumerPkg } from '../types';
+
+export interface DevOptions {
+  json?: boolean;
+}
+
+const TRIDENT_READY_PATTERN = /Server started at/i;
+
+export async function devCommand(opts: DevOptions): Promise<void> {
+  if (opts.json) {
+    setOutputMode('json');
+  }
+
+  const ctx = await prepareShadow();
+  const { port } = ctx;
+  const url = `https://bigbrain.me/bigbrain-vibe/${ctx.appName}?zth_local=${port}`;
+
+  info('starting z2h app');
+  // stdout is piped so we can detect trident's ready banner before printing
+  // our own ready line. stdin/stderr stay inherited so colored errors and
+  // interactive prompts still flow naturally.
+  const server = execa('yarn', ['start'], {
+    cwd: ctx.paths.shadowDir,
+    stdio: ['inherit', 'pipe', 'inherit'],
+  });
+
+  let readyPrinted = false;
+  server.stdout?.on('data', (chunk: Buffer) => {
+    process.stdout.write(chunk);
+    if (!readyPrinted && TRIDENT_READY_PATTERN.test(chunk.toString())) {
+      readyPrinted = true;
+      output(`\n[z2h-cli] ready — open:\n  ${url}\n`, {
+        ok: true,
+        appName: ctx.appName,
+        port,
+        url,
+      });
+    }
+  });
+
+  // Only watch consumer package.json. Source changes flow through Vite's
+  // native import graph — the wrapper imports consumer src via relative
+  // path, so Vite's HMR picks up edits without any rsync.
+  const pkgWatcher = watch(ctx.paths.consumerPkg, { ignoreInitial: true });
+  pkgWatcher.on('change', async () => {
+    warn('consumer package.json changed — re-checking deps');
+    try {
+      const raw = (await readJson(ctx.paths.consumerPkg)) as ConsumerPkg;
+      const { pkg } = await ensureConsumerPkg(ctx.paths.consumerPkg, raw);
+      await syncShadow(ctx.paths, pkg);
+    } catch (err) {
+      errorLog(`re-prepare failed: ${(err as Error).message}`);
+    }
+  });
+
+  await server;
+}

package/src/constants.ts

@@ -0,0 +1,63 @@
+/**
+ * Cross-file constants. Narrowly-used literals (templates, prefixes used in
+ * one place) stay local to their file to keep this index small.
+ */
+
+// ─────────── Shadow dir layout ───────────
+export const SHADOW_DIR_NAME = '.zth';
+
+// ─────────── Consumer pkg enforcement ──────
+/**
+ * Protected runtime deps that MUST resolve to a single instance across the
+ * wrapper (.zth) and the consumer's src. Declared as peerDependencies in
+ * the shadow pkg so yarn hoists them from the workspace root — which is
+ * why we enforce their presence in the consumer's own package.json.
+ */
+export const PROTECTED_DEPS: Record<string, string> = {
+  react: '^18.2.0',
+  'react-dom': '^18.2.0',
+  'react-error-boundary': '^3.1.3',
+  '@mondaydotcomorg/trident-runtime': '^1.24.1',
+  '@vibe/core': '^4.0.1',
+};
+
+/**
+ * Protected dev deps. Same idempotent treatment as PROTECTED_DEPS but live
+ * in the consumer's `devDependencies`. These give the LLM-authored consumer
+ * code access to monday.com platform types out of the box.
+ */
+export const PROTECTED_DEV_DEPS: Record<string, string> = {
+  '@mondaydotcomorg/mf-api-types': '^0.1.1',
+  '@mondaydotcomorg/bigbrain-types': '^0.3.3',
+};
+
+// ─────────── Shadow pkg template ───────────
+// TODO — Add trident mf-types / bigbrain-types opt-in.
+export const WORKSPACE_DEV_DEPS: Record<string, string> = {
+  '@mondaydotcomorg/trident-toolkit': '^2.9.25',
+  '@types/react': '^18.0.14',
+  '@types/react-dom': '^18.0.5',
+  typescript: '^5.7.2',
+};
+
+export const SHADOW_SCRIPTS: Record<string, string> = {
+  start: 'trident start',
+  build: 'trident build',
+};
+
+// ─────────── Auto-allocated dev port range ────
+// High enough to dodge common dev defaults (3000 Next, 5173 Vite, 8080).
+// Collisions within the 7k-port pool are rare for POC; if trident can't
+// bind, the user sees a clear bind error from the dev server and re-runs.
+export const MIN_PORT = 13000;
+export const MAX_PORT = 19999;
+
+// ─────────── Gitignore entries auto-appended to the consumer's file ────
+export const GITIGNORE_ENTRIES = ['.zth/'];
+
+// ─────────── .yarnrc.yml written to new consumer apps ────
+export const YARNRC_LINES = [
+  'nodeLinker: node-modules',
+  "npmAuthToken: '${NPM_TOKEN}'",
+  "npmRegistryServer: 'https://registry.npmjs.org/'",
+];

package/src/index.ts

@@ -0,0 +1,90 @@
+import { Command } from 'commander';
+import { devCommand } from './commands/dev';
+import { buildCommand } from './commands/build';
+import { cleanCommand } from './commands/clean';
+import { deployCommand } from './commands/deploy';
+import { errorLog, fail } from './util/logger';
+
+async function main(): Promise<void> {
+  const program = new Command();
+  program
+    .name('z2h-cli')
+    .description(
+      [
+        'Zero-to-Hero CLI — ship LLM-generated React apps as Trident MFs.',
+        '',
+        'Each consumer dir is self-contained: a shadow at <consumer>/.zth/',
+        'wraps the consumer source as a Trident MF. Run from inside any',
+        'consumer dir (the one with your src/index.tsx).',
+        '',
+        'Exit codes:',
+        '  0  success',
+        '  1  user-resolvable error (bad cwd, invalid package.json, lock held)',
+        '  2  system error (yarn install or trident build failed)',
+      ].join('\n')
+    )
+    .version('0.0.0');
+
+  program
+    .command('build')
+    .description('Build the consumer into its .zth/ shadow and copy artifacts to ./build/')
+    .option('--json', 'emit structured JSON on stdout')
+    .action(async (opts: { json?: boolean }) => {
+      try {
+        await buildCommand(opts);
+      } catch (err) {
+        // fail() emits a structured JSON error on stdout in --json mode and
+        // a red line on stderr in human mode, then exits. errorLog alone is
+        // silent in JSON mode, which leaves machine consumers with no signal.
+        fail(`build failed: ${(err as Error).message}`, { command: 'build' }, 2);
+      }
+    });
+
+  program
+    .command('dev')
+    .description('Start the Trident dev server against .zth/ with native Vite HMR')
+    .option('--json', 'emit structured JSON on stdout')
+    .action(async (opts: { json?: boolean }) => {
+      try {
+        await devCommand(opts);
+      } catch (err) {
+        fail(`dev failed: ${(err as Error).message}`, { command: 'dev' }, 2);
+      }
+    });
+
+  program
+    .command('clean')
+    .description('Delete <consumer>/.zth/ and <consumer>/build/')
+    .option('--json', 'emit structured JSON on stdout')
+    .action(async (opts: { json?: boolean }) => {
+      try {
+        await cleanCommand(opts);
+      } catch (err) {
+        fail(`clean failed: ${(err as Error).message}`, { command: 'clean' }, 2);
+      }
+    });
+
+  program
+    .command('deploy')
+    .description('Build, upload artifacts to S3, and update the Z2H manifest')
+    .option('--dry-run', 'print what would happen without uploading anything')
+    .option('--json', 'emit structured JSON on stdout')
+    .action(async (opts: { dryRun?: boolean; json?: boolean }) => {
+      try {
+        await deployCommand(opts);
+      } catch (err) {
+        fail(`deploy failed: ${(err as Error).message}`, { command: 'deploy' }, 2);
+      }
+    });
+
+  await program.parseAsync(process.argv);
+}
+
+void main()
+  .then(() => {
+    process.exit(0);
+  })
+  .catch((err: unknown) => {
+    errorLog(`main failed: ${(err as Error).message}`);
+    process.exit(1);
+  });

package/src/shadow/consumer-pkg.ts

@@ -0,0 +1,100 @@
+import { writeJson } from 'fs-extra';
+import { PROTECTED_DEPS, PROTECTED_DEV_DEPS, SHADOW_DIR_NAME } from '../constants';
+import type { ConsumerPkg } from '../types';
+
+/**
+ * Return the consumer's `workspaces` field extended with `.zth`. Handles
+ * all three shapes: missing, array form, or object form (`{ packages }`).
+ * Always extends — never replaces the user's existing entries.
+ */
+export function ensureConsumerWorkspaces(pkg: ConsumerPkg): {
+  changed: boolean;
+  workspaces: ConsumerPkg['workspaces'];
+} {
+  const { workspaces } = pkg;
+
+  if (Array.isArray(workspaces)) {
+    if (workspaces.includes(SHADOW_DIR_NAME)) {
+      return { changed: false, workspaces };
+    }
+    return { changed: true, workspaces: [...workspaces, SHADOW_DIR_NAME] };
+  }
+
+  if (workspaces && typeof workspaces === 'object') {
+    const pkgs = workspaces.packages ?? [];
+    if (pkgs.includes(SHADOW_DIR_NAME)) {
+      return { changed: false, workspaces };
+    }
+    return {
+      changed: true,
+      workspaces: { ...workspaces, packages: [...pkgs, SHADOW_DIR_NAME] },
+    };
+  }
+
+  return { changed: true, workspaces: [SHADOW_DIR_NAME] };
+}
+
+/**
+ * Extend a deps map with the protected entries; only fills in missing ones,
+ * never overrides versions the consumer already pinned.
+ */
+function applyProtected(
+  current: Record<string, string> | undefined,
+  protectedMap: Record<string, string>
+): { changed: boolean; next: Record<string, string> } {
+  const next = { ...(current ?? {}) };
+  let changed = false;
+  for (const [name, version] of Object.entries(protectedMap)) {
+    if (!next[name]) {
+      next[name] = version;
+      changed = true;
+    }
+  }
+  return { changed, next };
+}
+
+/**
+ * Idempotently reshape the consumer's package.json so that:
+ *  - it is marked `"private": true`
+ *  - `.zth` is declared as a yarn workspace member (yarn will hoist)
+ *  - the protected runtime deps are present at compatible versions
+ *  - the protected dev deps are present at compatible versions
+ *
+ * Always extends — never overrides existing fields.
+ */
+export async function ensureConsumerPkg(
+  pkgPath: string,
+  pkg: ConsumerPkg
+): Promise<{ changed: boolean; pkg: ConsumerPkg }> {
+  let changed = false;
+  const next: ConsumerPkg = { ...pkg };
+
+  if (next.private !== true) {
+    next.private = true;
+    changed = true;
+  }
+
+  const ws = ensureConsumerWorkspaces(next);
+  if (ws.changed) {
+    next.workspaces = ws.workspaces;
+    changed = true;
+  }
+
+  const deps = applyProtected(next.dependencies, PROTECTED_DEPS);
+  if (deps.changed) {
+    next.dependencies = deps.next;
+    changed = true;
+  }
+
+  const devDeps = applyProtected(next.devDependencies, PROTECTED_DEV_DEPS);
+  if (devDeps.changed) {
+    next.devDependencies = devDeps.next;
+    changed = true;
+  }
+
+  if (changed) {
+    await writeJson(pkgPath, next, { spaces: 2 });
+  }
+
+  return { changed, pkg: next };
+}

package/src/shadow/gitignore.ts

@@ -0,0 +1,30 @@
+import path from 'node:path';
+import { pathExists, readFile, writeFile } from 'fs-extra';
+import { GITIGNORE_ENTRIES } from '../constants';
+
+/**
+ * Idempotently append our shadow-dir entries to the consumer's .gitignore.
+ * Never modifies existing entries; only appends missing ones. Creates the
+ * file if absent.
+ */
+export async function ensureGitignore(consumerDir: string): Promise<void> {
+  const gitignorePath = path.join(consumerDir, '.gitignore');
+  let body = '';
+  if (await pathExists(gitignorePath)) {
+    body = await readFile(gitignorePath, 'utf8');
+  }
+  const existing = new Set(
+    body
+      .split('\n')
+      .map(l => l.trim())
+      .filter(Boolean)
+  );
+  const missing = GITIGNORE_ENTRIES.filter(e => !existing.has(e));
+  if (missing.length === 0) {
+    return;
+  }
+
+  const prefix = body.length && !body.endsWith('\n') ? '\n' : '';
+  const block = `${prefix}\n# z2h-cli\n${missing.join('\n')}\n`;
+  await writeFile(gitignorePath, body + block);
+}

package/src/shadow/merge-package-json.ts

@@ -0,0 +1,62 @@
+import crypto from 'node:crypto';
+import { writeJson } from 'fs-extra';
+import { PROTECTED_DEPS, SHADOW_SCRIPTS, WORKSPACE_DEV_DEPS } from '../constants';
+import { mfAppName } from '../util/app-name';
+import type { ConsumerPkg, ShadowPkg } from '../types';
+
+/**
+ * Build the shadow package.json. Declares the shared runtime deps as
+ * peerDependencies — yarn resolves them from the workspace root (the
+ * consumer's package.json), guaranteeing a single React instance across
+ * the wrapper and consumer src.
+ */
+export function buildShadowPkg(consumerPkg: ConsumerPkg): ShadowPkg {
+  // Use the `@trident/` scope so trident-toolkit strips it and the emitted
+  // bundle becomes `MF-mf-<appName>`, matching the URL the host MF routes to.
+  // The scope also keeps the shadow's name distinct from the consumer's
+  // package.json name (same workspace, different identifiers).
+  return {
+    name: `@trident/${mfAppName(consumerPkg.name)}`,
+    version: '0.0.1',
+    private: true,
+    scripts: SHADOW_SCRIPTS,
+    peerDependencies: { ...PROTECTED_DEPS },
+    devDependencies: WORKSPACE_DEV_DEPS,
+  };
+}
+
+/**
+ * Stable, key-sorted serialization. Two objects with the same keys/values
+ * hash identically regardless of insertion order — so re-orderings from
+ * yarn's install or ensureConsumerPkg don't trigger spurious reinstalls.
+ */
+function stableStringify(value: unknown): string {
+  return JSON.stringify(value, (_key, v) => {
+    if (v && typeof v === 'object' && !Array.isArray(v)) {
+      return Object.fromEntries(Object.entries(v as Record<string, unknown>).sort(([a], [b]) => a.localeCompare(b)));
+    }
+    return v;
+  });
+}
+
+/**
+ * Hash the consumer's declared deps. This is the sole input that decides
+ * whether `yarn install` needs to run — the shadow package.json is
+ * regenerated from a CLI-owned template every run and doesn't participate.
+ */
+export function hashConsumerDeps(consumer: ConsumerPkg): string {
+  return crypto
+    .createHash('sha256')
+    .update(
+      stableStringify({
+        deps: consumer.dependencies ?? {},
+        devDeps: consumer.devDependencies ?? {},
+        peerDeps: consumer.peerDependencies ?? {},
+      })
+    )
+    .digest('hex');
+}
+
+export async function writeShadowPkg(shadowPkgPath: string, shadow: ShadowPkg): Promise<void> {
+  await writeJson(shadowPkgPath, shadow, { spaces: 2 });
+}

package/src/shadow/metadata.ts

@@ -0,0 +1,17 @@
+import { pathExists, readJson, writeJson } from 'fs-extra';
+import type { ConsumerPaths, ShadowMetadata } from '../types';
+
+export async function readMetadata(paths: ConsumerPaths): Promise<ShadowMetadata | null> {
+  if (!(await pathExists(paths.shadowMetadata))) {
+    return null;
+  }
+  try {
+    return (await readJson(paths.shadowMetadata)) as ShadowMetadata;
+  } catch {
+    return null;
+  }
+}
+
+export async function writeMetadata(paths: ConsumerPaths, meta: ShadowMetadata): Promise<void> {
+  await writeJson(paths.shadowMetadata, meta, { spaces: 2 });
+}

package/src/shadow/paths.ts

@@ -0,0 +1,24 @@
+import path from 'node:path';
+import { SHADOW_DIR_NAME } from '../constants';
+import type { ConsumerPaths } from '../types';
+
+export function resolveConsumerPaths(consumerDir: string): ConsumerPaths {
+  const shadowDir = path.join(consumerDir, SHADOW_DIR_NAME);
+  return {
+    consumerDir,
+    consumerPkg: path.join(consumerDir, 'package.json'),
+    consumerSrc: path.join(consumerDir, 'src'),
+    consumerSrcEntry: path.join(consumerDir, 'src', 'index.tsx'),
+    shadowDir,
+    shadowPkg: path.join(shadowDir, 'package.json'),
+    shadowSrc: path.join(shadowDir, 'src'),
+    shadowWrapper: path.join(shadowDir, 'src', 'index.tsx'),
+    shadowTridentrc: path.join(shadowDir, '.tridentrc.js'),
+    shadowNvmrc: path.join(shadowDir, '.nvmrc'),
+    shadowDts: path.join(shadowDir, 'src', 'declaration.d.ts'),
+    shadowTsconfig: path.join(shadowDir, 'tsconfig.json'),
+    shadowBuild: path.join(shadowDir, 'build'),
+    shadowDepsHash: path.join(shadowDir, '.deps-hash'),
+    shadowMetadata: path.join(shadowDir, 'metadata.json'),
+  };
+}

package/src/shadow/port.ts

@@ -0,0 +1,34 @@
+import net from 'node:net';
+import { MAX_PORT, MIN_PORT } from '../constants';
+
+function randomPort(): number {
+  return MIN_PORT + Math.floor(Math.random() * (MAX_PORT - MIN_PORT + 1));
+}
+
+/**
+ * Tries to bind to `port` on localhost; resolves true if the bind succeeds
+ * (port is free) and the listener was cleanly closed.
+ */
+export function isPortFree(port: number): Promise<boolean> {
+  return new Promise(resolve => {
+    const server = net.createServer();
+    server.once('error', () => resolve(false));
+    server.once('listening', () => server.close(() => resolve(true)));
+    server.listen(port, '127.0.0.1');
+  });
+}
+
+/**
+ * Picks a random port from the configured range and verifies it's actually
+ * free before returning. Tries up to `MAX_PORT_TRIES` candidates.
+ */
+const MAX_PORT_TRIES = 50;
+export async function pickPort(): Promise<number> {
+  for (let i = 0; i < MAX_PORT_TRIES; i++) {
+    const p = randomPort();
+    if (await isPortFree(p)) {
+      return p;
+    }
+  }
+  throw new Error(`Could not find a free port in range ${MIN_PORT}-${MAX_PORT} after ${MAX_PORT_TRIES} tries`);
+}

package/src/shadow/prepare.ts

@@ -0,0 +1,68 @@
+import { ensureDir, pathExists, readJson } from 'fs-extra';
+import { info } from '../util/logger';
+import { cleanAppName } from '../util/app-name';
+import { resolveConsumerPaths } from './paths';
+import { ensureGitignore } from './gitignore';
+import { ensureYarnRc } from './yarnrc';
+import { ensureConsumerPkg } from './consumer-pkg';
+import { scaffoldShadow } from './scaffold';
+import { readMetadata, writeMetadata } from './metadata';
+import { isPortFree, pickPort } from './port';
+import { syncShadow } from './sync';
+import type { ConsumerPaths, ConsumerPkg, PreparedShadow, ShadowMetadata } from '../types';
+
+export async function prepareShadow(): Promise<PreparedShadow> {
+  const paths = resolveConsumerPaths(process.cwd());
+
+  if (!(await pathExists(paths.consumerPkg))) {
+    throw new Error(`No package.json found in ${paths.consumerDir}`);
+  }
+  if (!(await pathExists(paths.consumerSrcEntry))) {
+    throw new Error(`Consumer must have src/index.tsx (in ${paths.consumerDir})`);
+  }
+
+  const rawConsumerPkg = (await readJson(paths.consumerPkg)) as ConsumerPkg;
+  if (!rawConsumerPkg.name) {
+    throw new Error('Consumer package.json must have a "name" field');
+  }
+  const appName = cleanAppName(rawConsumerPkg.name);
+
+  const { pkg: consumerPkg, changed: consumerChanged } = await ensureConsumerPkg(paths.consumerPkg, rawConsumerPkg);
+  if (consumerChanged) {
+    info(`ensured consumer pkg shape at ${paths.consumerPkg}`);
+  }
+
+  await ensureGitignore(paths.consumerDir);
+  await ensureYarnRc(paths.consumerDir);
+  await ensureDir(paths.shadowDir);
+
+  const metadata = await resolvePortAndMetadata(paths, appName);
+  const port = metadata.port;
+
+  info(`preparing shadow at ${paths.shadowDir} (port ${port})`);
+  await scaffoldShadow(paths, appName, port);
+  await syncShadow(paths, consumerPkg);
+
+  return { appName, port, paths };
+}
+
+/**
+ * Resolve the dev server port. Prefer the persisted port if it's still free
+ * (URL stays stable across restarts). Otherwise pick a fresh one. The
+ * orphaned process — if there is one — keeps running on its old port,
+ * harmless. No process killing, no PID files.
+ */
+async function resolvePortAndMetadata(paths: ConsumerPaths, appName: string): Promise<ShadowMetadata> {
+  const existing = await readMetadata(paths);
+  if (existing?.port && (await isPortFree(existing.port))) {
+    return existing;
+  }
+
+  const next: ShadowMetadata = {
+    createdAt: existing?.createdAt ?? new Date().toISOString(),
+    appName,
+    port: await pickPort(),
+  };
+  await writeMetadata(paths, next);
+  return next;
+}

package/src/shadow/scaffold.ts

@@ -0,0 +1,120 @@
+import path from 'node:path';
+import { ensureDir, writeFile, writeJson } from 'fs-extra';
+import type { ConsumerPaths } from '../types';
+
+const WRAPPER_TEMPLATE = `import '@vibe/core/tokens';
+import ConsumerApp from '../../src/index';
+import React from 'react';
+import * as ReactDOM from 'react-dom/client';
+import { ErrorBoundary } from 'react-error-boundary';
+
+const roots = new Map<HTMLElement, ReactDOM.Root>();
+
+export function init() {}
+
+export function render(element: HTMLElement) {
+  const root = ReactDOM.createRoot(element);
+  root.render(
+    <ErrorBoundary fallback={<div style={{ padding: 16 }}>This app crashed.</div>}>
+      <ConsumerApp />
+    </ErrorBoundary>,
+  );
+  roots.set(element, root);
+}
+
+export function unmount({ element }: { element: HTMLElement }) {
+  const root = roots.get(element);
+  if (root) {
+    root.unmount();
+    roots.delete(element);
+  }
+}
+`;
+
+const tridentrcTemplate = (appName: string, port: number): string =>
+  `/** @type {import("@mondaydotcomorg/trident-user-config").MicroFrontendConfig} */
+const config = {
+  appName: '${appName}',
+  port: ${port},
+};
+
+module.exports = config;
+`;
+
+const dtsFileTemplate = (): string =>
+  `
+declare module '*.module.css' {
+  const classNames: {
+    [className: string]: string;
+  };
+  export = classNames;
+}
+
+declare module '*.module.scss' {
+  const classNames: {
+    [className: string]: string;
+  };
+  export = classNames;
+}
+
+declare module '*.jpg' {
+  const e: string;
+  export default e;
+}
+declare module '*.jpeg' {
+  const e: string;
+  export default e;
+}
+declare module '*.png' {
+  const e: string;
+  export default e;
+}
+declare module '*.riv' {
+  const e: string;
+  export default e;
+}
+
+declare module '*.wasm' {
+  const e: string;
+  export default e;
+}
+`;
+
+const TSCONFIG_TEMPLATE = {
+  compilerOptions: {
+    target: 'es5',
+    lib: ['dom', 'dom.iterable', 'esnext'],
+    allowJs: false,
+    skipLibCheck: true,
+    esModuleInterop: true,
+    allowSyntheticDefaultImports: true,
+    strict: false,
+    module: 'esnext',
+    moduleResolution: 'bundler',
+    resolveJsonModule: true,
+    noImplicitAny: false,
+    isolatedModules: true,
+    baseUrl: 'src',
+    noEmit: true,
+    jsx: 'react-jsx',
+  },
+  include: ['src', '../src'],
+};
+
+/**
+ * Write every generated file under .zth/. Overwrites on every run so the
+ * shadow dir is a deterministic function of the CLI version — no drift.
+ */
+export async function scaffoldShadow(paths: ConsumerPaths, appName: string, port: number): Promise<void> {
+  await ensureDir(paths.shadowSrc);
+  await writeFile(paths.shadowWrapper, WRAPPER_TEMPLATE);
+  await writeFile(paths.shadowTridentrc, tridentrcTemplate(appName, port));
+  await writeFile(paths.shadowNvmrc, `${process.version}\n`);
+  await writeFile(paths.shadowDts, dtsFileTemplate());
+  await writeJson(paths.shadowTsconfig, TSCONFIG_TEMPLATE, { spaces: 2 });
+  // Drop a stub README so contributors who open .zth/ know what they're looking at.
+  await writeFile(
+    path.join(paths.shadowDir, 'README.md'),
+    '# .zth/\nGenerated by z2h-cli. Do not edit — run `z2h-cli build` or `z2h-cli dev` to refresh.\n'
+  );
+}