@mondaydotcomorg/z2h-cli 0.1.0 → 0.1.1

package/src/commands/create.ts

@@ -0,0 +1,113 @@
+import path from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { ensureDir, pathExists, readdir, writeFile, copy } from 'fs-extra';
+import { execa } from 'execa';
+import { info, output, setOutputMode } from '../util/logger';
+import { assertWorkspace } from '../util/workspace';
+import { getTemplatesDir, renderTemplate, APP_TEMPLATES, type AppTemplate } from '../util/templates';
+
+export interface CreateOptions {
+  template?: string;
+  htmlFile?: string;
+  json?: boolean;
+}
+
+const APP_NAME_RE = /^[a-z][a-z0-9-]{1,49}$/;
+
+/**
+ * Convert kebab-case to PascalCase. `demo-app` → `DemoApp`.
+ */
+function pascalCase(input: string): string {
+  return input
+    .split('-')
+    .filter(Boolean)
+    .map(part => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('');
+}
+
+/**
+ * Returns true iff `dir` either does not exist or is an empty directory.
+ */
+async function isDirEmpty(dir: string): Promise<boolean> {
+  if (!(await pathExists(dir))) {
+    return true;
+  }
+  const entries = await readdir(dir);
+  return entries.length === 0;
+}
+
+export async function createCommand(appName: string, opts: CreateOptions): Promise<void> {
+  if (opts.json) {
+    setOutputMode('json');
+  }
+
+  // Validate workspace.
+  const workspace = await assertWorkspace();
+
+  // Validate app name.
+  if (!APP_NAME_RE.test(appName)) {
+    throw new Error(
+      `App name "${appName}" is invalid. Use lowercase kebab-case (a-z, 0-9, -), ` +
+        `2-50 chars, starting with a letter.`
+    );
+  }
+
+  // Resolve template.
+  // `--html-file` implies `--template html-embed` unless the user already picked one.
+  const template: AppTemplate = (opts.template ?? (opts.htmlFile ? 'html-embed' : 'default')) as AppTemplate;
+  if (!APP_TEMPLATES.includes(template)) {
+    throw new Error(`Unknown template "${template}". Available: ${APP_TEMPLATES.join(', ')}.`);
+  }
+
+  if (opts.htmlFile && !(await pathExists(opts.htmlFile))) {
+    throw new Error(`HTML file does not exist: ${opts.htmlFile}`);
+  }
+
+  // Validate target dir.
+  const appDir = path.join(workspace, appName);
+  if (!(await isDirEmpty(appDir))) {
+    throw new Error(`${appDir} is non-empty. Pick a different name or wipe it first.`);
+  }
+
+  // Compute substitutions.
+  const vars = {
+    __APP_NAME__: appName,
+    __APP_COMPONENT__: pascalCase(appName),
+  };
+
+  const appTemplatesDir = path.join(getTemplatesDir(), 'app');
+  await ensureDir(path.join(appDir, 'src'));
+  await ensureDir(path.join(appDir, '.claude'));
+
+  // package.json (templated).
+  const pkgRaw = await readFile(path.join(appTemplatesDir, 'package.json.tmpl'), 'utf8');
+  await writeFile(path.join(appDir, 'package.json'), renderTemplate(pkgRaw, vars));
+
+  // src/index.tsx (templated; choice driven by template).
+  const indexTemplate = template === 'html-embed' ? 'html-index.tsx.tmpl' : 'default-index.tsx.tmpl';
+  const indexRaw = await readFile(path.join(appTemplatesDir, indexTemplate), 'utf8');
+  await writeFile(path.join(appDir, 'src', 'index.tsx'), renderTemplate(indexRaw, vars));
+
+  // Copy verbatim files.
+  await copy(path.join(appTemplatesDir, 'gitignore'), path.join(appDir, '.gitignore'));
+  await copy(path.join(appTemplatesDir, 'claude-settings.json'), path.join(appDir, '.claude', 'settings.json'));
+  await copy(path.join(appTemplatesDir, 'CLAUDE.md'), path.join(appDir, 'CLAUDE.md'));
+
+  // html-embed: also copy the source HTML.
+  if (template === 'html-embed' && opts.htmlFile) {
+    await copy(opts.htmlFile, path.join(appDir, 'src', 'page.html'));
+  }
+
+  info(`installing into workspace at ${workspace}`);
+  await execa('yarn', ['install'], {
+    cwd: workspace,
+    stdio: 'inherit',
+  });
+
+  output(`[z2h-cli] app ready at ${appDir}`, {
+    ok: true,
+    appDir,
+    appName,
+    template,
+  });
+}

package/src/constants.ts

@@ -6,45 +6,22 @@
 // ─────────── 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',
-};
-
+// ─────────── Shadow scripts ───────
 export const SHADOW_SCRIPTS: Record<string, string> = {
   start: 'trident start',
   build: 'trident build',
 };
 
+// ─────────── Shadow dev deps ───────
+// Yarn berry only wires a workspace member's `node_modules/.bin/` PATH
+// for packages that member explicitly declares. The shadow's scripts
+// invoke `trident`, so trident-toolkit must be declared here for the
+// bin to resolve. `*` is fine — yarn workspaces resolve the actual
+// version from the workspace root's pinned entry.
+export const SHADOW_DEV_DEPS: Record<string, string> = {
+  '@mondaydotcomorg/trident-toolkit': '*',
+};
+
 // ─────────── 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

package/src/index.ts

@@ -3,6 +3,8 @@ import { devCommand } from './commands/dev';
 import { buildCommand } from './commands/build';
 import { cleanCommand } from './commands/clean';
 import { deployCommand } from './commands/deploy';
+import { createWorkspaceCommand } from './commands/create-workspace';
+import { createCommand } from './commands/create';
 import { errorLog, fail } from './util/logger';
 
 async function main(): Promise<void> {
@@ -77,6 +79,32 @@ async function main(): Promise<void> {
       }
     });
 
+  program
+    .command('create-workspace')
+    .description('Bootstrap the ~/zth-projects/ yarn workspace (one-time setup)')
+    .option('--json', 'emit structured JSON on stdout')
+    .action(async (opts: { json?: boolean }) => {
+      try {
+        await createWorkspaceCommand(opts);
+      } catch (err) {
+        fail(`create-workspace failed: ${(err as Error).message}`, { command: 'create-workspace' }, 1);
+      }
+    });
+
+  program
+    .command('create <app-name>')
+    .description('Scaffold a new Z2H consumer app inside ~/zth-projects/')
+    .option('--template <name>', 'Template name (default | html-embed)')
+    .option('--html-file <path>', 'Path to an HTML file to embed (implies --template html-embed)')
+    .option('--json', 'emit structured JSON on stdout')
+    .action(async (appName: string, opts: { template?: string; htmlFile?: string; json?: boolean }) => {
+      try {
+        await createCommand(appName, opts);
+      } catch (err) {
+        fail(`create failed: ${(err as Error).message}`, { command: 'create' }, 1);
+      }
+    });
+
   await program.parseAsync(process.argv);
 }
 

package/src/shadow/__tests__/consumer-pkg.test.ts

@@ -0,0 +1,56 @@
+import path from 'node:path';
+import os from 'node:os';
+import { mkdtemp, rm, writeJson, readJson } from 'fs-extra';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { ensureConsumerPkg } from '../consumer-pkg';
+
+describe('ensureConsumerPkg (slimmed)', () => {
+  let tmp: string;
+  let pkgPath: string;
+
+  beforeEach(async () => {
+    tmp = await mkdtemp(path.join(os.tmpdir(), 'z2h-pkg-'));
+    pkgPath = path.join(tmp, 'package.json');
+  });
+
+  afterEach(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  it('adds `private: true` when missing', async () => {
+    await writeJson(pkgPath, { name: 'demo', version: '0.0.0' });
+    const result = await ensureConsumerPkg(pkgPath, { name: 'demo', version: '0.0.0' });
+    expect(result.changed).toBe(true);
+    expect(result.pkg.private).toBe(true);
+    const onDisk = await readJson(pkgPath);
+    expect(onDisk.private).toBe(true);
+  });
+
+  it('is a no-op when private:true is already present', async () => {
+    const initial = { name: 'demo', version: '0.0.0', private: true };
+    await writeJson(pkgPath, initial);
+    const result = await ensureConsumerPkg(pkgPath, initial);
+    expect(result.changed).toBe(false);
+    expect(result.pkg.private).toBe(true);
+  });
+
+  it('does NOT add a `workspaces` field', async () => {
+    await writeJson(pkgPath, { name: 'demo' });
+    const result = await ensureConsumerPkg(pkgPath, { name: 'demo' });
+    expect(result.pkg.workspaces).toBeUndefined();
+  });
+
+  it('does NOT inject runtime deps that the workspace root owns', async () => {
+    await writeJson(pkgPath, { name: 'demo' });
+    const result = await ensureConsumerPkg(pkgPath, { name: 'demo' });
+    expect(result.pkg.dependencies).toBeUndefined();
+    expect(result.pkg.devDependencies).toBeUndefined();
+  });
+
+  it('preserves existing dependencies declared by the consumer', async () => {
+    const initial = { name: 'demo', dependencies: { lodash: '^4.0.0' } };
+    await writeJson(pkgPath, initial);
+    const result = await ensureConsumerPkg(pkgPath, initial);
+    expect(result.pkg.dependencies).toEqual({ lodash: '^4.0.0' });
+  });
+});

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

@@ -0,0 +1,44 @@
+import { describe, it, expect } from 'vitest';
+import { buildShadowPkg, hashConsumerDeps } from '../merge-package-json';
+
+describe('buildShadowPkg', () => {
+  it('emits the @trident scope for the name', () => {
+    const shadow = buildShadowPkg({ name: 'demo-app' });
+    expect(shadow.name).toMatch(/^@trident\//);
+  });
+
+  it('marks the shadow private', () => {
+    const shadow = buildShadowPkg({ name: 'demo' });
+    expect(shadow.private).toBe(true);
+  });
+
+  it('declares only trident-toolkit so the trident bin is on the shadow PATH', () => {
+    const shadow = buildShadowPkg({ name: 'demo' });
+    expect(shadow.devDependencies).toEqual({ '@mondaydotcomorg/trident-toolkit': '*' });
+    const asAny = shadow as unknown as Record<string, unknown>;
+    expect(asAny.dependencies).toBeUndefined();
+    expect(asAny.peerDependencies).toBeUndefined();
+  });
+
+  it('uses plain trident scripts (no `-T`); bin resolves via the local devDep', () => {
+    const shadow = buildShadowPkg({ name: 'demo' });
+    expect(shadow.scripts).toEqual({
+      start: 'trident start',
+      build: 'trident build',
+    });
+  });
+});
+
+describe('hashConsumerDeps', () => {
+  it('returns the same hash for equivalent dep maps regardless of key order', () => {
+    const a = hashConsumerDeps({ name: 'x', dependencies: { b: '1', a: '2' } });
+    const b = hashConsumerDeps({ name: 'x', dependencies: { a: '2', b: '1' } });
+    expect(a).toBe(b);
+  });
+
+  it('returns different hashes when deps change', () => {
+    const a = hashConsumerDeps({ name: 'x', dependencies: { a: '1' } });
+    const b = hashConsumerDeps({ name: 'x', dependencies: { a: '2' } });
+    expect(a).not.toBe(b);
+  });
+});

package/src/shadow/consumer-pkg.ts

@@ -1,100 +1,22 @@
 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
+ * The consumer pkg is a thin manifest. Z2H apps live inside a yarn
+ * workspace at `~/zth-projects/`; runtime and dev deps come from the
+ * workspace root, hoisted into a single `node_modules/`.
  *
- * Always extends — never overrides existing fields.
+ * The only thing this file enforces today is `private: true` — apps must
+ * never accidentally publish to npm.
  */
 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 (pkg.private === true) {
+    return { changed: false, pkg };
   }
-
-  if (changed) {
-    await writeJson(pkgPath, next, { spaces: 2 });
-  }
-
-  return { changed, pkg: next };
+  const next: ConsumerPkg = { ...pkg, private: true };
+  await writeJson(pkgPath, next, { spaces: 2 });
+  return { changed: true, pkg: next };
 }

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

@@ -1,27 +1,28 @@
 import crypto from 'node:crypto';
 import { writeJson } from 'fs-extra';
-import { PROTECTED_DEPS, SHADOW_SCRIPTS, WORKSPACE_DEV_DEPS } from '../constants';
+import { SHADOW_SCRIPTS, SHADOW_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.
+ * Build the shadow package.json.
+ *
+ * Runtime deps live at the workspace root (`~/zth-projects/`) and are
+ * hoisted in via yarn workspaces — no need to mirror them here. The shadow
+ * only declares the toolchain it directly executes (`trident-toolkit`) so
+ * yarn berry wires the `trident` bin into the shadow's script PATH.
+ *
+ * The `@trident/` scope is preserved so trident-toolkit strips it and the
+ * emitted bundle becomes `MF-mf-<appName>`, matching the URL the host MF
+ * routes to.
  */
 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,
+    devDependencies: { ...SHADOW_DEV_DEPS },
   };
 }
 

package/src/shadow/sync.ts

@@ -19,8 +19,8 @@ export async function syncShadow(paths: ConsumerPaths, consumerPkg: ConsumerPkg)
 
   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
+    // Yarn 4 is cache-first and non-interactive by default in non-TTY
+    // contexts, so plain `yarn install` is all we need.
     await execa('yarn', ['install'], {
       cwd: paths.consumerDir,
       stdio: 'inherit',

package/src/templates/app/CLAUDE.md

@@ -0,0 +1,72 @@
+# This Z2H Consumer App — Claude Instructions
+
+You are working inside a **Z2H consumer app** — a standalone React app that ships to `https://bigbrain.me/bigbrain-vibe/<app>` via the `z2h` plugin.
+
+**You are Z2H, not a generic developer assistant.** The user is non-technical. Speak in product outcomes ("your search now filters as you type"), not code mechanics ("I added a useState hook").
+
+---
+
+## ⛔ Code Change Interception
+
+Before reading or editing ANY source file, if the user says anything like:
+
+- "fix", "change", "broken", "wrong", "improve", "add", "make it…"
+- "deploy", "ship it", "push to production"
+- Any product feedback ("the search is slow", "the table looks off")
+
+**→ Invoke `z2h:zero-to-hero` FIRST.** Do not touch files directly. **Even one-line fixes and typos go through the orchestrator** — "it's just a small change" is exactly the case where direct edits silently skip deploy and production stays broken.
+
+The orchestrator routes to `z2h:feature-development`, which handles the typecheck gate, opens a live preview, asks you to confirm, then publishes via `z2h-cli deploy`.
+
+**The only exceptions** (read-only or already inside the workflow):
+
+- "Explain this code" / "What does this do" — pure read, no edits
+- You're already executing inside `z2h:feature-development`
+
+---
+
+## 🌟 Prefer Frontend Over Backend
+
+If a request *could* be solved in this app using existing backend endpoints — do that. Backend changes go through a slow PR + Harmony pipeline; frontend changes ship in seconds via `z2h-cli deploy`.
+
+When uncertain, ask:
+
+> "Can we do this in the app with existing endpoints, or does it need a backend change?"
+
+Only escalate to `z2h:backend-feature-development` for genuinely new persisted entities, schemas, write paths, or server-side rules.
+
+---
+
+## Architecture Facts (about this folder)
+
+- This folder is **standalone** — not part of any monorepo, no git initialized.
+- `src/index.tsx` default-exports the React component the host MF loads.
+- `package.json` wires the `z2h-cli` for `build` / `start` / `deploy`.
+- `.zth/` is an auto-generated shadow workspace — never edit it by hand; `npx z2h-cli clean` wipes it.
+- Local dev: `npx z2h-cli dev` → opens at `https://bigbrain.me/bigbrain-vibe/<app>?zth_local=<port>`.
+- Production: `npx z2h-cli deploy` → live at `https://bigbrain.me/bigbrain-vibe/<app>`.
+- There is no git, no PR, no CI. The gate is: lint pass → typecheck pass → user previews and approves.
+
+---
+
+## ⛔ No Agent Visual Testing
+
+When you make a change, **do not screenshot, do not run `axcli chrome`, do not run `playwright-cli`, do not open browser tabs**. The user is sitting in front of the live preview and verifies with their own eyes — HMR updates instantly. Edit → tell the user → wait for their approval. Agent-side visual checks have proven slow and unreliable in this flow.
+
+---
+
+## Tone (mandatory)
+
+Banned in user-facing output: PR, branch, merge, CI, deploy (as noun), S3, manifest, lint, ESLint, TypeScript, repo, monorepo, microfrontend, MF, yarn, npm, tsx, jsx, scss, commit, push.
+
+Use instead: "changes", "code quality check", "publish", "go live", "your app".
+
+Every step transition includes a time estimate. Transition pattern: what just finished → what's next → how long.
+
+---
+
+## Where the Skills Live
+
+The Z2H plugin is installed globally — every Claude session has access to `z2h:zero-to-hero`, `z2h:feature-development`, `z2h:run-mf-locally`, `z2h:plan`, etc. **Always go through `z2h:zero-to-hero`** for user requests; never invoke sub-skills directly.
+
+If `z2h:zero-to-hero` is not available in this session, the plugin isn't installed in the user's Claude config. Direct them to: `claude plugin marketplace add <bigbrain-z2h-path>` then `claude plugin install z2h`.

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

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Skill(z2h:*)"
+    ]
+  }
+}

package/src/templates/app/default-index.tsx.tmpl

@@ -0,0 +1,21 @@
+// Always import the default React alongside any named hooks. Trident's MFE
+// federation initializes the shared `react` module via the default-import
+// code path; pure named-only imports resolve to null at runtime.
+import React, { useState } from 'react';
+
+export default function __APP_COMPONENT__() {
+  const [count, setCount] = useState(0);
+
+  return (
+    <div style={{ width: '100vw', padding: 24, fontFamily: 'system-ui, sans-serif' }}>
+      <h1>Hello from Z2H 👋</h1>
+      <p>Edit <code>src/index.tsx</code> and the page will hot-reload.</p>
+      <button
+        onClick={() => setCount(c => c + 1)}
+        style={{ padding: '8px 16px', fontSize: 16, cursor: 'pointer' }}
+      >
+        Clicked {count} times
+      </button>
+    </div>
+  );
+}

package/src/templates/app/gitignore

@@ -0,0 +1,4 @@
+# z2h-cli
+.zth/
+build/
+node_modules/

package/src/templates/app/html-index.tsx.tmpl

@@ -0,0 +1,21 @@
+// HTML-embed entrypoint. Renders src/page.html in an iframe, with the file
+// imported via Vite's `?url` suffix so Vite's dev server hosts it at
+// /src/page.html (and copies it to /assets/ at build time). Same-origin
+// (the URL lives under whatever host is rendering the app), so the page's
+// fetch() calls carry bigbrain.me auth cookies normally.
+//
+// The iframe gives the page its own document — scripts execute natively,
+// CSS/JS is fully isolated from the host React app, no script reinjection
+// logic needed.
+import React from 'react';
+import pageUrl from './page.html?url';
+
+export default function __APP_COMPONENT__() {
+  return (
+    <iframe
+      src={pageUrl}
+      title="App"
+      style={{ width: '100vw', height: '100vh', border: 'none', display: 'block' }}
+    />
+  );
+}

package/src/templates/app/package.json.tmpl

@@ -0,0 +1,13 @@
+{
+  "name": "__APP_NAME__",
+  "version": "0.0.0",
+  "private": true,
+  "scripts": {
+    "build": "z2h-cli build",
+    "start": "z2h-cli dev",
+    "deploy": "z2h-cli deploy"
+  },
+  "devDependencies": {
+    "@mondaydotcomorg/z2h-cli": "*"
+  }
+}

package/src/templates/workspace/README.md

@@ -0,0 +1,39 @@
+# Z2H Projects Workspace
+
+This folder hosts every Z2H consumer app you build. Each subfolder is a standalone
+React app that ships to `https://bigbrain.me/bigbrain-vibe/<app>`.
+
+## How it works
+
+- This folder is a **yarn workspace**. All apps share one `node_modules/` and one
+  `yarn.lock` — installs are fast, deps stay consistent across apps.
+- Each app folder is a workspace member; the per-app `.zth/` folder (auto-generated
+  by the Z2H CLI) is also a workspace member, kept in sync with the CLI version.
+- Do not edit `node_modules/`, `yarn.lock`, or any `.zth/` folder by hand.
+
+## Add an app
+
+```bash
+z2h-cli create <app-name>
+```
+
+Templates: `default` (React entry, the usual case) and `html-embed` (drops an
+existing `.html` file into an iframe). Add `--template html-embed --html-file <path>`
+for the second flow.
+
+## Run / deploy an app
+
+```bash
+cd <app-name>
+z2h-cli dev      # local preview at https://bigbrain.me/bigbrain-vibe/<app>?zth_local=<port>
+z2h-cli deploy   # publishes to S3, live at https://bigbrain.me/bigbrain-vibe/<app>
+```
+
+## Reset
+
+If you need a clean slate:
+
+```bash
+rm -rf ~/zth-projects
+z2h-cli create-workspace
+```