@tdk-landscape/tdk-cli-core 1.3.110 → 1.3.112

package/CHANGELOG.md

@@ -4,6 +4,17 @@ Notable changes to the `tdk` CLI. Versions match [npm](https://www.npmjs.com/pac
 
 ## Unreleased
 
+- `tdk eject` no longer claims files it does not create or prints a command that cannot work. It still writes only `EJECTED.md` (no file is copied, moved or generated; the Tiltfile and engine stay in git-ignored `.tdk/.tdk-out/`, and the per-service Compose files, golden-layer Dockerfile and Traefik file only exist after Tilt has run). `EJECTED.md` no longer lists them under "Keep" and says the Tiltfile still reads `.tdk/project.json` and the `service.json` files. `Next: tilt up` (which finds no Tiltfile at the project root) is replaced by `tilt up -f .tdk/.tdk-out/Tiltfile -- --focus=<stack>`, the form `tdk up` runs. A project that already has an `EJECTED.md` keeps its old text (the file is never overwritten) and is now told so. `--dry-run` headings read `Generated files, left where they are (git-ignored):` and `Files written:`. A command that exports plain Compose files and Dockerfiles does not exist. Fixes #610.
+- `tdk config regenerate` now restores a root `.tiltignore` that TDK wrote (it carries the `SYSTEM-GENERATED BY TDK CLI` header) and that was edited by hand, and prints `Restored: .tiltignore → project root (hand edits discarded)`. Before, it only copied the file when none existed, so `tdk config verify` kept failing with `Out of sync: .tiltignore (run 'tdk config regenerate')` after the advice was followed. A root `.tiltignore` without the header is still never overwritten, and plain `tdk project --yes` still does not overwrite an existing one. Docs: `docs/adopt-tdk.md` now quotes the current `tdk doctor` unknown-field wording.
+- `tdk doctor` now checks the project's own resource configs for duplicates. Two resources with the same `appName` fail (`Duplicate resource names`, naming both `service.json` paths): the name becomes the Compose service and Traefik router, so they collide, and before nothing reported it. Two backend, mcp or routed bring-your-own resources on the same `port` give a warning, not a failure (`Duplicate resource ports`): service ports are not published on the host and each service has its own container, so the pair can run, but it is usually a copied `service.json`. Frontends, workers, libraries and a missing `port` are ignored. Fixes #76.
+- `tdk doctor` no longer fails with `N resources without a package.json` for a bring-your-own resource. A bring-your-own resource (`--image`, `--dockerfile` or `buildContext`) is a plain container: its image is pulled or built from its own Dockerfile, never from the generated Dockerfile that copies a `package.json`, so the check was a false positive that made `tdk doctor` (and CI recipes that gate on it) exit non-zero right after wrapping an existing service. Backend, frontend, worker, migrator, mcp, library and sdk resources without a `package.json` still fail; Python, Go and Rust backends were already exempt. The other doctor checks were run on a project with only bring-your-own resources and report nothing. Fixes #599.
+- A scaffolded frontend now says why `bun run build` / `bun run dev` cannot run on the host before `tdk up`: the `.autogenerated/vite.config.*.autogenerated.ts` files its scripts point at are written by the engine (Tilt) when `tdk up` loads the resource, and neither `tdk resource` nor `tdk config regenerate` creates them. Before, `vite` stopped with an esbuild `Could not resolve` stack trace. New `predev`/`prebuild` scripts print what is missing and how to get it; once the file exists (and inside the engine image build) they pass silently. Existing frontends need the two scripts added by hand. Backend, worker and mcp scaffolds are unchanged. Fixes #592.
+- `tdk up` now honours `minTdkVersion` from `.tdk/project.json`, like `tdk doctor`. On an older CLI (or a malformed value) it exits 1 before the Docker checks and before Tilt starts, with `tdk X is older than the Y this project requires (minTdkVersion)` and `Run: tdk upgrade`; `--dry-run` reports it the same way. New `tdk up --ignore-version` skips the check with a warning. A project without `minTdkVersion` behaves as before. The check lives in `cli/src/utils/tdk-version.ts`, shared with doctor.
+- `init-networks` now fails with Docker's own message when a network that does not exist cannot be created. It ran `docker network create X 2>/dev/null && echo ... || true`, so a failure such as `all predefined address pools have been fully subnetted` was reported as `Docker networks initialized` and Postgres and Traefik then failed with `network ... declared as external, but could not be found`. An already existing network (including one another process creates between the check and the create) is still not an error, and a network with incorrect compose labels is still removed first when unused. Fixes #587.
+- A freshly scaffolded worker now type-checks: its `src/index.ts` typed `Job.payload` as `Record<string, JsonValue>`, but `JsonValue` is a type internal to the CLI that the generated project neither defines nor imports, so `bun run build` failed with `TS2304: Cannot find name 'JsonValue'`. The payload is now `Record<string, unknown>`. Existing workers need the same one-word edit. Fixes #588.
+- A freshly scaffolded backend, worker or mcp service now builds on the host: its `tsconfig.json` sets `"types": ["node"]`, matching the generated Docker tsconfig. Before, `bun run build` failed with `TS2591: Cannot find name 'process'` because TypeScript 7 no longer auto-includes `@types/*`. Frontend scaffolds are unchanged. Existing services need `"types": ["node"]` added by hand. Closes #581.
+- The `Dockerfile` that `tdk resource` writes next to `service.json` now follows the service: `PORT`, `EXPOSE` and the health check use the `port` (and `healthCheckPath`) from `service.json` instead of a fixed 3000, the health probe no longer needs `curl` (not in `oven/bun`), `bun.lock` is optional in the `COPY` (a TDK workspace keeps it at the project root, so the old file stopped at `"/bun.lock": not found`), and a header comment says `tdk up` does not build this file (it builds `.autogenerated/Dockerfile.app.autogenerated`). A worker, which declares no health path, gets no HEALTHCHECK. Fixes #579.
+- `tdk down` now removes what `tdk up <stack>` started. It ran `tilt down` without `--focus`, so the Tiltfile fell back to its default phase and did not register the stack's own compose project: the generated service container (`shop-autogenerated-orders-api-1`) kept running and only Traefik and Postgres were removed. It now passes every stack to the Tiltfile, and it stops the project's own `tilt up` process first (it kept running, and a live Tilt re-creates removed containers). Only a `tilt up` started with this project's Tiltfile is stopped. New `tdk down --prune-networks` also removes the project's Docker networks (`<project>_backend`, `_database`, `_traefik-public`, ...) that no container is attached to; without the flag they are kept, as before. `tdk doctor`'s "all predefined address pools are in use" fix now names it.
 - `tdk config verify` no longer fails on a root `.tiltignore` the repository already had. `tdk project` never overwrote it, but verify compared it with the generated one and reported `Out of sync: .tiltignore`; it now warns `not generated by TDK, left as is`. A `.tiltignore` carrying TDK's generated header that was edited is still reported. Refs #568.
 - A repo can pin the oldest CLI it works with: add `"minTdkVersion": "1.3.80"` to `.tdk/project.json`, and `tdk doctor` fails with `Run: tdk upgrade` on an older `tdk` (a value that is not `MAJOR.MINOR.PATCH` also fails). It is a floor, not an exact pin. Documented in `docs/upgrading.md`. Refs #564.
 - `tdk doctor` warns when a backend or worker applies database migrations from its own start-up (a `start`/`dev` script, a Dockerfile `CMD`/`ENTRYPOINT`, a shell entrypoint or its source: Prisma, Drizzle, Knex, TypeORM, MikroORM, Sequelize, dbmate, Atlas, Alembic). It is a warning, not a failure: such services work, but migrations belong in a `migrator` resource that runs once before the services that depend on it. `migrator` and bring-your-own resources are not checked.

package/README.md

@@ -69,6 +69,15 @@ curl -fsSL https://tdk-landscape.github.io/install.sh | sh
 - [Pilot TDK on a real repository](docs/adopt-tdk.md)
 - [FAQ for agencies and multi-client teams](docs/faq-teams.md)
 - [Working alongside Helm](docs/with-helm.md)
+- [Scope: local development, and what does not carry over to production](docs/scope.md)
+- [Gradual adoption: adding TDK to an existing repository](docs/gradual-adoption.md)
+- [Troubleshooting: tdk and Tilt error messages and their fixes](docs/troubleshooting.md)
+- [Layout and ownership: services in several repositories](docs/layout.md)
+- [Local data: reset, seed, snapshot](docs/data.md)
+- [Upgrading and version pinning](docs/upgrading.md)
+- [Security: network calls, secrets and supply chain](docs/security.md)
+- [Pilot scorecard](docs/pilot-scorecard.md)
+- [Bring-your-own resources](docs/byo.md)
 - [Configuration and editor schemas](docs/configuration.md)
 - [Runnable one-backend example](examples/one-backend/README.md)
 - [Runnable Python backend example](examples/one-backend-python/README.md)

package/cli/dist/commands/completion.js

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 import chalk from "chalk";
 import { Command } from "commander";
 const BASH_COMPLETION = `# TDK CLI Bash Completion
@@ -250,12 +250,22 @@ const POWERSHELL_COMPLETION = `Register-ArgumentCompleter -Native -CommandName t
 const POWERSHELL_START = "# TDK-CLI-COMPLETION-START";
 const POWERSHELL_END = "# TDK-CLI-COMPLETION-END";
 export const completionCommand = new Command("completion")
+    .argument("[shell]", "Target shell (bash, zsh, fish, powershell)")
     .description("Generate shell completion scripts")
-    .option("-s, --shell <shell>", "Target shell (bash, zsh, fish, powershell)", "bash")
+    .option("-s, --shell <shell>", "Target shell (bash, zsh, fish, powershell)")
     .option("-o, --output <path>", "Output file path (default: stdout)")
     .option("--install", "Install to shell config automatically")
-    .action((options) => {
-    const shell = options.shell.toLowerCase();
+    .action((shellArgument, options) => {
+    const requestedShell = options.shell ?? shellArgument;
+    const environmentShell = basename(process.env.SHELL ?? "")
+        .replace(/\.exe$/i, "")
+        .toLowerCase();
+    const supportedShells = ["bash", "zsh", "fish", "powershell"];
+    const defaultShell = supportedShells.includes(environmentShell) ? environmentShell : "bash";
+    const shell = (requestedShell ?? defaultShell).toLowerCase();
+    if (requestedShell === undefined) {
+        console.error(chalk.gray(`Using ${shell} completion`));
+    }
     let completionScript;
     let filename;
     switch (shell) {

package/cli/dist/commands/config.js

@@ -116,7 +116,7 @@ export const configCommand = new Command("config")
             return;
         }
         console.log(chalk.blue("📋 Regenerating master configuration files...\n"));
-        await generateMasterConfigs(projectRoot);
+        await generateMasterConfigs(projectRoot, { discardHandEdits: true });
         console.log(chalk.green("\n✅ Configuration regenerated!"));
     });
 }))

package/cli/dist/commands/doctor.js

@@ -9,7 +9,7 @@ import { MASTER_CONFIG_FILES, REQUIRED_PACKAGE_SCRIPTS } from "../utils/constant
 import { isPathDiscovered, readDiscoveryPaths } from "../utils/discovery-paths.js";
 import { collectDoctorChecks, createDoctorReport, getDoctorExitCode, } from "../utils/doctor-report.js";
 import { checkHealthRoutes, checkIngressPorts, checkPrivateNpmRegistry, checkTiltResourceHealth, projectConfigEnablesVerdaccio, summarizeServiceProbes, } from "../utils/doctor-runtime.js";
-import { checkDockerNetworkCapacity, checkFrontendBackendUrls, checkMigrationsInApi, checkNatsBroker, checkResourcePackageJson, checkServiceUrlPorts, checkTiltInstances, } from "../utils/doctor-wiring.js";
+import { checkDockerNetworkCapacity, checkDuplicateResourceNames, checkDuplicateResourcePorts, checkFrontendBackendUrls, checkMigrationsInApi, 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";
@@ -19,6 +19,7 @@ import { findProjectRoot, getPackageVersion } from "../utils/paths.js";
 import { isApiServiceType } from "../utils/resource-kind.js";
 import { buildHealthTargets, pingHealthTargets } from "../utils/service-urls.js";
 import { discoverResourcesFromRoot } from "../utils/services.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";
 // A wedged Docker daemon makes `docker ps` block forever instead of failing,
@@ -431,15 +432,8 @@ export function checkTdkVersion(currentVersion = getPackageVersion()) {
             message: "Not in a project - skipping TDK version check",
         };
     }
-    let minimum;
-    try {
-        const parsed = JSON.parse(readFileSync(join(projectRoot, ".tdk", "project.json"), "utf-8"));
-        minimum = parsed?.minTdkVersion;
-    }
-    catch {
-        minimum = undefined;
-    }
-    if (minimum === undefined) {
+    const floor = evaluateTdkVersionFloor(projectRoot, currentVersion);
+    if (floor.status === "none") {
         return {
             name: "TDK version",
             didPass: true,
@@ -447,27 +441,13 @@ export function checkTdkVersion(currentVersion = getPackageVersion()) {
             message: `tdk ${currentVersion} (no minTdkVersion in .tdk/project.json)`,
         };
     }
-    const required = typeof minimum === "string" ? parseVersion(minimum) : null;
-    if (!required || !/^\d+\.\d+\.\d+$/.test(String(minimum).trim())) {
-        return {
-            name: "TDK version",
-            didPass: false,
-            message: `.tdk/project.json minTdkVersion ${JSON.stringify(minimum)} is not a version like "1.3.80"`,
-            fix: 'Set minTdkVersion to a MAJOR.MINOR.PATCH string, for example "1.3.80".',
-        };
-    }
-    if (!versionMeetsMinimum(currentVersion, required)) {
-        return {
-            name: "TDK version",
-            didPass: false,
-            message: `tdk ${currentVersion} is older than the ${required.join(".")} this project requires (minTdkVersion)`,
-            fix: "Run: tdk upgrade",
-        };
+    if (floor.status === "malformed" || floor.status === "too-old") {
+        return { name: "TDK version", didPass: false, message: floor.message, fix: floor.fix };
     }
     return {
         name: "TDK version",
         didPass: true,
-        message: `tdk ${currentVersion} meets minTdkVersion ${required.join(".")}`,
+        message: `tdk ${currentVersion} meets minTdkVersion ${floor.required}`,
     };
 }
 /**
@@ -1158,6 +1138,8 @@ export const doctorCommand = new Command("doctor")
         checkResourceDiscovery,
         // Wiring mistakes that otherwise surface minutes into `tdk up`.
         () => checkResourcePackageJson(),
+        () => checkDuplicateResourceNames(),
+        () => checkDuplicateResourcePorts(),
         () => checkServiceUrlPorts(),
         () => checkFrontendBackendUrls(),
         () => checkNatsBroker(),

package/cli/dist/commands/down.js

@@ -1,13 +1,50 @@
 import chalk from "chalk";
 import { Command } from "commander";
+import { readProjectConfig } from "../generator/template-engine.js";
 import { handleDryRun } from "../utils/command-helpers.js";
+import { pruneProjectNetworks, stopProjectTiltUp, waitForTiltUpExit, } from "../utils/down-cleanup.js";
 import { handleTiltFailure, withTiltCheck } from "../utils/errors.js";
 import { createJsonEmitter } from "../utils/json-output.js";
-import { buildTiltDownArgs, runTilt } from "../utils/tilt.js";
+import { findProjectRoot } from "../utils/paths.js";
+import { discoverResources, discoverStacks } from "../utils/services.js";
+import { buildTiltDownArgs, getTiltfilePath, runTilt } from "../utils/tilt.js";
+function allStackNames() {
+    try {
+        const names = discoverStacks(discoverResources()).map((stack) => stack.name);
+        return names.length > 0 ? names : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function pruneNetworksOrWarn(json) {
+    const root = findProjectRoot();
+    if (!root)
+        return undefined;
+    try {
+        const result = pruneProjectNetworks(readProjectConfig(root).project.name);
+        if (!json) {
+            if (result.removed.length > 0) {
+                console.log(chalk.gray(`Removed networks: ${result.removed.join(", ")}`));
+            }
+            for (const kept of result.kept) {
+                console.log(chalk.yellow(`Kept network ${kept.name}: ${kept.reason}`));
+            }
+        }
+        return result;
+    }
+    catch (err) {
+        if (!json) {
+            console.log(chalk.yellow(`Could not remove networks: ${err.message}`));
+        }
+        return undefined;
+    }
+}
 export const downCommand = new Command("down")
     .description("Stop all tilt resources")
     .option("-v, --verbose", "Enable verbose output", false)
     .option("-f, --force", "Skip confirmation", false)
+    .option("--prune-networks", "Also remove this project's Docker networks (only those no container is attached to)", false)
     .option("--dry-run", "Show what would be stopped without stopping", false)
     .option("--json", "Print one JSON object on stdout; implies quiet human output", false)
     .action(async (options) => {
@@ -22,7 +59,22 @@ export const downCommand = new Command("down")
         }
         const tiltArgs = buildTiltDownArgs({
             force: options.force,
+            focusTargets: allStackNames(),
         });
+        // Stop `tilt up` first: `tilt down` does not end it, and a live Tilt re-creates the containers `tilt down` just removed.
+        let stoppedTilt = [];
+        try {
+            const tiltfile = getTiltfilePath();
+            stoppedTilt = stopProjectTiltUp(tiltfile);
+            if (stoppedTilt.length > 0)
+                await waitForTiltUpExit(tiltfile);
+        }
+        catch {
+            // Not fatal: the containers are already down.
+        }
+        if (stoppedTilt.length > 0 && !options.json) {
+            console.log(chalk.gray(`Stopped tilt up (pid ${stoppedTilt.join(", ")}).`));
+        }
         if (!options.json)
             console.log(chalk.blue("Stopping all tilt resources..."));
         if (options.verbose && !options.json) {
@@ -35,7 +87,15 @@ export const downCommand = new Command("down")
         if (result.exitCode !== 0) {
             handleTiltFailure("down", result.exitCode);
         }
-        emit?.({ ok: true });
+        let networks;
+        if (options.pruneNetworks) {
+            networks = pruneNetworksOrWarn(options.json);
+        }
+        emit?.({
+            ok: true,
+            stoppedTilt,
+            ...(networks ? { removedNetworks: networks.removed, keptNetworks: networks.kept } : {}),
+        });
     });
 });
 //# sourceMappingURL=down.js.map

package/cli/dist/commands/eject.js

@@ -5,25 +5,44 @@ import { Command } from "commander";
 import { confirmOrCancel } from "../utils/command-helpers.js";
 import { runCommand } from "../utils/errors.js";
 import { findProjectRoot } from "../utils/paths.js";
+// Same location `tdk up` hands to Tilt (see getTiltfilePath in utils/tilt.ts), relative to the project root.
+export const TILTFILE_RELATIVE_PATH = ".tdk/.tdk-out/Tiltfile";
+export const TILT_UP_COMMAND = `tilt up -f ${TILTFILE_RELATIVE_PATH} -- --focus=<stack>`;
 export const EJECTED_CONTENT = `# Ejected from TDK
 
-These files were generated by TDK. You can keep using Docker and Tilt without the tdk CLI.
+\`tdk eject\` wrote this file and nothing else. It did not copy, move or generate anything, and it did
+not remove TDK. What exists is what TDK had already generated, and that is still TDK-owned output.
 
-Keep:
-- Tiltfile
-- Dockerfiles
-- compose files TDK wrote
-- Traefik / proxy config TDK wrote
+## Where the generated files are
 
-Optional to delete later:
-- .tdk/
-- service.json files (only if you no longer want tdk up)
+- \`.tdk/.tdk-out/\` holds the Tiltfile and the engine it loads (\`tdk-cli-ext/\`). It is git-ignored.
+  \`tdk config regenerate\` rewrites the master files in it.
+- The per-service Compose files (\`services/<stack>/<name>/.autogenerated/\`), the golden-layer
+  Dockerfile and the Traefik file (\`.tdk/.tdk-out/\`) are written by Tilt when it runs, not by
+  \`tdk eject\`. Until Tilt has run they do not exist. They are git-ignored too.
+- Your own Dockerfiles, \`service.json\` files and source code are untouched.
 
-To go back: install TDK and run \`tdk config regenerate\`.
+## Running the stack without the tdk CLI
+
+There is no Tiltfile at the project root, so a plain \`tilt up\` does not find one. TDK runs:
+
+    ${TILT_UP_COMMAND}
+
+from the project root (\`<stack>\` is a stack name under \`services/\`; without \`--focus\` the Tiltfile
+falls back to its default phase). The Tiltfile still reads \`.tdk/project.json\` and the
+\`service.json\` files, so those must stay. \`tdk up\` also does steps before Tilt starts (it chooses
+host ports and exports them to Tilt); running Tilt by hand skips them.
+
+## Cleaning up
+
+Optional to delete later: this file, and \`.tdk/\` plus the \`service.json\` files if you stop using TDK.
+Deleting them also removes what the Tiltfile needs.
+
+To go back to TDK: install it and run \`tdk config regenerate\`.
 `;
 export const ejectCommand = new Command("eject")
-    .description("Take ownership of the generated Tilt and Docker files")
-    .option("--dry-run", "List generated files without changing the project", false)
+    .description("Write EJECTED.md describing the generated Tilt files (copies and generates nothing; they stay in .tdk/.tdk-out/)")
+    .option("--dry-run", "List the generated files and what would be written, without changing the project", false)
     .option("--yes", "Skip the confirmation prompt", false)
     .action(async (options) => {
     await runCommand(async () => {
@@ -48,15 +67,19 @@ export const ejectCommand = new Command("eject")
             throw new Error("Generated Tilt files are missing. Run `tdk project --yes` before ejecting.");
         }
         const rootTiltfile = join(projectRoot, "Tiltfile");
-        if (existsSync(rootTiltfile))
-            files.push("Tiltfile");
+        const userTiltfile = existsSync(rootTiltfile) ? ["Tiltfile"] : [];
         const ejectedPath = join(projectRoot, "EJECTED.md");
         const willCreate = existsSync(ejectedPath) ? [] : ["EJECTED.md"];
         if (options.dryRun) {
-            console.log("Files kept:");
+            console.log("Generated files, left where they are (git-ignored):");
             for (const path of files)
                 console.log(`  ${path}`);
-            console.log("Files created:");
+            if (userTiltfile.length > 0) {
+                console.log("Root Tiltfile, left where it is (not generated, not git-ignored):");
+                for (const path of userTiltfile)
+                    console.log(`  ${path}`);
+            }
+            console.log("Files written:");
             for (const path of willCreate)
                 console.log(`  ${path}`);
             if (willCreate.length === 0)
@@ -64,13 +87,19 @@ export const ejectCommand = new Command("eject")
             return;
         }
         if (!options.yes &&
-            !(await confirmOrCancel("Take ownership of the generated Tilt and Docker files?"))) {
+            !(await confirmOrCancel("Write EJECTED.md? (Generated files stay in .tdk/.tdk-out/; nothing is copied or moved.)"))) {
             return;
         }
-        if (!existsSync(ejectedPath))
+        if (existsSync(ejectedPath)) {
+            console.log(chalk.green("EJECTED.md already exists and was left unchanged. Nothing was copied, moved or generated."));
+        }
+        else {
             writeFileSync(ejectedPath, EJECTED_CONTENT, { flag: "wx" });
-        console.log(chalk.green("Ejected. Tilt and Docker files are yours."));
-        console.log("Next: tilt up");
+            console.log(chalk.green("Wrote EJECTED.md. Nothing was copied, moved or generated."));
+        }
+        console.log("Generated files stay in .tdk/.tdk-out/ (git-ignored) and still need TDK inputs.");
+        console.log(`Run from the project root: ${TILT_UP_COMMAND}`);
+        console.log("Replace <stack> with a stack name under services/, or omit --focus to use the Tiltfile's default phase.");
         console.log("Read EJECTED.md");
     });
 });

package/cli/dist/commands/resource.js

@@ -128,6 +128,19 @@ export function createByoServiceJson(name, stack, port, options) {
         ...(options.restart ? { restart: options.restart } : {}),
     };
 }
+/**
+ * The Vite configs a frontend's `dev`/`build` scripts point at are written by the engine
+ * (Tilt loads the Starlark generator in `tdk up`), not by `tdk resource`. Without them
+ * `vite` stops with an esbuild "Could not resolve" stack trace, so the pre-scripts say what
+ * is missing instead. Inside the engine's image build the file exists and the check passes.
+ */
+function requireGeneratedViteConfig(configPath) {
+    // The text sits inside single quotes in a shell command: no quotes, backticks or parentheses.
+    const message = `${configPath} does not exist yet. TDK engine writes it when tdk up loads this resource ` +
+        "(needs Docker); tdk resource and tdk config regenerate do not create it. " +
+        "Run tdk up <stack> once, or point this script at your own Vite config to build on the host.";
+    return `bun -e 'if(!require("fs").existsSync(${JSON.stringify(configPath)})){console.error(${JSON.stringify(message)});process.exit(1)}'`;
+}
 export function createPackageJson(name, type, frameworkId) {
     const isFrontend = type === "frontend";
     const framework = resolveFrontendFramework(type, frameworkId);
@@ -137,6 +150,12 @@ export function createPackageJson(name, type, frameworkId) {
         version: "0.0.1",
         type: "module",
         scripts: {
+            ...(isFrontend
+                ? {
+                    predev: requireGeneratedViteConfig(".autogenerated/vite.config.frontend.autogenerated.ts"),
+                    prebuild: requireGeneratedViteConfig(".autogenerated/vite.config.build.autogenerated.ts"),
+                }
+                : {}),
             dev: isFrontend
                 ? "vite --config .autogenerated/vite.config.frontend.autogenerated.ts"
                 : "bun run --watch src/index.ts",
@@ -174,6 +193,10 @@ export function createResourceTsconfig(resourceType, frameworkId) {
         ...TSCONFIG_TEMPLATE,
         compilerOptions: {
             ...TSCONFIG_TEMPLATE.compilerOptions,
+            // TypeScript 7 does not auto-include @types/*: without this, `tsc` fails with TS2591 on
+            // `process`/`Buffer`. "node" matches the generated Docker tsconfig. Frontends target the
+            // DOM and keep the default.
+            ...(resourceType === "frontend" ? {} : { types: ["node"] }),
             ...(framework?.compilerOptions ?? {}),
             ...(backendFramework?.compilerOptions ?? {}),
         },
@@ -197,15 +220,33 @@ export const TSCONFIG_TEMPLATE = {
     include: ["src/**/*"],
     exclude: ["node_modules", "dist"],
 };
-export const DOCKERFILE_TEMPLATE = `FROM oven/bun:1.2
+/**
+ * The plain `Dockerfile` written next to service.json. `tdk up` does not build it: for generated
+ * resources the engine builds `.autogenerated/Dockerfile.app.autogenerated`. It is a starting point
+ * for building the service image outside TDK, so its port follows the service's `port`.
+ */
+export function getDockerfileTemplate(port, healthCheckPath) {
+    // `oven/bun` has no curl, so the probe uses bun itself.
+    const healthcheck = healthCheckPath
+        ? `# Health check
+HEALTHCHECK --interval=10s --timeout=5s --retries=3 \\
+  CMD bun -e "fetch('http://localhost:${port}${healthCheckPath}').then((r) => process.exit(r.ok ? 0 : 1), () => process.exit(1))"
+
+`
+        : "";
+    return `# Scaffolded by \`tdk resource\`. \`tdk up\` does NOT build this file: it builds
+# .autogenerated/Dockerfile.app.autogenerated (golden layers, project root as context).
+# Use this one as a starting point for building the image outside TDK, and keep its
+# port in step with "port" in service.json.
+FROM oven/bun:1.2
 
 WORKDIR /app
 
-# Copy package files
-COPY package.json bun.lock ./
+# Copy package files (bun.lock is optional: a TDK workspace keeps it at the project root)
+COPY package.json bun.lock* ./
 
 # Install dependencies
-RUN bun install --frozen-lockfile
+RUN bun install
 
 # Copy source
 COPY . .
@@ -213,14 +254,12 @@ COPY . .
 # Build if needed
 RUN bun run build
 
-# Health check
-HEALTHCHECK --interval=10s --timeout=5s --retries=3 \\
-  CMD curl -f http://localhost:3000/health || exit 1
-
-EXPOSE 3000
+${healthcheck}ENV PORT=${port}
+EXPOSE ${port}
 
 CMD ["bun", "run", "start"]
 `;
+}
 export { getBackendIndexTemplate };
 function getShutdownHandlerTemplate(signal) {
     return `process.on('${signal}', () => {
@@ -234,7 +273,7 @@ export function getWorkerIndexTemplate(name) {
 interface Job {
   id: string;
   type: string;
-  payload: Record<string, JsonValue>;
+  payload: Record<string, unknown>;
   priority?: number;
   timestamp?: string;
 }
@@ -328,7 +367,7 @@ export const resourceCommand = new Command("resource")
     .option("-p, --path <path>", "Custom path for resource directory")
     .option("--resource-path <path>", "Alias for --path (for backward compatibility)")
     .option("--register-existing", "Register an existing resource without creating templates")
-    .option("-y, --yes", "Skip confirmation prompt", false)
+    .option("-y, --yes", "Run without prompts; use defaults", false)
     .option("--ddd", "Scaffold DDD (domain-driven design) folders + path aliases (Premium - requires TDK_LICENSE_KEY)")
     .option("--dockerfile <path>", "Path to Dockerfile relative to resource dir (for bring-your-own)")
     .option("--health-path <path>", "HTTP health check path (for bring-your-own)", "/health")
@@ -350,6 +389,11 @@ export const resourceCommand = new Command("resource")
         showCommandHeader("Resource Creation");
         const allResources = discoverResources();
         let resourceName = name;
+        if (!resourceName && options.yes) {
+            throw new TdkError("A resource name is required when using --yes.", [
+                "Pass the name explicitly, for example: tdk resource api --yes.",
+            ]);
+        }
         if (!resourceName) {
             const inputName = await promptText({
                 message: "Resource name (kebab-case):",
@@ -411,27 +455,40 @@ export const resourceCommand = new Command("resource")
             }
             const existingStacks = Array.from(stackSet);
             if (existingStacks.length > 0) {
-                const selectedStack = await promptSelect({
-                    message: "Assign to stack:",
-                    choices: [
-                        ...existingStacks.map((s) => ({ title: s, value: s })),
-                        { title: "Create new stack", value: "__new__" },
-                    ],
-                });
-                if (selectedStack === "__new__") {
-                    const newStack = await promptText({
-                        message: "New stack name:",
-                        validate: (input) => {
-                            const validation = createKebabCaseValidator("stack")(input);
-                            return validation === true || validation;
-                        },
-                    });
-                    stackName = newStack;
+                if (options.yes) {
+                    if (existingStacks.length > 1) {
+                        throw new TdkError("Multiple stacks exist; specify --stack when using --yes.", [
+                            `Available stacks: ${existingStacks.join(", ")}`,
+                        ]);
+                    }
+                    stackName = existingStacks[0] ?? "main";
                 }
                 else {
-                    stackName = selectedStack;
+                    const selectedStack = await promptSelect({
+                        message: "Assign to stack:",
+                        choices: [
+                            ...existingStacks.map((s) => ({ title: s, value: s })),
+                            { title: "Create new stack", value: "__new__" },
+                        ],
+                    });
+                    if (selectedStack === "__new__") {
+                        const newStack = await promptText({
+                            message: "New stack name:",
+                            validate: (input) => {
+                                const validation = createKebabCaseValidator("stack")(input);
+                                return validation === true || validation;
+                            },
+                        });
+                        stackName = newStack;
+                    }
+                    else {
+                        stackName = selectedStack;
+                    }
                 }
             }
+            else if (options.yes) {
+                stackName = "main";
+            }
             else {
                 const newStack = await promptText({
                     message: "Stack name (first resource):",
@@ -651,7 +708,9 @@ This file contains the resource configuration for TDK.
             {
                 type: "text",
                 filename: "Dockerfile",
-                content: DOCKERFILE_TEMPLATE,
+                content: getDockerfileTemplate(serviceJson.port, typeof serviceJson.healthCheckPath === "string"
+                    ? serviceJson.healthCheckPath
+                    : undefined),
                 description: "Generating Dockerfile",
                 emoji: "🐳",
             },

package/cli/dist/commands/resources.js

@@ -1,15 +1,18 @@
 import chalk from "chalk";
 import { Command } from "commander";
+import { VALID_RESOURCE_TYPES } from "../utils/constants.js";
 import { createDiscoveryContext } from "../utils/discovery-context.js";
-import { errorFactories, requireProjectRoot, runCommand } from "../utils/errors.js";
+import { errorFactories, requireProjectRoot, runCommand, TdkError } from "../utils/errors.js";
 import { formatCount, showAllSatisfyCondition, showDetail, showEmptyState, showStep, } from "../utils/formatting.js";
 import { createMachineEnvelope, writeMachineError } from "../utils/machine-output.js";
 import { findProjectRoot } from "../utils/paths.js";
 import { stackExists } from "../utils/services.js";
+import { includes } from "../utils/validation.js";
 export const resourcesCommand = new Command("resources")
     .description("List all resources (services) in the project")
     .option("-v, --verbose", "Show detailed information about each resource", false)
     .option("-s, --stack <stack>", "Filter resources by stack name")
+    .option("-t, --type <type>", "Filter resources by type")
     .option("--no-stack", "Show only resources without a stack")
     .option("--ports", "Show port assignments", false)
     .option("--json", "Output a versioned JSON resource report", false)
@@ -23,6 +26,11 @@ export const resourcesCommand = new Command("resources")
         else {
             requireProjectRoot();
         }
+        if (options.type !== undefined && !includes(VALID_RESOURCE_TYPES, options.type)) {
+            throw new TdkError(`Invalid resource type "${options.type}"`, [
+                `Valid types: ${VALID_RESOURCE_TYPES.join(", ")}`,
+            ]);
+        }
         const discovery = createDiscoveryContext();
         if (options.stack && !stackExists(options.stack, discovery.resources)) {
             const error = errorFactories.stackNotFound(options.stack);
@@ -34,18 +42,21 @@ export const resourcesCommand = new Command("resources")
         let resources = discovery.resources;
         if (options.stack) {
             resources = discovery.resourcesByStack.get(options.stack) || [];
-            if (resources.length === 0 && !options.json) {
+            if (resources.length === 0 && !options.json && options.type === undefined) {
                 showEmptyState("stack-services", ` in stack "${options.stack}"`);
                 return;
             }
         }
         if (withoutStackFilter) {
             resources = discovery.unassignedResources;
-            if (resources.length === 0 && !options.json) {
+            if (resources.length === 0 && !options.json && options.type === undefined) {
                 showAllSatisfyCondition("resources", "assigned to a stack");
                 return;
             }
         }
+        if (options.type !== undefined) {
+            resources = resources.filter((resource) => (resource.config?.appType ?? resource.type) === options.type);
+        }
         if (options.json) {
             const data = resources.map((resource) => ({
                 name: resource.name,
@@ -58,7 +69,10 @@ export const resourcesCommand = new Command("resources")
             return;
         }
         if (resources.length === 0) {
-            showEmptyState(options.stack ? "stack-services" : "resources", options.stack ? ` in stack "${options.stack}"` : "");
+            const stackContext = options.stack ? ` in stack "${options.stack}"` : "";
+            const noStackContext = withoutStackFilter && !options.stack ? " without a stack" : "";
+            const typeContext = options.type !== undefined ? ` with type "${options.type}"` : "";
+            showEmptyState(options.stack ? "stack-services" : "resources", stackContext + noStackContext + typeContext);
             return;
         }
         showStep(`Found ${formatCount(resources.length, "resource")}:\n`);
@@ -90,7 +104,7 @@ export const resourcesCommand = new Command("resources")
             }
             showDetail("\nRun with --verbose for more details or --ports to see port assignments.", 0);
         }
-        const withoutStackCount = options.stack
+        const withoutStackCount = options.stack || options.type !== undefined
             ? resources.filter((r) => !r.stack).length
             : discovery.unassignedResources.length;
         if (withoutStackCount > 0 && !withoutStackFilter && !options.stack) {

package/cli/dist/commands/up.js

@@ -12,12 +12,13 @@ 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 { createJsonEmitter } from "../utils/json-output.js";
-import { findProjectRoot } from "../utils/paths.js";
+import { findProjectRoot, getPackageVersion } from "../utils/paths.js";
 import { findAvailablePort } from "../utils/port-assignment.js";
 import { isApiServiceType } from "../utils/resource-kind.js";
 import { appendHealthPath, resolveSubdomainBases } from "../utils/service-urls.js";
 import { discoverResources, discoverResourcesStrict, discoverStacks, stackExists, } from "../utils/services.js";
 import { buildSmokePlans, formatSmokeFailure, runSmokePlans } from "../utils/smoke.js";
+import { evaluateTdkVersionFloor } from "../utils/tdk-version.js";
 import { buildTiltUpArgs, runTilt } from "../utils/tilt.js";
 import { stopTiltOnPort } from "../utils/tilt-process.js";
 import { parseTiltPort, resolveTiltPort, stopTiltForUp } from "../utils/tilt-startup.js";
@@ -96,6 +97,24 @@ export function enforceDriftGate(projectRoot, options, exit = process.exit) {
         console.error(chalk.red(line));
     exit(DRIFT_EXIT_CODE);
 }
+/**
+ * Runs before anything starts (also under --dry-run, like the drift gate): a project's `minTdkVersion` in
+ * .tdk/project.json that this CLI does not meet, or cannot read, exits with 1 and the same text as `tdk doctor`.
+ * `ignoreVersion` skips the check and says so. No minTdkVersion means no check.
+ */
+export function enforceVersionFloor(projectRoot, options, currentVersion = getPackageVersion(), exit = process.exit) {
+    if (options.ignoreVersion) {
+        console.warn(chalk.yellow("Warning: --ignore-version set; minTdkVersion was not checked."));
+        return;
+    }
+    const floor = evaluateTdkVersionFloor(projectRoot, currentVersion);
+    if (floor.status === "none" || floor.status === "ok")
+        return;
+    options.onFail?.(`${floor.message}\n${floor.fix}`);
+    console.error(chalk.red(floor.message));
+    console.error(chalk.red(floor.fix));
+    exit(1);
+}
 function waitForTiltUi(port, timeoutMs = 30_000) {
     return new Promise((resolve) => {
         const deadline = Date.now() + timeoutMs;
@@ -127,6 +146,7 @@ export const upCommand = new Command("up")
     .option("--dry-run", "Show what would be started without starting", false)
     .option("-f, --force", "Kill existing Tilt process before starting", false)
     .option("--ignore-drift", "Start even if generated files differ from service.json", false)
+    .option("--ignore-version", "Start even if this tdk is older than minTdkVersion in .tdk/project.json", false)
     .option("--only <services...>", "Start only these services plus what the Tiltfile enables for them (their dependsOn services and shared infrastructure). With a stack, names must belong to that stack; dependencies may cross stacks")
     .option("--json", "Print one JSON object on stdout when the stack is ready or the command fails; implies --quiet", false)
     .action(async (stackName, options) => {
@@ -139,6 +159,14 @@ export const upCommand = new Command("up")
         showErrorAndExit(portSetting.message);
     }
     const configuredTiltPort = portSetting.port;
+    // First, before the host/Docker checks below: an old CLI must stop with one clear line, not a half-working stack.
+    const versionRoot = findProjectRoot();
+    if (versionRoot) {
+        enforceVersionFloor(versionRoot, {
+            ignoreVersion: options.ignoreVersion,
+            onFail: (message) => emit?.({ ok: false }, [{ code: "TDK_VERSION_TOO_OLD", message }]),
+        });
+    }
     const hostRefusal = options.dryRun ? null : await hostUpRefusal();
     if (hostRefusal) {
         emit?.({ ok: false }, [{ code: "HOST_UNSUPPORTED", message: hostRefusal }]);

package/cli/dist/commands/upgrade.js

@@ -1,6 +1,6 @@
 import { execFileSync, execSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { accessSync, constants, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { accessSync, chmodSync, constants, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync, } from "node:fs";
 import { basename, dirname, join, resolve, win32 } from "node:path";
 import { fileURLToPath } from "node:url";
 import chalk from "chalk";
@@ -143,6 +143,10 @@ async function getLatestBinaryRelease() {
         return null;
     }
 }
+function isPermissionError(err) {
+    const code = err?.code;
+    return code === "EACCES" || code === "EPERM";
+}
 export function isWritable(path) {
     try {
         accessSync(path, constants.W_OK);
@@ -210,6 +214,10 @@ export async function upgradeViaBinary(tdkPath, release) {
         const sums = parseChecksums(await checksumResponse.text());
         verifyChecksum(tmpPath, release.assetName, sums, true);
         verifyChecksum(engineTmpPath, ENGINE_ASSET_NAME, sums, false);
+        // writeFileSync creates the file 0644; without this the swapped-in binary
+        // is not executable and the shell reports "Permission denied".
+        if (!isWindows())
+            chmodSync(tmpPath, 0o755);
         mkdirSync(engineStageDir, { recursive: true });
         extractTarball(engineBuffer, engineStageDir);
         if (existsSync(tdkPath))
@@ -622,11 +630,18 @@ export const upgradeCommand = new Command("upgrade")
         console.log();
         console.log(chalk.yellow("⚠️  Upgrade status unknown - verification failed"));
         console.log();
-        console.log(chalk.yellow("💡 Verify manually:"));
-        console.log(chalk.white("   1. Restart your terminal"));
-        console.log(chalk.white("   2. Run: tdk version"));
-        if (installInfo.path) {
-            console.log(chalk.white(`   3. Compare with: git -C ${installInfo.path} rev-parse HEAD`));
+        if (isPermissionError(err) && installInfo.method !== "git" && installInfo.path) {
+            console.log(chalk.yellow("💡 The installed binary isn't executable. Fix it with:"));
+            console.log(chalk.cyan(`   chmod +x ${installInfo.path}`));
+            console.log(chalk.white("   then run: tdk version"));
+        }
+        else {
+            console.log(chalk.yellow("💡 Verify manually:"));
+            console.log(chalk.white("   1. Restart your terminal"));
+            console.log(chalk.white("   2. Run: tdk version"));
+            if (installInfo.method === "git" && installInfo.path) {
+                console.log(chalk.white(`   3. Compare with: git -C ${installInfo.path} rev-parse HEAD`));
+            }
         }
     }
 });

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

@@ -407,7 +407,7 @@ function ensureRootWorkspaceManifest(projectRoot, projectConfig) {
     writeTextFile(packageJsonPath, `${JSON.stringify(manifest, null, 2)}\n`);
     return true;
 }
-export async function generateMasterConfigs(projectRoot) {
+export async function generateMasterConfigs(projectRoot, options = {}) {
     const projectConfig = readProjectConfig(projectRoot);
     await warnIfSablierUnlicensed(projectRoot);
     if (ensureRootWorkspaceManifest(projectRoot, projectConfig)) {
@@ -455,9 +455,21 @@ export async function generateMasterConfigs(projectRoot) {
     // Copy .tiltignore to project root so Tilt uses it
     const tiltignoreSource = path.join(outputDir, ".tiltignore");
     const tiltignoreTarget = assertTdkGeneratedPath(projectRoot, ".tiltignore");
-    if (fs.existsSync(tiltignoreSource) && !fs.existsSync(tiltignoreTarget)) {
-        fs.copyFileSync(tiltignoreSource, tiltignoreTarget);
-        console.log(`✓ Copied: .tiltignore → project root`);
+    if (fs.existsSync(tiltignoreSource)) {
+        if (!fs.existsSync(tiltignoreTarget)) {
+            fs.copyFileSync(tiltignoreSource, tiltignoreTarget);
+            console.log(`✓ Copied: .tiltignore → project root`);
+        }
+        else if (options.discardHandEdits) {
+            // Only a file TDK wrote (it carries the header) may be restored; one without the
+            // header is the team's own and `verifyMasterConfigs` reports it as a warning.
+            const current = fs.readFileSync(tiltignoreTarget, "utf-8");
+            if (current.includes(TDK_GENERATED_MARKER) &&
+                current !== fs.readFileSync(tiltignoreSource, "utf-8")) {
+                fs.copyFileSync(tiltignoreSource, tiltignoreTarget);
+                console.log("✓ Restored: .tiltignore → project root (hand edits discarded)");
+            }
+        }
     }
     const copiedAssets = ensureProjectRuntimeAssets(projectRoot);
     for (const asset of copiedAssets) {

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

@@ -53,9 +53,18 @@ function ownsRuntimeFiles(resource) {
         Object.hasOwn(BACKEND_LANGUAGES, language) &&
         BACKEND_LANGUAGES[language].createFiles !== undefined);
 }
+/**
+ * A bring-your-own resource is a plain container: the engine builds the image from the resource's own `dockerfile`
+ * (or its `buildContext`), or pulls `image`, and never generates the golden-layer Dockerfile that COPYs a package.json.
+ */
+function isBringYourOwn(resource) {
+    return (resource.config?.appType ?? resource.type) === "bring-your-own";
+}
 export function checkResourcePackageJson(projectRoot = findProjectRoot() ?? process.cwd()) {
     const missing = discoverResourcesFromRoot(projectRoot)
-        .filter((resource) => !ownsRuntimeFiles(resource) && !existsSync(join(resource.path, "package.json")))
+        .filter((resource) => !isBringYourOwn(resource) &&
+        !ownsRuntimeFiles(resource) &&
+        !existsSync(join(resource.path, "package.json")))
         .map((resource) => resource.name);
     if (missing.length === 0) {
         return {
@@ -71,6 +80,73 @@ export function checkResourcePackageJson(projectRoot = findProjectRoot() ?? proc
         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",
     };
 }
+/**
+ * Two resources with one appName share a Compose service name and Traefik router and service names
+ * (all built from the name, none from the directory), so one of them is lost or misrouted.
+ */
+export function checkDuplicateResourceNames(projectRoot = findProjectRoot() ?? process.cwd()) {
+    const byName = new Map();
+    for (const resource of discoverResourcesFromRoot(projectRoot)) {
+        const paths = byName.get(resource.name) ?? [];
+        paths.push(relative(projectRoot, resource.configPath) || resource.configPath);
+        byName.set(resource.name, paths);
+    }
+    const duplicates = [...byName].filter(([, paths]) => paths.length > 1);
+    if (duplicates.length === 0) {
+        return {
+            name: "Duplicate resource names",
+            didPass: true,
+            message: "Every resource has a unique appName",
+        };
+    }
+    const lines = duplicates.map(([name, paths]) => `"${name}" in ${paths.join(" and ")}`);
+    return {
+        name: "Duplicate resource names",
+        didPass: false,
+        message: `${formatCount(duplicates.length, "appName")} used by more than one resource:\n    ${lines.join("\n    ")}`,
+        fix: 'Give each resource its own "appName" in its service.json. The name becomes the Compose service and the Traefik router, so two resources with one name collide',
+    };
+}
+/** A resource that gets a Traefik route to its own `port`: a backend, an mcp server, or a bring-your-own resource that is not opted out. */
+function isRoutedToPort(resource) {
+    const appType = resource.config?.appType;
+    if (isApiServiceType(appType))
+        return true;
+    return appType === "bring-your-own" && resource.config?.exposeViaProxy !== false;
+}
+/**
+ * Two routed resources on one `port`. This is a warning, not a failure: the engine publishes no service
+ * port on the host and gives each resource its own container, which Traefik reaches as <container>:<port>,
+ * so two containers can listen on 4000 at once. The pair still confuses the checks and URLs that identify
+ * a backend by its port, and usually means a copied service.json.
+ */
+export function checkDuplicateResourcePorts(projectRoot = findProjectRoot() ?? process.cwd()) {
+    const byPort = new Map();
+    for (const resource of discoverResourcesFromRoot(projectRoot)) {
+        const port = resource.config?.port;
+        if (typeof port !== "number" || !isRoutedToPort(resource))
+            continue;
+        const names = byPort.get(port) ?? [];
+        names.push(resource.name);
+        byPort.set(port, names);
+    }
+    const shared = [...byPort].filter(([, names]) => names.length > 1);
+    if (shared.length === 0) {
+        return {
+            name: "Duplicate resource ports",
+            didPass: true,
+            message: "No two routed resources use the same port",
+        };
+    }
+    const lines = shared.map(([port, names]) => `port ${port}: ${names.join(", ")}`);
+    return {
+        name: "Duplicate resource ports",
+        didPass: false,
+        isWarning: true,
+        message: `${formatCount(shared.length, "port")} used by more than one routed resource:\n    ${lines.join("\n    ")}`,
+        fix: 'Usually a copied service.json. Each container can listen on the same port, but pick distinct "port" values (tdk resource assigns free ones) so URLs like http://<resource>:<port> and localhost checks stay unambiguous',
+    };
+}
 const CONTAINER_URL = /https?:\/\/([a-z][a-z0-9-]*):(\d+)/g;
 export function checkServiceUrlPorts(projectRoot = findProjectRoot() ?? process.cwd()) {
     const resources = discoverResourcesFromRoot(projectRoot);
@@ -345,7 +421,7 @@ export async function checkDockerNetworkCapacity(exec = execAsync) {
                 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",
+                fix: "run tdk down --prune-networks in projects you are not using, or docker network prune (removes all unused networks)",
             };
         }
         return {

package/cli/dist/utils/down-cleanup.js

@@ -0,0 +1,98 @@
+import { execFileSync } from "node:child_process";
+const run = (command, args) => execFileSync(command, args, { encoding: "utf-8", stdio: "pipe", windowsHide: true });
+/** Network names the engine creates per project (see engine/.../docker/constants.star and init-networks). */
+const PROJECT_NETWORK_SUFFIXES = [
+    "traefik-public",
+    "traefik-private",
+    "backend",
+    "database",
+    "infisical-network",
+    "verdaccio-network",
+    "proxy",
+];
+/** The engine prefixes networks with the project name, hyphens turned into underscores. */
+export function projectNetworkNames(projectName) {
+    const prefix = projectName.replace(/-/g, "_");
+    return PROJECT_NETWORK_SUFFIXES.map((suffix) => `${prefix}_${suffix}`);
+}
+/**
+ * Remove this project's own networks. Only the exact names the engine creates are touched, and `docker network rm`
+ * itself refuses a network that still has containers attached, so another project's networks and in-use networks
+ * are never removed.
+ */
+export function pruneProjectNetworks(projectName, commandRunner = run) {
+    const existing = new Set(commandRunner("docker", ["network", "ls", "--format", "{{.Name}}"])
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean));
+    const result = { removed: [], kept: [] };
+    for (const name of projectNetworkNames(projectName)) {
+        if (!existing.has(name))
+            continue;
+        try {
+            commandRunner("docker", ["network", "rm", name]);
+            result.removed.push(name);
+        }
+        catch (err) {
+            const stderr = String(err.stderr ?? err).trim();
+            result.kept.push({ name, reason: stderr.split(/\r?\n/)[0] ?? "" });
+        }
+    }
+    return result;
+}
+/**
+ * PIDs of `tilt up` processes started for this project's Tiltfile. Matching on the Tiltfile path keeps another
+ * project's Tilt (or a Tilt the user started by hand) untouched.
+ */
+export function findProjectTiltUpPids(tiltfilePath, platform = process.platform, commandRunner = run) {
+    if (platform === "win32")
+        return [];
+    let output;
+    try {
+        output = commandRunner("ps", ["-axo", "pid=,command="]);
+    }
+    catch {
+        return [];
+    }
+    const pids = [];
+    for (const line of output.split(/\r?\n/)) {
+        const match = /^\s*(\d+)\s+(.*)$/.exec(line);
+        if (!match)
+            continue;
+        const command = match[2] ?? "";
+        const exe = (command.split(/\s+/)[0] ?? "").split("/").at(-1);
+        const target = ` -f ${tiltfilePath}`;
+        const at = command.indexOf(target);
+        const boundary = command[at + target.length];
+        if (exe === "tilt" &&
+            /^\S+\s+up\s/.test(command) &&
+            at > 0 &&
+            (boundary === undefined || boundary === " ")) {
+            pids.push(Number(match[1]));
+        }
+    }
+    return pids;
+}
+export function stopProjectTiltUp(tiltfilePath, platform = process.platform, commandRunner = run) {
+    const pids = findProjectTiltUpPids(tiltfilePath, platform, commandRunner);
+    for (const pid of pids) {
+        try {
+            commandRunner("kill", ["-TERM", String(pid)]);
+        }
+        catch {
+            // Already gone.
+        }
+    }
+    return pids;
+}
+/** Wait (up to `timeoutMs`) for the `tilt up` processes to exit after TERM, so `tilt down` does not race a live Tilt. */
+export async function waitForTiltUpExit(tiltfilePath, timeoutMs = 8000, findPids = findProjectTiltUpPids) {
+    const deadline = Date.now() + timeoutMs;
+    while (findPids(tiltfilePath).length > 0) {
+        if (Date.now() >= deadline)
+            return false;
+        await new Promise((resolve) => setTimeout(resolve, 250));
+    }
+    return true;
+}
+//# sourceMappingURL=down-cleanup.js.map

package/cli/dist/utils/tdk-version.js

@@ -0,0 +1,49 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+function toParts(raw) {
+    const match = raw.trim().match(/(\d+)\.(\d+)(?:\.(\d+))?/);
+    return match ? [Number(match[1]), Number(match[2]), Number(match[3] ?? 0)] : null;
+}
+function readMinTdkVersion(projectRoot) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(projectRoot, ".tdk", "project.json"), "utf-8"));
+        return parsed?.minTdkVersion;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function evaluateTdkVersionFloor(projectRoot, currentVersion) {
+    const minimum = readMinTdkVersion(projectRoot);
+    if (minimum === undefined)
+        return { status: "none" };
+    const required = typeof minimum === "string" ? toParts(minimum) : null;
+    if (!required || !/^\d+\.\d+\.\d+$/.test(String(minimum).trim())) {
+        return {
+            status: "malformed",
+            message: `.tdk/project.json minTdkVersion ${JSON.stringify(minimum)} is not a version like "1.3.80"`,
+            fix: 'Set minTdkVersion to a MAJOR.MINOR.PATCH string, for example "1.3.80".',
+        };
+    }
+    const current = toParts(currentVersion);
+    const meets = current !== null &&
+        (() => {
+            for (const [index, need] of required.entries()) {
+                const actual = current[index] ?? 0;
+                if (actual !== need)
+                    return actual > need;
+            }
+            return true;
+        })();
+    const requiredText = required.join(".");
+    if (!meets) {
+        return {
+            status: "too-old",
+            required: requiredText,
+            message: `tdk ${currentVersion} is older than the ${requiredText} this project requires (minTdkVersion)`,
+            fix: "Run: tdk upgrade",
+        };
+    }
+    return { status: "ok", required: requiredText };
+}
+//# sourceMappingURL=tdk-version.js.map

package/cli/dist/utils/tilt.js

@@ -92,6 +92,12 @@ export function buildTiltDownArgs(options = {}) {
     if (options.force) {
         args.push("--force");
     }
+    // `tilt down` re-evaluates the Tiltfile and removes only the resources that evaluation registers. Without `--focus`
+    // the Tiltfile falls back to its default phase and never registers a stack's own compose project, so `tdk up shop`
+    // containers survived `tdk down`. Pass the same selection `tdk up` used (every stack) after `--`.
+    if (options.focusTargets && options.focusTargets.length > 0) {
+        args.push("--", `--focus=${options.focusTargets.join(",")}`);
+    }
     return args;
 }
 //# sourceMappingURL=tilt.js.map

package/cli/package.json

@@ -1,7 +1,7 @@
 {
   "name": "tdk-cli-internal",
   "private": true,
-  "version": "1.3.110",
+  "version": "1.3.112",
   "description": "TDK CLI — start services on your laptop.",
   "keywords": [
     "tdk",

package/engine/topologies/tilt/common/utils_docker_networks.star

@@ -7,7 +7,8 @@ def fix_docker_networks(platform_networks):
     """
     Generates a shell command that:
     1. Removes networks with incorrect labels (if they exist and are not in use)
-    2. Creates all platform networks if they don't exist
+    2. Creates all platform networks if they don't exist, and fails with Docker's own
+       error if one that does not exist cannot be created
     """
     commands = []
     commands.append('echo "Initializing Docker networks..."')
@@ -19,7 +20,12 @@ def fix_docker_networks(platform_networks):
         check_and_remove += 'docker network rm ' + network + ' 2>/dev/null) || true'
         commands.append(check_and_remove)
 
-        create_cmd = 'docker network create ' + network + ' 2>/dev/null && echo "Created network ' + network + '" || true'
+        # Create the network. A failed create is an error unless the network exists
+        # afterwards (already there, or another process created it first). Docker's own
+        # message is printed and the command exits non-zero, so Tilt marks init-networks failed.
+        create_cmd = 'if _out=$(docker network create ' + network + ' 2>&1); then echo "Created network ' + network + '"; '
+        create_cmd += 'elif docker network inspect ' + network + ' >/dev/null 2>&1; then :; '
+        create_cmd += 'else echo "Failed to create Docker network ' + network + ': $_out" >&2; exit 1; fi'
         commands.append(create_cmd)
 
     commands.append('echo "Docker networks initialized"')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tdk-landscape/tdk-cli-core",
-  "version": "1.3.110",
+  "version": "1.3.112",
   "description": "TDK CLI — start services on your laptop.",
   "homepage": "https://tdk-landscape.github.io/tdk-website",
   "repository": {