@flisk-sh/flisk 0.0.0-stage → 1.3.190

package/cli/dist/utils/spinner.js

@@ -0,0 +1,40 @@
+// Copyright (c) 2026 Flisk Landscape contributors
+// SPDX-License-Identifier: MIT
+import chalk from "chalk";
+const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+export function startSpinner(initialText) {
+    const stream = process.stderr;
+    const animate = stream.isTTY === true;
+    let frame = 0;
+    let text = initialText;
+    let timer;
+    const render = () => stream.write(`\r\x1b[2K${chalk.cyan(FRAMES[frame])} ${text}`);
+    if (animate) {
+        render();
+        timer = setInterval(() => {
+            frame = (frame + 1) % FRAMES.length;
+            render();
+        }, 80);
+    }
+    else {
+        stream.write(`- ${text}\n`);
+    }
+    const finish = (symbol, message) => {
+        if (timer)
+            clearInterval(timer);
+        stream.write(`${animate ? "\r\x1b[2K" : ""}${symbol} ${message ?? text}\n`);
+    };
+    return {
+        get text() {
+            return text;
+        },
+        set text(value) {
+            text = value;
+            if (!animate)
+                stream.write(`- ${text}\n`);
+        },
+        succeed: (message) => finish(chalk.green("✔"), message),
+        fail: (message) => finish(chalk.red("✖"), message),
+        warn: (message) => finish(chalk.yellow("⚠"), message),
+    };
+}

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

@@ -0,0 +1,15 @@
+// Copyright (c) 2026 Flisk Landscape contributors
+// SPDX-License-Identifier: MIT
+import { DATABASE_MANAGEMENT_FEATURE } from "./constants.js";
+export const STACK_FEATURES = {
+    [DATABASE_MANAGEMENT_FEATURE]: {
+        name: DATABASE_MANAGEMENT_FEATURE,
+        description: "Generate and load the stack-level PostgreSQL docker-compose file",
+        generatedFiles: ["services/platform/database-management/docker-compose.yml"],
+    },
+};
+export function isStackFeatureEnabledInStacks(stacks, featureName) {
+    if (!STACK_FEATURES[featureName])
+        return false;
+    return ["pre_alpha", "alpha", "beta"].some((phase) => stacks[phase]?.enabledStacks?.includes(featureName));
+}

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

@@ -0,0 +1,14 @@
+/**
+ * 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";
+}

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

@@ -0,0 +1,78 @@
+// Copyright (c) 2026 Flisk Landscape contributors
+// SPDX-License-Identifier: MIT
+import { parseTiltResourceFailures, summarizeTiltBuildError } from "./doctor-runtime.js";
+import { portConflictFix } from "./port-conflict-fix.js";
+import { effectiveRuntimeStatus, 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 ?? "", effectiveRuntimeStatus(item.status));
+}
+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))
+            continue;
+        const because = [...transitiveDependencies(name, dependsOn)]
+            .filter((dep) => failedNames.has(dep))
+            .sort();
+        if (because.length > 0)
+            blocked.push({ name, because });
+        else if (isPending(item))
+            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}`);
+        const fix = portConflictFix(message);
+        if (fix)
+            lines.push(`  ${fix}`);
+    }
+    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) {
+        const causes = [...new Set(report.blocked.flatMap((entry) => entry.because))].sort();
+        const count = report.blocked.length;
+        const summary = count > 0
+            ? `: ${causes.join(", ")} failed, so ${count} dependent ${count === 1 ? "service is" : "services are"} not ready`
+            : "";
+        lines.push(`The environment is not ready${summary}. Tilt is still running; inspect it or run: flisk down`);
+    }
+    return lines;
+}

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

@@ -0,0 +1,21 @@
+export function createStatusMessageController(setMessage) {
+    let timer;
+    return {
+        show(message, durationMs = 1500) {
+            if (timer !== undefined) {
+                clearTimeout(timer);
+            }
+            setMessage(message);
+            timer = setTimeout(() => {
+                timer = undefined;
+                setMessage("");
+            }, durationMs);
+        },
+        dispose() {
+            if (timer !== undefined) {
+                clearTimeout(timer);
+                timer = undefined;
+            }
+        },
+    };
+}

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

@@ -0,0 +1,33 @@
+import { STANDARD_PORTS } from "./constants.js";
+import { isApiServiceType } from "./resource-kind.js";
+import { resolveServicePath, resolveSubdomainBases } from "./service-urls.js";
+export function buildServicePorts(resource, ingressHttp) {
+    const appType = resource.config?.appType;
+    const routable = appType === "frontend" || isApiServiceType(appType);
+    let url = null;
+    if (routable) {
+        const { appBase, apiBase } = resolveSubdomainBases(ingressHttp);
+        url = `${isApiServiceType(appType) ? apiBase : appBase}${resolveServicePath(resource)}`;
+    }
+    const containerPort = resource.port ?? resource.config?.port ?? null;
+    const directUrl = !routable && containerPort ? `http://localhost:${containerPort}` : null;
+    return { url, containerPort, hostPort: null, directUrl };
+}
+/** Ports a client should forward or open: ingress, Tilt UI, and the published datastore. Not one per service. */
+export function buildStackPorts(plan, tiltPort) {
+    const ports = [];
+    if (plan) {
+        ports.push({ name: "ingress-http", hostPort: plan.ingressHttp, purpose: "Traefik HTTP ingress" }, { name: "ingress-https", hostPort: plan.ingressHttps, purpose: "Traefik HTTPS ingress" });
+    }
+    // `flisk up` may move Tilt off 10350 and records that only in its own process, so this is the default or TILT_PORT.
+    const validTiltPort = tiltPort !== undefined && Number.isInteger(tiltPort) && tiltPort > 0;
+    ports.push({
+        name: "tilt-ui",
+        hostPort: validTiltPort ? tiltPort : STANDARD_PORTS.tiltUi,
+        purpose: "Tilt UI",
+    });
+    if (plan) {
+        ports.push({ name: "postgres", hostPort: plan.postgres, purpose: "Published Postgres" });
+    }
+    return ports;
+}

package/cli/dist/utils/suggestions.js

@@ -0,0 +1,63 @@
+// Copyright (c) 2026 Flisk Landscape contributors
+// SPDX-License-Identifier: MIT
+// Every cell is written before it is read, so the fallback never changes the result.
+function cell(row, index) {
+    return row[index] ?? 0;
+}
+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(cell(currentRow, rightIndex - 1) + 1, cell(previousRow, rightIndex) + 1, cell(previousRow, rightIndex - 1) + substitutionCost);
+        }
+        previousRow = currentRow;
+    }
+    return cell(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;
+}

package/cli/dist/utils/tar.js

@@ -0,0 +1,46 @@
+// Copyright (c) 2026 Flisk Landscape contributors
+// SPDX-License-Identifier: MIT
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+/**
+ * Extracts a gzipped tarball (as an in-memory buffer) into destDir.
+ * Shells out to the system `tar` binary rather than pulling in a JS tar
+ * implementation - available by default on macOS and Linux.
+ */
+export function extractTarball(data, destDir) {
+    const tempDir = mkdtempSync(join(tmpdir(), "flisk-ext-"));
+    const tmpFile = join(tempDir, "bundle.tar.gz");
+    writeFileSync(tmpFile, data);
+    mkdirSync(destDir, { recursive: true });
+    const tarBin = process.platform === "win32" ? "tar.exe" : "tar";
+    const result = spawnSync(tarBin, ["xzf", tmpFile, "-C", destDir, "--strip-components=1"], {
+        stdio: "pipe",
+        windowsHide: true,
+    });
+    if (result.status !== 0) {
+        const fallbackDir = join(tempDir, "fallback");
+        mkdirSync(fallbackDir, { recursive: true });
+        const fallback = spawnSync(tarBin, ["xzf", tmpFile, "-C", fallbackDir], {
+            stdio: "pipe",
+            windowsHide: true,
+        });
+        if (fallback.status !== 0) {
+            rmSync(tempDir, { recursive: true, force: true });
+            throw new Error(`tar extraction failed: ${fallback.stderr?.toString() || result.stderr?.toString() || "unknown error"}`);
+        }
+        const entries = readdirSync(fallbackDir);
+        const [only] = entries;
+        const sourceDir = entries.length === 1 &&
+            only !== undefined &&
+            existsSync(join(fallbackDir, only)) &&
+            statSync(join(fallbackDir, only)).isDirectory()
+            ? join(fallbackDir, only)
+            : fallbackDir;
+        for (const entry of readdirSync(sourceDir)) {
+            renameSync(join(sourceDir, entry), join(destDir, entry));
+        }
+    }
+    rmSync(tempDir, { recursive: true, force: true });
+}

package/cli/dist/utils/tdk-version.js

@@ -0,0 +1,51 @@
+// Copyright (c) 2026 Flisk Landscape contributors
+// SPDX-License-Identifier: MIT
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { PROJECT_JSON } from "./constants.js";
+function toParts(raw) {
+    const match = raw.trim().match(/(\d+)\.(\d+)(?:\.(\d+))?/);
+    return match ? [Number(match[1]), Number(match[2]), Number(match[3] ?? 0)] : null;
+}
+function readMinTdkVersion(projectRoot) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(projectRoot, ".tdk", PROJECT_JSON), "utf-8"));
+        return parsed?.minTdkVersion;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function evaluateTdkVersionFloor(projectRoot, currentVersion) {
+    const minimum = readMinTdkVersion(projectRoot);
+    if (minimum === undefined)
+        return { status: "none" };
+    const required = typeof minimum === "string" ? toParts(minimum) : null;
+    if (!required || !/^\d+\.\d+\.\d+$/.test(String(minimum).trim())) {
+        return {
+            status: "malformed",
+            message: `.tdk/project.json minTdkVersion ${JSON.stringify(minimum)} is not a version like "1.3.80"`,
+            fix: 'Set minTdkVersion to a MAJOR.MINOR.PATCH string, for example "1.3.80".',
+        };
+    }
+    const current = toParts(currentVersion);
+    const meets = current !== null &&
+        (() => {
+            for (const [index, need] of required.entries()) {
+                const actual = current[index] ?? 0;
+                if (actual !== need)
+                    return actual > need;
+            }
+            return true;
+        })();
+    const requiredText = required.join(".");
+    if (!meets) {
+        return {
+            status: "too-old",
+            required: requiredText,
+            message: `flisk ${currentVersion} is older than the ${requiredText} this project requires (minTdkVersion)`,
+            fix: "Run: flisk upgrade",
+        };
+    }
+    return { status: "ok", required: requiredText };
+}

package/cli/dist/utils/terminal-layout.js

@@ -0,0 +1,19 @@
+const COMPACT_TAB_WIDTH = 76;
+const WIDE_TAB_WIDTH = 100;
+export function getTerminalRuleWidth(terminalWidth) {
+    return Math.max(0, Math.min(terminalWidth - 4, 100));
+}
+export function getTabBarDensity(terminalWidth) {
+    if (terminalWidth < COMPACT_TAB_WIDTH)
+        return "compact";
+    if (terminalWidth < WIDE_TAB_WIDTH)
+        return "standard";
+    return "wide";
+}
+/**
+ * Convert an SGR mouse row (1-based) to an Ink layout row (0-based).
+ * The UI uses Ink's alternate screen with no Static content, so the live region starts at row 1.
+ */
+export function getListRowFromMouseY(mouseY, listTop) {
+    return mouseY - 1 - listTop;
+}

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

@@ -0,0 +1,194 @@
+import { STANDARD_PORTS } from "./constants.js";
+import { runTilt } from "./tilt.js";
+export class TiltEventsLoadError extends Error {
+    kind;
+    constructor(message, kind) {
+        super(message);
+        this.kind = kind;
+        this.name = "TiltEventsLoadError";
+    }
+}
+function asRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+// Tilt-controlled text is rendered in the terminal, so drop ANSI/OSC escape sequences and
+// other control characters (keeping tab/newline for later whitespace normalization).
+const ESC = String.fromCharCode(0x1b);
+const BEL = String.fromCharCode(0x07);
+const ANSI_SEQUENCE = new RegExp(`${ESC}(?:\\[[0-?]*[ -/]*[@-~]|\\][^${BEL}${ESC}]*(?:${BEL}|${ESC}\\\\)?|[@-Z\\\\-_])`, "g");
+// A regex literal would trip noControlCharactersInRegex, so this stays a string; keep the autofix from rewriting it.
+// biome-ignore lint/complexity/useRegexLiterals: the control-character range must stay in a string
+const CONTROL_CHARS = new RegExp("[\\u0000-\\u0008\\u000b-\\u001f\\u007f-\\u009f]", "g");
+export function stripTerminalControls(value) {
+    return value.replace(ANSI_SEQUENCE, "").replace(CONTROL_CHARS, "");
+}
+function readString(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const cleaned = stripTerminalControls(value).trim();
+    return cleaned || undefined;
+}
+function readStringArray(value) {
+    return Array.isArray(value)
+        ? value.flatMap((item) => {
+            const cleaned = readString(item);
+            return cleaned ? [cleaned] : [];
+        })
+        : [];
+}
+export function parseTiltUiResourceList(value) {
+    const list = asRecord(value);
+    if (!list || !Array.isArray(list.items)) {
+        throw new Error("Tilt returned an invalid UIResource list");
+    }
+    const resources = [];
+    const events = [];
+    for (const value of list.items) {
+        const item = asRecord(value);
+        const metadata = asRecord(item?.metadata);
+        const resourceName = readString(metadata?.name);
+        if (!item || !resourceName)
+            continue;
+        const status = asRecord(item.status);
+        resources.push({
+            name: resourceName,
+            runtimeStatus: readString(status?.runtimeStatus),
+            updateStatus: readString(status?.updateStatus),
+            hasPendingChanges: typeof status?.hasPendingChanges === "boolean" ? status.hasPendingChanges : undefined,
+        });
+        const history = Array.isArray(status?.buildHistory) ? status.buildHistory : [];
+        for (const [buildIndex, value] of history.entries()) {
+            const build = asRecord(value);
+            if (!build)
+                continue;
+            const error = readString(build.error);
+            const warnings = readStringArray(build.warnings);
+            const details = [error, ...warnings].filter((entry) => Boolean(entry));
+            const spanId = readString(build.spanID);
+            events.push({
+                id: `${resourceName}:build:${spanId ?? String(buildIndex)}`,
+                resourceName,
+                kind: error ? "failed" : warnings.length ? "warning" : "success",
+                title: error
+                    ? "Build failed"
+                    : warnings.length
+                        ? "Build completed with warnings"
+                        : "Build completed",
+                occurredAt: readString(build.finishTime) ?? readString(build.startTime),
+                details: details.length ? details.join("; ") : undefined,
+            });
+        }
+        const currentBuild = asRecord(status?.currentBuild);
+        if (currentBuild) {
+            events.push({
+                id: `${resourceName}:current-build`,
+                resourceName,
+                kind: "running",
+                title: "Build in progress",
+                occurredAt: readString(currentBuild.startTime),
+            });
+        }
+        const pendingSince = readString(status?.pendingBuildSince);
+        if (!currentBuild && (status?.queued === true || pendingSince)) {
+            events.push({
+                id: `${resourceName}:queued`,
+                resourceName,
+                kind: "warning",
+                title: "Update queued",
+                occurredAt: pendingSince,
+            });
+        }
+        const lastDeployTime = readString(status?.lastDeployTime);
+        const deployTimestamp = lastDeployTime ? Date.parse(lastDeployTime) : Number.NaN;
+        const matchingBuild = events.some((event) => event.resourceName === resourceName &&
+            event.kind === "success" &&
+            event.occurredAt !== undefined &&
+            Date.parse(event.occurredAt) === deployTimestamp);
+        if (lastDeployTime && !matchingBuild) {
+            events.push({
+                id: `${resourceName}:last-deploy`,
+                resourceName,
+                kind: "success",
+                title: "Last deployed",
+                occurredAt: lastDeployTime,
+            });
+        }
+        const conditions = Array.isArray(status?.conditions) ? status.conditions : [];
+        for (const [conditionIndex, value] of conditions.entries()) {
+            const condition = asRecord(value);
+            if (!condition)
+                continue;
+            const type = readString(condition.type);
+            const state = readString(condition.status);
+            const reason = readString(condition.reason);
+            const message = readString(condition.message);
+            if ((!type && !reason && !message) || (state === "True" && !reason && !message))
+                continue;
+            const detail = [reason, message]
+                .filter((entry) => Boolean(entry))
+                .join(": ");
+            events.push({
+                id: `${resourceName}:condition:${conditionIndex}:${type ?? "status"}`,
+                resourceName,
+                kind: state === "False" ? "warning" : "status",
+                title: `Condition ${type ?? "status"}${state ? `: ${state}` : ""}`,
+                occurredAt: readString(condition.lastTransitionTime),
+                details: detail || undefined,
+            });
+        }
+    }
+    events.sort((left, right) => {
+        if (left.kind === "running" && right.kind !== "running")
+            return -1;
+        if (right.kind === "running" && left.kind !== "running")
+            return 1;
+        const leftTime = left.occurredAt ? Date.parse(left.occurredAt) : Number.NaN;
+        const rightTime = right.occurredAt ? Date.parse(right.occurredAt) : Number.NaN;
+        if (Number.isNaN(leftTime)) {
+            return Number.isNaN(rightTime) ? left.resourceName.localeCompare(right.resourceName) : 1;
+        }
+        if (Number.isNaN(rightTime))
+            return -1;
+        return rightTime - leftTime;
+    });
+    return { resources, events };
+}
+export async function loadTiltEvents() {
+    const port = process.env.TILT_PORT ?? String(STANDARD_PORTS.tiltUi);
+    let result;
+    try {
+        result = await runTilt("get", ["uiresources", "-o", "json", "--port", port], {
+            inheritStdio: false,
+            timeoutMs: 10_000,
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const kind = /ENOENT|not found|no such file|connection refused|failed to connect|could not connect|unable to connect|Tilt is not running/i.test(message)
+            ? "unavailable"
+            : "error";
+        throw new TiltEventsLoadError(message, kind);
+    }
+    if (result.exitCode !== 0) {
+        const message = result.stderr.trim() || `tilt get exited with code ${result.exitCode}`;
+        const kind = /connection refused|failed to connect|could not connect|unable to connect|Tilt is not running|no running Tilt/i.test(message)
+            ? "unavailable"
+            : "error";
+        throw new TiltEventsLoadError(message, kind);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(result.stdout);
+    }
+    catch {
+        throw new TiltEventsLoadError("Tilt returned invalid UIResource JSON", "error");
+    }
+    try {
+        return parseTiltUiResourceList(parsed);
+    }
+    catch (error) {
+        throw new TiltEventsLoadError(error instanceof Error ? error.message : "Tilt returned an invalid UIResource list", "error");
+    }
+}

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

@@ -0,0 +1,61 @@
+export const DEFAULT_LOG_TAIL = 200;
+/** Upper bound for --tail so a snapshot stays small enough for an agent to read. */
+export const MAX_LOG_TAIL = 10_000;
+const NANOSECONDS = {
+    ns: 1,
+    us: 1e3,
+    µs: 1e3,
+    ms: 1e6,
+    s: 1e9,
+    m: 6e10,
+    h: 3.6e12,
+};
+// Go's time.Duration is an int64 of nanoseconds, so anything beyond this is rejected by `tilt logs`.
+const MAX_DURATION_NANOSECONDS = 2 ** 63 - 1;
+/**
+ * Go-style duration such as 30s, 5m, 1h or 1h30m, within roughly the range Go's ParseDuration accepts.
+ * The sum is a JS number, so values within a few nanoseconds of the int64 limit can disagree with Go; this only needs to
+ * reject absurd input, and Tilt remains the final judge (its rejection is reported as TILT_LOGS_FAILED).
+ */
+export function isValidSince(value) {
+    if (!/^(\d+(\.\d+)?(ns|us|µs|ms|s|m|h))+$/.test(value))
+        return false;
+    let total = 0;
+    for (const [, amount, unit] of value.matchAll(/(\d+(?:\.\d+)?)(ns|us|µs|ms|s|m|h)/g)) {
+        total += Number(amount) * (NANOSECONDS[unit] ?? 0);
+    }
+    return total <= MAX_DURATION_NANOSECONDS;
+}
+export function isValidPort(value) {
+    return /^[1-9]\d{0,4}$/.test(value) && Number(value) <= 65535;
+}
+export function isValidTail(value) {
+    return /^[1-9]\d*$/.test(value) && Number(value) <= MAX_LOG_TAIL;
+}
+/** Parse `tilt logs --json` (JSON Lines) into normalized lines, keeping at most the last `limit`. Unparseable lines are skipped. */
+export function parseTiltLogLines(output, limit) {
+    const lines = [];
+    for (const raw of output.split("\n")) {
+        if (!raw.trim())
+            continue;
+        try {
+            const entry = JSON.parse(raw);
+            const str = (value) => typeof value === "string" && value !== "" ? value : null;
+            lines.push({
+                time: str(entry.time),
+                resource: str(entry.resource),
+                level: str(entry.level),
+                source: str(entry.source),
+                text: typeof entry.message === "string" ? entry.message : "",
+            });
+        }
+        catch {
+            // Tilt can print a non-JSON notice before the stream; it is not a log line.
+        }
+    }
+    return lines.slice(-limit);
+}
+/** True when `tilt logs` failed because no Tilt server answered, as opposed to rejecting its arguments. */
+export function isTiltConnectionFailure(stderr) {
+    return /connection refused|connecting to Tilt|no such host|dial tcp|websocket_token/i.test(stderr);
+}