@flisk-sh/flisk 0.0.0-stage → 1.3.189

package/cli/dist/utils/discovery-paths.js

@@ -0,0 +1,93 @@
+// Copyright (c) 2026 Flisk Landscape contributors
+// SPDX-License-Identifier: MIT
+import { existsSync, readFileSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
+import { PROJECT_JSON } from "./constants.js";
+// Mirrors discovery/json_manifest_scanner.star: every `discovery.paths` entry is a shell
+// glob of directories, and `find -maxdepth 3` looks for service.json under each match. So a
+// resource is only seen by Tilt if some directory matching a pattern is the resource
+// directory itself or at most this many levels above it.
+const MAX_LEVELS_BELOW_MATCH = 2;
+const DEFAULT_DISCOVERY_PATHS = ["services/*/*"];
+function segments(path) {
+    return path.split(sep).filter(Boolean);
+}
+// Wildcard match without building a RegExp: `*` matches any run of characters, `?` one character,
+// everything else is literal. Greedy with a single backtrack point, so it stays linear-ish on
+// hostile patterns such as "a*a*a*b".
+function segmentMatches(pattern, name) {
+    let p = 0;
+    let n = 0;
+    let starP = -1;
+    let starN = 0;
+    while (n < name.length) {
+        if (p < pattern.length &&
+            pattern[p] !== "*" &&
+            (pattern[p] === "?" || pattern[p] === name[n])) {
+            p++;
+            n++;
+        }
+        else if (p < pattern.length && pattern[p] === "*") {
+            starP = p++;
+            starN = n;
+        }
+        else if (starP !== -1) {
+            p = starP + 1;
+            n = ++starN;
+        }
+        else {
+            return false;
+        }
+    }
+    while (p < pattern.length && pattern[p] === "*")
+        p++;
+    return p === pattern.length;
+}
+function globMatchesDir(patternSegments, dirSegments) {
+    return (patternSegments.length === dirSegments.length &&
+        patternSegments.every((segment, index) => segmentMatches(segment, dirSegments[index])));
+}
+/** `discovery.paths` from .tdk/project.json, or the generic default when unset/unreadable. */
+export function readDiscoveryPaths(projectRoot) {
+    const configPath = join(projectRoot, ".tdk", PROJECT_JSON);
+    if (!existsSync(configPath))
+        return DEFAULT_DISCOVERY_PATHS;
+    try {
+        const paths = JSON.parse(readFileSync(configPath, "utf-8"))?.discovery?.paths;
+        if (Array.isArray(paths) && paths.every((p) => typeof p === "string"))
+            return paths;
+    }
+    catch { }
+    return DEFAULT_DISCOVERY_PATHS;
+}
+/** Whether Tilt's discovery would find a service.json in `resourceDir` given `patterns`. */
+export function isPathDiscovered(projectRoot, resourceDir, patterns) {
+    const resourceSegments = segments(relative(projectRoot, resolve(projectRoot, resourceDir)));
+    return patterns.some((pattern) => {
+        const patternSegments = segments(relative(projectRoot, resolve(projectRoot, pattern)));
+        for (let levels = 0; levels <= MAX_LEVELS_BELOW_MATCH; levels++) {
+            const depth = resourceSegments.length - levels;
+            if (depth > 0 && globMatchesDir(patternSegments, resourceSegments.slice(0, depth))) {
+                return true;
+            }
+        }
+        return false;
+    });
+}
+/**
+ * Picks the folder for a new resource without an explicit --path. The conventional folder
+ * per type (apps/, workers/, packages/) is kept when discovery covers it; otherwise the
+ * resource goes under services/<stack>/, which the default discovery paths cover, because a
+ * resource outside every discovery path is scaffolded but never started by `flisk up`.
+ */
+export function chooseResourcePath(projectRoot, conventionalPath, stack, name) {
+    const patterns = readDiscoveryPaths(projectRoot);
+    if (isPathDiscovered(projectRoot, conventionalPath, patterns)) {
+        return { path: conventionalPath };
+    }
+    const fallback = `services/${stack}/${name}`;
+    if (isPathDiscovered(projectRoot, fallback, patterns)) {
+        return { path: fallback, adjustedFrom: conventionalPath };
+    }
+    return { path: conventionalPath };
+}

package/cli/dist/utils/docker.js

@@ -0,0 +1,34 @@
+// Copyright (c) 2026 Flisk Landscape contributors
+// SPDX-License-Identifier: MIT
+import { execFileSync, execSync } from "node:child_process";
+import { findOnPath } from "./which.js";
+// A wedged daemon makes `docker ps` block forever instead of failing.
+const RUNTIME_CHECK_TIMEOUT_MS = 10_000;
+/** Whether Docker, Colima, or Podman is reachable, hung, or absent. */
+export function getContainerRuntimeStatus() {
+    let sawTimeout = false;
+    if (process.platform === "win32") {
+        try {
+            execFileSync(findOnPath("docker") ?? "docker", ["ps"], {
+                stdio: "ignore",
+                timeout: RUNTIME_CHECK_TIMEOUT_MS,
+                windowsHide: true,
+            });
+            return "running";
+        }
+        catch (err) {
+            return err.code === "ETIMEDOUT" ? "unresponsive" : "missing";
+        }
+    }
+    for (const command of ["docker ps", "colima status", "podman ps"]) {
+        try {
+            execSync(command, { stdio: "ignore", timeout: RUNTIME_CHECK_TIMEOUT_MS });
+            return "running";
+        }
+        catch (err) {
+            if (err.code === "ETIMEDOUT")
+                sawTimeout = true;
+        }
+    }
+    return sawTimeout ? "unresponsive" : "missing";
+}

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

@@ -0,0 +1,161 @@
+// Copyright (c) 2026 Flisk 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 Flisk 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 (flisk 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 (flisk 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 (/\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)
+        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,391 @@
+// Copyright (c) 2026 Flisk Landscape contributors
+// SPDX-License-Identifier: MIT
+import { execFile } from "node:child_process";
+import { realpathSync, statfsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { DISK_WARN_GIB } from "./doctor-host.js";
+import { findProjectTiltUpPids, projectNetworkNames, tdkNetworkOwner, tdkNetworkPrefixes, } from "./down-cleanup.js";
+import { executableName, legacyExecutableName } from "./platform.js";
+import { tiltGetUiResources } from "./up-readiness.js";
+import { findAllOnPath } from "./which.js";
+const execFilePromise = promisify(execFile);
+const DOCKER_TIMEOUT_MS = 15_000;
+/** The networks `flisk doctor` creates to test capacity; an interrupted run leaves one behind. */
+const PROBE_NETWORK = /^flisk_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] ?? "";
+}
+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() {
+            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, `flisk 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));
+            }
+        },
+        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);
+                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: 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 Flisk projects' unused
+ * networks are planned only with `context.machine`, each naming its owner.
+ */
+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 flisk 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";
+        }
+        else if (own.has(network.name)) {
+            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;
+        }
+        const action = {
+            id: `remove-network:${network.name}`,
+            check,
+            scope,
+            command: `docker network rm ${network.name}`,
+            status: "planned",
+            reason,
+        };
+        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;
+        }
+        try {
+            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) {
+            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 Flisk install on PATH (symlinks to one binary count once), in PATH order. */
+export async function findTdkInstalls(paths = [...findAllOnPath(executableName()), ...findAllOnPath(legacyExecutableName())], 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 `flisk` 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: "Flisk installs", didPass: true, message: "One flisk 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: "Flisk installs",
+        didPass: false,
+        isWarning: true,
+        message: `${found.length} flisk installs on PATH${versions.size > 1 ? " with different versions" : ""}: ${list}`,
+        fix: "Keep one: remove the others, or run flisk upgrade. The first on PATH is the one your shell runs; tools that launch /usr/local/bin/flisk 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];
+}