@flisk-sh/flisk 0.0.0-stage → 1.3.190

package/cli/dist/utils/file-helpers.js

@@ -0,0 +1,104 @@
+// Copyright (c) 2026 Flisk Landscape contributors
+// SPDX-License-Identifier: MIT
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import chalk from "chalk";
+export function writeFilesWithProgress(basePath, tasks, onProgress) {
+    for (const [i, task] of tasks.entries()) {
+        console.log(chalk.blue(`${task.emoji} ${task.description}...`));
+        if (task.type === "json") {
+            writeJsonFileInDir(basePath, task.filename, task.content);
+        }
+        else {
+            writeTextFileInDir(basePath, task.filename, String(task.content));
+        }
+        if (onProgress) {
+            onProgress(task, i, tasks.length);
+        }
+    }
+}
+/**
+ * Write JSON data to a file.
+ * @param filePath - Path to the file
+ * @param data - JSON-serializable data
+ * @param space - Number of spaces for indentation (default: 2)
+ */
+export function writeJsonFile(filePath, data, space = 2) {
+    const content = `${JSON.stringify(data, null, space)}\n`;
+    writeFileSync(filePath, content, "utf-8");
+}
+export function writeJsonFileInDir(dir, filename, data, space = 2) {
+    const filePath = resolve(dir, filename);
+    writeJsonFile(filePath, data, space);
+}
+export function writeTextFile(filePath, content) {
+    writeFileSync(filePath, content, "utf-8");
+}
+export function writeTextFileInDir(dir, filename, content) {
+    const filePath = resolve(dir, filename);
+    writeTextFile(filePath, content);
+}
+export function ensureDirectory(dirPath) {
+    if (!existsSync(dirPath)) {
+        mkdirSync(dirPath, { recursive: true });
+    }
+}
+/** Generated files that must never be committed: .env holds a generated DB password. */
+const GITIGNORE_ENTRIES = [
+    ".env",
+    ".tdk/.tdk-out/",
+    ".tdk/.project-id",
+    ".tdk/smoke/",
+    "node_modules/",
+];
+/**
+ * Appends the Flisk entries missing from the project's .gitignore (creating it
+ * if needed), so the first `git add .` doesn't commit .env or generated
+ * output. Returns the entries it added.
+ */
+export function ensureGitignore(projectRoot) {
+    const gitignorePath = resolve(projectRoot, ".gitignore");
+    const existing = existsSync(gitignorePath) ? readFileSync(gitignorePath, "utf-8") : "";
+    const lines = new Set(existing.split("\n").map((line) => line.trim().replace(/\/$/, "")));
+    const missing = GITIGNORE_ENTRIES.filter((entry) => !lines.has(entry.replace(/\/$/, "")));
+    if (missing.length === 0)
+        return [];
+    const prefix = existing && !existing.endsWith("\n") ? "\n" : "";
+    const header = existing
+        ? "\n# Flisk (generated files and secrets)\n"
+        : "# Flisk (generated files and secrets)\n";
+    appendFileSync(gitignorePath, `${prefix}${header}${missing.join("\n")}\n`);
+    return missing;
+}
+/**
+ * True when the path sits inside a git working tree: a `.git` directory in a clone, a `.git` file in a linked worktree.
+ * Only then is an ignore entry worth writing.
+ */
+export function isInsideGitWorkTree(startPath) {
+    let dir = resolve(startPath);
+    for (;;) {
+        if (existsSync(resolve(dir, ".git")))
+            return true;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return false;
+        dir = parent;
+    }
+}
+/**
+ * Makes sure the smoke records cannot be committed by accident: the project .gitignore must ignore `.tdk/smoke/` before
+ * `flisk up` writes a record. Only meaningful inside a git working tree, so nothing is written outside one. Returns the
+ * warning to show when the entry could not be ensured, and undefined when it is.
+ */
+export function ensureSmokeRecordsIgnored(projectRoot) {
+    if (!isInsideGitWorkTree(projectRoot))
+        return undefined;
+    try {
+        ensureGitignore(projectRoot);
+        return undefined;
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        return `Could not add .tdk/smoke/ to ${resolve(projectRoot, ".gitignore")}: ${reason}. Git may track the smoke response records.`;
+    }
+}

package/cli/dist/utils/formatting.js

@@ -0,0 +1,165 @@
+// Copyright (c) 2026 Flisk Landscape contributors
+// SPDX-License-Identifier: MIT
+import chalk from "chalk";
+function pluralize(count, singular, plural) {
+    return count === 1 ? singular : plural || `${singular}s`;
+}
+export function formatCount(count, singular, plural) {
+    return `${count} ${pluralize(count, singular, plural)}`;
+}
+const DATE_FORMAT_OPTIONS = {
+    month: "short",
+    day: "numeric",
+    hour: "2-digit",
+    minute: "2-digit",
+};
+export function formatDate(timestamp) {
+    const date = new Date(timestamp);
+    return date.toLocaleString("en-US", DATE_FORMAT_OPTIONS);
+}
+export function formatShortDate(timestamp) {
+    const date = new Date(timestamp);
+    return date.toLocaleDateString("en-US", { month: "short", day: "numeric" });
+}
+const STATUS_CATEGORY_CONFIG = {
+    success: { color: "green", icon: "✓", chalkFn: chalk.green },
+    error: { color: "red", icon: "✗", chalkFn: chalk.red },
+    warning: { color: "yellow", icon: "○", chalkFn: chalk.yellow },
+    unknown: { color: "gray", icon: "?", chalkFn: chalk.gray },
+};
+function getStatusCategory(status) {
+    if (!status)
+        return "unknown";
+    const lowerStatus = status.toLowerCase();
+    if (lowerStatus === "ready" ||
+        lowerStatus === "healthy" ||
+        lowerStatus === "active" ||
+        lowerStatus === "running") {
+        return "success";
+    }
+    if (lowerStatus === "error" ||
+        lowerStatus === "failed" ||
+        lowerStatus === "critical" ||
+        lowerStatus === "stopped") {
+        return "error";
+    }
+    if (lowerStatus === "pending" ||
+        lowerStatus === "starting" ||
+        lowerStatus === "building" ||
+        lowerStatus === "degraded") {
+        return "warning";
+    }
+    return "unknown";
+}
+export function getStatusColor(status) {
+    return STATUS_CATEGORY_CONFIG[getStatusCategory(status)].color;
+}
+export function getStatusIcon(status) {
+    return STATUS_CATEGORY_CONFIG[getStatusCategory(status)].icon;
+}
+export function colorizeByStatus(text, status) {
+    return STATUS_CATEGORY_CONFIG[getStatusCategory(status)].chalkFn(text);
+}
+const EMPTY_STATE_CONFIG = {
+    resources: {
+        singular: "resource",
+        command: "flisk resource <name>",
+        context: "\nTo create a resource:",
+    },
+    stacks: {
+        singular: "stack",
+        command: "flisk stack <stack-name>",
+        context: "\nTo create a stack, use:",
+    },
+    services: {
+        singular: "service",
+        command: "flisk resource <name>",
+        context: "\nTo create a service:",
+    },
+    "stack-services": {
+        singular: "service",
+        command: "flisk resource <name> --stack <stack-name>",
+        context: "\nTo add services to this stack:",
+    },
+};
+export function showEmptyState(itemType, filterContext) {
+    const config = EMPTY_STATE_CONFIG[itemType];
+    if (filterContext) {
+        console.log(chalk.yellow(`No ${config.singular}s found${filterContext}.`));
+    }
+    else {
+        console.log(chalk.yellow(`No ${config.singular}s found.`));
+    }
+    console.log(chalk.gray(config.context));
+    console.log(chalk.gray(`  ${config.command}`));
+    if (itemType === "stacks") {
+        console.log(chalk.gray("\nOr create a new resource with a stack:"));
+        console.log(chalk.gray("  flisk resource <name> --stack <stack-name>"));
+    }
+}
+export function showCancelled(message) {
+    console.log(chalk.yellow(message || "Cancelled."));
+}
+export function showCommandHeader(title) {
+    console.log(chalk.blue(`Flisk ${title}\n`));
+}
+export function showAllSatisfyCondition(items, condition) {
+    console.log(chalk.green(`All ${items} are ${condition}!`));
+}
+/** Default width for ASCII boxes */
+export const DEFAULT_BOX_WIDTH = 62;
+export function formatBoxLine(char = "─", width = DEFAULT_BOX_WIDTH) {
+    return char.repeat(width);
+}
+export function formatCentered(text, width = DEFAULT_BOX_WIDTH - 2) {
+    const padding = Math.max(0, width - text.length);
+    const left = Math.floor(padding / 2);
+    const right = padding - left;
+    return " ".repeat(left) + text + " ".repeat(right);
+}
+export function formatPadded(text, width) {
+    if (text.length > width) {
+        return `${text.slice(0, width - 1)}…`;
+    }
+    return text.padEnd(width);
+}
+export function truncate(str, maxLength) {
+    if (str.length <= maxLength)
+        return str;
+    return `${str.slice(0, maxLength - 3)}...`;
+}
+export function showSuccess(message) {
+    console.log(chalk.green(`✓ ${message}`));
+}
+export function showStep(message) {
+    console.log(chalk.blue(message));
+}
+export function showDetail(message, indent = 2) {
+    console.log(chalk.gray(`${" ".repeat(indent)}${message}`));
+}
+export function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+/**
+ * Print a boxed header with title and optional subtitle.
+ * Consolidates common box formatting patterns from networks.ts and other commands.
+ * @param title - The main title to display
+ * @param subtitle - Optional subtitle (e.g., domain info)
+ * @param width - Box width (defaults to DEFAULT_BOX_WIDTH)
+ */
+export function printBoxedHeader(title, subtitle, width = DEFAULT_BOX_WIDTH) {
+    const innerWidth = width - 2;
+    const line = "─".repeat(innerWidth);
+    console.log();
+    console.log(chalk.cyan(`╭${line}╮`));
+    console.log(chalk.cyan("│") + chalk.bold.white(formatCentered(title, innerWidth)) + chalk.cyan("│"));
+    if (subtitle) {
+        console.log(chalk.cyan(`├${line}┤`));
+        console.log(chalk.cyan("│") + chalk.gray(formatCentered(subtitle, innerWidth)) + chalk.cyan("│"));
+    }
+    console.log(chalk.cyan(`╰${line}╯`));
+}

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

@@ -0,0 +1,51 @@
+// Copyright (c) 2026 Flisk Landscape contributors
+// SPDX-License-Identifier: MIT
+import { existsSync, lstatSync } from "node:fs";
+import { isAbsolute, normalize, relative, sep } from "node:path";
+import { AUTOGENERATED_DIR, PACKAGE_JSON, TILTIGNORE_FILE } from "./constants.js";
+/** Reviewed Flisk-owned destinations written by `flisk config regenerate` or Tilt generation. */
+export const TDK_GENERATED_PATH_ALLOWLIST = [
+    `${AUTOGENERATED_DIR}/**`,
+    ".tdk/.tdk-out/**",
+    "Tiltfile",
+    "TILT_*.star",
+    TILTIGNORE_FILE,
+    `${PACKAGE_JSON} (create only)`,
+    "shared-platform-engineering/docker-templates/**",
+    "services/platform/database-management/docker-compose.yml",
+    "product_autogenerated_resource_manifests/**",
+    "product_autogenerated_services_list/**",
+];
+export function isTdkGeneratedPath(path) {
+    const normalized = normalize(path).split(sep).join("/");
+    if (isAbsolute(path) || normalized === ".." || normalized.startsWith("../"))
+        return false;
+    if (normalized.split("/").includes(AUTOGENERATED_DIR) ||
+        normalized.startsWith(".tdk/.tdk-out/") ||
+        normalized === "shared-platform-engineering/docker-templates" ||
+        normalized.startsWith("shared-platform-engineering/docker-templates/") ||
+        normalized.startsWith("product_autogenerated_resource_manifests/") ||
+        normalized.startsWith("product_autogenerated_services_list/")) {
+        return true;
+    }
+    return (normalized === "Tiltfile" ||
+        /^TILT_[^/]+\.star$/.test(normalized) ||
+        normalized === TILTIGNORE_FILE ||
+        normalized === PACKAGE_JSON ||
+        normalized === "services/platform/database-management/docker-compose.yml");
+}
+export function assertTdkGeneratedPath(projectRoot, path) {
+    const absolute = isAbsolute(path) ? normalize(path) : normalize(`${projectRoot}/${path}`);
+    const projectRelative = relative(projectRoot, absolute).split(sep).join("/");
+    if (!isTdkGeneratedPath(projectRelative)) {
+        throw new Error(`Refusing to write outside Flisk's generated-file allowlist: ${projectRelative}`);
+    }
+    let cursor = projectRoot;
+    for (const segment of projectRelative.split("/")) {
+        cursor = normalize(`${cursor}/${segment}`);
+        if (existsSync(cursor) && lstatSync(cursor).isSymbolicLink()) {
+            throw new Error(`Refusing to write through a symbolic link in generated path: ${projectRelative}`);
+        }
+    }
+    return absolute;
+}

package/cli/dist/utils/help-command.js

@@ -0,0 +1,11 @@
+/**
+ * `flisk help <name>` should fail for a name that is not a command or alias, like `flisk <name>` does.
+ * Returns the unknown name, or undefined when the arguments are not `help <name>` or the name is known.
+ */
+export function unknownHelpTarget(args, commands) {
+    const [first, target] = args;
+    if (first !== "help" || !target || target.startsWith("-"))
+        return undefined;
+    const known = commands.some((command) => command.name() === target || command.aliases().includes(target));
+    return known ? undefined : target;
+}

package/cli/dist/utils/host-port-config.js

@@ -0,0 +1,140 @@
+// Copyright (c) 2026 Flisk Landscape contributors
+// SPDX-License-Identifier: MIT
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+import { PROJECT_JSON } from "./constants.js";
+import { createHostPortPlan, isHostPortAvailable, PREFERRED_HOST_PORTS, } from "./host-port-plan.js";
+const CONFIG_PATH = join(".tdk", ".tdk-out", "host-ports.json");
+export function isDockerPortOwnedByProject(dockerPs, projectPrefix, port) {
+    return dockerPs.split("\n").some((line) => {
+        const [name = "", ports = ""] = line.split("|");
+        const containerName = name.toLowerCase();
+        const prefix = projectPrefix.toLowerCase();
+        return ((containerName.startsWith(`${prefix}_`) || containerName.startsWith(`${prefix}-`)) &&
+            ports.includes(`:${port}->`));
+    });
+}
+export function readSavedHostPortPlan(projectRoot) {
+    const path = join(projectRoot, CONFIG_PATH);
+    if (!existsSync(path))
+        return null;
+    try {
+        const value = JSON.parse(readFileSync(path, "utf-8"));
+        if (!value || typeof value !== "object")
+            return null;
+        const plan = value;
+        if (!Number.isInteger(plan.ingressHttp) ||
+            !Number.isInteger(plan.ingressHttps) ||
+            !Number.isInteger(plan.postgres) ||
+            !plan.requested ||
+            !plan.explicit ||
+            !plan.reason)
+            return null;
+        return plan;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeSavedHostPortPlan(projectRoot, plan) {
+    const path = join(projectRoot, CONFIG_PATH);
+    mkdirSync(join(projectRoot, ".tdk", ".tdk-out"), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(plan, null, 2)}\n`, { encoding: "utf-8", mode: 0o600 });
+}
+export function exportHostPortPlan(plan) {
+    process.env.TDK_HTTP_PORT = String(plan.ingressHttp);
+    process.env.TDK_HTTPS_PORT = String(plan.ingressHttps);
+    process.env.TDK_POSTGRES_PORT = String(plan.postgres);
+}
+const COMPOSE_WORKING_DIR_LABEL = "com.docker.compose.project.working_dir";
+/**
+ * True when a container whose Compose working directory is inside this project publishes the port. A container-name prefix is not
+ * enough: tdk_shop_ also matches the containers of a different project called tdk-shop-extra. Compose records the directory each
+ * project was started from, so that identifies the project exactly. Containers without the label never count.
+ */
+export function isPortHeldByProjectContainers(dockerPs, projectRoot, port) {
+    const roots = new Set([resolve(projectRoot)]);
+    try {
+        roots.add(realpathSync(projectRoot));
+    }
+    catch {
+        // The project root is already known to exist; keep the unresolved path.
+    }
+    return dockerPs.split("\n").some((line) => {
+        const [, ports = "", workingDir = ""] = line.split("|");
+        if (!workingDir || !ports.includes(`:${port}->`))
+            return false;
+        return [...roots].some((root) => workingDir === root || workingDir.startsWith(`${root}${sep}`));
+    });
+}
+/**
+ * The HTTP ingress port to probe while a stack is running. getHostPortPlan moves a saved fallback port (8080) back to the
+ * preferred one (80) as soon as that is free, which is right for the next `flisk up` but wrong for a running stack: Traefik is still
+ * bound to the saved port, so probing the planned one finds nothing and every runtime check is skipped. When this project's own
+ * containers hold the saved port, probe that one.
+ */
+export function resolveRuntimeIngressPort(projectRoot, plannedPort, readDockerPs = () => execFileSync("docker", ["ps", "--format", `{{.Names}}|{{.Ports}}|{{.Label "${COMPOSE_WORKING_DIR_LABEL}"}}`], { encoding: "utf-8", timeout: 5000 })) {
+    const saved = readSavedHostPortPlan(projectRoot);
+    if (!saved || saved.ingressHttp === plannedPort)
+        return plannedPort;
+    try {
+        if (isPortHeldByProjectContainers(readDockerPs(), projectRoot, saved.ingressHttp)) {
+            return saved.ingressHttp;
+        }
+    }
+    catch {
+        // Docker unavailable: keep the planned port.
+    }
+    return plannedPort;
+}
+/** Reuse this project's last selection when its ports are still free or held by its own containers. */
+export async function getHostPortPlan(projectRoot, options = {}) {
+    const saved = readSavedHostPortPlan(projectRoot);
+    const hasOverride = ["TDK_HTTP_PORT", "TDK_HTTPS_PORT", "TDK_POSTGRES_PORT"].some((key) => process.env[key]);
+    // Dry-run must not call Docker. A saved plan is the best representation of
+    // the current landscape in that mode; explicit overrides are still planned.
+    if (options.inspectDocker === false && saved && !hasOverride)
+        return saved;
+    let prefix = "";
+    try {
+        const project = JSON.parse(readFileSync(join(projectRoot, ".tdk", PROJECT_JSON), "utf-8"));
+        prefix = String(project?.project?.name ?? "tdk-project")
+            .replace(/-/g, "_")
+            .toLowerCase();
+    }
+    catch {
+        prefix = "tdk_project";
+    }
+    let dockerPs = "";
+    if (options.inspectDocker !== false) {
+        try {
+            dockerPs = execFileSync("docker", ["ps", "--format", "{{.Names}}|{{.Ports}}"], {
+                encoding: "utf-8",
+                timeout: 5000,
+            });
+        }
+        catch {
+            // If Docker is down, reuse only when host binds are still available.
+        }
+    }
+    const ownedByProject = (port) => isDockerPortOwnedByProject(dockerPs, prefix, port);
+    const isPortFree = options.isPortFree ?? isHostPortAvailable;
+    const isAvailable = async (port) => (await isPortFree(port)) || ownedByProject(port);
+    if (saved && !hasOverride) {
+        for (const port of [saved.ingressHttp, saved.ingressHttps, saved.postgres]) {
+            if (!(await isAvailable(port)))
+                return createHostPortPlan({ isAvailable });
+        }
+        // A plan saved on a fallback port (8080) moves back to the preferred one (80)
+        // once that is free, so URLs lose the port without deleting host-ports.json.
+        for (const [key, preferred] of Object.entries(PREFERRED_HOST_PORTS)) {
+            const savedPort = saved[key];
+            if (preferred !== undefined && savedPort !== preferred && (await isAvailable(preferred))) {
+                return createHostPortPlan({ isAvailable });
+            }
+        }
+        return saved;
+    }
+    return createHostPortPlan({ isAvailable });
+}

package/cli/dist/utils/host-port-plan.js

@@ -0,0 +1,100 @@
+// Copyright (c) 2026 Flisk Landscape contributors
+// SPDX-License-Identifier: MIT
+import { createServer } from "node:net";
+import { hasLocalListener } from "./port-listener-probe.js";
+export const DEFAULT_HOST_PORT_RANGES = {
+    ingressHttp: { start: 8080, end: 8180 },
+    ingressHttps: { start: 8443, end: 8543 },
+    postgres: { start: 15432, end: 15532 },
+};
+const ENV_KEYS = {
+    ingressHttp: "TDK_HTTP_PORT",
+    ingressHttps: "TDK_HTTPS_PORT",
+    postgres: "TDK_POSTGRES_PORT",
+};
+const REQUESTED_PORTS = { ingressHttp: 80, ingressHttps: 443, postgres: 5432 };
+// Tried before the fallback range so routed URLs need no port. Postgres keeps
+// its range: a local Postgres on 5432 is common, and no URL carries that port.
+export const PREFERRED_HOST_PORTS = {
+    ingressHttp: REQUESTED_PORTS.ingressHttp,
+    ingressHttps: REQUESTED_PORTS.ingressHttps,
+};
+/**
+ * Whether a failed bind on 127.0.0.1 means the port is still free for Docker. Only macOS
+ * refuses a non-root bind below 1024 while Docker Desktop publishes it through a privileged
+ * helper. Callers check for a listener first, so a bind error here is never another process.
+ */
+export function isPrivilegedBindFree(errorCode, platform) {
+    return errorCode === "EACCES" && platform === "darwin";
+}
+export async function isHostPortAvailable(port) {
+    if (await hasLocalListener(port))
+        return false;
+    return new Promise((resolve) => {
+        const server = createServer();
+        server.once("error", (error) => {
+            resolve(isPrivilegedBindFree(error.code, process.platform));
+        });
+        // Docker Desktop and Windows publish these host ports through IPv4 loopback.
+        // Match that target instead of probing wildcard binds that may differ by OS.
+        server.listen(port, "127.0.0.1", () => server.close(() => resolve(true)));
+    });
+}
+function parsePort(name, value) {
+    const port = Number(value);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new Error(`${name} must be an integer between 1 and 65535 (received ${JSON.stringify(value)})`);
+    }
+    return port;
+}
+export async function createHostPortPlan(options = {}) {
+    const env = options.env ?? process.env;
+    const isAvailable = options.isAvailable ?? isHostPortAvailable;
+    const explicitFlags = { ingressHttp: false, ingressHttps: false, postgres: false };
+    const reasons = { ingressHttp: "", ingressHttps: "", postgres: "" };
+    const selected = { explicit: explicitFlags };
+    const reserved = new Set();
+    for (const key of ["ingressHttp", "ingressHttps", "postgres"]) {
+        const envValue = env[ENV_KEYS[key]];
+        const explicit = envValue !== undefined && envValue.trim() !== "";
+        const range = options.ranges?.[key] ?? DEFAULT_HOST_PORT_RANGES[key];
+        const preferred = PREFERRED_HOST_PORTS[key];
+        const candidates = explicit
+            ? [parsePort(ENV_KEYS[key], envValue)]
+            : [
+                ...(preferred === undefined ? [] : [preferred]),
+                ...Array.from({ length: range.end - range.start + 1 }, (_, index) => range.start + index),
+            ];
+        let chosen;
+        for (const port of candidates) {
+            if (reserved.has(port))
+                continue;
+            if (await isAvailable(port)) {
+                chosen = port;
+                break;
+            }
+            if (explicit) {
+                throw new Error(`${ENV_KEYS[key]}=${port} is already in use. Choose a free host port and retry.`);
+            }
+        }
+        if (chosen === undefined) {
+            throw new Error(`No available host port in ${range.start}-${range.end} for ${key}. Set ${ENV_KEYS[key]} to a free port and retry.`);
+        }
+        reserved.add(chosen);
+        selected[key] = chosen;
+        explicitFlags[key] = explicit;
+        reasons[key] = explicit
+            ? "explicit override"
+            : chosen === preferred
+                ? "requested port is free"
+                : `selected from fallback range ${range.start}-${range.end}`;
+    }
+    return {
+        ...selected,
+        requested: { ...REQUESTED_PORTS },
+        reason: reasons,
+    };
+}
+export function formatHostPortPlan(plan) {
+    return `Host ports: HTTP ${plan.ingressHttp}, HTTPS ${plan.ingressHttps}, Postgres ${plan.postgres}`;
+}

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

@@ -0,0 +1,29 @@
+// Copyright (c) 2026 Flisk Landscape contributors
+// SPDX-License-Identifier: MIT
+import { writeSync } from "node:fs";
+import { createMachineEnvelope } from "./machine-output.js";
+/**
+ * Returns an emitter that writes at most one `{schemaVersion, data, errors}` object to stdout. If the process
+ * exits before anything was emitted (a preflight `process.exit`, Tilt ending early), a failure object is written
+ * so a JSON consumer never sees an empty stdout. Uses writeSync because `process.exit` does not flush async writes.
+ */
+export function createJsonEmitter(failureCode, command) {
+    let emitted = false;
+    const emit = (data, errors = []) => {
+        if (emitted)
+            return;
+        emitted = true;
+        writeSync(1, `${JSON.stringify(createMachineEnvelope(data, errors))}\n`);
+    };
+    process.once("exit", (code) => {
+        emit({ ok: false }, [
+            {
+                code: failureCode,
+                message: code === 0
+                    ? `${command} exited before reporting a result`
+                    : `${command} exited with code ${code}`,
+            },
+        ]);
+    });
+    return emit;
+}

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

@@ -0,0 +1,33 @@
+// Copyright (c) 2026 Flisk Landscape contributors
+// SPDX-License-Identifier: MIT
+import { TdkError } from "./errors.js";
+export const SCHEMA_VERSION = 1;
+export function createMachineEnvelope(data, errors = []) {
+    return { schemaVersion: SCHEMA_VERSION, data, errors };
+}
+export function toMachineError(error) {
+    if (error instanceof TdkError) {
+        return {
+            error: {
+                code: "COMMAND_FAILED",
+                message: error.message,
+                ...(error.suggestions.length > 0 ? { suggestions: error.suggestions } : {}),
+            },
+            exitCode: error.exitCode,
+        };
+    }
+    return {
+        error: {
+            code: "INTERNAL",
+            message: error instanceof Error ? error.message : String(error),
+        },
+        exitCode: 2,
+    };
+}
+/** Keep machine stdout parseable when a command fails before it has data to return. */
+export function writeMachineError(error) {
+    const result = toMachineError(error);
+    console.log(JSON.stringify(createMachineEnvelope(null, [result.error])));
+    console.error(result.error.message);
+    process.exit(result.exitCode);
+}

package/cli/dist/utils/paths.js

@@ -0,0 +1,43 @@
+// Copyright (c) 2026 Flisk Landscape contributors
+// SPDX-License-Identifier: MIT
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { cwd } from "node:process";
+import packageJson from "../../package.json" with { type: "json" };
+import { PROJECT_JSON } from "./constants.js";
+export function findProjectRoot(startDir = cwd()) {
+    let currentDir = resolve(startDir);
+    const root = resolve("/");
+    while (currentDir !== root) {
+        if (existsSync(join(currentDir, ".tdk", PROJECT_JSON))) {
+            return currentDir;
+        }
+        const parentDir = dirname(currentDir);
+        if (parentDir === currentDir) {
+            break;
+        }
+        currentDir = parentDir;
+    }
+    return null;
+}
+let packageCache = null;
+function getPackageInfo() {
+    if (packageCache) {
+        return packageCache;
+    }
+    // Imported JSON is bundled by Bun compile, unlike a runtime fs lookup from $bunfs.
+    const parsed = packageJson;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("Invalid package.json: expected object");
+    }
+    const packageInfo = parsed;
+    packageCache = {
+        name: String(packageInfo.name ?? "@flisk-sh/flisk"),
+        version: String(packageInfo.version ?? "0.0.0"),
+        fullPackage: packageInfo,
+    };
+    return packageCache;
+}
+export function getPackageVersion() {
+    return getPackageInfo().version;
+}