@tdk-landscape/tdk-cli-core 1.3.144 → 1.3.146

package/CHANGELOG.md

@@ -4,6 +4,7 @@ Notable changes to the `tdk` CLI. Versions match [npm](https://www.npmjs.com/pac
 
 ## Unreleased
 
+- `tdk up` now publishes Traefik on host port 80 (and 443) when they are free, so routed URLs read `http://app.<project>.localhost/<app>` instead of `...localhost:8080/<app>`. It always wanted 80 but only ever tried 8080-8180. On macOS the free-port check treated the kernel's refusal of a non-root bind below 1024 as "busy", although Docker Desktop publishes those ports itself; that also made `TDK_HTTP_PORT=80` fail with "already in use". A project whose saved plan is on 8080 moves to 80 on its next `tdk up` once 80 is free. On Linux and WSL2 a non-root user cannot check port 80, so the 8080-8180 range is kept there. Printed URLs no longer end in `:80`.
 - TDK MCP tools now accept an absolute `projectPath` so a projectless MCP client can run doctor, inspect services and logs, and manage the intended project without depending on the server launch directory.
 - Shared platform stacks (postgres, traefik, proxy, messaging, infisical, monitoring, cdc, elk) now run in Compose projects named `<project>-<stack>` (for example `tdk-erp-system-database-management`) instead of the directory-named `database-management`, `tdk-out` and so on. Two TDK projects on one Docker daemon no longer share them.
 

package/README.md

@@ -52,10 +52,10 @@ mkdir shop && cd shop
 tdk project --yes
 tdk resource orders-api --type backend --stack shop --yes
 tdk up shop
-curl http://api.shop.localhost:8080/api/orders/health
+curl http://api.shop.localhost/api/orders/health
 ```
 
-`tdk up` prints the host ports it chose. Port 8080 is the default; if it was taken, use the HTTP port `tdk up` reports (or set `TDK_HTTP_PORT`). A resource named `orders-api` is served at `/api/orders` (a trailing `-api` is dropped); `tdk up` prints the exact URLs.
+`tdk up` prints the host ports it chose. It uses port 80 when it is free, so URLs carry no port. Otherwise it picks one from 8080-8180, and the URLs it prints include that port (on Linux and WSL2 a non-root user cannot check port 80, so the range is used there). Use the URL `tdk up` prints, or set `TDK_HTTP_PORT`. A resource named `orders-api` is served at `/api/orders` (a trailing `-api` is dropped); `tdk up` prints the exact URLs.
 
 ![TDK scaffolding a backend and a frontend, then listing the stack](docs/assets/demo.svg)
 

package/Tiltfile

@@ -36,6 +36,7 @@ load('./engine/topologies/tilt/resources/declaration.star', _Orchestrator='Orche
 load('./engine/topologies/tilt/resources/ordering.star', _Infra='Infra')
 load('./engine/topologies/tilt/resources/triggers.star', _Watchers='Watchers')
 load('./engine/topologies/tilt/resources/orchestrator/apply_compose_resource_registration.star', _resource_defers_start='resource_defers_start')
+load('./engine/topologies/platform/docker/build/frontend_build_plan.star', _frontend_build_plan='frontend_build_plan')
 
 # =============================================================================
 # SPECS (Tech stack and standards)
@@ -132,6 +133,7 @@ Watchers = _Watchers
 # True when a manifest's deferStart is actually active (licensed); decides whether a `<name>-image` prebuild resource exists.
 # The generated Tiltfile loads this from ext://tdk-cli, which resolves to this root Tiltfile.
 resource_defers_start = _resource_defers_start
+FrontendBuildPlan = _frontend_build_plan
 
 # Specs
 assert_tech_stack = _assert_tech_stack

package/cli/dist/commands/doctor.js

@@ -10,8 +10,9 @@ import { DEVCONTAINER_DOCKER_FIX, detectHost, isContainerHost, WEBCONTAINER_DOCS
 import { projectNeedsBun } from "../utils/bun-requirement.js";
 import { AUTOGENERATED_DIR, CONTAINER_RUNTIME_CHECK, MASTER_CONFIG_FILES, PACKAGE_JSON, REQUIRED_PACKAGE_SCRIPTS, } from "../utils/constants.js";
 import { isPathDiscovered, readDiscoveryPaths } from "../utils/discovery-paths.js";
+import { checkDiskSpace, dockerDesktopStuck } from "../utils/doctor-host.js";
 import { collectDoctorChecks, createDoctorReport, getDoctorExitCode, } from "../utils/doctor-report.js";
-import { checkHealthRoutes, checkIngressPorts, checkPrivateNpmRegistry, checkTiltResourceHealth, projectConfigEnablesVerdaccio, summarizeServiceProbes, } from "../utils/doctor-runtime.js";
+import { checkHealthRoutes, checkIngressPorts, checkPrivateNpmRegistry, checkTiltResourceHealth, projectConfigEnablesVerdaccio, summarizeAdvertisedProbes, summarizeServiceProbes, summarizeSmokeResults, } from "../utils/doctor-runtime.js";
 import { checkStarlarkLoadExports } from "../utils/doctor-starlark.js";
 import { checkDockerNetworkCapacity, checkDuplicateResourceNames, checkDuplicateResourcePorts, checkFrontendBackendUrls, checkMigrationsInApi, checkNatsBroker, checkPrismaConsistency, checkResourcePackageJson, checkServiceUrlPorts, checkSharedPlatformPostgres, checkSharedStackRoutes, checkTiltInstances, } from "../utils/doctor-wiring.js";
 import { validateEnvFile } from "../utils/env-validator.js";
@@ -22,8 +23,9 @@ import { createHostPortPlan } from "../utils/host-port-plan.js";
 import { findProjectRoot, getPackageVersion } from "../utils/paths.js";
 import { EnvUnreadableError, envSecretValues, redactSecrets, redactValue, } from "../utils/secret-redaction.js";
 import { checkCircularDependencies, checkDependsOnShape, checkSchemaVersions, checkServicePorts, } from "../utils/service-config-checks.js";
-import { buildHealthTargets, pingHealthTargets } from "../utils/service-urls.js";
+import { buildAdvertisedTargets, buildHealthTargets, pingHealthTargets, } from "../utils/service-urls.js";
 import { discoverResourcesFromRoot } from "../utils/services.js";
+import { buildSmokePlans, readOnlySmokePlans, runSmokePlans } from "../utils/smoke.js";
 import { evaluateTdkVersionFloor } from "../utils/tdk-version.js";
 import { findOnPath } from "../utils/which.js";
 export { checkIngressPorts, checkPrivateNpmRegistry, checkTiltResourceHealth, summarizeServiceProbes, summarizeTiltBuildError, } from "../utils/doctor-runtime.js";
@@ -202,6 +204,10 @@ export async function checkDockerRuntime() {
             };
         }
     }
+    // Docker Desktop open but its engine down or stuck: say so instead of "not running".
+    const stuck = dockerDesktopStuck(await succeeds("pgrep -f com.docker.backend"));
+    if (stuck)
+        return stuck;
     // Docker not running: check for Colima, then Podman
     if (await succeeds("colima status")) {
         return {
@@ -920,6 +926,50 @@ async function checkServiceHealth(timeoutMs, ingressPort) {
     }
     return summarizeServiceProbes(await pingHealthTargets(targets, timeoutMs));
 }
+/**
+ * Runs the GET steps of each service's "smoke" block through its public URL. These are the checks `tdk up` already runs, minus the
+ * writes, so a service with an empty /health but a missing list route is caught before anyone clicks a dead link.
+ *
+ * Like the health ping, this only runs once services answer. A stopped stack is skipped, not failed.
+ */
+async function checkServiceSmoke(timeoutMs, ingressPort) {
+    const projectRoot = findProjectRoot() ?? process.cwd();
+    const resources = discoverResourcesFromRoot(projectRoot);
+    const plans = readOnlySmokePlans(buildSmokePlans(resources, ingressPort), {
+        timeoutSeconds: Math.ceil(timeoutMs / 1000),
+    });
+    if (plans.length === 0) {
+        return summarizeSmokeResults([]);
+    }
+    const probes = await pingHealthTargets(buildHealthTargets(resources, ingressPort), timeoutMs);
+    if (!probes.some((probe) => probe.status !== undefined)) {
+        return {
+            name: "Service Smoke",
+            didPass: true,
+            isSkipped: true,
+            message: "No services responded - skipped smoke checks",
+        };
+    }
+    return summarizeSmokeResults(await runSmokePlans(plans));
+}
+/**
+ * Requests the URL each routable service advertises, the same one `tdk networks` and the TDK App show, and warns on a 404.
+ * Like the other runtime checks, it only runs once services answer. A stopped stack is skipped, not reported.
+ */
+async function checkAdvertisedEndpoints(timeoutMs, ingressPort) {
+    const projectRoot = findProjectRoot() ?? process.cwd();
+    const resources = discoverResourcesFromRoot(projectRoot);
+    const targets = buildAdvertisedTargets(resources, ingressPort);
+    if (targets.length === 0) {
+        return {
+            name: "Advertised Endpoints",
+            didPass: true,
+            isSkipped: true,
+            message: "No routable services to check",
+        };
+    }
+    return summarizeAdvertisedProbes(await pingHealthTargets(targets, timeoutMs));
+}
 export const doctorCommand = new Command("doctor")
     .description("Check environment readiness for TDK")
     .option("--json", "Output a versioned JSON readiness report", false)
@@ -1026,6 +1076,7 @@ export const doctorCommand = new Command("doctor")
                 message: "Ingress port plan is unavailable",
             },
         checkDockerRuntime,
+        () => checkDiskSpace(),
         checkDockerOperatingSystem,
         checkTilt,
         checkDockerCompose,
@@ -1081,6 +1132,8 @@ export const doctorCommand = new Command("doctor")
     // Runs last: needs routable services (and working Traefik) to mean anything.
     if (options.ping) {
         projectChecks.push(() => checkServiceHealth(pingTimeout, hostPortPlan?.ingressHttp));
+        projectChecks.push(() => checkServiceSmoke(pingTimeout, hostPortPlan?.ingressHttp));
+        projectChecks.push(() => checkAdvertisedEndpoints(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

package/cli/dist/commands/status.js

@@ -11,7 +11,7 @@ import { createMachineEnvelope, writeMachineError } from "../utils/machine-outpu
 import { findProjectRoot } from "../utils/paths.js";
 import { deriveServiceStates } from "../utils/service-runtime-state.js";
 import { buildServicePorts, buildStackPorts } from "../utils/status-ports.js";
-import { getTiltfilePath, isTiltAvailable, runTilt } from "../utils/tilt.js";
+import { isTiltAvailable, runTilt } from "../utils/tilt.js";
 import { getTiltPollingPort } from "../utils/tilt-startup.js";
 import { evaluateTiltReadiness, tiltGetUiResources } from "../utils/up-readiness.js";
 export const statusCommand = new Command("status")
@@ -43,22 +43,6 @@ export const statusCommand = new Command("status")
         }
         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";
-            }
-        }
         // A single look at the running Tilt, so a caller that started `tdk up` detached can poll for readiness. Null when no
         // Tilt answers or its output cannot be read.
         let readiness = null;
@@ -67,6 +51,20 @@ export const statusCommand = new Command("status")
         const tiltPort = getTiltPollingPort(process.env.TILT_PORT);
         if (tiltAvailable) {
             const text = await tiltGetUiResources(tiltPort);
+            // `tilt get` has no -f flag; resources come from the running Tilt's API on its port, the same source as readiness.
+            if (options.json && options.tilt) {
+                if (text) {
+                    try {
+                        tiltResources = JSON.parse(text);
+                    }
+                    catch (error) {
+                        queryError = `Tilt returned invalid JSON: ${error instanceof Error ? error.message : String(error)}`;
+                    }
+                }
+                else {
+                    queryError = `No Tilt is answering on port ${tiltPort}. Start it with: tdk up`;
+                }
+            }
             if (text) {
                 const deferred = getDeferredResourceNames();
                 try {
@@ -171,15 +169,14 @@ export const statusCommand = new Command("status")
         if (options.tilt && tiltAvailable) {
             console.log();
             showStep("Tilt Resources:");
-            const tiltfilePath = getTiltfilePath();
-            const result = await runTilt("get", ["-f", tiltfilePath, "resources"], {
+            const result = await runTilt("get", ["uiresources", "--port", String(tiltPort)], {
                 inheritStdio: false,
             });
             if (result.exitCode === 0) {
                 console.log(result.stdout || chalk.gray("  No active tilt resources"));
             }
             else {
-                showDetail("Could not retrieve tilt resource status");
+                showDetail(`No Tilt is answering on port ${tiltPort}. Start it with: tdk up`);
             }
         }
         console.log();

package/cli/dist/commands/up.js

@@ -1,10 +1,11 @@
 // Copyright (c) 2026 TDK Landscape contributors
 // SPDX-License-Identifier: MIT
+import { existsSync } from "node:fs";
 import { connect } from "node:net";
 import { join } from "node:path";
 import chalk from "chalk";
 import { Command } from "commander";
-import { ensureProjectRuntimeAssets, ProjectConfigNotFoundError, verifyMasterConfigs, } from "../generator/template-engine.js";
+import { ensureProjectRuntimeAssets, generateMasterConfigs, ProjectConfigNotFoundError, verifyMasterConfigs, } from "../generator/template-engine.js";
 import { DEVCONTAINER_DOCKER_FIX, detectHost, isContainerHost, WEBCONTAINER_UP_MESSAGE, } from "../utils/agent-host.js";
 import { handleDryRun } from "../utils/command-helpers.js";
 import { STANDARD_PORTS } from "../utils/constants.js";
@@ -256,6 +257,14 @@ export const upCommand = new Command("up")
                     console.log(chalk.gray(`Added ${addedEnvKeys.join(", ")} to .env (generated; existing values unchanged)`));
                 }
             }
+            // A project made by `tdk import` has .tdk/project.json but no generated files yet. Generate them rather than letting
+            // Tilt fail on a missing Tiltfile.
+            if (foundRoot && !existsSync(join(projectRoot, ".tdk", ".tdk-out", "Tiltfile"))) {
+                if (!options.quiet) {
+                    console.log(chalk.gray("No generated Tiltfile yet; generating .tdk/.tdk-out/ ..."));
+                }
+                await generateMasterConfigs(projectRoot, { quiet: options.quiet });
+            }
             const copiedAssets = ensureProjectRuntimeAssets(projectRoot);
             if (copiedAssets.length > 0 && options.verbose && !options.quiet) {
                 console.log(chalk.gray(`Refreshed runtime assets: ${copiedAssets.join(", ")}`));

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

@@ -428,7 +428,7 @@ export async function generateMasterConfigs(projectRoot, options = {}) {
         throw new Error(`Refusing to generate config from unsafe service.json values:\n${unsafeFields.map((error) => `  ${error}`).join("\n")}`);
     }
     await warnIfSablierUnlicensed(projectRoot);
-    if (ensureRootWorkspaceManifest(projectRoot, projectConfig)) {
+    if (ensureRootWorkspaceManifest(projectRoot, projectConfig) && !options.quiet) {
         console.log("✓ Generated: package.json (workspace root)");
     }
     // Verdaccio is Premium, but unlike the old posture here, this is NOT the
@@ -461,14 +461,17 @@ export async function generateMasterConfigs(projectRoot, options = {}) {
         const content = files[filename];
         const filePath = assertTdkGeneratedPath(projectRoot, path.join(".tdk", ".tdk-out", filename));
         writeTextFileAtomic(filePath, content);
-        console.log(`✓ Generated: .tdk/.tdk-out/${filename}`);
+        if (!options.quiet)
+            console.log(`✓ Generated: .tdk/.tdk-out/${filename}`);
     }
     if (isStackFeatureEnabledInStacks(projectConfig.phases, DATABASE_MANAGEMENT_FEATURE)) {
         const composePath = assertTdkGeneratedPath(projectRoot, path.join("services", "platform", DATABASE_MANAGEMENT_FEATURE, DOCKER_COMPOSE_FILE));
         const composeDir = path.dirname(composePath);
         fs.mkdirSync(composeDir, { recursive: true });
         writeTextFileAtomic(composePath, generateDatabaseManagementCompose(projectConfig));
-        console.log("✓ Generated: services/platform/database-management/docker-compose.yml");
+        if (!options.quiet) {
+            console.log("✓ Generated: services/platform/database-management/docker-compose.yml");
+        }
     }
     // Copy .tiltignore to project root so Tilt uses it
     const tiltignoreSource = path.join(outputDir, TILTIGNORE_FILE);

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

@@ -0,0 +1,66 @@
+// Copyright (c) 2026 TDK Landscape contributors
+// SPDX-License-Identifier: MIT
+import { statfsSync } from "node:fs";
+import { homedir } from "node:os";
+export const DISK_SPACE_CHECK = "Disk Space";
+const GIB = 1024 ** 3;
+// Docker Desktop keeps images and containers in one large disk image. When the host disk fills up, the engine
+// stops answering while the Docker Desktop app keeps running, so `tdk up` waits with no visible error.
+export const DISK_FAIL_GIB = 2;
+export const DISK_WARN_GIB = 10;
+export const DISK_CLEANUP_FIX = [
+    "Free disk space, then retry: tdk doctor",
+    "  docker system prune -af        # unused images and build cache (needs Docker running)",
+    "  npm cache clean --force",
+    "  bun pm cache rm",
+    "  brew cleanup -s",
+].join("\n");
+export function checkDiskSpace(statfs = statfsSync, path = homedir()) {
+    let freeGib;
+    try {
+        const stats = statfs(path);
+        freeGib = (Number(stats.bavail) * Number(stats.bsize)) / GIB;
+    }
+    catch {
+        return {
+            name: DISK_SPACE_CHECK,
+            didPass: true,
+            isSkipped: true,
+            message: "Could not read free disk space",
+        };
+    }
+    const shown = `${freeGib.toFixed(1)} GB free`;
+    if (freeGib < DISK_FAIL_GIB) {
+        return {
+            name: DISK_SPACE_CHECK,
+            didPass: false,
+            message: `${shown}: Docker cannot build or start containers`,
+            fix: DISK_CLEANUP_FIX,
+        };
+    }
+    if (freeGib < DISK_WARN_GIB) {
+        return {
+            name: DISK_SPACE_CHECK,
+            didPass: false,
+            isWarning: true,
+            message: `${shown}: image builds may fail`,
+            fix: DISK_CLEANUP_FIX,
+        };
+    }
+    return { name: DISK_SPACE_CHECK, didPass: true, message: shown };
+}
+export const DOCKER_DESKTOP_STUCK_FIX = "Quit Docker Desktop completely (whale icon > Quit Docker Desktop), reopen it, and wait until it shows Running. If it keeps getting stuck, check free disk space. Then retry: tdk doctor";
+/**
+ * Docker Desktop's app process is up but `docker ps` fails: the engine is stopped or stuck, which needs a different fix
+ * than "start Docker". Returns the failing check, or null when that is not the situation.
+ */
+export function dockerDesktopStuck(desktopRunning, platform = process.platform) {
+    if (platform !== "darwin" || !desktopRunning)
+        return null;
+    return {
+        name: "Container Runtime",
+        didPass: false,
+        message: "Docker Desktop is open, but its engine is not responding",
+        fix: DOCKER_DESKTOP_STUCK_FIX,
+    };
+}

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

@@ -462,6 +462,66 @@ export function summarizeServiceProbes(probes) {
             : "Check container state and routing: docker ps, then tdk networks to compare the advertised URLs against Traefik's routers",
     };
 }
+/**
+ * Summarizes the read-only smoke checks. A 404 here usually means the service never registered the route its service.json
+ * names, which the health ping cannot see because /health answers regardless.
+ */
+export function summarizeSmokeResults(results) {
+    if (results.length === 0) {
+        return {
+            name: "Service Smoke",
+            didPass: true,
+            isSkipped: true,
+            message: "No read-only smoke checks declared",
+        };
+    }
+    const failed = results.filter((result) => !result.ok);
+    if (failed.length === 0) {
+        return {
+            name: "Service Smoke",
+            didPass: true,
+            message: `All ${formatCount(results.length, "service")} pass their smoke checks`,
+        };
+    }
+    const details = failed.map((result) => result.failure ?? `${result.name}: failed`).join("\n    ");
+    return {
+        name: "Service Smoke",
+        didPass: false,
+        message: `${formatCount(failed.length, "service")} failing a smoke check (${results.length - failed.length}/${results.length} passing):\n    ${details}`,
+        fix: 'Add the route the smoke step expects, or correct its "path" in the service.json "smoke" block. Then re-run tdk doctor.',
+    };
+}
+/**
+ * Flags advertised links that answer 404. Only a 404 counts: a route that answers with any other status is reachable, and many APIs
+ * have no root route, so this is a warning and never fails the run on its own.
+ */
+export function summarizeAdvertisedProbes(probes) {
+    const answered = probes.filter((probe) => probe.status !== undefined);
+    if (answered.length === 0) {
+        return {
+            name: "Advertised Endpoints",
+            didPass: true,
+            isSkipped: true,
+            message: "No services responded - skipped advertised endpoint check",
+        };
+    }
+    const dead = answered.filter((probe) => probe.status === 404);
+    if (dead.length === 0) {
+        return {
+            name: "Advertised Endpoints",
+            didPass: true,
+            message: `${formatCount(answered.length, "advertised endpoint")} reachable`,
+        };
+    }
+    const details = dead.map((probe) => `${probe.name} (404)\n      ${probe.url}`).join("\n    ");
+    return {
+        name: "Advertised Endpoints",
+        didPass: true,
+        isWarning: true,
+        message: `${formatCount(dead.length, "advertised link")} returns 404:\n    ${details}`,
+        fix: 'Nothing handles this path, so the link is dead. Add a route for it, or declare a read-only "smoke" step on a real route in service.json. The URL tdk networks and the TDK App print stays the same until the CLI changes how it reports it.',
+    };
+}
 /**
  * Catches host ports taken by something other than this project's containers,
  * most often a local Postgres on 5432 or a web server on 80. Docker-held 80/443

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

@@ -4,7 +4,7 @@ import { execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { PROJECT_JSON } from "./constants.js";
-import { createHostPortPlan, isHostPortAvailable } from "./host-port-plan.js";
+import { createHostPortPlan, isHostPortAvailable, PREFERRED_HOST_PORTS, } from "./host-port-plan.js";
 const CONFIG_PATH = join(".tdk", ".tdk-out", "host-ports.json");
 export function isDockerPortOwnedByProject(dockerPs, projectPrefix, port) {
     return dockerPs.split("\n").some((line) => {
@@ -78,12 +78,21 @@ export async function getHostPortPlan(projectRoot, options = {}) {
         }
     }
     const ownedByProject = (port) => isDockerPortOwnedByProject(dockerPs, prefix, port);
-    const isAvailable = async (port) => (await isHostPortAvailable(port)) || ownedByProject(port);
+    const isPortFree = options.isPortFree ?? isHostPortAvailable;
+    const isAvailable = async (port) => (await isPortFree(port)) || ownedByProject(port);
     if (saved && !hasOverride) {
         for (const port of [saved.ingressHttp, saved.ingressHttps, saved.postgres]) {
             if (!(await isAvailable(port)))
                 return createHostPortPlan({ isAvailable });
         }
+        // A plan saved on a fallback port (8080) moves back to the preferred one (80)
+        // once that is free, so URLs lose the port without deleting host-ports.json.
+        for (const [key, preferred] of Object.entries(PREFERRED_HOST_PORTS)) {
+            const savedPort = saved[key];
+            if (preferred !== undefined && savedPort !== preferred && (await isAvailable(preferred))) {
+                return createHostPortPlan({ isAvailable });
+            }
+        }
         return saved;
     }
     return createHostPortPlan({ isAvailable });

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

@@ -13,12 +13,28 @@ const ENV_KEYS = {
     postgres: "TDK_POSTGRES_PORT",
 };
 const REQUESTED_PORTS = { ingressHttp: 80, ingressHttps: 443, postgres: 5432 };
+// Tried before the fallback range so routed URLs need no port. Postgres keeps
+// its range: a local Postgres on 5432 is common, and no URL carries that port.
+export const PREFERRED_HOST_PORTS = {
+    ingressHttp: REQUESTED_PORTS.ingressHttp,
+    ingressHttps: REQUESTED_PORTS.ingressHttps,
+};
+/**
+ * Whether a failed bind on 127.0.0.1 means the port is still free for Docker. Only macOS
+ * refuses a non-root bind below 1024 while Docker Desktop publishes it through a privileged
+ * helper. Callers check for a listener first, so a bind error here is never another process.
+ */
+export function isPrivilegedBindFree(errorCode, platform) {
+    return errorCode === "EACCES" && platform === "darwin";
+}
 export async function isHostPortAvailable(port) {
     if (await hasLocalListener(port))
         return false;
     return new Promise((resolve) => {
         const server = createServer();
-        server.once("error", () => resolve(false));
+        server.once("error", (error) => {
+            resolve(isPrivilegedBindFree(error.code, process.platform));
+        });
         // Docker Desktop and Windows publish these host ports through IPv4 loopback.
         // Match that target instead of probing wildcard binds that may differ by OS.
         server.listen(port, "127.0.0.1", () => server.close(() => resolve(true)));
@@ -42,9 +58,13 @@ export async function createHostPortPlan(options = {}) {
         const envValue = env[ENV_KEYS[key]];
         const explicit = envValue !== undefined && envValue.trim() !== "";
         const range = options.ranges?.[key] ?? DEFAULT_HOST_PORT_RANGES[key];
+        const preferred = PREFERRED_HOST_PORTS[key];
         const candidates = explicit
             ? [parsePort(ENV_KEYS[key], envValue)]
-            : Array.from({ length: range.end - range.start + 1 }, (_, index) => range.start + index);
+            : [
+                ...(preferred === undefined ? [] : [preferred]),
+                ...Array.from({ length: range.end - range.start + 1 }, (_, index) => range.start + index),
+            ];
         let chosen;
         for (const port of candidates) {
             if (reserved.has(port))
@@ -65,7 +85,9 @@ export async function createHostPortPlan(options = {}) {
         explicitFlags[key] = explicit;
         reasons[key] = explicit
             ? "explicit override"
-            : `selected from fallback range ${range.start}-${range.end}`;
+            : chosen === preferred
+                ? "requested port is free"
+                : `selected from fallback range ${range.start}-${range.end}`;
     }
     return {
         ...selected,

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

@@ -26,7 +26,11 @@ export function resolveSubdomainBases(ingressPort) {
     try {
         const u = new URL(raw.includes("://") ? raw : `http://${raw}`);
         const host = u.hostname;
-        const port = u.port || (ingressPort ? String(ingressPort) : "");
+        // URL drops a default port (80 for http, 443 for https), so u.port is empty
+        // for http://x.localhost:80. Keep it empty instead of re-adding ingressPort.
+        const defaultPort = u.protocol === "https:" ? "443" : "80";
+        const explicitPort = u.port || (ingressPort ? String(ingressPort) : "");
+        const port = explicitPort === defaultPort ? "" : explicitPort;
         if (host === "localhost" || /^\d+\.\d+\.\d+\.\d+$/.test(host)) {
             return {
                 appBase: `${u.protocol}//${host}${port ? `:${port}` : ""}`,
@@ -63,6 +67,16 @@ export function resolveServicePath(resource) {
  * skipped rather than reported as unreachable.
  */
 export function buildHealthTargets(resources, ingressPort) {
+    return routableTargets(resources, ingressPort, (path) => appendHealthPath(path));
+}
+/**
+ * The URL `tdk up` and `tdk networks` advertise for each routable service, with no suffix. A service can answer /health while
+ * this URL is a 404 (nothing handles the bare path), which is the dead link users click.
+ */
+export function buildAdvertisedTargets(resources, ingressPort) {
+    return routableTargets(resources, ingressPort, (path) => path);
+}
+function routableTargets(resources, ingressPort, toPath) {
     const { appBase, apiBase } = resolveSubdomainBases(ingressPort);
     return resources
         .filter((resource) => resource.config?.appType === "frontend" || isApiServiceType(resource.config?.appType))
@@ -71,7 +85,7 @@ export function buildHealthTargets(resources, ingressPort) {
         return {
             name: resource.name,
             appType: resource.config.appType,
-            url: `${base}${appendHealthPath(resolveServicePath(resource))}`,
+            url: `${base}${toPath(resolveServicePath(resource))}`,
         };
     });
 }

package/cli/dist/utils/smoke.js

@@ -105,6 +105,34 @@ export function buildSmokePlans(resources, ingressPort) {
     }
     return plans;
 }
+/** Caps each read-only smoke check so a doctor run cannot wait the full `tdk up` budget per service. */
+const DOCTOR_SMOKE_TIMEOUT_SECONDS = 10;
+/**
+ * The GET-only part of each smoke block, for `tdk doctor`. Doctor must never write to a service, and a step whose path reads
+ * a value saved by an earlier write (`{{name}}`) cannot run on its own, so both are dropped. A service with no such steps is left out.
+ * `bodyContains` is also cleared: it asserts on data that earlier writes created, so doctor would fail a healthy route whose data was removed.
+ * The status check stays, which is what shows a route exists.
+ */
+export function readOnlySmokePlans(plans, options = {}) {
+    const cap = options.timeoutSeconds ?? DOCTOR_SMOKE_TIMEOUT_SECONDS;
+    return plans.flatMap((plan) => {
+        const steps = plan.smoke.steps
+            .filter((step) => (step.method ?? "GET").toUpperCase() === "GET" &&
+            step.body === undefined &&
+            !step.path.includes("{{"))
+            .map((step) => ({ ...step, bodyContains: undefined }));
+        if (steps.length === 0)
+            return [];
+        const budget = Math.min(plan.smoke.timeoutSeconds ?? DEFAULT_SMOKE_TIMEOUT_SECONDS, cap);
+        return [
+            {
+                name: plan.name,
+                baseUrl: plan.baseUrl,
+                smoke: { via: plan.smoke.via, timeoutSeconds: budget, steps },
+            },
+        ];
+    });
+}
 function readPath(value, path) {
     const parts = path.replace(/^\$\.?/, "").match(/[^.[\]]+/g) ?? [];
     let current = value;