@mondaydotcomorg/z2h-cli 0.1.0

package/dist/esm/constants.mjs

@@ -0,0 +1,57 @@
+/**
+ * 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 ───────────
+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.
+ */
+const PROTECTED_DEPS = {
+    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.
+ */
+const PROTECTED_DEV_DEPS = {
+    '@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.
+const WORKSPACE_DEV_DEPS = {
+    '@mondaydotcomorg/trident-toolkit': '^2.9.25',
+    '@types/react': '^18.0.14',
+    '@types/react-dom': '^18.0.5',
+    typescript: '^5.7.2',
+};
+const SHADOW_SCRIPTS = {
+    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.
+const MIN_PORT = 13000;
+const MAX_PORT = 19999;
+// ─────────── Gitignore entries auto-appended to the consumer's file ────
+const GITIGNORE_ENTRIES = ['.zth/'];
+// ─────────── .yarnrc.yml written to new consumer apps ────
+const YARNRC_LINES = [
+    'nodeLinker: node-modules',
+    "npmAuthToken: '${NPM_TOKEN}'",
+    "npmRegistryServer: 'https://registry.npmjs.org/'",
+];
+
+export { GITIGNORE_ENTRIES, MAX_PORT, MIN_PORT, PROTECTED_DEPS, PROTECTED_DEV_DEPS, SHADOW_DIR_NAME, SHADOW_SCRIPTS, WORKSPACE_DEV_DEPS, YARNRC_LINES };

package/dist/esm/index.d.ts

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

package/dist/esm/index.d.ts.map

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

package/dist/esm/index.mjs

@@ -0,0 +1,86 @@
+import { Command } from 'commander';
+import { devCommand } from './commands/dev.mjs';
+import { buildCommand } from './commands/build.mjs';
+import { cleanCommand } from './commands/clean.mjs';
+import { deployCommand } from './commands/deploy.mjs';
+import { errorLog, fail } from './util/logger.mjs';
+
+async function main() {
+    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) => {
+        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.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) => {
+        try {
+            await devCommand(opts);
+        }
+        catch (err) {
+            fail(`dev failed: ${err.message}`, { command: 'dev' }, 2);
+        }
+    });
+    program
+        .command('clean')
+        .description('Delete <consumer>/.zth/ and <consumer>/build/')
+        .option('--json', 'emit structured JSON on stdout')
+        .action(async (opts) => {
+        try {
+            await cleanCommand(opts);
+        }
+        catch (err) {
+            fail(`clean failed: ${err.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) => {
+        try {
+            await deployCommand(opts);
+        }
+        catch (err) {
+            fail(`deploy failed: ${err.message}`, { command: 'deploy' }, 2);
+        }
+    });
+    await program.parseAsync(process.argv);
+}
+void main()
+    .then(() => {
+    process.exit(0);
+})
+    .catch((err) => {
+    errorLog(`main failed: ${err.message}`);
+    process.exit(1);
+});

package/dist/esm/shadow/consumer-pkg.d.ts

@@ -0,0 +1,24 @@
+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 declare function ensureConsumerWorkspaces(pkg: ConsumerPkg): {
+    changed: boolean;
+    workspaces: ConsumerPkg['workspaces'];
+};
+/**
+ * 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 declare function ensureConsumerPkg(pkgPath: string, pkg: ConsumerPkg): Promise<{
+    changed: boolean;
+    pkg: ConsumerPkg;
+}>;
+//# sourceMappingURL=consumer-pkg.d.ts.map

package/dist/esm/shadow/consumer-pkg.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consumer-pkg.d.ts","sourceRoot":"","sources":["../../../src/shadow/consumer-pkg.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5C;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,WAAW,GAAG;IAC1D,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,WAAW,CAAC,YAAY,CAAC,CAAC;CACvC,CAsBA;AAqBD;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,WAAW,GACf,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,WAAW,CAAA;CAAE,CAAC,CAgCjD"}

package/dist/esm/shadow/consumer-pkg.mjs

@@ -0,0 +1,81 @@
+import { writeJson } from 'fs-extra';
+import { SHADOW_DIR_NAME, PROTECTED_DEPS, PROTECTED_DEV_DEPS } from '../constants.mjs';
+
+/**
+ * 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.
+ */
+function ensureConsumerWorkspaces(pkg) {
+    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, protectedMap) {
+    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.
+ */
+async function ensureConsumerPkg(pkgPath, pkg) {
+    let changed = false;
+    const next = { ...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 };
+}
+
+export { ensureConsumerPkg, ensureConsumerWorkspaces };

package/dist/esm/shadow/gitignore.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 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 declare function ensureGitignore(consumerDir: string): Promise<void>;
+//# sourceMappingURL=gitignore.d.ts.map

package/dist/esm/shadow/gitignore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gitignore.d.ts","sourceRoot":"","sources":["../../../src/shadow/gitignore.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAoBxE"}

package/dist/esm/shadow/gitignore.mjs

@@ -0,0 +1,29 @@
+import path from 'node:path';
+import { pathExists, readFile, writeFile } from 'fs-extra';
+import { GITIGNORE_ENTRIES } from '../constants.mjs';
+
+/**
+ * Idempotently append our shadow-dir entries to the consumer's .gitignore.
+ * Never modifies existing entries; only appends missing ones. Creates the
+ * file if absent.
+ */
+async function ensureGitignore(consumerDir) {
+    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);
+}
+
+export { ensureGitignore };

package/dist/esm/shadow/merge-package-json.d.ts

@@ -0,0 +1,16 @@
+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 declare function buildShadowPkg(consumerPkg: ConsumerPkg): ShadowPkg;
+/**
+ * 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 declare function hashConsumerDeps(consumer: ConsumerPkg): string;
+export declare function writeShadowPkg(shadowPkgPath: string, shadow: ShadowPkg): Promise<void>;
+//# sourceMappingURL=merge-package-json.d.ts.map

package/dist/esm/shadow/merge-package-json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-package-json.d.ts","sourceRoot":"","sources":["../../../src/shadow/merge-package-json.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAEvD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,WAAW,GAAG,SAAS,CAalE;AAgBD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,WAAW,GAAG,MAAM,CAW9D;AAED,wBAAsB,cAAc,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAE5F"}

package/dist/esm/shadow/merge-package-json.mjs

@@ -0,0 +1,58 @@
+import crypto from 'node:crypto';
+import { writeJson } from 'fs-extra';
+import { SHADOW_SCRIPTS, PROTECTED_DEPS, WORKSPACE_DEV_DEPS } from '../constants.mjs';
+import { mfAppName } from '../util/app-name.mjs';
+
+/**
+ * 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.
+ */
+function buildShadowPkg(consumerPkg) {
+    // 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) {
+    return JSON.stringify(value, (_key, v) => {
+        if (v && typeof v === 'object' && !Array.isArray(v)) {
+            return Object.fromEntries(Object.entries(v).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.
+ */
+function hashConsumerDeps(consumer) {
+    return crypto
+        .createHash('sha256')
+        .update(stableStringify({
+        deps: consumer.dependencies ?? {},
+        devDeps: consumer.devDependencies ?? {},
+        peerDeps: consumer.peerDependencies ?? {},
+    }))
+        .digest('hex');
+}
+async function writeShadowPkg(shadowPkgPath, shadow) {
+    await writeJson(shadowPkgPath, shadow, { spaces: 2 });
+}
+
+export { buildShadowPkg, hashConsumerDeps, writeShadowPkg };

package/dist/esm/shadow/metadata.d.ts

@@ -0,0 +1,4 @@
+import type { ConsumerPaths, ShadowMetadata } from '../types';
+export declare function readMetadata(paths: ConsumerPaths): Promise<ShadowMetadata | null>;
+export declare function writeMetadata(paths: ConsumerPaths, meta: ShadowMetadata): Promise<void>;
+//# sourceMappingURL=metadata.d.ts.map

package/dist/esm/shadow/metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../../../src/shadow/metadata.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE9D,wBAAsB,YAAY,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CASvF;AAED,wBAAsB,aAAa,CAAC,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAE7F"}

package/dist/esm/shadow/metadata.mjs

@@ -0,0 +1,18 @@
+import { pathExists, readJson, writeJson } from 'fs-extra';
+
+async function readMetadata(paths) {
+    if (!(await pathExists(paths.shadowMetadata))) {
+        return null;
+    }
+    try {
+        return (await readJson(paths.shadowMetadata));
+    }
+    catch {
+        return null;
+    }
+}
+async function writeMetadata(paths, meta) {
+    await writeJson(paths.shadowMetadata, meta, { spaces: 2 });
+}
+
+export { readMetadata, writeMetadata };

package/dist/esm/shadow/paths.d.ts

@@ -0,0 +1,3 @@
+import type { ConsumerPaths } from '../types';
+export declare function resolveConsumerPaths(consumerDir: string): ConsumerPaths;
+//# sourceMappingURL=paths.d.ts.map

package/dist/esm/shadow/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../../src/shadow/paths.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE9C,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,CAmBvE"}

package/dist/esm/shadow/paths.mjs

@@ -0,0 +1,25 @@
+import path from 'node:path';
+import { SHADOW_DIR_NAME } from '../constants.mjs';
+
+function resolveConsumerPaths(consumerDir) {
+    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'),
+    };
+}
+
+export { resolveConsumerPaths };

package/dist/esm/shadow/port.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Tries to bind to `port` on localhost; resolves true if the bind succeeds
+ * (port is free) and the listener was cleanly closed.
+ */
+export declare function isPortFree(port: number): Promise<boolean>;
+export declare function pickPort(): Promise<number>;
+//# sourceMappingURL=port.d.ts.map

package/dist/esm/shadow/port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"port.d.ts","sourceRoot":"","sources":["../../../src/shadow/port.ts"],"names":[],"mappings":"AAOA;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOzD;AAOD,wBAAsB,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC,CAQhD"}

package/dist/esm/shadow/port.mjs

@@ -0,0 +1,34 @@
+import net from 'node:net';
+import { MIN_PORT, MAX_PORT } from '../constants.mjs';
+
+function randomPort() {
+    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.
+ */
+function isPortFree(port) {
+    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;
+async function pickPort() {
+    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`);
+}
+
+export { isPortFree, pickPort };

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"prepare.d.ts","sourceRoot":"","sources":["../../../src/shadow/prepare.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAA8B,cAAc,EAAkB,MAAM,UAAU,CAAC;AAE3F,wBAAsB,aAAa,IAAI,OAAO,CAAC,cAAc,CAAC,CAiC7D"}

package/dist/esm/shadow/prepare.mjs

@@ -0,0 +1,60 @@
+import { pathExists, readJson, ensureDir } from 'fs-extra';
+import { info } from '../util/logger.mjs';
+import { cleanAppName } from '../util/app-name.mjs';
+import { resolveConsumerPaths } from './paths.mjs';
+import { ensureGitignore } from './gitignore.mjs';
+import { ensureYarnRc } from './yarnrc.mjs';
+import { ensureConsumerPkg } from './consumer-pkg.mjs';
+import { scaffoldShadow } from './scaffold.mjs';
+import { readMetadata, writeMetadata } from './metadata.mjs';
+import { isPortFree, pickPort } from './port.mjs';
+import { syncShadow } from './sync.mjs';
+
+async function prepareShadow() {
+    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));
+    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, appName) {
+    const existing = await readMetadata(paths);
+    if (existing?.port && (await isPortFree(existing.port))) {
+        return existing;
+    }
+    const next = {
+        createdAt: existing?.createdAt ?? new Date().toISOString(),
+        appName,
+        port: await pickPort(),
+    };
+    await writeMetadata(paths, next);
+    return next;
+}
+
+export { prepareShadow };

package/dist/esm/shadow/scaffold.d.ts

@@ -0,0 +1,7 @@
+import type { ConsumerPaths } from '../types';
+/**
+ * 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 declare function scaffoldShadow(paths: ConsumerPaths, appName: string, port: number): Promise<void>;
+//# sourceMappingURL=scaffold.d.ts.map

package/dist/esm/shadow/scaffold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../../../src/shadow/scaffold.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAqG9C;;;GAGG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAYvG"}