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

package/CHANGELOG.md

@@ -4,6 +4,12 @@ Notable changes to the `tdk` CLI. Versions match [npm](https://www.npmjs.com/pac
 
 ## Unreleased
 
+- Add `tdk doctor --json` with schema-versioned readiness, checks, and structured errors; diagnostics remain on stderr.
+- Stabilize doctor exits: 0 ready, 1 blocking findings, 2 invalid arguments/internal check failures. Invalid `--ping-timeout` now exits 2 instead of 1 and rejects fractional/unit-suffixed values.
+- Add versioned `--json` envelopes to `tdk status`, `tdk resources`, and `tdk networks`; existing `networks --json` array consumers can migrate with `--json-legacy` through CLI 1.4.x. The compatibility flag is scheduled for removal in 1.5.0.
+- Add `tdk config verify --json` with drift summaries and unified diffs for missing or stale master outputs; verification remains read-only, and structured command/internal failures use exits 1/2.
+
+
 ## 1.3.77 (2026-09-30)
 
 - `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.

package/README.md

@@ -1,27 +1,6 @@
-<div align="center">
-
 # TDK — Tilt Development Kit
 
-TDK is a local development kit. It scaffolds services and runs a stack on your
-laptop with Docker and Tilt (hot reload, health, Traefik, Postgres).
-
-It is not a Kubernetes packager. It does not replace Helm, Argo CD,
-Kustomize, or your production charts.
-
-Use TDK when local bring-up of many services is painful and you do not want a
-cluster on the laptop.
-
-Skip TDK if `helm install` (or your existing compose/Tilt/Skaffold) already
-gives you a working local or shared-dev environment.
-
-## Status
-
-Supported: macOS, Linux, Windows via WSL2 Ubuntu.
-Native Windows: CLI inspect only; `tdk up` unsupported.
-WSL2 smoke: local script only (no GitHub WSL runner).
-Stability: 1.x — generated files are a contract; verify in CI.
-Check your machine: `tdk doctor`
-Known limits: [docs/compare-honest.md](docs/compare-honest.md)
+TDK runs many services on your laptop with Docker + Tilt. Helm still deploys the cluster.
 
 [![npm version](https://img.shields.io/npm/v/@tdk-landscape/tdk-cli-core.svg?style=flat&color=blue)](https://www.npmjs.com/package/@tdk-landscape/tdk-cli-core)
 [![CI](https://github.com/tdk-landscape/tdk-cli-core/actions/workflows/ci.yml/badge.svg)](https://github.com/tdk-landscape/tdk-cli-core/actions/workflows/ci.yml)
@@ -32,216 +11,51 @@ Known limits: [docs/compare-honest.md](docs/compare-honest.md)
 [![Socket Badge](https://badge.socket.dev/npm/package/@tdk-landscape/tdk-cli-core/latest)](https://socket.dev/npm/package/@tdk-landscape/tdk-cli-core/overview)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-[Website](https://tdk-landscape.github.io/tdk-website) · [Quickstart](https://tdk-landscape.github.io/tdk-website/docs/quickstart/) · [Examples](https://tdk-landscape.github.io/tdk-website/docs/examples/) · [Demo](https://tdk-landscape.github.io/tdk-demo-animation/) · [Report a bug](https://github.com/tdk-landscape/tdk-cli-core/issues/new/choose)
-
-</div>
-
-## When not to use TDK
-
-- Production or shared-cluster deploy is Helm/Argo/Kustomize — keep it.
-- Your local or namespace-per-dev environment already works.
-- You will not adopt `service.json` and generated files.
+## Installation
 
-## TDK is for you if
-
-- You have many services and want `tdk up <one stack>` on Docker.
-- You do not want kind or minikube as your daily path.
-- You want to generate services, run `tdk config verify`, and use Traefik `*.localhost` routes.
-
-Start with the [bundled product example](examples/tdk-example/README.md); its write path is covered by [example-e2e](.github/workflows/example-e2e.yml).
+Install the CLI from npm (requires Node.js 22.12+) or use the prebuilt binary (no Node.js or Bun required):
 
 ```bash
 npm install -g @tdk-landscape/tdk-cli-core
-npx @tdk-landscape/tdk-cli-core
-mkdir shop && cd shop                                   # tdk writes files into the current directory
-tdk project --yes                                       # set up the project
-tdk resource orders-api --type backend --stack shop     # scaffold a service
-tdk up shop                                             # run it with hot reload
-```
-
-![tdk scaffolding a backend and a frontend, then listing the stack](docs/demo.svg)
-
-Want to inspect a stack before starting containers? `tdk up shop --dry-run` shows the services and local URLs without Docker or Tilt installed.
-
-![npm downloads, last month](docs/npm-downloads.svg)
-
-**Requirements:** Docker (Desktop, OrbStack or Colima; Engine 25+, Compose 2.20+), [Tilt](https://docs.tilt.dev/install.html), [Bun](https://bun.sh) for the generated services, and Node.js 22.12+ for npm installs. Ports 80, 443 and 5432 must be free (a local Postgres is the usual conflict). macOS and Linux releases are available. Windows native is unsupported. WSL2 Ubuntu is supported. See docs/wsl2.md. Run `tdk doctor` to check your setup.
-
-This is the core monorepo for TDK: the `tdk` CLI, the Starlark-based Tilt orchestration engine that powers it, and the discovery system that turns a directory of services into a running local landscape.
-
-## Why TDK?
-
-| | docker-compose | Local Kubernetes (kind, minikube) | Plain Tilt | **TDK** |
-|---|---|---|---|---|
-| Scaffold a new service in one command | ❌ | ❌ | ❌ | ✅ `tdk resource` |
-| Hot reload on file change | ⚠️ `compose watch` config | ⚠️ extra tooling | ✅ | ✅ |
-| Health-checked startup order | ✅ `depends_on: condition: service_healthy` | ✅ | ⚠️ write it yourself | ✅ |
-| Proxy, Postgres, monitoring included | ❌ | ❌ | ❌ | ✅ |
-| Needs a cluster | No | Yes | Optional | **No** |
-| Start only one stack of a large system | ⚠️ profiles | ⚠️ | ⚠️ | ✅ `tdk up <stack>` |
-
-TDK is not a replacement for Tilt: it generates the Tiltfile, Dockerfiles and compose files and then runs Tilt. If you already have a hand-written Tiltfile or compose setup you're happy with, TDK mostly saves you the boilerplate for the next service.
-
-## Fixture bench: 100 generated services on one laptop
-
-Measured with [`scripts/benchmark/container-scale.ts`](scripts/benchmark/README.md) against the 100-service [`tdk-erp-system` fixture bench](https://github.com/tdk-landscape/tdk-erp-system), a scale fixture of generated `/health` services rather than an ERP product, on a 16 GB machine (Docker VM: 7.75 GiB). Raw results are in [`benchmarks/results/`](benchmarks/results).
-
-| Services | All healthy after | Total memory | Avg memory / service | Crashes / OOM kills |
-|---:|---:|---:|---:|---:|
-| 10 | 8 s | 161 MiB | 16 MiB | 0 / 0 |
-| 50 | 24 s | 829 MiB | 17 MiB | 0 / 0 |
-| 100 | 112 s | 1.6 GiB | 17 MiB | 0 / 0 |
-
-What this does and doesn't measure:
-
-- The ERP services are small generated Bun HTTP services (about 20 lines each) answering `/health`. Real services with real dependencies use more memory; the point is that TDK's per-service overhead (runtime image, healthchecks, proxy routing) stays small.
-- Images were already built, so build time isn't included. The clean-machine run below includes it.
-- The script starts the service containers with the settings `tdk up` generates (512 MiB / 0.5 CPU limits, healthchecks), without Tilt running. The memory column counts only the service containers, not Postgres or Traefik.
-- Numbers vary between runs (a later run reached 100 healthy in 74 s). Run it yourself with `bun scripts/benchmark/container-scale.ts`.
-
-### Cold boot on a clean machine (CI)
-
-The table above is a warm start. Two workflows install the published CLI on a fresh GitHub-hosted Ubuntu runner and run `tdk up` from nothing, building every image:
-
-- [**Quickstart E2E**](.github/workflows/quickstart-e2e.yml): the commands from the top of this README, one scaffolded backend, until it answers `/health` through Traefik. About 4 minutes. Runs after each release and daily.
-- [**ERP fixture scale E2E**](.github/workflows/erp-scale-e2e.yml): the 100-service generated-health fixture bench. [Run 36395860088](https://github.com/tdk-landscape/tdk-cli-core/actions/runs/36395860088) (CLI 1.3.72, 4 vCPU / 15 GB): **100 / 100 backends healthy through Traefik after 472 s**, 111 containers, 1.8 GiB used by all containers. Runs weekly.
-
-Both are Linux/Ubuntu CI fixtures: generated services answering `/health`, not a real business app. A green run means TDK can generate, build, route and health-check a landscape of that size on a clean Ubuntu runner. Windows now has a separate smoke workflow for CLI startup and unit tests, but it does not boot a full landscape on Windows. These CI runs also don't cover Apple Silicon or an existing repo you bring yourself.
-
-## What is TDK?
-
-TDK organizes microservices using a **Project → Stack → Resource** hierarchy, then uses Tilt to build, run, and hot-reload them locally:
-
-```
-Project (1 per repo)
-├── TILT_RESOURCE_DEFAULTS.star   # Ports, health checks, memory
-├── TILT_TECH_STACK.star          # Bun, Vite, Prisma, NATS
-│
-└── Stacks (deployment groups)
-    ├── api-stack
-    │   ├── api-backend      # Resource
-    │   └── web-frontend     # Resource
-    │
-    └── worker-stack
-        ├── worker-backend
-        └── web-frontend
-```
-
-`.tdk/project.json` also groups stacks into phases (`pre_alpha`, `alpha`, `beta`, `out_of_scope`) so a large system can be brought up in stages. `tdk up` runs stacks from the first three and adds any new stack to `pre_alpha`.
-
-Running `tdk resource` scaffolds a service (Dockerfile, TypeScript config, starter code, tests); `tdk up` hands the whole landscape to Tilt for orchestration, live-reload, and health checking — sized to fit dozens of services on a single laptop.
-
-## Install
-
-```bash
-npm install -g @tdk-landscape/tdk-cli-core
-# or
-bun install -g @tdk-landscape/tdk-cli-core
-```
-
-Or install the prebuilt binary (no Node or Bun needed; verified against the release checksums):
-
-```bash
+# or install the prebuilt binary
 curl -fsSL https://tdk-landscape.github.io/install.sh | sh
 ```
 
-Premium features don't need a different install: set `TDK_LICENSE_KEY` and any of these installs unlocks them. See [docs/FEATURES.md](docs/FEATURES.md).
-
 ## Quick start
 
 ```bash
 mkdir shop && cd shop
-tdk project --yes                                     # writes .tdk/project.json and generated configs
-tdk resource orders-api --type backend --stack shop   # asks you to confirm, then scaffolds services/shop/orders-api
-tdk resource storefront --type frontend --stack shop
-tdk up shop                                           # starts Tilt; UI at http://localhost:10350
-tdk networks                                          # lists the *.localhost URLs Traefik routes
-tdk down                                              # stops everything
-```
-
-See the [CLI reference](cli/README.md) for the full command set (`stack`, `resources`, `doctor`, `ui`, and more).
-
-## Repository layout
-
-This is a monorepo — most day-to-day CLI work happens under `cli/`, while `engine/` and `discovery/` implement the Tilt-side orchestration that the CLI drives.
-
-| Path | What it is |
-|------|------------|
-| [`cli/`](cli) | The `tdk` CLI source (TypeScript/Bun) — commands, UI, templates. See [cli/README.md](cli/README.md). |
-| [`engine/`](engine) | The Starlark Tilt framework: topology modules for Docker, networking, database virtualization, secrets, observability. See [engine/README.md](engine/README.md). |
-| [`discovery/`](discovery) | Manifest-driven service discovery — scans `service.json` files and builds the resource/dependency graph consumed by the engine. |
-| [`ext/`](ext) | Tilt extension (`ext://tdk-cli`) plus IDE/UI enhancement components. |
-| [`scripts/`](scripts) | Release, benchmarking, and dev-environment scripts (git hooks, pre-commit, idle-footprint measurement). |
-| [`benchmarks/`](benchmarks) | Container/landscape scale benchmarks. |
-| [`docs/`](docs) | Reference docs, including [FEATURES.md](docs/FEATURES.md) for project- and resource-level feature flags. |
-| [`Tiltfile`](Tiltfile) | Entry point that wires the engine into `tilt up`. |
-| [`install.sh`](install.sh) | Legacy installer URL; hands off to the official installer at `tdk-landscape.github.io/install.sh`. |
-
-## Features
-
-TDK ships a set of always-on infrastructure services (Traefik proxy, PostgreSQL) plus opt-in features — monitoring, ELK, Debezium CDC, a local npm registry, and more. Enable/disable them per-project via `.tdk/project.json`, or per-resource via each service's `service.json`. Full reference: [docs/FEATURES.md](docs/FEATURES.md).
-
-## Free and paid features
-
-The CLI, engine and everything in this repository are MIT-licensed and work without an account or key. A few extras are paid and need a `TDK_LICENSE_KEY`: on-demand start/stop of idle services (Sablier), a local npm registry (Verdaccio), DDD scaffolding, Playwright config, C4 diagrams, synthetic monitoring, and a few generators (see `KNOWN_RESOURCES` in [extension-fetch.ts](cli/src/generator/extension-fetch.ts)). In this repo those are disabled stubs; with a key set, the CLI downloads the real implementations. [docs/FEATURES.md](docs/FEATURES.md) marks which features are which. To get a key, use the [request form on the website](https://tdk-landscape.github.io/tdk-website/#waitlist) or open a [Premium license request](https://github.com/tdk-landscape/tdk-cli-core/issues/new?template=premium_license.yml).
-
-## Network access and telemetry
-
-TDK has no telemetry or analytics. The CLI only goes online when you ask it to:
-
-- `tdk upgrade` checks the latest release on GitHub.
-- With `TDK_LICENSE_KEY` set, `tdk project` and `tdk up` download the paid bundle from `tdk-extension-dist.oranguman.workers.dev` and re-check the key every 12 hours. Without a key, nothing is sent.
-- Docker and Tilt pull images and packages as they normally would.
-- Tilt, which TDK runs, has its own anonymous usage analytics. Turn them off with `tilt analytics opt out`.
-
-## FAQ
-
-**Why not just docker compose?** For a handful of services, compose is fine. TDK generates the compose files for you. It adds hot reload through Tilt, one-command scaffolding with matching Dockerfiles, and a stack-level `tdk up` for large systems where starting everything is too slow.
-
-**How is this different from Skaffold, Garden, DevSpace or Tilt itself?** Skaffold, Garden and DevSpace are built around Kubernetes, and plain Tilt leaves the Tiltfile to you. TDK runs on plain Docker with no cluster, and generates both the services and the Tilt config from a `service.json` per service.
-
-See the [honest comparison](docs/compare-honest.md) for tradeoffs and cases where TDK may not fit.
-
-**Do I need 100 microservices?** No. Two services work the same way. The 100-service fixture bench is a stress test to show the overhead stays flat; it is not an ERP product example.
-
-**Is TDK affiliated with Tilt or Docker?** No. TDK is an independent project built on top of [Tilt](https://tilt.dev), which is maintained by Docker, Inc.
-
-## Development
-
-```bash
-make help          # list all make targets
-make test          # run the full test suite
-make test-fast      # fast unit tests, no external deps
-make pre-commit-run # run pre-commit hooks on all files
+tdk project --yes
+tdk resource orders-api --type backend --stack shop --yes
+tdk up shop
+tdk networks
 ```
 
-`npm run typecheck` / `npm run lint` / `npm run test` delegate to the `cli/` workspace. If you're contributing, start with the [step-by-step contributor guide](docs/contributing/README.md) for subsystem-specific instructions.
+`tdk up shop --dry-run` previews selected local services and URLs before starting containers. The default starter is Bun/TypeScript; TDK's core role is running local containers through Docker + Tilt, not providing a Node.js application framework. See the [one-backend example](examples/one-backend/README.md).
 
-## Environment check
+## When not to use TDK
 
-### Cold npx / first run
+- Your existing Compose or Tilt workflow already gives you a working local environment.
+- You do not want `service.json` manifests and generated local configuration.
 
-```bash
-npx @tdk-landscape/tdk-cli-core
-npx @tdk-landscape/tdk-cli-core doctor
-```
-
-Ranked first failures: Node 22.12+, Docker Engine 25+, Compose 2.20.2+, Tilt 0.25+, Bun 1.2+, and ports 80/443/5432.
-Install Bun 1.2+ as a machine prerequisite. `tdk project` generates the stack configuration; Prisma and NATS are project-specific, and NATS is required only when the feature is enabled.
+## Docs
 
-```bash
-tdk doctor
-```
+- [Documentation index](docs/README.md)
+- [Working alongside Helm](docs/with-helm.md)
+- [Configuration and editor schemas](docs/configuration.md)
+- [Runnable one-backend example](examples/one-backend/README.md)
+- [Full multi-service example](examples/tdk-example/README.md)
+- [Features and license limits](docs/FEATURES.md)
+- [Honest comparison and known limits](docs/compare-honest.md)
+- [Architecture and repository map](docs/project-overview.md)
+- [Scale fixture measurements and caveats](docs/scale-bench.md)
 
-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.
+## Requirements and support
 
-## Community
+For the local runtime, install Docker (Desktop, OrbStack, or Colima; Engine 25+, Compose 2.20+) and [Tilt](https://docs.tilt.dev/install.html). Bun 1.2+ is used by the default generated services. Ports 80, 443, and 5432 must be free. TDK supports macOS, Linux, and Windows through WSL2 Ubuntu; native Windows supports CLI inspection only. Run `tdk doctor` to check local readiness. See [WSL2 setup](docs/wsl2.md).
 
-- **Questions and ideas:** [open an issue](https://github.com/tdk-landscape/tdk-cli-core/issues/new/choose).
-- **Contributing:** see [CONTRIBUTING.md](CONTRIBUTING.md) and the [step-by-step guide](docs/contributing/README.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:** bundled [TDK product example](examples/tdk-example), [ERP fixture bench (100 generated 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).
+## Contributing and license
 
-## License
+Contributions are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md) and the [contributor guide](docs/contributing/README.md). Report security issues using [SECURITY.md](SECURITY.md).
 
-[MIT](LICENSE) © [TDK Landscape](https://github.com/tdk-landscape)
+TDK is MIT-licensed; see [LICENSE](LICENSE).

package/cli/dist/commands/config.js

@@ -8,8 +8,10 @@ import { generateMasterConfigs, readProjectConfig, TemplateEngine, verifyMasterC
 import { isMasterConfigFileName } from "../types/index.js";
 import { assertValid } from "../utils/command-helpers.js";
 import { MASTER_CONFIG_FILES } from "../utils/constants.js";
-import { requireProjectRoot, runCommand } from "../utils/errors.js";
+import { errorFactories, requireProjectRoot, runCommand } from "../utils/errors.js";
 import { writeJsonFile } from "../utils/file-helpers.js";
+import { createMachineEnvelope, writeMachineError } from "../utils/machine-output.js";
+import { findProjectRoot } from "../utils/paths.js";
 import { SERVICE_MANIFEST_SCHEMA_VERSION, validateServiceManifest, } from "../utils/service-manifest.js";
 import { discoverServiceManifestPaths } from "../utils/services.js";
 import { validateOptionalInfraService } from "../utils/validation.js";
@@ -173,11 +175,25 @@ export const configCommand = new Command("config")
 }))
     .addCommand(new Command("verify")
     .description("Verify that generated files match .tdk/project.json")
-    .action(async () => {
-    await runCommand(async () => {
-        const projectRoot = requireProjectRoot();
-        console.log(chalk.blue("🔍 Verifying configuration...\n"));
+    .option("--json", "Emit a machine-readable verification report")
+    .action(async (options) => {
+    const action = async () => {
+        const projectRoot = options.json ? findProjectRoot() : requireProjectRoot();
+        if (!projectRoot)
+            throw errorFactories.notInProject();
         const result = verifyMasterConfigs(projectRoot);
+        if (options.json) {
+            console.log(JSON.stringify(createMachineEnvelope({
+                valid: result.valid,
+                errors: result.errors,
+                warnings: result.warnings,
+                diffs: result.diffs,
+            })));
+            if (!result.valid)
+                process.exit(1);
+            return;
+        }
+        console.log(chalk.blue("🔍 Verifying configuration...\n"));
         for (const warning of result.warnings) {
             console.warn(chalk.yellow(`⚠️  ${warning}`));
         }
@@ -190,10 +206,22 @@ export const configCommand = new Command("config")
             for (const error of result.errors) {
                 console.log(chalk.gray(`   - ${error}`));
             }
+            for (const { diff } of result.diffs)
+                console.log(chalk.gray(`\n${diff}`));
             console.log(chalk.gray("\nRun `tdk config regenerate` to fix."));
             process.exit(1);
         }
-    });
+    };
+    if (options.json) {
+        try {
+            await action();
+        }
+        catch (error) {
+            writeMachineError(error);
+        }
+        return;
+    }
+    await runCommand(action);
 }))
     .addCommand(new Command("edit").description("Open .tdk/project.json in your $EDITOR").action(async () => {
     await runCommand(async () => {

package/cli/dist/commands/doctor.js

@@ -6,6 +6,7 @@ import { Command } from "commander";
 import { hasVerdaccioLicense } from "../generator/extension-fetch.js";
 import { MASTER_CONFIG_FILES, REQUIRED_PACKAGE_SCRIPTS } from "../utils/constants.js";
 import { isPathDiscovered, readDiscoveryPaths } from "../utils/discovery-paths.js";
+import { collectDoctorChecks, createDoctorReport, getDoctorExitCode, } from "../utils/doctor-report.js";
 import { checkHealthRoutes, checkHostPorts, checkIngressPorts, checkPrivateNpmRegistry, checkTiltResourceHealth, projectConfigEnablesVerdaccio, summarizeServiceProbes, } from "../utils/doctor-runtime.js";
 import { checkDockerNetworkCapacity, checkFrontendBackendUrls, checkNatsBroker, checkResourcePackageJson, checkServiceUrlPorts, checkTiltInstances, } from "../utils/doctor-wiring.js";
 import { validateEnvFile } from "../utils/env-validator.js";
@@ -66,8 +67,8 @@ export function checkWslProjectLocation(projectPath, strict, isWsl = process.pla
 }
 /** Failures are shown before passing statuses, with a 5432 conflict first. */
 export function orderDoctorResults(results) {
-    const failures = results.filter((result) => !result.didPass && !result.isSkipped);
-    const remaining = results.filter((result) => result.didPass || result.isSkipped);
+    const failures = results.filter((result) => !result.didPass && !result.isSkipped && !result.isWarning);
+    const remaining = results.filter((result) => result.didPass || result.isSkipped || result.isWarning);
     failures.sort((left, right) => {
         const rank = (result) => result.name === "Host Ports" && /\b5432\b/.test(result.message)
             ? 0
@@ -968,21 +969,52 @@ async function checkServiceHealth(timeoutMs) {
 }
 export const doctorCommand = new Command("doctor")
     .description("Check environment readiness for TDK")
+    .option("--json", "Output a versioned JSON readiness report", false)
+    .exitOverride((error) => {
+    if (error.exitCode === 0)
+        process.exit(0);
+    if (doctorCommand.opts().json) {
+        console.log(JSON.stringify(createDoctorReport([], false, [{ code: "USAGE", message: error.message }])));
+    }
+    process.exit(2);
+})
     .option("--no-ping", "Skip pinging running services' /health endpoints")
     .option("--strict", "Fail warnings such as a WSL project under /mnt/c")
     .option("--ping-timeout <ms>", "Per-service ping timeout in milliseconds", String(DEFAULT_PING_TIMEOUT_MS))
     .action(async (options) => {
+    // Validate before running any probe; parseInt would silently accept "100ms" or "1.5".
+    const pingTimeout = Number(options.pingTimeout);
+    if (!/^\d+$/.test(options.pingTimeout) ||
+        !Number.isSafeInteger(pingTimeout) ||
+        pingTimeout <= 0) {
+        const message = "--ping-timeout must be a positive integer number of milliseconds";
+        if (options.json)
+            console.log(JSON.stringify(createDoctorReport([], false, [{ code: "USAGE", message }])));
+        console.error(message);
+        process.exit(2);
+        return;
+    }
+    if (!options.json) {
+        console.log("TDK doctor checks your local Docker + Tilt development environment; it does not check cluster deployments.");
+    }
     if (process.platform === "win32") {
+        if (options.json) {
+            console.log(JSON.stringify(createDoctorReport([
+                {
+                    name: "Native Windows support",
+                    didPass: false,
+                    message: NATIVE_WINDOWS_DOCTOR_MESSAGE,
+                    fix: "Use WSL2 Ubuntu with Docker Desktop integration. Guide: docs/wsl2.md",
+                },
+            ], Boolean(findProjectRoot()))));
+        }
         console.error(NATIVE_WINDOWS_DOCTOR_MESSAGE);
         process.exit(1);
         return;
     }
-    console.log(`\n${chalk.bold("🔍 TDK Doctor")}\n`);
-    console.log("Checking environment...\n");
-    const pingTimeout = Number.parseInt(options.pingTimeout, 10);
-    if (!Number.isFinite(pingTimeout) || pingTimeout <= 0) {
-        console.log(`${chalk.red("✗")} --ping-timeout must be a positive number of milliseconds`);
-        process.exit(1);
+    if (!options.json) {
+        console.log(`\n${chalk.bold("🔍 TDK Doctor")}\n`);
+        console.log("Checking environment...\n");
     }
     const machineChecks = [
         () => checkHostPorts(),
@@ -1035,20 +1067,22 @@ export const doctorCommand = new Command("doctor")
     // project. Only the machine checks mean anything there; the project checks
     // would all fail with "run tdk project".
     const inProject = Boolean(findProjectRoot());
-    const checks = inProject ? [...machineChecks, ...projectChecks] : [...machineChecks];
-    // Machine checks are independent and mostly wait on child processes, so run
-    // them concurrently. Project checks stay sequential; rendering ranks failures first.
-    const startedMachineChecks = machineChecks.map((checkFn) => Promise.resolve().then(checkFn));
-    const results = [];
-    for (const [index, checkFn] of checks.entries()) {
-        const result = await (startedMachineChecks[index] ?? checkFn());
-        results.push(result);
-    }
-    // Let machine checks finish before process.exit so their probes can clean up.
-    await Promise.allSettled(startedMachineChecks);
-    const allPassed = results.every((result) => result.didPass || result.isSkipped);
+    const { checks: results, errors } = await collectDoctorChecks(machineChecks, inProject ? projectChecks : []);
+    const report = createDoctorReport(orderDoctorResults(results), inProject, errors);
+    const exitCode = getDoctorExitCode(report);
+    const allPassed = report.data.ready;
+    if (options.json) {
+        console.log(JSON.stringify(report));
+        for (const error of errors)
+            console.error(error.message);
+        if (exitCode !== 0)
+            process.exit(exitCode);
+        return;
+    }
+    for (const error of errors)
+        console.error(`${chalk.red("✗")} Doctor check failed: ${error.message}`);
     for (const result of orderDoctorResults(results)) {
-        if (!result.didPass && !result.isSkipped) {
+        if (!result.didPass && !result.isSkipped && !result.isWarning) {
             console.log(`${chalk.red("✗")} ${result.message}`);
             if (result.fix)
                 console.log(`${chalk.blue("ℹ")} Fix: ${result.fix}`);
@@ -1074,7 +1108,7 @@ export const doctorCommand = new Command("doctor")
     }
     const outcome = getDoctorOutcomeMessage(inProject, allPassed);
     console.log(`${allPassed ? chalk.green(chalk.bold("✓")) : chalk.red(chalk.bold("✗"))} ${outcome}`);
-    if (!allPassed)
-        process.exit(1);
+    if (exitCode !== 0)
+        process.exit(exitCode);
 });
 //# sourceMappingURL=doctor.js.map

package/cli/dist/commands/help.js

@@ -1,7 +1,7 @@
 import chalk from "chalk";
 import pkg from "../../package.json" with { type: "json" };
 const TDK_BANNER = `
-  ${chalk.bold.cyan("tdk")} ${chalk.gray(`v${pkg.version}`)}  ${chalk.white("Tilt Development Kit: run your microservices locally")}
+  ${chalk.bold.cyan("tdk")} ${chalk.gray(`v${pkg.version}`)}  ${chalk.white("TDK runs many services locally with Docker + Tilt; Helm deploys the cluster")}
 `;
 const COMMAND_GROUPS = [
     {
@@ -78,7 +78,8 @@ function formatCommand(name, desc, alias, color) {
 }
 export function showHelp() {
     console.log(TDK_BANNER);
-    console.log(chalk.bold.white("\n  Project → Phase → Stack → Resource\n"));
+    console.log(chalk.gray("\n  Local development inner loop; TDK does not replace Helm for cluster deployments.\n"));
+    console.log(chalk.bold.white("  Project → Phase → Stack → Resource\n"));
     console.log(chalk.gray("  Usage: tdk [command] [options]\n"));
     console.log(chalk.bold.yellow("  Global Options:"));
     console.log(`  ${chalk.cyan("-v, --version".padEnd(20))} ${chalk.white("Display version number")}`);