@tdk-landscape/tdk-cli-core 1.3.79 → 1.3.81

package/cli/dist/commands/runtime.js

@@ -0,0 +1,74 @@
+import { statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { Command } from "commander";
+import { findCliAssetRoot, loadTemplate } from "../generator/template-engine.js";
+const REQUIRED_ASSET_PATHS = [
+    { path: "Tiltfile", directory: false },
+    { path: "engine", directory: true },
+    { path: "discovery", directory: true },
+    { path: "specs", directory: true },
+    { path: "ext", directory: true },
+    { path: "cli/templates", directory: true },
+    { path: "shared-platform-engineering/docker-templates", directory: true },
+];
+const REQUIRED_TEMPLATES = [
+    ".tiltignore.hbs",
+    "TILT_RESOURCE_DEFAULTS.star.hbs",
+    "TILT_TECH_STACK.star.hbs",
+    "Tiltfile.hbs",
+    "spec.master.hbs",
+];
+export const runtimeCommand = new Command("runtime")
+    .description("Inspect the packaged TDK runtime assets")
+    .option("--check-assets", "Check bundled engine and template assets")
+    .option("--json", "Print the check result as JSON")
+    .action((options) => {
+    if (!options.checkAssets) {
+        runtimeCommand.outputHelp();
+        process.exitCode = 2;
+        return;
+    }
+    const candidate = findCliAssetRoot();
+    const assetRoot = candidate ? resolve(candidate) : null;
+    const missing = assetRoot
+        ? REQUIRED_ASSET_PATHS.filter(({ path, directory }) => {
+            try {
+                const stats = statSync(join(assetRoot, path));
+                return directory ? !stats.isDirectory() : !stats.isFile();
+            }
+            catch {
+                return true;
+            }
+        }).map(({ path }) => path)
+        : REQUIRED_ASSET_PATHS.map(({ path }) => path);
+    const templateErrors = [];
+    if (assetRoot && missing.length === 0) {
+        for (const template of REQUIRED_TEMPLATES) {
+            try {
+                loadTemplate(template);
+            }
+            catch (error) {
+                templateErrors.push(error instanceof Error ? error.message : `Failed to load template ${template}`);
+            }
+        }
+    }
+    const ok = Boolean(assetRoot) && missing.length === 0 && templateErrors.length === 0;
+    if (options.json) {
+        console.log(JSON.stringify({ ok, assetRoot, missing, templateErrors }));
+    }
+    else if (ok) {
+        console.log(`TDK runtime assets found at ${assetRoot}`);
+    }
+    else {
+        console.error([
+            assetRoot
+                ? `Incomplete TDK runtime assets at ${assetRoot}`
+                : "TDK runtime assets not found",
+            ...missing.map((path) => `Missing: ${path}`),
+            ...templateErrors,
+        ].join("\n"));
+    }
+    if (!ok)
+        process.exitCode = 1;
+});
+//# sourceMappingURL=runtime.js.map

package/cli/dist/commands/status.js

@@ -3,15 +3,17 @@ import { Command } from "commander";
 import { createDiscoveryContext } from "../utils/discovery-context.js";
 import { runCommand } from "../utils/errors.js";
 import { formatCount, showDetail, showStep } from "../utils/formatting.js";
+import { createMachineEnvelope, writeMachineError } from "../utils/machine-output.js";
 import { getTiltfilePath, isTiltAvailable, runTilt } from "../utils/tilt.js";
 export const statusCommand = new Command("status")
     .description("Show status of resources and stacks")
+    .option("--json", "Output a versioned JSON status report", false)
     .option("-v, --verbose", "Show detailed information", false)
     .option("--stacks", "Show stack information (default)", true)
     .option("--resources", "Show all discovered resources", false)
     .option("--tilt", "Show tilt resource status", false)
     .action(async (options) => {
-    await runCommand(async () => {
+    const action = async () => {
         let tiltAvailable = false;
         try {
             tiltAvailable = await isTiltAvailable();
@@ -20,13 +22,59 @@ export const statusCommand = new Command("status")
             // Tilt not available (spawn error)
             tiltAvailable = false;
         }
-        showStep("TDK Status\n");
-        console.log(chalk.bold("Tilt:"), tiltAvailable ? chalk.green("available") : chalk.red("not found"));
-        if (!tiltAvailable) {
-            showDetail("Install Tilt: https://docs.tilt.dev/install.html");
+        if (!options.json) {
+            showStep("TDK Status\n");
+            console.log(chalk.bold("Tilt:"), tiltAvailable ? chalk.green("available") : chalk.red("not found"));
+            if (!tiltAvailable) {
+                showDetail("Install Tilt: https://docs.tilt.dev/install.html");
+            }
+            console.log();
         }
-        console.log();
         const discovery = createDiscoveryContext();
+        let tiltResources = null;
+        let queryError = null;
+        if (options.json && options.tilt && tiltAvailable) {
+            const result = await runTilt("get", ["-f", getTiltfilePath(), "resources", "--output=json"], {
+                inheritStdio: false,
+            });
+            if (result.exitCode === 0) {
+                try {
+                    tiltResources = JSON.parse(result.stdout);
+                }
+                catch (error) {
+                    queryError = `Tilt returned invalid JSON: ${error instanceof Error ? error.message : String(error)}`;
+                }
+            }
+            else {
+                queryError = result.stderr || "Could not retrieve Tilt resource status";
+            }
+        }
+        if (options.json) {
+            const errors = queryError ? [{ code: "TILT_STATUS_UNAVAILABLE", message: queryError }] : [];
+            const data = {
+                tilt: {
+                    available: tiltAvailable,
+                    resourcesQueried: options.tilt && tiltAvailable,
+                    resources: tiltResources,
+                },
+                resources: discovery.resources.map((resource) => ({
+                    name: resource.name,
+                    stack: resource.stack ?? null,
+                    type: resource.type ?? "unknown",
+                    port: resource.port ?? null,
+                })),
+                stacks: discovery.stacks.map((stack) => ({
+                    name: stack.name,
+                    resourceCount: stack.resourceCount,
+                })),
+            };
+            console.log(JSON.stringify(createMachineEnvelope(data, errors)));
+            if (errors.length > 0) {
+                console.error(queryError);
+                process.exit(1);
+            }
+            return;
+        }
         console.log(chalk.bold("Resources:"), `${discovery.resources.length} discovered`);
         console.log(chalk.bold("Stacks:"), `${discovery.stacks.length} defined`);
         if (discovery.stacks.length > 0) {
@@ -66,6 +114,16 @@ export const statusCommand = new Command("status")
         console.log();
         showDetail('Run "tdk list-stacks" to see all stacks.');
         showDetail('Run "tdk up <stack-name>" to start a stack.');
-    });
+    };
+    if (options.json) {
+        try {
+            await action();
+        }
+        catch (error) {
+            writeMachineError(error);
+        }
+        return;
+    }
+    await runCommand(action);
 });
 //# sourceMappingURL=status.js.map

package/cli/dist/commands/up.js

@@ -3,9 +3,10 @@ import chalk from "chalk";
 import { Command } from "commander";
 import { ensureProjectRuntimeAssets } from "../generator/template-engine.js";
 import { handleDryRun } from "../utils/command-helpers.js";
-import { checkHostPorts } from "../utils/doctor-runtime.js";
 import { errorFactories, handleTiltFailure, requireProjectRoot, runCommand, showErrorAndExit, withTiltCheck, } from "../utils/errors.js";
 import { formatCount } from "../utils/formatting.js";
+import { exportHostPortPlan, getHostPortPlan, writeSavedHostPortPlan, } from "../utils/host-port-config.js";
+import { formatHostPortPlan } from "../utils/host-port-plan.js";
 import { findProjectRoot } from "../utils/paths.js";
 import { findAvailablePort } from "../utils/port-assignment.js";
 import { appendHealthPath, resolveSubdomainBases } from "../utils/service-urls.js";
@@ -71,6 +72,9 @@ export const upCommand = new Command("up")
         const projectRoot = options.dryRun
             ? requireProjectRoot()
             : (findProjectRoot() ?? process.cwd());
+        const hostPortPlan = await getHostPortPlan(projectRoot, {
+            inspectDocker: !options.dryRun,
+        });
         if (!options.dryRun) {
             const copiedAssets = ensureProjectRuntimeAssets(projectRoot);
             if (copiedAssets.length > 0 && options.verbose && !options.quiet) {
@@ -106,7 +110,7 @@ export const upCommand = new Command("up")
             serviceNames.forEach((name) => {
                 console.log(chalk.gray(`  - ${name}`));
             });
-            const { appBase, apiBase } = resolveSubdomainBases();
+            const { appBase, apiBase } = resolveSubdomainBases(hostPortPlan.ingressHttp);
             const frontends = servicesToStart.filter((s) => s.config?.appType === "frontend");
             const backends = servicesToStart.filter((s) => s.config?.appType === "backend");
             if (frontends.length > 0) {
@@ -132,17 +136,15 @@ export const upCommand = new Command("up")
         const dryRunCommand = stackName
             ? `tilt up -- --focus=${stackName} ${focusServiceNames.join(" ")}`
             : "tilt up";
+        if (!options.quiet) {
+            console.log(chalk.blue(formatHostPortPlan(hostPortPlan)));
+            console.log(chalk.gray("Override with TDK_HTTP_PORT, TDK_HTTPS_PORT, or TDK_POSTGRES_PORT."));
+        }
         if (handleDryRun(options, "not starting services", dryRunCommand)) {
             return;
         }
-        // Warn rather than block: a stale local Postgres on 5432 makes Tilt fail
-        // halfway through startup with a bind error that's hard to read.
-        const hostPorts = await checkHostPorts();
-        if (!hostPorts.didPass && !options.quiet) {
-            console.log(chalk.yellow(`\n⚠️  ${hostPorts.message}`));
-            if (hostPorts.fix)
-                console.log(chalk.gray(`   ${hostPorts.fix}\n`));
-        }
+        exportHostPortPlan(hostPortPlan);
+        writeSavedHostPortPlan(projectRoot, hostPortPlan);
         const basePort = 10350;
         let port = basePort;
         if (process.env.TILT_PORT) {

package/cli/dist/generator/template-engine.js

@@ -231,7 +231,7 @@ services:
       POSTGRES_PASSWORD: \${DB_PASSWORD}
       POSTGRES_DB: postgres
     ports:
-      - "5432:5432"
+      - "\${TDK_POSTGRES_PORT:-15432}:5432"
     volumes:
       - ${name}_postgres_data:/var/lib/postgresql/data
     networks:
@@ -494,7 +494,7 @@ function findSelfContainedEngineRoot() {
     }
     return null;
 }
-function findCliAssetRoot() {
+export function findCliAssetRoot() {
     let dir = import.meta.dirname || process.cwd();
     for (let i = 0; i < 8; i++) {
         if (fs.existsSync(path.join(dir, "shared-platform-engineering", "docker-templates"))) {
@@ -603,6 +603,16 @@ async function vendorTdkExtension(projectRoot) {
 export function verifyMasterConfigs(projectRoot) {
     const errors = [];
     const warnings = [];
+    const diffs = [];
+    const addDrift = (displayPath, actual, expected) => {
+        if (actual === expected)
+            return;
+        errors.push(`${actual === undefined ? "Missing file" : "Out of sync"}: ${displayPath} (run 'tdk config regenerate')`);
+        diffs.push({
+            file: displayPath,
+            diff: createUnifiedDiff(displayPath, actual ?? "", expected),
+        });
+    };
     const projectConfig = readProjectConfig(projectRoot);
     const engine = new TemplateEngine();
     const expectedFiles = engine.generateAll(projectConfig);
@@ -610,22 +620,10 @@ export function verifyMasterConfigs(projectRoot) {
     for (const filename of ALL_GENERATED_FILES) {
         const expectedContent = expectedFiles[filename];
         const filePath = path.join(outputDir, filename);
-        if (!fs.existsSync(filePath)) {
-            errors.push(`Missing file: .tdk/.tdk-out/${filename}`);
-            continue;
-        }
-        const actualContent = fs.readFileSync(filePath, "utf-8");
-        if (actualContent !== expectedContent) {
-            errors.push(`Out of sync: .tdk/.tdk-out/${filename} (run 'tdk config regenerate')`);
-        }
+        addDrift(`.tdk/.tdk-out/${filename}`, fs.existsSync(filePath) ? fs.readFileSync(filePath, "utf-8") : undefined, expectedContent);
     }
     const rootTiltIgnore = path.join(projectRoot, ".tiltignore");
-    if (!fs.existsSync(rootTiltIgnore)) {
-        errors.push("Missing file: .tiltignore");
-    }
-    else if (fs.readFileSync(rootTiltIgnore, "utf-8") !== expectedFiles[".tiltignore"]) {
-        errors.push("Out of sync: .tiltignore (run 'tdk config regenerate')");
-    }
+    addDrift(".tiltignore", fs.existsSync(rootTiltIgnore) ? fs.readFileSync(rootTiltIgnore, "utf-8") : undefined, expectedFiles[".tiltignore"]);
     for (const manifestPath of discoverServiceManifestPaths(projectRoot)) {
         const displayPath = path.relative(projectRoot, manifestPath).split(path.sep).join("/");
         const validation = validateServiceManifestFile(manifestPath, displayPath);
@@ -633,7 +631,21 @@ export function verifyMasterConfigs(projectRoot) {
         warnings.push(...validation.warnings);
         errors.push(...verifyGeneratedResourceFiles(projectRoot, manifestPath));
     }
-    return { valid: errors.length === 0, errors, warnings };
+    return { valid: errors.length === 0, errors, warnings, diffs };
+}
+function createUnifiedDiff(file, actual, expected) {
+    const oldLines = actual.replace(/\n$/, "").split("\n");
+    const newLines = expected.replace(/\n$/, "").split("\n");
+    const lines = [
+        `--- a/${file}`,
+        `+++ b/${file}`,
+        `@@ -1,${oldLines.length} +1,${newLines.length} @@`,
+    ];
+    for (const line of oldLines)
+        lines.push(`-${line}`);
+    for (const line of newLines)
+        lines.push(`+${line}`);
+    return lines.join("\n");
 }
 function verifyGeneratedResourceFiles(projectRoot, serviceJsonPath) {
     const serviceDir = path.dirname(serviceJsonPath);

package/cli/dist/utils/cold-preflight.js

@@ -2,8 +2,8 @@ import { execFileSync } from "node:child_process";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { checkDockerCompose, checkDockerRuntime, checkDockerVersions, checkTilt, } from "../commands/doctor.js";
-import { checkHostPorts, checkIngressPorts } from "./doctor-runtime.js";
 import { checkNatsBroker } from "./doctor-wiring.js";
+import { getHostPortPlan } from "./host-port-config.js";
 import { findProjectRoot } from "./paths.js";
 import { discoverResourcesFromRoot } from "./services.js";
 import { findOnPath } from "./which.js";
@@ -99,26 +99,20 @@ export async function runColdPreflight(opts = {}) {
         message: bun ? "Bun 1.2+ is available on PATH" : "Bun 1.2+ not found on PATH",
         fix: bun ? undefined : "curl -fsSL https://bun.sh/install | bash",
     });
-    const [hostPorts, ingressPorts] = await Promise.all([
-        safeCheck("ports", checkHostPorts, "Could not check required host ports"),
-        safeCheck("ports", checkIngressPorts, "Could not check ingress ports"),
-    ]);
-    if (!hostPorts.ok || !ingressPorts.ok) {
-        const port5432 = !hostPorts.ok && /(?:^|\n)\s*5432\s*\(/.test(hostPorts.message);
-        const messages = [
-            !hostPorts.ok
-                ? port5432
-                    ? "Port 5432 is taken (usually local Postgres). Stop it or TDK cannot bind the bundled Postgres."
-                    : hostPorts.message
-                : undefined,
-            !ingressPorts.ok ? ingressPorts.message : undefined,
-        ].filter((message) => Boolean(message));
-        const fixes = [hostPorts.fix, ingressPorts.fix].filter((fix) => Boolean(fix));
+    try {
+        const plan = await getHostPortPlan(projectRoot ?? cwd);
+        items.push({
+            id: "ports",
+            ok: true,
+            message: `HTTP ${plan.ingressHttp}, HTTPS ${plan.ingressHttps}, Postgres ${plan.postgres}`,
+        });
+    }
+    catch (error) {
         items.push({
             id: "ports",
             ok: false,
-            message: messages.join("\n"),
-            fix: fixes.join(" "),
+            message: error instanceof Error ? error.message : String(error),
+            fix: "Set TDK_HTTP_PORT, TDK_HTTPS_PORT, or TDK_POSTGRES_PORT to available host ports.",
         });
     }
     if (projectRoot) {

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

@@ -0,0 +1,64 @@
+/** Wait for concurrent probes to finish even if one throws, so they can release resources. */
+export async function collectDoctorChecks(machineChecks, projectChecks) {
+    const checks = [];
+    const errors = [];
+    const append = (result) => {
+        if (result.status === "fulfilled")
+            checks.push(result.value);
+        else
+            errors.push({
+                code: "INTERNAL",
+                message: result.reason instanceof Error ? result.reason.message : String(result.reason),
+            });
+    };
+    for (const result of await Promise.allSettled(machineChecks.map((check) => Promise.resolve().then(check)))) {
+        append(result);
+    }
+    for (const check of projectChecks) {
+        for (const result of await Promise.allSettled([Promise.resolve().then(check)]))
+            append(result);
+    }
+    return { checks, errors };
+}
+/** Produce the same readiness decision for human and machine consumers. */
+export function createDoctorReport(checks, inProject, errors = [], portPlan) {
+    return {
+        schemaVersion: 1,
+        data: {
+            ready: errors.length === 0 &&
+                checks.every((check) => check.didPass || check.isSkipped || check.isWarning),
+            inProject,
+            checks,
+            ...(portPlan !== undefined
+                ? {
+                    ports: {
+                        http: {
+                            requested: portPlan?.requested.ingressHttp ?? 80,
+                            chosen: portPlan?.ingressHttp ?? null,
+                            explicit: portPlan?.explicit.ingressHttp ?? Boolean(process.env.TDK_HTTP_PORT),
+                            reason: portPlan?.reason.ingressHttp ?? "port planning failed",
+                        },
+                        https: {
+                            requested: portPlan?.requested.ingressHttps ?? 443,
+                            chosen: portPlan?.ingressHttps ?? null,
+                            explicit: portPlan?.explicit.ingressHttps ?? Boolean(process.env.TDK_HTTPS_PORT),
+                            reason: portPlan?.reason.ingressHttps ?? "port planning failed",
+                        },
+                        postgres: {
+                            requested: portPlan?.requested.postgres ?? 5432,
+                            chosen: portPlan?.postgres ?? null,
+                            explicit: portPlan?.explicit.postgres ?? Boolean(process.env.TDK_POSTGRES_PORT),
+                            reason: portPlan?.reason.postgres ?? "port planning failed",
+                        },
+                    },
+                }
+                : {}),
+        },
+        errors,
+    };
+}
+/** 0: ready (warnings permitted), 1: blocking findings, 2: usage/internal failure. */
+export function getDoctorExitCode(report) {
+    return report.errors.length > 0 ? 2 : report.data.ready ? 0 : 1;
+}
+//# sourceMappingURL=doctor-report.js.map

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

@@ -305,7 +305,7 @@ export function checkPrivateNpmRegistry(exec = execSync, projectRoot = findProje
  * This is the exact failure mode that leaves apps never scheduled while doctor
  * previously reported "Environment ready".
  */
-export function checkIngressPorts(exec = execSync, projectName = getProjectName()) {
+export function checkIngressPorts(exec = execSync, projectName = getProjectName(), ports = INGRESS_PORTS) {
     const projectPrefix = toComposeProjectPrefix(projectName);
     let dockerPs = "";
     try {
@@ -323,7 +323,7 @@ export function checkIngressPorts(exec = execSync, projectName = getProjectName(
             message: "Docker not available - skipped ingress port check",
         };
     }
-    const holders = parsePublishedPortHolders(dockerPs, INGRESS_PORTS);
+    const holders = parsePublishedPortHolders(dockerPs, ports);
     const foreign = findForeignIngressHolders(holders, projectPrefix);
     if (foreign.length === 0) {
         const own = holders.filter((holder) => isOwnIngressContainer(holder.name, projectPrefix));
@@ -331,7 +331,7 @@ export function checkIngressPorts(exec = execSync, projectName = getProjectName(
             return {
                 name: "Ingress Ports",
                 didPass: true,
-                message: `Ingress ports ${INGRESS_PORTS.join("/")} held by this project's Traefik (${own
+                message: `Ingress ports ${ports.join("/")} held by this project's Traefik (${own
                     .map((h) => h.name)
                     .join(", ")})`,
             };
@@ -339,7 +339,7 @@ export function checkIngressPorts(exec = execSync, projectName = getProjectName(
         return {
             name: "Ingress Ports",
             didPass: true,
-            message: `Ingress ports ${INGRESS_PORTS.join("/")} are free for Traefik`,
+            message: `Ingress ports ${ports.join("/")} are free for Traefik`,
         };
     }
     const details = foreign

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

@@ -0,0 +1,88 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { createHostPortPlan, isHostPortAvailable } 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}-`)) &&
+            new RegExp(`:${port}->`).test(ports));
+    });
+}
+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);
+}
+/** 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 isAvailable = async (port) => (await isHostPortAvailable(port)) || ownedByProject(port);
+    if (saved && !hasOverride) {
+        for (const port of [saved.ingressHttp, saved.ingressHttps, saved.postgres]) {
+            if (!(await isAvailable(port)))
+                return createHostPortPlan({ isAvailable });
+        }
+        return saved;
+    }
+    return createHostPortPlan({ isAvailable });
+}
+//# sourceMappingURL=host-port-config.js.map

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

@@ -0,0 +1,74 @@
+import { createServer } from "node:net";
+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 };
+export async function isHostPortAvailable(port) {
+    return new Promise((resolve) => {
+        const server = createServer();
+        server.once("error", () => resolve(false));
+        // 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 candidates = explicit
+            ? [parsePort(ENV_KEYS[key], envValue)]
+            : 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"
+            : `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}`;
+}
+//# sourceMappingURL=host-port-plan.js.map

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

@@ -0,0 +1,24 @@
+import { TdkError } from "./errors.js";
+export function createMachineEnvelope(data, errors = []) {
+    return { schemaVersion: 1, data, errors };
+}
+export function toMachineError(error) {
+    if (error instanceof TdkError) {
+        return { error: { code: "COMMAND_FAILED", message: error.message }, exitCode: 1 };
+    }
+    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);
+}
+//# sourceMappingURL=machine-output.js.map

package/cli/dist/utils/service-manifest.js

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
 export const SERVICE_MANIFEST_SCHEMA_VERSION = 1;
+export const SERVICE_MANIFEST_SCHEMA_URL = "https://tdk-landscape.github.io/schema.service.json";
 const KNOWN_SERVICE_FIELDS = new Set([
     "$schema",
     "apiBasePath",