@topolo/cli 0.5.1 → 0.6.0

package/dist/generate-wrangler.mjs

@@ -0,0 +1,911 @@
+#!/usr/bin/env node
+// Generate every wrangler.toml + topolo.cloudcontrol.json from topolo.app.json.
+//
+// Run from an app's repo root:
+//   node ../../topolo-platform/tooling/generate-wrangler.mjs
+//
+// The generated files are gitignored — they are build artifacts, not hand-edited
+// source files. Drift is impossible by construction.
+//
+// Usage:
+//   node generate-wrangler.mjs [--manifest=<path>] [--dry-run] [--check]
+//
+// Defaults:
+//   --manifest=$PWD/topolo.app.json
+//
+// Flags:
+//   --dry-run  Print to stdout, don't write.
+//   --check    Generate to temp + diff against existing tracked files; non-zero on drift. Used in CI.
+
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { resolve, dirname, join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+const args = Object.fromEntries(
+  process.argv.slice(2)
+    .filter((a) => a.startsWith('--'))
+    .map((a) => {
+      const m = a.match(/^--([^=]+)(?:=(.*))?$/);
+      return [m[1], m[2] === undefined ? true : m[2]];
+    })
+);
+
+const MANIFEST_INPUT = resolve(process.cwd(), args.manifest || 'topolo.app.json');
+const DRY_RUN = !!args['dry-run'];
+const CHECK = !!args.check;
+
+if (!existsSync(MANIFEST_INPUT)) {
+  console.error(`[generate] manifest not found: ${MANIFEST_INPUT}`);
+  process.exit(2);
+}
+
+// Resolve both through realpath so they agree about symlinked roots (macOS
+// /tmp -> /private/tmp, symlinked checkouts). If they disagree, the `# Manifest:`
+// header below — relative(<target dir>, MANIFEST_PATH) — escapes the app and
+// bakes a machine-specific absolute path into a COMMITTED artifact, which then
+// reads as drift on every other machine.
+const CWD = realpathSync(process.cwd());
+const MANIFEST_PATH = realpathSync(MANIFEST_INPUT);
+
+const manifest = JSON.parse(readFileSync(MANIFEST_PATH, 'utf8'));
+
+// --------------------------------------------------------------------------
+// Helpers
+// --------------------------------------------------------------------------
+const ENV_PRIORITY = ['development', 'staging', 'production'];
+const WORKER_RUNTIME_PACKAGE = '@topolo-io/worker-runtime';
+const FRONTEND_PACKAGES = new Set(['react', 'react-dom', 'astro', 'next']);
+const NEXUS_GATEWAY_URLS = {
+  development: 'https://nexus.topolo.dev',
+  staging: 'https://nexus.stg.topolo.us',
+  production: 'https://nexus.topolo.app',
+};
+const ENVS = Object.keys(manifest.environments || {}).sort((a, b) => {
+  const ai = ENV_PRIORITY.indexOf(a);
+  const bi = ENV_PRIORITY.indexOf(b);
+  if (ai !== -1 || bi !== -1) {
+    if (ai === -1) return 1;
+    if (bi === -1) return -1;
+    return ai - bi;
+  }
+  return a.localeCompare(b);
+});
+const ENV_SET = new Set(ENVS);
+
+function fail(msg) { console.error(`[generate] ERROR: ${msg}`); process.exit(2); }
+
+function isPerEnvObject(v) {
+  return v && typeof v === 'object' && !Array.isArray(v)
+    && Object.keys(v).some((k) => ENV_SET.has(k))
+    && Object.keys(v).every((k) => ENV_SET.has(k));
+}
+
+function valueForEnv(v, env) {
+  if (isPerEnvObject(v)) return v[env];
+  return v;
+}
+
+function tomlString(v) {
+  if (typeof v === 'string') return JSON.stringify(v);
+  if (typeof v === 'number' || typeof v === 'boolean') return String(v);
+  return JSON.stringify(v);
+}
+
+function tomlValue(v) {
+  if (Array.isArray(v)) return `[${v.map(tomlValue).join(', ')}]`;
+  if (v && typeof v === 'object') {
+    return `{ ${Object.entries(v).map(([key, value]) => `${key} = ${tomlValue(value)}`).join(', ')} }`;
+  }
+  return tomlString(v);
+}
+
+function deriveHost(target, env) {
+  if (target.hostOverride && target.hostOverride[env]) return target.hostOverride[env];
+  if (!target.subdomain) return null;
+  return `${target.subdomain}.${manifest.environments[env].domain}`;
+}
+
+// The canonical public host for cloudcontrol domains/url. Prefers the
+// subdomain-derived host; falls back to the first custom_domain route for the
+// env (for complex multi-route targets that don't use a subdomain).
+function primaryHost(target, env) {
+  const h = deriveHost(target, env);
+  if (h) return h;
+  for (const r of target.routes || []) {
+    if (r.environments && !r.environments.includes(env)) continue;
+    return r.pattern.replace(/\/\*$/, '');
+  }
+  return null;
+}
+
+// Host taken from a target's declared `publicUrl` (per-env string or map).
+// Used only for cloudcontrol reporting — see the note in emitCloudcontrol.
+function publicUrlHost(target, env) {
+  const url = valueForEnv(target.publicUrl, env);
+  if (!url) return null;
+  try {
+    return new URL(url).host;
+  } catch {
+    return String(url).replace(/^https?:\/\//, '').replace(/\/.*$/, '') || null;
+  }
+}
+
+function explicitRoutes(target, env) {
+  return (target.routes || [])
+    .filter((r) => !r.environments || r.environments.includes(env))
+    .map((r) => r.pattern);
+}
+
+function targetsIncludingEnv(target, env) {
+  return !target.environments || target.environments.includes(env);
+}
+
+function bindingAppliesToEnv(binding, env) {
+  if (!binding.environments) return true;
+  return binding.environments.includes(env);
+}
+
+function deployTargetName(target, env) {
+  if (env === 'staging') return `${target.wranglerName}-staging`;
+  if (env === 'development') return `${target.wranglerName}-development`;
+  return manifest.governed === true ? target.wranglerName : `${target.wranglerName}-production`;
+}
+
+function targetConfigPath(target) {
+  const configFile = target.deployConfigFile || target.configFile || 'wrangler.toml';
+  return target.dir === '.' ? configFile : `${target.dir}/${configFile}`;
+}
+
+function readDeps(packagePath) {
+  try {
+    const pkg = JSON.parse(readFileSync(packagePath, 'utf8'));
+    return { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+  } catch {
+    return null;
+  }
+}
+
+function targetPackageDeps(target) {
+  let packagePath = resolve(CWD, target.dir, 'package.json');
+  while (!existsSync(packagePath)) {
+    const currentDir = dirname(packagePath);
+    if (currentDir === CWD || currentDir === dirname(currentDir)) return {};
+    packagePath = resolve(dirname(currentDir), 'package.json');
+  }
+  return readDeps(packagePath) ?? {};
+}
+
+// Only the target's own package.json — never an ancestor's. Returns null when
+// the target doesn't have one, which the caller must treat as "unknown", not
+// as "no deps".
+function ownPackageDeps(target) {
+  const packagePath = resolve(CWD, target.dir, 'package.json');
+  if (!existsSync(packagePath)) return null;
+  return readDeps(packagePath);
+}
+
+function usesWorkerRuntime(target) {
+  return Object.prototype.hasOwnProperty.call(targetPackageDeps(target), WORKER_RUNTIME_PACKAGE);
+}
+
+// Frontend-ness is a property of the TARGET, so it must be decided from a
+// per-target signal. targetPackageDeps() walks up to the app root when a target
+// has no package.json of its own, and those hoisted deps describe the whole app
+// — so a root-level `react` would mark every worker in the app a frontend and
+// suppress the NEXUS_GATEWAY_URL injection below, leaving backends to fall back
+// to their prod-Nexus default. Prefer the target's own manifest instead.
+function isFrontendWorkerTarget(target) {
+  const ownDeps = ownPackageDeps(target);
+  // The target declares its own deps: authoritative, and precise enough to tell
+  // an SSR frontend (astro/next) from a worker that merely serves assets.
+  if (ownDeps) return Object.keys(ownDeps).some((dep) => FRONTEND_PACKAGES.has(dep));
+  // Deps are inherited, so they can't discriminate. Serving a built asset
+  // directory is what makes a target a frontend in that case.
+  return hasWorkerAssets(target);
+}
+
+function isRuntimeBackendTarget(target) {
+  return target.kind === 'worker' && usesWorkerRuntime(target) && !isFrontendWorkerTarget(target);
+}
+
+// --------------------------------------------------------------------------
+// Validation
+// --------------------------------------------------------------------------
+for (const k of ['name', 'appId', 'environments', 'targets']) {
+  if (!manifest[k]) fail(`manifest missing required field: ${k}`);
+}
+if (/\b(?:srv|svc)_/.test(String(manifest.appId))) {
+  fail(`appId must be an app_* identifier, not a retired legacy-prefixed id: ${manifest.appId}`);
+}
+for (const env of ENVS) {
+  const e = manifest.environments[env];
+  if (!e?.accountId || !e?.domain) fail(`environments.${env} missing accountId or domain`);
+}
+for (const [name, t] of Object.entries(manifest.targets)) {
+  if (!t.kind || !t.dir) fail(`targets.${name} missing kind/dir`);
+  if (!['worker', 'none'].includes(t.kind)) fail(`targets.${name}: kind must be "worker" or "none"`);
+  if (t.kind === 'worker' && !t.wranglerName) fail(`targets.${name}: kind=worker requires "wranglerName"`);
+  if (t.kind === 'worker' && !t.main) fail(`targets.${name}: kind=worker requires "main"`);
+  if (t.kind === 'none' && !t.reason) fail(`targets.${name}: kind=none requires "reason"`);
+}
+
+// A production build_command must never select a non-production build flavour.
+// Vite bakes the API hosts into the bundle at build time, so `build:staging` on
+// the production target serves the staging bundle from the production host: it
+// points at *.stg.topolo.us and never at the production API. A single flat
+// buildCommand string is the trap — it is reused verbatim for every env, so an
+// env-specific one silently reaches production. Declare buildCommand per-env.
+//
+// Deliberately asymmetric: `--mode production` on a staging target is NOT an
+// error. It is a legitimate "optimized build" where the staging hosts are passed
+// explicitly as VITE_* vars on the command line.
+const NON_PROD_BUILD_FLAVOUR = /(?:\bbuild:|--mode[ =]|\bCLOUDFLARE_ENV=|\bDEPLOY_ENVIRONMENT=)(development|staging)\b/;
+if (ENV_SET.has('production')) {
+  for (const [name, t] of Object.entries(manifest.targets)) {
+    if (t.kind === 'none' || t.buildCommand === undefined) continue;
+    if (t.environments && !t.environments.includes('production')) continue;
+    const cmd = valueForEnv(t.buildCommand, 'production');
+    if (typeof cmd !== 'string') continue;
+    const hit = cmd.match(NON_PROD_BUILD_FLAVOUR);
+    if (!hit) continue;
+    fail(
+      `targets.${name}.buildCommand builds the ${hit[1]} flavour for production (matched "${hit[0]}"):\n`
+      + `           ${cmd}\n`
+      + `         Production would serve the ${hit[1]} bundle, pointing at ${hit[1]} APIs.\n`
+      + `         Declare buildCommand per-environment instead:\n`
+      + `           "buildCommand": { "staging": "<staging build>", "production": "<production build>" }`
+    );
+  }
+}
+
+// --------------------------------------------------------------------------
+// Per-target wrangler.toml emission
+// --------------------------------------------------------------------------
+function emitWranglerToml(targetName, target) {
+  const lines = [];
+  lines.push(`# THIS FILE IS GENERATED from topolo.app.json by topolo-platform/tooling/generate-wrangler.mjs`);
+  lines.push(`# DO NOT HAND-EDIT — your changes will be overwritten on next build/deploy.`);
+  lines.push(`# Manifest: ${relative(resolve(CWD, target.dir), MANIFEST_PATH)}`);
+  lines.push(`# Target:   ${targetName}`);
+  lines.push('');
+
+  lines.push(`name = ${tomlString(target.wranglerName)}`);
+  lines.push(`compatibility_date = ${tomlString(manifest.compatibilityDate || '2026-05-01')}`);
+  if (target.compatibilityFlags?.length) {
+    lines.push(`compatibility_flags = ${JSON.stringify(target.compatibilityFlags)}`);
+  }
+  if (target.main) {
+    lines.push(`main = ${tomlString(target.main)}`);
+  }
+  lines.push('');
+
+  // [assets] block — Worker static assets. Top-level plus an env mirror below.
+  if (hasWorkerAssets(target)) {
+    lines.push('[assets]');
+    lines.push(`directory = ${tomlString(target.assets.directory || target.outputDir || 'dist')}`);
+    if (target.assets.binding) lines.push(`binding = ${tomlString(target.assets.binding)}`);
+    else lines.push(`binding = "ASSETS"`);
+    if (target.assets.notFoundHandling) lines.push(`not_found_handling = ${tomlString(target.assets.notFoundHandling)}`);
+    if (target.assets.runWorkerFirst !== undefined) lines.push(`run_worker_first = ${tomlString(target.assets.runWorkerFirst)}`);
+    lines.push('');
+  }
+
+  // Durable Object migrations — top-level [[migrations]] blocks (DO class
+  // lifecycle tags). Required for workers that declare durable objects.
+  for (const m of target.migrations || []) {
+    lines.push('[[migrations]]');
+    if (m.tag) lines.push(`tag = ${tomlString(m.tag)}`);
+    if (m.new_classes) lines.push(`new_classes = ${tomlValue(m.new_classes)}`);
+    if (m.new_sqlite_classes) lines.push(`new_sqlite_classes = ${tomlValue(m.new_sqlite_classes)}`);
+    if (m.renamed_classes) lines.push(`renamed_classes = ${tomlValue(m.renamed_classes)}`);
+    if (m.deleted_classes) lines.push(`deleted_classes = ${tomlValue(m.deleted_classes)}`);
+    lines.push('');
+  }
+
+  // Top-level [vars]: ONLY values stable across envs (appId identity echo +
+  // sharedVars resolved to scalars). Per-target vars are NEVER hoisted to
+  // top-level because
+  // wrangler treats top-level [vars] as a fallback — and the fallback should
+  // never carry env-specific values that could leak across envs.
+  const topVars = collectTopLevelVars();
+  if (Object.keys(topVars).length) {
+    lines.push('[vars]');
+    for (const [k, v] of Object.entries(topVars)) {
+      if (v === undefined) continue;
+      lines.push(`${k} = ${tomlString(v)}`);
+    }
+    lines.push('');
+  }
+
+  if (target.observability !== false) {
+    lines.push('[observability]');
+    lines.push('enabled = true');
+    lines.push('');
+  }
+
+  // [cache] — Cloudflare Workers Cache. Emit explicit true and false values so
+  // a target can reliably turn off caching that an earlier version enabled.
+  // Omitting the block during that transition can leave the remote setting on.
+  if (typeof target.cache?.enabled === 'boolean') {
+    lines.push('[cache]');
+    lines.push(`enabled = ${target.cache.enabled}`);
+    lines.push('');
+  }
+
+  for (const env of ENVS) {
+    // Honor a target-level environments filter (e.g. production-only redirect worker).
+    if (target.environments && !target.environments.includes(env)) continue;
+    lines.push(`# ──────── ${env} ────────`);
+    const accountId = manifest.environments[env].accountId;
+    // [env.X] header — emit worker account_id / workers_dev scalars.
+    const envHeaderLines = [];
+    envHeaderLines.push(`account_id = ${tomlString(accountId)}`);
+    const wd = (target.workersDev !== undefined) ? target.workersDev : (env !== 'production');
+    envHeaderLines.push(`workers_dev = ${wd ? 'true' : 'false'}`);
+    if (envHeaderLines.length) {
+      lines.push(`[env.${env}]`);
+      lines.push(...envHeaderLines);
+      lines.push('');
+    }
+
+    // Vars
+    const envVars = collectVars(target, env);
+    const envVarEntries = Object.entries(envVars).filter(([, v]) => v !== undefined);
+    if (envVarEntries.length) {
+      lines.push(`[env.${env}.vars]`);
+      for (const [k, v] of envVarEntries) {
+        lines.push(`${k} = ${tomlString(v)}`);
+      }
+      lines.push('');
+    }
+
+    // Custom-domain route (derived from subdomain + domain, or hostOverride)
+    const host = deriveHost(target, env);
+    if (host) {
+      lines.push(`[[env.${env}.routes]]`);
+      lines.push(`pattern = ${tomlString(host)}`);
+      lines.push(`custom_domain = true`);
+      lines.push('');
+    }
+
+    // Explicit routes (zone routes / non-custom-domain patterns)
+    for (const r of target.routes || []) {
+      if (r.environments && !r.environments.includes(env)) continue;
+      lines.push(`[[env.${env}.routes]]`);
+      lines.push(`pattern = ${tomlString(r.pattern)}`);
+      if (r.customDomain) {
+        lines.push(`custom_domain = true`);
+      } else if (r.zoneName) {
+        lines.push(`zone_name = ${tomlString(r.zoneName)}`);
+      }
+      lines.push('');
+    }
+
+    // Per-env [env.X.assets] mirror — wrangler does NOT inherit top-level
+    // [assets] into named environments, so it must be repeated per env.
+    if (hasWorkerAssets(target)) {
+      lines.push(`[env.${env}.assets]`);
+      lines.push(`directory = ${tomlString(target.assets.directory || target.outputDir || 'dist')}`);
+      lines.push(`binding = ${tomlString(target.assets.binding || 'ASSETS')}`);
+      if (target.assets.notFoundHandling) lines.push(`not_found_handling = ${tomlString(target.assets.notFoundHandling)}`);
+      if (target.assets.runWorkerFirst !== undefined) lines.push(`run_worker_first = ${tomlString(target.assets.runWorkerFirst)}`);
+      lines.push('');
+    }
+
+    // Bindings
+    if (target.bindings) {
+      emitBindings(lines, target.bindings, env);
+    }
+
+    // Crons
+    const crons = isPerEnvObject(target.crons) ? target.crons[env] : target.crons;
+    if (crons?.length) {
+      lines.push(`[env.${env}.triggers]`);
+      lines.push(`crons = ${JSON.stringify(crons)}`);
+      lines.push('');
+    }
+  }
+
+  return lines.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd() + '\n';
+}
+
+// A gateway the manifest states explicitly, at either scope, outranks the
+// injected default below. Resolved PER ENV, not by key presence: a per-env map
+// that omits an environment (staging+production but no development is a common
+// shape — the CLI scaffolds it) declares nothing for the env it omits, and that
+// env must still get a default rather than silently inheriting the prod Nexus.
+function declaresGatewayForEnv(target, env) {
+  const declared = (o) => Boolean(o)
+    && Object.prototype.hasOwnProperty.call(o, 'NEXUS_GATEWAY_URL')
+    && valueForEnv(o.NEXUS_GATEWAY_URL, env) !== undefined;
+  return declared(target.vars) || declared(manifest.sharedVars);
+}
+
+// Copy a var block into `out` for one env. A per-env map that omits this env
+// contributes NOTHING — assigning the undefined would clobber a default set
+// earlier (the emitter drops undefined, so the var would vanish entirely).
+function assignForEnv(out, vars, env) {
+  if (!vars) return;
+  for (const [k, v] of Object.entries(vars)) {
+    const value = valueForEnv(v, env);
+    if (value !== undefined) out[k] = value;
+  }
+}
+
+function collectVars(target, env) {
+  const out = {};
+  // Runtime identity binding (env.APP_ID) + the VITE_ var index.html reads into
+  // window.__TOPOLO_APP_ID__ (%VITE_TOPOLO_APP_ID%). Both carry manifest.appId.
+  out.APP_ID = manifest.appId;
+  out.VITE_TOPOLO_APP_ID = manifest.appId;
+  assignForEnv(out, manifest.sharedVars, env);
+  // A backend with no gateway declared anywhere falls back to the PROD Nexus at
+  // runtime, so give it its own environment's. Skipped rather than overridden
+  // when the manifest declares one, so a declared gateway keeps the position the
+  // manifest gives it: assigning here and letting vars overwrite would pin the
+  // key to *this* position and reorder every app that declares it.
+  if (isRuntimeBackendTarget(target) && !declaresGatewayForEnv(target, env)) {
+    out.NEXUS_GATEWAY_URL = NEXUS_GATEWAY_URLS[env];
+  }
+  assignForEnv(out, target.vars, env);
+  if (hasWorkerAssets(target)) assignForEnv(out, target.viteVars, env);
+  return out;
+}
+
+function collectTopLevelVars() {
+  const out = {};
+  out.APP_ID = manifest.appId;
+  out.VITE_TOPOLO_APP_ID = manifest.appId;
+  if (manifest.sharedVars) {
+    for (const [k, v] of Object.entries(manifest.sharedVars)) {
+      // Hoist only if scalar (same across envs). Per-env objects stay in [env.*.vars] only.
+      if (!isPerEnvObject(v)) out[k] = v;
+    }
+  }
+  return out;
+}
+
+function hasWorkerAssets(target) {
+  return target.kind === 'worker' && !!target.assets;
+}
+
+function emitBindings(lines, bindings, env) {
+  for (const d of bindings.d1 || []) {
+    if (!bindingAppliesToEnv(d, env)) continue;
+    const cfg = d[env];
+    if (!cfg) continue;
+    lines.push(`[[env.${env}.d1_databases]]`);
+    lines.push(`binding = ${tomlString(d.binding)}`);
+    lines.push(`database_name = ${tomlString(cfg.databaseName)}`);
+    if (cfg.databaseId) lines.push(`database_id = ${tomlString(cfg.databaseId)}`);
+    if (d.migrationsDir) lines.push(`migrations_dir = ${tomlString(d.migrationsDir)}`);
+    lines.push('');
+  }
+  for (const r of bindings.r2 || []) {
+    if (!bindingAppliesToEnv(r, env)) continue;
+    const cfg = r[env];
+    if (!cfg) continue;
+    lines.push(`[[env.${env}.r2_buckets]]`);
+    lines.push(`binding = ${tomlString(r.binding)}`);
+    lines.push(`bucket_name = ${tomlString(cfg.bucketName)}`);
+    lines.push('');
+  }
+  for (const kv of bindings.kv || []) {
+    if (!bindingAppliesToEnv(kv, env)) continue;
+    const cfg = kv[env];
+    if (!cfg) continue;
+    lines.push(`[[env.${env}.kv_namespaces]]`);
+    lines.push(`binding = ${tomlString(kv.binding)}`);
+    lines.push(`id = ${tomlString(cfg.id)}`);
+    lines.push('');
+  }
+  for (const d of bindings.durableObjects || []) {
+    if (!bindingAppliesToEnv(d, env)) continue;
+    lines.push(`[[env.${env}.durable_objects.bindings]]`);
+    lines.push(`name = ${tomlString(d.binding)}`);
+    lines.push(`class_name = ${tomlString(d.className)}`);
+    if (d.scriptName) lines.push(`script_name = ${tomlString(d.scriptName)}`);
+    lines.push('');
+  }
+  for (const q of bindings.queues?.producers || []) {
+    if (!bindingAppliesToEnv(q, env)) continue;
+    const cfg = q[env];
+    if (!cfg) continue;
+    lines.push(`[[env.${env}.queues.producers]]`);
+    lines.push(`binding = ${tomlString(q.binding)}`);
+    lines.push(`queue = ${tomlString(cfg.queue)}`);
+    lines.push('');
+  }
+  for (const q of bindings.queues?.consumers || []) {
+    if (!bindingAppliesToEnv(q, env)) continue;
+    const cfg = q[env];
+    if (!cfg) continue;
+    lines.push(`[[env.${env}.queues.consumers]]`);
+    lines.push(`queue = ${tomlString(cfg.queue)}`);
+    if (q.maxBatchSize !== undefined) lines.push(`max_batch_size = ${q.maxBatchSize}`);
+    if (q.maxBatchTimeout !== undefined) lines.push(`max_batch_timeout = ${q.maxBatchTimeout}`);
+    if (q.maxRetries !== undefined) lines.push(`max_retries = ${q.maxRetries}`);
+    const deadLetterQueue = valueForEnv(q.deadLetterQueue, env);
+    if (deadLetterQueue !== undefined) lines.push(`dead_letter_queue = ${tomlString(deadLetterQueue)}`);
+    lines.push('');
+  }
+  for (const a of bindings.analyticsEngine || []) {
+    if (!bindingAppliesToEnv(a, env)) continue;
+    const dataset = a[env]?.dataset ?? a.dataset;
+    if (!dataset) continue;
+    lines.push(`[[env.${env}.analytics_engine_datasets]]`);
+    lines.push(`binding = ${tomlString(a.binding)}`);
+    lines.push(`dataset = ${tomlString(dataset)}`);
+    lines.push('');
+  }
+  for (const v of bindings.vectorize || []) {
+    if (!bindingAppliesToEnv(v, env)) continue;
+    // indexName may be a shared scalar OR per-env (v[env].indexName).
+    const indexName = v[env]?.indexName ?? v.indexName;
+    if (!indexName) continue;
+    lines.push(`[[env.${env}.vectorize]]`);
+    lines.push(`binding = ${tomlString(v.binding)}`);
+    lines.push(`index_name = ${tomlString(indexName)}`);
+    lines.push('');
+  }
+  for (const w of bindings.workflows || []) {
+    if (!bindingAppliesToEnv(w, env)) continue;
+    // name may be a shared scalar OR per-env (w[env].name); class_name is shared.
+    const name = w[env]?.name ?? w.name;
+    if (!name || !w.className) continue;
+    lines.push(`[[env.${env}.workflows]]`);
+    lines.push(`binding = ${tomlString(w.binding)}`);
+    lines.push(`name = ${tomlString(name)}`);
+    lines.push(`class_name = ${tomlString(w.className)}`);
+    if (w.scriptName) lines.push(`script_name = ${tomlString(valueForEnv(w.scriptName, env))}`);
+    lines.push('');
+  }
+  for (const s of bindings.services || []) {
+    if (!bindingAppliesToEnv(s, env)) continue;
+    const service = valueForEnv(s.service, env);
+    if (!service) continue;
+    lines.push(`[[env.${env}.services]]`);
+    lines.push(`binding = ${tomlString(s.binding)}`);
+    lines.push(`service = ${tomlString(service)}`);
+    lines.push('');
+  }
+  for (const a of bindings.ai || []) {
+    lines.push(`[env.${env}.ai]`);
+    lines.push(`binding = ${tomlString(a.binding)}`);
+    lines.push('');
+  }
+}
+
+// --------------------------------------------------------------------------
+// topolo.cloudcontrol.json emission — kept in sync because fleet tooling
+// (standard_deploy.py, fleet-rollout, fleet-promote) consumes it.
+// --------------------------------------------------------------------------
+function emitCloudcontrol() {
+  const existing = existsSync(resolve(CWD, 'topolo.cloudcontrol.json'))
+    ? JSON.parse(readFileSync(resolve(CWD, 'topolo.cloudcontrol.json'), 'utf8'))
+    : {};
+
+  const cc = { ...existing };
+  cc.name = manifest.name;
+  const deployableTargets = Object.values(manifest.targets).filter((t) => t.kind !== 'none');
+  const deployableEnvironments = new Set(
+    deployableTargets.flatMap((target) => target.environments || ENVS),
+  );
+  cc.deploy_method = deployableTargets.length ? 'wrangler' : 'none';
+  cc.ci_provider = existing.ci_provider || 'github_actions';
+  cc.quality_policy = existing.quality_policy || {
+    profile: 'first_party_app',
+    coverage: { mode: 'ratchet' },
+    staging_e2e: [],
+  };
+  cc.repo_identity = existing.repo_identity || cc.repo_identity;
+
+  cc.environments = ENVS.filter((env) => deployableEnvironments.has(env)).map((env) => {
+    const publicTarget = firstPublicTarget(env);
+    const host = publicTarget ? primaryHost(publicTarget, env) : null;
+    return {
+      name: env,
+      url: host ? `https://${host}` : null,
+      branch: env === 'production' ? 'main' : env,
+      status: env === 'production' ? 'unknown' : 'active',
+    };
+  });
+
+  const existingDeployTargets = new Map(
+    (existing.deploy_targets || [])
+      .filter((target) => target && target.environment && target.target_name)
+      .map((target) => [`${target.environment}:${target.target_name}`, target])
+  );
+  const cloudControlOnlyFields = ['sdk_app_id', 'agent_callable'];
+
+  cc.deploy_targets = [];
+  for (const env of ENVS) {
+    for (const [tname, t] of Object.entries(manifest.targets)) {
+      if (t.kind === 'none') continue;
+      if (t.environments && !t.environments.includes(env)) continue;
+      const host = primaryHost(t, env);
+      const routes = explicitRoutes(t, env);
+      // cloudcontrol-only host resolution. A target that is fronted by a sibling
+      // worker (Nexus' gateway sits behind the dashboard's service binding) owns
+      // no route of its own, so it has no `subdomain` and primaryHost() is null —
+      // but it still has a public URL that fleet tooling needs. Fall back to
+      // `publicUrl` for the reported domain WITHOUT feeding it into `routes`,
+      // which must keep reflecting only what this worker actually serves.
+      // Deliberately not folded into deriveHost(): that is shared with the
+      // wrangler.toml route emitter, and adding a route there would try to
+      // attach the fronting worker's custom domain to the backing worker.
+      const reportedHost = host || publicUrlHost(t, env);
+      const reportedRoutes = routes.length ? routes : (host ? [host] : []);
+      const d1Migrations = (t.bindings?.d1 || [])
+        .filter((binding) => bindingAppliesToEnv(binding, env) && binding[env])
+        .map((binding) => ({
+          binding: binding.binding,
+          ...(binding.migrationsDir || binding.migrations_dir
+            ? { migrations_dir: binding.migrationsDir || binding.migrations_dir }
+            : {}),
+        }));
+      const targetName = deployTargetName(t, env);
+      const existingTarget = existingDeployTargets.get(`${env}:${targetName}`) || {};
+      const preservedCloudControlFields = Object.fromEntries(
+        cloudControlOnlyFields
+          .filter((field) => Object.prototype.hasOwnProperty.call(existingTarget, field))
+          .map((field) => [field, existingTarget[field]])
+      );
+      cc.deploy_targets.push({
+        kind: t.kind,
+        environment: env,
+        target_name: targetName,
+        cloudflare_account_id: manifest.environments[env].accountId,
+        config_path: targetConfigPath(t),
+        workdir: t.dir || '.',
+        build_command: t.buildCommand !== undefined ? (valueForEnv(t.buildCommand, env) ?? null) : null,
+        output_dir: null,
+        production_branch: env === 'production' ? 'main' : env,
+        healthcheck_path: t.healthcheckPath || '/',
+        domains: reportedHost ? [reportedHost] : [],
+        routes: reportedRoutes,
+        ...(reportedHost ? { api_url: `https://${reportedHost}` } : {}),
+        ...(Array.isArray(t.requiredSecrets) && t.requiredSecrets.length
+          ? { required_secrets: t.requiredSecrets }
+          : {}),
+        ...(d1Migrations.length ? { migrations: { d1: d1Migrations } } : {}),
+        ...preservedCloudControlFields,
+      });
+    }
+  }
+
+  // Preserve externally-managed deploy targets the manifest doesn't drive
+  // (e.g. Astro's generated dist/server/wrangler.json runtime). Identified by a
+  // config_path no manifest target produces.
+  const manifestConfigPaths = new Set(
+    Object.values(manifest.targets).filter((t) => t.kind !== 'none').map((t) => targetConfigPath(t))
+  );
+  for (const dt of (existing.deploy_targets || [])) {
+    if (!ENVS.includes(dt.environment)) continue;
+    if (manifestConfigPaths.has(dt.config_path)) continue;
+    // Only preserve configs GENERATED by another build tool (live under a build
+    // output dir, e.g. Astro's dist/server/wrangler.json). Hand-authored configs
+    // we manage (wrangler.toml / wrangler.jsonc at source paths) must NOT be
+    // preserved — otherwise a jsonc→toml conversion leaves a stale jsonc target.
+    const p = dt.config_path || '';
+    if (!/\/dist\/|^dist\//.test(p)) continue;
+    cc.deploy_targets.push(dt);
+  }
+
+  cc.resource_bindings = [];
+  for (const env of ENVS) {
+    const accountId = manifest.environments[env].accountId;
+    for (const [, t] of Object.entries(manifest.targets)) {
+      if (t.kind === 'none') continue;
+      if (t.environments && !t.environments.includes(env)) continue;
+      if (!t.bindings) continue;
+      for (const d of t.bindings.d1 || []) {
+        if (!bindingAppliesToEnv(d, env) || !d[env]) continue;
+        cc.resource_bindings.push({
+          resource_type: 'd1',
+          binding: d.binding,
+          environment: env,
+          account_id: accountId,
+          resource_name: d[env].databaseName,
+          resource_id: d[env].databaseId ?? null,
+        });
+      }
+      for (const r of t.bindings.r2 || []) {
+        if (!bindingAppliesToEnv(r, env) || !r[env]) continue;
+        cc.resource_bindings.push({
+          resource_type: 'r2',
+          binding: r.binding,
+          environment: env,
+          account_id: accountId,
+          resource_name: r[env].bucketName,
+          resource_id: null,
+        });
+      }
+      for (const kv of t.bindings.kv || []) {
+        if (!bindingAppliesToEnv(kv, env) || !kv[env]) continue;
+        cc.resource_bindings.push({
+          resource_type: 'kv',
+          binding: kv.binding,
+          environment: env,
+          account_id: accountId,
+          resource_name: null,
+          resource_id: kv[env].id,
+        });
+      }
+      for (const q of (t.bindings.queues?.producers || [])) {
+        if (!bindingAppliesToEnv(q, env) || !q[env]) continue;
+        cc.resource_bindings.push({
+          resource_type: 'queue',
+          binding: q.binding,
+          environment: env,
+          account_id: accountId,
+          resource_name: q[env].queue,
+          resource_id: null,
+        });
+      }
+      for (const a of (t.bindings.analyticsEngine || [])) {
+        if (!bindingAppliesToEnv(a, env)) continue;
+        const dataset = a[env]?.dataset ?? a.dataset;
+        if (!dataset) continue;
+        cc.resource_bindings.push({
+          resource_type: 'analytics_engine',
+          binding: a.binding,
+          environment: env,
+          account_id: accountId,
+          resource_name: dataset,
+          resource_id: null,
+        });
+      }
+      for (const v of (t.bindings.vectorize || [])) {
+        if (!bindingAppliesToEnv(v, env)) continue;
+        const indexName = v[env]?.indexName ?? v.indexName;
+        if (!indexName) continue;
+        cc.resource_bindings.push({
+          resource_type: 'vectorize',
+          binding: v.binding,
+          environment: env,
+          account_id: accountId,
+          resource_name: indexName,
+          resource_id: null,
+        });
+      }
+    }
+  }
+
+  cc.resource_bindings = Array.from(new Map(cc.resource_bindings.map((entry) => [
+    [
+      entry.resource_type,
+      entry.binding,
+      entry.environment,
+      entry.account_id,
+      entry.resource_name,
+      entry.resource_id,
+    ].join('\0'),
+    entry,
+  ])).values());
+
+  cc.ci_workflows = existing.ci_workflows || [];
+  // Reconcile ci_targets' deploy_targets references to the canonical target
+  // names. Production targets are suffixed `-production`; a preserved ci_target
+  // that still names the bare worker (the pre-canonicalization prod name) would
+  // make `standard_ci plan` reject the deploy ("references unknown deploy
+  // target"). Map bare -> `<name>-production` when that resolves to a real target.
+  {
+    const validTargetNames = new Set(cc.deploy_targets.map((d) => d.target_name));
+    const coveredTargetNames = new Set();
+    cc.ci_targets = (existing.ci_targets || []).map((ct) => {
+      if (!ct || !Array.isArray(ct.deploy_targets)) return ct;
+      const deployTargets = ct.deploy_targets
+        .map((nm) => {
+          if (validTargetNames.has(nm)) return nm;
+          if (manifest.governed === true && typeof nm === 'string' && nm.endsWith('-production')) {
+            const bareName = nm.slice(0, -'-production'.length);
+            if (validTargetNames.has(bareName)) return bareName;
+          }
+          if (validTargetNames.has(`${nm}-production`)) return `${nm}-production`;
+          // Drop references to targets this manifest doesn't emit — e.g.
+          // TopoloWeb's Astro `web-runtime`, which is excluded from the
+          // generator and deploys via its own wrangler.jsonc + CI. Leaving it
+          // would make standard_ci plan reject the whole deploy.
+          return null;
+        })
+        .filter(Boolean);
+      for (const targetName of deployTargets) coveredTargetNames.add(targetName);
+      return {
+        ...ct,
+        deploy_targets: deployTargets,
+      };
+    });
+    const firstCiTarget = cc.ci_targets.find((ct) => ct && Array.isArray(ct.deploy_targets));
+    const ownsDeployTarget = (ciTarget, deployTarget) => {
+      if (!ciTarget?.path || !deployTarget) return false;
+      const ciPath = `${ciTarget.path}`.replace(/\/+$/, '');
+      const workdir = `${deployTarget.workdir || ''}`.replace(/\/+$/, '');
+      const configPath = `${deployTarget.config_path || ''}`;
+      return workdir === ciPath || workdir.startsWith(`${ciPath}/`) || configPath.startsWith(`${ciPath}/`);
+    };
+    const deployTargetByName = new Map(cc.deploy_targets.map((target) => [target.target_name, target]));
+    const missingGeneratedTargets = cc.deploy_targets
+      .map((target) => target.target_name)
+      .filter((targetName) => validTargetNames.has(targetName) && !coveredTargetNames.has(targetName));
+    for (const targetName of missingGeneratedTargets) {
+      const deployTarget = deployTargetByName.get(targetName);
+      const owningCiTarget = cc.ci_targets.find((ct) =>
+        ct && Array.isArray(ct.deploy_targets) && ownsDeployTarget(ct, deployTarget)
+      ) || firstCiTarget;
+      if (owningCiTarget) {
+        owningCiTarget.deploy_targets = [
+          ...owningCiTarget.deploy_targets,
+          targetName,
+        ];
+      }
+    }
+  }
+  cc.tags = existing.tags || ['application', 'cloudflare', 'github-actions', 'javascript'];
+  cc.cloudflare_account_id = manifest.environments.production.accountId;
+
+  return JSON.stringify(cc, null, 2) + '\n';
+}
+
+function firstPublicTarget(env) {
+  if (manifest.primaryTarget) {
+    const target = manifest.targets[manifest.primaryTarget];
+    if (!target) fail(`primaryTarget references unknown target: ${manifest.primaryTarget}`);
+    if (target.kind === 'none') return null;
+    if (targetsIncludingEnv(target, env) && primaryHost(target, env)) return target;
+  }
+  return Object.values(manifest.targets).filter((t) => t.kind !== 'none' && targetsIncludingEnv(t, env)).find((t) => primaryHost(t, env))
+    || Object.values(manifest.targets).find((t) => t.kind !== 'none' && targetsIncludingEnv(t, env))
+    || null;
+}
+
+// --------------------------------------------------------------------------
+// Write outputs
+// --------------------------------------------------------------------------
+const outputs = [];
+for (const [name, target] of Object.entries(manifest.targets)) {
+  if (target.kind === 'none') continue;
+  if (target.generateConfig === false) continue;
+  const dir = resolve(CWD, target.dir);
+  const outPath = join(dir, target.configFile || 'wrangler.toml');
+  outputs.push({ path: outPath, content: emitWranglerToml(name, target), kind: 'wrangler', target: name });
+}
+outputs.push({ path: resolve(CWD, 'topolo.cloudcontrol.json'), content: emitCloudcontrol(), kind: 'cloudcontrol' });
+
+if (DRY_RUN) {
+  for (const o of outputs) {
+    console.log(`\n=== ${relative(CWD, o.path)} (${o.kind}${o.target ? ':' + o.target : ''}) ===`);
+    process.stdout.write(o.content);
+  }
+  process.exit(0);
+}
+
+if (CHECK) {
+  let drift = false;
+  for (const o of outputs) {
+    if (!existsSync(o.path)) {
+      console.error(`[generate --check] missing: ${relative(CWD, o.path)}`);
+      drift = true;
+      continue;
+    }
+    const cur = readFileSync(o.path, 'utf8');
+    if (cur !== o.content) {
+      console.error(`[generate --check] drift in ${relative(CWD, o.path)}`);
+      const tmp = `/tmp/genwrangler-${process.pid}-${Math.random().toString(36).slice(2)}`;
+      writeFileSync(tmp, o.content);
+      const diff = spawnSync('diff', ['-u', o.path, tmp], { encoding: 'utf8' });
+      if (diff.stdout) process.stderr.write(diff.stdout);
+      drift = true;
+    }
+  }
+  process.exit(drift ? 1 : 0);
+}
+
+for (const o of outputs) {
+  mkdirSync(dirname(o.path), { recursive: true });
+  writeFileSync(o.path, o.content, 'utf8');
+  console.log(`[generate] wrote ${relative(CWD, o.path)}`);
+}