@tdk-landscape/tdk-cli-core 1.3.44 → 1.3.48

package/cli/src/generator/template-engine.ts

@@ -0,0 +1,754 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import Handlebars from "handlebars";
+import { PLATFORM_STANDARDS } from "../config/platform-standards.js";
+import type { JsonValue, ProjectConfig } from "../types/index.js";
+import { writeTextFile } from "../utils/file-helpers.js";
+import { discoverResourcesFromRoot } from "../utils/services.js";
+import { isStackFeatureEnabledInStacks } from "../utils/stack-features.js";
+import { hasSablierLicense, hasVerdaccioLicense } from "./extension-fetch.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Helper function to load templates with robust path resolution
+export function loadTemplate(filename: string): string {
+  // Try multiple possible template directory locations
+  const templateDirs = [
+    path.join(__dirname, "..", "..", "templates"), // Standard: dist/generator -> templates (also covers src/generator -> ../../templates in dev/test)
+    path.join(__dirname, "..", "templates"), // Installed: dist/generator -> dist/templates
+    path.join(__dirname, "..", "..", "..", "templates"), // Development: cli/dist/generator -> cli/templates
+    path.join(process.cwd(), "node_modules", "@tdk-landscape", "tdk-cli-core", "templates"), // Monorepo root
+    // Compiled single-file binary (bun build --compile): __dirname resolves inside the
+    // virtual $bunfs filesystem, not a real path, so fall back to the directory the actual
+    // executable lives in. release-binaries.sh bundles cli/templates at tdk-cli/cli/templates
+    // next to the platform binaries.
+    path.join(path.dirname(process.execPath), "tdk-cli", "cli", "templates"),
+  ];
+
+  const triedPaths: string[] = [];
+  for (const templateDir of templateDirs) {
+    const templatePath = path.join(templateDir, filename);
+    triedPaths.push(templatePath);
+    try {
+      return fs.readFileSync(templatePath, "utf-8");
+    } catch (error) {
+      // Try next path
+      continue;
+    }
+  }
+
+  throw new Error(`Failed to load template ${filename} from any of these paths: ${triedPaths.join(", ")}`);
+}
+
+// Templates used to be loaded eagerly here, at module initialization. That
+// meant importing this module at all (e.g. via cli.ts -> config.ts/project.ts)
+// threw immediately whenever the bundled templates folder was missing or
+// stale - bricking every single `tdk` command, including `tdk upgrade`, the
+// one command meant to repair a stale install. Load lazily instead, on first
+// actual use, so commands that don't need templates (upgrade, doctor,
+// version, ...) keep working even when the templates folder is absent, and
+// `tdk upgrade` can run to fix it.
+let embeddedTemplatesCache: Record<string, string> | null = null;
+function getEmbeddedTemplates(): Record<string, string> {
+  if (!embeddedTemplatesCache) {
+    embeddedTemplatesCache = {
+      ".tiltignore": loadTemplate(".tiltignore.hbs"),
+      "TILT_RESOURCE_DEFAULTS.star": loadTemplate("TILT_RESOURCE_DEFAULTS.star.hbs"),
+      "TILT_TECH_STACK.star": loadTemplate("TILT_TECH_STACK.star.hbs"),
+      Tiltfile: loadTemplate("Tiltfile.hbs"),
+      "spec.master": loadTemplate("spec.master.hbs"),
+    };
+  }
+  return embeddedTemplatesCache;
+}
+
+interface GeneratorContext {
+  version: string;
+  timestamp: string;
+  tech: typeof PLATFORM_STANDARDS.tech;
+  ports: typeof PLATFORM_STANDARDS.ports;
+  health: typeof PLATFORM_STANDARDS.health;
+  naming: typeof PLATFORM_STANDARDS.naming;
+  traefik: typeof PLATFORM_STANDARDS.traefik;
+  filewatchIgnores: string[];
+  serviceTypes: typeof PLATFORM_STANDARDS.serviceTypes;
+  paths: typeof PLATFORM_STANDARDS.paths;
+  discovery: { scanIntervalSeconds: number; maxManifestsPerRoot: number; paths: string[] };
+  docker: typeof PLATFORM_STANDARDS.docker;
+  runtime: typeof PLATFORM_STANDARDS.runtime;
+  project: ProjectConfig["project"];
+  phases: ProjectConfig["phases"];
+  alwaysEnabledInfra: string[];
+  optionalInfra: ProjectConfig["optional_infra"];
+  serviceDescriptions: Record<string, string>;
+  infraDescriptions: Record<string, string>;
+}
+
+// Generic resource descriptions - no hardcoded service names
+// Users define their own service descriptions in project.json
+const RESOURCE_DESCRIPTIONS: Record<string, string> = {
+  proxy: "Traefik reverse proxy",
+  verdaccio: "Private npm registry",
+  "database-management": "PostgreSQL database",
+};
+
+const INFRA_DESCRIPTIONS: Record<string, string> = {
+  monitoring: "Signoz, SkyWalking (RAM intensive)",
+  elk: "Elasticsearch/Logstash/Kibana",
+  debezium: "CDC with Kafka/Zookeeper",
+  golden_image: "Golden image rebuild (one-time)",
+  verdaccio: "Premium local npm registry",
+};
+
+/**
+ * List of all files generated by the template engine.
+ * Used for iteration and type-safe access to generated content.
+ */
+const ALL_GENERATED_FILES = [
+  "TILT_TECH_STACK.star",
+  "TILT_RESOURCE_DEFAULTS.star",
+  "spec.master",
+  "Tiltfile",
+  ".tiltignore",
+] as const;
+
+/**
+ * Type representing valid generated file names.
+ * Derived from ALL_GENERATED_FILES const array for type safety.
+ */
+type GeneratedFileName = (typeof ALL_GENERATED_FILES)[number];
+
+export class TemplateEngine {
+  private templatesDir: string;
+
+  constructor(templatesDir?: string) {
+    const currentDir = import.meta.dirname || path.dirname(new URL(import.meta.url).pathname);
+    this.templatesDir = templatesDir || path.join(currentDir, "..", "..", "templates");
+    this.registerHelpers();
+  }
+
+  private formatStarlarkValue(val: JsonValue): string {
+    if (val === null || val === undefined) {
+      return "None";
+    }
+    if (typeof val === "string") {
+      return `"${val.replace(/"/g, '\\"')}"`;
+    }
+    if (typeof val === "boolean") {
+      return val ? "True" : "False";
+    }
+    if (typeof val === "number") {
+      return String(val);
+    }
+    if (Array.isArray(val)) {
+      const items = val.map((item) => this.formatStarlarkValue(item));
+      return `[${items.join(", ")}]`;
+    }
+    if (typeof val === "object") {
+      const entries = Object.entries(val).map(([key, v]) => {
+        return `"${key}": ${this.formatStarlarkValue(v)}`;
+      });
+      return `{${entries.join(", ")}}`;
+    }
+    return String(val);
+  }
+
+  private registerHelpers(): void {
+    Handlebars.registerHelper("starlark", (value: JsonValue): Handlebars.SafeString => {
+      return new Handlebars.SafeString(this.formatStarlarkValue(value));
+    });
+
+    Handlebars.registerHelper("starlarkArray", (value: JsonValue[]): Handlebars.SafeString => {
+      if (!Array.isArray(value)) return new Handlebars.SafeString("[]");
+      const items = value.map((item) => this.formatStarlarkValue(item));
+      return new Handlebars.SafeString(`[${items.join(", ")}]`);
+    });
+
+    Handlebars.registerHelper("json", (value: JsonValue): string => {
+      return JSON.stringify(value);
+    });
+  }
+
+  buildContext(projectConfig: ProjectConfig): GeneratorContext {
+    return {
+      version: PLATFORM_STANDARDS.version,
+      timestamp: new Date().toISOString(),
+      tech: PLATFORM_STANDARDS.tech,
+      ports: PLATFORM_STANDARDS.ports,
+      health: PLATFORM_STANDARDS.health,
+      naming: PLATFORM_STANDARDS.naming,
+      traefik: PLATFORM_STANDARDS.traefik,
+      filewatchIgnores: [...PLATFORM_STANDARDS.filewatchIgnores],
+      serviceTypes: PLATFORM_STANDARDS.serviceTypes,
+      paths: PLATFORM_STANDARDS.paths,
+      discovery: {
+        scanIntervalSeconds: PLATFORM_STANDARDS.discovery.scanIntervalSeconds,
+        maxManifestsPerRoot: PLATFORM_STANDARDS.discovery.maxManifestsPerRoot,
+        paths: projectConfig.discovery.paths,
+      },
+      docker: PLATFORM_STANDARDS.docker,
+      runtime: PLATFORM_STANDARDS.runtime,
+      project: projectConfig.project,
+      phases: dedupePhaseEnabledStacks(projectConfig.phases),
+      alwaysEnabledInfra: projectConfig.always_enabled_infra ?? [
+        "database-management",
+        "proxy",
+      ],
+      optionalInfra: projectConfig.optional_infra,
+      serviceDescriptions: RESOURCE_DESCRIPTIONS,
+      infraDescriptions: INFRA_DESCRIPTIONS,
+    };
+  }
+
+  private loadTemplate(templateName: string): HandlebarsTemplateDelegate {
+    const templatePath = path.join(this.templatesDir, `${templateName}.hbs`);
+    const templateSource = fs.existsSync(templatePath)
+      ? fs.readFileSync(templatePath, "utf-8")
+      : getEmbeddedTemplates()[templateName];
+    if (!templateSource) {
+      throw new Error(`Template not found: ${templatePath}`);
+    }
+    return Handlebars.compile(templateSource);
+  }
+
+  generateTechStack(context: GeneratorContext): string {
+    const template = this.loadTemplate("TILT_TECH_STACK.star");
+    return template(context);
+  }
+
+  generateServiceDefaults(context: GeneratorContext): string {
+    const template = this.loadTemplate("TILT_RESOURCE_DEFAULTS.star");
+    return template(context);
+  }
+
+  generateSpecMaster(context: GeneratorContext): string {
+    const template = this.loadTemplate("spec.master");
+    return template(context);
+  }
+
+  generateTiltfile(context: GeneratorContext): string {
+    const template = this.loadTemplate("Tiltfile");
+    return template(context);
+  }
+
+  generateTiltIgnore(context: GeneratorContext): string {
+    const template = this.loadTemplate(".tiltignore");
+    return template(context);
+  }
+
+  generateAll(projectConfig: ProjectConfig): Record<GeneratedFileName, string> {
+    const context = this.buildContext(projectConfig);
+
+    return {
+      "TILT_TECH_STACK.star": this.generateTechStack(context),
+      "TILT_RESOURCE_DEFAULTS.star": this.generateServiceDefaults(context),
+      "spec.master": this.generateSpecMaster(context),
+      Tiltfile: this.generateTiltfile(context),
+      ".tiltignore": this.generateTiltIgnore(context),
+    };
+  }
+}
+
+// spec.master.hbs emits one Starlark dict entry per enabledStacks[] item, so a
+// duplicate name in project.json (e.g. from the interactive wizard offering
+// the same service as both a core feature and a discovered stack) becomes a
+// duplicate dict key, which fails Starlark parsing at `tdk up`. Dedupe here
+// so a bad project.json can't break generation.
+function dedupePhaseEnabledStacks(phases: ProjectConfig["phases"]): ProjectConfig["phases"] {
+  const deduped = { ...phases };
+  for (const key of Object.keys(deduped) as (keyof ProjectConfig["phases"])[]) {
+    deduped[key] = {
+      ...deduped[key],
+      enabledStacks: Array.from(new Set(deduped[key].enabledStacks)),
+    };
+  }
+  return deduped;
+}
+
+function toComposeProjectName(projectName: string): string {
+  return projectName.replace(/-/g, "_");
+}
+
+export function generateDatabaseManagementCompose(projectConfig: ProjectConfig): string {
+  const name = toComposeProjectName(projectConfig.project.name || "tdk_project");
+  return `###############################################################################
+# SYSTEM-GENERATED - DO NOT EDIT
+# Stack feature: database-management
+# Source: .tdk/project.json phases.*.enabledStacks includes "database-management"
+###############################################################################
+
+services:
+  postgres:
+    image: postgres:16-alpine
+    container_name: ${name}_postgres
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: ${name}
+      POSTGRES_PASSWORD: \${DB_PASSWORD}
+      POSTGRES_DB: postgres
+    ports:
+      - "5432:5432"
+    volumes:
+      - ${name}_postgres_data:/var/lib/postgresql/data
+    networks:
+      - database
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${name} -d postgres"]
+      interval: 5s
+      timeout: 5s
+      retries: 20
+
+networks:
+  database:
+    name: ${name}_database
+    external: true
+
+volumes:
+  ${name}_postgres_data:
+`;
+}
+
+/**
+ * Type guard to validate if an unknown value is a valid ProjectConfig.
+ *
+ * NOTE: The `as` assertions below are INTENTIONAL and SAFE:
+ * - We've already verified `typeof value === 'object'` and `value !== null`
+ * - TypeScript doesn't automatically narrow `{}` to `Record<string, unknown>`
+ * - Each assertion is immediately followed by property type checks
+ * - This pattern is standard for deep object validation in type guards
+ */
+function hasPhaseShape(value: unknown, fieldName: "enabledStacks" | "services"): boolean {
+  if (!value || typeof value !== "object") return false;
+  const phases = value as Record<string, unknown>;
+  for (const phaseName of ["pre_alpha", "alpha", "beta", "out_of_scope"]) {
+    const phase = phases[phaseName];
+    if (!phase || typeof phase !== "object") return false;
+    if (!Array.isArray((phase as Record<string, unknown>)[fieldName])) return false;
+  }
+  return true;
+}
+
+function normalizeProjectConfig(value: unknown): ProjectConfig | null {
+  if (!value || typeof value !== "object") {
+    return null;
+  }
+
+  // Safe to assert as Record after null and object type checks
+  const config = value as Record<string, unknown>;
+
+  if (typeof config.version !== "string") {
+    return null;
+  }
+
+  if (!config.project || typeof config.project !== "object") {
+    return null;
+  }
+  const project = config.project as Record<string, unknown>;
+  if (typeof project.name !== "string" || typeof project.version !== "string") {
+    return null;
+  }
+
+  let phases: ProjectConfig["phases"] | null = null;
+  if (hasPhaseShape(config.phases, "enabledStacks")) {
+    phases = config.phases as ProjectConfig["phases"];
+  } else if (hasPhaseShape(config.stacks, "services")) {
+    const legacyStacks = config.stacks as NonNullable<ProjectConfig["stacks"]>;
+    phases = {
+      pre_alpha: {
+        name: legacyStacks.pre_alpha.name,
+        description: legacyStacks.pre_alpha.description,
+        enabledStacks: legacyStacks.pre_alpha.services,
+      },
+      alpha: {
+        name: legacyStacks.alpha.name,
+        description: legacyStacks.alpha.description,
+        enabledStacks: legacyStacks.alpha.services,
+      },
+      beta: {
+        name: legacyStacks.beta.name,
+        description: legacyStacks.beta.description,
+        enabledStacks: legacyStacks.beta.services,
+      },
+      out_of_scope: {
+        name: legacyStacks.out_of_scope.name,
+        description: legacyStacks.out_of_scope.description,
+        enabledStacks: legacyStacks.out_of_scope.services,
+      },
+    };
+  }
+
+  if (!phases) {
+    return null;
+  }
+
+  if (!config.optional_infra || typeof config.optional_infra !== "object") {
+    return null;
+  }
+  const optionalInfra = config.optional_infra as Record<string, unknown>;
+  if (
+    typeof optionalInfra.monitoring !== "boolean" ||
+    typeof optionalInfra.elk !== "boolean" ||
+    typeof optionalInfra.debezium !== "boolean" ||
+    typeof optionalInfra.golden_image !== "boolean" ||
+    typeof optionalInfra.verdaccio !== "boolean"
+  ) {
+    return null;
+  }
+
+  if (!config.discovery || typeof config.discovery !== "object") {
+    return null;
+  }
+  const discovery = config.discovery as Record<string, unknown>;
+  if (!Array.isArray(discovery.paths)) {
+    return null;
+  }
+
+  return {
+    version: config.version,
+    project: config.project as ProjectConfig["project"],
+    phases,
+    always_enabled_infra: config.always_enabled_infra as string[] | undefined,
+    optional_infra: config.optional_infra as ProjectConfig["optional_infra"],
+    discovery: config.discovery as ProjectConfig["discovery"],
+    overrides: config.overrides as ProjectConfig["overrides"],
+  };
+}
+
+export function readProjectConfig(projectRoot: string): ProjectConfig {
+  const projectJsonPath = path.join(projectRoot, ".tdk", "project.json");
+
+  if (!fs.existsSync(projectJsonPath)) {
+    throw new Error(`Project config not found: ${projectJsonPath}. Run 'tdk project init' first.`);
+  }
+
+  const jsonContent = fs.readFileSync(projectJsonPath, "utf-8");
+  const parsed: unknown = JSON.parse(jsonContent);
+
+  const projectConfig = normalizeProjectConfig(parsed);
+  if (!projectConfig) {
+    throw new Error(
+      "Invalid project.json: missing or invalid required fields. " +
+        "Expected: version (string), project (object with name/version), " +
+        "phases (object with pre_alpha/alpha/beta/out_of_scope enabledStacks), " +
+        "optional_infra (object with boolean flags), " +
+        "discovery (object with paths array)",
+    );
+  }
+
+  return projectConfig;
+}
+
+// Sablier ("sablier: {enable: true}" on a resource's own service.json) is
+// Premium, but unlike Verdaccio below, this is NOT the enforcement - it's a
+// friendly heads-up. The real gate is that engine/.../sablier_container_cycle.star
+// in this (public) repo is a free-tier stub that always returns disabled; the
+// working implementation only exists in the private tdk-cli-extensions/premium/
+// bundle, applied by vendorTdkExtension()'s applyPremiumOverlay() below when a
+// license grants it. Forking this repo and deleting a license check (as you
+// could with Verdaccio/DDD) gets you nothing here, because there's no check to
+// delete - the actual code simply isn't present without the overlay. This just
+// tells a confused free-tier user why their `sablier` block silently does
+// nothing, instead of leaving them to guess.
+async function warnIfSablierUnlicensed(projectRoot: string): Promise<void> {
+  const resources = discoverResourcesFromRoot(projectRoot).filter(
+    (r) => r.config?.sablier?.enable === true,
+  );
+  if (resources.length === 0) return;
+
+  const granted = await hasSablierLicense(projectRoot);
+  if (granted) return;
+
+  console.warn(
+    `⚠️  Sablier (on-demand scaling) is a Premium feature - no valid license key found. ` +
+      `${resources.length} resource${resources.length === 1 ? " has" : "s have"} a \`sablier\` block, ` +
+      "but it will have no effect without a license. Set TDK_LICENSE_KEY to a key that grants it, " +
+      "or remove the `sablier` block from the affected service.json file(s) to silence this warning.",
+  );
+}
+
+function ensureRootWorkspaceManifest(projectRoot: string, projectConfig: ProjectConfig): boolean {
+  const packageJsonPath = path.join(projectRoot, "package.json");
+  if (fs.existsSync(packageJsonPath)) {
+    return false;
+  }
+
+  const manifest = {
+    name: projectConfig.project.name || path.basename(projectRoot),
+    version: projectConfig.project.version || "1.0.0",
+    private: true,
+    type: "module",
+    workspaces: projectConfig.discovery.paths,
+  };
+
+  writeTextFile(packageJsonPath, `${JSON.stringify(manifest, null, 2)}\n`);
+  return true;
+}
+
+export async function generateMasterConfigs(projectRoot: string): Promise<void> {
+  const projectConfig = readProjectConfig(projectRoot);
+
+  await warnIfSablierUnlicensed(projectRoot);
+
+  if (ensureRootWorkspaceManifest(projectRoot, projectConfig)) {
+    console.log("✓ Generated: package.json (workspace root)");
+  }
+
+  // Verdaccio is Premium, but unlike the old posture here, this is NOT the
+  // enforcement - it's a friendly heads-up. The real gate is that
+  // engine/topologies/platform/registries/verdaccio_loader.star in this
+  // (public) repo is a free-tier stub that always skips; the working loader
+  // only exists in the private tdk-cli-extensions/premium/ bundle, applied
+  // by vendorTdkExtension()'s applyPremiumOverlay() below when a license
+  // grants it. Forking this repo and deleting a license check gets you
+  // nothing, because there's no check left to delete - the actual code
+  // simply isn't present without the overlay. This just tells a confused
+  // free-tier user why enabling Verdaccio silently did nothing, instead of
+  // leaving them to guess.
+  const verdaccioInPhase = Object.values(projectConfig.phases).some((phase) =>
+    phase.enabledStacks.includes("verdaccio"),
+  );
+  if (projectConfig.optional_infra.verdaccio || verdaccioInPhase) {
+    const granted = await hasVerdaccioLicense(projectRoot);
+    if (!granted) {
+      console.warn(
+        "⚠️  Verdaccio is a Premium feature - no valid license key found. It's enabled in " +
+          "this project's config, but will have no effect without a license. Set TDK_LICENSE_KEY " +
+          "to a key that grants it, or run `tdk config disable-infra verdaccio` to silence this warning.",
+      );
+    }
+  }
+
+  const outputDir = path.join(projectRoot, ".tdk", ".tdk-out");
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+  }
+
+  const engine = new TemplateEngine();
+  const files = engine.generateAll(projectConfig);
+
+  for (const filename of ALL_GENERATED_FILES) {
+    const content = files[filename];
+    const filePath = path.join(outputDir, filename);
+    writeTextFile(filePath, content);
+    console.log(`✓ Generated: .tdk/.tdk-out/${filename}`);
+  }
+
+  if (isStackFeatureEnabledInStacks(projectConfig.phases, "database-management")) {
+    const composeDir = path.join(projectRoot, "services", "platform", "database-management");
+    fs.mkdirSync(composeDir, { recursive: true });
+    const composePath = path.join(
+      composeDir,
+      "docker-compose.yml",
+    );
+    writeTextFile(composePath, generateDatabaseManagementCompose(projectConfig));
+    console.log("✓ Generated: services/platform/database-management/docker-compose.yml");
+  }
+
+  // Copy .tiltignore to project root so Tilt uses it
+  const tiltignoreSource = path.join(outputDir, ".tiltignore");
+  const tiltignoreTarget = path.join(projectRoot, ".tiltignore");
+  if (fs.existsSync(tiltignoreSource)) {
+    fs.copyFileSync(tiltignoreSource, tiltignoreTarget);
+    console.log(`✓ Copied: .tiltignore → project root`);
+  }
+
+  const copiedAssets = ensureProjectRuntimeAssets(projectRoot);
+  for (const asset of copiedAssets) {
+    console.log(`✓ Copied: ${asset} → project root`);
+  }
+
+  await vendorTdkExtension(projectRoot);
+
+  console.log("");
+  console.log("💡 To start Tilt: tdk up");
+}
+
+// The generated Tiltfile loads the TDK Tilt extension (engine, discovery,
+// specs, ext starlark modules). The extension repo may stay private, so we
+// vendor a working copy into .tdk/.tdk-out/tdk-cli-ext/ at generation time.
+// This makes `tdk up` work offline and on any machine - no hardcoded paths,
+// no dependency on a private GitHub repo.
+const TDK_EXTENSION_DIRS = ["engine", "discovery", "specs", "ext"] as string[];
+const PROJECT_RUNTIME_ASSET_DIRS = [
+  ["shared-platform-engineering", "docker-templates"],
+] as const;
+const REQUIRED_DOCKER_TEMPLATE_FILES = [
+  "install-deps.sh",
+  "bun-hoisted-symlink-fix.sh",
+  "prisma-bun-client-link-fix.sh",
+  "prisma-normalize-client.sh",
+] as const;
+
+// Walk up from this module's own location looking for a directory that has
+// both Tiltfile and engine/ next to it - true when cli/ and engine/ ship
+// together in the same repo (the public tdk-cli-core layout, where a plain
+// `git clone` + `bun run` needs zero extra config to find the engine).
+function findSelfContainedEngineRoot(): string | null {
+  let dir = import.meta.dirname || process.cwd();
+  for (let i = 0; i < 6; i++) {
+    if (fs.existsSync(path.join(dir, "Tiltfile")) && fs.existsSync(path.join(dir, "engine"))) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+function findCliAssetRoot(): string | null {
+  let dir = import.meta.dirname || process.cwd();
+  for (let i = 0; i < 8; i++) {
+    if (fs.existsSync(path.join(dir, "shared-platform-engineering", "docker-templates"))) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  const exeDir = path.dirname(process.execPath);
+  const candidates = [
+    path.join(exeDir, "tdk-cli"),
+    path.join(process.cwd(), "node_modules", "@tdk-landscape", "tdk-cli-core"),
+  ];
+
+  return candidates.find((candidate) =>
+    fs.existsSync(path.join(candidate, "shared-platform-engineering", "docker-templates")),
+  ) ?? null;
+}
+
+export function ensureProjectRuntimeAssets(projectRoot: string): string[] {
+  const sourceRoot = findCliAssetRoot();
+  const copied: string[] = [];
+
+  if (!sourceRoot) {
+    console.warn(
+      "⚠️  TDK runtime assets not found - generated Dockerfiles may fail. " +
+        "Reinstall or upgrade TDK, then re-run `tdk project`.",
+    );
+    return copied;
+  }
+
+  for (const parts of PROJECT_RUNTIME_ASSET_DIRS) {
+    const source = path.join(sourceRoot, ...parts);
+    const target = path.join(projectRoot, ...parts);
+    if (!fs.existsSync(source)) {
+      continue;
+    }
+
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.cpSync(source, target, { recursive: true });
+    copied.push(parts.join("/"));
+  }
+
+  for (const file of REQUIRED_DOCKER_TEMPLATE_FILES) {
+    const filePath = path.join(projectRoot, "shared-platform-engineering", "docker-templates", file);
+    if (!fs.existsSync(filePath)) {
+      console.warn(`⚠️  Missing runtime asset after copy: ${filePath}`);
+    }
+  }
+
+  return copied;
+}
+
+async function vendorTdkExtension(projectRoot: string): Promise<void> {
+  const outputDir = path.join(projectRoot, ".tdk", ".tdk-out");
+  const vendoredDir = path.join(outputDir, "tdk-cli-ext");
+
+  // Source resolution order:
+  //   1. $TDK_EXTENSION_SOURCE (explicit override)
+  //   2. Self-contained repo (engine/ ships next to cli/ - public tdk-cli-core)
+  //   3. Executable-adjacent checkout (bundled installs)
+  //   4. Relative ../tdk-cli sibling (monorepo maintainer layout)
+  let sources: string[] = [];
+  if (process.env.TDK_EXTENSION_SOURCE) {
+    sources.push(process.env.TDK_EXTENSION_SOURCE);
+  }
+  const selfContainedRoot = findSelfContainedEngineRoot();
+  if (selfContainedRoot) {
+    sources.push(selfContainedRoot);
+  }
+  // process.execPath is the compiled binary's own path when running as a
+  // standalone executable (what we actually need here). In dev mode it's
+  // the bun CLI's own path instead (e.g. ~/.bun/bin/bun) - harmless, that
+  // candidate just won't match anything and falls through to the next
+  // one. Note: process.executablePath is not a real property on Node or
+  // Bun's process object - it was always undefined, silently falling
+  // back to cwd() instead of the binary's real location.
+  const exeDir = path.dirname(process.execPath);
+  sources.push(path.join(exeDir, "tdk-cli"));
+  sources.push(path.join(projectRoot, "..", "tdk-cli"));
+
+  let sourceRoot = "";
+  for (const candidate of sources) {
+    if (
+      candidate &&
+      fs.existsSync(path.join(candidate, "Tiltfile")) &&
+      fs.existsSync(path.join(candidate, "engine"))
+    ) {
+      sourceRoot = candidate;
+      break;
+    }
+  }
+
+  if (!sourceRoot) {
+    console.warn(
+      "⚠️  TDK extension not found - set TDK_EXTENSION_SOURCE to its checkout path " +
+        "and re-run `tdk project` (or `tdk config regenerate`) to vendor it before `tdk up`.",
+    );
+    return;
+  }
+
+  if (!fs.existsSync(vendoredDir)) {
+    fs.mkdirSync(vendoredDir, { recursive: true });
+  }
+  fs.copyFileSync(path.join(sourceRoot, "Tiltfile"), path.join(vendoredDir, "Tiltfile"));
+  for (const dir of TDK_EXTENSION_DIRS) {
+    fs.cpSync(path.join(sourceRoot, dir), path.join(vendoredDir, dir), {
+      recursive: true,
+    });
+  }
+  console.log(`✓ Vendored TDK extension → .tdk/.tdk-out/tdk-cli-ext/`);
+
+  // Best-effort: if TDK_LICENSE_KEY is set and grants any paid resource,
+  // overlay the premium bundle over the stub files just vendored above.
+  // No-ops silently (beyond a warning) if there's no key, the fetch
+  // fails, or nothing's granted - the free engine already works fine on
+  // its own.
+  try {
+    const { applyPremiumOverlay } = await import("./extension-fetch.js");
+    await applyPremiumOverlay(projectRoot, vendoredDir);
+  } catch (err) {
+    console.warn(`⚠️  Premium overlay skipped: ${(err as Error).message}`);
+  }
+}
+
+export function verifyMasterConfigs(projectRoot: string): { valid: boolean; errors: string[] } {
+  const errors: string[] = [];
+
+  const projectConfig = readProjectConfig(projectRoot);
+  const engine = new TemplateEngine();
+  const expectedFiles = engine.generateAll(projectConfig);
+
+  const outputDir = path.join(projectRoot, ".tdk", ".tdk-out");
+
+  for (const filename of ALL_GENERATED_FILES) {
+    const expectedContent = expectedFiles[filename];
+    const filePath = path.join(outputDir, filename);
+
+    if (!fs.existsSync(filePath)) {
+      errors.push(`Missing file: .tdk/.tdk-out/${filename}`);
+      continue;
+    }
+
+    const actualContent = fs.readFileSync(filePath, "utf-8");
+    if (actualContent !== expectedContent) {
+      errors.push(`Out of sync: .tdk/.tdk-out/${filename} (run 'tdk config regenerate')`);
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}