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

package/CHANGELOG.md

@@ -4,6 +4,8 @@ Notable changes to the `tdk` CLI. Versions match [npm](https://www.npmjs.com/pac
 
 ## Unreleased
 
+## 1.3.80 (2026-09-30)
+
 - Add `tdk doctor --json` with schema-versioned readiness, checks, and structured errors; diagnostics remain on stderr.
 - Stabilize doctor exits: 0 ready, 1 blocking findings, 2 invalid arguments/internal check failures. Invalid `--ping-timeout` now exits 2 instead of 1 and rejects fractional/unit-suffixed values.
 - Add versioned `--json` envelopes to `tdk status`, `tdk resources`, and `tdk networks`; existing `networks --json` array consumers can migrate with `--json-legacy` through CLI 1.4.x. The compatibility flag is scheduled for removal in 1.5.0.

package/README.md

@@ -2,6 +2,8 @@
 
 TDK runs many services on your laptop with Docker + Tilt. Helm still deploys the cluster.
 
+[Website](https://tdk-landscape.github.io/tdk-website/) · [Quickstart](https://tdk-landscape.github.io/tdk-website/docs/quickstart/) · [Examples](https://tdk-landscape.github.io/tdk-website/docs/examples/) · [Awesome TDK](https://github.com/tdk-landscape/awesome-tdk-framework) · [Demo](https://tdk-landscape.github.io/tdk-demo-animation/) · [Report a bug](https://github.com/tdk-landscape/tdk-cli-core/issues)
+
 [![npm version](https://img.shields.io/npm/v/@tdk-landscape/tdk-cli-core.svg?style=flat&color=blue)](https://www.npmjs.com/package/@tdk-landscape/tdk-cli-core)
 [![CI](https://github.com/tdk-landscape/tdk-cli-core/actions/workflows/ci.yml/badge.svg)](https://github.com/tdk-landscape/tdk-cli-core/actions/workflows/ci.yml)
 [![Quickstart E2E](https://github.com/tdk-landscape/tdk-cli-core/actions/workflows/quickstart-e2e.yml/badge.svg)](https://github.com/tdk-landscape/tdk-cli-core/actions/workflows/quickstart-e2e.yml)
@@ -33,6 +35,21 @@ tdk networks
 
 `tdk up shop --dry-run` previews selected local services and URLs before starting containers. The default starter is Bun/TypeScript; TDK's core role is running local containers through Docker + Tilt, not providing a Node.js application framework. See the [one-backend example](examples/one-backend/README.md).
 
+![TDK scaffolding a backend and a frontend, then listing the stack](docs/demo.svg)
+
+*Scaffolding a backend and frontend, then listing the stack.*
+
+## Why TDK?
+
+| | Compose | Local Kubernetes (kind, minikube) | Plain Tilt | **TDK** |
+|---|---|---|---|---|
+| Scaffold a service in one command | ❌ | ❌ | ❌ | ✅ `tdk resource` |
+| Hot reload on file change | ⚠️ `compose watch` config | ⚠️ extra tooling | ✅ | ✅ |
+| Health-checked startup order | ✅ | ✅ | ⚠️ configure it yourself | ✅ |
+| Needs a cluster | No | Yes | Optional | **No** |
+
+100 generated health-check services reached healthy in 112 s, using about 1.6 GiB in service-container memory on a 16 GB machine. [Details and caveats](docs/scale-bench.md).
+
 ## When not to use TDK
 
 - Your existing Compose or Tilt workflow already gives you a working local environment.
@@ -52,7 +69,9 @@ tdk networks
 
 ## Requirements and support
 
-For the local runtime, install Docker (Desktop, OrbStack, or Colima; Engine 25+, Compose 2.20+) and [Tilt](https://docs.tilt.dev/install.html). Bun 1.2+ is used by the default generated services. Ports 80, 443, and 5432 must be free. TDK supports macOS, Linux, and Windows through WSL2 Ubuntu; native Windows supports CLI inspection only. Run `tdk doctor` to check local readiness. See [WSL2 setup](docs/wsl2.md).
+For the local runtime, install Docker (Desktop, OrbStack, or Colima; Engine 25+, Compose 2.20+) and [Tilt](https://docs.tilt.dev/install.html). Bun 1.2+ is used by the default generated services. TDK selects host ports from bounded fallback ranges for HTTP, HTTPS, and Postgres; set `TDK_HTTP_PORT`, `TDK_HTTPS_PORT`, or `TDK_POSTGRES_PORT` to override them. TDK supports macOS, Linux, and Windows through WSL2 Ubuntu; native Windows supports CLI inspection only. Run `tdk doctor` to check local readiness. See [WSL2 setup](docs/wsl2.md).
+
+**Ecosystem map:** examples, articles, related tools, and notes live in [awesome-tdk-framework](https://github.com/tdk-landscape/awesome-tdk-framework). Star this repo (`tdk-cli-core`) if the CLI is what you run; use the awesome list to browse the rest.
 
 ## Contributing and license
 

package/cli/dist/cli.js

@@ -13,6 +13,7 @@ import { projectCommand } from "./commands/project.js";
 import { projectsCommand } from "./commands/projects.js";
 import { resourceCommand } from "./commands/resource.js";
 import { resourcesCommand } from "./commands/resources.js";
+import { runtimeCommand } from "./commands/runtime.js";
 import { stackCommand } from "./commands/stack.js";
 import { stacksCommand } from "./commands/stacks.js";
 import { statusCommand } from "./commands/status.js";
@@ -46,6 +47,7 @@ program.addCommand(ejectCommand);
 program.addCommand(statusCommand);
 program.addCommand(stackCommand);
 program.addCommand(resourceCommand);
+program.addCommand(runtimeCommand);
 program.addCommand(projectCommand);
 program.addCommand(configCommand);
 program.addCommand(uiCommand);

package/cli/dist/commands/completion.js

@@ -11,10 +11,14 @@ _tdk_completions() {
     prev="\${COMP_WORDS[COMP_CWORD-1]}"
     
     # Main commands
-    local commands="project projects stack stacks resource resources up down status ui doctor version completion help upgrade"
+    local commands="project projects stack stacks resource resources up down status ui doctor runtime version completion help upgrade"
     
     # Options for specific commands
     case "\${prev}" in
+        runtime)
+            COMPREPLY=( $(compgen -W "--check-assets --json" -- \${cur}) )
+            return 0
+            ;;
         tdk)
             COMPREPLY=( $(compgen -W "\${commands}" -- \${cur}) )
             return 0
@@ -108,6 +112,11 @@ _tdk() {
             _arguments 
                 '--fix[Attempt to fix issues]'
             ;;
+        runtime)
+            _arguments
+                '--check-assets[Check bundled engine and template assets]'
+                '--json[Print the check result as JSON]'
+            ;;
         upgrade)
             _arguments
                 '--force[Force upgrade even if on latest]'
@@ -129,6 +138,7 @@ _tdk_commands() {
         'status:Show resource status'
         'ui:Open interactive UI'
         'doctor:Check environment'
+        'runtime:Inspect packaged runtime assets'
         'version:Show version'
         'upgrade:Upgrade TDK CLI'
         'completion:Generate shell completions'
@@ -173,6 +183,7 @@ complete -c tdk -n '__fish_use_subcommand' -a 'down' -d 'Stop all services'
 complete -c tdk -n '__fish_use_subcommand' -a 'status' -d 'Show resource status'
 complete -c tdk -n '__fish_use_subcommand' -a 'ui' -d 'Open interactive UI'
 complete -c tdk -n '__fish_use_subcommand' -a 'doctor' -d 'Check environment'
+complete -c tdk -n '__fish_use_subcommand' -a 'runtime' -d 'Inspect packaged runtime assets'
 complete -c tdk -n '__fish_use_subcommand' -a 'version' -d 'Show version'
 complete -c tdk -n '__fish_use_subcommand' -a 'upgrade' -d 'Upgrade TDK CLI'
 complete -c tdk -n '__fish_use_subcommand' -a 'completion' -d 'Generate shell completions'
@@ -208,6 +219,8 @@ complete -c tdk -n '__fish_seen_subcommand_from up' -a '(tdk resources 2>/dev/nu
 
 # doctor command options
 complete -c tdk -n '__fish_seen_subcommand_from doctor' -l fix -d 'Attempt to fix issues'
+complete -c tdk -n '__fish_seen_subcommand_from runtime' -l check-assets -d 'Check bundled engine and template assets'
+complete -c tdk -n '__fish_seen_subcommand_from runtime' -l json -d 'Print the check result as JSON'
 
 # upgrade command options
 complete -c tdk -n '__fish_seen_subcommand_from upgrade' -l force -d 'Force upgrade even if on latest'
@@ -215,7 +228,7 @@ complete -c tdk -n '__fish_seen_subcommand_from upgrade' -l dry-run -d 'Show wha
 `;
 const POWERSHELL_COMPLETION = `Register-ArgumentCompleter -Native -CommandName tdk -ScriptBlock {
   param($wordToComplete)
-  $cmds = @('up','down','doctor','project','resource','stacks','status','networks','upgrade','version','ui','config')
+  $cmds = @('up','down','doctor','project','resource','stacks','status','networks','upgrade','runtime','version','ui','config')
   $cmds | Where-Object { $_ -like "$wordToComplete*" }
 }`;
 const POWERSHELL_START = "# TDK-CLI-COMPLETION-START";

package/cli/dist/commands/doctor.js

@@ -7,11 +7,13 @@ import { hasVerdaccioLicense } from "../generator/extension-fetch.js";
 import { MASTER_CONFIG_FILES, REQUIRED_PACKAGE_SCRIPTS } from "../utils/constants.js";
 import { isPathDiscovered, readDiscoveryPaths } from "../utils/discovery-paths.js";
 import { collectDoctorChecks, createDoctorReport, getDoctorExitCode, } from "../utils/doctor-report.js";
-import { checkHealthRoutes, checkHostPorts, checkIngressPorts, checkPrivateNpmRegistry, checkTiltResourceHealth, projectConfigEnablesVerdaccio, summarizeServiceProbes, } from "../utils/doctor-runtime.js";
+import { checkHealthRoutes, checkIngressPorts, checkPrivateNpmRegistry, checkTiltResourceHealth, projectConfigEnablesVerdaccio, summarizeServiceProbes, } from "../utils/doctor-runtime.js";
 import { checkDockerNetworkCapacity, checkFrontendBackendUrls, checkNatsBroker, checkResourcePackageJson, checkServiceUrlPorts, checkTiltInstances, } from "../utils/doctor-wiring.js";
 import { validateEnvFile } from "../utils/env-validator.js";
 import { execAsync, isExecTimeout } from "../utils/exec-async.js";
 import { formatCount } from "../utils/formatting.js";
+import { getHostPortPlan } from "../utils/host-port-config.js";
+import { createHostPortPlan } from "../utils/host-port-plan.js";
 import { findProjectRoot } from "../utils/paths.js";
 import { buildHealthTargets, pingHealthTargets } from "../utils/service-urls.js";
 import { discoverResourcesFromRoot } from "../utils/services.js";
@@ -954,9 +956,9 @@ const DEFAULT_PING_TIMEOUT_MS = 5000;
  * it catches the case where a container is running but Traefik never routed
  * to it, which `docker ps` alone will not show.
  */
-async function checkServiceHealth(timeoutMs) {
+async function checkServiceHealth(timeoutMs, ingressPort) {
     const projectRoot = findProjectRoot() ?? process.cwd();
-    const targets = buildHealthTargets(discoverResourcesFromRoot(projectRoot));
+    const targets = buildHealthTargets(discoverResourcesFromRoot(projectRoot), ingressPort);
     if (targets.length === 0) {
         return {
             name: "Service Health",
@@ -999,6 +1001,13 @@ export const doctorCommand = new Command("doctor")
     }
     if (process.platform === "win32") {
         if (options.json) {
+            let windowsPortPlan = null;
+            try {
+                windowsPortPlan = await createHostPortPlan();
+            }
+            catch {
+                /* The native-Windows platform finding remains the primary failure. */
+            }
             console.log(JSON.stringify(createDoctorReport([
                 {
                     name: "Native Windows support",
@@ -1006,7 +1015,7 @@ export const doctorCommand = new Command("doctor")
                     message: NATIVE_WINDOWS_DOCTOR_MESSAGE,
                     fix: "Use WSL2 Ubuntu with Docker Desktop integration. Guide: docs/wsl2.md",
                 },
-            ], Boolean(findProjectRoot()))));
+            ], Boolean(findProjectRoot()), [], windowsPortPlan)));
         }
         console.error(NATIVE_WINDOWS_DOCTOR_MESSAGE);
         process.exit(1);
@@ -1016,9 +1025,39 @@ export const doctorCommand = new Command("doctor")
         console.log(`\n${chalk.bold("🔍 TDK Doctor")}\n`);
         console.log("Checking environment...\n");
     }
+    const projectRoot = findProjectRoot();
+    let hostPortPlan;
+    let portPlanError;
+    try {
+        hostPortPlan = await getHostPortPlan(projectRoot ?? process.cwd());
+    }
+    catch (error) {
+        hostPortPlan = null;
+        portPlanError = error instanceof Error ? error.message : String(error);
+    }
     const machineChecks = [
-        () => checkHostPorts(),
-        () => checkIngressPorts(),
+        () => hostPortPlan
+            ? {
+                name: "Host Ports",
+                didPass: true,
+                message: `HTTP ${hostPortPlan.ingressHttp}, HTTPS ${hostPortPlan.ingressHttps}, Postgres ${hostPortPlan.postgres}`,
+            }
+            : {
+                name: "Host Ports",
+                didPass: false,
+                message: portPlanError ?? "Could not select host ports",
+                fix: "Set TDK_HTTP_PORT, TDK_HTTPS_PORT, or TDK_POSTGRES_PORT to available host ports.",
+            },
+        () => hostPortPlan
+            ? checkIngressPorts(execSync, undefined, [
+                hostPortPlan.ingressHttp,
+                hostPortPlan.ingressHttps,
+            ])
+            : {
+                name: "Ingress Ports",
+                didPass: false,
+                message: "Ingress port plan is unavailable",
+            },
         checkDockerRuntime,
         checkDockerOperatingSystem,
         checkTilt,
@@ -1061,14 +1100,14 @@ export const doctorCommand = new Command("doctor")
     ];
     // Runs last: needs routable services (and working Traefik) to mean anything.
     if (options.ping) {
-        projectChecks.push(() => checkServiceHealth(pingTimeout));
+        projectChecks.push(() => checkServiceHealth(pingTimeout, hostPortPlan?.ingressHttp));
     }
     // Right after installing, people run `tdk doctor` before they have a
     // project. Only the machine checks mean anything there; the project checks
     // would all fail with "run tdk project".
-    const inProject = Boolean(findProjectRoot());
+    const inProject = Boolean(projectRoot);
     const { checks: results, errors } = await collectDoctorChecks(machineChecks, inProject ? projectChecks : []);
-    const report = createDoctorReport(orderDoctorResults(results), inProject, errors);
+    const report = createDoctorReport(orderDoctorResults(results), inProject, errors, hostPortPlan);
     const exitCode = getDoctorExitCode(report);
     const allPassed = report.data.ready;
     if (options.json) {

package/cli/dist/commands/help.js

@@ -63,6 +63,11 @@ const COMMAND_GROUPS = [
                 alias: "regenerate, verify, edit",
             },
             { name: "doctor", desc: "Check environment readiness", alias: "" },
+            {
+                name: "runtime",
+                desc: "Inspect packaged engine and template assets",
+                alias: "--check-assets",
+            },
             { name: "completion", desc: "Generate shell completions", alias: "--install --shell zsh" },
             { name: "upgrade, update", desc: "Self-update to latest version", alias: "--force" },
             { name: "version, -v", desc: "Display version number", alias: "" },

package/cli/dist/commands/networks.js

@@ -6,6 +6,8 @@ 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 { readSavedHostPortPlan } from "../utils/host-port-config.js";
+import { createHostPortPlan } from "../utils/host-port-plan.js";
 import { createMachineEnvelope, writeMachineError } from "../utils/machine-output.js";
 import { findProjectRoot } from "../utils/paths.js";
 import { checkPortStatus } from "../utils/port-assignment.js";
@@ -166,6 +168,9 @@ export const networksCommand = new Command("networks")
         if (!projectRoot) {
             throw new Error("Could not find project root (no .tdk/project.json found)");
         }
+        const savedPlan = readSavedHostPortPlan(projectRoot);
+        const hostPortPlan = savedPlan ?? (await createHostPortPlan());
+        const httpPort = hostPortPlan.ingressHttp;
         const discovery = createDiscoveryContext();
         const baseDomain = determineDefaultDomain();
         const bareDomain = baseDomain.replace(/^(app|api)\./, "");
@@ -178,7 +183,7 @@ export const networksCommand = new Command("networks")
             const basePath = s.config.basePath.replace(/^\//, "");
             const isBackend = s.config?.appType === "backend";
             const host = isBackend ? apiDomain : appDomain;
-            const url = `http://${host}/${basePath}`;
+            const url = `http://${host}:${httpPort}/${basePath}`;
             const port = s.config.port;
             const status = await checkServiceStatus(s.name, port, url);
             return {
@@ -187,7 +192,7 @@ export const networksCommand = new Command("networks")
                 basePath: s.config.basePath,
                 url,
                 ...(process.platform === "win32"
-                    ? { loopbackUrl: `http://127.0.0.1:80/${basePath}`.replace(/\/$/, "") }
+                    ? { loopbackUrl: `http://127.0.0.1:${httpPort}/${basePath}`.replace(/\/$/, "") }
                     : {}),
                 port,
                 status,
@@ -222,7 +227,7 @@ export const networksCommand = new Command("networks")
             }
             process.exit(0);
         }
-        printBoxedHeader("🌐  TRAEFIK NETWORKS", `Domain: http://${baseDomain}`, DEFAULT_BOX_WIDTH);
+        printBoxedHeader("🌐  TRAEFIK NETWORKS", `Domain: http://${baseDomain}:${httpPort}`, 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) {

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/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"))) {

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

@@ -21,7 +21,7 @@ export async function collectDoctorChecks(machineChecks, projectChecks) {
     return { checks, errors };
 }
 /** Produce the same readiness decision for human and machine consumers. */
-export function createDoctorReport(checks, inProject, errors = []) {
+export function createDoctorReport(checks, inProject, errors = [], portPlan) {
     return {
         schemaVersion: 1,
         data: {
@@ -29,6 +29,30 @@ export function createDoctorReport(checks, inProject, errors = []) {
                 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,
     };

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

@@ -1,5 +1,5 @@
 import { createServer } from "node:net";
-const DEFAULT_RANGES = {
+export const DEFAULT_HOST_PORT_RANGES = {
     ingressHttp: { start: 8080, end: 8180 },
     ingressHttps: { start: 8443, end: 8543 },
     postgres: { start: 15432, end: 15532 },
@@ -9,7 +9,8 @@ const ENV_KEYS = {
     ingressHttps: "TDK_HTTPS_PORT",
     postgres: "TDK_POSTGRES_PORT",
 };
-async function isHostPortAvailable(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));
@@ -29,12 +30,13 @@ 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_RANGES[key];
+        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);
@@ -56,7 +58,17 @@ export async function createHostPortPlan(options = {}) {
         reserved.add(chosen);
         selected[key] = chosen;
         explicitFlags[key] = explicit;
+        reasons[key] = explicit
+            ? "explicit override"
+            : `selected from fallback range ${range.start}-${range.end}`;
     }
-    return selected;
+    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/service-urls.js

@@ -15,22 +15,24 @@ export function getProjectName() {
     }
     return "tdk-project";
 }
-export function resolveSubdomainBases() {
+export function resolveSubdomainBases(ingressPort) {
     const projectName = getProjectName();
-    const raw = process.env.TDK_SERVICE_BASE_URL ?? `http://${projectName}.localhost`;
+    const raw = process.env.TDK_SERVICE_BASE_URL ??
+        `http://${projectName}.localhost${ingressPort ? `:${ingressPort}` : ""}`;
     try {
         const u = new URL(raw.includes("://") ? raw : `http://${raw}`);
         const host = u.hostname;
+        const port = u.port || (ingressPort ? String(ingressPort) : "");
         if (host === "localhost" || /^\d+\.\d+\.\d+\.\d+$/.test(host)) {
             return {
-                appBase: `${u.protocol}//${host}${u.port ? `:${u.port}` : ""}`,
-                apiBase: `${u.protocol}//${host}${u.port ? `:${u.port}` : ""}`,
+                appBase: `${u.protocol}//${host}${port ? `:${port}` : ""}`,
+                apiBase: `${u.protocol}//${host}${port ? `:${port}` : ""}`,
             };
         }
         const bare = host.replace(/^(app|api)\./, "");
         return {
-            appBase: `${u.protocol}//app.${bare}${u.port ? `:${u.port}` : ""}`,
-            apiBase: `${u.protocol}//api.${bare}${u.port ? `:${u.port}` : ""}`,
+            appBase: `${u.protocol}//app.${bare}${port ? `:${port}` : ""}`,
+            apiBase: `${u.protocol}//api.${bare}${port ? `:${port}` : ""}`,
         };
     }
     catch {
@@ -56,8 +58,8 @@ export function resolveServicePath(resource) {
  * Workers, libraries, SDKs and migrators have no Traefik route, so they are
  * skipped rather than reported as unreachable.
  */
-export function buildHealthTargets(resources) {
-    const { appBase, apiBase } = resolveSubdomainBases();
+export function buildHealthTargets(resources, ingressPort) {
+    const { appBase, apiBase } = resolveSubdomainBases(ingressPort);
     return resources
         .filter((resource) => resource.config?.appType === "frontend" || resource.config?.appType === "backend")
         .map((resource) => {

package/cli/package.json

@@ -1,7 +1,7 @@
 {
   "name": "tdk-cli-internal",
   "private": true,
-  "version": "1.3.80",
+  "version": "1.3.81",
   "description": "TDK CLI - Tilt Development Kit command line interface",
   "keywords": [
     "tdk",

package/engine/topologies/platform/docker/compose/traefik_standalone.star

@@ -10,7 +10,7 @@ load("../config/healthcheck.star", "compose_healthcheck_timing")
 load("../networking/traefik_static_routes.star", "normalize_abs_path")
 
 
-def generate_standalone_traefik_compose(sablier_enabled = False):
+def generate_standalone_traefik_compose(sablier_enabled = False, http_host_port = "8080", https_host_port = "8443"):
     """Minimal Traefik that routes Docker labels on api.{project}.localhost.
 
     The Sablier plugin, the sablier container and the wake gateway are only
@@ -48,8 +48,8 @@ services:
       - "--entrypoints.websecure.address=:443"
       - "--log.level=INFO"
 {sablier_flags}    ports:
-      - "80:80"
-      - "8080:8080"
+      - "{http_host_port}:80"
+      - "{https_host_port}:443"
     volumes:
       - /var/run/docker.sock:/var/run/docker.sock:ro
       - ./{dynamic_dir_name}:/etc/traefik/dynamic:ro
@@ -65,6 +65,8 @@ services:
 """.format(
         name=name,
         network=network,
+        http_host_port=http_host_port,
+        https_host_port=https_host_port,
         healthcheck_timing=compose_healthcheck_timing(10),
         traefik_depends_on=_SABLIER_DEPENDS_ON if sablier_enabled else "",
         sablier_flags=_SABLIER_FLAGS if sablier_enabled else "",

package/engine/topologies/tilt/resources/infra-loader.star

@@ -70,7 +70,7 @@ services:
       POSTGRES_PASSWORD: ${{DB_PASSWORD}}
       POSTGRES_DB: postgres
     ports:
-      - "5432:5432"
+      - "{host_port}:5432"
     volumes:
       - {name}_postgres_data:/var/lib/postgresql/data
     networks:
@@ -88,7 +88,7 @@ networks:
 
 volumes:
   {name}_postgres_data:
-""".format(name=name, database_network=database_network)
+""".format(name=name, database_network=database_network, host_port=os.environ.get('TDK_POSTGRES_PORT', '15432'))
 
 
 def _ensure_database_management_compose(root_prefix, write_fn):
@@ -174,43 +174,18 @@ def _load_infisical(should_enable, root_prefix="", env_file=None):
 # 🌐 PROXY (Traefik)
 # =============================================================================
 
-def _stop_conflicting_traefik():
-    """Auto-stop another TDK project's standalone Traefik if it already holds
-    host port 80/8080, so `tdk up` on a new project always wins over a stale
-    Traefik left running from a previous one.
-
-    Each standalone project gets its own container name and Docker network
-    (see PlatformDockerConstants.PROJECT_NAME), but the host ports are hardcoded
-    to 80/8080 so `api.{project}.localhost` works without a port suffix. That
-    means only one standalone project's Traefik can run at a time. Without this,
-    starting a second project while another's Traefik is still running fails
-    deep inside `docker compose up` with a cryptic "port is already allocated"
-    networking error instead of just taking over the port.
-    """
-    own_container = PlatformDockerConstants.PROJECT_NAME + "_traefik"
-    result = str(local(
-        "docker ps --filter 'publish=80' --filter 'publish=8080' --format '{{.Names}}' 2>/dev/null || true",
-        quiet=True, echo_off=True,
-    )).strip()
-    for container in result.split("\n"):
-        container = container.strip()
-        if container and container != own_container:
-            print("🛑 Stopping Traefik from another TDK project ('{}') — it was holding host port 80/8080".format(container))
-            local(
-                "docker stop '{}' >/dev/null 2>&1 || true".format(container),
-                quiet=True, echo_off=True,
-            )
-
-
 def _load_standalone_traefik(root_prefix, env_file, write_fn):
     """Generate and load a self-contained Traefik compose for standalone projects."""
-    _stop_conflicting_traefik()
     compose_rel = ".tdk/.tdk-out/docker-compose.traefik.yml"
     # The free-tier stub always reports "disabled"; the licensed module reports
     # enabled for a manifest that opts in. Probing it keeps this file free of any
     # license logic while starting the sablier containers only when they can work.
     _, sablier_enabled = sablier_middleware_suffix({"sablier": {"enable": True}}, "probe")
-    content = generate_standalone_traefik_compose(sablier_enabled)
+    content = generate_standalone_traefik_compose(
+        sablier_enabled,
+        os.environ.get('TDK_HTTP_PORT', '8080'),
+        os.environ.get('TDK_HTTPS_PORT', '8443'),
+    )
     if write_fn:
         write_fn(compose_rel, content)
     compose_file = root_prefix + compose_rel if root_prefix else compose_rel

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tdk-landscape/tdk-cli-core",
-  "version": "1.3.80",
+  "version": "1.3.81",
   "description": "TDK runs many services on your laptop with Docker + Tilt. Helm still deploys the cluster.",
   "homepage": "https://tdk-landscape.github.io/tdk-website",
   "repository": {