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

package/cli/dist/commands/networks.js

@@ -6,6 +6,7 @@ import { getStackEmoji } from "../utils/constants.js";
 import { createDiscoveryContext } from "../utils/discovery-context.js";
 import { logVerbose, requireProjectRoot } from "../utils/errors.js";
 import { colorizeByStatus, DEFAULT_BOX_WIDTH, formatBoxLine, formatPadded, getStatusIcon, printBoxedHeader, } from "../utils/formatting.js";
+import { createMachineEnvelope, writeMachineError } from "../utils/machine-output.js";
 import { findProjectRoot } from "../utils/paths.js";
 import { checkPortStatus } from "../utils/port-assignment.js";
 import { isValidPort, sanitizeForShell } from "../utils/validation.js";
@@ -156,118 +157,137 @@ export const networksCommand = new Command("networks")
     .alias("urls")
     .alias("traefik")
     .option("-s, --stack <stack>", "Filter by stack name")
-    .option("--json", "Output as JSON")
+    .option("--json", "Output a versioned JSON response")
+    .option("--json-legacy", "Output the legacy JSON array (deprecated)")
     .option("--raw", "Output raw URLs only")
     .action(async (options) => {
-    const projectRoot = requireProjectRoot();
-    const discovery = createDiscoveryContext();
-    const baseDomain = determineDefaultDomain();
-    const bareDomain = baseDomain.replace(/^(app|api)\./, "");
-    const appDomain = `app.${bareDomain}`;
-    const apiDomain = `api.${bareDomain}`;
-    const services = discovery.resources;
-    const servicesWithUrls = await Promise.all(services
-        .filter((s) => typeof s.config?.basePath === "string")
-        .map(async (s) => {
-        const basePath = s.config.basePath.replace(/^\//, "");
-        const isBackend = s.config?.appType === "backend";
-        const host = isBackend ? apiDomain : appDomain;
-        const url = `http://${host}/${basePath}`;
-        const port = s.config.port;
-        const status = await checkServiceStatus(s.name, port, url);
-        return {
-            name: s.name,
-            stack: s.stack,
-            basePath: s.config.basePath,
-            url,
-            ...(process.platform === "win32"
-                ? { loopbackUrl: `http://127.0.0.1:80/${basePath}`.replace(/\/$/, "") }
-                : {}),
-            port,
-            status,
-        };
-    }));
-    const filteredServices = options.stack
-        ? servicesWithUrls.filter((s) => s.stack === options.stack)
-        : servicesWithUrls;
-    if (filteredServices.length === 0) {
-        if (options.stack) {
-            console.log(chalk.yellow(`⚠️ No services with basePath found in stack "${options.stack}"`));
+    const action = async () => {
+        const projectRoot = options.json || options.jsonLegacy ? findProjectRoot() : requireProjectRoot();
+        if (!projectRoot) {
+            throw new Error("Could not find project root (no .tdk/project.json found)");
         }
-        else {
-            console.log(chalk.yellow("⚠️ No services with basePath found"));
-            console.log(chalk.gray("\nAdd basePath to your service.json:"));
-            console.log(chalk.gray('  "basePath": "/my-service"'));
+        const discovery = createDiscoveryContext();
+        const baseDomain = determineDefaultDomain();
+        const bareDomain = baseDomain.replace(/^(app|api)\./, "");
+        const appDomain = `app.${bareDomain}`;
+        const apiDomain = `api.${bareDomain}`;
+        const services = discovery.resources;
+        const servicesWithUrls = await Promise.all(services
+            .filter((s) => typeof s.config?.basePath === "string")
+            .map(async (s) => {
+            const basePath = s.config.basePath.replace(/^\//, "");
+            const isBackend = s.config?.appType === "backend";
+            const host = isBackend ? apiDomain : appDomain;
+            const url = `http://${host}/${basePath}`;
+            const port = s.config.port;
+            const status = await checkServiceStatus(s.name, port, url);
+            return {
+                name: s.name,
+                stack: s.stack,
+                basePath: s.config.basePath,
+                url,
+                ...(process.platform === "win32"
+                    ? { loopbackUrl: `http://127.0.0.1:80/${basePath}`.replace(/\/$/, "") }
+                    : {}),
+                port,
+                status,
+            };
+        }));
+        const filteredServices = options.stack
+            ? servicesWithUrls.filter((s) => s.stack === options.stack)
+            : servicesWithUrls;
+        if (options.json || options.jsonLegacy) {
+            const output = options.jsonLegacy
+                ? filteredServices
+                : createMachineEnvelope({ services: filteredServices });
+            console.log(JSON.stringify(output, null, 2));
+            return;
         }
-        process.exit(0);
-    }
-    if (options.json) {
-        console.log(JSON.stringify(filteredServices, null, 2));
-        process.exit(0);
-    }
-    if (options.raw) {
-        for (const service of filteredServices) {
-            console.log(service.url);
-            if (service.loopbackUrl)
-                console.log(service.loopbackUrl);
+        if (filteredServices.length === 0) {
+            if (options.stack) {
+                console.log(chalk.yellow(`⚠️ No services with basePath found in stack "${options.stack}"`));
+            }
+            else {
+                console.log(chalk.yellow("⚠️ No services with basePath found"));
+                console.log(chalk.gray("\nAdd basePath to your service.json:"));
+                console.log(chalk.gray('  "basePath": "/my-service"'));
+            }
+            process.exit(0);
         }
-        process.exit(0);
-    }
-    printBoxedHeader("🌐  TRAEFIK NETWORKS", `Domain: http://${baseDomain}`, DEFAULT_BOX_WIDTH);
-    // Group services by stack using discovery context's stack names for consistent ordering
-    const stacks = new Map();
-    for (const stackName of discovery.stackNames) {
-        const stackServices = filteredServices.filter((s) => s.stack === stackName);
-        if (stackServices.length > 0) {
-            stacks.set(stackName, stackServices);
+        if (options.raw) {
+            for (const service of filteredServices) {
+                console.log(service.url);
+                if (service.loopbackUrl)
+                    console.log(service.loopbackUrl);
+            }
+            process.exit(0);
         }
-    }
-    // Add unstacked services to 'default' group
-    const unstackedServices = filteredServices.filter((s) => !s.stack);
-    if (unstackedServices.length > 0) {
-        stacks.set("default", unstackedServices);
-    }
-    let isFirstStack = true;
-    for (const [stackName, stackServices] of stacks) {
-        if (!isFirstStack) {
+        printBoxedHeader("🌐  TRAEFIK NETWORKS", `Domain: http://${baseDomain}`, DEFAULT_BOX_WIDTH);
+        // Group services by stack using discovery context's stack names for consistent ordering
+        const stacks = new Map();
+        for (const stackName of discovery.stackNames) {
+            const stackServices = filteredServices.filter((s) => s.stack === stackName);
+            if (stackServices.length > 0) {
+                stacks.set(stackName, stackServices);
+            }
+        }
+        // Add unstacked services to 'default' group
+        const unstackedServices = filteredServices.filter((s) => !s.stack);
+        if (unstackedServices.length > 0) {
+            stacks.set("default", unstackedServices);
+        }
+        let isFirstStack = true;
+        for (const [stackName, stackServices] of stacks) {
+            if (!isFirstStack) {
+                console.log();
+            }
+            isFirstStack = false;
+            const emoji = getStackEmoji(stackName);
+            const stackTitle = `${emoji}  ${stackName.toUpperCase()} STACK`;
             console.log();
+            console.log(chalk.bold.white(stackTitle));
+            console.log(chalk.gray(formatBoxLine("━", DEFAULT_BOX_WIDTH - 4)));
+            for (const service of stackServices) {
+                const statusSymbol = getStatusIcon(service.status);
+                const statusEmoji = colorizeByStatus(statusSymbol, service.status);
+                const namePart = formatPadded(service.name, 22);
+                const urlPart = service.status === "running"
+                    ? chalk.cyan.underline(service.url)
+                    : chalk.gray(service.url); // Gray out URL if stopped
+                const statusLabel = service.status !== "running" ? chalk.gray(` [${service.status}]`) : "";
+                console.log(`  ${statusEmoji} ${chalk.white(namePart)}  ${urlPart}${statusLabel}`);
+                if (service.loopbackUrl) {
+                    console.log(`     ${chalk.gray(`Loopback: ${service.loopbackUrl} (Host: ${new URL(service.url).hostname})`)}`);
+                }
+            }
         }
-        isFirstStack = false;
-        const emoji = getStackEmoji(stackName);
-        const stackTitle = `${emoji}  ${stackName.toUpperCase()} STACK`;
         console.log();
-        console.log(chalk.bold.white(stackTitle));
-        console.log(chalk.gray(formatBoxLine("━", DEFAULT_BOX_WIDTH - 4)));
-        for (const service of stackServices) {
-            const statusSymbol = getStatusIcon(service.status);
-            const statusEmoji = colorizeByStatus(statusSymbol, service.status);
-            const namePart = formatPadded(service.name, 22);
-            const urlPart = service.status === "running"
-                ? chalk.cyan.underline(service.url)
-                : chalk.gray(service.url); // Gray out URL if stopped
-            const statusLabel = service.status !== "running" ? chalk.gray(` [${service.status}]`) : "";
-            console.log(`  ${statusEmoji} ${chalk.white(namePart)}  ${urlPart}${statusLabel}`);
-            if (service.loopbackUrl) {
-                console.log(`     ${chalk.gray(`Loopback: ${service.loopbackUrl} (Host: ${new URL(service.url).hostname})`)}`);
-            }
+        console.log(chalk.gray(formatBoxLine("─", DEFAULT_BOX_WIDTH - 2)));
+        console.log(chalk.gray("🖱️  Click any URL above to open in browser"));
+        console.log(chalk.gray("📊 Status: ") +
+            chalk.green("✓ Running") +
+            " | " +
+            chalk.red("✗ Stopped") +
+            " | " +
+            chalk.gray("? Unknown"));
+        if (baseDomain === "localhost") {
+            console.log();
+            const projectConfig = readProjectConfig(projectRoot);
+            const projectName = projectConfig.project.name;
+            console.log(chalk.yellow("💡 Tip: Set custom domain with:"));
+            console.log(chalk.cyan(`   export TDK_PUBLIC_HOST=${projectName}.localhost`));
         }
-    }
-    console.log();
-    console.log(chalk.gray(formatBoxLine("─", DEFAULT_BOX_WIDTH - 2)));
-    console.log(chalk.gray("🖱️  Click any URL above to open in browser"));
-    console.log(chalk.gray("📊 Status: ") +
-        chalk.green("✓ Running") +
-        " | " +
-        chalk.red("✗ Stopped") +
-        " | " +
-        chalk.gray("? Unknown"));
-    if (baseDomain === "localhost") {
         console.log();
-        const projectConfig = readProjectConfig(projectRoot);
-        const projectName = projectConfig.project.name;
-        console.log(chalk.yellow("💡 Tip: Set custom domain with:"));
-        console.log(chalk.cyan(`   export TDK_PUBLIC_HOST=${projectName}.localhost`));
+    };
+    if (options.json || options.jsonLegacy) {
+        try {
+            await action();
+        }
+        catch (error) {
+            writeMachineError(error);
+        }
+        return;
     }
-    console.log();
+    await action();
 });
 //# sourceMappingURL=networks.js.map

package/cli/dist/commands/resource.js

@@ -13,7 +13,7 @@ import { showCommandHeader } from "../utils/formatting.js";
 import { assignPort } from "../utils/port-assignment.js";
 import { promptSelect, promptText } from "../utils/prompt.js";
 import { getDefaultFeaturesForResourceType } from "../utils/resource-features.js";
-import { SERVICE_MANIFEST_SCHEMA_VERSION } from "../utils/service-manifest.js";
+import { SERVICE_MANIFEST_SCHEMA_URL, SERVICE_MANIFEST_SCHEMA_VERSION, } from "../utils/service-manifest.js";
 import { discoverResources } from "../utils/services.js";
 import { createKebabCaseValidator, isPathSafe, validateResourceName } from "../utils/validation.js";
 export const BASE_TEMPLATE = {
@@ -77,6 +77,7 @@ export function createServiceJson(name, type, stack, port, extraFeatures = [], f
     }
     return {
         ...base,
+        $schema: SERVICE_MANIFEST_SCHEMA_URL,
         schemaVersion: SERVICE_MANIFEST_SCHEMA_VERSION,
         appName: name,
         appType: type,
@@ -494,6 +495,7 @@ export const resourceCommand = new Command("resource")
             // Update with new values while preserving existing fields
             const updatedServiceJson = {
                 ...existingServiceJson,
+                $schema: existingServiceJson.$schema ?? SERVICE_MANIFEST_SCHEMA_URL,
                 schemaVersion: existingServiceJson.schemaVersion ?? SERVICE_MANIFEST_SCHEMA_VERSION,
                 appName: resourceName,
                 appType: resourceType === "sdk" ? "sdk" : existingServiceJson.appType || resourceType,
@@ -525,6 +527,7 @@ export const resourceCommand = new Command("resource")
             mkdirSync(fullPath, { recursive: true });
             // Create service.json
             const byoServiceJson = {
+                $schema: SERVICE_MANIFEST_SCHEMA_URL,
                 schemaVersion: SERVICE_MANIFEST_SCHEMA_VERSION,
                 appName: resourceName,
                 appType: "bring-your-own",

package/cli/dist/commands/resources.js

@@ -3,35 +3,56 @@ import { Command } from "commander";
 import { createDiscoveryContext } from "../utils/discovery-context.js";
 import { requireProjectRoot, runCommand } from "../utils/errors.js";
 import { formatCount, showAllSatisfyCondition, showDetail, showEmptyState, showStep, } from "../utils/formatting.js";
+import { createMachineEnvelope, writeMachineError } from "../utils/machine-output.js";
+import { findProjectRoot } from "../utils/paths.js";
 export const resourcesCommand = new Command("resources")
     .description("List all resources (services) in the project")
     .option("-v, --verbose", "Show detailed information about each resource", false)
     .option("-s, --stack <stack>", "Filter resources by stack name")
     .option("--no-stack", "Show only resources without a stack")
     .option("--ports", "Show port assignments", false)
+    .option("--json", "Output a versioned JSON resource report", false)
     .action(async (options) => {
-    await runCommand(async () => {
-        requireProjectRoot();
-        const discovery = createDiscoveryContext();
-        if (discovery.resources.length === 0) {
-            showEmptyState("resources");
-            return;
+    const action = async () => {
+        if (options.json) {
+            if (!findProjectRoot()) {
+                writeMachineError(new Error("Could not find project root (no .tdk/project.json found)"));
+            }
         }
+        else {
+            requireProjectRoot();
+        }
+        const discovery = createDiscoveryContext();
         let resources = discovery.resources;
         if (options.stack) {
             resources = discovery.resourcesByStack.get(options.stack) || [];
-            if (resources.length === 0) {
+            if (resources.length === 0 && !options.json) {
                 showEmptyState("stack-services", ` in stack "${options.stack}"`);
                 return;
             }
         }
         if (options.noStack) {
             resources = discovery.unassignedResources;
-            if (resources.length === 0) {
+            if (resources.length === 0 && !options.json) {
                 showAllSatisfyCondition("resources", "assigned to a stack");
                 return;
             }
         }
+        if (options.json) {
+            const data = resources.map((resource) => ({
+                name: resource.name,
+                stack: resource.stack ?? null,
+                type: resource.config?.appType ?? resource.type ?? "unknown",
+                port: resource.port ?? null,
+                path: resource.configPath,
+            }));
+            console.log(JSON.stringify(createMachineEnvelope({ resources: data })));
+            return;
+        }
+        if (resources.length === 0) {
+            showEmptyState(options.stack ? "stack-services" : "resources", options.stack ? ` in stack "${options.stack}"` : "");
+            return;
+        }
         showStep(`Found ${formatCount(resources.length, "resource")}:\n`);
         if (options.verbose || options.ports) {
             for (const resource of resources) {
@@ -68,6 +89,16 @@ export const resourcesCommand = new Command("resources")
             console.log(chalk.yellow(`\n${formatCount(withoutStackCount, "resource")} not assigned to any stack.`));
             showDetail('Run "tdk resources --no-stack" to see them, or "tdk stack" to assign them.');
         }
-    });
+    };
+    if (options.json) {
+        try {
+            await action();
+        }
+        catch (error) {
+            writeMachineError(error);
+        }
+        return;
+    }
+    await runCommand(action);
 });
 //# sourceMappingURL=resources.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/generator/template-engine.js

@@ -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/doctor-report.js

@@ -0,0 +1,40 @@
+/** 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 = []) {
+    return {
+        schemaVersion: 1,
+        data: {
+            ready: errors.length === 0 &&
+                checks.every((check) => check.didPass || check.isSkipped || check.isWarning),
+            inProject,
+            checks,
+        },
+        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/host-port-plan.js

@@ -0,0 +1,62 @@
+import { createServer } from "node:net";
+const DEFAULT_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",
+};
+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 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_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;
+    }
+    return selected;
+}
+//# 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