@tdk-landscape/tdk-cli-core 1.3.49 → 1.3.50

package/CONTRIBUTING.md

@@ -0,0 +1,42 @@
+# Contributing to TDK
+
+Thanks for helping. Bug reports, docs fixes, and code changes are all welcome.
+
+## Ways to help
+
+- **Report a bug or ask a question:** [open an issue](https://github.com/tdk-landscape/tdk-cli-core/issues/new/choose). Include the output of `tdk doctor`.
+- **Pick up an issue:** look for [`good first issue`](https://github.com/tdk-landscape/tdk-cli-core/labels/good%20first%20issue) or [`help wanted`](https://github.com/tdk-landscape/tdk-cli-core/labels/help%20wanted). Comment on it so nobody duplicates your work.
+- **Share what you built:** an example project or a blog post helps other people find TDK.
+
+## Development setup
+
+You need [Bun](https://bun.sh), Node.js 22.12+, Docker, and [Tilt](https://docs.tilt.dev/install.html).
+
+```bash
+git clone https://github.com/tdk-landscape/tdk-cli-core.git
+cd tdk-cli-core/cli
+bun install
+npm run typecheck
+npm run lint
+npm test
+```
+
+From the repo root, `make help` lists more targets (`make test-fast`, `make pre-commit-run`).
+
+## Where things live
+
+- `cli/` is the `tdk` CLI (TypeScript). Conventions are in [cli/AGENTS.md](cli/AGENTS.md).
+- `engine/` is the Starlark Tilt framework. Conventions are in [engine/AGENTS.md](engine/AGENTS.md).
+- `discovery/` builds the resource and dependency graph from `service.json` files.
+
+## Pull requests
+
+1. Fork the repo and create a branch from `main`.
+2. Keep the change focused. One fix or feature per PR.
+3. Add or update tests for behavior changes.
+4. Make sure `npm run typecheck`, `npm run lint`, and `npm test` pass in `cli/`. CI runs the same checks.
+5. Describe what changed and why in the PR description.
+
+## Code of conduct
+
+This project follows the [Code of Conduct](CODE_OF_CONDUCT.md). By taking part you agree to follow it.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TDK Landscape
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,149 @@
+<div align="center">
+
+# TDK — Tilt Development Kit
+
+**Run 100 microservices on a 16 GB laptop. No Kubernetes.**
+
+One CLI that scaffolds your services and runs the whole landscape locally with hot reload, health checks, a proxy, and Postgres, all built on [Tilt](https://tilt.dev).
+
+[![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)
+[![npm downloads](https://img.shields.io/npm/dm/@tdk-landscape/tdk-cli-core.svg?style=flat)](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)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/tdk-landscape/tdk-cli-core?style=flat&logo=github)](https://github.com/tdk-landscape/tdk-cli-core/stargazers)
+
+[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>
+
+```bash
+npm install -g @tdk-landscape/tdk-cli-core
+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
+```
+
+> ⭐ **If TDK saves you from writing another `docker-compose.yml`, please [star the repo](https://github.com/tdk-landscape/tdk-cli-core/stargazers).** Stars help other developers find it.
+
+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` only | ✅ | ⚠️ 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>` |
+
+## Benchmark: 100 services on one laptop
+
+Measured with [`scripts/benchmark/container-scale.ts`](scripts/benchmark/README.md) against the 100-service [ERP example](https://github.com/tdk-landscape/tdk-erp-system) 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 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
+```
+
+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 via the installer script:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/tdk-landscape/tdk-cli-core/main/install.sh | bash
+```
+
+## Quick start
+
+```bash
+cd my-project
+tdk project                                          # initialize master configs
+tdk resource api-api --type backend --stack api      # scaffold a backend
+tdk resource api-app --type frontend --stack api     # scaffold a frontend
+tdk up api                                            # start the stack via Tilt
+tdk status                                            # check what's running
+```
+
+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) | Standalone installer used by the `curl \| bash` flow above. |
+
+## 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).
+
+## 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
+```
+
+`npm run typecheck` / `npm run lint` / `npm run test` delegate to the `cli/` workspace. See [cli/AGENTS.md](cli/AGENTS.md) for coding conventions if you're contributing to the CLI, and [engine/AGENTS.md](engine/AGENTS.md) for the Starlark topology framework.
+
+## Environment check
+
+```bash
+tdk doctor
+```
+
+Verifies Docker, Bun, Tilt, required ports, and master config files are all in place before you run `tdk up`.
+
+## Community
+
+- **Questions and ideas:** [open an issue](https://github.com/tdk-landscape/tdk-cli-core/issues/new/choose).
+- **Contributing:** see [CONTRIBUTING.md](CONTRIBUTING.md). Issues labeled [`good first issue`](https://github.com/tdk-landscape/tdk-cli-core/labels/good%20first%20issue) are a good place to start.
+- **Security:** see [SECURITY.md](SECURITY.md). Please don't report vulnerabilities in public issues.
+- **Examples:** [ERP system (100 services)](https://github.com/tdk-landscape/tdk-erp-system), [SaaS starter](https://github.com/tdk-landscape/tdk-saas-starter), [restaurant](https://github.com/tdk-landscape/tdk-restaurant-example).
+
+If TDK is useful to you, a ⭐ helps more than you'd think.
+
+## License
+
+[MIT](LICENSE) © [TDK Landscape](https://github.com/tdk-landscape)

package/SECURITY.md

@@ -0,0 +1,17 @@
+# Security Policy
+
+## Supported versions
+
+Security fixes go into the latest release published on [npm](https://www.npmjs.com/package/@tdk-landscape/tdk-cli-core). Please upgrade before reporting.
+
+## Reporting a vulnerability
+
+Please **do not** open a public issue for security problems.
+
+Report them privately through [GitHub security advisories](https://github.com/tdk-landscape/tdk-cli-core/security/advisories/new). Include:
+
+- the TDK version (`tdk --version`) and your OS
+- steps to reproduce
+- what an attacker could do with it
+
+We aim to reply within a few days and will credit you in the fix unless you prefer otherwise.

package/benchmarks/results/container-scale-2026-09-25T20-54-49-736Z.json

@@ -0,0 +1,45 @@
+{
+  "date": "2026-09-25T20:54:49.736Z",
+  "hostMemGiB": 16,
+  "dockerMemMiB": 7934,
+  "perServiceBudgetMiB": 74,
+  "options": {
+    "project": "../tdk-erp-system",
+    "tiers": [
+      5
+    ],
+    "gate": 5,
+    "timeoutSeconds": 240,
+    "interval": 30,
+    "startInterval": 2,
+    "settleSeconds": 5
+  },
+  "images": 107,
+  "singleProcessImageShare": 0.24299065420560748,
+  "results": [
+    {
+      "tier": 5,
+      "launchSeconds": 2.1,
+      "firstHealthySeconds": 3.3,
+      "allHealthySeconds": 4.4,
+      "healthy": 5,
+      "unhealthy": 0,
+      "starting": 0,
+      "crashed": 0,
+      "oomKilled": 0,
+      "crashes": [],
+      "totalMemMiB": 87,
+      "avgMemMiB": 17.4,
+      "totalCpuPct": 2.1,
+      "dockerPsMs": 101,
+      "requestMsP50": 2.2,
+      "loadAvg1m": 13.4,
+      "hostFreeMiB": 76,
+      "singleProcessShare": 0.2
+    }
+  ],
+  "gate": {
+    "tier": 5,
+    "passed": true
+  }
+}

package/benchmarks/results/container-scale-2026-09-25T21-01-20-540Z.json

@@ -0,0 +1,150 @@
+{
+  "date": "2026-09-25T21:01:20.540Z",
+  "hostMemGiB": 16,
+  "dockerMemMiB": 7934,
+  "perServiceBudgetMiB": 74,
+  "options": {
+    "project": "../tdk-erp-system",
+    "tiers": [
+      5,
+      10,
+      20,
+      50,
+      80,
+      100
+    ],
+    "gate": 100,
+    "timeoutSeconds": 240,
+    "interval": 30,
+    "startInterval": 2,
+    "settleSeconds": 15
+  },
+  "images": 107,
+  "singleProcessImageShare": 0.24299065420560748,
+  "results": [
+    {
+      "tier": 5,
+      "launchSeconds": 2.2,
+      "firstHealthySeconds": 3.4,
+      "allHealthySeconds": 4.5,
+      "healthy": 5,
+      "unhealthy": 0,
+      "starting": 0,
+      "crashed": 0,
+      "oomKilled": 0,
+      "crashes": [],
+      "totalMemMiB": 77,
+      "avgMemMiB": 15.5,
+      "totalCpuPct": 1.6,
+      "dockerPsMs": 142,
+      "requestMsP50": 4.1,
+      "loadAvg1m": 9.25,
+      "hostFreeMiB": 106,
+      "singleProcessShare": 0.2
+    },
+    {
+      "tier": 10,
+      "launchSeconds": 5.8,
+      "firstHealthySeconds": 5.9,
+      "allHealthySeconds": 8.1,
+      "healthy": 10,
+      "unhealthy": 0,
+      "starting": 0,
+      "crashed": 0,
+      "oomKilled": 0,
+      "crashes": [],
+      "totalMemMiB": 161,
+      "avgMemMiB": 16.1,
+      "totalCpuPct": 4.3,
+      "dockerPsMs": 100,
+      "requestMsP50": 4.8,
+      "loadAvg1m": 8.14,
+      "hostFreeMiB": 75,
+      "singleProcessShare": 0.3
+    },
+    {
+      "tier": 20,
+      "launchSeconds": 10.1,
+      "firstHealthySeconds": 10.3,
+      "allHealthySeconds": 12.5,
+      "healthy": 20,
+      "unhealthy": 0,
+      "starting": 0,
+      "crashed": 0,
+      "oomKilled": 0,
+      "crashes": [],
+      "totalMemMiB": 315,
+      "avgMemMiB": 15.8,
+      "totalCpuPct": 7.4,
+      "dockerPsMs": 110,
+      "requestMsP50": 3.8,
+      "loadAvg1m": 6.8,
+      "hostFreeMiB": 112,
+      "singleProcessShare": 0.7
+    },
+    {
+      "tier": 50,
+      "launchSeconds": 21.2,
+      "firstHealthySeconds": 21.5,
+      "allHealthySeconds": 23.9,
+      "healthy": 50,
+      "unhealthy": 0,
+      "starting": 0,
+      "crashed": 0,
+      "oomKilled": 0,
+      "crashes": [],
+      "totalMemMiB": 829,
+      "avgMemMiB": 16.6,
+      "totalCpuPct": 28.1,
+      "dockerPsMs": 140,
+      "requestMsP50": 2.3,
+      "loadAvg1m": 8.2,
+      "hostFreeMiB": 72,
+      "singleProcessShare": 0.4
+    },
+    {
+      "tier": 80,
+      "launchSeconds": 50,
+      "firstHealthySeconds": 50.6,
+      "allHealthySeconds": 53.3,
+      "healthy": 80,
+      "unhealthy": 0,
+      "starting": 0,
+      "crashed": 0,
+      "oomKilled": 0,
+      "crashes": [],
+      "totalMemMiB": 1334,
+      "avgMemMiB": 16.7,
+      "totalCpuPct": 37.3,
+      "dockerPsMs": 451,
+      "requestMsP50": 15.2,
+      "loadAvg1m": 10.43,
+      "hostFreeMiB": 114,
+      "singleProcessShare": 0.3
+    },
+    {
+      "tier": 100,
+      "launchSeconds": 109.6,
+      "firstHealthySeconds": 110.7,
+      "allHealthySeconds": 112.2,
+      "healthy": 100,
+      "unhealthy": 0,
+      "starting": 0,
+      "crashed": 0,
+      "oomKilled": 0,
+      "crashes": [],
+      "totalMemMiB": 1678,
+      "avgMemMiB": 16.8,
+      "totalCpuPct": 117.5,
+      "dockerPsMs": 1538,
+      "requestMsP50": 8.5,
+      "loadAvg1m": 14.9,
+      "hostFreeMiB": 61,
+      "singleProcessShare": 0.2
+    }
+  ],
+  "gate": {
+    "tier": 100,
+    "passed": true
+  }
+}

package/benchmarks/results/container-scale-2026-09-25T21-15-01-441Z.json

@@ -0,0 +1,73 @@
+{
+  "date": "2026-09-25T21:15:01.442Z",
+  "hostMemGiB": 16,
+  "dockerMemMiB": 7934,
+  "perServiceBudgetMiB": 74,
+  "options": {
+    "mode": "synthetic",
+    "project": "../tdk-erp-system",
+    "tiers": [
+      20
+    ],
+    "gate": 20,
+    "timeoutSeconds": 240,
+    "interval": 30,
+    "startInterval": 2,
+    "settleSeconds": 15
+  },
+  "images": 107,
+  "imageStats": {
+    "backend": {
+      "count": 100,
+      "min": 191,
+      "avg": 245,
+      "max": 263
+    },
+    "frontend": {
+      "count": 7,
+      "min": 89,
+      "avg": 89,
+      "max": 89
+    },
+    "backendSingleProcess": {
+      "count": 26,
+      "min": 191,
+      "avg": 194,
+      "max": 263
+    },
+    "backendWrapper": {
+      "count": 74,
+      "min": 263,
+      "avg": 263,
+      "max": 263
+    }
+  },
+  "diskUsage": "Images 6.653GB",
+  "singleProcessImageShare": 0.308411214953271,
+  "results": [
+    {
+      "tier": 20,
+      "launchSeconds": 11.3,
+      "firstHealthySeconds": 11.8,
+      "allHealthySeconds": 14.4,
+      "healthy": 20,
+      "unhealthy": 0,
+      "starting": 0,
+      "crashed": 0,
+      "oomKilled": 0,
+      "crashes": [],
+      "totalMemMiB": 312,
+      "avgMemMiB": 15.6,
+      "totalCpuPct": 6,
+      "dockerPsMs": 156,
+      "requestMsP50": 1.7,
+      "loadAvg1m": 11.09,
+      "hostFreeMiB": 110,
+      "singleProcessShare": 1
+    }
+  ],
+  "gate": {
+    "tier": 20,
+    "passed": true
+  }
+}

package/benchmarks/results/container-scale-2026-09-25T22-09-01-630Z.json

@@ -0,0 +1,77 @@
+{
+  "date": "2026-09-25T22:09:01.631Z",
+  "hostMemGiB": 16,
+  "dockerMemMiB": 7934,
+  "perServiceBudgetMiB": 74,
+  "options": {
+    "mode": "compose",
+    "project": "../tdk-erp-system",
+    "tiers": [
+      5
+    ],
+    "gate": 5,
+    "timeoutSeconds": 240,
+    "interval": 30,
+    "startInterval": 2,
+    "settleSeconds": 5
+  },
+  "images": 107,
+  "imageStats": {
+    "backend": {
+      "count": 100,
+      "min": 176,
+      "avg": 242,
+      "max": 263
+    },
+    "frontend": {
+      "count": 7,
+      "min": 89,
+      "avg": 89,
+      "max": 89
+    },
+    "backendSingleProcess": {
+      "count": 26,
+      "min": 176,
+      "avg": 183,
+      "max": 263
+    },
+    "backendWrapper": {
+      "count": 74,
+      "min": 263,
+      "avg": 263,
+      "max": 263
+    }
+  },
+  "diskUsage": "Images 6.56GB",
+  "singleProcessImageShare": 0.308411214953271,
+  "results": [
+    {
+      "tier": 5,
+      "launchSeconds": 2.2,
+      "firstHealthySeconds": 3.8,
+      "allHealthySeconds": 4.9,
+      "healthy": 5,
+      "unhealthy": 0,
+      "starting": 0,
+      "crashed": 0,
+      "oomKilled": 0,
+      "crashes": [],
+      "totalMemMiB": 75,
+      "avgMemMiB": 14.9,
+      "totalCpuPct": 2.4,
+      "dockerPsMs": 101,
+      "requestMsP50": 3.1,
+      "loadAvg1m": 5.12,
+      "hostFreeMiB": 148,
+      "singleProcessShare": 1,
+      "routed": {
+        "200": 5
+      },
+      "restarts": 0
+    }
+  ],
+  "gate": {
+    "tier": 5,
+    "passed": true
+  }
+}