@tdk-landscape/tdk-cli-core 1.3.120 → 1.3.121

package/README.md

@@ -110,16 +110,18 @@ curl -fsSL https://tdk-landscape.github.io/install.sh | sh
 
 ## History
 
-TDK is older than this repository and its npm package suggest. Development started on 21 April 2026 in
-[tdk-landscape/tdk](https://github.com/tdk-landscape/tdk), now archived and kept as read-only history; its first commit is
-[`1714637`](https://github.com/tdk-landscape/tdk/commit/1714637637196ed54cbfa18534230a782c05ab36) ("Initial commit: TDK specs,
-generators, CLI, and standards"). This repository, `tdk-cli-core`, was created on 19 September 2026 and is where development
-continues; the `@tdk-landscape/tdk-cli-core` package on npm was first published on 21 September 2026. So the code lineage is about
-five months older than the repository and package dates that you will see on GitHub and npm.
+TDK development began on 21 April 2026. The archived, read-only [tdk-landscape/tdk](https://github.com/tdk-landscape/tdk)
+repository records its [first commit](https://github.com/tdk-landscape/tdk/commit/1714637637196ed54cbfa18534230a782c05ab36)
+("Initial commit: TDK specs, generators, CLI, and standards") from that day. A separate `tdk-cli` history spanning 21 April to
+18 September 2026 was [imported into this repository](https://github.com/tdk-landscape/tdk-cli-core/pull/670) as 306 filtered
+commits. Those commits are now ancestors of `main`; the import did not change the source tree.
+
+This `tdk-cli-core` repository was created on 19 September 2026, and the `@tdk-landscape/tdk-cli-core` npm package was first
+published on 21 September 2026. Those dates describe the current repository and package, not the start of TDK development.
 
 ## Requirements and support
 
-For the local runtime, install Docker (Desktop, OrbStack, or Colima; Engine 25+, Compose 2.20+) and [Tilt](https://docs.tilt.dev/install.html). Bun 1.2+ is used by the default generated services. TDK selects host ports from bounded fallback ranges for HTTP, HTTPS, and Postgres; set `TDK_HTTP_PORT`, `TDK_HTTPS_PORT`, or `TDK_POSTGRES_PORT` to override them. TDK supports macOS, Linux, and Windows through WSL2 Ubuntu; native Windows supports CLI inspection only. Run `tdk doctor` to check local readiness. See [WSL2 setup](docs/wsl2.md).
+For the local runtime, install Docker (Desktop, OrbStack, or Colima; Engine 25+, Compose 2.20+) and [Tilt](https://docs.tilt.dev/install.html). Bun 1.2+ is used by the default generated services. TDK selects host ports from bounded fallback ranges for HTTP, HTTPS, and Postgres; set `TDK_HTTP_PORT`, `TDK_HTTPS_PORT`, or `TDK_POSTGRES_PORT` to override them. TDK supports macOS, Linux, and Windows through WSL2 Ubuntu; native Windows supports CLI inspection only. Run `tdk doctor` to check local readiness (supports `--no-ping` to skip service health checks and `--ping-timeout <ms>`). See [WSL2 setup](docs/wsl2.md).
 
 On native Windows, `tdk --version`, `tdk doctor`, and `tdk up --dry-run` are inspect-only commands. `tdk up` exits 2 with “Landscape startup needs Ubuntu on WSL2. Native Windows is inspect-only.”
 

package/cli/dist/commands/config.js

@@ -244,8 +244,12 @@ export const configCommand = new Command("config")
             }
             for (const { diff } of result.diffs)
                 console.log(chalk.gray(`\n${diff}`));
-            if (!result.valid) {
-                console.log(chalk.gray("\nRun `tdk config regenerate` to fix."));
+            const schemaErrors = result.errors.filter((error) => error.includes(".schemaVersion:"));
+            if (schemaErrors.length > 0) {
+                console.log(chalk.gray("\nRun `tdk config migrate` to fix schemaVersion."));
+            }
+            if (result.diffs.length > 0) {
+                console.log(chalk.gray("\nRun `tdk config regenerate` to fix generated files."));
             }
             process.exit(1);
         }

package/cli/dist/commands/logs.js

@@ -1,6 +1,6 @@
 import { Command } from "commander";
 import { STANDARD_PORTS } from "../utils/constants.js";
-import { runCommand, showErrorAndExit } from "../utils/errors.js";
+import { errorFactories, runCommand, showErrorAndExit, TdkError } from "../utils/errors.js";
 import { createMachineEnvelope } from "../utils/machine-output.js";
 import { isTiltAvailable, runTilt } from "../utils/tilt.js";
 import { DEFAULT_LOG_TAIL, isTiltConnectionFailure, isValidPort, isValidSince, isValidTail, MAX_LOG_TAIL, parseTiltLogLines, } from "../utils/tilt-logs.js";
@@ -28,12 +28,16 @@ export const logsCommand = new Command("logs")
     .option("--port <n>", "Tilt UI port (default: TILT_PORT or 10350)")
     .option("--json", "Output one JSON object and exit", false)
     .action(async (options) => {
-    const fail = (code, message, exitCode = 1) => {
+    const fail = (code, message, exitCode = 1, suggestions = []) => {
         if (options.json) {
-            console.log(JSON.stringify(createMachineEnvelope(null, [{ code, message }])));
+            console.log(JSON.stringify(createMachineEnvelope(null, [
+                { code, message, ...(suggestions.length > 0 ? { suggestions } : {}) },
+            ])));
             console.error(message);
             process.exit(exitCode);
         }
+        if (suggestions.length > 0)
+            return new TdkError(message, suggestions, exitCode).exit();
         return showErrorAndExit(message, exitCode);
     };
     if (!isValidTail(options.tail))
@@ -54,7 +58,9 @@ export const logsCommand = new Command("logs")
             const known = await tiltResourceNames(portText);
             const unknown = services.filter((name) => known && !known.includes(name));
             if (unknown.length > 0) {
-                fail("UNKNOWN_SERVICE", `Unknown service ${unknown.join(", ")}. Valid names: ${(known ?? []).join(", ")}`, 2);
+                const error = errorFactories.unknownServices(unknown, known ?? []);
+                const suggestions = error.suggestions;
+                fail("UNKNOWN_SERVICE", error.message, error.exitCode, suggestions);
             }
         }
         const args = ["--port", portText, "--tail", String(tail)];

package/cli/dist/commands/networks.js

@@ -172,7 +172,7 @@ export const networksCommand = new Command("networks")
         }
         const discovery = createDiscoveryContext();
         if (options.stack && !stackExists(options.stack, discovery.resources)) {
-            const error = errorFactories.stackNotFound(options.stack);
+            const error = errorFactories.stackNotFound(options.stack, discovery.stackNames);
             if (options.json || options.jsonLegacy)
                 throw error;
             error.exit();

package/cli/dist/commands/resources.js

@@ -33,7 +33,7 @@ export const resourcesCommand = new Command("resources")
         }
         const discovery = createDiscoveryContext();
         if (options.stack && !stackExists(options.stack, discovery.resources)) {
-            const error = errorFactories.stackNotFound(options.stack);
+            const error = errorFactories.stackNotFound(options.stack, discovery.stackNames);
             if (options.json)
                 writeMachineError(error);
             error.exit();

package/cli/dist/commands/status.js

@@ -7,6 +7,7 @@ import { formatCount, showDetail, showStep } from "../utils/formatting.js";
 import { getHostPortPlan } from "../utils/host-port-config.js";
 import { createMachineEnvelope, writeMachineError } from "../utils/machine-output.js";
 import { findProjectRoot } from "../utils/paths.js";
+import { deriveServiceStates } from "../utils/service-runtime-state.js";
 import { buildServicePorts, buildStackPorts } from "../utils/status-ports.js";
 import { getTiltfilePath, isTiltAvailable, runTilt } from "../utils/tilt.js";
 import { evaluateTiltReadiness, tiltGetUiResources } from "../utils/up-readiness.js";
@@ -58,16 +59,26 @@ export const statusCommand = new Command("status")
         // A single look at the running Tilt, so a caller that started `tdk up` detached can poll for readiness. Null when no
         // Tilt answers or its output cannot be read.
         let readiness = null;
-        if (options.json && tiltAvailable) {
+        // The same look at Tilt feeds readiness and each service's state, so `tdk status` and `tdk ui` cannot disagree.
+        let serviceStates = null;
+        if (tiltAvailable) {
             const port = Number.parseInt(process.env.TILT_PORT ?? "", 10);
             const text = await tiltGetUiResources(Number.isInteger(port) ? port : 10350);
             if (text) {
+                const deferred = getDeferredResourceNames();
                 try {
-                    readiness = evaluateTiltReadiness(text, getDeferredResourceNames()).result;
+                    if (options.json)
+                        readiness = evaluateTiltReadiness(text, deferred).result;
                 }
                 catch {
                     readiness = null;
                 }
+                try {
+                    serviceStates = deriveServiceStates(text, Object.fromEntries(discovery.resources.map((r) => [r.name, r.config?.dependsOn ?? []])), deferred);
+                }
+                catch {
+                    serviceStates = null;
+                }
             }
         }
         if (options.json) {
@@ -94,6 +105,13 @@ export const statusCommand = new Command("status")
                     type: resource.type ?? "unknown",
                     port: resource.port ?? null,
                     ...buildServicePorts(resource, portPlan?.ingressHttp),
+                    status: serviceStates?.[resource.name]?.status ?? "unknown",
+                    ...(serviceStates?.[resource.name]?.reason
+                        ? { statusReason: serviceStates[resource.name]?.reason }
+                        : {}),
+                    ...(serviceStates?.[resource.name]?.blockedBy
+                        ? { blockedBy: serviceStates[resource.name]?.blockedBy }
+                        : {}),
                 })),
                 ports: buildStackPorts(portPlan, process.env.TILT_PORT ? Number.parseInt(process.env.TILT_PORT, 10) : undefined),
                 stacks: discovery.stacks.map((stack) => ({
@@ -132,6 +150,21 @@ export const statusCommand = new Command("status")
                 }
             }
         }
+        if (serviceStates && Object.keys(serviceStates).length > 0) {
+            console.log();
+            console.log(chalk.bold("Services:"));
+            for (const resource of discovery.resources) {
+                const state = serviceStates[resource.name];
+                if (!state)
+                    continue;
+                const mark = state.status === "ready"
+                    ? chalk.green("✓")
+                    : state.status === "error"
+                        ? chalk.red("✗")
+                        : chalk.yellow("…");
+                showDetail(`${mark} ${resource.name}  ${state.status}${state.reason ? ` (${state.reason})` : ""}`);
+            }
+        }
         if (options.tilt && tiltAvailable) {
             console.log();
             showStep("Tilt Resources:");

package/cli/dist/commands/ui.js

@@ -2,16 +2,18 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
 import { Command } from "commander";
 import { Box, render, Text, useApp, useInput, useStdin, useStdout } from "ink";
 import { useCallback, useEffect, useMemo, useState } from "react";
-import { DetailPanel, FileTree, ResourceSelectInput, ResourceTable, TabBar, TUIHeader, } from "../components/index.js";
+import { DetailPanel, FileTree, ResourceSelectInput, ResourceTable, ServiceIssues, TabBar, TUIHeader, } from "../components/index.js";
 import { TABS } from "../components/TabBar.js";
 import { createTUITheme, TUIThemeContext, useTUITheme } from "../components/ui-theme.js";
 import { errorFactories, requireProjectRoot } from "../utils/errors.js";
 import { findProjectRoot, getPackageVersion } from "../utils/paths.js";
 import { describeSearch } from "../utils/search-status.js";
 import { clearMetadataCache, discoverResources, discoverStacks, getResourceMetadata, getStackMetadata, } from "../utils/services.js";
+import { singleFlight } from "../utils/single-flight.js";
 import { createStatusMessageController } from "../utils/status-message.js";
 import { getListRowFromMouseY, getTerminalRuleWidth } from "../utils/terminal-layout.js";
 import { isTiltAvailable } from "../utils/tilt.js";
+import { applyServiceStates, fetchServiceStates, } from "../utils/ui-service-state.js";
 // biome-ignore lint/correctness/noUnusedFunctionParameters: reserved callback prop kept in the component API
 const HelpPanel = ({ onClose }) => {
     const theme = useTUITheme();
@@ -75,6 +77,25 @@ export const TUIApp = ({ animated = true }) => {
     useEffect(() => () => statusMessage.dispose(), [statusMessage]);
     const projectRoot = findProjectRoot() || "unknown";
     const [{ stacks, services }, setDiscovered] = useState({ stacks: [], services: [] });
+    // What the running Tilt says about each service: the same answer `tdk status` gives. Empty while no Tilt answers.
+    const [serviceStates, setServiceStates] = useState({});
+    useEffect(() => {
+        let cancelled = false;
+        const tiltPort = Number.parseInt(process.env.TILT_PORT ?? "", 10);
+        // A Tilt call can outlast the 5 s interval; never start a poll while the last one is still running.
+        const run = singleFlight((next) => {
+            if (cancelled)
+                return;
+            setServiceStates((previous) => JSON.stringify(previous) === JSON.stringify(next) ? previous : next);
+        });
+        const poll = () => run(() => fetchServiceStates(services, Number.isInteger(tiltPort) ? tiltPort : 10350));
+        void poll();
+        const timer = setInterval(() => void poll(), 5000);
+        return () => {
+            cancelled = true;
+            clearInterval(timer);
+        };
+    }, [services]);
     // Re-read service.json files from disk. An empty project is not an error:
     // it renders EmptyState. Only a failed discovery shows ErrorScreen.
     const refresh = useCallback(() => {
@@ -103,9 +124,9 @@ export const TUIApp = ({ animated = true }) => {
             return null;
         return {
             stack,
-            metadata: getStackMetadata(stack),
+            metadata: applyServiceStates(getStackMetadata(stack), serviceStates),
         };
-    }, [selectedStack, stacks]);
+    }, [selectedStack, stacks, serviceStates]);
     const selectedServiceData = useMemo(() => {
         if (!selectedService)
             return null;
@@ -476,7 +497,7 @@ export const TUIApp = ({ animated = true }) => {
     if (services.length === 0) {
         return (_jsxs(Box, { flexDirection: "column", height: stdout.rows || 24, children: [header, _jsx(EmptyState, { message: message })] }));
     }
-    return (_jsxs(Box, { flexDirection: "column", height: stdout.rows || 24, children: [header, isSearching && (_jsxs(Box, { paddingX: 1, height: 1, children: [_jsxs(Text, { color: theme.warning, children: ["Search: ", searchQuery, "_"] }), searchStatus && (_jsx(Text, { color: theme.muted, dimColor: theme.dimMuted, children: `   ${searchStatus.summary}` }))] })), searchStatus?.emptyMessage && (_jsx(Box, { paddingX: 1, height: 1, children: _jsx(Text, { color: theme.muted, children: searchStatus.emptyMessage }) })), !isSearching && message && (_jsx(Box, { paddingX: 1, height: 1, children: _jsxs(Text, { color: theme.accent, children: [theme.bannerStart, " ", message, " ", theme.bannerEnd] }) })), !isSearching && !message && showTooltips && !showHelp && (_jsx(Box, { paddingX: 1, height: 1, children: _jsx(Text, { color: theme.muted, dimColor: theme.dimMuted, children: createHelpHint(activeTab, selectedStack, selectedService, showEnabledOnly, theme.ascii) }) })), showHelp && (_jsx(Box, { paddingX: 1, flexGrow: 1, children: _jsx(HelpPanel, { onClose: () => setShowHelp(false) }) })), !showHelp && (_jsxs(_Fragment, { children: [_jsx(Box, { marginTop: 1, children: _jsx(TabBar, { activeTab: activeTab, onTabChange: setActiveTab, terminalWidth: terminalWidth }) }), _jsxs(Box, { flexDirection: "row", paddingX: 1, flexGrow: 1, children: [_jsxs(Box, { flexDirection: "column", flexGrow: 1, width: mainPanelWidth, children: [activeTab === "overview" && (_jsxs(_Fragment, { children: [_jsx(Box, { marginBottom: 1, children: _jsx(Text, { bold: true, color: theme.muted, children: theme.ascii ? "[ Stacks ]" : "┌─ Stacks ─" }) }), _jsx(Box, { marginTop: 1, flexGrow: 1, children: _jsx(ResourceSelectInput, { items: items, onSelect: handleSelect, highlightedIndex: highlightedIndex, isActive: !isSearching, maxVisibleItems: pageSize, width: mainPanelWidth, onLayout: handleListLayout }) })] })), activeTab === "resources" && (_jsxs(_Fragment, { children: [_jsx(Box, { marginBottom: 1, children: _jsx(Text, { bold: true, color: theme.muted, children: theme.ascii ? "[ Resources ]" : "┌─ Resources ─" }) }), selectedStackData ? (_jsxs(_Fragment, { children: [_jsxs(Text, { color: theme.muted, children: ["Stack: ", selectedStackData.stack.name] }), _jsx(Box, { marginTop: 1, children: _jsx(ResourceTable, { resources: selectedStackData.metadata.resources, maxWidth: terminalWidth - (showSidebar ? 50 : 10) }) })] })) : (_jsxs(_Fragment, { children: [_jsx(Text, { color: theme.muted, children: "Select a stack to view resources" }), _jsx(Box, { marginTop: 1, children: _jsx(ResourceSelectInput, { items: items, onSelect: handleSelect, highlightedIndex: highlightedIndex, isActive: !isSearching, maxVisibleItems: pageSize, width: mainPanelWidth, onLayout: handleListLayout }) })] }))] })), activeTab === "files" && (_jsxs(_Fragment, { children: [_jsx(Box, { marginBottom: 1, children: _jsx(Text, { bold: true, color: theme.muted, children: theme.ascii ? "[ Autogenerated Files ]" : "┌─ Autogenerated Files ─" }) }), selectedServiceData ? (_jsxs(_Fragment, { children: [_jsxs(Text, { color: theme.muted, children: ["Service: ", selectedServiceData.service.name] }), _jsx(Box, { marginTop: 1, children: _jsx(FileTree, { nodes: fileTreeNodes, selectedPath: selectedFile || undefined }) })] })) : (_jsxs(_Fragment, { children: [_jsx(Text, { color: theme.muted, children: "Select a service to view files" }), _jsx(Box, { marginTop: 1, children: _jsx(ResourceSelectInput, { items: items, onSelect: handleSelect, highlightedIndex: highlightedIndex, isActive: !isSearching, maxVisibleItems: pageSize, width: mainPanelWidth, onLayout: handleListLayout }) })] }))] })), activeTab === "config" && (_jsxs(_Fragment, { children: [_jsx(Box, { marginBottom: 1, children: _jsx(Text, { bold: true, color: theme.muted, children: theme.ascii ? "[ Configuration ]" : "┌─ Configuration ─" }) }), selectedServiceData ? (_jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { color: theme.accent, children: selectedServiceData.service.configPath }), _jsx(Box, { marginTop: 1, ...(theme.ascii
+    return (_jsxs(Box, { flexDirection: "column", height: stdout.rows || 24, children: [header, isSearching && (_jsxs(Box, { paddingX: 1, height: 1, children: [_jsxs(Text, { color: theme.warning, children: ["Search: ", searchQuery, "_"] }), searchStatus && (_jsx(Text, { color: theme.muted, dimColor: theme.dimMuted, children: `   ${searchStatus.summary}` }))] })), searchStatus?.emptyMessage && (_jsx(Box, { paddingX: 1, height: 1, children: _jsx(Text, { color: theme.muted, children: searchStatus.emptyMessage }) })), !isSearching && message && (_jsx(Box, { paddingX: 1, height: 1, children: _jsxs(Text, { color: theme.accent, children: [theme.bannerStart, " ", message, " ", theme.bannerEnd] }) })), !isSearching && !message && showTooltips && !showHelp && (_jsx(Box, { paddingX: 1, height: 1, children: _jsx(Text, { color: theme.muted, dimColor: theme.dimMuted, children: createHelpHint(activeTab, selectedStack, selectedService, showEnabledOnly, theme.ascii) }) })), showHelp && (_jsx(Box, { paddingX: 1, flexGrow: 1, children: _jsx(HelpPanel, { onClose: () => setShowHelp(false) }) })), !showHelp && (_jsxs(_Fragment, { children: [_jsx(Box, { marginTop: 1, children: _jsx(TabBar, { activeTab: activeTab, onTabChange: setActiveTab, terminalWidth: terminalWidth }) }), _jsxs(Box, { flexDirection: "row", paddingX: 1, flexGrow: 1, children: [_jsxs(Box, { flexDirection: "column", flexGrow: 1, width: mainPanelWidth, children: [activeTab === "overview" && (_jsxs(_Fragment, { children: [_jsx(Box, { marginBottom: 1, children: _jsx(Text, { bold: true, color: theme.muted, children: theme.ascii ? "[ Stacks ]" : "┌─ Stacks ─" }) }), _jsx(Box, { marginTop: 1, flexGrow: 1, children: _jsx(ResourceSelectInput, { items: items, onSelect: handleSelect, highlightedIndex: highlightedIndex, isActive: !isSearching, maxVisibleItems: pageSize, width: mainPanelWidth, onLayout: handleListLayout }) })] })), activeTab === "resources" && (_jsxs(_Fragment, { children: [_jsx(Box, { marginBottom: 1, children: _jsx(Text, { bold: true, color: theme.muted, children: theme.ascii ? "[ Resources ]" : "┌─ Resources ─" }) }), selectedStackData ? (_jsxs(_Fragment, { children: [_jsxs(Text, { color: theme.muted, children: ["Stack: ", selectedStackData.stack.name] }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(ResourceTable, { resources: selectedStackData.metadata.resources, maxWidth: terminalWidth - (showSidebar ? 50 : 10) }), _jsx(ServiceIssues, { resources: selectedStackData.metadata.resources })] })] })) : (_jsxs(_Fragment, { children: [_jsx(Text, { color: theme.muted, children: "Select a stack to view resources" }), _jsx(Box, { marginTop: 1, children: _jsx(ResourceSelectInput, { items: items, onSelect: handleSelect, highlightedIndex: highlightedIndex, isActive: !isSearching, maxVisibleItems: pageSize, width: mainPanelWidth, onLayout: handleListLayout }) })] }))] })), activeTab === "files" && (_jsxs(_Fragment, { children: [_jsx(Box, { marginBottom: 1, children: _jsx(Text, { bold: true, color: theme.muted, children: theme.ascii ? "[ Autogenerated Files ]" : "┌─ Autogenerated Files ─" }) }), selectedServiceData ? (_jsxs(_Fragment, { children: [_jsxs(Text, { color: theme.muted, children: ["Service: ", selectedServiceData.service.name] }), _jsx(Box, { marginTop: 1, children: _jsx(FileTree, { nodes: fileTreeNodes, selectedPath: selectedFile || undefined }) })] })) : (_jsxs(_Fragment, { children: [_jsx(Text, { color: theme.muted, children: "Select a service to view files" }), _jsx(Box, { marginTop: 1, children: _jsx(ResourceSelectInput, { items: items, onSelect: handleSelect, highlightedIndex: highlightedIndex, isActive: !isSearching, maxVisibleItems: pageSize, width: mainPanelWidth, onLayout: handleListLayout }) })] }))] })), activeTab === "config" && (_jsxs(_Fragment, { children: [_jsx(Box, { marginBottom: 1, children: _jsx(Text, { bold: true, color: theme.muted, children: theme.ascii ? "[ Configuration ]" : "┌─ Configuration ─" }) }), selectedServiceData ? (_jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { color: theme.accent, children: selectedServiceData.service.configPath }), _jsx(Box, { marginTop: 1, ...(theme.ascii
                                                             ? {}
                                                             : { borderStyle: "single", borderColor: theme.border }), paddingX: 1, children: _jsx(Text, { color: theme.muted, wrap: "wrap", children: JSON.stringify(selectedServiceData.service.config, null, 2).slice(0, 1000) }) })] })) : (_jsxs(_Fragment, { children: [_jsx(Text, { color: theme.muted, children: "Select a service to view configuration" }), _jsx(Box, { marginTop: 1, children: _jsx(ResourceSelectInput, { items: items, onSelect: handleSelect, highlightedIndex: highlightedIndex, isActive: !isSearching, maxVisibleItems: pageSize, width: mainPanelWidth, onLayout: handleListLayout }) })] }))] }))] }), showSidebar && (_jsx(Box, { marginLeft: 2, children: _jsx(DetailPanel, { stack: selectedStackData?.stack || null, service: selectedServiceData?.service || null, stackMetadata: selectedStackData?.metadata || null, visible: !!selectedStack || !!selectedService }) }))] }), _jsxs(Box, { ...(theme.ascii ? {} : { borderStyle: "single", borderColor: theme.border }), paddingX: 1, height: 3, flexDirection: "column", marginTop: 1, children: [_jsxs(Box, { justifyContent: "space-between", children: [_jsxs(Text, { color: theme.accent, bold: true, children: [theme.bannerStart, " ", activeTab] }), _jsxs(Text, { color: theme.success, children: [theme.ascii ? "[+]" : "\u25cf", " ", services.filter((s) => s.stack).length, " in stack"] }), _jsxs(Text, { color: theme.warning, children: [theme.ascii ? "-" : "\u25cb", " ", services.filter((s) => !s.stack).length, " no stack"] })] }), _jsxs(Box, { justifyContent: "space-between", children: [_jsxs(Text, { color: theme.muted, children: ["Stacks: ", stacks.length] }), _jsxs(Text, { color: theme.muted, children: ["Services: ", services.length] }), _jsxs(Text, { color: theme.muted, children: [theme.ascii ? "Mouse" : "🖱️", " ", mouseEnabled ? "ON" : "OFF", theme.ascii ? " | " : " \u2502 ", theme.ascii ? "Info" : "ℹ️", " ", showTooltips ? "ON" : "OFF", theme.ascii ? " | " : " \u2502 ", _jsx(Text, { color: showEnabledOnly ? theme.success : theme.warning, children: showEnabledOnly
                                                     ? theme.ascii

package/cli/dist/commands/up.js

@@ -12,16 +12,19 @@ import { formatCount } from "../utils/formatting.js";
 import { exportHostPortPlan, getHostPortPlan, writeSavedHostPortPlan, } from "../utils/host-port-config.js";
 import { formatHostPortPlan } from "../utils/host-port-plan.js";
 import { createJsonEmitter } from "../utils/json-output.js";
+import { toMachineError } from "../utils/machine-output.js";
 import { findProjectRoot, getPackageVersion } from "../utils/paths.js";
 import { findAvailablePort } from "../utils/port-assignment.js";
+import { formatPortFallbackNotice } from "../utils/port-fallback-notice.js";
 import { isApiServiceType } from "../utils/resource-kind.js";
 import { appendHealthPath, resolveSubdomainBases } from "../utils/service-urls.js";
 import { discoverResources, discoverResourcesStrict, discoverStacks, stackExists, } from "../utils/services.js";
 import { buildSmokePlans, formatSmokeFailure, runSmokePlans } from "../utils/smoke.js";
+import { buildStartupReport, formatStartupReport, isStartupStalled, } from "../utils/startup-report.js";
 import { evaluateTdkVersionFloor } from "../utils/tdk-version.js";
 import { buildTiltUpArgs, runTilt } from "../utils/tilt.js";
 import { stopTiltOnPort } from "../utils/tilt-process.js";
-import { parseTiltPort, resolveTiltPort, stopTiltForUp } from "../utils/tilt-startup.js";
+import { parseTiltPort, resolveTiltPort, secondUpAction, stopTiltForUp, } from "../utils/tilt-startup.js";
 import { findUnknownServices, resolveOnlySelection } from "../utils/up-only.js";
 import { tiltGetUiResources, waitForTiltResourcesReady } from "../utils/up-readiness.js";
 import { enableDiscoveredStacks } from "./project.js";
@@ -183,18 +186,34 @@ export const upCommand = new Command("up")
         const foundRoot = options.dryRun ? requireProjectRoot() : findProjectRoot();
         const projectRoot = foundRoot ?? process.cwd();
         const discoveredResources = discoverResourcesStrict();
+        let discoveredStacks;
+        let discoveredStackNames = [];
+        if (!options.only || stackName) {
+            discoveredStacks = discoverStacks(discoveredResources);
+            discoveredStackNames = discoveredStacks.map((stack) => stack.name);
+        }
         // Reject a bad request before anything below can write to the project (.env, runtime assets, .tdk/project.json).
         if (options.only) {
-            if (stackName && !stackExists(stackName))
-                errorFactories.stackNotFound(stackName).exit();
+            if (stackName && !stackExists(stackName)) {
+                const error = errorFactories.stackNotFound(stackName, discoveredStackNames);
+                emit?.({ ok: false }, [toMachineError(error).error]);
+                error.exit();
+            }
             const candidates = stackName
                 ? discoveredResources.filter((resource) => resource.stack === stackName)
                 : discoveredResources;
             const unknown = findUnknownServices(options.only, candidates);
             if (unknown.length > 0) {
-                const message = `Unknown service ${unknown.join(", ")}. Valid names: ${candidates.map((s) => s.name).join(", ")}`;
-                emit?.({ ok: false }, [{ code: "UNKNOWN_SERVICE", message }]);
-                showErrorAndExit(message, 2);
+                const validNames = candidates.map((service) => service.name);
+                const error = errorFactories.unknownServices(unknown, validNames);
+                emit?.({ ok: false }, [
+                    {
+                        code: "UNKNOWN_SERVICE",
+                        message: error.message,
+                        ...(error.suggestions.length > 0 ? { suggestions: error.suggestions } : {}),
+                    },
+                ]);
+                error.exit();
             }
         }
         // Also under --dry-run: the check only reads, and a dry run should show what a real run would refuse.
@@ -231,14 +250,16 @@ export const upCommand = new Command("up")
         if (stackName) {
             servicesToStart = discoveredResources.filter((resource) => resource.stack === stackName);
             if (servicesToStart.length === 0) {
-                errorFactories.stackNotFound(stackName).exit();
+                const error = errorFactories.stackNotFound(stackName, discoveredStackNames);
+                emit?.({ ok: false }, [toMachineError(error).error]);
+                error.exit();
             }
             focusServiceNames = servicesToStart.map((s) => s.name);
             stackDescription = `stack "${stackName}"`;
         }
         else {
             servicesToStart = discoveredResources;
-            const allStacks = discoverStacks(discoveredResources);
+            const allStacks = discoveredStacks ?? discoverStacks(discoveredResources);
             stackDescription = `all stacks (${formatCount(allStacks.length, "stack")}, ${formatCount(servicesToStart.length, "service")})`;
         }
         let dependencyNames = [];
@@ -292,6 +313,8 @@ export const upCommand = new Command("up")
         const dryRunCommand = focusTargets ? `tilt up ${tiltArgs.join(" ")}` : "tilt up";
         if (!options.quiet) {
             console.log(chalk.blue(formatHostPortPlan(hostPortPlan)));
+            for (const line of formatPortFallbackNotice(hostPortPlan))
+                console.log(chalk.yellow(line));
             console.log(chalk.gray("Override with TDK_HTTP_PORT, TDK_HTTPS_PORT, or TDK_POSTGRES_PORT."));
         }
         if (emit && options.dryRun) {
@@ -313,23 +336,35 @@ export const upCommand = new Command("up")
         exportHostPortPlan(hostPortPlan);
         writeSavedHostPortPlan(projectRoot, hostPortPlan);
         const basePort = 10350;
-        // A second Tilt would apply a different selection to the same containers, whatever port it listens on, so `--only`
-        // looks for a Tilt that answers on the default port and on TILT_PORT before it chooses one. A listener that is not
-        // Tilt does not count: the port is then picked below as usual.
+        const watchedPort = configuredTiltPort ?? basePort;
+        const candidatePorts = options.only ? [...new Set([basePort, watchedPort])] : [watchedPort];
+        const running = [];
+        for (const candidate of candidatePorts) {
+            if ((await tiltGetUiResources(candidate)) !== null)
+                running.push(candidate);
+        }
+        const decision = secondUpAction({
+            runningPorts: running,
+            force: options.force,
+            only: Boolean(options.only),
+        });
+        if (decision.action === "already-running") {
+            const message = `Environment is already running on port ${decision.ports.join(", ")}.`;
+            emit?.({
+                ok: true,
+                alreadyRunning: true,
+                tiltUrl: `http://localhost:${decision.ports[0]}`,
+            });
+            if (!options.quiet)
+                console.log(chalk.green(message));
+            return;
+        }
+        if (decision.action === "only-blocked") {
+            const message = `A Tilt is already running on port ${decision.ports.join(", ")}. --only cannot change a running stack's services: run \`tdk down\` first, or pass --force to replace it.`;
+            emit?.({ ok: false }, [{ code: "TILT_ALREADY_RUNNING", message }]);
+            showErrorAndExit(message);
+        }
         if (options.only) {
-            const candidatePorts = [
-                ...new Set([basePort, ...(configuredTiltPort === undefined ? [] : [configuredTiltPort])]),
-            ];
-            const running = [];
-            for (const candidate of candidatePorts) {
-                if ((await tiltGetUiResources(candidate)) !== null)
-                    running.push(candidate);
-            }
-            if (running.length > 0 && !options.force) {
-                const message = `A Tilt is already running on port ${running.join(", ")}. --only cannot change a running stack's services: run \`tdk down\` first, or pass --force to replace it.`;
-                emit?.({ ok: false }, [{ code: "TILT_ALREADY_RUNNING", message }]);
-                showErrorAndExit(message);
-            }
             for (const runningPort of running)
                 stopTiltOnPort(runningPort);
         }
@@ -364,6 +399,7 @@ export const upCommand = new Command("up")
         const smokePlans = buildSmokePlans(servicesToStart, hostPortPlan.ingressHttp);
         let smokeFailed = false;
         let printedSuccess = false;
+        let startupFailed = false;
         const successOutput = (async () => {
             const uiReady = await waitForTiltUi(port);
             // JSON consumers get success only after every non-deferred resource is built and running, not when the UI port opens.
@@ -399,12 +435,36 @@ export const upCommand = new Command("up")
                     ]);
                 }
             }
-            if (uiReady && !options.quiet) {
+            // The UI port opening only means Tilt started. Say "up" once every resource is built and running, and otherwise name
+            // what failed and what it blocks.
+            if (uiReady && !emit) {
+                const deferred = getDeferredResourceNames();
+                const dependsOn = Object.fromEntries(discoverResources().map((r) => [r.name, r.config?.dependsOn ?? []]));
+                const readiness = await waitForTiltResourcesReady(port, {
+                    deferred,
+                    isStalled: (text) => isStartupStalled(text, dependsOn, deferred),
+                });
+                if (!readiness.ready) {
+                    startupFailed = true;
+                    const resourcesJson = await tiltGetUiResources(port);
+                    const report = resourcesJson
+                        ? buildStartupReport(resourcesJson, dependsOn, deferred)
+                        : {
+                            failed: readiness.failures,
+                            blocked: [],
+                            starting: [],
+                        };
+                    for (const line of formatStartupReport(report, readiness.timedOut)) {
+                        console.error(chalk.red(line));
+                    }
+                }
+            }
+            if (uiReady && !options.quiet && !startupFailed) {
                 for (const line of formatUpSuccess(port))
                     console.log(chalk.blue(line));
                 printedSuccess = true;
             }
-            if (uiReady && smokePlans.length > 0 && (!emit || jsonReady)) {
+            if (uiReady && smokePlans.length > 0 && (emit ? jsonReady : !startupFailed)) {
                 if (!options.quiet) {
                     console.log(chalk.gray(`Smoke check: ${smokePlans.map((p) => p.name).join(", ")}`));
                 }
@@ -446,6 +506,9 @@ export const upCommand = new Command("up")
         if (result.exitCode !== 0) {
             handleTiltFailure("up", result.exitCode);
         }
+        if (startupFailed && result.exitCode === 0) {
+            process.exit(1);
+        }
         if (!options.quiet && result.exitCode === 0 && !printedSuccess) {
             for (const line of formatUpSuccess(port))
                 console.log(chalk.blue(line));

package/cli/dist/components/ServiceIssues.js

@@ -0,0 +1,12 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from "ink";
+import { useTUITheme } from "./ui-theme.js";
+/** One line per service that is not ready and has a reason, so a failed dependency is named on screen. */
+export function ServiceIssues({ resources }) {
+    const theme = useTUITheme();
+    const issues = resources.filter((r) => r.status !== "ready" && r.statusReason);
+    if (issues.length === 0)
+        return null;
+    return (_jsx(Box, { flexDirection: "column", marginTop: 1, children: issues.map((resource) => (_jsxs(Text, { color: theme.muted, children: [resource.name, ": ", resource.statusReason] }, resource.name))) }));
+}
+//# sourceMappingURL=ServiceIssues.js.map

package/cli/dist/components/index.js

@@ -3,6 +3,7 @@ export { DetailPanel } from "./DetailPanel.js";
 export { FileTree } from "./FileTree.js";
 export { ResourceSelectInput } from "./ResourceSelectInput.js";
 export { ResourceTable } from "./ResourceTable.js";
+export { ServiceIssues } from "./ServiceIssues.js";
 export { TabBar } from "./TabBar.js";
 export { TOOLTIPS } from "./Tooltip.js";
 export { TUIHeader } from "./TUIHeader.js";

package/cli/dist/generator/template-engine.js

@@ -3,6 +3,7 @@ import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import Handlebars from "handlebars";
 import { PLATFORM_STANDARDS } from "../config/platform-standards.js";
+import { writeTextFileAtomic } from "../utils/atomic-write.js";
 import { writeTextFile } from "../utils/file-helpers.js";
 import { assertTdkGeneratedPath } from "../utils/generated-paths.js";
 import { DEFAULT_ALWAYS_ENABLED_INFRA } from "../utils/project-config-defaults.js";
@@ -220,6 +221,7 @@ export function generateDatabaseManagementCompose(projectConfig) {
 # SYSTEM-GENERATED - DO NOT EDIT
 # Stack feature: database-management
 # Source: .tdk/project.json phases.*.enabledStacks includes "database-management"
+# Regenerate with: tdk config regenerate
 ###############################################################################
 
 services:
@@ -443,14 +445,14 @@ export async function generateMasterConfigs(projectRoot, options = {}) {
     for (const filename of ALL_GENERATED_FILES) {
         const content = files[filename];
         const filePath = assertTdkGeneratedPath(projectRoot, path.join(".tdk", ".tdk-out", filename));
-        writeTextFile(filePath, content);
+        writeTextFileAtomic(filePath, content);
         console.log(`✓ Generated: .tdk/.tdk-out/${filename}`);
     }
     if (isStackFeatureEnabledInStacks(projectConfig.phases, "database-management")) {
         const composePath = assertTdkGeneratedPath(projectRoot, path.join("services", "platform", "database-management", "docker-compose.yml"));
         const composeDir = path.dirname(composePath);
         fs.mkdirSync(composeDir, { recursive: true });
-        writeTextFile(composePath, generateDatabaseManagementCompose(projectConfig));
+        writeTextFileAtomic(composePath, generateDatabaseManagementCompose(projectConfig));
         console.log("✓ Generated: services/platform/database-management/docker-compose.yml");
     }
     // Copy .tiltignore to project root so Tilt uses it

package/cli/dist/utils/atomic-write.js

@@ -0,0 +1,35 @@
+import { randomBytes } from "node:crypto";
+import { closeSync, fchmodSync, fsyncSync, openSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { basename, dirname, join } from "node:path";
+/**
+ * Replaces `filePath` in one step. A plain writeFileSync truncates first, so an interrupt mid-write leaves a
+ * half-written file that looks current; here readers see the old content or the new content, never a mix.
+ */
+export function writeTextFileAtomic(filePath, content) {
+    const tempPath = join(dirname(filePath), `.${basename(filePath)}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`);
+    let mode;
+    try {
+        mode = statSync(filePath).mode & 0o777;
+    }
+    catch {
+        mode = undefined;
+    }
+    try {
+        const fd = openSync(tempPath, "wx");
+        try {
+            if (mode !== undefined)
+                fchmodSync(fd, mode);
+            writeFileSync(fd, content, "utf-8");
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        renameSync(tempPath, filePath);
+    }
+    catch (error) {
+        rmSync(tempPath, { force: true });
+        throw error;
+    }
+}
+//# sourceMappingURL=atomic-write.js.map

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

@@ -7,6 +7,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 { findOnPath } from "./which.js";
 const EXEC_TIMEOUT_MS = 10_000;
 const REGISTRY_PROBE_TIMEOUT_MS = 3_000;
@@ -119,11 +120,7 @@ export function parseTiltResourceFailures(jsonText, deferredNames = new Set()) {
             okCount += 1;
             continue;
         }
-        if (name !== "(Tiltfile)" &&
-            (updateStatus === "pending" ||
-                runtimeStatus === "pending" ||
-                updateStatus === "none" ||
-                runtimeStatus === "none")) {
+        if (name !== "(Tiltfile)" && isTiltResourcePending(updateStatus, runtimeStatus)) {
             if (deferredNames.has(name)) {
                 deferredCount += 1;
             }

package/cli/dist/utils/errors.js

@@ -2,6 +2,7 @@ import chalk from "chalk";
 import { QUICKSTART_DOCS_URL } from "./constants.js";
 import { getContainerRuntimeStatus } from "./docker.js";
 import { findProjectRoot } from "./paths.js";
+import { suggestClosest } from "./suggestions.js";
 import { isTiltAvailable } from "./tilt.js";
 export function getErrorMessage(err) {
     return err instanceof Error ? err.message : String(err);
@@ -30,6 +31,16 @@ export class TdkError extends Error {
         process.exit(this.exitCode);
     }
 }
+function closestNameSuggestions(names, candidates, includeInput = false) {
+    const suggestions = new Set();
+    for (const name of names) {
+        const closest = suggestClosest(name, candidates);
+        if (closest) {
+            suggestions.add(includeInput ? `Did you mean "${closest}" for "${name}"?` : `Did you mean "${closest}"?`);
+        }
+    }
+    return [...suggestions];
+}
 export const errorFactories = {
     tiltNotInstalled: () => new TdkError("Tilt CLI is not installed", [
         "Install Tilt: `brew install tilt` (macOS)",
@@ -47,14 +58,21 @@ export const errorFactories = {
         "Quit and reopen Docker Desktop, or run `colima restart`",
         "Then verify with: `docker ps`",
     ]),
-    stackNotFound: (name) => new TdkError(`Stack "${name}" not found`, [
+    stackNotFound: (name, stackNames = []) => new TdkError(`Stack "${name}" not found`, [
+        ...closestNameSuggestions([name], stackNames),
         "Run `tdk stacks` to see available stacks",
         "Run `tdk stack` to assign resources to a stack",
     ]),
-    resourceNotFound: (name) => new TdkError(`Resource "${name}" not found`, [
+    resourceNotFound: (name, resourceNames = []) => new TdkError(`Resource "${name}" not found`, [
+        ...closestNameSuggestions([name], resourceNames),
         "Run `tdk resources` to list all resources",
         "Check the resource name spelling",
     ]),
+    unknownServices: (names, validNames) => {
+        // Service selectors are Tilt resource names, so share the resource suggestion path.
+        const suggestions = closestNameSuggestions(names, validNames, names.length > 1);
+        return new TdkError(`Unknown service ${names.join(", ")}. Valid names: ${validNames.join(", ")}`, suggestions, 2);
+    },
     directoryExists: (path) => new TdkError(`Directory already exists: ${path}`, [
         "Use `--path` to specify a different location",
         "Remove the existing directory if no longer needed",

package/cli/dist/utils/machine-output.js

@@ -4,7 +4,14 @@ export function createMachineEnvelope(data, errors = []) {
 }
 export function toMachineError(error) {
     if (error instanceof TdkError) {
-        return { error: { code: "COMMAND_FAILED", message: error.message }, exitCode: 1 };
+        return {
+            error: {
+                code: "COMMAND_FAILED",
+                message: error.message,
+                ...(error.suggestions.length > 0 ? { suggestions: error.suggestions } : {}),
+            },
+            exitCode: error.exitCode,
+        };
     }
     return {
         error: {

package/cli/dist/utils/port-fallback-notice.js

@@ -0,0 +1,18 @@
+const PORT_KEYS = [
+    { key: "ingressHttp", label: "HTTP", env: "TDK_HTTP_PORT" },
+    { key: "ingressHttps", label: "HTTPS", env: "TDK_HTTPS_PORT" },
+    { key: "postgres", label: "Postgres", env: "TDK_POSTGRES_PORT" },
+];
+/** One line per port TDK moved off the one it wanted. Ports the user set explicitly are never listed. */
+export function formatPortFallbackNotice(plan) {
+    const lines = [];
+    for (const { key, label, env } of PORT_KEYS) {
+        const requested = plan.requested[key];
+        const chosen = plan[key];
+        if (plan.explicit[key] || chosen === requested)
+            continue;
+        lines.push(`${label}: wanted ${requested}, using ${chosen} (${plan.reason[key]}). To force ${requested}: ${env}=${requested} tdk up`);
+    }
+    return lines;
+}
+//# sourceMappingURL=port-fallback-notice.js.map

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

@@ -0,0 +1,67 @@
+import { buildStartupReport, transitiveDependencies } from "./startup-report.js";
+import { 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`
+ * in service.json. A service whose own process is up is still not ready while something it depends on has failed or
+ * is still starting. Services Tilt does not list are absent: the caller shows them as unknown.
+ */
+export function deriveServiceStates(jsonText, dependsOn, deferred = new Set()) {
+    const report = buildStartupReport(jsonText, dependsOn, deferred);
+    const failed = new Map(report.failed.map((entry) => [entry.name, entry.message]));
+    const blocked = new Map(report.blocked.map((entry) => [entry.name, entry.because]));
+    const starting = new Set(report.starting);
+    const items = JSON.parse(onlyEnabledResources(jsonText)).items ?? [];
+    const direct = new Map();
+    for (const item of items) {
+        const name = item.metadata?.name;
+        if (!name || name === "(Tiltfile)")
+            continue;
+        if (failed.has(name)) {
+            direct.set(name, { status: "error", reason: failed.get(name) });
+        }
+        else if (blocked.has(name)) {
+            const because = blocked.get(name) ?? [];
+            direct.set(name, {
+                status: "error",
+                reason: `${because.join(", ")} failed`,
+                blockedBy: because,
+            });
+        }
+        else if (starting.has(name)) {
+            direct.set(name, { status: "pending" });
+        }
+        else if (deferred.has(name) &&
+            isTiltResourcePending(item.status?.updateStatus ?? "", item.status?.runtimeStatus ?? "")) {
+            direct.set(name, { status: "unknown", reason: "starts on its first request" });
+        }
+        else {
+            direct.set(name, { status: "ready" });
+        }
+    }
+    const result = {};
+    for (const [name, state] of direct) {
+        if (state.status !== "ready") {
+            result[name] = state;
+            continue;
+        }
+        const deps = [...transitiveDependencies(name, dependsOn)].filter((dep) => direct.has(dep));
+        const failedDeps = deps.filter((dep) => direct.get(dep)?.status === "error").sort();
+        const waitingDeps = deps.filter((dep) => direct.get(dep)?.status === "pending").sort();
+        if (failedDeps.length > 0) {
+            result[name] = {
+                status: "error",
+                reason: `${failedDeps.join(", ")} failed`,
+                blockedBy: failedDeps,
+            };
+        }
+        else if (waitingDeps.length > 0) {
+            result[name] = { status: "pending", reason: `waiting for ${waitingDeps.join(", ")}` };
+        }
+        else {
+            result[name] = state;
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=service-runtime-state.js.map

package/cli/dist/utils/services.js

@@ -6,6 +6,7 @@ import { errorFactories } from "./errors.js";
 import { formatCount } from "./formatting.js";
 import { findProjectRoot } from "./paths.js";
 import { validateServiceManifest } from "./service-manifest.js";
+import { deriveStackStatus } from "./stack-status.js";
 import { includes } from "./validation.js";
 const RESOURCE_JSON_FILENAME = "service.json";
 function findServiceJsonFiles(dir, maxDepth = 5, currentDepth = 0) {
@@ -338,21 +339,7 @@ export function getStackMetadata(stack) {
     const timestamps = resourcesMetadata.map((r) => new Date(r.createdAt).getTime());
     const earliestTimestamp = Math.min(...timestamps);
     const latestTimestamp = Math.max(...timestamps);
-    const totalResources = resourcesMetadata.length;
-    let overallStatus = "unknown";
-    if (totalResources > 0) {
-        const readyCount = resourcesMetadata.filter((r) => r.status === "ready").length;
-        const ratio = readyCount / totalResources;
-        if (ratio > 0.9) {
-            overallStatus = "healthy";
-        }
-        else if (ratio > 0.5) {
-            overallStatus = "degraded";
-        }
-        else {
-            overallStatus = "error";
-        }
-    }
+    const overallStatus = deriveStackStatus(resourcesMetadata.map((r) => r.status));
     const metadata = {
         name: stack.name,
         resourceCount: resourcesMetadata.length,

package/cli/dist/utils/single-flight.js

@@ -0,0 +1,20 @@
+/**
+ * Runs a load and applies its result, but starts nothing while a previous load is still running. A poll on a timer
+ * therefore never overlaps itself: results cannot arrive out of order, and a slow Tilt cannot make every poll get
+ * superseded before it finishes.
+ */
+export function singleFlight(apply) {
+    let running = false;
+    return async (load) => {
+        if (running)
+            return;
+        running = true;
+        try {
+            apply(await load());
+        }
+        finally {
+            running = false;
+        }
+    };
+}
+//# sourceMappingURL=single-flight.js.map

package/cli/dist/utils/stack-status.js

@@ -0,0 +1,15 @@
+/**
+ * A stack with no known service status has not been checked, so it is "unknown", not "error". Once any service has a
+ * status, the share of ready services decides it.
+ */
+export function deriveStackStatus(statuses) {
+    if (statuses.length === 0 || statuses.every((status) => status === "unknown"))
+        return "unknown";
+    const ratio = statuses.filter((status) => status === "ready").length / statuses.length;
+    if (ratio > 0.9)
+        return "healthy";
+    if (ratio > 0.5)
+        return "degraded";
+    return "error";
+}
+//# sourceMappingURL=stack-status.js.map

package/cli/dist/utils/startup-report.js

@@ -0,0 +1,68 @@
+import { parseTiltResourceFailures, summarizeTiltBuildError } from "./doctor-runtime.js";
+import { isTiltResourcePending } from "./tilt-resource-state.js";
+import { onlyEnabledResources } from "./up-readiness.js";
+export function transitiveDependencies(name, dependsOn) {
+    const seen = new Set();
+    const visit = (current) => {
+        for (const dep of dependsOn[current] ?? []) {
+            if (seen.has(dep))
+                continue;
+            seen.add(dep);
+            visit(dep);
+        }
+    };
+    visit(name);
+    return seen;
+}
+function isPending(item) {
+    return isTiltResourcePending(item.status?.updateStatus ?? "", item.status?.runtimeStatus ?? "");
+}
+export function buildStartupReport(jsonText, dependsOn, deferred = new Set()) {
+    const enabledJson = onlyEnabledResources(jsonText);
+    const failures = parseTiltResourceFailures(enabledJson, deferred).failures;
+    const failed = failures.map((failure) => ({
+        name: failure.name,
+        message: failure.error
+            ? summarizeTiltBuildError(failure.error)
+            : `${failure.updateStatus}/${failure.runtimeStatus}`,
+    }));
+    const failedNames = new Set(failed.map((entry) => entry.name));
+    const items = JSON.parse(enabledJson).items ?? [];
+    const blocked = [];
+    const starting = [];
+    for (const item of items) {
+        const name = item.metadata?.name ?? "unknown";
+        if (name === "(Tiltfile)" || failedNames.has(name) || deferred.has(name) || !isPending(item)) {
+            continue;
+        }
+        const because = [...transitiveDependencies(name, dependsOn)]
+            .filter((dep) => failedNames.has(dep))
+            .sort();
+        if (because.length > 0)
+            blocked.push({ name, because });
+        else
+            starting.push(name);
+    }
+    return { failed, blocked, starting };
+}
+/** A failure exists and everything still pending is blocked by it, so waiting longer cannot help. */
+export function isStartupStalled(jsonText, dependsOn, deferred = new Set()) {
+    const report = buildStartupReport(jsonText, dependsOn, deferred);
+    return report.failed.length > 0 && report.starting.length === 0;
+}
+export function formatStartupReport(report, timedOut) {
+    const lines = [];
+    for (const { name, message } of report.failed)
+        lines.push(`✗ ${name} failed: ${message}`);
+    for (const { name, because } of report.blocked) {
+        lines.push(`✗ ${name} is not ready because ${because.join(", ")} failed`);
+    }
+    if (report.starting.length > 0) {
+        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");
+    }
+    return lines;
+}
+//# sourceMappingURL=startup-report.js.map

package/cli/dist/utils/suggestions.js

@@ -0,0 +1,58 @@
+function levenshteinDistance(left, right) {
+    let previousRow = Array.from({ length: right.length + 1 }, (_, index) => index);
+    for (let leftIndex = 1; leftIndex <= left.length; leftIndex++) {
+        const currentRow = [leftIndex];
+        for (let rightIndex = 1; rightIndex <= right.length; rightIndex++) {
+            const substitutionCost = left[leftIndex - 1] === right[rightIndex - 1] ? 0 : 1;
+            currentRow[rightIndex] = Math.min(currentRow[rightIndex - 1] + 1, previousRow[rightIndex] + 1, previousRow[rightIndex - 1] + substitutionCost);
+        }
+        previousRow = currentRow;
+    }
+    return previousRow[right.length];
+}
+function isAdjacentTransposition(left, right) {
+    if (left.length !== right.length)
+        return false;
+    for (let index = 0; index < left.length - 1; index++) {
+        if (left[index] !== right[index] &&
+            left[index] === right[index + 1] &&
+            left[index + 1] === right[index] &&
+            left.slice(0, index) === right.slice(0, index) &&
+            left.slice(index + 2) === right.slice(index + 2)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Bases the threshold on the longer name and caps it at two edits.
+ * An adjacent transposition counts as one typo; ties use deterministic code-unit order.
+ */
+export function suggestClosest(input, candidates) {
+    if (input.length < 2 || candidates.length === 0)
+        return undefined;
+    // stackExists and findUnknownServices are case-sensitive, so case-only mismatches need the canonical spelling.
+    if (candidates.includes(input))
+        return undefined;
+    const normalizedInput = input.toLowerCase();
+    let closest;
+    let closestDistance = Number.POSITIVE_INFINITY;
+    for (const candidate of candidates) {
+        if (candidate.length === 0)
+            continue;
+        const normalizedCandidate = candidate.toLowerCase();
+        const distance = isAdjacentTransposition(normalizedInput, normalizedCandidate)
+            ? 1
+            : levenshteinDistance(normalizedInput, normalizedCandidate);
+        const threshold = Math.max(1, Math.min(2, Math.floor(Math.max(normalizedInput.length, normalizedCandidate.length) / 3)));
+        if (distance > threshold)
+            continue;
+        if (distance < closestDistance ||
+            (distance === closestDistance && (closest === undefined || candidate < closest))) {
+            closest = candidate;
+            closestDistance = distance;
+        }
+    }
+    return closest;
+}
+//# sourceMappingURL=suggestions.js.map

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

@@ -0,0 +1,12 @@
+/**
+ * A Tilt resource that is not built and running yet: still waiting (`pending`, `none`) or building right now
+ * (`in_progress`). Readiness must treat all of these as not ready.
+ */
+export function isTiltResourcePending(updateStatus, runtimeStatus) {
+    return (updateStatus === "pending" ||
+        updateStatus === "in_progress" ||
+        updateStatus === "none" ||
+        runtimeStatus === "pending" ||
+        runtimeStatus === "none");
+}
+//# sourceMappingURL=tilt-resource-state.js.map

package/cli/dist/utils/tilt-startup.js

@@ -11,6 +11,13 @@ export function parseTiltPort(value) {
     }
     return { ok: true, port };
 }
+export function secondUpAction(input) {
+    if (input.runningPorts.length === 0 || input.force)
+        return { action: "start" };
+    if (input.only)
+        return { action: "only-blocked", ports: input.runningPorts };
+    return { action: "already-running", ports: input.runningPorts };
+}
 export async function resolveTiltPort(options) {
     if (options.configuredPort !== undefined) {
         return { port: options.configuredPort, autoSwitched: false };

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

@@ -0,0 +1,35 @@
+import { getDeferredResourceNames } from "./doctor-runtime.js";
+import { deriveServiceStates } from "./service-runtime-state.js";
+import { deriveStackStatus } from "./stack-status.js";
+import { tiltGetUiResources } from "./up-readiness.js";
+/** One look at the running Tilt. Empty when no Tilt answers, so every service stays unknown. */
+export async function fetchServiceStates(services, tiltPort) {
+    try {
+        const text = await tiltGetUiResources(tiltPort);
+        if (!text)
+            return {};
+        return deriveServiceStates(text, Object.fromEntries(services.map((r) => [r.name, r.config?.dependsOn ?? []])), getDeferredResourceNames());
+    }
+    catch {
+        return {};
+    }
+}
+/** The same states `tdk status` shows, put onto the stack the UI is about to draw. */
+export function applyServiceStates(metadata, states) {
+    const resources = metadata.resources.map((resource) => {
+        const state = states[resource.name];
+        if (!state)
+            return resource;
+        return {
+            ...resource,
+            status: state.status,
+            ...(state.reason ? { statusReason: state.reason } : {}),
+        };
+    });
+    return {
+        ...metadata,
+        resources,
+        overallStatus: deriveStackStatus(resources.map((r) => r.status)),
+    };
+}
+//# sourceMappingURL=ui-service-state.js.map

package/cli/dist/utils/up-readiness.js

@@ -102,6 +102,8 @@ export async function waitForTiltResourcesReady(port, options = {}) {
                 last = evaluation.result;
                 if (evaluation.settled)
                     return last;
+                if (last.failures.length > 0 && options.isStalled?.(text))
+                    return last;
             }
             catch {
                 /* Tilt may emit partial output while starting; retry. */

package/cli/package.json

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

package/cli/templates/.tiltignore.hbs

@@ -3,8 +3,7 @@
 # =============================================================================
 # SYSTEM-GENERATED BY TDK CLI - DO NOT EDIT
 # Source: .tdk/project.json
-# Generated: {{timestamp}}
-# Run 'tdk project' to regenerate
+# Regenerate with: tdk config regenerate
 # =============================================================================
 #
 # This file tells Tilt which directories to ignore during file watching.

package/cli/templates/TILT_RESOURCE_DEFAULTS.star.hbs

@@ -6,7 +6,7 @@
 # SYSTEM-GENERATED BY TDK CLI - DO NOT EDIT
 # Source: TDK Platform Standards v{{version}}
 # Output: .tdk/.tdk-out/
-# Run 'tdk project' to update
+# Regenerate with: tdk config regenerate
 # =============================================================================
 
 # Port Configuration

package/cli/templates/TILT_TECH_STACK.star.hbs

@@ -6,7 +6,7 @@
 # SYSTEM-GENERATED BY TDK CLI - DO NOT EDIT
 # Source: TDK Platform Standards v{{version}}
 # Output: .tdk/.tdk-out/
-# Run 'tdk project' to update
+# Regenerate with: tdk config regenerate
 # =============================================================================
 
 def get_tech_stack():

package/cli/templates/Tiltfile.hbs

@@ -1,11 +1,11 @@
 #!/usr/bin/env starlark
-# -*- coding: utf-8 -*}
+# -*- coding: utf-8 -*-
 # =============================================================================
 # 🎯 {{project.name}} - TILT ENTRYPOINT
 # =============================================================================
 # SYSTEM-GENERATED BY TDK CLI - DO NOT EDIT
 # Source: .tdk/project.json
-# Run 'tdk project' to regenerate
+# Regenerate with: tdk config regenerate
 # =============================================================================
 
 print("🚀 Loading {{project.name}}...")
@@ -38,7 +38,7 @@ TDK extension not found.
 'tdk up' needs the TDK Tilt extension (engine/discovery/specs/ext).
 Fix it with one of:
   1) Regenerate the project so the extension is vendored in:
-       tdk project --yes
+       tdk config regenerate
      (set $TDK_EXTENSION_SOURCE to a tdk-cli checkout if it was not auto-detected)
   2) Point at any tdk-cli checkout:
        export TDK_EXTENSION_PATH=/path/to/tdk-cli

package/cli/templates/spec.master.hbs

@@ -6,7 +6,7 @@
 # SYSTEM-GENERATED BY TDK CLI - DO NOT EDIT
 # Source: .tdk/project.json + TDK Platform Standards v{{version}}
 # Output: .tdk/.tdk-out/
-# Run 'tdk project' to update
+# Regenerate with: tdk config regenerate
 #
 # 🏗️ ARCHITECTURE: Project → Stack → Service (PSR Model)
 # Services are organized into stacks by release phase.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tdk-landscape/tdk-cli-core",
-  "version": "1.3.120",
+  "version": "1.3.121",
   "description": "TDK CLI — start services on your laptop.",
   "homepage": "https://tdk-landscape.github.io/tdk-website",
   "repository": {