@mondaydotcomorg/z2h-cli 0.25.8 → 0.26.0

package/dist/commands/backend.js

@@ -1,7 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
 const path = require('node:path');
-const node_fs = require('node:fs');
+const fs = require('node:fs');
 const clientS3 = require('@aws-sdk/client-s3');
 const util_logger = require('../util/logger.js');
 const util_appName = require('../util/app-name.js');
@@ -29,7 +29,7 @@ function currentAppName() {
  * play.
  */
 function hasHandlers(appDir) {
-    return node_fs.existsSync(path__default.default.join(appDir, 'backend', 'handlers'));
+    return fs.existsSync(path__default.default.join(appDir, 'backend', 'handlers'));
 }
 /**
  * Read handlers, detect declared integrations, and upload to `prefix` when there

package/dist/commands/deploy.d.ts

@@ -6,6 +6,7 @@ export interface DeployOptions {
     preview?: boolean;
     open?: boolean;
     description?: string;
+    prebuiltDir?: string;
 }
 export declare function deployCommand(opts?: DeployOptions): Promise<void>;
 //# sourceMappingURL=deploy.d.ts.map

package/dist/commands/deploy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../src/commands/deploy.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,KAAK,UAAU,EAA2C,MAAM,4BAA4B,CAAC;AAkBtG,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAWD,wBAAsB,aAAa,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAyB3E"}
+{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../src/commands/deploy.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAE,KAAK,UAAU,EAA2C,MAAM,4BAA4B,CAAC;AAkBtG,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IAIrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAWD,wBAAsB,aAAa,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAyB3E"}

package/dist/commands/deploy.js

@@ -1,6 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
 const os = require('node:os');
+const path = require('node:path');
 const fs = require('fs-extra');
 const util_logger = require('../util/logger.js');
 const shadow_paths = require('../shadow/paths.js');
@@ -26,6 +27,7 @@ const commands_tag = require('./tag.js');
 const _interopDefault = e => e && e.__esModule ? e : { default: e };
 
 const os__default = /*#__PURE__*/_interopDefault(os);
+const path__default = /*#__PURE__*/_interopDefault(path);
 
 /** Who is publishing this version — the machine identity, else the OS user. */
 function whoDeployed() {
@@ -64,7 +66,15 @@ async function deployCommand(opts = {}) {
  * asset manifest Trident emitted.
  */
 async function buildAndStamp(opts) {
-    const { assetManifest } = await commands_build.buildCommand({ publicUrl: opts.publicUrl });
+    let assetManifest;
+    if (opts.prebuiltDir) {
+        util_logger.info(`skipping build — reusing prebuilt bundle from ${opts.prebuiltDir}`);
+        await fs.copy(opts.prebuiltDir, opts.paths.shadowBuild, { overwrite: true });
+        assetManifest = await fs.readJson(path__default.default.join(opts.paths.shadowBuild, 'asset-manifest.json'));
+    }
+    else {
+        ({ assetManifest } = await commands_build.buildCommand({ publicUrl: opts.publicUrl }));
+    }
     const deployedBy = whoDeployed();
     return {
         ...assetManifest,
@@ -109,7 +119,13 @@ async function deployPreview({ paths, consumerName, appName, token, opts }) {
     // and anything unclassified reports as `unknown` via reasonOf() in runCommand.
     const nextVersion = (await util_auth_brokerCredentialProvider.fetchDeployVersion(previewAppName)) + 1;
     util_logger.info('building');
-    const entry = await buildAndStamp({ paths, publicUrl: url, nextVersion, gitRemote: '' });
+    const entry = await buildAndStamp({
+        paths,
+        publicUrl: url,
+        nextVersion,
+        gitRemote: '',
+        prebuiltDir: opts.prebuiltDir,
+    });
     util_logger.info('getting sts credentials');
     const creds = await util_auth_brokerCredentialProvider.brokerCredentialProvider({ appName: previewAppName, previewId })();
     util_s3_client.setupS3Client(creds);
@@ -182,7 +198,7 @@ async function deployLive({ paths, consumerName, appName, token, opts }) {
     const keyPrefix = `${appName}/${nextVersion}`;
     const url = `${constants.BUCKET_READ_DNS_URL}/${keyPrefix}`;
     util_logger.info('building');
-    const entry = await buildAndStamp({ paths, publicUrl: url, nextVersion, gitRemote });
+    const entry = await buildAndStamp({ paths, publicUrl: url, nextVersion, gitRemote, prebuiltDir: opts.prebuiltDir });
     if (opts.dryRun) {
         util_logger.output(`[z2h-cli] dry-run: would upload to s3://${constants.BUCKET_WRITE_NAME}/${keyPrefix}/ as v${version}`, {
             ok: true,

package/dist/commands/generate.d.ts

@@ -0,0 +1,12 @@
+export interface GenerateOptions {
+    template: string;
+    input: string;
+}
+/**
+ * Copies a warm @mondaydotcomorg/z2h-dashboard-templates entry, patches its already-built bundle with real
+ * config data, and previews it — no `z2h-cli build`, no `yarn install`, no live deploy. See
+ * systems/owned/z2h/specs/agent-dashboard-generation.md ("Separating Z2H from its consumers")
+ * in bb-foundations for why this lives here instead of as agent-side MCP tools.
+ */
+export declare function generateCommand(appName: string, opts: GenerateOptions): Promise<void>;
+//# sourceMappingURL=generate.d.ts.map

package/dist/commands/generate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../src/commands/generate.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf;AAwHD;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CA6E3F"}

package/dist/commands/generate.js

@@ -0,0 +1,190 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const path = require('node:path');
+const fs = require('node:fs');
+const node_module = require('node:module');
+const execa = require('execa');
+const fs$1 = require('fs-extra');
+const util_workspace = require('../util/workspace.js');
+const util_appName = require('../util/app-name.js');
+const util_broker_app = require('../util/broker/app.js');
+const util_dashboardTemplates_patchBundle = require('../util/dashboard-templates/patch-bundle.js');
+const util_dashboardTemplates_loadCatalog = require('../util/dashboard-templates/load-catalog.js');
+const util_git_repo = require('../util/git/repo.js');
+const util_logger = require('../util/logger.js');
+
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+const _interopDefault = e => e && e.__esModule ? e : { default: e };
+
+const path__default = /*#__PURE__*/_interopDefault(path);
+const fs__default = /*#__PURE__*/_interopDefault(fs);
+
+// Must match zth-backend-runner's route pattern — fail at generate time, not at first invocation.
+const HANDLER_NAME_RE = /^[a-z][a-z0-9_]{0,63}$/;
+function createSetupAPI(handlersDir) {
+    return {
+        createBackend(handlerName, content) {
+            if (!HANDLER_NAME_RE.test(handlerName)) {
+                throw new Error(`setupBackend: invalid handler name "${handlerName}" — must be lowercase snake_case, matching ${HANDLER_NAME_RE}`);
+            }
+            fs__default.default.writeFileSync(path__default.default.join(handlersDir, `${handlerName}.js`), content);
+        },
+    };
+}
+// Shape is entirely template-defined — validated wholesale against the template's own zod schema,
+// not against any fields z2h-cli itself knows about.
+function parseInput(raw, template) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error('--input must be valid JSON');
+    }
+    const result = template.validateConfig(parsed);
+    if (!result.success) {
+        throw new Error(`--input failed validation against template "${template.id}": ${result.error}`);
+    }
+    return result.data;
+}
+async function isDirEmpty(dir) {
+    if (!(await fs$1.pathExists(dir))) {
+        return true;
+    }
+    return (await fs$1.readdir(dir)).length === 0;
+}
+const DEPENDENCY_FIELDS = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'];
+// A real npm publish already resolves a template's workspace:* deps to real versions before
+// packaging (see trident-monorepo's replaceWorkspaceProtocolInPackage) — this is a no-op there.
+// In this repo's own dev setup (reached via yarn link, unpublished), that never ran, so we resolve
+// it ourselves via require.resolve, same as node would, anchored to this file not to cwd.
+function resolveWorkspaceProtocolDeps(appDir) {
+    const pkgPath = path__default.default.join(appDir, 'package.json');
+    const pkg = JSON.parse(fs__default.default.readFileSync(pkgPath, 'utf8'));
+    const nodeRequire = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('commands/generate.js', document.baseURI).href)));
+    let changed = false;
+    for (const field of DEPENDENCY_FIELDS) {
+        const deps = pkg[field];
+        if (!deps) {
+            continue;
+        }
+        for (const [depName, range] of Object.entries(deps)) {
+            if (!range.startsWith('workspace:')) {
+                continue;
+            }
+            const protocol = range.slice('workspace:'.length);
+            const depPkgPath = nodeRequire.resolve(`${depName}/package.json`);
+            const actualVersion = JSON.parse(fs__default.default.readFileSync(depPkgPath, 'utf8')).version;
+            deps[depName] = protocol === '*' ? actualVersion : `${protocol}${actualVersion}`;
+            changed = true;
+        }
+    }
+    if (changed) {
+        fs__default.default.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+    }
+}
+// Only the top-level package.json needs renaming — deployCommand() reads its "name" to derive
+// the registered app name/URL slug. `.zth/package.json` is NOT patched here: `generate` never
+// rebuilds (deploy runs with --prebuilt-dir), so it's never read; a real rebuild later would
+// regenerate it from the top-level name anyway (see shadow/sync.ts's writeShadowPkg).
+function patchPackageJson(appDir, appName) {
+    const pkgPath = path__default.default.join(appDir, 'package.json');
+    const pkg = JSON.parse(fs__default.default.readFileSync(pkgPath, 'utf8'));
+    pkg.name = appName;
+    delete pkg.devDependencies?.['@mondaydotcomorg/z2h-shared-utils'];
+    fs__default.default.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+    resolveWorkspaceProtocolDeps(appDir);
+}
+// The copied template already ships src/templateConfig.ts as a placeholder — real, typed source
+// kept buildable on its own so the template can be verified independently of the generator.
+function patchConfigSource(appDir, frontendConfig) {
+    const configPath = path__default.default.join(appDir, 'src', 'templateConfig.ts');
+    const placeholder = fs__default.default.readFileSync(configPath, 'utf8');
+    const patched = util_dashboardTemplates_patchBundle.patchOneFile(placeholder, frontendConfig);
+    if (patched === null) {
+        throw new Error(`generate: ${configPath} has no Z2H_CONFIG_V1 anchor — template's placeholder is stale`);
+    }
+    fs__default.default.writeFileSync(configPath, patched);
+}
+// Optional per-template extension point, mirroring setup-backend.ts's contract: decides which
+// fields of the raw, validated --input are safe to ship to the browser. Templates with nothing
+// sensitive to strip (no sql, no secrets) can skip shipping this file entirely — the raw config
+// is used as-is. Compiled from setup-frontend.ts into dist/setup-frontend.js by dashboard-templates'
+// build script (scripts/build-templates.mjs) — a standalone tsc pass, separate from the browser
+// MF build, since this hook is Node-side and never ships to the browser.
+function toFrontendConfig(templateDir, rawConfig) {
+    const setupFrontendPath = path__default.default.join(templateDir, 'dist', 'setup-frontend.js');
+    if (!fs__default.default.existsSync(setupFrontendPath)) {
+        return rawConfig;
+    }
+    const templateRequire = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('commands/generate.js', document.baseURI).href)));
+    const { toFrontendConfig: transform } = templateRequire(setupFrontendPath);
+    return transform(rawConfig);
+}
+/**
+ * Copies a warm @mondaydotcomorg/z2h-dashboard-templates entry, patches its already-built bundle with real
+ * config data, and previews it — no `z2h-cli build`, no `yarn install`, no live deploy. See
+ * systems/owned/z2h/specs/agent-dashboard-generation.md ("Separating Z2H from its consumers")
+ * in bb-foundations for why this lives here instead of as agent-side MCP tools.
+ */
+async function generateCommand(appName, opts) {
+    const workspace = await util_workspace.assertWorkspace();
+    util_appName.validateAppName(appName);
+    const template = util_dashboardTemplates_loadCatalog.findTemplate(opts.template);
+    const rawConfig = parseInput(opts.input, template);
+    const appDir = path__default.default.join(workspace, appName);
+    if (!(await isDirEmpty(appDir))) {
+        throw new Error(`${appDir} is non-empty. Pick a different name or wipe it first.`);
+    }
+    const existing = await util_broker_app.fetchApp(util_appName.mfAppName(appName));
+    if (existing) {
+        throw new Error(`An app named "${appName}" already exists in the Z2H registry. Pick a different name.`);
+    }
+    util_logger.info(`copying template "${template.id}" → ${appDir}`);
+    // Excludes node_modules (installed into templateDir itself by build-templates.mjs, never
+    // needed by the generated app), .build-shadow (a scratch dir that build-templates.mjs
+    // normally cleans up itself — only present here if a prior build crashed mid-way), and
+    // setup-backend/setup-frontend/template (source .ts at templateDir root, compiled .js in dist/ —
+    // generation-time-only files, required() straight from template.templateDir/dist above, never
+    // read again once the app exists, so neither form should end up in the generated app).
+    fs__default.default.cpSync(template.templateDir, appDir, {
+        recursive: true,
+        filter: src => !/[/\\](node_modules|\.build-shadow|setup-backend\.(ts|js)|setup-frontend\.(ts|js)|template\.(ts|js))([/\\]|$)/.test('/' + path__default.default.relative(template.templateDir, src)),
+    });
+    patchPackageJson(appDir, appName);
+    fs__default.default.appendFileSync(path__default.default.join(appDir, '.gitignore'), 'dist/\n');
+    const frontendConfig = toFrontendConfig(template.templateDir, rawConfig);
+    patchConfigSource(appDir, frontendConfig);
+    const patchedBuildDir = path__default.default.join(appDir, '.zth', 'build-patched');
+    util_logger.info('patching prebuilt bundle with real config data');
+    // Source is templateDir/dist/ — built by @mondaydotcomorg/z2h-dashboard-templates' own `build` script (see
+    // packages/dashboard-templates/scripts/build-templates.mjs), never committed to git.
+    util_dashboardTemplates_patchBundle.patchBuiltBundle(path__default.default.join(appDir, 'dist'), patchedBuildDir, frontendConfig);
+    const setupBackendPath = path__default.default.join(template.templateDir, 'dist', 'setup-backend.js');
+    if (fs__default.default.existsSync(setupBackendPath)) {
+        util_logger.info('generating backend handlers via template.setupBackend');
+        const templateRequire = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('commands/generate.js', document.baseURI).href)));
+        const { setupBackend } = templateRequire(setupBackendPath);
+        const handlersDir = path__default.default.join(appDir, 'backend', 'handlers');
+        fs__default.default.mkdirSync(handlersDir, { recursive: true });
+        setupBackend(rawConfig, createSetupAPI(handlersDir));
+    }
+    util_logger.info(`initializing git repo for ${appName}...`);
+    await util_git_repo.initRepo(appDir, util_git_repo.defaultS3Remote(appName));
+    // generate only ever produces a preview — a disposable, shareable synthetic slot. It never
+    // registers a live version; that's a separate, explicit `z2h-cli deploy` the user runs
+    // themselves once they're happy with the preview.
+    util_logger.info('deploying preview');
+    const previewArgs = ['deploy', '--preview', '--prebuilt-dir', patchedBuildDir, '--json', '--open'];
+    const { stdout } = await execa.execa('z2h-cli', previewArgs, { cwd: appDir });
+    const previewResult = JSON.parse(stdout.trim().split('\n').filter(Boolean).at(-1) ?? '{}');
+    util_logger.output(`[z2h-cli] generated "${appName}" from template "${template.id}" ✅\n  preview: ${previewResult.previewUrl}`, {
+        ok: true,
+        appName: util_appName.cleanAppName(appName),
+        templateId: template.id,
+        previewUrl: previewResult.previewUrl,
+        version: previewResult.version,
+    });
+}
+
+exports.generateCommand = generateCommand;

package/dist/commands/templates.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Prints the @mondaydotcomorg/z2h-dashboard-templates catalog — id, title, description, and the
+ * config schema as JSON Schema (each template defines its own whole-config shape;
+ * `generate-app-template` validates `--input` against whichever one is named).
+ */
+export declare function templatesCommand(): Promise<void>;
+//# sourceMappingURL=templates.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../src/commands/templates.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAWtD"}

package/dist/commands/templates.js

@@ -0,0 +1,23 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const util_logger = require('../util/logger.js');
+const util_dashboardTemplates_loadCatalog = require('../util/dashboard-templates/load-catalog.js');
+
+/**
+ * Prints the @mondaydotcomorg/z2h-dashboard-templates catalog — id, title, description, and the
+ * config schema as JSON Schema (each template defines its own whole-config shape;
+ * `generate-app-template` validates `--input` against whichever one is named).
+ */
+async function templatesCommand() {
+    const templates = util_dashboardTemplates_loadCatalog.loadDashboardTemplatesCatalog().map(({ id, title, description, configSchema }) => ({
+        id,
+        title,
+        description,
+        configSchema,
+    }));
+    const templatesInfo = templates.map(t => `${t.id} — ${t.title}\n  ${t.description}`);
+    const hasInfo = templatesInfo.length > 0;
+    util_logger.output(hasInfo ? templatesInfo.join('\n') : '(no templates in catalog)', { ok: true, templates });
+}
+
+exports.templatesCommand = templatesCommand;

package/dist/esm/commands/deploy.d.ts

@@ -6,6 +6,7 @@ export interface DeployOptions {
     preview?: boolean;
     open?: boolean;
     description?: string;
+    prebuiltDir?: string;
 }
 export declare function deployCommand(opts?: DeployOptions): Promise<void>;
 //# sourceMappingURL=deploy.d.ts.map

package/dist/esm/commands/deploy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../../src/commands/deploy.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,KAAK,UAAU,EAA2C,MAAM,4BAA4B,CAAC;AAkBtG,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAWD,wBAAsB,aAAa,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAyB3E"}
+{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../../src/commands/deploy.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAE,KAAK,UAAU,EAA2C,MAAM,4BAA4B,CAAC;AAkBtG,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IAIrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAWD,wBAAsB,aAAa,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAyB3E"}

package/dist/esm/commands/deploy.mjs

@@ -1,5 +1,6 @@
 import os from 'node:os';
-import { readJson, ensureDir } from 'fs-extra';
+import path from 'node:path';
+import { readJson, ensureDir, copy } from 'fs-extra';
 import { info, output, getOutputMode, warn } from '../util/logger.mjs';
 import { resolveConsumerPaths } from '../shadow/paths.mjs';
 import { fetchAppTags, fetchTagCatalog, setAppTags } from '../util/tags.mjs';
@@ -58,7 +59,15 @@ async function deployCommand(opts = {}) {
  * asset manifest Trident emitted.
  */
 async function buildAndStamp(opts) {
-    const { assetManifest } = await buildCommand({ publicUrl: opts.publicUrl });
+    let assetManifest;
+    if (opts.prebuiltDir) {
+        info(`skipping build — reusing prebuilt bundle from ${opts.prebuiltDir}`);
+        await copy(opts.prebuiltDir, opts.paths.shadowBuild, { overwrite: true });
+        assetManifest = await readJson(path.join(opts.paths.shadowBuild, 'asset-manifest.json'));
+    }
+    else {
+        ({ assetManifest } = await buildCommand({ publicUrl: opts.publicUrl }));
+    }
     const deployedBy = whoDeployed();
     return {
         ...assetManifest,
@@ -103,7 +112,13 @@ async function deployPreview({ paths, consumerName, appName, token, opts }) {
     // and anything unclassified reports as `unknown` via reasonOf() in runCommand.
     const nextVersion = (await fetchDeployVersion(previewAppName)) + 1;
     info('building');
-    const entry = await buildAndStamp({ paths, publicUrl: url, nextVersion, gitRemote: '' });
+    const entry = await buildAndStamp({
+        paths,
+        publicUrl: url,
+        nextVersion,
+        gitRemote: '',
+        prebuiltDir: opts.prebuiltDir,
+    });
     info('getting sts credentials');
     const creds = await brokerCredentialProvider({ appName: previewAppName, previewId })();
     setupS3Client(creds);
@@ -176,7 +191,7 @@ async function deployLive({ paths, consumerName, appName, token, opts }) {
     const keyPrefix = `${appName}/${nextVersion}`;
     const url = `${BUCKET_READ_DNS_URL}/${keyPrefix}`;
     info('building');
-    const entry = await buildAndStamp({ paths, publicUrl: url, nextVersion, gitRemote });
+    const entry = await buildAndStamp({ paths, publicUrl: url, nextVersion, gitRemote, prebuiltDir: opts.prebuiltDir });
     if (opts.dryRun) {
         output(`[z2h-cli] dry-run: would upload to s3://${BUCKET_WRITE_NAME}/${keyPrefix}/ as v${version}`, {
             ok: true,

package/dist/esm/commands/generate.d.ts

@@ -0,0 +1,12 @@
+export interface GenerateOptions {
+    template: string;
+    input: string;
+}
+/**
+ * Copies a warm @mondaydotcomorg/z2h-dashboard-templates entry, patches its already-built bundle with real
+ * config data, and previews it — no `z2h-cli build`, no `yarn install`, no live deploy. See
+ * systems/owned/z2h/specs/agent-dashboard-generation.md ("Separating Z2H from its consumers")
+ * in bb-foundations for why this lives here instead of as agent-side MCP tools.
+ */
+export declare function generateCommand(appName: string, opts: GenerateOptions): Promise<void>;
+//# sourceMappingURL=generate.d.ts.map

package/dist/esm/commands/generate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../../src/commands/generate.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf;AAwHD;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CA6E3F"}

package/dist/esm/commands/generate.mjs

@@ -0,0 +1,182 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import { execa } from 'execa';
+import { pathExists, readdir } from 'fs-extra';
+import { assertWorkspace } from '../util/workspace.mjs';
+import { validateAppName, mfAppName, cleanAppName } from '../util/app-name.mjs';
+import { fetchApp } from '../util/broker/app.mjs';
+import { patchBuiltBundle, patchOneFile } from '../util/dashboard-templates/patch-bundle.mjs';
+import { findTemplate } from '../util/dashboard-templates/load-catalog.mjs';
+import { initRepo, defaultS3Remote } from '../util/git/repo.mjs';
+import { info, output } from '../util/logger.mjs';
+
+// Must match zth-backend-runner's route pattern — fail at generate time, not at first invocation.
+const HANDLER_NAME_RE = /^[a-z][a-z0-9_]{0,63}$/;
+function createSetupAPI(handlersDir) {
+    return {
+        createBackend(handlerName, content) {
+            if (!HANDLER_NAME_RE.test(handlerName)) {
+                throw new Error(`setupBackend: invalid handler name "${handlerName}" — must be lowercase snake_case, matching ${HANDLER_NAME_RE}`);
+            }
+            fs.writeFileSync(path.join(handlersDir, `${handlerName}.js`), content);
+        },
+    };
+}
+// Shape is entirely template-defined — validated wholesale against the template's own zod schema,
+// not against any fields z2h-cli itself knows about.
+function parseInput(raw, template) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error('--input must be valid JSON');
+    }
+    const result = template.validateConfig(parsed);
+    if (!result.success) {
+        throw new Error(`--input failed validation against template "${template.id}": ${result.error}`);
+    }
+    return result.data;
+}
+async function isDirEmpty(dir) {
+    if (!(await pathExists(dir))) {
+        return true;
+    }
+    return (await readdir(dir)).length === 0;
+}
+const DEPENDENCY_FIELDS = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'];
+// A real npm publish already resolves a template's workspace:* deps to real versions before
+// packaging (see trident-monorepo's replaceWorkspaceProtocolInPackage) — this is a no-op there.
+// In this repo's own dev setup (reached via yarn link, unpublished), that never ran, so we resolve
+// it ourselves via require.resolve, same as node would, anchored to this file not to cwd.
+function resolveWorkspaceProtocolDeps(appDir) {
+    const pkgPath = path.join(appDir, 'package.json');
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    const nodeRequire = createRequire(import.meta.url);
+    let changed = false;
+    for (const field of DEPENDENCY_FIELDS) {
+        const deps = pkg[field];
+        if (!deps) {
+            continue;
+        }
+        for (const [depName, range] of Object.entries(deps)) {
+            if (!range.startsWith('workspace:')) {
+                continue;
+            }
+            const protocol = range.slice('workspace:'.length);
+            const depPkgPath = nodeRequire.resolve(`${depName}/package.json`);
+            const actualVersion = JSON.parse(fs.readFileSync(depPkgPath, 'utf8')).version;
+            deps[depName] = protocol === '*' ? actualVersion : `${protocol}${actualVersion}`;
+            changed = true;
+        }
+    }
+    if (changed) {
+        fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+    }
+}
+// Only the top-level package.json needs renaming — deployCommand() reads its "name" to derive
+// the registered app name/URL slug. `.zth/package.json` is NOT patched here: `generate` never
+// rebuilds (deploy runs with --prebuilt-dir), so it's never read; a real rebuild later would
+// regenerate it from the top-level name anyway (see shadow/sync.ts's writeShadowPkg).
+function patchPackageJson(appDir, appName) {
+    const pkgPath = path.join(appDir, 'package.json');
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    pkg.name = appName;
+    delete pkg.devDependencies?.['@mondaydotcomorg/z2h-shared-utils'];
+    fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+    resolveWorkspaceProtocolDeps(appDir);
+}
+// The copied template already ships src/templateConfig.ts as a placeholder — real, typed source
+// kept buildable on its own so the template can be verified independently of the generator.
+function patchConfigSource(appDir, frontendConfig) {
+    const configPath = path.join(appDir, 'src', 'templateConfig.ts');
+    const placeholder = fs.readFileSync(configPath, 'utf8');
+    const patched = patchOneFile(placeholder, frontendConfig);
+    if (patched === null) {
+        throw new Error(`generate: ${configPath} has no Z2H_CONFIG_V1 anchor — template's placeholder is stale`);
+    }
+    fs.writeFileSync(configPath, patched);
+}
+// Optional per-template extension point, mirroring setup-backend.ts's contract: decides which
+// fields of the raw, validated --input are safe to ship to the browser. Templates with nothing
+// sensitive to strip (no sql, no secrets) can skip shipping this file entirely — the raw config
+// is used as-is. Compiled from setup-frontend.ts into dist/setup-frontend.js by dashboard-templates'
+// build script (scripts/build-templates.mjs) — a standalone tsc pass, separate from the browser
+// MF build, since this hook is Node-side and never ships to the browser.
+function toFrontendConfig(templateDir, rawConfig) {
+    const setupFrontendPath = path.join(templateDir, 'dist', 'setup-frontend.js');
+    if (!fs.existsSync(setupFrontendPath)) {
+        return rawConfig;
+    }
+    const templateRequire = createRequire(import.meta.url);
+    const { toFrontendConfig: transform } = templateRequire(setupFrontendPath);
+    return transform(rawConfig);
+}
+/**
+ * Copies a warm @mondaydotcomorg/z2h-dashboard-templates entry, patches its already-built bundle with real
+ * config data, and previews it — no `z2h-cli build`, no `yarn install`, no live deploy. See
+ * systems/owned/z2h/specs/agent-dashboard-generation.md ("Separating Z2H from its consumers")
+ * in bb-foundations for why this lives here instead of as agent-side MCP tools.
+ */
+async function generateCommand(appName, opts) {
+    const workspace = await assertWorkspace();
+    validateAppName(appName);
+    const template = findTemplate(opts.template);
+    const rawConfig = parseInput(opts.input, template);
+    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.`);
+    }
+    const existing = await fetchApp(mfAppName(appName));
+    if (existing) {
+        throw new Error(`An app named "${appName}" already exists in the Z2H registry. Pick a different name.`);
+    }
+    info(`copying template "${template.id}" → ${appDir}`);
+    // Excludes node_modules (installed into templateDir itself by build-templates.mjs, never
+    // needed by the generated app), .build-shadow (a scratch dir that build-templates.mjs
+    // normally cleans up itself — only present here if a prior build crashed mid-way), and
+    // setup-backend/setup-frontend/template (source .ts at templateDir root, compiled .js in dist/ —
+    // generation-time-only files, required() straight from template.templateDir/dist above, never
+    // read again once the app exists, so neither form should end up in the generated app).
+    fs.cpSync(template.templateDir, appDir, {
+        recursive: true,
+        filter: src => !/[/\\](node_modules|\.build-shadow|setup-backend\.(ts|js)|setup-frontend\.(ts|js)|template\.(ts|js))([/\\]|$)/.test('/' + path.relative(template.templateDir, src)),
+    });
+    patchPackageJson(appDir, appName);
+    fs.appendFileSync(path.join(appDir, '.gitignore'), 'dist/\n');
+    const frontendConfig = toFrontendConfig(template.templateDir, rawConfig);
+    patchConfigSource(appDir, frontendConfig);
+    const patchedBuildDir = path.join(appDir, '.zth', 'build-patched');
+    info('patching prebuilt bundle with real config data');
+    // Source is templateDir/dist/ — built by @mondaydotcomorg/z2h-dashboard-templates' own `build` script (see
+    // packages/dashboard-templates/scripts/build-templates.mjs), never committed to git.
+    patchBuiltBundle(path.join(appDir, 'dist'), patchedBuildDir, frontendConfig);
+    const setupBackendPath = path.join(template.templateDir, 'dist', 'setup-backend.js');
+    if (fs.existsSync(setupBackendPath)) {
+        info('generating backend handlers via template.setupBackend');
+        const templateRequire = createRequire(import.meta.url);
+        const { setupBackend } = templateRequire(setupBackendPath);
+        const handlersDir = path.join(appDir, 'backend', 'handlers');
+        fs.mkdirSync(handlersDir, { recursive: true });
+        setupBackend(rawConfig, createSetupAPI(handlersDir));
+    }
+    info(`initializing git repo for ${appName}...`);
+    await initRepo(appDir, defaultS3Remote(appName));
+    // generate only ever produces a preview — a disposable, shareable synthetic slot. It never
+    // registers a live version; that's a separate, explicit `z2h-cli deploy` the user runs
+    // themselves once they're happy with the preview.
+    info('deploying preview');
+    const previewArgs = ['deploy', '--preview', '--prebuilt-dir', patchedBuildDir, '--json', '--open'];
+    const { stdout } = await execa('z2h-cli', previewArgs, { cwd: appDir });
+    const previewResult = JSON.parse(stdout.trim().split('\n').filter(Boolean).at(-1) ?? '{}');
+    output(`[z2h-cli] generated "${appName}" from template "${template.id}" ✅\n  preview: ${previewResult.previewUrl}`, {
+        ok: true,
+        appName: cleanAppName(appName),
+        templateId: template.id,
+        previewUrl: previewResult.previewUrl,
+        version: previewResult.version,
+    });
+}
+
+export { generateCommand };

package/dist/esm/commands/templates.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Prints the @mondaydotcomorg/z2h-dashboard-templates catalog — id, title, description, and the
+ * config schema as JSON Schema (each template defines its own whole-config shape;
+ * `generate-app-template` validates `--input` against whichever one is named).
+ */
+export declare function templatesCommand(): Promise<void>;
+//# sourceMappingURL=templates.d.ts.map

package/dist/esm/commands/templates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../../src/commands/templates.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAWtD"}

package/dist/esm/commands/templates.mjs

@@ -0,0 +1,21 @@
+import { output } from '../util/logger.mjs';
+import { loadDashboardTemplatesCatalog } from '../util/dashboard-templates/load-catalog.mjs';
+
+/**
+ * Prints the @mondaydotcomorg/z2h-dashboard-templates catalog — id, title, description, and the
+ * config schema as JSON Schema (each template defines its own whole-config shape;
+ * `generate-app-template` validates `--input` against whichever one is named).
+ */
+async function templatesCommand() {
+    const templates = loadDashboardTemplatesCatalog().map(({ id, title, description, configSchema }) => ({
+        id,
+        title,
+        description,
+        configSchema,
+    }));
+    const templatesInfo = templates.map(t => `${t.id} — ${t.title}\n  ${t.description}`);
+    const hasInfo = templatesInfo.length > 0;
+    output(hasInfo ? templatesInfo.join('\n') : '(no templates in catalog)', { ok: true, templates });
+}
+
+export { templatesCommand };