@tdk-landscape/tdk-cli-core 1.3.145 → 1.3.147

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)
 
@@ -141,6 +141,8 @@ Set `TDK_DEBUG=1` before running `tdk up --verbose` to include Starlark debug lo
 - [Show HN draft](docs/drafts/show-hn.md)
 - [Architecture and repository map](docs/project-overview.md)
 - [Scale fixture measurements and caveats](docs/benchmarks/scale-bench.md)
+- [Benchmark report: warm and cold start charts, history](https://tdk-landscape.github.io/tdk-cli-core/) (updated on every change to `main` that affects start-up)
+- [How to run the start-time benchmark](scripts/benchmark/README.md#tdk-up-warm-start-benchmark)
 
 ## History
 

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

@@ -12,7 +12,7 @@ import { AUTOGENERATED_DIR, CONTAINER_RUNTIME_CHECK, MASTER_CONFIG_FILES, PACKAG
 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";
@@ -23,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";
@@ -925,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)
@@ -1087,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/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;