@tdk-landscape/tdk-cli-core 1.3.75 → 1.3.76

package/CHANGELOG.md

@@ -4,6 +4,12 @@ Notable changes to the `tdk` CLI. Versions match [npm](https://www.npmjs.com/pac
 
 ## Unreleased
 
+- `tdk up` no longer leaves `nats` (and any other service in `services/platform/messaging/docker-compose.yml`, e.g. a local mail catcher) disabled in Tilt. The pre-alpha default always goes through a focus-filter path that only re-enabled `init-networks`/`postgres`/`traefik`/`golden-layers-build`, so a resource with the `nats` feature retried its broker connection forever until you ran `tilt enable nats` by hand. Fixes #155.
+
+- `tdk doctor` now catches wiring mistakes that used to surface minutes into `tdk up`: a resource with no `package.json` (the image build stops at "COPY ... not found"), a `params` URL such as `http://auth-emulator:4000` whose port is not the one the target listens on (its `service.json` `port`), a frontend calling a backend through `localhost:<port>` (TDK publishes no backend ports on localhost; use the Traefik route), the `nats` feature without `services/platform/messaging/docker-compose.yml` (TDK does not generate it, so no NATS server starts), two Tilt processes running for one project, and Docker having no address pool left for the networks a project needs. Found while building [tdk-ecommerce-example](https://github.com/tdk-landscape/tdk-ecommerce-example) and a queue/auth example.
+
+- `tdk project ecommerce` clones [tdk-ecommerce-example](https://github.com/tdk-landscape/tdk-ecommerce-example), a Vue 3 storefront and Hono catalog API. Before, only restaurant, saas, erp, user-management and example were accepted.
+
 ## 1.3.73 (2026-09-28)
 
 - Free-tier projects no longer start the `sablier` and `wake-gateway` containers, and Traefik no longer downloads the Sablier plugin from GitHub on every start. They were always launched (the `sablier` one with a read-write Docker socket) even though the license only gated the per-service labels, so nothing could use them. They are now generated only when a license grants Sablier. Fewer containers, one image build less, and no network fetch at Traefik boot. Spotted in the ERP CI run log.

package/README.md

@@ -187,14 +187,14 @@ make pre-commit-run # run pre-commit hooks on all files
 tdk doctor
 ```
 
-Checks Docker, Compose and Tilt. Inside a project it also checks the generated configs, `.env`, service scripts and that the ingress ports are free, before you run `tdk up`.
+Checks Docker, Compose and Tilt. Inside a project it also checks the generated configs, `.env`, service scripts and that the ingress ports are free, before you run `tdk up`. It also catches wiring mistakes: a resource without `package.json`, a `params` URL that uses the wrong port for another service, a frontend calling a backend on `localhost:<port>`, the `nats` feature without a broker to start, duplicate Tilt processes, and Docker running out of network address space.
 
 ## Community
 
 - **Questions and ideas:** [open an issue](https://github.com/tdk-landscape/tdk-cli-core/issues/new/choose).
 - **Contributing:** see [CONTRIBUTING.md](CONTRIBUTING.md). Issues labeled [`good first issue`](https://github.com/tdk-landscape/tdk-cli-core/labels/good%20first%20issue) are a good place to start.
 - **Security:** see [SECURITY.md](SECURITY.md). Please don't report vulnerabilities in public issues.
-- **Examples:** [ERP system (100 services)](https://github.com/tdk-landscape/tdk-erp-system), [SaaS starter](https://github.com/tdk-landscape/tdk-saas-starter), [restaurant](https://github.com/tdk-landscape/tdk-restaurant-example).
+- **Examples:** [ERP system (100 services)](https://github.com/tdk-landscape/tdk-erp-system), [SaaS starter](https://github.com/tdk-landscape/tdk-saas-starter), [restaurant](https://github.com/tdk-landscape/tdk-restaurant-example), [ecommerce (Vue + Hono)](https://github.com/tdk-landscape/tdk-ecommerce-example).
 
 ## License
 

package/cli/dist/commands/doctor.js

@@ -7,6 +7,7 @@ import { hasVerdaccioLicense } from "../generator/extension-fetch.js";
 import { MASTER_CONFIG_FILES, QUICKSTART_DOCS_URL, REQUIRED_PACKAGE_SCRIPTS, } from "../utils/constants.js";
 import { isPathDiscovered, readDiscoveryPaths } from "../utils/discovery-paths.js";
 import { checkHealthRoutes, checkHostPorts, 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 { formatCount } from "../utils/formatting.js";
 import { findProjectRoot } from "../utils/paths.js";
@@ -795,6 +796,8 @@ export const doctorCommand = new Command("doctor")
         checkTilt,
         checkDockerCompose,
         checkDockerVersions,
+        // Each project needs several networks; a full address pool fails `tdk up` late.
+        () => checkDockerNetworkCapacity(),
     ];
     const projectChecks = [
         checkMasterConfigs,
@@ -806,6 +809,12 @@ export const doctorCommand = new Command("doctor")
         checkTypeScriptTypeDependencies,
         checkFrontendDockerPreflight,
         checkResourceDiscovery,
+        // Wiring mistakes that otherwise surface minutes into `tdk up`.
+        () => checkResourcePackageJson(),
+        () => checkServiceUrlPorts(),
+        () => checkFrontendBackendUrls(),
+        () => checkNatsBroker(),
+        () => checkTiltInstances(),
         checkEnvironmentVariables,
         // Preflight: catch "port 80 already allocated" BEFORE claiming ready.
         checkIngressPorts,

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

@@ -0,0 +1,261 @@
+import { execSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { formatCount } from "./formatting.js";
+import { findProjectRoot } from "./paths.js";
+import { discoverResourcesFromRoot } from "./services.js";
+/**
+ * Checks for wiring mistakes that only show up minutes into `tdk up`: an image
+ * build that cannot find package.json, a token check that cannot reach its
+ * identity provider, a frontend calling a port nothing publishes, a queue
+ * feature with no broker. Each one is decidable from the files on disk.
+ */
+const EXEC_TIMEOUT_MS = 10_000;
+const SOURCE_EXTENSIONS = /\.(?:[cm]?[jt]sx?|vue)$/;
+const TEST_FILE = /(?:\.test\.|\.spec\.|\/tests?\/|\/__tests__\/)/;
+const SKIPPED_DIRS = new Set(["node_modules", ".autogenerated", "dist", "tests", "__tests__"]);
+function projectName(projectRoot) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(projectRoot, ".tdk", "project.json"), "utf-8"));
+        return typeof parsed?.project?.name === "string" ? parsed.project.name : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function readParams(configPath) {
+    try {
+        const params = JSON.parse(readFileSync(configPath, "utf-8")).params;
+        return params && typeof params === "object" ? params : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** Backends are the only resources that listen on their `port`. */
+function backendPorts(resources) {
+    const ports = new Map();
+    for (const resource of resources) {
+        const port = resource.config?.port;
+        if (resource.config?.appType === "backend" && typeof port === "number") {
+            ports.set(resource.name, port);
+        }
+    }
+    return ports;
+}
+export function checkResourcePackageJson(projectRoot = findProjectRoot() ?? process.cwd()) {
+    const missing = discoverResourcesFromRoot(projectRoot)
+        .filter((resource) => !existsSync(join(resource.path, "package.json")))
+        .map((resource) => resource.name);
+    if (missing.length === 0) {
+        return {
+            name: "Resource package.json",
+            didPass: true,
+            message: "Every resource has a package.json",
+        };
+    }
+    return {
+        name: "Resource package.json",
+        didPass: false,
+        message: `${formatCount(missing.length, "resource")} without a package.json: ${missing.join(", ")}. The image build stops at "COPY .../package.json: not found"`,
+        fix: "Add a package.json next to each service.json (copy one from a working resource), or delete the folder's service.json if it is not a service",
+    };
+}
+const CONTAINER_URL = /https?:\/\/([a-z][a-z0-9-]*):(\d+)/g;
+export function checkServiceUrlPorts(projectRoot = findProjectRoot() ?? process.cwd()) {
+    const resources = discoverResourcesFromRoot(projectRoot);
+    const ports = backendPorts(resources);
+    const byPort = new Map([...ports].map(([name, port]) => [port, name]));
+    const problems = [];
+    for (const resource of resources) {
+        for (const [key, value] of Object.entries(readParams(resource.configPath))) {
+            for (const [, host, portText] of String(value).matchAll(CONTAINER_URL)) {
+                const port = Number(portText);
+                const expected = ports.get(host);
+                if (expected !== undefined && expected !== port) {
+                    problems.push(`${resource.name} param ${key}: ${host}:${port}, but ${host} listens on ${expected}`);
+                }
+                else if ((host === "localhost" || host === "127.0.0.1") &&
+                    byPort.has(port) &&
+                    byPort.get(port) !== resource.name) {
+                    problems.push(`${resource.name} param ${key}: localhost:${port} is ${resource.name} itself inside its container; ${byPort.get(port)} is reached as ${byPort.get(port)}:${port}`);
+                }
+            }
+        }
+    }
+    if (problems.length === 0) {
+        return {
+            name: "Service URL ports",
+            didPass: true,
+            message: "Service URLs in params point at the ports the services listen on",
+        };
+    }
+    return {
+        name: "Service URL ports",
+        didPass: false,
+        message: `${formatCount(problems.length, "service URL")} in params that cannot connect:\n    ${problems.join("\n    ")}`,
+        fix: 'TDK runs each backend on the "port" in its service.json, and containers reach each other by resource name (http://<resource>:<port>). Use that port in the URL',
+    };
+}
+function listSourceFiles(dir) {
+    const files = [];
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return files;
+    }
+    for (const entry of entries) {
+        const path = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (!SKIPPED_DIRS.has(entry.name))
+                files.push(...listSourceFiles(path));
+        }
+        else if (SOURCE_EXTENSIONS.test(entry.name) && !TEST_FILE.test(path)) {
+            files.push(path);
+        }
+    }
+    return files;
+}
+const LOCALHOST_PORT = /(?:localhost|127\.0\.0\.1):(\d{2,5})\b/g;
+const COMMENT_LINE = /^\s*(?:\/\/|\/\*|\*|<!--|#)/;
+export function checkFrontendBackendUrls(projectRoot = findProjectRoot() ?? process.cwd()) {
+    const resources = discoverResourcesFromRoot(projectRoot);
+    const byPort = new Map([...backendPorts(resources)].map(([name, port]) => [port, name]));
+    const problems = [];
+    for (const resource of resources.filter((r) => r.config?.appType === "frontend")) {
+        for (const file of listSourceFiles(join(resource.path, "src"))) {
+            readFileSync(file, "utf-8")
+                .split("\n")
+                .forEach((line, index) => {
+                if (COMMENT_LINE.test(line))
+                    return;
+                for (const [, portText] of line.matchAll(LOCALHOST_PORT)) {
+                    const backend = byPort.get(Number(portText));
+                    if (backend) {
+                        problems.push(`${relative(projectRoot, file)}:${index + 1} calls localhost:${portText} (${backend})`);
+                    }
+                }
+            });
+        }
+    }
+    if (problems.length === 0) {
+        return {
+            name: "Frontend backend URLs",
+            didPass: true,
+            message: "No frontend calls a backend through a localhost port",
+        };
+    }
+    const project = projectName(projectRoot) ?? "<project>";
+    return {
+        name: "Frontend backend URLs",
+        didPass: false,
+        message: `${formatCount(problems.length, "frontend call")} to a backend port that TDK does not publish on localhost:\n    ${problems.join("\n    ")}`,
+        fix: `Backends are only reachable through Traefik: http://api.${project}.localhost/api/<name without -api>/... (for example catalog-api is /api/catalog). Use that URL, or the generated .autogenerated/env.ts`,
+    };
+}
+export function checkNatsBroker(projectRoot = findProjectRoot() ?? process.cwd()) {
+    const users = discoverResourcesFromRoot(projectRoot)
+        .filter((resource) => resource.config?.featuresEnabled?.includes("nats"))
+        .map((resource) => resource.name);
+    if (users.length === 0) {
+        return {
+            name: "NATS broker",
+            didPass: true,
+            message: "No resource enables the nats feature",
+            isSkipped: true,
+        };
+    }
+    if (existsSync(join(projectRoot, "services", "platform", "messaging", "docker-compose.yml"))) {
+        return {
+            name: "NATS broker",
+            didPass: true,
+            message: `${formatCount(users.length, "resource")} enable nats and services/platform/messaging/docker-compose.yml is present`,
+        };
+    }
+    const name = (projectName(projectRoot) ?? "project").replace(/-/g, "_");
+    return {
+        name: "NATS broker",
+        didPass: false,
+        message: `${users.join(", ")} enable the nats feature, but no NATS server will start: TDK only starts one when services/platform/messaging/docker-compose.yml exists, and it does not generate that file`,
+        fix: `Create it with a "nats" service (image nats with -js, container_name ${name}_nats, network ${name}_backend, external) and a "redis" service, which TDK registers alongside it`,
+    };
+}
+export function parseTiltProcesses(psOutput) {
+    const processes = [];
+    for (const line of psOutput.split("\n")) {
+        const match = line.match(/^\s*(\d+)\s+.*\btilt up\b.*?\s-f\s+(\S+)/);
+        if (!match)
+            continue;
+        processes.push({ pid: Number(match[1]), root: match[2].split("/.tdk/")[0] });
+    }
+    return processes;
+}
+export function checkTiltInstances(projectRoot = findProjectRoot() ?? process.cwd(), exec = execSync) {
+    let output;
+    try {
+        output = exec("ps -Ao pid=,command=", { encoding: "utf-8", timeout: EXEC_TIMEOUT_MS });
+    }
+    catch {
+        return {
+            name: "Tilt processes",
+            didPass: true,
+            isSkipped: true,
+            message: "Could not list processes",
+        };
+    }
+    const running = parseTiltProcesses(output);
+    const mine = running.filter((p) => p.root === projectRoot);
+    const others = running.filter((p) => p.root !== projectRoot);
+    if (mine.length > 1) {
+        return {
+            name: "Tilt processes",
+            didPass: false,
+            message: `${mine.length} Tilt processes are running for this project (pids ${mine.map((p) => p.pid).join(", ")}). They fight over ports and containers`,
+            fix: `Stop them all, then start one: tdk down && kill ${mine.map((p) => p.pid).join(" ")} && tdk up`,
+        };
+    }
+    if (others.length > 0) {
+        const list = others.map((p) => `${p.root} (pid ${p.pid})`).join(", ");
+        return {
+            name: "Tilt processes",
+            didPass: true,
+            isSkipped: true,
+            message: `Another project's Tilt is running: ${list}`,
+            fix: "tdk up will use the next free Tilt UI port (10351, ...). If it is a leftover, run tdk down in that project",
+        };
+    }
+    return { name: "Tilt processes", didPass: true, message: "No stray Tilt processes" };
+}
+export function checkDockerNetworkCapacity(exec = execSync) {
+    const probe = `tdk_doctor_probe_${process.pid}`;
+    try {
+        exec(`docker network create ${probe}`, { stdio: "pipe", timeout: EXEC_TIMEOUT_MS });
+    }
+    catch (error) {
+        const stderr = String(error.stderr ?? error);
+        if (/address pools/i.test(stderr)) {
+            return {
+                name: "Docker networks",
+                didPass: false,
+                message: "Docker cannot create another network: all predefined address pools are in use. Each TDK project needs several",
+                fix: "docker network prune  (removes unused networks), or run tdk down in projects you are not using",
+            };
+        }
+        return {
+            name: "Docker networks",
+            didPass: true,
+            isSkipped: true,
+            message: "Could not test network creation",
+        };
+    }
+    try {
+        exec(`docker network rm ${probe}`, { stdio: "pipe", timeout: EXEC_TIMEOUT_MS });
+    }
+    catch {
+        // A leftover probe network is harmless and tdk_doctor_probe_* is easy to prune.
+    }
+    return { name: "Docker networks", didPass: true, message: "Docker can create networks" };
+}
+//# sourceMappingURL=doctor-wiring.js.map

package/cli/dist/utils/project-templates.js

@@ -16,6 +16,10 @@ export const PROJECT_TEMPLATES = {
         repo: "https://github.com/tdk-landscape/tdk-user-management.git",
         description: "User/auth management services",
     },
+    ecommerce: {
+        repo: "https://github.com/tdk-landscape/tdk-ecommerce-example.git",
+        description: "Vue 3 storefront and Hono catalog API (needs TDK 1.3.75+ for --framework vue)",
+    },
     example: {
         repo: "https://github.com/tdk-landscape/tdk-example.git",
         description: "Minimal Project-Stack-Resource (PSR) demonstration",

package/cli/package.json

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

package/cli/templates/Tiltfile.hbs

@@ -279,9 +279,30 @@ if FOCUS_MODE and FOCUS_ENABLED_RESOURCES:
         else:
             _MATCHED = [kr for kr in _KNOWN_TILT_RESOURCES if kr != 'service-discovery-daemon' and kr.startswith(_R + '-')]
             _FILTERED_RESOURCES.extend(_MATCHED)
-    for _INFRA in ['init-networks', 'postgres', 'traefik', 'golden-layers-build']:
-        if _INFRA in _KNOWN_TILT_RESOURCES:
-            _FILTERED_RESOURCES.append(_INFRA)
+    # NATS is gated by the same 'database-management' should_enable() check as
+    # postgres (see infra-loader.star), so it belongs with the infra that is
+    # always kept enabled here -- otherwise config.set_enabled_resources()
+    # below disables it on every out-of-the-box `tdk up` (pre-alpha always
+    # activates this focus-filter branch), and any resource that enables the
+    # 'nats' feature never gets a broker to connect to.
+    #
+    # services/platform/messaging/docker-compose.yml is user-authored (TDK
+    # does not generate it) and may declare more than nats/redis -- e.g. a
+    # local mail catcher standing in for a managed email provider. Every
+    # service it declares is loaded via docker_compose() in infra-loader.star,
+    # so it must be enabled here too, or it is silently disabled the same way.
+    _ALWAYS_ENABLED_INFRA_RESOURCES = ['init-networks', 'postgres', 'traefik', 'golden-layers-build']
+    _messaging_compose_path = PROJECT_ROOT + '/services/platform/messaging/docker-compose.yml'
+    if str(local("test -f '" + _messaging_compose_path + "' && echo yes || echo no", quiet=True, echo_off=True)).strip() == 'yes':
+        # infra-loader.star only creates these Tilt resources when this file
+        # exists, so only add them here when they actually exist to add.
+        _messaging_compose_doc = read_yaml(_messaging_compose_path, default={})
+        for _messaging_svc_name in _messaging_compose_doc.get('services', {}).keys():
+            _ALWAYS_ENABLED_INFRA_RESOURCES.append(_messaging_svc_name)
+        if 'nats' not in _ALWAYS_ENABLED_INFRA_RESOURCES:
+            _ALWAYS_ENABLED_INFRA_RESOURCES.append('nats')
+    for _INFRA in _ALWAYS_ENABLED_INFRA_RESOURCES:
+        _FILTERED_RESOURCES.append(_INFRA)
     for _KR in _KNOWN_TILT_RESOURCES:
         if _KR.startswith('provision-db-'):
             _FILTERED_RESOURCES.append(_KR)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tdk-landscape/tdk-cli-core",
-  "version": "1.3.75",
+  "version": "1.3.76",
   "description": "Run your whole microservice landscape locally without Kubernetes. Scaffold services and run them with hot reload, built on Tilt.",
   "homepage": "https://tdk-landscape.github.io/tdk-website",
   "repository": {