@mondaydotcomorg/z2h-cli 0.1.0 → 0.1.1

package/dist/shadow/merge-package-json.js

@@ -10,23 +10,24 @@ const _interopDefault = e => e && e.__esModule ? e : { default: e };
 const crypto__default = /*#__PURE__*/_interopDefault(crypto);
 
 /**
- * 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.
  */
 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/${util_appName.mfAppName(consumerPkg.name)}`,
         version: '0.0.1',
         private: true,
         scripts: constants.SHADOW_SCRIPTS,
-        peerDependencies: { ...constants.PROTECTED_DEPS },
-        devDependencies: constants.WORKSPACE_DEV_DEPS,
+        devDependencies: { ...constants.SHADOW_DEV_DEPS },
     };
 }
 /**

package/dist/shadow/sync.js

@@ -18,8 +18,8 @@ async function syncShadow(paths, consumerPkg) {
     const oldHash = (await fsExtra.pathExists(paths.shadowDepsHash)) ? await fsExtra.readFile(paths.shadowDepsHash, 'utf8') : null;
     if (oldHash !== newHash) {
         util_logger.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.execa('yarn', ['install'], {
             cwd: paths.consumerDir,
             stdio: 'inherit',

package/dist/templates/app/claude-settings.js

@@ -0,0 +1,13 @@
+Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toStringTag]: { value: 'Module' } });
+
+var permissions = {
+	allow: [
+		"Skill(z2h:*)"
+	]
+};
+const claudeSettings = {
+	permissions: permissions
+};
+
+exports.default = claudeSettings;
+exports.permissions = permissions;

package/dist/types.d.ts

@@ -20,7 +20,6 @@ export interface ShadowPkg {
     version: string;
     private: true;
     scripts: Record<string, string>;
-    peerDependencies: Record<string, string>;
     devDependencies: Record<string, string>;
 }
 export interface ShadowMetadata {

package/dist/types.d.ts.map

@@ -1 +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"}
+{"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;AAOD,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,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/util/__tests__/templates.test.d.ts

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

package/dist/util/__tests__/templates.test.d.ts.map

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

package/dist/util/__tests__/workspace-templates-shipped.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=workspace-templates-shipped.test.d.ts.map

package/dist/util/__tests__/workspace-templates-shipped.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-templates-shipped.test.d.ts","sourceRoot":"","sources":["../../../src/util/__tests__/workspace-templates-shipped.test.ts"],"names":[],"mappings":""}

package/dist/util/__tests__/workspace.test.d.ts

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

package/dist/util/__tests__/workspace.test.d.ts.map

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

package/dist/util/s3/upload.js

@@ -1,8 +1,8 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
 const path = require('node:path');
-const fsExtra = require('fs-extra');
 const promises = require('node:fs/promises');
+const fsExtra = require('fs-extra');
 const mimeTypes = require('mime-types');
 const pMap = require('p-map');
 const clientS3 = require('@aws-sdk/client-s3');

package/dist/util/templates.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Substitute `__PLACEHOLDER__` tokens in `content` with values from `vars`.
+ * Values are inserted literally — no regex special-char interpretation —
+ * which matters for content like `$1` or `&` that could otherwise be
+ * captured by `String.prototype.replace`.
+ */
+export declare function renderTemplate(content: string, vars: Record<string, string>): string;
+/**
+ * Absolute path to the bundled `templates/` directory under `src/`.
+ *
+ * The CLI's `package.json` `files` array ships `src/` (so `src/templates/`
+ * lands in published packages). The build emits `.ts` files to `dist/`,
+ * but raw template assets (`.tmpl`, `.md`, `gitignore`, `.json`) live only
+ * under `src/templates/`. Resolving here keeps a single source of truth
+ * for both:
+ *   - dev (vitest, tsx)             → `<pkg>/src/util/`     +  ../../src/templates  → `<pkg>/src/templates`
+ *   - published install (dist/util) → `<pkg>/dist/util/`    +  ../../src/templates  → `<pkg>/src/templates`
+ */
+export declare function getTemplatesDir(): string;
+export type AppTemplate = 'default' | 'html-embed';
+export declare const APP_TEMPLATES: AppTemplate[];
+//# sourceMappingURL=templates.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../src/util/templates.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAQpF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAGxC;AAED,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,YAAY,CAAC;AACnD,eAAO,MAAM,aAAa,EAAE,WAAW,EAA8B,CAAC"}

package/dist/util/templates.js

@@ -0,0 +1,45 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const path = require('node:path');
+const node_url = require('node:url');
+
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+const _interopDefault = e => e && e.__esModule ? e : { default: e };
+
+const path__default = /*#__PURE__*/_interopDefault(path);
+
+/**
+ * Substitute `__PLACEHOLDER__` tokens in `content` with values from `vars`.
+ * Values are inserted literally — no regex special-char interpretation —
+ * which matters for content like `$1` or `&` that could otherwise be
+ * captured by `String.prototype.replace`.
+ */
+function renderTemplate(content, vars) {
+    let out = content;
+    for (const [key, value] of Object.entries(vars)) {
+        // Use split+join (literal pattern) to avoid regex interpretation of
+        // special chars in `value`.
+        out = out.split(key).join(value);
+    }
+    return out;
+}
+/**
+ * Absolute path to the bundled `templates/` directory under `src/`.
+ *
+ * The CLI's `package.json` `files` array ships `src/` (so `src/templates/`
+ * lands in published packages). The build emits `.ts` files to `dist/`,
+ * but raw template assets (`.tmpl`, `.md`, `gitignore`, `.json`) live only
+ * under `src/templates/`. Resolving here keeps a single source of truth
+ * for both:
+ *   - dev (vitest, tsx)             → `<pkg>/src/util/`     +  ../../src/templates  → `<pkg>/src/templates`
+ *   - published install (dist/util) → `<pkg>/dist/util/`    +  ../../src/templates  → `<pkg>/src/templates`
+ */
+function getTemplatesDir() {
+    const here = path__default.default.dirname(node_url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('util/templates.js', document.baseURI).href))));
+    return path__default.default.resolve(here, '..', '..', 'src', 'templates');
+}
+const APP_TEMPLATES = ['default', 'html-embed'];
+
+exports.APP_TEMPLATES = APP_TEMPLATES;
+exports.getTemplatesDir = getTemplatesDir;
+exports.renderTemplate = renderTemplate;

package/dist/util/workspace.d.ts

@@ -0,0 +1,20 @@
+export declare const WORKSPACE_DIR_NAME = "zth-projects";
+export declare const WORKSPACE_MARKER_FIELD = "z2hWorkspace";
+/**
+ * The Z2H workspace home is hardcoded to `~/zth-projects/` for users.
+ * Tests override via the `Z2H_WORKSPACE_HOME` env var so they can use a
+ * tmp dir without touching the user's real home.
+ */
+export declare function getWorkspaceHome(): string;
+/**
+ * Returns true iff `<dir>/package.json` exists and has `"z2hWorkspace": true`.
+ * Any read or parse error returns false (defensive — callers route to a
+ * helpful message via assertWorkspace).
+ */
+export declare function isZ2hWorkspace(dir: string): Promise<boolean>;
+/**
+ * Resolves to the workspace home path if the marker is present; otherwise
+ * throws an Error pointing the user at `z2h-cli create-workspace`.
+ */
+export declare function assertWorkspace(): Promise<string>;
+//# sourceMappingURL=workspace.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../src/util/workspace.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,kBAAkB,iBAAiB,CAAC;AACjD,eAAO,MAAM,sBAAsB,iBAAiB,CAAC;AAErD;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAMD;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAWlE;AAED;;;GAGG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC,CASvD"}

package/dist/util/workspace.js

@@ -0,0 +1,57 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const path = require('node:path');
+const os = require('node:os');
+const fsExtra = require('fs-extra');
+
+const _interopDefault = e => e && e.__esModule ? e : { default: e };
+
+const path__default = /*#__PURE__*/_interopDefault(path);
+const os__default = /*#__PURE__*/_interopDefault(os);
+
+const WORKSPACE_DIR_NAME = 'zth-projects';
+const WORKSPACE_MARKER_FIELD = 'z2hWorkspace';
+/**
+ * The Z2H workspace home is hardcoded to `~/zth-projects/` for users.
+ * Tests override via the `Z2H_WORKSPACE_HOME` env var so they can use a
+ * tmp dir without touching the user's real home.
+ */
+function getWorkspaceHome() {
+    return process.env.Z2H_WORKSPACE_HOME ?? path__default.default.join(os__default.default.homedir(), WORKSPACE_DIR_NAME);
+}
+/**
+ * Returns true iff `<dir>/package.json` exists and has `"z2hWorkspace": true`.
+ * Any read or parse error returns false (defensive — callers route to a
+ * helpful message via assertWorkspace).
+ */
+async function isZ2hWorkspace(dir) {
+    const pkgPath = path__default.default.join(dir, 'package.json');
+    if (!(await fsExtra.pathExists(pkgPath))) {
+        return false;
+    }
+    try {
+        const pkg = (await fsExtra.readJson(pkgPath));
+        return pkg[WORKSPACE_MARKER_FIELD] === true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolves to the workspace home path if the marker is present; otherwise
+ * throws an Error pointing the user at `z2h-cli create-workspace`.
+ */
+async function assertWorkspace() {
+    const home = getWorkspaceHome();
+    if (await isZ2hWorkspace(home)) {
+        return home;
+    }
+    throw new Error(`No Z2H workspace at ${home}. Run "z2h-cli create-workspace" first ` +
+        `(or set Z2H_WORKSPACE_HOME if you keep the workspace elsewhere).`);
+}
+
+exports.WORKSPACE_DIR_NAME = WORKSPACE_DIR_NAME;
+exports.WORKSPACE_MARKER_FIELD = WORKSPACE_MARKER_FIELD;
+exports.assertWorkspace = assertWorkspace;
+exports.getWorkspaceHome = getWorkspaceHome;
+exports.isZ2hWorkspace = isZ2hWorkspace;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mondaydotcomorg/z2h-cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "bin": "./bin/z2h-cli.js",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -20,7 +20,8 @@
     ]
   },
   "scripts": {
-    "test": "echo noop",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "lint": "trident-library lint",
     "build": "trident-library build",
     "watch": "trident-library build -w"
@@ -46,7 +47,8 @@
     "@types/fs-extra": "^11.0.4",
     "@types/mime-types": "^2.1.4",
     "@types/node": "^22.19.0",
-    "typescript": "^5.7.2"
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.4"
   },
   "repository": {
     "type": "git",

package/src/commands/__tests__/create-workspace.test.ts

@@ -0,0 +1,78 @@
+import path from 'node:path';
+import os from 'node:os';
+import { mkdtemp, rm, writeJson, readJson, ensureDir, pathExists } from 'fs-extra';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { execa } from 'execa';
+import { createWorkspaceCommand } from '../create-workspace';
+
+// Mock execa so `yarn install` doesn't actually run.
+vi.mock('execa', () => ({
+  execa: vi.fn().mockResolvedValue({ stdout: '', stderr: '', exitCode: 0 }),
+}));
+
+describe('create-workspace', () => {
+  let tmp: string;
+
+  beforeEach(async () => {
+    tmp = await mkdtemp(path.join(os.tmpdir(), 'z2h-cw-'));
+    process.env.Z2H_WORKSPACE_HOME = tmp;
+    vi.mocked(execa).mockClear();
+    // After mkdtemp the dir exists and is empty; we want absent for the
+    // "happy path" tests, so remove it.
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  afterEach(async () => {
+    delete process.env.Z2H_WORKSPACE_HOME;
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  it('creates package.json with the marker, gitignore, README, then runs yarn install', async () => {
+    await createWorkspaceCommand({});
+
+    const pkgPath = path.join(tmp, 'package.json');
+    expect(await pathExists(pkgPath)).toBe(true);
+    const pkg = await readJson(pkgPath);
+    expect(pkg.z2hWorkspace).toBe(true);
+    expect(pkg.workspaces).toEqual(['*', '*/.zth']);
+    expect(pkg.private).toBe(true);
+    expect(pkg.dependencies).toBeDefined();
+    expect(pkg.devDependencies).toBeDefined();
+
+    expect(await pathExists(path.join(tmp, '.gitignore'))).toBe(true);
+    expect(await pathExists(path.join(tmp, '.yarnrc.yml'))).toBe(true);
+    expect(await pathExists(path.join(tmp, '.nvmrc'))).toBe(true);
+    expect(await pathExists(path.join(tmp, '.npmrc'))).toBe(true);
+    expect(await pathExists(path.join(tmp, 'README.md'))).toBe(true);
+
+    expect(execa).toHaveBeenCalledWith(
+      'yarn',
+      expect.arrayContaining(['install']),
+      expect.objectContaining({ cwd: tmp })
+    );
+  });
+
+  it('refuses if the target dir is non-empty', async () => {
+    await ensureDir(tmp);
+    await writeJson(path.join(tmp, 'somefile.json'), { hello: 'world' });
+
+    await expect(createWorkspaceCommand({})).rejects.toThrow(/non-empty/);
+    expect(execa).not.toHaveBeenCalled();
+  });
+
+  it('substitutes the current z2h-cli version into the workspace template', async () => {
+    await createWorkspaceCommand({});
+
+    const pkg = await readJson(path.join(tmp, 'package.json'));
+    const cliDep = pkg.devDependencies['@mondaydotcomorg/z2h-cli'];
+    expect(cliDep).toBeTruthy();
+    expect(cliDep).not.toBe('__Z2H_CLI_VERSION__'); // should be substituted
+  });
+
+  it('ships the yarn berry release inline so any `yarn` invocation runs 4.x without corepack', async () => {
+    await createWorkspaceCommand({});
+
+    expect(await pathExists(path.join(tmp, '.yarn', 'releases', 'yarn-4.5.1.cjs'))).toBe(true);
+  });
+});

package/src/commands/__tests__/create.test.ts

@@ -0,0 +1,111 @@
+import path from 'node:path';
+import os from 'node:os';
+import { mkdtemp, rm, writeJson, readJson, ensureDir, pathExists, writeFile } from 'fs-extra';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { execa } from 'execa';
+import { createCommand } from '../create';
+
+vi.mock('execa', () => ({
+  execa: vi.fn().mockResolvedValue({ stdout: '', stderr: '', exitCode: 0 }),
+}));
+
+async function makeWorkspace(tmp: string): Promise<void> {
+  await ensureDir(tmp);
+  await writeJson(path.join(tmp, 'package.json'), {
+    name: '@mondaydotcomorg/zth-projects-workspace',
+    private: true,
+    z2hWorkspace: true,
+    workspaces: ['*', '*/.zth'],
+  });
+}
+
+describe('create', () => {
+  let tmp: string;
+
+  beforeEach(async () => {
+    tmp = await mkdtemp(path.join(os.tmpdir(), 'z2h-c-'));
+    process.env.Z2H_WORKSPACE_HOME = tmp;
+    vi.mocked(execa).mockClear();
+  });
+
+  afterEach(async () => {
+    delete process.env.Z2H_WORKSPACE_HOME;
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  it('refuses when there is no workspace marker', async () => {
+    await expect(createCommand('demo-app', {})).rejects.toThrow(/create-workspace/);
+    expect(execa).not.toHaveBeenCalled();
+  });
+
+  it('rejects invalid app names', async () => {
+    await makeWorkspace(tmp);
+    await expect(createCommand('Invalid_Name', {})).rejects.toThrow(/lowercase kebab-case/);
+    await expect(createCommand('1starts-with-digit', {})).rejects.toThrow(/lowercase kebab-case/);
+  });
+
+  it('refuses when the target app dir already exists and is non-empty', async () => {
+    await makeWorkspace(tmp);
+    const appDir = path.join(tmp, 'demo-app');
+    await ensureDir(appDir);
+    await writeFile(path.join(appDir, 'something.txt'), 'hi');
+    await expect(createCommand('demo-app', {})).rejects.toThrow(/non-empty/);
+  });
+
+  it('scaffolds an app with the default React template', async () => {
+    await makeWorkspace(tmp);
+    await createCommand('demo-app', {});
+
+    const appDir = path.join(tmp, 'demo-app');
+    expect(await pathExists(path.join(appDir, 'package.json'))).toBe(true);
+    expect(await pathExists(path.join(appDir, 'src', 'index.tsx'))).toBe(true);
+    expect(await pathExists(path.join(appDir, '.gitignore'))).toBe(true);
+    expect(await pathExists(path.join(appDir, '.claude', 'settings.json'))).toBe(true);
+    expect(await pathExists(path.join(appDir, 'CLAUDE.md'))).toBe(true);
+
+    const pkg = await readJson(path.join(appDir, 'package.json'));
+    expect(pkg.name).toBe('demo-app');
+    expect(pkg.private).toBe(true);
+    expect(pkg.scripts.start).toBe('z2h-cli dev');
+
+    const indexSrc = (await import('node:fs/promises')).readFile;
+    const content = await indexSrc(path.join(appDir, 'src', 'index.tsx'), 'utf8');
+    expect(content).toContain('export default function DemoApp()');
+    expect(content).not.toContain('__APP_COMPONENT__');
+
+    expect(execa).toHaveBeenCalledWith(
+      'yarn',
+      expect.arrayContaining(['install']),
+      expect.objectContaining({ cwd: tmp })
+    );
+  });
+
+  it('scaffolds an html-embed app and copies the html file', async () => {
+    await makeWorkspace(tmp);
+    const htmlPath = path.join(tmp, 'page.html');
+    await writeFile(htmlPath, '<html><body>Hi</body></html>');
+
+    await createCommand('html-app', { template: 'html-embed', htmlFile: htmlPath });
+
+    const appDir = path.join(tmp, 'html-app');
+    expect(await pathExists(path.join(appDir, 'src', 'page.html'))).toBe(true);
+    const indexContent = await (
+      await import('node:fs/promises')
+    ).readFile(path.join(appDir, 'src', 'index.tsx'), 'utf8');
+    expect(indexContent).toContain("import pageUrl from './page.html?url'");
+    expect(indexContent).toContain('export default function HtmlApp()');
+  });
+
+  it('rejects unknown templates', async () => {
+    await makeWorkspace(tmp);
+    await expect(createCommand('demo', { template: 'nonexistent' })).rejects.toThrow(/unknown template/i);
+  });
+
+  it('rejects --html-file when the file does not exist', async () => {
+    await makeWorkspace(tmp);
+    await expect(createCommand('demo', { template: 'html-embed', htmlFile: '/no/such/file.html' })).rejects.toThrow(
+      /html file/i
+    );
+  });
+});

package/src/commands/create-workspace.ts

@@ -0,0 +1,85 @@
+import path from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { ensureDir, readJson, writeFile, pathExists, readdir, copy } from 'fs-extra';
+import { execa } from 'execa';
+import { info, output, setOutputMode } from '../util/logger';
+import { getWorkspaceHome } from '../util/workspace';
+import { getTemplatesDir, renderTemplate } from '../util/templates';
+
+export interface CreateWorkspaceOptions {
+  json?: boolean;
+}
+
+/**
+ * Read the current z2h-cli version from its own package.json — the version
+ * that gets pinned into the workspace's devDependencies. That way the
+ * workspace's `@mondaydotcomorg/z2h-cli` always matches the version that
+ * bootstrapped it.
+ */
+async function readCurrentCliVersion(): Promise<string> {
+  // util/templates.ts already locates `<package-root>/src/templates`. The
+  // package's own package.json sits two levels above templates/.
+  const templatesDir = getTemplatesDir();
+  const pkgPath = path.resolve(templatesDir, '..', '..', 'package.json');
+  const pkg = (await readJson(pkgPath)) as { version: string };
+  return `^${pkg.version}`;
+}
+
+export async function createWorkspaceCommand(opts: CreateWorkspaceOptions): Promise<void> {
+  if (opts.json) {
+    setOutputMode('json');
+  }
+
+  const home = getWorkspaceHome();
+  const templatesDir = getTemplatesDir();
+  const wsTemplatesDir = path.join(templatesDir, 'workspace');
+
+  // Refuse non-empty target.
+  if (await pathExists(home)) {
+    const entries = await readdir(home);
+    if (entries.length > 0) {
+      throw new Error(`${home} is non-empty. Wipe it before running create-workspace.`);
+    }
+  } else {
+    await ensureDir(home);
+  }
+
+  const [cliVersion, pkgRaw] = await Promise.all([
+    readCurrentCliVersion(),
+    readFile(path.join(wsTemplatesDir, 'package.json.tmpl'), 'utf8'),
+  ]);
+
+  // Sources have plain names (gitignore, yarnrc.yml, nvmrc, npmrc) so they
+  // aren't interpreted as the active config files of *this* package; we
+  // rename to dotfiles at the destination.
+  //
+  // Yarn berry ships inline at .yarn/releases/. The workspace's .yarnrc.yml
+  // sets `yarnPath` to point here, so any `yarn` invocation (system classic
+  // or otherwise) reads the rc, delegates to this binary, and runs as 4.5.1
+  // — no corepack, no global pin needed. Mirrors how bigbrain-z2h ships its
+  // own yarn release.
+  await Promise.all([
+    writeFile(path.join(home, 'package.json'), renderTemplate(pkgRaw, { __Z2H_CLI_VERSION__: cliVersion })),
+    copy(path.join(wsTemplatesDir, 'gitignore'), path.join(home, '.gitignore')),
+    copy(path.join(wsTemplatesDir, 'yarnrc.yml'), path.join(home, '.yarnrc.yml')),
+    copy(path.join(wsTemplatesDir, 'nvmrc'), path.join(home, '.nvmrc')),
+    copy(path.join(wsTemplatesDir, 'npmrc'), path.join(home, '.npmrc')),
+    copy(path.join(wsTemplatesDir, 'README.md'), path.join(home, 'README.md')),
+    copy(
+      path.join(wsTemplatesDir, 'yarn-releases', 'yarn-4.5.1.cjs'),
+      path.join(home, '.yarn', 'releases', 'yarn-4.5.1.cjs')
+    ),
+  ]);
+
+  info(`bootstrapping workspace at ${home}`);
+  await execa('yarn', ['install'], {
+    cwd: home,
+    stdio: 'inherit',
+  });
+
+  output(`[z2h-cli] workspace ready at ${home}`, {
+    ok: true,
+    workspace: home,
+    z2hCliVersion: cliVersion,
+  });
+}