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

package/.claude/skills/layer-autoresearch/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: layer-autoresearch
+description: Autonomous keep/discard experiment loop (after karpathy/autoresearch) that optimises TDK's L1-L4 Docker layers toward the north star of 100 services on a 16 GB machine. Use when asked to run autoresearch on the Docker layers or to optimise the golden/runtime layers experimentally.
+---
+
+# Layer autoresearch
+
+Adapted from karpathy/autoresearch `program.md`. You are an autonomous researcher making the TDK runtime layers cheaper **without removing features**.
+
+## Setup (with the user, once)
+
+1. Agree a run tag (e.g. `sep25`). Create `git checkout -b autoresearch/<tag>` from `main`. The branch must be new.
+2. Warn the user: this workspace has an external tool that auto-commits and pushes working-tree edits. Ask them to pause it for the run, because experiment resets must not reach `origin/main`.
+3. Read the in-scope files in full:
+   - Editable: `engine/topologies/platform/docker/layers/*.star`, `engine/topologies/platform/docker/layers/prisma/*.star`, `engine/topologies/platform/docker/build/golden_image_dockerfile.star`, `engine/topologies/platform/docker/config/healthcheck.star`.
+   - Read-only ground truth: `scripts/autoresearch/layer-eval.sh`, `scripts/benchmark/container-scale.ts`, `tests/tilt-engine/test_runtime_container_footprint.py`, and the spec `openspec/specs/runtime-container-footprint` (or its change under `openspec/changes/`).
+4. Check that `../tdk-erp-system` exists with built images (`docker images | grep finance_`). If not, ask the human to run `tdk up` there once.
+5. Create an untracked `autoresearch-results.tsv` with the header `commit	mem_mib	image_mib	status	description`.
+6. Confirm with the user, then start.
+
+## Experiment
+
+Run `scripts/autoresearch/layer-eval.sh > run.log 2>&1` (about 5-10 minutes). Read the results with `grep -A20 '^---' run.log`.
+
+- **Primary metric: `mem_per_service_mib`, lower is better.** This is idle memory per real ERP service, and it is what limits 100 services on 16 GB.
+- **Tie-breaker:** if memory is within 0.5 MiB of the best, a lower `unique_per_service_mib` or `service_image_mib` wins, then simpler code.
+- **Hard constraints.** `status: ok` requires all 20 services healthy, zero crashes, and passing feature tests. Anything else is a discard, or a crash if it didn't run.
+- **Never** edit the eval harness, benchmark, tests or spec. Never remove a user-facing feature: Prisma, Infisical entrypoint, hugo-as-feature, healthchecks, signal handling. Don't add dependencies.
+
+Candidate ideas, from real measurements on 2026-09-25:
+- Duplicate `node_modules` copy in the L4 backend runtime (4.2 MB twice per service).
+- L1 installs `file`, `bash` and `openssl` into every runtime image (30 MB apk layer). Check what actually needs them first.
+- Bun runtime memory flags (e.g. `--smol`) in the resolved `CMD`.
+- Distroless or slimmer Bun base for L4.
+- Per-service unique layer size.
+
+## Loop (never stop until the human interrupts)
+
+1. Note the current commit.
+2. Change the editable files with one idea.
+3. `git commit -m "<idea>"`.
+4. Run the eval, redirected to `run.log` (don't flood context).
+5. If there's no `---` block, `tail -n 50 run.log`. Fix trivial mistakes, otherwise log `crash`.
+6. Append a row to `autoresearch-results.tsv` (untracked).
+7. If the metric improved and `status: ok`, keep the commit. Otherwise `git reset --hard HEAD~1`.
+8. An eval that runs longer than 20 minutes counts as a failure.
+
+The first run is always the unmodified baseline.

package/.claude/skills/tdk-troubleshoot/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: tdk-troubleshoot
+description: Diagnose and fix TDK (tdk-cli-core) local-dev problems with verified commands. Covers `tdk doctor`, `tdk up` or `tdk down` failing or hanging, "Docker daemon is not responding", red Tilt resources (pull access denied for golden images, missing shared-platform-engineering files, TS2688 bun types, run-only "No such image"), Postgres crash loops, services never reaching healthy, a machine overloaded by many services, Docker image size vs memory questions, and benchmarking how many services fit on a laptop. Use this whenever someone works in tdk-cli-core or a TDK project (tdk-erp-system, tdk-saas-starter, tdk-restaurant-example, auth-user) and anything about tdk, Tilt, or Docker is broken, slow, or being measured, even if they never say "troubleshoot".
+---
+
+# TDK troubleshooting
+
+This skill comes from a long session on 2026-09-25. It brought `tdk-erp-system` (107 services) up, measured it, and wasted a lot of the user's time along the way. Everything below marked **measured** or **verified** was run on the user's 16 GB MacBook Air (Docker VM: 8 CPUs, 7,934 MiB). Anything else is labelled as unknown.
+
+## How to work (the expensive lessons)
+
+- **Say what you measured, what you estimated, and what you don't know, in that order.** Most of the frustration came from confident claims that a later measurement contradicted, such as "memory is ~16 MiB/container" (`docker stats`, which undercounts) and "112 s boot" (actually the launcher script). "I don't know yet, here is how I'd find out" is a good answer.
+- **Check machine load before blaming Docker, Tilt or the code.** An overloaded Mac makes every tool look broken.
+- **Before anything that runs longer than about 5 minutes or starts dozens of containers, say so and give an estimate.** A full ERP `tdk up` froze this machine once. Ask first.
+- **Give short status lines while waiting.** Silence during long builds reads as "nothing works".
+- **Don't polish a proxy metric.** Shrinking images didn't touch the real bottleneck. Ask what actually hurts (time, CPU, a freeze) and measure that.
+
+## First 60 seconds: triage
+
+```bash
+sysctl -n vm.loadavg; top -l 1 -n 0 | grep -E "CPU usage|PhysMem"
+time docker ps -q | wc -l
+pgrep -fl "tilt up"
+docker info --format 'CPUs={{.NCPU}} MemTotal={{.MemTotal}}'
+```
+
+- **`docker ps` taking more than about 5 s means overload, not breakage.** Measured: 6–13 s with 110 ERP containers plus Tilt running, load average 28–43, 99 MB free RAM. `tdk doctor` and `tdk down` both fail their own 10 s Docker check in that state.
+- **A `tilt up` process still running recreates any container you `docker stop`** within seconds. Stop Tilt first.
+- **Other TDK projects share the `*-autogenerated-*` container naming** (for example kitchen, guest, operations and auth from the restaurant and auth projects). Filter by stack name before stopping anything.
+
+## Symptoms, causes and fixes (verified)
+
+### "Docker daemon is not responding (`docker ps` hung for 10s)"
+
+**Cause:** overload, as above. `tdk down` is blocked by the same check.
+
+**Fix:** stop Tilt, then stop the project's containers directly.
+
+```bash
+pkill -TERM -f "tilt up -f $PWD/.tdk/.tdk-out/Tiltfile"
+docker ps --format '{{.Names}}' | grep -E '^(finance|hr|sales|inventory|manufacturing|supply_chain|analytics)-autogenerated-' | xargs docker stop
+```
+
+### Postgres restarting with "Database is uninitialized and superuser password is not specified"
+
+**Cause:** the container was created while `DB_PASSWORD` was empty. Environment variables are fixed when a container is created, so fixing `.env` later doesn't help.
+
+**Check:**
+
+```bash
+docker inspect <project>_postgres --format '{{range .Config.Env}}{{println .}}{{end}}' | grep POSTGRES_PASSWORD
+```
+
+**Fix:** recreate the container (Tilt or compose `up` recreates it). The data volume survives.
+
+### Tilt build error `pull access denied ... docker.io/library/<project>-l4-backend:latest`
+
+**Cause:** the golden layers aren't built yet (the `golden-layers-build` resource is still running).
+
+**Fix:** wait for it to finish. Tilt does **not** retry resources that failed before it finished, so trigger every errored resource yourself.
+
+```bash
+tilt get uiresources -o json | python3 -c 'import json,sys; [print(i["metadata"]["name"]) for i in json.load(sys.stdin)["items"] if i.get("status",{}).get("updateStatus")=="error"]' | xargs -n1 tilt trigger
+```
+
+### `*-run-only` resources fail with `No such image: <stack>_<svc>:dev`
+
+**Cause:** they ran `docker compose up --no-build` before the image existed.
+
+**Fix:** once the image builds, `tilt trigger` them.
+
+### Missing generated files in the build context
+
+The build fails with `"/shared-platform-engineering/docker-templates/<x>.sh": not found` or `"/package.json": not found`.
+
+**Cause:** the project is missing its generated runtime assets.
+
+**Fix:**
+- `tdk project --yes` copies `shared-platform-engineering/docker-templates` (verified).
+- If the root `package.json` is still missing, add a Bun workspace manifest. This is what fixed ERP:
+
+  ```json
+  { "name": "<project>", "private": true, "type": "module", "workspaces": ["services/*/*"] }
+  ```
+
+- `tdk doctor` now reports both (`checkGeneratedProjectRuntimeAssets`).
+
+### `bun run build` fails with `TS2688: Cannot find type definition file for 'bun'`
+
+**Cause:** the generated tsconfig sets `"types": ["bun"]`, but the service's `package.json` has no `@types/bun`.
+
+**Fix:** add `"@types/bun": "^1.4.2"` to `devDependencies`. `tdk doctor` now reports this (`checkTypeScriptTypeDependencies`).
+
+### `tdk up <stack>` queues every stack
+
+**Observed, not root-caused:** `tdk up finance` left 129 resources pending across all stacks.
+
+**Protect the machine:** check the counts, then disable the other stacks.
+
+```bash
+tilt get uiresources -o json | python3 -c 'import json,sys,collections; print(collections.Counter(i.get("status",{}).get("updateStatus") for i in json.load(sys.stdin)["items"]))'
+tilt disable <other-stack-resource> <...>
+```
+
+### Engine edits have no effect
+
+**Cause:** projects run a vendored copy of the engine at `.tdk/.tdk-out/tdk-cli-ext/`. The installed `/usr/local/bin/tdk` vendors **its own bundled engine**, so it can silently overwrite your local one.
+
+**Fix:** re-vendor from your local checkout, then check the copy matches.
+
+```bash
+(cd <core>/cli && bun run build)
+TDK_EXTENSION_SOURCE=<core> node <core>/cli/bin/tdk.js project --yes
+diff -rq <core>/engine/topologies/platform/docker .tdk/.tdk-out/tdk-cli-ext/engine/topologies/platform/docker
+```
+
+### Reading Tilt state
+
+- Use the CLI. The HTTP API (`localhost:10350/api/view`) returns 403 "missing session token".
+- `tilt get uiresources <name> -o json` shows a resource's state. **`buildHistory[0]` is the newest build**; reading `[-1]` shows a stale error and misleads you.
+- `tilt logs <resource>` gives the full build log.
+
+## ERP project layout
+
+| Thing | Value |
+|---|---|
+| Service manifests | `services/<stack>/<svc>/service.json` |
+| Image names | `<stack>_<svc>:dev` |
+| Compose project | `<stack>-autogenerated` |
+| Compose file | `services/<stack>/.autogenerated/docker-compose.app.autogenerated.yml` |
+| Postgres | `services/platform/database-management/docker-compose.yml` |
+| Traefik | `.tdk/.tdk-out/docker-compose.traefik.yml` |
+| Databases | `<project>_<stack>`, created with `createdb` |
+| Golden images | `<project>-l1`, `-l2`, `-l3-*`, `-l4-*` |
+
+## Measuring without fooling yourself
+
+### Image size is disk, not RAM
+
+- `docker images` counts shared layers once per image. Real disk use is `docker system df`. The 107 ERP images add up to 26 GB listed, but all 151 images on the machine together use 6 GB on disk.
+- See what fills an image, layer by layer:
+
+  ```bash
+  docker history <img> --format '{{.Size}}\t{{.CreatedBy}}'
+  ```
+
+- **Measured:** ERP backends are 176–276 MB each, but only 4.5–8.8 MB is service-specific. The rest is shared: Bun binary 93 MB, Alpine 9 MB, L1 packages 30 MB.
+- **Measured:** `auth_auth-api-backend:dev` is 826 MB on disk, yet uses 33 MiB of RAM when running. Of the 826 MB, two copies of `node_modules` take 199 MB each, and hugo takes 57 MB. The duplicate-copy fix is only on branch `autoresearch/sep25`. The hugo removal is on `main`. Both need a rebuild to take effect.
+
+### RAM: `docker stats` undercounts
+
+It leaves out Docker's per-container overhead in the VM (containerd shims and the init process). Use the change in the Docker VM's own memory instead:
+
+```bash
+docker run --rm alpine awk '/MemTotal/{t=$2}/MemAvailable/{a=$2}END{printf "%d MiB used\n",(t-a)/1024}' /proc/meminfo
+```
+
+- **Measured:** 100 idle ERP containers cost **2,076 MiB real (about 21 MiB each)**. `docker stats` reported 1,693 MiB for the same containers.
+- The VM measurement is noisy for small counts: the same 20-container setup read 442 MiB one time and 214 MiB the next. Use 100 containers, or repeat the run and report the range.
+
+### Time: start containers in parallel, as Tilt does
+
+A serial `docker run` loop measures the launcher, not the services. For parallel starts on macOS:
+
+```bash
+tr '\n' '\0' < cmds.txt | xargs -0 -n1 -P8 sh -c
+```
+
+- **Measured:** 100 ERP containers were all healthy in **31.7 s** starting 8 at a time, with 0 crashes. Starting the containers took 26.6 s of that.
+- The website claims "full boot in under 5 seconds". Measured, that only holds for about 5 services (4.5 s).
+
+### North-star math: 100 services in 16 GB
+
+(Docker VM MemTotal − 512 MiB for infrastructure) ÷ 100 = the per-service budget. On this Mac that's (7,934 − 512) ÷ 100 ≈ **74 MiB per service**. The measured 21 MiB fits, but only for idle containers answering `/health`. It hasn't been measured under real load.
+
+## Tools in this repo and how far to trust them
+
+| Tool | Status |
+|---|---|
+| `bun scripts/benchmark/container-scale.ts --synthetic` | **Verified** for 5 to 100 containers. Starts containers serially, so "all healthy" is about the launch time. |
+| `container-scale.ts` default (compose) mode | **Verified at tier 5** (2026-09-26): real generated compose files, real Postgres, real Traefik, 5/5 requests through Traefik returned 200, all healthy in 4.9s. Not yet run at 100 — that's the one that answers the north star. Its first run hung indefinitely (`Bun.spawn()` + a `Bun.sleepSync()` poll on `exitCode` never observes the exit, because `sleepSync` blocks the event loop Bun needs to record it) — fixed by launching with `spawnSync` instead. If you see a `container-scale.ts` run sit for minutes with 0% CPU while its containers are already healthy, this bug is back; check for `Bun.spawn` + `sleepSync` polling anywhere in the file. |
+| `scripts/autoresearch/layer-eval.sh` with the `layer-autoresearch` skill | **Verified** (4 runs). Run it from a worktree outside `~/Developer/Codex`. |
+| `scripts/measure-idle-footprint.sh <container>` | Written but **never run**. |
+| `tilt alpha tiltfile-result -f <Tiltfile>` | Runs Starlark without starting anything. `print` output is swallowed, so return data with `fail('RESULT' + encode_json(r))`. `load()` needs a literal path. |
+| `tests/tilt-engine/test_runtime_container_footprint.py` | Runs the real generators through Tilt. |
+
+## Environment traps
+
+- **`.tdk/.project-id` is not gitignored by default and is easy to accidentally stage.** It's created the first time anything checks a Premium license (`getOrCreateProjectId` in `cli/src/generator/extension-fetch.ts`) - a random UUID sent alongside `TDK_LICENSE_KEY` to the license server for per-project tracking, not itself a secret credential, but it's local machine state that has no business in a shared repo. Found staged (`git status`, not yet committed - caught before it reached `origin/main`) in `tdk-erp-system` on 2026-09-26; `tdk-saas-starter` and `tdk-restaurant-example` had the same `.gitignore` gap with no file yet; `tdk-user-management` has **no `.gitignore` at all** (currently harmless - only 35 minimal tracked files, nothing sensitive - but unprotected the moment real development starts there). The CLI has no `.gitignore` template of its own to fix at the source (`tdk project` doesn't generate one; each starter repo ships its own) - check every project's `.gitignore` for `.tdk/.project-id` individually, and `git status`/`git log --all -- .tdk/.project-id` before assuming it's fine.
+
+- **Auto-commit tool.** Something outside Claude commits and pushes edits in `~/Developer/Codex/*` repos to `origin/main` within about a minute, with messages like "skill" or "specs". Do experiments in a worktree outside that folder:
+
+  ```bash
+  git worktree add ~/Developer/<name> <branch>
+  ```
+
+- **macOS shell:**
+  - There's no `timeout` command.
+  - `xargs -I` has a 255-character limit, so use the `-0` form above.
+  - System `python3` is 3.9: add `from __future__ import annotations` before using `X | None` types.
+  - Bash is version 3.2.
+- **Lint only the files you touched:**
+
+  ```bash
+  cd cli && ./node_modules/.bin/biome check <files>
+  ```
+
+  `bun run lint -- <files>` still lints the whole repo, which has many pre-existing errors.
+- **Failures that aren't yours:**
+  - pytest `test_docker_generator_bugs.py::test_expose_line_must_be_numeric_port` and `test_health_endpoints.py::test_overall_health_endpoint_structure` also fail on the unmodified code.
+  - vitest `saas-starter-integration` and `stack-features-e2e` time out when Docker is busy.
+
+## Resolved since the first version of this skill
+
+- **`tdk up <stack>` queuing every stack — fixed and verified (2026-09-26).** `tdk up finance` computed the right 16-service list but passed it to Tilt as bare positional args. The generated Tiltfile's focus filter (`Config.apply_focus` / `apply_focus_filter` in `profiles.star`) only reads the `--focus` flag - the positional-args catch-all it also defines (`cfg['args']`) is never read anywhere. So every stack-scoped `tdk up` silently fell back to Tilt's default "pre-alpha" phase and enabled every stack in it (verified: 247 enabled resources instead of 16-40). Fix: `buildTiltUpArgs` (`cli/src/utils/tilt.ts`) now passes `--focus=<stackName>`, reusing the Tiltfile's own dependency-aware domain expansion. **Argument order matters**: `--focus=...` must come after a `--` separator (`tilt up -f <path> -- --focus=finance <names>`) - `tilt up` rejects `--focus` as an unrecognized top-level flag otherwise (`tilt up --help` lists its real flags; custom Tiltfile config flags only reach `config.parse()` via `--`). Verified end-to-end: `tilt get uiresources` showed 402 Disabled / 24 Enabled for `tdk up finance` after the fix, and the 24 enabled were exactly finance's services plus required infra.
+
+- **What actually overloads a real full `tdk up` at 100+ services — tested and it held (2026-09-26).** Ran a real, uncapped `tdk up` (no stack filter, all 107 services, Tilt doing real builds and reconciliation - not the synthetic/capped benchmark) with a self-killing watchdog sampling load/free-memory/`docker ps` latency every 5s. Result: **110/110 containers reached healthy, zero crashes, zero danger-threshold strikes**, over an 18-minute run. Load peaked around 20 during the busiest build phase (~20-30 containers starting at once) and then *settled back down* to 11-16 as more services came online, finishing at 11.45 with all 110 up. `docker ps` occasionally spiked to 2-6s under load but never approached the 10s `tdk doctor` timeout for long. This is the same scenario that froze the machine on 2026-09-25 (load 28-43, 99 MB free, `docker ps` 6-13s) - it did not recur. Caveat: this is one run on one machine state, and it isn't certain which fix (or whether the host simply had less competing load this time) made the difference; the single-process-CMD image rebuild only covered a minority of services (finance + a couple of supply_chain ones) at the time of this run, so a full image rebuild wasn't a factor. Re-run with the watchdog pattern above (`sysctl -n vm.loadavg`, `vm_stat` free pages, timed `docker ps`) before trusting a "it's fine now" claim on a different machine or after further engine changes.
+
+## Still unknown
+
+- **Whether Bun `--smol` (`BUN_OPTIONS=--smol`) saves memory.** Bun does read the variable, but the A/B test was inconclusive.
+- **Why auth's production `node_modules` is 199 MB.**

package/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,40 @@
+name: Bug report
+description: Something in tdk does not work as expected
+labels: [bug]
+body:
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: What did you run, what did you expect, and what happened instead?
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+      placeholder: |
+        1. tdk project --yes
+        2. tdk up api
+        3. ...
+    validations:
+      required: true
+  - type: textarea
+    id: doctor
+    attributes:
+      label: Output of `tdk doctor`
+      render: shell
+  - type: input
+    id: version
+    attributes:
+      label: TDK version
+      description: Output of `tdk --version`
+    validations:
+      required: true
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating system
+      options: [macOS (Apple Silicon), macOS (Intel), Linux, Windows (WSL), Other]
+    validations:
+      required: true

package/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Documentation
+    url: https://tdk-landscape.github.io/tdk-website
+    about: Guides, quickstart, and examples
+  - name: Report a security vulnerability
+    url: https://github.com/tdk-landscape/tdk-cli-core/security/advisories/new
+    about: Please report security issues privately

package/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,18 @@
+name: Feature request
+description: Suggest an idea or improvement for TDK
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem are you trying to solve?
+    validations:
+      required: true
+  - type: textarea
+    id: solution
+    attributes:
+      label: What would you like TDK to do?
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: What do you do today instead?

package/.github/dependabot.yml

@@ -0,0 +1,33 @@
+# Weekly dependency updates, grouped so minor and patch bumps arrive as one PR.
+version: 2
+updates:
+  - package-ecosystem: bun
+    directory: /
+    schedule:
+      interval: weekly
+      day: friday
+    open-pull-requests-limit: 5
+    labels:
+      - dependencies
+    commit-message:
+      prefix: "⬆️ "
+      include: scope
+    groups:
+      minor-and-patch:
+        update-types:
+          - minor
+          - patch
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly
+    labels:
+      - dependencies
+    commit-message:
+      prefix: "⬆️ "
+      include: scope
+    groups:
+      github-actions:
+        patterns:
+          - "*"

package/.github/pull_request_template.md

@@ -0,0 +1,5 @@
+## What changed and why
+
+## How it was tested
+
+- [ ] `npm run typecheck`, `npm run lint`, and `npm test` pass in `cli/`

package/.github/workflows/ci.yml

@@ -0,0 +1,187 @@
+# Checks for every PR and push to main. Run manually from the Actions tab too.
+name: 🚦 CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  changes:
+    name: 🔎 Detect Changes
+    runs-on: ubuntu-latest
+    outputs:
+      lockfile: ${{ steps.filter.outputs.lockfile }}
+      workflows: ${{ steps.filter.outputs.workflows }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+
+      - uses: dorny/paths-filter@v4
+        id: filter
+        with:
+          filters: |
+            lockfile:
+              - 'bun.lock'
+              - 'package.json'
+              - 'cli/package.json'
+            workflows:
+              - '.github/workflows/**'
+
+  lint:
+    name: 🛡️ Lint
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: cli
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install --frozen-lockfile
+      - run: bun run lint
+
+  typecheck:
+    name: 🦴 Typecheck
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: cli
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install --frozen-lockfile
+      - run: bun run typecheck
+
+  test:
+    name: 🧪 Test
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: cli
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: oven-sh/setup-bun@v2
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 22
+      - run: bun install --frozen-lockfile
+      - run: npm test
+
+  # Installs the npm package the way users do (npm install -g) and runs it,
+  # so a release can't ship without the compiled CLI or its dependencies.
+  package-smoke:
+    name: 📦 Package Smoke Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: oven-sh/setup-bun@v2
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 22
+
+      - name: Build
+        run: |
+          bun install --frozen-lockfile
+          npm run build
+
+      - name: Pack and install globally
+        run: | # zizmor: ignore[adhoc-packages] installs our own freshly packed tarball
+          npm pack --pack-destination "$RUNNER_TEMP"
+          npm install -g "$RUNNER_TEMP"/tdk-landscape-tdk-cli-core-*.tgz
+
+      - name: Run the installed CLI
+        working-directory: ${{ runner.temp }}
+        run: |
+          tdk --version
+          mkdir smoke-project && cd smoke-project
+          tdk project --yes
+          printf 'y\n' | tdk resource orders-api --type backend --stack shop
+          test -f services/shop/orders-api/service.json
+          echo "✅ Installed package scaffolds a project and a resource"
+
+  secret-scan:
+    name: 🔑 Secret Scan
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: trufflesecurity/trufflehog@v3.97.9
+        with:
+          base: ${{ github.event.pull_request.base.sha }}
+          head: ${{ github.event.pull_request.head.sha }}
+          extra_args: --only-verified
+
+  # Needs "Dependency graph" turned on in Settings > Code security, then the
+  # repository variable DEPENDENCY_REVIEW set to true (Settings > Variables).
+  dependency-review:
+    name: 🔒 Dependency Audit
+    runs-on: ubuntu-latest
+    needs: changes
+    if: vars.DEPENDENCY_REVIEW == 'true' && needs.changes.outputs.lockfile == 'true' && github.event_name == 'pull_request'
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: actions/dependency-review-action@v5
+        with:
+          fail-on-severity: high
+
+  workflow-audit:
+    name: 🛠️ Workflow Audit
+    runs-on: ubuntu-latest
+    needs: changes
+    if: needs.changes.outputs.workflows == 'true' || github.event_name == 'workflow_dispatch'
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: raven-actions/actionlint@v2
+        with:
+          fail-on-error: true
+      - uses: zizmorcore/zizmor-action@v0.6.4
+        with:
+          inputs: .github/workflows/
+          advanced-security: false
+          annotations: true
+
+  summary:
+    name: 📋 Summary
+    runs-on: ubuntu-latest
+    if: always()
+    needs: [lint, typecheck, test, package-smoke, secret-scan, dependency-review, workflow-audit]
+    steps:
+      - name: Render summary
+        env:
+          NEEDS: ${{ toJSON(needs) }}
+        run: |
+          {
+            echo "## CI Summary"
+            echo ""
+            echo "| Check | Result |"
+            echo "|---|---|"
+            echo "$NEEDS" | jq -r 'to_entries[] | "| \(.key) | \(
+              if .value.result == "success" then "✅ Passed"
+              elif .value.result == "skipped" then "⏭️ Skipped"
+              elif .value.result == "cancelled" then "🚫 Cancelled"
+              else "❌ Failed" end) |"'
+          } >> "$GITHUB_STEP_SUMMARY"

package/.github/workflows/release-binaries.yml

@@ -1,48 +1,58 @@
 name: Release binaries and npm package
 
 on:
+  workflow_dispatch:
   push:
     branches: [main]
     paths:
+      - "package.json"
       - "cli/package.json"
 
 permissions:
   contents: read
   id-token: write
 
+# Queue releases instead of running them side by side: two runs for the same
+# version upload the same assets and one fails with "already exists".
+concurrency:
+  group: release
+  cancel-in-progress: false
+
 jobs:
   release:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
 
       - uses: oven-sh/setup-bun@v2
         with:
           bun-version: latest
 
-      - uses: actions/setup-node@v6
+      - uses: actions/setup-node@v7
         with:
           node-version: 24.15.0
           registry-url: "https://registry.npmjs.org"
           package-manager-cache: false
 
       - name: Update npm for trusted publishing
-        run: npm install -g npm@latest
+        run: npm install -g npm@latest # zizmor: ignore[adhoc-packages] trusted publishing needs a current npm
 
       - run: bun install --frozen-lockfile
         working-directory: cli
 
+      # cli/bin/tdk.js loads cli/dist/cli.js, so the npm package is broken
+      # unless the CLI is compiled before `npm publish`.
+      - run: npm run build
+
       - run: scripts/release-binaries.sh --publish
         env:
           GH_TOKEN: ${{ secrets.BINARY_RELEASE_TOKEN }}
 
-      # cli/package.json's prepack script (scripts/stage-npm-engine.sh) copies
-      # Tiltfile/engine/discovery/specs/ext into cli/ before packing, so the
-      # published tarball is self-contained the same way the binary release
-      # is. npm can't overwrite an already-published version, so skip instead
-      # of failing when this run didn't bump the version.
+      # The root package is the public package. It owns the tdk bin entry and
+      # already contains the compiled CLI plus the bundled engine assets.
       - name: Publish to npm
-        working-directory: cli
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
         run: |

package/.github/zizmor.yml

@@ -0,0 +1,9 @@
+# Config for zizmor, the GitHub Actions security linter run by ci.yml's
+# Workflow Audit job whenever a workflow changes. Run locally with:
+#   zizmor .github/workflows/
+#
+# unpinned-uses is off: we only use official or widely used actions by
+# major version tag, and hash pins would need updating for every release.
+rules:
+  unpinned-uses:
+    disable: true

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,9 @@
+# Code of Conduct
+
+This project follows the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+
+In short: be respectful, assume good intent, and keep discussion about the work. Harassment, personal attacks, and discriminatory language are not accepted in issues, pull requests, or any other project space.
+
+## Reporting
+
+To report unacceptable behavior, open a [private security advisory](https://github.com/tdk-landscape/tdk-cli-core/security/advisories/new) or contact the maintainers through the [TDK Landscape organization](https://github.com/tdk-landscape). Reports are reviewed promptly and kept confidential.