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

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

@@ -0,0 +1,160 @@
+// Copyright (c) 2026 TDK Landscape contributors
+// SPDX-License-Identifier: MIT
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { toComposeProjectPrefix } from "./doctor-runtime.js";
+import { redactSecrets } from "./secret-redaction.js";
+const execFilePromise = promisify(execFile);
+const DOCKER_TIMEOUT_MS = 10_000;
+/** Restarts that make a container a crash loop rather than a one-off. */
+export const CRASH_LOOP_RESTARTS = 5;
+/** A container that restarted this recently is still looping; an old count on a healthy container is history. */
+const RECENT_START_MS = 10 * 60_000;
+const LOG_LINES = 3;
+const LOG_LINE_MAX = 200;
+const runDocker = async (args) => {
+    const { stdout, stderr } = await execFilePromise("docker", args, {
+        encoding: "utf-8",
+        timeout: DOCKER_TIMEOUT_MS,
+        windowsHide: true,
+    });
+    return `${stdout}${stderr}`;
+};
+/** Whether this container's compose project belongs to the TDK project, however the engine spelled the separator. */
+export function belongsToProject(composeProject, projectName) {
+    const prefix = toComposeProjectPrefix(projectName).toLowerCase();
+    const label = composeProject.replace(/-/g, "_").toLowerCase();
+    return label === prefix || label.startsWith(`${prefix}_`);
+}
+export function isCrashLooping(state, now = Date.now()) {
+    if (state.status === "restarting")
+        return true;
+    if (state.restartCount < CRASH_LOOP_RESTARTS)
+        return false;
+    if (state.status === "running") {
+        const started = Date.parse(state.startedAt);
+        return Number.isNaN(started) || now - started < RECENT_START_MS;
+    }
+    // Stopped: only a recent failure is a loop that gave up (restart policy exhausted). A container stopped by hand
+    // keeps its old restart count, and that is history.
+    const finished = Date.parse(state.finishedAt ?? "");
+    return state.exitCode !== 0 && !Number.isNaN(finished) && now - finished < RECENT_START_MS;
+}
+/** A hint for a cause that the last log lines name. Null when they do not say. */
+export function crashLoopHint(logs, state) {
+    const database = /database "([^"]+)" does not exist/i.exec(logs);
+    if (database) {
+        return `database "${database[1]}" does not exist: re-run the project's database provisioning (tdk up) or create it`;
+    }
+    if (/Cannot find module|MODULE_NOT_FOUND|module not found/i.test(logs)) {
+        return "a module is missing from the image: rebuild it (tdk up --force) after checking the resource's dependencies";
+    }
+    if (/EADDRINUSE|address already in use/i.test(logs)) {
+        return "the port inside the container is already in use: check for two processes started by the same command";
+    }
+    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)) {
+        return "a required environment variable is missing: check the project's .env";
+    }
+    if (state.exitCode === 137)
+        return "killed (exit 137), usually out of memory: raise the container's memory limit";
+    return null;
+}
+function parseStates(output) {
+    const states = [];
+    for (const line of output.split(/\r?\n/)) {
+        const [name, restarts, status, startedAt, exitCode, finishedAt] = line.split("\t");
+        if (!name || restarts === undefined)
+            continue;
+        states.push({
+            name: name.replace(/^\//, ""),
+            restartCount: Number(restarts) || 0,
+            status: status ?? "",
+            startedAt: startedAt ?? "",
+            exitCode: Number(exitCode) || 0,
+            finishedAt: finishedAt ?? "",
+        });
+    }
+    return states;
+}
+/** Containers of this project that keep restarting, with their last log lines and a cause hint when one is clear. */
+export async function checkCrashLoopingContainers(projectName, secrets = [], run = runDocker, now = Date.now()) {
+    const name = "Crash-looping containers";
+    let candidates;
+    try {
+        const listing = await run([
+            "ps",
+            "-a",
+            "--format",
+            '{{.ID}}\t{{.Label "com.docker.compose.project"}}',
+        ]);
+        candidates = listing
+            .split(/\r?\n/)
+            .map((line) => line.split("\t"))
+            .filter(([id, project]) => id && project && belongsToProject(project, projectName))
+            .map(([id]) => id);
+    }
+    catch {
+        return {
+            name,
+            didPass: true,
+            isSkipped: true,
+            message: "Docker not available - skipped crash-loop check",
+        };
+    }
+    if (candidates.length === 0) {
+        return { name, didPass: true, isSkipped: true, message: "No project containers to check" };
+    }
+    let states;
+    try {
+        states = parseStates(await run([
+            "inspect",
+            "--format",
+            "{{.Name}}\t{{.RestartCount}}\t{{.State.Status}}\t{{.State.StartedAt}}\t{{.State.ExitCode}}\t{{.State.FinishedAt}}",
+            ...candidates,
+        ]));
+    }
+    catch {
+        // A container removed between ps and inspect fails the whole batch; that is not a finding.
+        return {
+            name,
+            didPass: true,
+            isSkipped: true,
+            message: "Containers changed while checking - skipped crash-loop check",
+        };
+    }
+    const looping = states.filter((state) => isCrashLooping(state, now));
+    if (looping.length === 0) {
+        return { name, didPass: true, message: "No project container is crash-looping" };
+    }
+    const details = [];
+    const hints = new Set();
+    for (const state of looping) {
+        let logs = "";
+        try {
+            logs = await run(["logs", "--tail", String(LOG_LINES), state.name]);
+        }
+        catch {
+            // The container may have just been removed; report it without logs.
+        }
+        const lines = redactSecrets(logs, secrets)
+            .split(/\r?\n/)
+            .map((line) => line.trim().slice(0, LOG_LINE_MAX))
+            .filter(Boolean);
+        const hint = crashLoopHint(logs, state);
+        if (hint)
+            hints.add(hint);
+        details.push([
+            `${state.name}: ${state.status}, restarted ${state.restartCount} times`,
+            ...lines.map((line) => `  | ${line}`),
+        ].join("\n    "));
+    }
+    return {
+        name,
+        didPass: false,
+        message: `${looping.length} container${looping.length === 1 ? " is" : "s are"} crash-looping:\n    ${details.join("\n    ")}`,
+        fix: [...hints, "Read the full log: docker logs <container>"].join("; "),
+    };
+}

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

@@ -0,0 +1,211 @@
+// Copyright (c) 2026 TDK Landscape contributors
+// SPDX-License-Identifier: MIT
+import { execFile } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { promisify } from "node:util";
+import { projectNetworkNames } from "./down-cleanup.js";
+import { findAllOnPath } from "./which.js";
+const execFilePromise = promisify(execFile);
+const DOCKER_TIMEOUT_MS = 15_000;
+/** The networks `tdk doctor` creates to test capacity; an interrupted run leaves one behind. */
+const PROBE_NETWORK = /^tdk_doctor_probe_(\d+)$/;
+const runDocker = async (args) => {
+    const { stdout } = await execFilePromise("docker", args, {
+        encoding: "utf-8",
+        timeout: DOCKER_TIMEOUT_MS,
+        windowsHide: true,
+    });
+    return stdout;
+};
+function firstLine(error) {
+    const stderr = String(error.stderr ?? error).trim();
+    return stderr.split(/\r?\n/)[0] ?? "";
+}
+export function createDockerFixDeps(run = runDocker) {
+    return {
+        async listNetworks() {
+            const names = (await run(["network", "ls", "--format", "{{.Name}}"]))
+                .split(/\r?\n/)
+                .map((line) => line.trim())
+                .filter(Boolean);
+            // One inspect per network: another process (a doctor probe, `tdk down`) can remove one mid-listing, and a
+            // batched inspect would then fail for all of them.
+            const inspected = await Promise.all(names.map(async (name) => {
+                try {
+                    const count = await run([
+                        "network",
+                        "inspect",
+                        "--format",
+                        "{{len .Containers}}",
+                        name,
+                    ]);
+                    return { name, containers: Number(count.trim()) || 0 };
+                }
+                catch (error) {
+                    if (/no such network|not found/i.test(String(error)))
+                        return null;
+                    throw error;
+                }
+            }));
+            return inspected.filter((network) => network !== null);
+        },
+        async removeNetwork(name) {
+            try {
+                await run(["network", "rm", name]);
+            }
+            catch (error) {
+                throw new Error(firstLine(error));
+            }
+        },
+        isProcessAlive(pid) {
+            try {
+                process.kill(pid, 0);
+                return true;
+            }
+            catch (error) {
+                // EPERM means the process exists but belongs to someone else.
+                return error.code === "EPERM";
+            }
+        },
+    };
+}
+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.
+ */
+export async function planDoctorFixes(projectName, deps = dockerFixDeps, projectBusy) {
+    const networks = await deps.listNetworks();
+    const actions = [];
+    const own = new Set(projectName ? projectNetworkNames(projectName) : []);
+    for (const network of networks) {
+        const probe = PROBE_NETWORK.exec(network.name);
+        let scope;
+        let check;
+        if (probe) {
+            scope = "probe";
+            check = "Orphaned probe networks";
+        }
+        else if (own.has(network.name)) {
+            scope = "project";
+            check = "Docker networks";
+        }
+        else {
+            continue;
+        }
+        const action = {
+            id: `remove-network:${network.name}`,
+            check,
+            scope,
+            command: `docker network rm ${network.name}`,
+            status: "planned",
+            reason: "unused network",
+        };
+        if (network.containers > 0) {
+            action.status = "skipped";
+            action.reason = `${network.containers} container(s) still attached`;
+        }
+        else if (scope === "project" && projectBusy) {
+            // A starting stack creates its networks before any container joins them, so "unused" is not safe to remove.
+            action.status = "skipped";
+            action.reason = projectBusy;
+        }
+        else if (probe && deps.isProcessAlive(Number(probe[1]))) {
+            // The doctor run that created it may still be using it.
+            action.status = "skipped";
+            action.reason = `probe of a running process (pid ${probe[1]})`;
+        }
+        actions.push(action);
+    }
+    return actions;
+}
+/** Run the planned actions in order. A declined or failed action never stops the rest, so a re-run converges. */
+export async function applyDoctorFixes(actions, options, deps = dockerFixDeps) {
+    const results = [];
+    for (const action of actions) {
+        if (action.status !== "planned" || options.dryRun) {
+            results.push(action);
+            continue;
+        }
+        if (!options.confirm) {
+            results.push({
+                ...action,
+                status: "skipped",
+                reason: "confirmation required; run in a terminal or pass --yes",
+            });
+            continue;
+        }
+        let confirmed = false;
+        try {
+            confirmed = await options.confirm(action);
+        }
+        catch {
+            // No terminal to ask on.
+        }
+        if (!confirmed) {
+            results.push({ ...action, status: "skipped", reason: "not confirmed" });
+            continue;
+        }
+        const name = action.id.slice("remove-network:".length);
+        try {
+            await deps.removeNetwork(name);
+            results.push({ ...action, status: "applied", reason: "removed" });
+        }
+        catch (error) {
+            results.push({ ...action, status: "failed", reason: firstLine(error) });
+        }
+    }
+    return results;
+}
+/** Whether any action leaves a problem behind that a re-run could still repair. */
+export function hasFailedActions(actions) {
+    return actions.some((action) => action.status === "failed");
+}
+async function readTdkVersion(path) {
+    try {
+        const { stdout } = await execFilePromise(path, ["--version"], {
+            encoding: "utf-8",
+            timeout: 5000,
+            windowsHide: true,
+        });
+        return stdout.trim().split(/\r?\n/)[0] || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Every distinct `tdk` on PATH (symlinks to one binary count once), in PATH order. */
+export async function findTdkInstalls(paths = findAllOnPath("tdk"), readVersion = readTdkVersion) {
+    const seen = new Set();
+    const installs = [];
+    for (const path of paths) {
+        let real = path;
+        try {
+            real = realpathSync(path);
+        }
+        catch {
+            // Keep the PATH entry as is.
+        }
+        if (seen.has(real))
+            continue;
+        seen.add(real);
+        installs.push({ path, version: await readVersion(path) });
+    }
+    return installs;
+}
+/** Two `tdk` binaries can disagree (a dashboard or MCP client may launch the older one), so say which is which. */
+export async function checkDuplicateTdkInstalls(installs) {
+    const found = installs ?? (await findTdkInstalls());
+    if (found.length <= 1) {
+        return { name: "TDK installs", didPass: true, message: "One tdk install on PATH" };
+    }
+    const list = found.map((i) => `${i.path} (${i.version ?? "version unknown"})`).join(", ");
+    const versions = new Set(found.map((i) => i.version));
+    return {
+        name: "TDK installs",
+        didPass: false,
+        isWarning: true,
+        message: `${found.length} tdk installs on PATH${versions.size > 1 ? " with different versions" : ""}: ${list}`,
+        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",
+    };
+}

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

@@ -0,0 +1,49 @@
+// Copyright (c) 2026 TDK Landscape contributors
+// SPDX-License-Identifier: MIT
+import { execFileSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { resolve } from "node:path";
+import { parseTiltProcesses } from "./doctor-wiring.js";
+const run = (command, args) => execFileSync(command, args, {
+    encoding: "utf-8",
+    stdio: "pipe",
+    timeout: 5000,
+    windowsHide: true,
+});
+/**
+ * The project whose `tilt up` listens on `port`, or null when it cannot be told (no lsof, Windows, a Tilt started
+ * without `-f`, a listener that is not Tilt). Callers must treat null as "unknown", not as "not mine".
+ */
+export function findTiltPortOwner(port, platform = process.platform, commandRunner = run) {
+    if (platform === "win32")
+        return null;
+    try {
+        const pids = commandRunner("lsof", ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-t"])
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter(Boolean);
+        for (const pid of pids) {
+            const command = commandRunner("ps", ["-p", pid, "-o", "command="]).trim();
+            const [owner] = parseTiltProcesses(`${pid} ${command}`);
+            if (owner)
+                return owner;
+        }
+    }
+    catch {
+        // lsof exits 1 when nothing listens, and may be missing.
+    }
+    return null;
+}
+/** Symlinked checkouts (macOS /tmp -> /private/tmp) must not make a project look foreign to itself. */
+function canonical(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return resolve(path);
+    }
+}
+/** Whether `owner` is another project's Tilt, as opposed to this project's or unknown. */
+export function isForeignTilt(owner, projectRoot) {
+    return owner !== null && canonical(owner.root) !== canonical(projectRoot);
+}

package/cli/dist/utils/which.js

@@ -25,3 +25,32 @@ export function findOnPath(command) {
     }
     return null;
 }
+export function findAllOnPath(command) {
+    const pathEnv = process.env.PATH ?? process.env.Path ?? "";
+    const windows = isWindows();
+    const names = pathLookups(command, windows);
+    if (windows && !extname(command)) {
+        for (const extension of (process.env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";")) {
+            const suffix = extension.toLowerCase();
+            if (suffix && !names.includes(`${command}${suffix}`))
+                names.push(`${command}${suffix}`);
+        }
+    }
+    const found = [];
+    const seen = new Set();
+    for (const dir of pathEnv.split(delimiter)) {
+        if (!dir)
+            continue;
+        for (const name of names) {
+            const candidate = join(dir, name);
+            if (!existsSync(candidate))
+                continue;
+            const key = windows ? candidate.toLowerCase() : candidate;
+            if (!seen.has(key)) {
+                seen.add(key);
+                found.push(candidate);
+            }
+        }
+    }
+    return found;
+}