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

package/engine/topologies/platform/docker/layers/l4_runtime_layers.star

@@ -1,7 +1,6 @@
 # === INLINED CONSTANTS for pure extension loading ===
 BASE_PORT_FRONTEND = 3000
 BASE_PORT_BACKEND = 4000
-get_docker_healthcheck_config = lambda: {"path": "/health", "interval": "10s", "timeout": "5s"}
 OUTPUT = struct(AUTOGENERATED_FOLDER = ".autogenerated")
 # === END INLINED CONSTANTS ===
 
@@ -29,6 +28,7 @@ load('./prisma/prisma_runtime.star',
 )
 
 load('./bun_helpers.star', 'bun_hoisted_packages_symlink_fix')
+load('../config/healthcheck.star', 'DOCKER_HEALTHCHECK', 'dockerfile_healthcheck_flags')
 load('./infisical/infisical_docker.star', 'InfisicalDocker')
 
 
@@ -51,8 +51,55 @@ _docker_cfg = GLOBAL_CONFIG['docker']
 GOLDEN_L4_BACKEND_IMAGE = _docker_cfg.get('golden_l4_backend_image', _GOLDEN_PREFIX + '-l4-backend:latest')
 GOLDEN_L4_FRONTEND_IMAGE = _docker_cfg.get('golden_l4_frontend_image', _GOLDEN_PREFIX + '-l4-frontend:latest')
 
-# Load Docker healthcheck configuration
-_docker_health = get_docker_healthcheck_config()
+DEFAULT_BUN_START_COMMAND = 'bun run start'
+
+_ENTRY_FILE_EXTENSIONS = ['.js', '.mjs', '.cjs', '.ts', '.mts', '.cts', '.jsx', '.tsx']
+_SHELL_CHARS = ['=', '&', '|', ';', '$', '`', '<', '>', '(', ')', '"', "'", '*', '\\']
+
+
+def _is_entry_file(token):
+    if token.startswith('-'):
+        return False
+    for ch in _SHELL_CHARS:
+        if ch in token:
+            return False
+    for ext in _ENTRY_FILE_EXTENSIONS:
+        if token.endswith(ext):
+            return True
+    return False
+
+
+def start_command_from_script(start_script):
+    """
+    `bun run start` starts a Bun wrapper that spawns a second Bun runtime for the
+    real server. When the start script only runs one entry file, run that file
+    directly so each container holds a single Bun process. Anything else keeps
+    `bun run start` so custom start scripts behave exactly as before.
+    """
+    tokens = (start_script or '').split()
+    if len(tokens) == 3 and tokens[0] == 'bun' and tokens[1] == 'run' and _is_entry_file(tokens[2]):
+        return 'bun ' + tokens[2]
+    if len(tokens) == 2 and tokens[0] == 'bun' and _is_entry_file(tokens[1]):
+        return 'bun ' + tokens[1]
+    return DEFAULT_BUN_START_COMMAND
+
+
+def resolve_bun_start_command(res_path, cmd = DEFAULT_BUN_START_COMMAND):
+    """Resolve the runtime command from the service's package.json `start` script."""
+    if cmd != DEFAULT_BUN_START_COMMAND:
+        return cmd
+    package_json_path = res_path + '/package.json'
+    if not res_path.startswith('/'):
+        package_json_path = os.environ.get('TDK_PROJECT_ROOT', '.') + '/' + package_json_path
+    if not os.path.exists(package_json_path):
+        return cmd
+    package_json = read_json(package_json_path, default = {}) or {}
+    scripts = package_json.get('scripts', {}) or {}
+    return start_command_from_script(scripts.get('start', ''))
+
+
+def _cmd_instruction(command):
+    return "CMD [" + ", ".join(["\"" + part + "\"" for part in command.split()]) + "]\n"
 
 
 def L4_generate_backend_runtime(res_path, port = BASE_PORT_BACKEND, cmd = 'bun run start', use_infisical = False, resource_name = 'service', use_golden = True, use_prisma = True, has_prisma_config = False, manifest = None):
@@ -79,6 +126,7 @@ def L4_generate_backend_runtime(res_path, port = BASE_PORT_BACKEND, cmd = 'bun r
     """
     # Normalize res_path for Docker COPY (must be relative to build context)
     res_path_rel = normalize_res_path(res_path)
+    cmd = resolve_bun_start_command(res_path, cmd)
     
     # Use golden L4-backend image if enabled (production-optimized backend runtime)
     base_image = GOLDEN_L4_BACKEND_IMAGE if use_golden else BUN_BASE
@@ -91,9 +139,6 @@ def L4_generate_backend_runtime(res_path, port = BASE_PORT_BACKEND, cmd = 'bun r
         "ARG SKIP_INFISICAL_SETUP=0\n",
         "ENV NODE_ENV=production\n",
         "COPY --from=l3_production_purger /app/" + res_path + "/node_modules ./node_modules\n",
-        # Bun isolated linker creates service symlinks that resolve through /app/node_modules/.bun.
-        # Copy from production_purger to avoid dragging full dev dependency store into runtime.
-        "COPY --from=l3_production_purger /app/" + res_path + "/node_modules/.bun /app/node_modules/.bun\n",
         prisma_runtime_copy(res_path) if use_prisma else "",
         prisma_cli_runtime_copy(res_path) if use_prisma else "",
         "COPY --from=l3_backend_build /app/" + res_path + "/dist ./dist\n",
@@ -124,12 +169,7 @@ def L4_generate_backend_runtime(res_path, port = BASE_PORT_BACKEND, cmd = 'bun r
     
     # Only add healthcheck if not using golden image (already in golden L4)
     if not use_golden:
-        parts.append("HEALTHCHECK --interval={}s --timeout={}s --start-period={}s --retries={} CMD bun --version || exit 1\n".format(
-            _docker_health["interval_seconds"],
-            _docker_health["timeout_seconds"],
-            _docker_health["start_period_seconds"],
-            _docker_health["retries"],
-        ))
+        parts.append("HEALTHCHECK " + dockerfile_healthcheck_flags() + " CMD bun --version || exit 1\n")
     
     if use_infisical:
         # Use InfisicalDocker generator for proper secret injection setup
@@ -143,7 +183,7 @@ def L4_generate_backend_runtime(res_path, port = BASE_PORT_BACKEND, cmd = 'bun r
         )
         parts.append(infisical_setup)
     else:
-        parts.append("CMD [\"" + cmd + "\"]\n")
+        parts.append(_cmd_instruction(cmd))
 
     # Provide build targets that match external tooling (e.g. --target production/ development)
     parts.append("\nFROM l4_backend_runtime AS production\nFROM l4_backend_runtime AS development\n")
@@ -184,12 +224,7 @@ def L4_generate_frontend_runtime(res_path, target_path = '/usr/share/nginx/html'
             + "COPY --from=l3_frontend_build /app/" + res_path + "/dist " + target_path + "\n"
             + "COPY " + res_path_rel + "/" + OUTPUT.AUTOGENERATED_FOLDER + "/nginx.autogenerated.conf /etc/nginx/conf.d/default.conf\n"
             + "EXPOSE 80\n"
-            + ("" if use_golden else "HEALTHCHECK --interval={}s --timeout={}s --start-period={}s --retries={} CMD curl -f http://localhost/ || exit 1\n".format(
-                _docker_health["interval_seconds"],
-                _docker_health["timeout_seconds"],
-                _docker_health["frontend_start_period_seconds"],
-                _docker_health["retries"],
-            ))
+            + ("" if use_golden else "HEALTHCHECK " + dockerfile_healthcheck_flags(DOCKER_HEALTHCHECK["frontend_start_period_seconds"]) + " CMD curl -f http://localhost/ || exit 1\n")
             + "CMD [\"nginx\", \"-g\", \"daemon off;\"]\n"
             + "FROM l4_frontend_runtime AS production\n"
             + "FROM l4_frontend_runtime AS development\n"
@@ -208,7 +243,7 @@ def L4_generate_frontend_runtime(res_path, target_path = '/usr/share/nginx/html'
         + "COPY --from=l3_frontend_build /app/" + res_path + "/" + OUTPUT.AUTOGENERATED_FOLDER + " ./" + OUTPUT.AUTOGENERATED_FOLDER + "\n"
         + "COPY " + res_path_rel + "/package.json ./package.json\n"
         + "EXPOSE " + str(expose_port) + "\n"
-        + 'CMD ["bun", "run", "start"]\n'
+        + _cmd_instruction(resolve_bun_start_command(res_path))
         + "FROM l4_frontend_runtime AS production\n"
         + "FROM l4_frontend_runtime AS development\n"
     )

package/engine/topologies/platform/docker/networking/traefik_static_routes.star

@@ -0,0 +1,107 @@
+# =============================================================================
+# Traefik static (file-provider) route for a deferred (`sablier.deferStart`)
+# resource -- see openspec/changes/prioritized-cold-start.
+# =============================================================================
+# A never-created resource has no container and thus no Docker labels, so its
+# route can't come from Traefik's Docker-label discovery the way every other
+# resource's does. This generates the file-provider equivalent instead:
+# same routing rule as the Docker-label `-project` router (traefik.star's
+# get_backend_traefik_labels), but pointed at the wake gateway with a fixed
+# LOW priority so the real, Docker-discovered router always wins once the
+# container exists (verified empirically -- see design.md D4: at equal
+# priority the file-provider router won even when the Docker-discovered
+# backend was healthy).
+#
+# Config for a request travels to the gateway via headers (X-Wake-*), not
+# the path/query, so the original request path reaches the real backend
+# unchanged once the resource is ready (see wake-gateway/server.ts).
+
+load("./traefik_helpers.star", "project_backend_rule", "build_entrypoints")
+load("./traefik_constants.star",
+    "TRAEFIK_BACKEND_ENABLE_HTTP",
+    "TRAEFIK_BACKEND_ENABLE_HTTPS",
+)
+
+STATIC_ROUTE_PRIORITY = 1
+
+
+def _container_name(compose_project_name, res_name):
+    """Docker Compose's own naming convention: <project>-<service>-<replica>.
+
+    Confirmed empirically against a live TDK container (analytics-autogenerated
+    -data-governance-api-1) -- see design.md D2 Context. Always replica 1: a
+    deferred resource's replica count is unrelated to which single instance
+    the wake gateway needs to address."""
+    return compose_project_name + "-" + res_name + "-1"
+
+
+def generate_static_wake_route(
+    resource_entry_name,
+    compose_project_name,
+    manifest,
+    internal_port,
+    gateway_host,
+    gateway_port,
+    dependencies=None,
+):
+    """YAML for one resource's Traefik file-provider dynamic-config entry.
+
+    `dependencies` is a list of (res_name, compose_project_name) tuples for
+    the resource's required startup dependencies (D5) -- each may live in a
+    different compose project than the resource itself, so the project name
+    travels alongside the resource name rather than being assumed shared.
+
+    Written to the directory PlatformDockerConstants.TRAEFIK_DYNAMIC_DIR_REL
+    mounts into the standalone Traefik container (traefik_standalone.star).
+    """
+    dependencies = dependencies or []
+
+    rule = project_backend_rule(manifest, resource_entry_name)
+    entrypoints = build_entrypoints(TRAEFIK_BACKEND_ENABLE_HTTP, TRAEFIK_BACKEND_ENABLE_HTTPS)
+    router_name = resource_entry_name + "-wake"
+    middleware_name = resource_entry_name + "-wake-headers"
+    service_name = resource_entry_name + "-wake-gateway"
+    container_name = _container_name(compose_project_name, resource_entry_name)
+    deps_header = ",".join([
+        dep_res_name + "=" + _container_name(dep_project_name, dep_res_name)
+        for dep_res_name, dep_project_name in dependencies
+    ])
+
+    return """# SYSTEM-GENERATED - DO NOT EDIT (sablier.deferStart static wake route)
+http:
+  routers:
+    {router_name}:
+      rule: "{rule}"
+      entryPoints:
+        - {entrypoint}
+      service: {service_name}
+      middlewares:
+        - {middleware_name}
+      priority: {priority}
+  middlewares:
+    {middleware_name}:
+      headers:
+        customRequestHeaders:
+          X-Wake-Resource: "{resource_entry_name}"
+          X-Wake-Container: "{container_name}"
+          X-Wake-Deps: "{deps_header}"
+          X-Wake-Proxy-Port: "{internal_port}"
+  services:
+    {service_name}:
+      loadBalancer:
+        servers:
+          - url: "http://{gateway_host}:{gateway_port}"
+""".format(
+        router_name=router_name,
+        rule=rule,
+        entrypoint=entrypoints.split(",")[0],
+        service_name=service_name,
+        middleware_name=middleware_name,
+        priority=STATIC_ROUTE_PRIORITY,
+        resource_entry_name=resource_entry_name,
+        container_name=container_name,
+        deps_header=deps_header,
+        internal_port=internal_port,
+        gateway_host=gateway_host,
+        gateway_port=gateway_port,
+    )

package/engine/topologies/tilt/generators/typescript/backend_tsconfig.star

@@ -64,7 +64,7 @@ def generate_backend_tsconfig(resource_path, prisma_path, write_fn, internal_dep
         # isolated linker), while @types/node is only a transitive dependency of
         # bun-types and isn't hoisted to the top level under the isolated linker -
         # "types": ["node"] fails to resolve there even though it works locally.
-        "types": ["bun"],
+        "types": ["node"],
     }
     content = {
         "compilerOptions": compiler_options,
@@ -114,7 +114,7 @@ def generate_backend_tsconfig(resource_path, prisma_path, write_fn, internal_dep
             "outDir": "./dist",
             "rootDir": docker_root_dir,
             # See note above: "bun" resolves under the isolated linker, "node" doesn't.
-            "types": ["bun"],
+            "types": ["node"],
         }
         docker_content = {
             "compilerOptions": docker_compiler_options,

package/engine/topologies/tilt/generators/typescript/frontend_tsconfig.star

@@ -93,7 +93,7 @@ def generate_frontend_tsconfig(resource_path, write_fn, internal_deps=None, is_d
             # (including Docker's isolated linker), while @types/node (when only pulled in
             # transitively, e.g. via bun-types) isn't hoisted under the isolated linker and
             # "types": ["node"] fails to resolve there even though it works locally.
-            "types": ["bun"],
+            "types": ["node"],
         },
         "exclude": [
             "node_modules",

package/engine/topologies/tilt/manifest/schema.star

@@ -277,6 +277,12 @@ MANIFEST_SCHEMA = {
                 'description': 'How long the resource stays up after its last request, as a Go duration (e.g. "10m", "1h")',
                 'example': '10m',
             },
+            'deferStart': {
+                'type': 'boolean',
+                'required': False,
+                'default': False,
+                'description': 'Skip this resource during tdk up entirely (no container is created or started); a Traefik static route wakes it and its dependencies on the first request instead. Requires enable: true.',
+            },
         },
         'description': 'On-demand scaling via Sablier: stop idle containers, wake them on the next request. Not recommended for stateful resources (databases) with in-flight writes. (Premium - requires TDK_LICENSE_KEY; see hasSablierLicense() in extension-fetch.ts)',
     },

package/engine/topologies/tilt/manifest/validator.star

@@ -388,6 +388,22 @@ def _validate_cross_field(manifest, context):
         else:
             stats['rules_passed'] += 1
     
+    # sablier.deferStart requires sablier.enable
+    sablier = manifest.get('sablier', {}) or {}
+    if sablier.get('deferStart', False):
+        stats['fields_checked'] += 1
+
+        if not sablier.get('enable', False):
+            errors.append(ManifestErrors.new(
+                message="sablier.deferStart requires sablier.enable to also be true",
+                category=ManifestErrors.CATEGORY['VALIDATION'],
+                severity=ManifestErrors.SEVERITY['ERROR'],
+                context={'field': 'sablier.deferStart', 'sablier': sablier},
+            ))
+            stats['rules_failed'] += 1
+        else:
+            stats['rules_passed'] += 1
+
     # Backend should have Traefik config
     if app_type == 'backend':
         stats['fields_checked'] += 1

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')
+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)
@@ -219,9 +286,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 +312,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 +395,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 +462,32 @@ 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'
+                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),
+                ))
+
         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.