@mondaydotcomorg/z2h-cli 0.25.9 → 0.26.0

package/src/commands/generate.ts

@@ -0,0 +1,225 @@
+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';
+import { validateAppName, cleanAppName, mfAppName } from '../util/app-name';
+import { fetchApp } from '../util/broker/app';
+import { patchBuiltBundle, patchOneFile, type PatchedConfig } from '../util/dashboard-templates/patch-bundle';
+import { findTemplate, type DashboardTemplateEntry } from '../util/dashboard-templates/load-catalog';
+import { initRepo, defaultS3Remote } from '../util/git/repo';
+import { info, output } from '../util/logger';
+import type {
+  DashboardTemplateSetupAPI,
+  ToFrontendConfigHook,
+  SetupBackendHook,
+} from '@mondaydotcomorg/z2h-shared-utils/dashboard-template-hooks';
+
+export interface GenerateOptions {
+  template: string;
+  input: string; // JSON string, shape defined entirely by the template's own configSchema
+}
+
+// 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: string): DashboardTemplateSetupAPI {
+  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: string, template: DashboardTemplateEntry): PatchedConfig {
+  let parsed: unknown;
+  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 as PatchedConfig;
+}
+
+async function isDirEmpty(dir: string): Promise<boolean> {
+  if (!(await pathExists(dir))) {
+    return true;
+  }
+  return (await readdir(dir)).length === 0;
+}
+
+const DEPENDENCY_FIELDS = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'] as const;
+
+// 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: string): void {
+  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) as [string, string][]) {
+      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')) as { version: string }).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: string, appName: string): void {
+  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: string, frontendConfig: PatchedConfig): void {
+  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: string, rawConfig: PatchedConfig): PatchedConfig {
+  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) as {
+    toFrontendConfig: ToFrontendConfigHook<PatchedConfig>;
+  };
+  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.
+ */
+export async function generateCommand(appName: string, opts: GenerateOptions): Promise<void> {
+  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) as {
+      setupBackend: SetupBackendHook<PatchedConfig>;
+    };
+    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) ?? '{}') as {
+    previewUrl?: string;
+    version?: number;
+  };
+
+  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,
+  });
+}

package/src/commands/templates.ts

@@ -0,0 +1,20 @@
+import { output } from '../util/logger';
+import { loadDashboardTemplatesCatalog } from '../util/dashboard-templates/load-catalog';
+
+/**
+ * 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 async function templatesCommand(): Promise<void> {
+  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 });
+}

package/src/index.ts

@@ -11,6 +11,8 @@ import { deleteCommand } from './commands/delete';
 import { grantCommand, revokeCommand, transferOwnerCommand } from './commands/grant';
 import { createWorkspaceCommand } from './commands/create-workspace';
 import { createCommand, CreateOptions } from './commands/create';
+import { generateCommand, GenerateOptions } from './commands/generate';
+import { templatesCommand } from './commands/templates';
 import { generateZ2HTokenCommand } from './commands/generate-z2h-token';
 import { migrateCommand } from './commands/migrate';
 import { tagCommand } from './commands/tag';
@@ -66,6 +68,7 @@ interface DeployCliOptions {
   remote?: string;
   repoUrl?: string;
   description?: string;
+  prebuiltDir?: string;
 }
 
 async function main(): Promise<void> {
@@ -127,6 +130,10 @@ async function main(): Promise<void> {
       'First deploy only: GitHub repo URL — required when --remote=github. Error if the app already has a git remote.'
     )
     .option('--description <text>', 'short (<=200 char) description of the app')
+    .option(
+      '--prebuilt-dir <path>',
+      'internal — used by `generate-app-template`: skip the build step and deploy this already-built directory as-is'
+    )
     .action(
       runCommand(
         {
@@ -170,7 +177,9 @@ async function main(): Promise<void> {
 
   program
     .command('create <app-name>')
-    .description(`Scaffold a new Z2H consumer app inside ${getWorkspaceHome()}/`)
+    .description(
+      `Scaffold a blank Z2H consumer app inside ${getWorkspaceHome()}/ using a built-in template (default | html-embed). If a catalog template already fits what you're building, use \`generate-app-template\` instead.`
+    )
     .option('--template <name>', 'Template name (default | html-embed)')
     .option('--html-file <path>', 'Path to an HTML file to embed (implies --template html-embed)')
     .option(
@@ -191,6 +200,32 @@ async function main(): Promise<void> {
       )
     );
 
+  program
+    .command('templates')
+    .description(
+      "List the BigBrain Studio (Z2H) template catalog — id, title, description, and each template's widget schema"
+    )
+    .action(runCommand({}, () => templatesCommand()));
+
+  program
+    .command('generate-app-template <app-name>')
+    .description(
+      `Scaffold + preview a Z2H app/dashboard from a templates catalog entry inside ${getWorkspaceHome()}/ — copies a prebuilt template, patches in real widget data, and deploys a preview. No build, no yarn install, no live deploy — run \`z2h-cli deploy\` yourself from the app dir once you're happy with it.`
+    )
+    .requiredOption('--template <id>', 'catalog template id — see `z2h-cli templates --json`')
+    .requiredOption(
+      '--input <json>',
+      "JSON string — shape is template-defined, validated wholesale against the template's configSchema (see `z2h-cli templates --json`)"
+    )
+    .action(
+      runCommand(
+        {
+          data: ([appName, opts]: [string, GenerateOptions]) => ({ app_name: appName, template: opts.template }),
+        },
+        (appName: string, opts: GenerateOptions) => generateCommand(appName, opts)
+      )
+    );
+
   program
     .command('edit <app-name>')
     .description(`Pull the latest version of an app into ${getWorkspaceHome()}/<app-name>, cloning it first if needed`)

package/src/util/dashboard-templates/load-catalog.ts

@@ -0,0 +1,80 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import { z } from 'zod';
+
+export type ValidateConfigResult = { success: true; data: unknown } | { success: false; error: string };
+
+export interface DashboardTemplateEntry {
+  id: string;
+  title: string;
+  description: string;
+  /** Absolute path to this template's dir — source + its already-built .zth/build. */
+  templateDir: string;
+  /** JSON Schema for this template's whole `--input` config object — shape is template-defined. */
+  configSchema: Record<string, unknown>;
+  /** Validates --input against this template's actual zod schema — the JSON Schema above is
+   *  display-only (catalog listing), this is what `generate` really validates against. */
+  validateConfig: (input: unknown) => ValidateConfigResult;
+}
+
+type RawTemplate = Omit<DashboardTemplateEntry, 'templateDir' | 'configSchema' | 'validateConfig'>;
+
+// Each template defines its catalog metadata and its config shape once, in template.ts (compiled
+// to dist/template.js by dashboard-templates' build script) — the JSON Schema used for catalog
+// listing is derived from its zod configSchema here rather than hand-duplicated as a separate JSON
+// literal, and --input validation goes through the same zod schema directly (see validateConfig),
+// so the schema and the TS types templates' own hooks import can never drift apart.
+function loadTemplateModule(
+  templateDir: string
+): { template: RawTemplate; configSchema: Record<string, unknown> } & Pick<DashboardTemplateEntry, 'validateConfig'> {
+  const templateModulePath = path.join(templateDir, 'dist', 'template.js');
+  const { template, configSchema } = createRequire(import.meta.url)(templateModulePath) as {
+    template: RawTemplate;
+    configSchema: z.ZodType;
+  };
+  return {
+    template,
+    // draft-7 is arbitrary here (nothing re-validates against it) — just a reasonably standard,
+    // widely-understood dialect for whatever reads `templates --json`'s output.
+    configSchema: z.toJSONSchema(configSchema, { target: 'draft-7' }) as Record<string, unknown>,
+    validateConfig: input => {
+      const result = configSchema.safeParse(input);
+      return result.success
+        ? { success: true, data: result.data }
+        : { success: false, error: z.prettifyError(result.error) };
+    },
+  };
+}
+
+export function findTemplate(id: string): DashboardTemplateEntry {
+  const templates = loadDashboardTemplatesCatalog();
+  const template = templates.find(t => t.id === id);
+  if (!template) {
+    const known = templates.map(t => t.id).join(', ') || '(none)';
+    throw new Error(`Unknown template "${id}". Available: ${known}.`);
+  }
+  return template;
+}
+
+export function loadDashboardTemplatesCatalog(): DashboardTemplateEntry[] {
+  const catalogDir = path.dirname(
+    createRequire(import.meta.url).resolve('@mondaydotcomorg/z2h-dashboard-templates/package.json')
+  );
+  const templatesRoot = path.join(catalogDir, 'templates');
+  if (!fs.existsSync(templatesRoot)) {
+    return [];
+  }
+
+  return fs
+    .readdirSync(templatesRoot, { withFileTypes: true })
+    .filter(entry => entry.isDirectory())
+    .flatMap(entry => {
+      const templateDir = path.join(templatesRoot, entry.name);
+      if (!fs.existsSync(path.join(templateDir, 'template.ts'))) {
+        return [];
+      }
+      const { template, configSchema, validateConfig } = loadTemplateModule(templateDir);
+      return [{ ...template, templateDir, configSchema, validateConfig }];
+    });
+}

package/src/util/dashboard-templates/patch-bundle.ts

@@ -0,0 +1,127 @@
+// Swaps a template's placeholder config object directly into an ALREADY-BUILT MF bundle by
+// string-patching the minified JS, instead of rerunning `z2h-cli build`. The config object is
+// marked by a `/*! Z2H_CONFIG_V1 */` comment immediately before it — comments are inert to a
+// minifier's dead-code elimination (unlike an object property, which gets stripped the moment
+// nothing in the app statically reads it — see this package's README for how that bit us), and
+// Terser's default `output.comments` setting (`some`) specifically preserves "bang" comments
+// (`/*!` ...) while dropping ordinary ones, which is why the marker must use that exact form.
+//
+// Anchor is shape-agnostic by design: every template in @mondaydotcomorg/z2h-dashboard-templates'
+// catalog must place this comment directly before its OWN placeholder config object, regardless
+// of that template's real configSchema (which varies per template — title+widgets for one
+// template, something else entirely for another) — see that package's README for the contract.
+// This is the one constant every template shares, so this file needs no per-template logic and
+// never reads any of the config's fields itself.
+import fs from 'node:fs';
+import path from 'node:path';
+
+// Comment content collapses whitespace during minification (`/*!Z2H_CONFIG_V1*/` is also valid),
+// hence \s* rather than a literal single space.
+const ANCHOR_RE = /\/\*!\s*Z2H_CONFIG_V1\s*\*\//;
+
+// Generic on purpose: this file never reads the config's fields (only JSON.stringify's the whole
+// object), and the catalog's templates each define their own shape — there is no one fixed shape
+// to name here.
+export type PatchedConfig = Record<string, unknown>;
+
+// The anchor comment sits immediately before the config object (`= /*! Z2H_CONFIG_V1 */ {...}`),
+// so unlike a property-based anchor nested inside the object, this never needs to scan backward
+// to find where the object starts — just forward from the end of the comment match to the next
+// "{", then a standard string-aware brace-depth scan to its matching "}".
+function findObjectAfterAnchor(src: string, anchorEnd: number): { start: number; end: number } {
+  let start = anchorEnd;
+  while (start < src.length && src[start] !== '{') {
+    start++;
+  }
+  if (start >= src.length) {
+    throw new Error('patch-bundle: no "{" found after the anchor comment — anchor may be stale');
+  }
+
+  let braceDepth = 0;
+  let inString = false;
+  let quoteChar = '';
+  let end = -1;
+  for (let i = start; i < src.length; i++) {
+    const ch = src[i];
+    const prev = src[i - 1];
+    if (inString) {
+      if (ch === quoteChar && prev !== '\\') {
+        inString = false;
+      }
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      inString = true;
+      quoteChar = ch;
+      continue;
+    }
+    if (ch === '{') {
+      braceDepth++;
+    } else if (ch === '}') {
+      braceDepth--;
+      if (braceDepth === 0) {
+        end = i;
+        break;
+      }
+    }
+  }
+  if (end === -1) {
+    throw new Error('patch-bundle: could not find matching "}" for the config object — malformed scan');
+  }
+  return { start, end: end + 1 };
+}
+
+// Finds the anchor comment and swaps its immediately-following object literal wholesale. Returns
+// null if this particular source doesn't contain the anchor (not every MF entrypoint does; the
+// caller decides whether that's fatal).
+export function patchOneFile(src: string, config: PatchedConfig): string | null {
+  const match = ANCHOR_RE.exec(src);
+  if (match === null) {
+    return null;
+  }
+  const { start, end } = findObjectAfterAnchor(src, match.index + match[0].length);
+  return src.slice(0, start) + JSON.stringify(config) + src.slice(end);
+}
+
+/**
+ * Reads a built `.zth/build` directory, patches every MF entrypoint's config-object literal
+ * in place with real data, and writes the result to `outDir` (does NOT mutate `sourceBuildDir`
+ * — safe to call against a shared/reused prebuilt bundle). Throws if the placeholder shape
+ * isn't found in ANY entrypoint, since that means the anchor is stale and nothing was patched.
+ */
+export function patchBuiltBundle(
+  sourceBuildDir: string,
+  outDir: string,
+  config: PatchedConfig
+): { patchedFiles: string[] } {
+  const manifestPath = path.join(sourceBuildDir, 'asset-manifest.json');
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8')) as {
+    entrypoints: string[];
+    nonExternalsEntrypoints: string[];
+  };
+  const jsEntries = [...manifest.entrypoints, ...manifest.nonExternalsEntrypoints].filter(f => f.endsWith('.js'));
+
+  fs.rmSync(outDir, { recursive: true, force: true });
+  fs.cpSync(sourceBuildDir, outDir, { recursive: true });
+
+  const patchedFiles: string[] = [];
+  for (const rel of jsEntries) {
+    const outPath = path.join(outDir, rel);
+    const src = fs.readFileSync(outPath, 'utf8');
+    const patched = patchOneFile(src, config);
+    if (patched === null) {
+      continue;
+    }
+
+    new Function(patched); // throws SyntaxError if the patch produced malformed JS — fail loud, not silently
+    fs.writeFileSync(outPath, patched);
+    patchedFiles.push(rel);
+  }
+
+  if (patchedFiles.length === 0) {
+    throw new Error(
+      `patch-bundle: patched 0 of ${jsEntries.length} entrypoint(s) — anchor ${ANCHOR_RE} not found in any of them`
+    );
+  }
+  return { patchedFiles };
+}