@tdk-landscape/tdk-cli-core 1.3.124 → 1.3.125

package/cli/dist/utils/doctor-starlark.js

@@ -0,0 +1,131 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, normalize } from "node:path";
+import { formatCount } from "./formatting.js";
+import { findProjectRoot } from "./paths.js";
+export function findPrivateStarlarkLoadExports(content) {
+    const privateExports = new Set();
+    const loadCallPattern = /^load\s*\(([\s\S]*?)\)/gm;
+    for (const loadMatch of content.matchAll(loadCallPattern)) {
+        const args = loadMatch[1] ?? "";
+        const quotedValuePattern = /["']([^"']+)["']/g;
+        const quotedValues = Array.from(args.matchAll(quotedValuePattern), (match) => match[1]);
+        // First quoted arg is the module path. Later quoted args are exported names
+        // or alias targets, and Starlark refuses to export names beginning with "_".
+        for (const value of quotedValues.slice(1)) {
+            if (value.startsWith("_")) {
+                privateExports.add(value);
+            }
+        }
+    }
+    return Array.from(privateExports).sort();
+}
+export function resolveStarlarkLoadTarget(file, modulePath, projectRoot) {
+    if (modulePath === "ext://tdk-cli") {
+        return join(projectRoot, ".tdk", ".tdk-out", "tdk-cli-ext", "Tiltfile");
+    }
+    if (modulePath.startsWith(".") || (!modulePath.includes("://") && !modulePath.startsWith("@"))) {
+        return normalize(join(dirname(file), modulePath));
+    }
+    return null;
+}
+export function findMissingRelativeStarlarkLoads(file, content, projectRoot) {
+    const missing = [];
+    const loadCallPattern = /^load\s*\(([\s\S]*?)\)/gm;
+    for (const loadMatch of content.matchAll(loadCallPattern)) {
+        const args = loadMatch[1] ?? "";
+        const moduleMatch = args.match(/["']([^"']+)["']/);
+        const modulePath = moduleMatch?.[1];
+        if (!modulePath) {
+            continue;
+        }
+        const resolved = resolveStarlarkLoadTarget(file, modulePath, projectRoot);
+        if (!resolved) {
+            continue;
+        }
+        if (!existsSync(resolved)) {
+            missing.push(`${file}: ${modulePath} -> ${resolved}`);
+        }
+    }
+    return missing;
+}
+export function findRelativeStarlarkLoadTargets(file, content, projectRoot) {
+    const targets = [];
+    const loadCallPattern = /^load\s*\(([\s\S]*?)\)/gm;
+    for (const loadMatch of content.matchAll(loadCallPattern)) {
+        const args = loadMatch[1] ?? "";
+        const moduleMatch = args.match(/["']([^"']+)["']/);
+        const modulePath = moduleMatch?.[1];
+        if (modulePath) {
+            const target = resolveStarlarkLoadTarget(file, modulePath, projectRoot);
+            if (target) {
+                targets.push(target);
+            }
+        }
+    }
+    return targets;
+}
+export function collectReachableStarlarkFiles(entryFile, projectRoot) {
+    const visited = new Set();
+    const pending = [entryFile];
+    while (pending.length > 0) {
+        const file = pending.pop();
+        if (!file || visited.has(file) || !existsSync(file)) {
+            continue;
+        }
+        visited.add(file);
+        const content = readFileSync(file, "utf-8");
+        for (const target of findRelativeStarlarkLoadTargets(file, content, projectRoot)) {
+            if (!visited.has(target)) {
+                pending.push(target);
+            }
+        }
+    }
+    return Array.from(visited).sort();
+}
+export function checkStarlarkLoadExports() {
+    const projectRoot = findProjectRoot() ?? process.cwd();
+    const entryFile = join(projectRoot, ".tdk", ".tdk-out", "Tiltfile");
+    if (!existsSync(entryFile)) {
+        return {
+            name: "Starlark Load Exports",
+            didPass: true,
+            isSkipped: true,
+            message: "No generated Tiltfile to check",
+        };
+    }
+    const privateExportProblems = [];
+    const missingLoadProblems = [];
+    const reachableFiles = collectReachableStarlarkFiles(entryFile, projectRoot);
+    for (const file of reachableFiles) {
+        const content = readFileSync(file, "utf-8");
+        const privateExports = findPrivateStarlarkLoadExports(content);
+        if (privateExports.length > 0) {
+            privateExportProblems.push(`${file}: ${privateExports.join(", ")}`);
+        }
+        for (const missingLoad of findMissingRelativeStarlarkLoads(file, content, projectRoot)) {
+            missingLoadProblems.push(missingLoad);
+        }
+    }
+    if (privateExportProblems.length === 0 && missingLoadProblems.length === 0) {
+        const fileCount = formatCount(reachableFiles.length, "reachable Starlark file");
+        return {
+            name: "Starlark Load Exports",
+            didPass: true,
+            message: `${fileCount} ${reachableFiles.length === 1 ? "has" : "have"} valid load exports and paths`,
+        };
+    }
+    const sections = [];
+    if (privateExportProblems.length > 0) {
+        sections.push(`Private exported symbols:\n    ${privateExportProblems.join("\n    ")}`);
+    }
+    if (missingLoadProblems.length > 0) {
+        sections.push(`Missing relative load targets:\n    ${missingLoadProblems.join("\n    ")}`);
+    }
+    return {
+        name: "Starlark Load Exports",
+        didPass: false,
+        message: `Starlark load() issues will stop Tilt before services start:\n    ${sections.join("\n\n    ")}`,
+        fix: "Regenerate with a current TDK (`tdk config regenerate`). If the issue remains, rename loaded symbols without leading underscores and update stale load paths.",
+    };
+}
+//# sourceMappingURL=doctor-starlark.js.map

package/cli/dist/utils/env-validator.js

@@ -1,6 +1,7 @@
 import { randomBytes } from "node:crypto";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { writeTextFileAtomic } from "./atomic-write.js";
 const REQUIRED_ENV_VARS = [
     {
         name: "VERDACCIO_URL_DOCKER",
@@ -180,10 +181,26 @@ export function validateEnvFile(projectRoot) {
     return result;
 }
 /**
- * Appends the keys a newer CLI expects to an existing .env, without touching or rotating anything already there (an existing
- * DB_PASSWORD must survive, or the database volume stops accepting it). Creates the file when it is missing.
+ * Replaces the value in one parsed assignment while preserving its prefix, inline comment, and line ending.
+ * The caller only uses this for assignments whose parsed value is empty or whitespace.
+ */
+function replaceEmptyEnvValue(line, name, value) {
+    const parsed = parseEnv(line);
+    if (!parsed.has(name))
+        return line;
+    const equalsIndex = line.indexOf("=");
+    if (equalsIndex < 0)
+        return line;
+    const rawValue = line.slice(equalsIndex + 1);
+    const commentIndex = rawValue.search(/\s#/);
+    const comment = commentIndex < 0 ? "" : rawValue.slice(commentIndex);
+    return line.slice(0, equalsIndex + 1) + value + comment;
+}
+/**
+ * Appends missing keys a newer CLI expects and fills empty generated keys in place.
+ * Non-empty values are not changed. Creates the file when it is missing.
  *
- * @returns the names that were added, empty when the file was already complete
+ * @returns the names that were added or filled in, empty when the file was already complete
  */
 export function completeEnvFile(projectRoot) {
     const envPath = join(projectRoot, ".env");
@@ -193,24 +210,49 @@ export function completeEnvFile(projectRoot) {
     }
     const existing = readFileSync(envPath, "utf-8");
     const env = parseEnv(existing);
-    const toAdd = REQUIRED_ENV_VARS.filter((v) => v.complete && !env.has(v.name));
-    if (toAdd.length === 0)
+    const toComplete = REQUIRED_ENV_VARS.filter((v) => {
+        if (!v.complete)
+            return false;
+        if (!env.has(v.name))
+            return true;
+        return !(env.get(v.name) ?? "").trim();
+    });
+    if (toComplete.length === 0)
         return [];
-    // Anything generated from the password must use the project's existing one.
-    const password = env.get("DB_PASSWORD") || generateDbPassword();
-    const lines = [
-        "",
-        "# Added by TDK: keys this version expects. Existing values above were not changed.",
-        "",
-    ];
-    for (const envVar of toAdd) {
-        lines.push(...describe(envVar));
-        lines.push(`${envVar.name}=${generatedValue(envVar.name, password)}`);
-        lines.push("");
+    const toAdd = toComplete.filter((v) => !env.has(v.name));
+    const toRepair = toComplete.filter((v) => env.has(v.name));
+    // Anything generated from the password must use the project's existing non-empty value.
+    const existingPassword = env.get("DB_PASSWORD");
+    const password = existingPassword?.trim() ? existingPassword : generateDbPassword();
+    const lines = existing.split(/(\r\n|\n|\r)/);
+    for (const envVar of toRepair) {
+        let lineIndex = -1;
+        for (let index = 0; index < lines.length; index += 2) {
+            if (parseEnv(lines[index]).has(envVar.name))
+                lineIndex = index;
+        }
+        if (lineIndex < 0) {
+            throw new Error(`Could not locate empty .env assignment for ${envVar.name}`);
+        }
+        lines[lineIndex] = replaceEmptyEnvValue(lines[lineIndex], envVar.name, generatedValue(envVar.name, password));
+    }
+    let updated = lines.join("");
+    if (toAdd.length > 0) {
+        const addedLines = [
+            "",
+            "# Added by TDK: keys this version expects. Existing values above were not changed.",
+            "",
+        ];
+        for (const envVar of toAdd) {
+            addedLines.push(...describe(envVar));
+            addedLines.push(`${envVar.name}=${generatedValue(envVar.name, password)}`);
+            addedLines.push("");
+        }
+        const separator = updated.endsWith("\n") || updated.endsWith("\r") ? "" : "\n";
+        updated += separator + addedLines.join("\n");
     }
-    const separator = existing.endsWith("\n") ? "" : "\n";
-    writeFileSync(envPath, `${existing}${separator}${lines.join("\n")}`);
-    return toAdd.map((v) => v.name);
+    writeTextFileAtomic(envPath, updated);
+    return toComplete.map((v) => v.name);
 }
 export function ensureEnvFile(projectRoot) {
     const envPath = join(projectRoot, ".env");

package/cli/dist/utils/service-manifest.js

@@ -14,6 +14,7 @@ const DEPRECATED_FIELDS = {
 const KNOWN_SERVICE_FIELDS = new Set([
     "$schema",
     "apiBasePath",
+    "apiPath",
     "appName",
     "appType",
     "backendName",
@@ -49,6 +50,13 @@ const KNOWN_SERVICE_FIELDS = new Set([
     "traefik",
     "type",
 ]);
+const SERVICE_ROUTE_PATH_FIELDS = ["apiPath", "basePath"];
+export function getInvalidServiceRoutePathFields(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return [];
+    const manifest = value;
+    return SERVICE_ROUTE_PATH_FIELDS.filter((field) => field in manifest && typeof manifest[field] !== "string");
+}
 export function validateServiceManifest(value, displayPath) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
         return { errors: [`${displayPath}: expected a JSON object`], warnings: [] };
@@ -67,6 +75,9 @@ export function validateServiceManifest(value, displayPath) {
     if ("schemaVersion" in manifest && manifest.schemaVersion !== SERVICE_MANIFEST_SCHEMA_VERSION) {
         errors.push(`${displayPath}.schemaVersion: unsupported version ${String(manifest.schemaVersion)} (supported: ${SERVICE_MANIFEST_SCHEMA_VERSION})`);
     }
+    for (const field of getInvalidServiceRoutePathFields(manifest)) {
+        errors.push(`${displayPath}.${field}: expected a string`);
+    }
     const dev = manifest.dev;
     const liveReload = dev && typeof dev === "object" && !Array.isArray(dev)
         ? dev.liveReload

package/cli/dist/utils/services.js

@@ -5,7 +5,7 @@ import { AUTOGENERATED_FILE_PATTERNS, SKIP_DIRECTORIES } from "./constants.js";
 import { errorFactories } from "./errors.js";
 import { formatCount } from "./formatting.js";
 import { findProjectRoot } from "./paths.js";
-import { validateServiceManifest } from "./service-manifest.js";
+import { getInvalidServiceRoutePathFields, validateServiceManifest } from "./service-manifest.js";
 import { deriveStackStatus } from "./stack-status.js";
 import { includes } from "./validation.js";
 const RESOURCE_JSON_FILENAME = "service.json";
@@ -79,6 +79,10 @@ function parseResource(serviceJsonPath) {
     if (!isValidResourceConfig(parsed)) {
         throw new InvalidServiceJsonError("missing required fields (appName, runtime or appType)");
     }
+    const invalidRoutePathFields = getInvalidServiceRoutePathFields(parsed);
+    if (invalidRoutePathFields.length > 0) {
+        throw new InvalidServiceJsonError(invalidRoutePathFields.map((field) => `${field}: expected a string`).join("; "));
+    }
     const parsedConfig = parsed;
     for (const warning of validateServiceManifest(parsed, serviceJsonPath).warnings) {
         // The warning names the file and field and says what is wrong (unknown, deprecated, ignored), so do not prefix it.

package/cli/dist/utils/tilt.js

@@ -1,5 +1,6 @@
 import { spawn } from "node:child_process";
 import { join } from "node:path";
+import { errorFactories } from "./errors.js";
 import { findProjectRoot } from "./paths.js";
 import { findOnPath } from "./which.js";
 export function runTilt(command, args = [], options = {}) {
@@ -49,7 +50,7 @@ export async function isTiltAvailable() {
 export function getTiltfilePath() {
     const projectRoot = findProjectRoot();
     if (!projectRoot) {
-        throw new Error("Not in a TDK project (no .tdk/project.json found)");
+        throw errorFactories.notInProject();
     }
     return join(projectRoot, ".tdk", ".tdk-out", "Tiltfile");
 }

package/cli/dist/utils/ui-keymap.js

@@ -0,0 +1,118 @@
+export const TABS = [
+    { id: "overview", label: "OVERVIEW", shortcut: "1" },
+    { id: "resources", label: "RESOURCES", shortcut: "2" },
+    { id: "events", label: "EVENTS", shortcut: "3" },
+    { id: "files", label: "FILES", shortcut: "4" },
+    { id: "config", label: "CONFIG", shortcut: "5" },
+];
+const tabRange = `${TABS[0].shortcut}-${TABS[TABS.length - 1].shortcut}`;
+const uiKeymap = [
+    {
+        id: "list-navigation",
+        keys: ["ArrowUp", "ArrowDown", "j", "k"],
+        label: "Navigate list items",
+        group: "Navigation",
+        display: { ascii: "UP/DOWN or k/j", unicode: "↑/↓ or k/j" },
+    },
+    {
+        id: "first-last",
+        keys: ["g", "G", "Home", "End"],
+        label: "First/last item",
+        group: "Navigation",
+        display: { ascii: "g/G or Home/End", unicode: "g/G or Home/End" },
+    },
+    {
+        id: "page-list",
+        keys: ["PageUp", "PageDown"],
+        label: "Move one page",
+        group: "Navigation",
+        display: { ascii: "PgUp/PgDn", unicode: "PgUp/PgDn" },
+    },
+    {
+        id: "select",
+        keys: ["Enter", "Space"],
+        label: "Select item / Open detail",
+        group: "Navigation",
+        display: { ascii: "Enter or Space", unicode: "Enter or Space" },
+    },
+    {
+        id: "cycle-tabs",
+        keys: ["Tab", "Shift+Tab"],
+        label: "Next / previous tab",
+        group: "Navigation",
+        display: { ascii: "Tab/Shift+Tab", unicode: "Tab/Shift+Tab" },
+    },
+    {
+        id: "direct-tabs",
+        keys: TABS.map((tab) => tab.shortcut),
+        label: "Direct tab access",
+        group: "Navigation",
+        display: { ascii: tabRange, unicode: tabRange },
+    },
+    {
+        id: "toggle-mouse",
+        keys: ["m"],
+        label: "Toggle mouse support",
+        group: "Actions",
+    },
+    {
+        id: "toggle-tooltips",
+        keys: ["t"],
+        label: "Toggle tooltips",
+        group: "Actions",
+    },
+    {
+        id: "toggle-enabled",
+        keys: ["e"],
+        label: "Toggle enabled/disabled services",
+        group: "Actions",
+    },
+    {
+        id: "refresh",
+        keys: ["r"],
+        label: "Refresh data",
+        group: "Actions",
+    },
+    {
+        id: "search",
+        keys: ["/"],
+        label: "Search/filter",
+        group: "Actions",
+    },
+    {
+        id: "help",
+        keys: ["?"],
+        label: "Show this help",
+        group: "Actions",
+    },
+    {
+        id: "quit",
+        keys: ["q"],
+        label: "Quit",
+        group: "Actions",
+    },
+    {
+        id: "back",
+        keys: ["Esc"],
+        label: "Back",
+        group: "Actions",
+    },
+];
+export const UI_KEYMAP = uiKeymap;
+function getUiKeymapEntry(id) {
+    const entry = UI_KEYMAP.find((shortcut) => shortcut.id === id);
+    if (!entry) {
+        throw new Error(`Unknown TDK UI shortcut: ${id}`);
+    }
+    return entry;
+}
+export function formatUiKeyNames(id, ascii = false) {
+    const entry = getUiKeymapEntry(id);
+    const display = ascii ? entry.display?.ascii : entry.display?.unicode;
+    return display ?? entry.keys.join("/");
+}
+export function formatUiKeyHint(id, label, ascii = false) {
+    const entry = getUiKeymapEntry(id);
+    return `[${formatUiKeyNames(id, ascii)}] ${label ?? entry.label}`;
+}
+//# sourceMappingURL=ui-keymap.js.map

package/cli/package.json

@@ -1,7 +1,7 @@
 {
   "name": "tdk-cli-internal",
   "private": true,
-  "version": "1.3.124",
+  "version": "1.3.125",
   "description": "TDK CLI — start services on your laptop.",
   "keywords": [
     "tdk",

package/engine/topologies/tilt/common/utils.star

@@ -318,11 +318,11 @@ def write_file_if_changed(file_path, content):
     existing = str(existing_blob).rstrip()
 
     if existing == expected:
-        print("DEBUG WRITE: Skipping {} (no changes)".format(file_path))
+        debug_log("WRITE: Skipping {} (no changes)".format(file_path))
     else:
-        print("DEBUG WRITE: Writing {} bytes to {}".format(len(expected), file_path))
+        debug_log("WRITE: Writing {} bytes to {}".format(len(expected), file_path))
         _write_generated_file(file_path, expected)
-        print("DEBUG WRITE: Completed {}".format(file_path))
+        debug_log("WRITE: Completed {}".format(file_path))
 
     # Keep a generated-content snapshot beside the service outputs. `tdk config verify`
     # compares these snapshots with the files and the source manifest, detecting both

package/engine/topologies/tilt/common/utils_debug.star

@@ -2,7 +2,7 @@
 # 🛠️ TILT SDK - DEBUG UTILITIES
 # =============================================================================
 
-DEBUG_MODE = os.environ.get('TILT_DEBUG', 'false').lower() in ['true', '1', 'yes']
+DEBUG_MODE = (os.environ.get('TDK_DEBUG') or os.environ.get('TILT_DEBUG', 'false')).lower() in ['true', '1', 'yes']
 
 
 def debug_log(message, data=None):

package/engine/topologies/tilt/generators/typescript/frontend_tsconfig.star

@@ -3,6 +3,7 @@ OUTPUT = struct(AUTOGENERATED_FOLDER = ".autogenerated")
 # === END INLINED CONSTANTS ===
 
 
+load("../../common/utils_debug.star", "debug_log")
 load("../../../../topologies/tilt/common/utils.star", "Utils")
 load("../../../../topologies/tilt/manifest/constants.star", "GENERATED_CONFIG_FILENAMES")
 
@@ -126,15 +127,12 @@ def generate_frontend_tsconfig(resource_path, write_fn, internal_deps=None, is_d
     }
     if is_docker:
         output_path = resource_path + '/' + OUTPUT.AUTOGENERATED_FOLDER + '/' + GENERATED_CONFIG_FILENAMES['tsconfig_docker']
-        if is_verbose:
-            print("📝 DEBUG: Writing Docker tsconfig to: {}".format(output_path))
+        debug_log("📝 Writing Docker tsconfig to: {}".format(output_path))
         write_fn(output_path, Utils.encode_json(content))
-        if is_verbose:
-            print("📝 DEBUG: Docker tsconfig write complete")
+        debug_log("📝 Docker tsconfig write complete")
     else:
         output_path = resource_path + '/' + OUTPUT.AUTOGENERATED_FOLDER + '/' + GENERATED_CONFIG_FILENAMES['tsconfig_local']
-        if is_verbose:
-            print("📝 DEBUG: Writing Local tsconfig to: {}".format(output_path))
+        debug_log("📝 Writing Local tsconfig to: {}".format(output_path))
         write_fn(output_path, Utils.encode_json(content))
 
 DEBUG = {}

package/engine/topologies/tilt/resources/infra-loader.star

@@ -18,6 +18,7 @@
 #   Infra.load_all(should_enable_fn)
 # =============================================================================
 
+load("../common/utils_debug.star", "debug_log")
 load("../../platform/docker/constants.star", "PlatformDockerConstants")
 load("../../platform/docker/compose/traefik_standalone.star", "generate_standalone_traefik_compose")
 load("../../platform/docker/networking/sablier_container_cycle.star", "sablier_middleware_suffix")
@@ -130,14 +131,14 @@ def _register_platform_postgres(should_enable, root_prefix="", env_file=None, wr
     """
     postgres_compose = _ensure_database_management_compose(root_prefix, write_fn)
     if _file_exists(postgres_compose):
-        print("DEBUG INFRA: Loading postgres compose from {}".format(postgres_compose))
+        debug_log("INFRA: Loading postgres compose from {}".format(postgres_compose))
         _docker_compose(postgres_compose, env_file)
         dc_resource('postgres', labels=['infra.tools'], resource_deps=['init-networks'], auto_init=True)
         return
     message = "Shared platform Postgres compose was not materialized at {}".format(postgres_compose)
     if required:
         fail(message + " (write_fn present: {}). Refusing to register a postgres Tilt resource with no compose.".format(write_fn != None))
-    print("DEBUG INFRA: Skipping postgres (compose file not found): {}".format(message))
+    debug_log("INFRA: Skipping postgres (compose file not found): {}".format(message))
 
 
 def force_start_platform_postgres(should_enable, root_prefix="", env_file=None, write_fn=None):
@@ -161,7 +162,7 @@ def force_start_platform_postgres(should_enable, root_prefix="", env_file=None,
 def _load_database_management(should_enable, root_prefix="", env_file=None, write_fn=None):
     """Load database and messaging infrastructure."""
     if not should_enable('database-management'):
-        print("DEBUG INFRA: database-management not enabled")
+        debug_log("INFRA: database-management not enabled")
         return
 
     print("🗃️  Loading database management services...")
@@ -172,7 +173,7 @@ def _load_database_management(should_enable, root_prefix="", env_file=None, writ
     # Load messaging if compose file exists
     messaging_compose = root_prefix + 'services/platform/messaging/docker-compose.yml'
     if _file_exists(messaging_compose):
-        print("DEBUG INFRA: Loading messaging compose from {}".format(messaging_compose))
+        debug_log("INFRA: Loading messaging compose from {}".format(messaging_compose))
         _docker_compose(messaging_compose, env_file)
         # Register only services present in the project compose file. Minimal
         # NATS-only examples should not need to add an unrelated Redis broker.
@@ -181,7 +182,7 @@ def _load_database_management(should_enable, root_prefix="", env_file=None, writ
         if _compose_has_service(messaging_compose, 'nats'):
             dc_resource('nats', labels=['infra.messaging'], auto_init=True)
     else:
-        print("DEBUG INFRA: Skipping messaging (compose file not found)")
+        debug_log("INFRA: Skipping messaging (compose file not found)")
 
     # Only create kafka resources if debezium is enabled AND messaging exists
     cdc_enabled = should_enable('debezium')
@@ -211,7 +212,7 @@ def _load_infisical(should_enable, root_prefix="", env_file=None):
 
     compose_file = root_prefix + 'docker-compose.infisical.yml'
     if not _file_exists(compose_file):
-        print("DEBUG INFRA: Skipping Infisical (compose file not found)")
+        debug_log("INFRA: Skipping Infisical (compose file not found)")
         return
 
     print("🔐 Loading Infisical...")
@@ -254,7 +255,7 @@ def _load_standalone_traefik(root_prefix, env_file, write_fn):
 def _load_proxy(should_enable, root_prefix="", env_file=None, write_fn=None):
     """Load Traefik reverse proxy with proper health check sequencing."""
     if not should_enable('proxy'):
-        print("DEBUG INFRA: proxy not enabled")
+        debug_log("INFRA: proxy not enabled")
         return
 
     compose_files = [
@@ -266,7 +267,7 @@ def _load_proxy(should_enable, root_prefix="", env_file=None, write_fn=None):
     ]
     missing = [path for path in compose_files if not _file_exists(path)]
     if missing:
-        print("DEBUG INFRA: Platform proxy compose missing ({}), using standalone Traefik".format(missing[0]))
+        debug_log("INFRA: Platform proxy compose missing ({}), using standalone Traefik".format(missing[0]))
         _load_standalone_traefik(root_prefix, env_file, write_fn)
         return
 
@@ -422,11 +423,11 @@ def load_all_infrastructure(should_enable, fix_docker_networks_fn=None, docker_p
     """
     # Initialize networks first
     if fix_docker_networks_fn:
-        print("DEBUG INFRA: Initializing networks...")
+        debug_log("INFRA: Initializing networks...")
         _init_networks(fix_docker_networks_fn)
-        print("DEBUG INFRA: Networks initialized")
+        debug_log("INFRA: Networks initialized")
     else:
-        print("DEBUG INFRA: SKIPPING network initialization (no fix_docker_networks_fn)")
+        debug_log("INFRA: SKIPPING network initialization (no fix_docker_networks_fn)")
 
     # These stacks both define an `elasticsearch` resource (and host port 9200).
     # Running both at once causes compose/resource collisions and unstable startup.

package/engine/topologies/tilt/resources/orchestrator/apply.star

@@ -4,6 +4,7 @@
 # Purpose: thin coordinator for service apply lifecycle.
 # =============================================================================
 
+load("../../common/utils_debug.star", "debug_log")
 load('../databases.star', 'Database')
 load('./apply_runtime_flags.star', 'RuntimeFlags')
 load('./apply_resource_validation.star', 'ResourceValidation')
@@ -38,7 +39,7 @@ def apply_app_service(resource_config, ctx):
         for nested in resource_config.get('resources', []):
             nested_name = nested.get('name', '')
             if nested_name and should_enable(nested_name):
-                print("DEBUG APPLY: stack '{}' not individually enabled, but nested service '{}' is - proceeding".format(resource_name, nested_name))
+                debug_log("APPLY: stack '{}' not individually enabled, but nested service '{}' is - proceeding".format(resource_name, nested_name))
                 service_enabled = True
                 break