@tdk-landscape/tdk-cli-core 1.3.156 → 1.3.158

package/cli/dist/commands/doctor.js

@@ -12,13 +12,12 @@ import { projectNeedsBun } from "../utils/bun-requirement.js";
 import { AUTOGENERATED_DIR, CONTAINER_RUNTIME_CHECK, MASTER_CONFIG_FILES, PACKAGE_JSON, REQUIRED_PACKAGE_SCRIPTS, } from "../utils/constants.js";
 import { isPathDiscovered, readDiscoveryPaths } from "../utils/discovery-paths.js";
 import { checkCrashLoopingContainers } from "../utils/doctor-crashloop.js";
-import { applyDoctorFixes, checkDuplicateTdkInstalls, hasFailedActions, planDoctorFixes, } from "../utils/doctor-fix.js";
+import { applyDoctorFixes, checkDuplicateTdkInstalls, hasFailedActions, planDoctorFixes, projectTiltPids, } from "../utils/doctor-fix.js";
 import { checkDiskSpace, dockerDesktopStuck } from "../utils/doctor-host.js";
 import { collectDoctorChecks, createDoctorReport, getDoctorExitCode, } from "../utils/doctor-report.js";
 import { checkHealthRoutes, checkIngressPorts, checkPrivateNpmRegistry, checkTiltResourceHealth, projectConfigEnablesVerdaccio, summarizeAdvertisedProbes, summarizeServiceProbes, summarizeSmokeResults, } from "../utils/doctor-runtime.js";
 import { checkStarlarkLoadExports } from "../utils/doctor-starlark.js";
 import { checkDockerNetworkCapacity, checkDuplicateResourceNames, checkDuplicateResourcePorts, checkFrontendBackendUrls, checkMigrationsInApi, checkNatsBroker, checkPrismaConsistency, checkResourcePackageJson, checkServiceUrlPorts, checkSharedPlatformPostgres, checkSharedStackRoutes, checkTiltInstances, } from "../utils/doctor-wiring.js";
-import { findProjectTiltUpPids } from "../utils/down-cleanup.js";
 import { validateEnvFile } from "../utils/env-validator.js";
 import { execAsync, isExecTimeout } from "../utils/exec-async.js";
 import { formatCount } from "../utils/formatting.js";
@@ -1018,6 +1017,7 @@ export const doctorCommand = new Command("doctor")
     .option("--strict", "Fail warnings such as a WSL project under /mnt/c")
     .option("--fix", "Repair this project's unused Docker networks and leftover doctor probes", false)
     .option("--dry-run", "With --fix: list the repairs without changing anything", false)
+    .option("--scope <scope>", "With --fix: project (default) or machine, which also removes unused networks of other TDK projects", "project")
     .option("-y, --yes", "With --fix: apply every repair without asking", false)
     .option("--ping-timeout <ms>", "Per-service ping timeout in milliseconds", String(DEFAULT_PING_TIMEOUT_MS))
     .action(async (options) => {
@@ -1033,8 +1033,14 @@ export const doctorCommand = new Command("doctor")
         process.exit(2);
         return;
     }
-    if ((options.dryRun || options.yes) && !options.fix) {
-        const message = `${options.dryRun ? "--dry-run" : "--yes"} only applies with --fix`;
+    const scopeInvalid = !["project", "machine"].includes(options.scope);
+    const scopeWithoutFix = options.scope !== "project" && !options.fix;
+    if (scopeInvalid || scopeWithoutFix || ((options.dryRun || options.yes) && !options.fix)) {
+        const message = scopeInvalid
+            ? `--scope must be project or machine, got "${options.scope}"`
+            : scopeWithoutFix
+                ? "--scope only applies with --fix"
+                : `${options.dryRun ? "--dry-run" : "--yes"} only applies with --fix`;
         if (options.json)
             console.log(JSON.stringify(createDoctorReport([], false, [{ code: "USAGE", message }])));
         console.error(message);
@@ -1100,12 +1106,11 @@ export const doctorCommand = new Command("doctor")
                     // An unreadable config is reported by the project checks below.
                 }
             }
-            const tiltPids = projectRoot
-                ? findProjectTiltUpPids(join(projectRoot, ".tdk", ".tdk-out", "Tiltfile"))
-                : [];
-            const planned = await planDoctorFixes(projectName, undefined, tiltPids.length > 0
-                ? `Tilt is running for this project (pid ${tiltPids.join(", ")}); run tdk down first`
-                : undefined);
+            const tiltPids = projectRoot ? projectTiltPids(projectRoot) : [];
+            const planned = await planDoctorFixes(projectName, undefined, {
+                tiltPids,
+                machine: options.scope === "machine",
+            });
             fixActions = await applyDoctorFixes(planned, {
                 dryRun: options.dryRun,
                 confirm: options.yes || (!options.json && process.stdin.isTTY)

package/cli/dist/commands/up.js

@@ -29,7 +29,7 @@ import { buildSmokePlans, formatSmokeFailure, runSmokePlans } from "../utils/smo
 import { buildStartupReport, formatStartupReport, isStartupStalled, } from "../utils/startup-report.js";
 import { evaluateTdkVersionFloor } from "../utils/tdk-version.js";
 import { buildTiltUpArgs, runTilt } from "../utils/tilt.js";
-import { findTiltPortOwner, isForeignTilt } from "../utils/tilt-port-owner.js";
+import { classifyTiltPorts } from "../utils/tilt-port-owner.js";
 import { stopTiltOnPort } from "../utils/tilt-process.js";
 import { parseTiltPort, resolveTiltPort, secondUpAction, stopTiltForUp, } from "../utils/tilt-startup.js";
 import { findUnknownServices, resolveOnlySelection } from "../utils/up-only.js";
@@ -369,20 +369,7 @@ export const upCommand = new Command("up")
         const basePort = STANDARD_PORTS.tiltUi;
         const watchedPort = configuredTiltPort ?? basePort;
         const candidatePorts = options.only ? [...new Set([basePort, watchedPort])] : [watchedPort];
-        const running = [];
-        const foreign = [];
-        for (const candidate of candidatePorts) {
-            if ((await tiltGetUiResources(candidate)) === null)
-                continue;
-            // A Tilt on this port may belong to another project; that is not "this environment is running".
-            const owner = findTiltPortOwner(candidate);
-            if (owner && isForeignTilt(owner, projectRoot)) {
-                foreign.push({ port: candidate, root: owner.root });
-            }
-            else {
-                running.push(candidate);
-            }
-        }
+        const { running, foreign } = await classifyTiltPorts(candidatePorts, projectRoot, async (candidate) => (await tiltGetUiResources(candidate)) !== null);
         if (foreign.length > 0 && configuredTiltPort !== undefined) {
             const other = foreign[0];
             const message = `TILT_PORT=${other?.port} is used by another project's Tilt (${other?.root}). Choose a free port, or run tdk down in that project.`;

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

@@ -55,7 +55,8 @@ export function crashLoopHint(logs, state) {
     if (/ECONNREFUSED|connection refused|could not connect/i.test(logs)) {
         return "a dependency is not reachable: check that the service it connects to is running and healthy";
     }
-    if (/(is not set|is required|missing required|undefined).*(env|environment|variable)|environment variable.*(missing|not set|required)/i.test(logs)) {
+    if (/\b(?:environment variable|env var)\b.*\b(?:missing|not set|required|undefined)\b/i.test(logs) ||
+        /\b[A-Z][A-Z0-9_]{2,}\b (?:is )?(?:not set|required|missing)\b/.test(logs)) {
         return "a required environment variable is missing: check the project's .env";
     }
     if (state.exitCode === 137)

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

@@ -1,9 +1,13 @@
 // Copyright (c) 2026 TDK Landscape contributors
 // SPDX-License-Identifier: MIT
 import { execFile } from "node:child_process";
-import { realpathSync } from "node:fs";
+import { realpathSync, statfsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
 import { promisify } from "node:util";
-import { projectNetworkNames } from "./down-cleanup.js";
+import { DISK_WARN_GIB } from "./doctor-host.js";
+import { findProjectTiltUpPids, projectNetworkNames, tdkNetworkOwner, tdkNetworkPrefixes, } from "./down-cleanup.js";
+import { tiltGetUiResources } from "./up-readiness.js";
 import { findAllOnPath } from "./which.js";
 const execFilePromise = promisify(execFile);
 const DOCKER_TIMEOUT_MS = 15_000;
@@ -21,6 +25,51 @@ function firstLine(error) {
     const stderr = String(error.stderr ?? error).trim();
     return stderr.split(/\r?\n/)[0] ?? "";
 }
+const STALE_TILT_MIN_AGE_S = 120;
+/** `ps -o etime=` ("[[dd-]hh:]mm:ss") in seconds. */
+export function parseElapsed(etime) {
+    const match = /^\s*(?:(?:(\d+)-)?(\d+):)?(\d+):(\d+)\s*$/.exec(etime);
+    if (!match)
+        return null;
+    const [, days = "0", hours = "0", minutes = "0", seconds = "0"] = match;
+    return ((Number(days) * 24 + Number(hours)) * 60 + Number(minutes)) * 60 + Number(seconds);
+}
+/**
+ * Whether any of `ports` answers as a Tilt UI. A busy Tilt can miss one request, and a wrong "stale" ends in a kill,
+ * so a port gets a second try before it counts as silent.
+ */
+export async function anyTiltAnswers(ports, probe = tiltGetUiResources, attempts = 2, wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms))) {
+    for (let attempt = 0; attempt < attempts; attempt++) {
+        if (attempt > 0)
+            await wait(1000);
+        for (const port of ports) {
+            if ((await probe(port)) !== null)
+                return true;
+        }
+    }
+    return false;
+}
+async function tiltProcessStatus(pid) {
+    if (process.platform === "win32")
+        return "unknown";
+    try {
+        const { stdout: etime } = await execFilePromise("ps", ["-p", String(pid), "-o", "etime="], {
+            encoding: "utf-8",
+            timeout: 5000,
+        });
+        const age = parseElapsed(etime);
+        // A Tilt that is still starting has not bound its port yet.
+        if (age === null || age < STALE_TILT_MIN_AGE_S)
+            return "unknown";
+        const { stdout } = await execFilePromise("lsof", ["-nP", "-a", "-p", String(pid), "-iTCP", "-sTCP:LISTEN", "-Fn"], { encoding: "utf-8", timeout: 5000 });
+        const ports = [...stdout.matchAll(/^n.*:(\d+)$/gm)].map((m) => Number(m[1]));
+        return (await anyTiltAnswers(ports)) ? "healthy" : "stale";
+    }
+    catch {
+        // No lsof, or the process is gone: do not guess.
+        return "unknown";
+    }
+}
 export function createDockerFixDeps(run = runDocker) {
     return {
         async listNetworks() {
@@ -57,6 +106,54 @@ export function createDockerFixDeps(run = runDocker) {
                 throw new Error(firstLine(error));
             }
         },
+        freeDiskGib() {
+            try {
+                const stats = statfsSync(homedir());
+                return (Number(stats.bavail) * Number(stats.bsize)) / 1024 ** 3;
+            }
+            catch {
+                return null;
+            }
+        },
+        async reclaimable() {
+            let buildCache = null;
+            try {
+                const df = await run(["system", "df", "--format", "{{.Type}}\t{{.Reclaimable}}"]);
+                for (const line of df.split(/\r?\n/)) {
+                    const [type, size] = line.split("\t");
+                    // "1.531GB" or "1.5GB (39%)"; the percentage is of the whole, not useful here.
+                    if (type === "Build Cache" && size)
+                        buildCache = size.replace(/\s*\(.*\)/, "").trim();
+                }
+            }
+            catch {
+                // Leave unknown.
+            }
+            let danglingImages = 0;
+            try {
+                const ids = await run(["images", "-q", "-f", "dangling=true"]);
+                danglingImages = ids.split(/\r?\n/).filter(Boolean).length;
+            }
+            catch {
+                // Leave zero.
+            }
+            return { buildCache, danglingImages };
+        },
+        async prune(kind) {
+            try {
+                // Never `volume prune`, never `-a`: only the build cache and untagged images.
+                await run(kind === "builder" ? ["builder", "prune", "-f"] : ["image", "prune", "-f"]);
+            }
+            catch (error) {
+                throw new Error(firstLine(error));
+            }
+        },
+        async tiltStatus(pid) {
+            return tiltProcessStatus(pid);
+        },
+        stopProcess(pid) {
+            process.kill(pid, "SIGTERM");
+        },
         isProcessAlive(pid) {
             try {
                 process.kill(pid, 0);
@@ -71,17 +168,66 @@ export function createDockerFixDeps(run = runDocker) {
 }
 export const dockerFixDeps = createDockerFixDeps();
 /**
- * What `--fix` would do. Only unused networks that are either a leftover doctor probe or one of this project's own
- * (the exact names the engine creates, and only while `projectBusy` is unset) are planned; another project's networks are never listed here.
+ * What `--fix` would do: stop this project's stale Tilt; remove unused networks that are a leftover doctor probe or
+ * this project's own (the exact names the engine creates, skipped while its Tilt runs). Other TDK projects' unused
+ * networks are planned only with `context.machine`, each naming its owner.
  */
-export async function planDoctorFixes(projectName, deps = dockerFixDeps, projectBusy) {
-    const networks = await deps.listNetworks();
+export async function planDoctorFixes(projectName, deps = dockerFixDeps, context = {}) {
     const actions = [];
+    // A Tilt that has run a while without serving its UI is stale and may be stopped; any other Tilt of this project is
+    // running or starting, and its networks are not to be touched.
+    const liveTilt = [];
+    for (const pid of context.tiltPids ?? []) {
+        if ((await deps.tiltStatus(pid)) === "stale") {
+            actions.push({
+                id: `stop-tilt:${pid}`,
+                check: "Tilt processes",
+                scope: "project",
+                command: `kill -TERM ${pid}`,
+                status: "planned",
+                reason: "this project's Tilt is running but its UI does not answer",
+            });
+        }
+        else {
+            liveTilt.push(pid);
+        }
+    }
+    const projectBusy = liveTilt.length > 0
+        ? `Tilt is running for this project (pid ${liveTilt.join(", ")}); run tdk down first`
+        : undefined;
+    const networks = await deps.listNetworks();
+    const freeGib = deps.freeDiskGib();
+    if (freeGib !== null && freeGib < DISK_WARN_GIB) {
+        const { buildCache, danglingImages } = await deps.reclaimable();
+        const low = `${freeGib.toFixed(1)} GB free`;
+        if (buildCache && !/^0(\.0+)?\s*B$/i.test(buildCache)) {
+            actions.push({
+                id: "prune:builder",
+                check: "Disk Space",
+                scope: "host",
+                command: "docker builder prune -f",
+                status: "planned",
+                reason: `${low}; ${buildCache} of build cache reclaimable`,
+            });
+        }
+        if (danglingImages > 0) {
+            actions.push({
+                id: "prune:images",
+                check: "Disk Space",
+                scope: "host",
+                command: "docker image prune -f",
+                status: "planned",
+                reason: `${low}; ${danglingImages} untagged image${danglingImages === 1 ? "" : "s"}`,
+            });
+        }
+    }
     const own = new Set(projectName ? projectNetworkNames(projectName) : []);
+    const prefixes = tdkNetworkPrefixes(networks.map((network) => network.name));
     for (const network of networks) {
         const probe = PROBE_NETWORK.exec(network.name);
         let scope;
         let check;
+        let reason = "unused network";
         if (probe) {
             scope = "probe";
             check = "Orphaned probe networks";
@@ -90,6 +236,11 @@ export async function planDoctorFixes(projectName, deps = dockerFixDeps, project
             scope = "project";
             check = "Docker networks";
         }
+        else if (context.machine && tdkNetworkOwner(network.name, prefixes)) {
+            scope = "machine";
+            check = "Docker networks";
+            reason = `unused network of project "${tdkNetworkOwner(network.name, prefixes)}"`;
+        }
         else {
             continue;
         }
@@ -99,7 +250,7 @@ export async function planDoctorFixes(projectName, deps = dockerFixDeps, project
             scope,
             command: `docker network rm ${network.name}`,
             status: "planned",
-            reason: "unused network",
+            reason,
         };
         if (network.containers > 0) {
             action.status = "skipped";
@@ -146,9 +297,18 @@ export async function applyDoctorFixes(actions, options, deps = dockerFixDeps) {
             results.push({ ...action, status: "skipped", reason: "not confirmed" });
             continue;
         }
-        const name = action.id.slice("remove-network:".length);
         try {
-            await deps.removeNetwork(name);
+            if (action.id.startsWith("prune:")) {
+                await deps.prune(action.id === "prune:builder" ? "builder" : "images");
+                results.push({ ...action, status: "applied", reason: "pruned" });
+                continue;
+            }
+            if (action.id.startsWith("stop-tilt:")) {
+                deps.stopProcess(Number(action.id.slice("stop-tilt:".length)));
+                results.push({ ...action, status: "applied", reason: "stopped" });
+                continue;
+            }
+            await deps.removeNetwork(action.id.slice("remove-network:".length));
             results.push({ ...action, status: "applied", reason: "removed" });
         }
         catch (error) {
@@ -209,3 +369,22 @@ export async function checkDuplicateTdkInstalls(installs) {
         fix: "Keep one: remove the others, or run tdk upgrade. The first on PATH is the one your shell runs; tools that launch /usr/local/bin/tdk directly may use another",
     };
 }
+/**
+ * PIDs of `tilt up` processes for this project. The process list shows the Tiltfile path as it was typed at launch,
+ * which may or may not be the symlink-resolved path, so both spellings are looked up.
+ */
+export function projectTiltPids(projectRoot, find = findProjectTiltUpPids) {
+    const roots = new Set([projectRoot]);
+    try {
+        roots.add(realpathSync(projectRoot));
+    }
+    catch {
+        // Keep the path as given.
+    }
+    const pids = new Set();
+    for (const root of roots) {
+        for (const pid of find(join(root, ".tdk", ".tdk-out", "Tiltfile")))
+            pids.add(pid);
+    }
+    return [...pids];
+}

package/cli/dist/utils/down-cleanup.js

@@ -17,6 +17,32 @@ export function projectNetworkNames(projectName) {
     const prefix = projectName.replace(/-/g, "_");
     return PROJECT_NETWORK_SUFFIXES.map((suffix) => `${prefix}_${suffix}`);
 }
+/**
+ * Prefixes of TDK projects among `networkNames`, from the networks the engine creates. Generic suffixes such as
+ * `backend` also occur in non-TDK compose projects, so a prefix counts only if it has a Traefik network, which
+ * only TDK creates.
+ */
+export function tdkNetworkPrefixes(networkNames) {
+    const prefixes = new Set();
+    for (const name of networkNames) {
+        for (const marker of ["traefik-public", "traefik-private"]) {
+            if (name.endsWith(`_${marker}`))
+                prefixes.add(name.slice(0, -(marker.length + 1)));
+        }
+    }
+    return prefixes;
+}
+/** The TDK project prefix a network belongs to (`umami` for `umami_backend`), or null. */
+export function tdkNetworkOwner(name, prefixes) {
+    for (const suffix of PROJECT_NETWORK_SUFFIXES) {
+        if (name.endsWith(`_${suffix}`)) {
+            const prefix = name.slice(0, -(suffix.length + 1));
+            if (prefixes.has(prefix))
+                return prefix;
+        }
+    }
+    return null;
+}
 /**
  * Remove this project's own networks. Only the exact names the engine creates are touched, and `docker network rm`
  * itself refuses a network that still has containers attached, so another project's networks and in-use networks

package/cli/dist/utils/tilt-port-owner.js

@@ -47,3 +47,17 @@ function canonical(path) {
 export function isForeignTilt(owner, projectRoot) {
     return owner !== null && canonical(owner.root) !== canonical(projectRoot);
 }
+/** Split the candidate Tilt UI ports that answer into this project's and other projects'. */
+export async function classifyTiltPorts(candidatePorts, projectRoot, isServing, ownerOf = findTiltPortOwner) {
+    const result = { running: [], foreign: [] };
+    for (const port of candidatePorts) {
+        if (!(await isServing(port)))
+            continue;
+        const owner = ownerOf(port);
+        if (owner && isForeignTilt(owner, projectRoot))
+            result.foreign.push({ port, root: owner.root });
+        else
+            result.running.push(port);
+    }
+    return result;
+}