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

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

@@ -8,7 +8,7 @@ import { findProjectRoot } from "./paths.js";
 import { isApiServiceType } from "./resource-kind.js";
 import { getProjectName } from "./service-urls.js";
 import { discoverResources, discoverResourcesFromRoot } from "./services.js";
-import { isTiltResourcePending } from "./tilt-resource-state.js";
+import { effectiveRuntimeStatus, isTiltResourcePending, UNHEALTHY_CONTAINER_MESSAGE, } from "./tilt-resource-state.js";
 import { findOnPath } from "./which.js";
 const EXEC_TIMEOUT_MS = 10_000;
 const REGISTRY_PROBE_TIMEOUT_MS = 3_000;
@@ -104,8 +104,11 @@ export function parseTiltResourceFailures(jsonText, deferredNames = new Set()) {
     for (const item of items) {
         const name = item.metadata?.name ?? "unknown";
         const updateStatus = item.status?.updateStatus ?? "";
-        const runtimeStatus = item.status?.runtimeStatus ?? "";
-        const error = (item.status?.buildHistory?.[0]?.error ?? "").trim();
+        const runtimeStatus = effectiveRuntimeStatus(item.status);
+        const unhealthy = runtimeStatus === "error" && item.status?.runtimeStatus === "ok";
+        // A failed build's own error is the cause to show; the health message only fills in when there is none.
+        const buildError = (item.status?.buildHistory?.[0]?.error ?? "").trim();
+        const error = buildError || (unhealthy ? UNHEALTHY_CONTAINER_MESSAGE : "");
         if (updateStatus === "error" || runtimeStatus === "error") {
             failures.push({
                 name,

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,129 @@ const KNOWN_SERVICE_FIELDS = new Set([
     "traefik",
     "type",
 ]);
+/**
+ * String fields written into the generated Docker Compose, Traefik and NATS config as they are. A newline or YAML syntax in one of
+ * them adds keys to the generated service (GHSA-phgf-pww4-7jxc), so each must match its pattern. Empty values are treated as unset.
+ * `tilt up` reads service.json without this CLI, so engine/topologies/tilt/manifest/parser.star enforces the same rules.
+ */
+const GENERATED_STRING_FIELDS = [
+    { path: ["healthCheckPath"], pattern: /^\/[a-z0-9/-]*$/, expected: "a path such as /health" },
+    {
+        path: ["traefik", "host"],
+        pattern: /^[A-Za-z0-9.-]+$/,
+        expected: "a hostname such as shop.backend.myproject.local",
+    },
+    {
+        path: ["traefik", "pathPrefix"],
+        pattern: /^\/[a-z0-9/-]*$/,
+        expected: "a path such as /api/v1/shop-management",
+    },
+    {
+        path: ["traefik", "healthCheck"],
+        pattern: /^\/[a-z0-9/-]*$/,
+        expected: "a path such as /health",
+    },
+    {
+        path: ["nats", "queueGroup"],
+        pattern: /^[A-Za-z0-9_.-]+$/,
+        expected: "letters, digits, '_', '.' or '-'",
+    },
+    { path: ["databaseName"], pattern: /^[A-Za-z0-9_-]+$/, expected: "letters, digits, '_' or '-'" },
+    { path: ["stack"], pattern: /^[A-Za-z0-9_-]+$/, expected: "letters, digits, '_' or '-'" },
+    {
+        path: ["image"],
+        pattern: /^[A-Za-z0-9._/:@-]+$/,
+        expected: "an image reference such as ghcr.io/acme/app:1.0",
+    },
+];
+/**
+ * Errors for generated-output fields whose values could change the generated YAML. The value itself is not echoed, because it may
+ * contain the newline that makes it dangerous.
+ */
+export function validateGeneratedStringFields(manifest, displayPath) {
+    const errors = [];
+    const reportedFields = new Set();
+    for (const { path, pattern, expected } of GENERATED_STRING_FIELDS) {
+        let value = manifest;
+        for (const key of path) {
+            value =
+                value && typeof value === "object" && !Array.isArray(value)
+                    ? value[key]
+                    : undefined;
+        }
+        if (value === undefined || value === null || value === "")
+            continue;
+        const field = `${displayPath}.${path.join(".")}`;
+        if (typeof value !== "string" || !pattern.test(value))
+            reportedFields.add(field);
+        if (typeof value !== "string") {
+            errors.push(`${field}: expected a string`);
+        }
+        else if (!pattern.test(value)) {
+            errors.push(`${field}: must be ${expected} (no spaces, line breaks or YAML syntax)`);
+        }
+    }
+    for (const [field, message] of lineBreakErrors(manifest, displayPath)) {
+        if (!reportedFields.has(field))
+            errors.push(`${field}: ${message}`);
+    }
+    return errors;
+}
+/** Line breaks (including the Unicode ones YAML 1.1 honours) and other control characters. */
+function hasLineBreakOrControl(text) {
+    for (let index = 0; index < text.length; index++) {
+        const code = text.charCodeAt(index);
+        if (code < 0x20 || code === 0x7f || code === 0x85 || code === 0x2028 || code === 0x2029) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Many more service.json values than GENERATED_STRING_FIELDS reach the generated YAML (port, appName, dockerfile, buildContext,
+ * basePath, envVars, ...). A key can only be added through a line break, so no string key or value may contain one. `smoke` is
+ * skipped: the CLI sends it over HTTP and it is never written into generated config.
+ */
+function lineBreakErrors(manifest, displayPath) {
+    const errors = [];
+    const pending = Object.entries(manifest)
+        .filter(([key]) => key !== "smoke")
+        .map(([key, value]) => [value, `${displayPath}.${key}`]);
+    for (const key of Object.keys(manifest)) {
+        if (hasLineBreakOrControl(key))
+            errors.push([displayPath, "a key contains a line break"]);
+    }
+    while (pending.length > 0) {
+        const [value, field] = pending.pop();
+        if (typeof value === "string") {
+            if (hasLineBreakOrControl(value)) {
+                errors.push([field, "must not contain line breaks or control characters"]);
+            }
+        }
+        else if (Array.isArray(value)) {
+            for (const [index, item] of value.entries())
+                pending.push([item, `${field}[${index}]`]);
+        }
+        else if (value && typeof value === "object") {
+            for (const [key, item] of Object.entries(value)) {
+                if (hasLineBreakOrControl(key)) {
+                    errors.push([field, "a key contains a line break"]);
+                }
+                else {
+                    pending.push([item, `${field}.${key}`]);
+                }
+            }
+        }
+    }
+    return errors.sort(([a], [b]) => a.localeCompare(b));
+}
+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 +191,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
@@ -74,6 +201,7 @@ export function validateServiceManifest(value, displayPath) {
     if (liveReload !== undefined && typeof liveReload !== "boolean") {
         errors.push(`${displayPath}.dev.liveReload: expected true or false`);
     }
+    errors.push(...validateGeneratedStringFields(manifest, displayPath));
     if ("smoke" in manifest) {
         for (const message of validateSmoke(manifest.smoke))
             errors.push(`${displayPath}.${message}`);
@@ -91,6 +219,23 @@ export function validateServiceManifest(value, displayPath) {
     }
     return { errors, warnings, manifest };
 }
+/**
+ * Generated-output errors for one service.json. A file that cannot be read or parsed returns none here, because
+ * validateServiceManifestFile reports that case.
+ */
+export function generatedFieldErrorsForFile(filePath, displayPath) {
+    if (!existsSync(filePath))
+        return [];
+    try {
+        const parsed = JSON.parse(readFileSync(filePath, "utf-8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return [];
+        return validateGeneratedStringFields(parsed, displayPath);
+    }
+    catch {
+        return [];
+    }
+}
 export function validateServiceManifestFile(filePath, displayPath) {
     if (!existsSync(filePath)) {
         return { errors: [`${displayPath}: file is missing`], warnings: [] };

package/cli/dist/utils/service-runtime-state.js

@@ -1,5 +1,5 @@
 import { buildStartupReport, transitiveDependencies } from "./startup-report.js";
-import { isTiltResourcePending } from "./tilt-resource-state.js";
+import { effectiveRuntimeStatus, isTiltResourcePending } from "./tilt-resource-state.js";
 import { onlyEnabledResources } from "./up-readiness.js";
 /**
  * The one answer to "is this service ready?" for `tdk status` and `tdk ui`, from Tilt's resources and the `dependsOn`
@@ -32,7 +32,7 @@ export function deriveServiceStates(jsonText, dependsOn, deferred = new Set()) {
             direct.set(name, { status: "pending" });
         }
         else if (deferred.has(name) &&
-            isTiltResourcePending(item.status?.updateStatus ?? "", item.status?.runtimeStatus ?? "")) {
+            isTiltResourcePending(item.status?.updateStatus ?? "", effectiveRuntimeStatus(item.status))) {
             direct.set(name, { status: "unknown", reason: "starts on its first request" });
         }
         else {

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, validateGeneratedStringFields, 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,13 @@ 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 unsafeFields = validateGeneratedStringFields(parsed, serviceJsonPath);
+    if (unsafeFields.length > 0)
+        throw new InvalidServiceJsonError(unsafeFields.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/startup-report.js

@@ -1,6 +1,6 @@
 import { parseTiltResourceFailures, summarizeTiltBuildError } from "./doctor-runtime.js";
 import { portConflictFix } from "./port-conflict-fix.js";
-import { isTiltResourcePending } from "./tilt-resource-state.js";
+import { effectiveRuntimeStatus, isTiltResourcePending } from "./tilt-resource-state.js";
 import { onlyEnabledResources } from "./up-readiness.js";
 export function transitiveDependencies(name, dependsOn) {
     const seen = new Set();
@@ -16,7 +16,7 @@ export function transitiveDependencies(name, dependsOn) {
     return seen;
 }
 function isPending(item) {
-    return isTiltResourcePending(item.status?.updateStatus ?? "", item.status?.runtimeStatus ?? "");
+    return isTiltResourcePending(item.status?.updateStatus ?? "", effectiveRuntimeStatus(item.status));
 }
 export function buildStartupReport(jsonText, dependsOn, deferred = new Set()) {
     const enabledJson = onlyEnabledResources(jsonText);
@@ -33,15 +33,14 @@ export function buildStartupReport(jsonText, dependsOn, deferred = new Set()) {
     const starting = [];
     for (const item of items) {
         const name = item.metadata?.name ?? "unknown";
-        if (name === "(Tiltfile)" || failedNames.has(name) || deferred.has(name) || !isPending(item)) {
+        if (name === "(Tiltfile)" || failedNames.has(name) || deferred.has(name))
             continue;
-        }
         const because = [...transitiveDependencies(name, dependsOn)]
             .filter((dep) => failedNames.has(dep))
             .sort();
         if (because.length > 0)
             blocked.push({ name, because });
-        else
+        else if (isPending(item))
             starting.push(name);
     }
     return { failed, blocked, starting };
@@ -66,7 +65,12 @@ export function formatStartupReport(report, timedOut) {
         lines.push(`${timedOut ? "Timed out waiting for" : "Still starting:"} ${report.starting.join(", ")}`);
     }
     if (lines.length > 0) {
-        lines.push("The environment is not ready. Tilt is still running; inspect it or run: tdk down");
+        const causes = [...new Set(report.blocked.flatMap((entry) => entry.because))].sort();
+        const count = report.blocked.length;
+        const summary = count > 0
+            ? `: ${causes.join(", ")} failed, so ${count} dependent ${count === 1 ? "service is" : "services are"} not ready`
+            : "";
+        lines.push(`The environment is not ready${summary}. Tilt is still running; inspect it or run: tdk down`);
     }
     return lines;
 }

package/cli/dist/utils/tilt-resource-state.js

@@ -9,4 +9,23 @@ export function isTiltResourcePending(updateStatus, runtimeStatus) {
         runtimeStatus === "pending" ||
         runtimeStatus === "none");
 }
+/** What a Tilt failure says when the container runs but Docker reports its health check as failing. */
+export const UNHEALTHY_CONTAINER_MESSAGE = "container is running, but its health check is failing";
+/**
+ * Tilt's runtime status, corrected for Docker health. Tilt reports a running compose container as `ok` even while its
+ * health check is still `starting` or has turned `unhealthy` (Tilt 0.37), so a Postgres that never accepts connections
+ * would read as ready. Health `starting` is pending and `unhealthy` is an error; a container without a health check
+ * keeps Tilt's status.
+ */
+export function effectiveRuntimeStatus(status) {
+    const runtimeStatus = status?.runtimeStatus ?? "";
+    if (runtimeStatus !== "ok")
+        return runtimeStatus;
+    const health = status?.composeResourceInfo?.healthStatus;
+    if (health === "unhealthy")
+        return "error";
+    if (health === "starting")
+        return "pending";
+    return runtimeStatus;
+}
 //# sourceMappingURL=tilt-resource-state.js.map

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");
 }