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

package/engine/topologies/tilt/resources/orchestrator/apply_compose_resource_registration.star

@@ -9,7 +9,9 @@ OUTPUT = struct(AUTOGENERATED_FOLDER = ".autogenerated")
 
 load('../../../platform/docker/index.star', 'Docker')
 load('../../../platform/docker/constants.star', 'PlatformDockerConstants')
-load('../../../tilt/manifest/constants.star', 'BASE_PORT_FRONTEND')
+load('../../../tilt/manifest/constants.star', 'BASE_PORT_FRONTEND', 'BASE_PORT_BACKEND')
+load('../../../platform/docker/networking/traefik_static_routes.star', 'generate_static_wake_route', 'normalize_abs_path')
+load('../../../platform/docker/networking/sablier_container_cycle.star', 'sablier_middleware_suffix')
 
 load('./builders/typescript.star', 'TypescriptBuilders')
 
@@ -114,6 +116,71 @@ def _build_resource_deps(res, res_name, manifest, resource_config, infra_deps, c
     return res_deps
 
 
+def resource_defers_start(manifest):
+    """True when a manifest opts into `sablier.enable` + `sablier.deferStart`
+    AND the licensed sablier module is actually active.
+
+    deferStart stays behind the same TDK_LICENSE_KEY gate as the rest of
+    `sablier` (an explicit product decision, not just the opt-in manifest
+    flag): the free-tier stub's sablier_middleware_suffix() always reports
+    `enabled=False` regardless of what the manifest says, so checking through
+    it here -- rather than reading manifest['sablier']['enable'] directly --
+    is what keeps deferStart off for unlicensed projects. Without this check,
+    a project with no license would still get "no container created or
+    started," silently bypassing the license boundary for the disable-the-
+    container half of the feature even though the Docker-label wake half
+    stays correctly disabled.
+
+    A deferred resource's image still builds (docker_build has no auto_init
+    gate), but its dc_resource/run-only/replica resources are held back with
+    auto_init=False: no container is created or started until the Traefik
+    static route wakes it on first request (see openspec/changes/
+    prioritized-cold-start)."""
+    _, sablier_licensed_and_enabled = sablier_middleware_suffix(manifest, '')
+    if not sablier_licensed_and_enabled:
+        return False
+    sablier = manifest.get('sablier', {}) if manifest else {}
+    return bool(sablier.get('deferStart', False))
+
+
+def resolve_manifest_dependency_names(manifest, all_services_map):
+    """Resolve a manifest's `dependsOn` short names to full resource names,
+    reusing the same `_resolve_dependency_to_resource` that `_build_resource_deps`
+    already trusts for Tilt's own resource_deps ordering -- an ambiguous name
+    behaves identically here as it already does there."""
+    resolved = []
+    for dep in (manifest.get('dependsOn', []) if manifest else []):
+        resolved_dep = _resolve_dependency_to_resource(dep, all_services_map)
+        if resolved_dep and resolved_dep not in resolved:
+            resolved.append(resolved_dep)
+    return resolved
+
+
+def resolve_defer_start_dependencies(manifest, resource_manifests, all_services_map):
+    """Of a deferStart resource's manifest dependencies, resolve the subset
+    that are themselves deferStart resources, for the wake gateway's
+    X-Wake-Deps (see generate_static_wake_route's `dependencies` param and
+    openspec/changes/prioritized-cold-start design.md D5).
+
+    A dependsOn name `_resolve_dependency_to_resource` can't map to an exact
+    resource (its own fallback branches -- see that function) won't be a key
+    in `resource_manifests` either, so it's quietly excluded here rather than
+    guessed at -- consistent with D5's existing stance. Always-on infra
+    (database, NATS) is never itself a deferStart resource (D5), so in
+    practice this only ever picks up the one case D5 flags as mattering: a
+    deferStart resource depending on another."""
+    dependencies = []
+    for resolved_dep in resolve_manifest_dependency_names(manifest, all_services_map):
+        dep_manifest = resource_manifests.get(resolved_dep)
+        if not dep_manifest or not resource_defers_start(dep_manifest):
+            continue
+        dep_service_name = all_services_map.get(resolved_dep, {}).get('name', '')
+        if not dep_service_name:
+            continue
+        dependencies.append((resolved_dep, dep_service_name + '-autogenerated'))
+    return dependencies
+
+
 def _register_replicas(config, auto_init_apps):
     """Register additional replica resources for high-availability services."""
     replicas = config.get('replicas', 1)
@@ -146,9 +213,38 @@ def _build_live_update_rules(res_path, full_res_path, syncs):
     return live_update_rules
 
 
+def _app_image_name(resource_name, res_name):
+    """The image ref docker_build builds and the app compose service declares."""
+    return resource_name + '_' + res_name + ':dev'
+
+
+def _wake_compose_invocation(project_root, resource_path, res_name, resource_name):
+    """Compose files, env file and image for the wake gateway's direct start.
+
+    The same files/--env-file the `-run-only` resource passes, as absolute
+    normalized paths: the gateway mounts the project at the same normalized
+    root (traefik_standalone.star), so these resolve identically there.
+    Returns None without a project root (paths would be relative to Tilt's cwd).
+    """
+    if not project_root:
+        return None
+    root = normalize_abs_path(project_root)
+    compose_dir = root + '/' + resource_path + '/' + OUTPUT.AUTOGENERATED_FOLDER
+    files = [compose_dir + '/docker-compose.app.autogenerated.yml']
+    port_override = compose_dir + '/docker-compose.port-override.yml'
+    if os.path.exists(port_override):
+        files.append(port_override)
+    env_file = root + '/.env'
+    return {
+        'compose_files': files,
+        'env_file': env_file if os.path.exists(env_file) else '',
+        'image': _app_image_name(resource_name, res_name),
+    }
+
+
 def _register_docker_build(config, live_update_rules):
     """Register docker_build with live_update for hot-reload support."""
-    image_name = config['resource_name'] + '_' + config['res_name'] + ':dev'
+    image_name = _app_image_name(config['resource_name'], config['res_name'])
     project_root = config.get('project_root', '')
     # Use custom dockerfile from config if specified, otherwise use autogenerated default
     # The res_path is relative to project_root (e.g., 'services/product/...')
@@ -219,9 +315,15 @@ def _register_single_resource(config, resource_path, compose_project_name, auto_
     """Register a single dc_resource with optional docker_build and run-only resource."""
     app_type = config.get('app_type', 'backend')
     res_name = config['res_name']
-    
-    print("DEBUG REGISTER: Registering '{}' app_type='{}' auto_init={}".format(res_name, app_type, auto_init_apps))
-    
+
+    # A sablier.enable + sablier.deferStart resource is held back from tdk up's
+    # normal bring-up: its container is never created or started here, only via
+    # the Traefik wake path on first request. docker_build below is unaffected
+    # (it has no auto_init gate), so the image still builds either way.
+    effective_auto_init = auto_init_apps and not resource_defers_start(config.get('manifest', {}))
+
+    print("DEBUG REGISTER: Registering '{}' app_type='{}' auto_init={}".format(res_name, app_type, effective_auto_init))
+
     # Skip docker_build for libraries and SDKs - they don't have Dockerfiles
     if app_type not in ['library', 'sdk'] and config.get('syncs'):
         print("DEBUG REGISTER: '{}' has syncs, calling docker_build".format(res_name))
@@ -239,12 +341,12 @@ def _register_single_resource(config, resource_path, compose_project_name, auto_
         config['res_name'],
         labels=config['labels'],
         resource_deps=config['res_deps'],
-        auto_init=auto_init_apps,
+        auto_init=effective_auto_init,
     )
     print("DEBUG REGISTER: dc_resource completed for '{}'".format(res_name))
 
-    _register_run_only_resource(config, resource_path, compose_project_name, auto_init_apps)
-    _register_replicas(config, auto_init_apps)
+    _register_run_only_resource(config, resource_path, compose_project_name, effective_auto_init)
+    _register_replicas(config, effective_auto_init)
 
 
 def _register_dc_resources(resource_configs, resource_path, compose_project_name, auto_init_apps):
@@ -322,6 +424,7 @@ def _build_resource_config(res, manifest, resource_config, full_res_path, infra_
         'res_path': full_res_path,
         'env': env_vars,
         'project_root': project_root,
+        'manifest': manifest,
     }
 
 
@@ -388,7 +491,38 @@ def register_compose_resources(resource_config, ctx, runtime_flags, manifest_sta
             entry = _process_frontend_resource(res, manifest, full_res_path, resource_path, resource_name, should_enable)
         else:
             entry = _process_backend_resource(res, manifest, full_res_path, resource_path, resource_name, should_enable)
-        
+            # A deferStart resource has no container Traefik can discover via
+            # labels until its first request creates one (D2/D4) -- give it a
+            # static file-provider route instead, pointed at the wake gateway.
+            # Scoped to backends for now, matching the proposal's motivating
+            # case; frontend support is a natural follow-up, not implemented
+            # here. Dependency waking (D5): TDK's real infra dependencies
+            # (database, NATS, a resource's own migrator) live in
+            # separately-registered compose files that `depends_on` cannot
+            # reference (confirmed empirically, see design.md D5), and they're
+            # always-on infra that's essentially never actually cold, so they
+            # never show up here regardless. The one real case D5 flags as
+            # mattering -- a peer resource that is itself deferStart -- is
+            # resolved via the manifest's own `dependsOn` below.
+            if resource_defers_start(manifest) and write_file:
+                internal_port = res.get('port', manifest.get('port', BASE_PORT_BACKEND))
+                static_route_path = PlatformDockerConstants.TRAEFIK_DYNAMIC_DIR_REL + '/' + res['name'] + '.yml'
+                compose_invocation = _wake_compose_invocation(
+                    ctx.get('project_root', ''), resource_path, res['name'], resource_name,
+                ) or {}
+                write_file(static_route_path, generate_static_wake_route(
+                    resource_entry_name=res['name'],
+                    compose_project_name=compose_project_name,
+                    manifest=manifest,
+                    internal_port=internal_port,
+                    gateway_host=PlatformDockerConstants.TRAEFIK_WAKE_GATEWAY_CONTAINER,
+                    gateway_port=PlatformDockerConstants.TRAEFIK_WAKE_GATEWAY_PORT,
+                    dependencies=resolve_defer_start_dependencies(manifest, resource_manifests, all_services_map),
+                    compose_files=compose_invocation.get('compose_files'),
+                    env_file=compose_invocation.get('env_file', ''),
+                    image=compose_invocation.get('image', ''),
+                ))
+
         resource_entries.append(entry)
         resource_configs.append(_build_resource_config(
             res, manifest, resource_config, full_res_path, infra_deps,

package/engine/topologies/tilt/resources/orchestrator/builders/typescript.star

@@ -84,14 +84,20 @@ def _get_resource_only_paths(resource_path):
         
         # Shared runtime scripts copied in generated Dockerfiles.
         'shared-platform-engineering/docker-templates',
-
-        # Common DDD layers used by backend Dockerfiles.
-        'shared-ddd-layers/domain',
-        'shared-ddd-layers/infrastructure',
     ]
 
-    # Include only internal libraries referenced by this service package.json.
-    # This prevents unrelated library changes from triggering global rebuilds.
+    # Include only internal libraries referenced by this service package.json
+    # (covers shared-ddd-layers/<lib> too, via resolve_lib_path's 'ddd' root -
+    # no Dockerfile ever COPYs a bare shared-ddd-layers/domain or /infrastructure
+    # path, so hardcoding those two here was pure dead weight: every one of a
+    # large landscape's docker_build resources got its own Tilt watch
+    # registration on paths most projects don't even have on disk. At 107
+    # resources that's 107 duplicate watchers on the same couple of
+    # nonexistent paths - real amplification if anything ever touches them,
+    # and a plausible contributor to "fsnotify: queue or buffer overflow" at
+    # this scale, on top of being wasted watch overhead regardless).
+    # This also prevents unrelated library changes from triggering rebuilds
+    # of services that don't use them.
     deps_map = Utils.build_deps_mapping(resource_path)
     for dep_path in deps_map.values():
         if dep_path not in only_paths:

package/engine/topologies/tilt/resources/orchestrator/generators/manifest_resource.star

@@ -361,7 +361,8 @@ def _generate_all_configs_for_resource(
             res_path=resource_path,
             resource_name=resource_name,
             use_golden=should_enable('golden-image'),
-            use_prisma='prisma' in manifest.get('featuresEnabled', [])
+            use_prisma='prisma' in manifest.get('featuresEnabled', []),
+            manifest=manifest,
         )
     
     write_file(resource_path + "/" + OUTPUT.AUTOGENERATED_FOLDER + "/" + GENERATED_CONFIG_FILENAMES['dockerfile_app'], dockerfile_content)

package/knip.json

@@ -4,7 +4,7 @@
     "cli": {
       "entry": ["src/cli.ts"],
       "project": ["src/**/*.ts", "src/**/*.tsx"],
-      "ignoreBinaries": ["biome"]
+      "ignoreBinaries": ["vi", "colima", "podman", "killall", "file", "tdk", "tilt"]
     }
   }
 }

package/openspec/changes/optimize-runtime-docker-layers/.openspec.yaml

@@ -0,0 +1,3 @@
+schema: spec-driven
+created: 2026-09-25
+goal: Cut per-container CPU/memory so a full-landscape tdk up fits on a 16GB laptop

package/openspec/changes/optimize-runtime-docker-layers/design.md

@@ -0,0 +1,81 @@
+# Design
+
+## Context
+
+See `proposal.md` (Why) for the measurements. Current runtime layer behaviour relevant to the approach:
+
+- The backend runtime Dockerfile is `ENTRYPOINT ["/entrypoint.sh"]` + `CMD ["bun", "run", "start"]`. `infisical-entrypoint.sh` ends in `exec "$@"`, so the `bun run start` wrapper becomes PID 1 and spawns the real `bun run dist/index.js` child. The wrapper is currently what receives `SIGTERM` from `docker stop` and passes it on to the child.
+- The start command is set in several places: `RUNTIME_CONFIG.bun.backend_start_command` (`l3_builder_layers.star`), default `cmd` parameters in `dockerfile.star`, `golden_docker_generator_v2.star` and `l4_runtime_layers.star`, the `_runtime_setup` default (`infisical_docker.star`), and a hard-coded `CMD` for the Bun-static frontend (`l4_runtime_layers.star:213`). The Node runtime already uses `node dist/index.js` directly.
+- Healthcheck timing lives in `get_docker_healthcheck_config` (`golden_image_dockerfile.star:6`), but `compose.star` (lines 141, 264) hard-codes `interval: 10s` with `retries: 6`.
+- The per-service L4 layer already installs hugo only when a service's `featuresEnabled` contains `hugo`. The golden `l4_backend_bun` stage installs it for every backend anyway.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Meet every requirement in `specs/runtime-container-footprint/spec.md` without changing any service's source files or `package.json`.
+- Keep a single source of truth for healthcheck timing.
+
+**Non-Goals:**
+- Reworking the entrypoint script beyond what signal handling needs.
+- Default startup scope and Sablier scale-to-zero (see proposal Non-goals).
+
+## Decisions
+
+### D1: Resolve the start command at generation time, exec the entry file directly
+
+When generating a Bun backend or Bun-static frontend runtime, the generator reads the service's `package.json` `scripts.start`. If it is exactly `bun run <file>` or `bun <file>` (one file path, no `&&`, `;`, pipes or env assignments), the runtime gets `CMD ["bun", "<file>"]`. In every other case it falls back to `CMD ["bun", "run", "start"]`. The resolver (`resolve_bun_start_command` in `l4_runtime_layers.star`) runs at the single point where the backend and Bun-static frontend `CMD` are emitted, both on the plain path and the Infisical-entrypoint path. Upstream defaults (`cmd='bun run start'` in `dockerfile.star`, `golden_docker_generator_v2.star` and `infisical_docker.star`) stay as they are and act as the "no explicit override" value. An explicit different `cmd` passed by a caller is always kept.
+
+*Alternatives considered:*
+- Rewriting `start` in each service's `package.json`: rejected because it edits user-owned files and breaks `bun run start` locally.
+- Always emitting `bun <file>` from a fixed path: rejected because it silently ignores custom start scripts.
+- `bun run --bun start`: rejected because it still keeps the wrapper process.
+
+### D2: Add `init: true` to generated runtime services
+
+With direct exec, Bun becomes PID 1. The kernel does not apply default signal actions to PID 1, so an app without a `SIGTERM` handler would ignore `docker stop` and be killed only after the stop timeout. Generated compose services get `init: true` (Docker's bundled tini, about 1 MB resident). Tini passes signals on and reaps zombies. It is not a Bun process, so the "exactly one Bun process" requirement still holds.
+
+*Alternative:* inject a `SIGTERM` handler into generated service templates. Rejected because it doesn't cover existing services or custom servers.
+
+### D3: One healthcheck config, 30 s interval with a 2 s start interval
+
+A new shared module, `engine/topologies/platform/docker/config/healthcheck.star`, replaces the per-file inlined `get_docker_healthcheck_config` copies. The copies had drifted: `l4_runtime_layers.star`'s copy lacked keys its own code read. Defaults: `interval 30s`, `start_period 30s` (unchanged), `start_interval 2s`, `timeout 5s`, `retries 3`. Golden images, the L4 runtime layer, `compose.star` and `traefik_standalone.star` all read it. Each value can be overridden per run with `TDK_HEALTHCHECK_INTERVAL_SECONDS`, `TDK_HEALTHCHECK_START_INTERVAL_SECONDS`, `TDK_HEALTHCHECK_TIMEOUT_SECONDS`, `TDK_HEALTHCHECK_START_PERIOD_SECONDS` and `TDK_HEALTHCHECK_RETRIES`. Environment variables are used because there is no per-project healthcheck setting today, and `tdk up` does not pass the project `.env` through to Tilt.
+
+During the start period Docker probes every 2 s, so a service is marked healthy right after it starts answering (see the spec's "Startup readiness is not delayed" scenario). After that, probes drop to every 30 s. With `retries 3`, a failing service is marked unhealthy within about 90 s, compared with about 60 s today.
+
+*Alternative:* 30 s interval with no start interval. Rejected because first-healthy time would move from about 10 s to about 30 s per container, which slows every dependency chain in `tdk up`.
+
+`start_interval` needs Docker Engine 25+ and Compose 2.20.2+. `tdk doctor` gets a check that fails with an upgrade hint on older versions.
+
+### D4: Golden migrator stage declares `HEALTHCHECK NONE`
+
+Resolved by task 1.2. Migrators are one-shot jobs: every migrator container is built from the per-service `l4_migrator_runtime` stage (`prisma_runtime.star`), which already sets `HEALTHCHECK NONE` and runs `ENTRYPOINT ["/app/migrate.sh"]` to completion. The golden `l4_migrator_golden` stage's `bunx prisma --version` healthcheck is therefore always overridden and never protects anything. It only runs if someone starts the bare golden image, and then it starts a bunx/Prisma process every interval. The golden stage now sets `HEALTHCHECK NONE` too, so both layers agree.
+
+Evidence (2026-09-25): `grep -rn L4_generate_migrator_runtime engine/` shows a single caller (`golden_docker_generator_v2.star:57`), and that stage emits `HEALTHCHECK NONE` before `ENTRYPOINT`. No project in the workspace declares `"appType": "migrator"`.
+
+*Alternative (original plan):* a `test -x` check on a symlinked Prisma binary. Dropped because a healthcheck on a run-to-completion container has no meaning.
+
+### D5: Remove hugo from the golden backend stage only
+
+Delete `RUN apk add --no-cache hugo` from `l4_backend_bun` in `golden_image_dockerfile.star`. The per-service feature-gated install stays, but it never actually ran: `manifest_resource.star` called `Docker.backend(...)` without `manifest`, so `featuresEnabled` was always empty in the L4 layer. The manifest is now passed through, which makes the per-service install work and makes removing hugo from the golden stage safe.
+
+Evidence (task 1.1, 2026-09-25): no service in `tdk-erp-system`, `tdk-saas-starter`, `tdk-restaurant-example` or `tdk-user-management` lists `"hugo"` in `service.json`, and no source, script or config file mentions hugo (search excluded `node_modules`, `.autogenerated`, `dist` and `.tdk`). Removal affects no existing project.
+
+### D6: Verifying the idle budget
+
+`tests/tilt-engine/test_runtime_container_footprint.py` executes the real Starlark generators through `tilt alpha tiltfile-result` (skipped when Tilt isn't installed) rather than inspecting source text. Those tests assert the generated `CMD`, `init: true` and healthcheck values. The idle budget is checked by a smoke script that generates a template backend, runs it, waits for healthy, samples `docker stats` for 60 s, and fails if memory is over 64 MiB or CPU averages 2% or more. It's run manually and in the release checklist rather than on every CI run, because it needs Docker.
+
+## Risks / Trade-offs
+
+- [The start-script parser misreads a script, e.g. `bun run dist/index.js --port 4000`] → Only a single file argument qualifies. Anything with extra tokens falls back to `bun run start`, so the fallback is always the current behaviour.
+- [Docker Engine / Compose is older than 25 / 2.20.2 and rejects `start_interval`] → New `tdk doctor` version check; the release notes state the minimum version.
+- [Unhealthy detection is slower (about 90 s vs 60 s)] → Acceptable for local dev. `retries` stays configurable.
+- [A project relied on hugo without declaring the feature] → The build fails loudly (`hugo: not found`). Migration note: add `"hugo"` to `featuresEnabled`. No project in this workspace is affected (see D5 evidence).
+- [Background auto-commit tooling in this workspace pushes partial engine edits] → Make each decision's edits in one sitting and run the snapshot tests before moving on, so every intermediate push is still consistent.
+
+## Migration Plan
+
+1. Ship the engine changes in a TDK release.
+2. In each project: run `tdk project --yes` to re-vendor `.tdk/.tdk-out/tdk-cli-ext/` and regenerate compose files and Dockerfiles, touch the Tiltfile, then rebuild golden layers with the `golden-layers-build` resource or a fresh `tdk up`.
+3. Existing images keep working until they are rebuilt, and nothing needs to change inside services.
+
+**Rollback:** revert the engine change, re-run `tdk project --yes`, and rebuild the golden layers.

package/openspec/changes/optimize-runtime-docker-layers/proposal.md

@@ -0,0 +1,44 @@
+# Proposal
+
+## Why
+
+A full-landscape `tdk up` of `tdk-erp-system` (107 resources, 110 containers) saturated a 16 GB MacBook Air on 2026-09-25. Load average reached 30–43, only 99 MB of memory was free with 8 GB compressed, and `docker ps` took 6–13 s, which made `tdk doctor` and `tdk down` fail their own 10 s Docker check. A single idle backend is cheap (0.3–1.2% CPU, about 20 MiB in its cgroup). The overload comes from per-container overhead that the generated runtime layers multiply by 110: a redundant second Bun process, a 10 s exec-based healthcheck, and tooling nobody uses baked into the golden images. Cutting that overhead at the layer level makes large landscapes usable on the laptops TDK targets.
+
+## What Changes
+
+- **Start the backend with one process.** The generated L4 backend runtime (and the Bun-static frontend runtime) now start the compiled entrypoint directly, e.g. `CMD ["bun", "dist/index.js"]`, instead of `bun run start`. `bun run start` launches a Bun wrapper that then spawns a second Bun runtime (about 10 MB + 52 MB resident per container). A service whose `start` script does more than run a single file keeps `bun run start`.
+- **Add an init process for signals.** Generated runtime services run under Docker's minimal init (`init: true`) so `docker stop` still reaches the app once the wrapper is gone.
+- **Slow down healthchecks.** The default steady-state healthcheck interval goes from 10 s to 30 s for generated compose services and golden images. A fast start interval keeps first-healthy time where it is today. The value stays configurable through the existing healthcheck config, and compose files now read that config instead of hard-coding 10 s.
+- **BREAKING (environment):** the fast start interval needs Docker Engine 25+ and Compose 2.20.2+. `tdk doctor` gets a check for this.
+- **Make the migrator healthcheck cheap.** The `l4_migrator_golden` healthcheck no longer runs `bunx prisma --version`, which starts a full bunx/Prisma process on every check. It checks the locally installed Prisma binary instead.
+- **Remove hugo from the golden backend image.** `apk add hugo` is removed from the golden `l4_backend_bun` stage (about 57 MB per backend image). The per-service L4 layer already installs hugo only when a manifest lists the `hugo` feature, and that stays as is.
+- **Document a per-container budget.** An idle generated backend has a documented footprint target, so regressions like these are visible.
+
+Nothing here is breaking for service code. Services that relied on hugo being present without declaring the `hugo` feature must add it to `featuresEnabled`.
+
+## Capabilities
+
+### New Capabilities
+- `runtime-container-footprint`: Requirements on generated runtime images and containers: one application process per container, healthcheck cadence and cost, golden image contents limited to what every service of that type needs, and an idle footprint budget.
+
+### Modified Capabilities
+- (none)
+
+## Non-goals
+
+- Changing which resources `tdk up` starts by default, or putting backends under Sablier scale-to-zero. Even with these fixes, starting all 107 services at once stays heavy on 16 GB machines. That is a separate product decision with its own change.
+- Changing the Bun version, base OS, or Prisma version.
+
+## Impact
+
+- **Engine (Starlark):**
+  - `engine/topologies/platform/docker/layers/l4_runtime_layers.star`: backend and Bun-static frontend `CMD`.
+  - `engine/topologies/platform/docker/layers/infisical/infisical_docker.star`: `_runtime_setup` default command.
+  - `engine/topologies/platform/docker/layers/l3_builder_layers.star`: `RUNTIME_CONFIG.bun.backend_start_command`.
+  - `engine/topologies/platform/docker/dockerfile/dockerfile.star` and `generators/golden_docker_generator_v2.star`: default `cmd` parameters.
+  - `engine/topologies/platform/docker/build/golden_image_dockerfile.star`: hugo removal, healthcheck interval, migrator healthcheck.
+  - `engine/topologies/platform/docker/compose/compose.star`: compose healthcheck (lines 141, 264) reads the shared config; `init: true`.
+- **CLI:** `cli/src/commands/doctor.ts` gets a Docker Engine / Compose minimum-version check.
+- **Generated projects:** every project needs `tdk project --yes` (re-vendoring `.tdk/.tdk-out/tdk-cli-ext/`) and a golden image rebuild to pick up the change. Existing images keep working until then.
+- **Behaviour:** after a failure, Docker marks a container unhealthy up to about 20 s later than today. Tilt readiness and dependency ordering still use the start period.
+- **Tests:** starlark and generated-Dockerfile snapshot tests covering these files need updating.

package/openspec/changes/optimize-runtime-docker-layers/specs/runtime-container-footprint/spec.md

@@ -0,0 +1,79 @@
+# Spec Delta
+
+## Purpose
+
+Keeps the per-container CPU, memory and image-size cost of generated TDK runtimes small enough that a large landscape (100+ resources) can run on a 16 GB developer laptop without starving the container runtime.
+
+## ADDED Requirements
+
+### Requirement: One Application Process Per Runtime Container
+
+A generated Bun backend or Bun-static frontend runtime container SHALL run its application as a single Bun process. The container entrypoint MUST hand off to that process with `exec` rather than keep a wrapper process alive. This applies when the service's `start` script runs a single entry file.
+
+#### Scenario: Default backend start script
+
+- **WHEN** a generated backend's `package.json` has `"start": "bun run dist/index.js"` and its runtime container has finished starting
+- **THEN** exactly one Bun process is running in the container (as listed by `docker top`)
+- **AND** that process is running `dist/index.js`
+
+#### Scenario: Custom start script is preserved
+
+- **WHEN** a service's `start` script does more than run a single entry file (for example it chains commands or sets environment variables)
+- **THEN** the runtime starts the service through `bun run start`
+- **AND** the service behaves as it did before this change
+
+#### Scenario: Signals reach the application
+
+- **WHEN** a running backend container is stopped with `docker stop`
+- **THEN** the application process receives SIGTERM directly and the container exits within the stop timeout
+
+### Requirement: Healthchecks Are Low-Cost And Low-Frequency
+
+Container healthchecks generated for services and golden images SHALL default to an interval of 30 seconds, and the timing MUST be overridable per run through `TDK_HEALTHCHECK_*` environment variables. A healthcheck command MUST NOT download packages or start a package-runner process (such as `bunx` or `npx`).
+
+#### Scenario: Default service healthcheck interval
+
+- **WHEN** a project is generated with default healthcheck configuration
+- **THEN** every generated compose service healthcheck has `interval: 30s`
+- **AND** the start period is at least as long as it was before this change
+
+#### Scenario: Startup readiness is not delayed
+
+- **WHEN** a generated service container starts and begins answering its health endpoint
+- **THEN** Docker reports it healthy within 5 seconds of the first successful answer, even with a 30-second steady-state interval
+
+#### Scenario: Configured interval is honoured
+
+- **WHEN** `tdk up` runs with `TDK_HEALTHCHECK_INTERVAL_SECONDS` set (e.g. `15`)
+- **THEN** the generated compose files and golden images use that interval
+
+#### Scenario: One-shot migrator images carry no healthcheck
+
+- **WHEN** the golden migrator image or a generated migrator runtime image is inspected
+- **THEN** it declares no healthcheck (`HEALTHCHECK NONE`)
+- **AND** no healthcheck anywhere in the generated images invokes `bunx` or `npx`
+
+### Requirement: Golden Images Contain Only Universally Required Tooling
+
+A golden runtime image SHALL contain only tooling that every service of that runtime type needs. Tooling that only some services use MUST be installed in the per-service layer, and only when that service's manifest declares the matching feature.
+
+#### Scenario: Backend golden image has no hugo
+
+- **WHEN** the golden L4 backend Bun image is built
+- **THEN** the `hugo` binary is not present in the image
+
+#### Scenario: Service declaring the hugo feature
+
+- **WHEN** a service's manifest lists `hugo` in `featuresEnabled`
+- **THEN** that service's runtime image contains the `hugo` binary
+- **AND** services that do not declare it do not
+
+### Requirement: Idle Backend Footprint Budget
+
+A backend generated from the default TDK backend template SHALL, when idle (running and healthy, with no incoming requests), stay within 64 MiB container memory and average under 2% of one CPU core over 60 seconds, as reported by `docker stats`.
+
+#### Scenario: Measuring an idle template backend
+
+- **WHEN** a backend generated with `tdk resource <name> --type backend` has been running and healthy for 60 seconds with no incoming requests
+- **THEN** its container memory usage is at most 64 MiB
+- **AND** its average CPU usage over the following 60 seconds is below 2% of one core

package/openspec/changes/optimize-runtime-docker-layers/tasks.md

@@ -0,0 +1,36 @@
+# Tasks
+
+## 1. Preflight checks
+
+- [x] 1.1 Search every TDK project in the workspace (`tdk-erp-system`, `tdk-saas-starter`, `tdk-restaurant-example`, `tdk-user-management`) for services that use `hugo` without listing it in `featuresEnabled`. Record the result under design D5. Verify by attaching the search command and its (expected empty) output to the design note.
+- [x] 1.2 Determine whether any `l4_migrator_golden`-based container runs long-lived or all are one-shot jobs. Record the answer under design D4 and keep or switch the D4 decision accordingly. Verify that design.md is updated with the evidence (compose `restart` policy and Tilt resource type).
+
+## 2. Single-process runtime (D1, D2)
+
+- [x] 2.1 Add one start-command resolver to the engine. It returns `bun <file>` for a `start` script of exactly `bun run <file>` or `bun <file>`, and `bun run start` otherwise. Verify with a new pytest in `tests/tilt-engine/` that generates Dockerfiles for fixture services with these start scripts: `bun run dist/index.js`, `bun dist/index.js`, `bun run dist/index.js --port 4000`, `NODE_ENV=x bun run dist/index.js`, `tsc && bun dist/index.js`, and no `start`. Assert the resulting `CMD` for each.
+- [x] 2.2 Apply the resolver where every Bun `CMD` is emitted: the backend runtime (plain and Infisical-entrypoint paths) and the Bun-static frontend in `l4_runtime_layers.star`. Upstream `cmd` defaults stay as the no-override value and explicit overrides are kept (design D1). Verify with `test_backend_cmd_follows_start_script` (both paths) and `test_explicit_cmd_override_is_kept`.
+- [x] 2.3 Emit `init: true` for generated backend and frontend runtime services in `compose.star`. Verify with a pytest asserting `init: true` on both service kinds in a generated compose file.
+- [ ] 2.4 Build one real backend (`cash-management-api` in `tdk-erp-system`) from the new layers. Verify that `docker top` lists exactly one Bun process running `dist/index.js`, and that `docker stop` finishes in under 3 s.
+
+## 3. Healthchecks (D3, D4)
+
+- [x] 3.1 Set `get_docker_healthcheck_config` to `interval 30`, `start_interval 2`, `start_period 30`, `retries 3`, and add `--start-interval` to every golden `HEALTHCHECK`. Verify with a pytest on the generated `golden-layers.Dockerfile` asserting `--interval=30s --start-interval=2s` on each stage.
+- [x] 3.2 Make `compose.star` (lines 141, 264) and `traefik_standalone.star` read the shared healthcheck config instead of hard-coding `10s`. Verify with a pytest asserting that generated compose files contain `interval: 30s` and `start_interval: 2s` and no `interval: 10s` for app services.
+- [ ] 3.3 Replace the golden migrator `bunx prisma --version` healthcheck with `HEALTHCHECK NONE` (design D4). Verify with a pytest asserting that no generated golden stage or migrator runtime contains `bunx` or `npx` in a `HEALTHCHECK`, and that after a golden rebuild `docker inspect <prefix>-l4-migrator:latest` shows `Healthcheck.Test` = `["NONE"]`.
+- [x] 3.4 Add a `tdk doctor` check for Docker Engine 25+ and Compose 2.20.2+ in `cli/src/commands/doctor.ts`, with vitest cases in `cli/src/commands/__tests__/doctor.test.ts` for an old version (fails, with an upgrade hint) and a current one (passes). Verify with `bun run test -- doctor.test.ts`.
+- [ ] 3.5 Verify startup readiness with `docker events`: a freshly started backend is marked `healthy` within 5 s of its first successful `/health` response.
+
+## 4. Golden image contents (D5)
+
+- [ ] 4.1 Remove `RUN apk add --no-cache hugo` from the `l4_backend_bun` stage in `golden_image_dockerfile.star`. Verify that `docker run --rm <prefix>-l4-backend:latest which hugo` exits non-zero, and that `docker image inspect` shows the image about 57 MB smaller than before.
+- [x] 4.2 Pass the manifest from `manifest_resource.star` to `Docker.backend` so the feature-gated install actually runs (design D5), then verify: a service with `"featuresEnabled": ["hugo"]` gets `apk add --no-cache hugo` in its generated Dockerfile and a service without it does not (`test_hugo_installed_only_for_services_declaring_it`).
+
+## 5. Footprint budget and docs (D6)
+
+- [ ] 5.1 Add `scripts/measure-idle-footprint.sh <container>`. It waits for the running backend container to be `healthy`, counts Bun processes, samples `docker stats` for 60 s, and exits non-zero if it finds more than one Bun process, memory over 64 MiB, or average CPU of 2% or more. (It measures an existing container instead of generating a template backend, because generation needs a whole project. The ERP backends are generated from the default template.) Verify it passes against a finance backend built from the new layers.
+- [ ] 5.2 Document the minimum Docker Engine / Compose versions, the `TDK_HEALTHCHECK_*` overrides, the `featuresEnabled: ["hugo"]` migration note, and how to run the footprint script in `cli/README.md` (the repo has no root README). Verify the documented commands run as written.
+
+## 6. Integration
+
+- [ ] 6.1 Re-vendor into `tdk-erp-system` (`tdk project --yes`, touch the Tiltfile, rebuild golden layers) and run `tdk up finance`. Verify that every finance service is healthy and answers HTTP 200, and record per-container idle memory next to the baseline in proposal.md.
+- [ ] 6.2 Measurement only: start the full `tdk-erp-system` landscape on the 16 GB reference machine. Record load average, free memory, and `docker ps` latency against the 2026-09-25 baseline, then add the numbers to proposal.md. This informs the separate default-startup-scope change and is not a pass/fail gate.

package/openspec/changes/prioritized-cold-start/.openspec.yaml

@@ -0,0 +1,4 @@
+schema: spec-driven
+created: 2026-09-26
+goal: Requests to a not-yet-running resource trigger and prioritize its startup
+  instead of waiting behind the full dependency graph