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

package/tests/tilt-engine/test_runtime_container_footprint.py

@@ -0,0 +1,162 @@
+"""
+Runtime container footprint: single Bun process, cheap healthchecks, lean golden images.
+
+Executes the real Starlark generators through Tilt's interpreter
+(`tilt alpha tiltfile-result`) instead of inspecting source text.
+Spec: openspec/changes/optimize-runtime-docker-layers/specs/runtime-container-footprint/spec.md
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+pytestmark = [
+    pytest.mark.generator,
+    pytest.mark.skipif(shutil.which("tilt") is None, reason="tilt CLI not installed"),
+]
+
+DOCKER_DIR = Path(__file__).resolve().parents[2] / "engine" / "topologies" / "platform" / "docker"
+RESULT_MARKER = "Error in fail: RESULT"
+
+
+def run_starlark(tmp_path: Path, body: str, env: dict | None = None) -> dict:
+    """Run `body` in a Tiltfile; `body` must assign a dict to `r`. `@DOCKER` is the engine docker dir."""
+    tiltfile = tmp_path / "Tiltfile"
+    tiltfile.write_text(
+        f"HERE = '{tmp_path}'\n"
+        + body.replace("@DOCKER", str(DOCKER_DIR))
+        + "\nfail('RESULT' + encode_json(r))\n"
+    )
+    proc = subprocess.run(
+        ["tilt", "alpha", "tiltfile-result", "-f", str(tiltfile)],
+        capture_output=True,
+        text=True,
+        env={**os.environ, **(env or {})},
+        timeout=180,
+    )
+    output = proc.stdout + proc.stderr
+    assert RESULT_MARKER in output, output[-3000:]
+    return json.loads(output.split(RESULT_MARKER, 1)[1].strip())
+
+
+def write_service(tmp_path: Path, name: str, start_script: str | None) -> None:
+    service_dir = tmp_path / name
+    service_dir.mkdir()
+    scripts = {} if start_script is None else {"start": start_script}
+    (service_dir / "package.json").write_text(json.dumps({"name": name, "scripts": scripts}))
+
+
+def cmd_lines(dockerfile: str) -> list[str]:
+    return [line for line in dockerfile.splitlines() if line.startswith("CMD ")]
+
+
+def healthcheck_lines(dockerfile: str) -> list[str]:
+    return [line for line in dockerfile.splitlines() if line.startswith("HEALTHCHECK")]
+
+
+@pytest.mark.parametrize(
+    ("start_script", "expected_cmd"),
+    [
+        ("bun run dist/index.js", 'CMD ["bun", "dist/index.js"]'),
+        ("bun dist/index.js", 'CMD ["bun", "dist/index.js"]'),
+        ("bun run dist/index.js --port 4000", 'CMD ["bun", "run", "start"]'),
+        ("NODE_ENV=x bun run dist/index.js", 'CMD ["bun", "run", "start"]'),
+        ("tsc && bun dist/index.js", 'CMD ["bun", "run", "start"]'),
+        ("bun run serve", 'CMD ["bun", "run", "start"]'),
+        (None, 'CMD ["bun", "run", "start"]'),
+    ],
+)
+def test_backend_cmd_follows_start_script(tmp_path, start_script, expected_cmd):
+    write_service(tmp_path, "svc", start_script)
+    r = run_starlark(
+        tmp_path,
+        "load('@DOCKER/layers/l4_runtime_layers.star', 'L4_generate_backend_runtime')\n"
+        "r = {\n"
+        "  'plain': L4_generate_backend_runtime(HERE + '/svc'),\n"
+        "  'infisical': L4_generate_backend_runtime(HERE + '/svc', use_infisical=True, resource_name='svc'),\n"
+        "}\n",
+    )
+    assert cmd_lines(r["plain"]) == [expected_cmd]
+    assert cmd_lines(r["infisical"]) == [expected_cmd]
+    assert 'ENTRYPOINT ["/entrypoint.sh"]' in r["infisical"]
+
+
+def test_explicit_cmd_override_is_kept(tmp_path):
+    write_service(tmp_path, "svc", "bun run dist/index.js")
+    r = run_starlark(
+        tmp_path,
+        "load('@DOCKER/layers/l4_runtime_layers.star', 'L4_generate_backend_runtime')\n"
+        "r = {'df': L4_generate_backend_runtime(HERE + '/svc', cmd='bun run start:prod')}\n",
+    )
+    assert cmd_lines(r["df"]) == ['CMD ["bun", "run", "start:prod"]']
+
+
+def test_hugo_installed_only_for_services_declaring_it(tmp_path):
+    write_service(tmp_path, "svc", "bun run dist/index.js")
+    r = run_starlark(
+        tmp_path,
+        "load('@DOCKER/layers/l4_runtime_layers.star', 'L4_generate_backend_runtime')\n"
+        "r = {\n"
+        "  'with': L4_generate_backend_runtime(HERE + '/svc', manifest={'featuresEnabled': ['hugo']}),\n"
+        "  'without': L4_generate_backend_runtime(HERE + '/svc', manifest={'featuresEnabled': []}),\n"
+        "}\n",
+    )
+    assert "apk add --no-cache hugo" in r["with"]
+    assert "apk add --no-cache hugo" not in r["without"]
+
+
+def test_golden_dockerfile_is_lean_and_uses_shared_healthcheck(tmp_path):
+    r = run_starlark(
+        tmp_path,
+        "load('@DOCKER/build/golden_image_dockerfile.star', 'generate_golden_dockerfile')\n"
+        "r = {'df': generate_golden_dockerfile()}\n",
+    )
+    df = r["df"]
+    backend_bun_stage = df.split("AS l4_backend_bun", 1)[1].split("\nFROM ", 1)[0]
+    migrator_stage = df.split("AS l4_migrator_golden", 1)[1].split("\nFROM ", 1)[0]
+
+    assert "apk add --no-cache hugo" not in backend_bun_stage
+    assert "HEALTHCHECK NONE" in migrator_stage
+
+    checks = healthcheck_lines(df)
+    assert checks, "golden Dockerfile has no HEALTHCHECK instructions"
+    for line in checks:
+        assert "bunx" not in line and "npx" not in line, line
+        if line != "HEALTHCHECK NONE":
+            assert "--interval=30s --start-interval=2s" in line, line
+
+
+def test_compose_entries_use_init_and_shared_healthcheck(tmp_path):
+    r = run_starlark(
+        tmp_path,
+        "load('@DOCKER/compose/compose.star', 'generate_backend_compose_entry', 'generate_frontend_compose')\n"
+        "r = {\n"
+        "  'backend': generate_backend_compose_entry('services/finance', 'finance', {'name': 'cash-api'},"
+        " {'stack': 'finance', 'port': 4018, 'appType': 'backend'}),\n"
+        "  'frontend': generate_frontend_compose('services/finance', 'finance', {'name': 'dash-app'},"
+        " {'stack': 'finance', 'port': 3010, 'appType': 'frontend'}),\n"
+        "}\n",
+    )
+    for kind in ("backend", "frontend"):
+        entry = r[kind]
+        assert "init: true" in entry, kind
+        assert "interval: 30s" in entry, kind
+        assert "start_interval: 2s" in entry, kind
+        assert "interval: 10s" not in entry, kind
+
+
+def test_healthcheck_interval_is_configurable(tmp_path):
+    r = run_starlark(
+        tmp_path,
+        "load('@DOCKER/config/healthcheck.star', 'dockerfile_healthcheck_flags', 'compose_healthcheck_timing')\n"
+        "r = {'flags': dockerfile_healthcheck_flags(), 'timing': compose_healthcheck_timing()}\n",
+        env={"TDK_HEALTHCHECK_INTERVAL_SECONDS": "15"},
+    )
+    assert "--interval=15s" in r["flags"]
+    assert "interval: 15s" in r["timing"]

package/tests/tilt-engine/test_sablier_defer_start.py

@@ -0,0 +1,196 @@
+"""
+sablier.deferStart: schema field and its enable-required cross-field rule.
+
+Executes the real Starlark validator through Tilt's interpreter
+(`tilt alpha tiltfile-result`) instead of inspecting source text.
+Spec: openspec/changes/prioritized-cold-start/specs/on-demand-resource-startup/spec.md
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+pytestmark = [
+    pytest.mark.generator,
+    pytest.mark.skipif(shutil.which("tilt") is None, reason="tilt CLI not installed"),
+]
+
+MANIFEST_DIR = Path(__file__).resolve().parents[2] / "engine" / "topologies" / "tilt" / "manifest"
+ORCHESTRATOR_DIR = Path(__file__).resolve().parents[2] / "engine" / "topologies" / "tilt" / "resources" / "orchestrator"
+RESULT_MARKER = "Error in fail: RESULT"
+
+
+def run_starlark(tmp_path: Path, body: str) -> dict:
+    """Run `body` in a Tiltfile; `body` must assign a dict to `r`. `@MANIFEST`/`@ORCHESTRATOR` are module dirs."""
+    tiltfile = tmp_path / "Tiltfile"
+    tiltfile.write_text(
+        body.replace("@MANIFEST", str(MANIFEST_DIR)).replace("@ORCHESTRATOR", str(ORCHESTRATOR_DIR))
+        + "\nfail('RESULT' + encode_json(r))\n"
+    )
+    proc = subprocess.run(
+        ["tilt", "alpha", "tiltfile-result", "-f", str(tiltfile)],
+        capture_output=True,
+        text=True,
+        timeout=180,
+    )
+    output = proc.stdout + proc.stderr
+    assert RESULT_MARKER in output, output[-3000:]
+    return json.loads(output.split(RESULT_MARKER, 1)[1].strip())
+
+
+def validate_sablier(tmp_path: Path, sablier: dict | None) -> dict:
+    manifest = {"appType": "backend", "stack": "test"}
+    if sablier is not None:
+        manifest["sablier"] = sablier
+    return run_starlark(
+        tmp_path,
+        "load('@MANIFEST/validator.star', 'ManifestValidator')\n"
+        f"manifest = {manifest!r}\n"
+        "result = ManifestValidator.validate(manifest, level='cross_field')\n"
+        "r = {'valid': result.valid, 'errors': [e.message for e in result.errors]}\n",
+    )
+
+
+@pytest.mark.parametrize(
+    "sablier",
+    [
+        None,
+        {"enable": False},
+        {"enable": True},
+        {"enable": True, "deferStart": True},
+        {"enable": True, "deferStart": False},
+    ],
+)
+def test_defer_start_with_enable_is_valid(tmp_path, sablier):
+    r = validate_sablier(tmp_path, sablier)
+    assert r["valid"], r["errors"]
+
+
+def test_defer_start_without_enable_is_rejected(tmp_path):
+    r = validate_sablier(tmp_path, {"deferStart": True})
+    assert not r["valid"]
+    assert any("deferStart" in e and "enable" in e for e in r["errors"]), r["errors"]
+
+
+def test_defer_start_with_enable_false_is_rejected(tmp_path):
+    r = validate_sablier(tmp_path, {"enable": False, "deferStart": True})
+    assert not r["valid"]
+    assert any("deferStart" in e and "enable" in e for e in r["errors"]), r["errors"]
+
+
+def resource_defers_start(tmp_path: Path, sablier: dict | None) -> bool:
+    manifest = {"appType": "backend", "stack": "test"}
+    if sablier is not None:
+        manifest["sablier"] = sablier
+    result = run_starlark(
+        tmp_path,
+        "load('@ORCHESTRATOR/apply_compose_resource_registration.star', 'resource_defers_start')\n"
+        f"manifest = {manifest!r}\n"
+        "r = {'defers': resource_defers_start(manifest)}\n",
+    )
+    return result["defers"]
+
+
+@pytest.mark.parametrize(
+    "sablier",
+    [
+        None,
+        {},
+        {"enable": False},
+        {"enable": True},
+        {"enable": False, "deferStart": True},
+        {"enable": True, "deferStart": False},
+        {"enable": True, "deferStart": True},
+    ],
+)
+def test_resource_defers_start_stays_off_without_a_license(tmp_path, sablier):
+    """deferStart stays behind the same TDK_LICENSE_KEY gate as the rest of
+    `sablier` (an explicit product decision -- see openspec/changes/
+    prioritized-cold-start's design.md). This repo ships only the free-tier
+    `sablier_container_cycle.star` stub, whose sablier_middleware_suffix()
+    always reports disabled regardless of the manifest -- so every case here
+    must resolve to False, including {"enable": True, "deferStart": True}.
+    The corresponding "licensed and enabled" True case can only be exercised
+    where the real premium module is actually vendored (tdk-cli-extensions),
+    not from this repo's stub."""
+    assert resource_defers_start(tmp_path, sablier) is False
+
+
+def _run_resolve_deps(tmp_path: Path, manifest: dict, resource_manifests: dict, all_services_map: dict) -> list:
+    result = run_starlark(
+        tmp_path,
+        "load('@ORCHESTRATOR/apply_compose_resource_registration.star', 'resolve_defer_start_dependencies')\n"
+        f"manifest = {manifest!r}\n"
+        f"resource_manifests = {resource_manifests!r}\n"
+        f"all_services_map = {all_services_map!r}\n"
+        "r = {'deps': [list(pair) for pair in resolve_defer_start_dependencies(manifest, resource_manifests, all_services_map)]}\n",
+    )
+    return result["deps"]
+
+
+LICENSED_SABLIER_MANIFEST = {"appType": "backend", "stack": "test", "sablier": {"enable": True, "deferStart": True}}
+
+
+def test_resolve_defer_start_dependencies_excludes_non_defer_dependency(tmp_path):
+    """A dependsOn entry that resolves to a real resource with no sablier.deferStart
+    (e.g. always-on infra, or a normal backend) contributes nothing to X-Wake-Deps."""
+    manifest = {"appType": "backend", "stack": "test", "dependsOn": ["plain-backend"]}
+    resource_manifests = {"plain-backend": {"appType": "backend", "stack": "other"}}
+    all_services_map = {"plain-backend": {"name": "other-service", "resources": [{"name": "plain-backend"}]}}
+    assert _run_resolve_deps(tmp_path, manifest, resource_manifests, all_services_map) == []
+
+
+def test_resolve_defer_start_dependencies_excludes_unresolvable_name(tmp_path):
+    """A dependsOn short name that doesn't match any known resource/service falls
+    back (via _resolve_dependency_to_resource) to a name absent from
+    resource_manifests, so it's quietly excluded rather than guessed at (D5)."""
+    manifest = {"appType": "backend", "stack": "test", "dependsOn": ["nonexistent-thing"]}
+    assert _run_resolve_deps(tmp_path, manifest, {}, {}) == []
+
+
+def test_resolve_defer_start_dependencies_stays_empty_without_a_license(tmp_path):
+    """Even when a dependsOn entry resolves to a resource whose manifest asks for
+    sablier.deferStart, this repo's free-tier stub keeps resource_defers_start()
+    False for it too (same license gate as the resource's own deferStart check),
+    so it's excluded here just as it would be for the resource itself."""
+    manifest = {"appType": "backend", "stack": "test", "dependsOn": ["peer-backend"]}
+    resource_manifests = {"peer-backend": LICENSED_SABLIER_MANIFEST}
+    all_services_map = {"peer-backend": {"name": "peer-service", "resources": [{"name": "peer-backend"}]}}
+    assert _run_resolve_deps(tmp_path, manifest, resource_manifests, all_services_map) == []
+
+
+def test_resolve_defer_start_dependencies_no_depends_on(tmp_path):
+    manifest = {"appType": "backend", "stack": "test"}
+    assert _run_resolve_deps(tmp_path, manifest, {}, {}) == []
+
+
+def _run_resolve_names(tmp_path: Path, manifest: dict, all_services_map: dict) -> list:
+    result = run_starlark(
+        tmp_path,
+        "load('@ORCHESTRATOR/apply_compose_resource_registration.star', 'resolve_manifest_dependency_names')\n"
+        f"manifest = {manifest!r}\n"
+        f"all_services_map = {all_services_map!r}\n"
+        "r = {'names': resolve_manifest_dependency_names(manifest, all_services_map)}\n",
+    )
+    return result["names"]
+
+
+def test_resolve_manifest_dependency_names_exact_match(tmp_path):
+    """The common case: dependsOn already names a real resource exactly, so
+    _resolve_dependency_to_resource returns it unchanged (no '-yaml' guess)."""
+    manifest = {"dependsOn": ["identity-management-backend"]}
+    all_services_map = {
+        "identity-management-backend": {"name": "identity-management", "resources": [{"name": "identity-management-backend"}]},
+    }
+    assert _run_resolve_names(tmp_path, manifest, all_services_map) == ["identity-management-backend"]
+
+
+def test_resolve_manifest_dependency_names_dedupes_and_skips_empty(tmp_path):
+    manifest = {"dependsOn": []}
+    assert _run_resolve_names(tmp_path, manifest, {}) == []

package/tests/tilt-engine/test_standalone_traefik.py

@@ -1,5 +1,8 @@
 """Standalone TDK projects must serve api.{project}.localhost via Traefik."""
 
+import json
+import shutil
+import subprocess
 from pathlib import Path
 
 import pytest
@@ -7,6 +10,22 @@ import pytest
 pytestmark = [pytest.mark.fast, pytest.mark.generator]
 
 REPO_ROOT = Path(__file__).resolve().parents[2]
+COMPOSE_DIR = REPO_ROOT / "engine" / "topologies" / "platform" / "docker" / "compose"
+RESULT_MARKER = "Error in fail: RESULT"
+
+
+def _run_starlark(tmp_path: Path, body: str) -> dict:
+    tiltfile = tmp_path / "Tiltfile"
+    tiltfile.write_text(body.replace("@COMPOSE", str(COMPOSE_DIR)) + "\nfail('RESULT' + encode_json(r))\n")
+    proc = subprocess.run(
+        ["tilt", "alpha", "tiltfile-result", "-f", str(tiltfile)],
+        capture_output=True,
+        text=True,
+        timeout=180,
+    )
+    output = proc.stdout + proc.stderr
+    assert RESULT_MARKER in output, output[-3000:]
+    return json.loads(output.split(RESULT_MARKER, 1)[1].strip())
 
 
 def test_standalone_traefik_compose_generator_exists():
@@ -106,3 +125,36 @@ def test_traefik_conflict_takeover_stops_other_project_and_logs_it():
     # instead of just erroring out.
     assert "docker stop" in stop_body
     assert "print(" in stop_body
+
+
+@pytest.mark.skipif(shutil.which("tilt") is None, reason="tilt CLI not installed")
+def test_standalone_compose_enables_file_provider_and_wake_gateway(tmp_path):
+    """openspec/changes/prioritized-cold-start (D4): a `sablier.deferStart`
+    resource's static route needs Traefik's file provider enabled and a wake
+    gateway running, even in a landscape with no such resource yet (harmless:
+    an empty dynamic directory yields zero extra routes)."""
+    r = _run_starlark(
+        tmp_path,
+        "load('@COMPOSE/traefik_standalone.star', 'generate_standalone_traefik_compose')\n"
+        "r = {'yaml': generate_standalone_traefik_compose()}\n",
+    )
+    yaml_text = r["yaml"]
+    assert "--providers.file.directory=/etc/traefik/dynamic" in yaml_text
+    assert "--providers.file.watch=true" in yaml_text
+    assert "/etc/traefik/dynamic:ro" in yaml_text
+    assert "wake-gateway:" in yaml_text
+    assert "/root/.tilt-dev:ro" in yaml_text
+
+
+@pytest.mark.skipif(shutil.which("tilt") is None, reason="tilt CLI not installed")
+def test_wake_gateway_mounts_project_root_at_its_own_absolute_path(tmp_path):
+    """The gateway runs `docker compose up --no-build` with the same compose
+    files Tilt uses; relative paths inside them resolve client-side, so the
+    project must exist at the same absolute path in the gateway container."""
+    r = _run_starlark(
+        tmp_path,
+        "os.environ['TDK_PROJECT_ROOT'] = '/Users/dev/tdk-erp-system/.tdk/.tdk-out/../..'\n"
+        "load('@COMPOSE/traefik_standalone.star', 'generate_standalone_traefik_compose')\n"
+        "r = {'yaml': generate_standalone_traefik_compose()}\n",
+    )
+    assert "- /Users/dev/tdk-erp-system:/Users/dev/tdk-erp-system:ro" in r["yaml"]

package/tests/tilt-engine/test_traefik_static_wake_route.py

@@ -0,0 +1,187 @@
+"""
+Traefik static (file-provider) wake route for `sablier.deferStart` resources.
+
+Executes the real Starlark generators through Tilt's interpreter
+(`tilt alpha tiltfile-result`) instead of inspecting source text.
+Spec: openspec/changes/prioritized-cold-start/specs/on-demand-resource-startup/spec.md
+Design: openspec/changes/prioritized-cold-start/design.md (D4)
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+pytestmark = [
+    pytest.mark.generator,
+    pytest.mark.skipif(shutil.which("tilt") is None, reason="tilt CLI not installed"),
+]
+
+NETWORKING_DIR = Path(__file__).resolve().parents[2] / "engine" / "topologies" / "platform" / "docker" / "networking"
+RESULT_MARKER = "Error in fail: RESULT"
+
+
+def run_starlark(tmp_path: Path, body: str) -> dict:
+    tiltfile = tmp_path / "Tiltfile"
+    tiltfile.write_text(body.replace("@NETWORKING", str(NETWORKING_DIR)) + "\nfail('RESULT' + encode_json(r))\n")
+    proc = subprocess.run(
+        ["tilt", "alpha", "tiltfile-result", "-f", str(tiltfile)],
+        capture_output=True,
+        text=True,
+        timeout=180,
+    )
+    output = proc.stdout + proc.stderr
+    assert RESULT_MARKER in output, output[-3000:]
+    return json.loads(output.split(RESULT_MARKER, 1)[1].strip())
+
+
+MANIFEST = {
+    "appType": "backend",
+    "stack": "analytics",
+    "sablier": {"enable": True, "deferStart": True},
+}
+
+
+def test_static_route_rule_matches_docker_label_project_router(tmp_path):
+    r = run_starlark(
+        tmp_path,
+        "load('@NETWORKING/traefik.star', 'get_backend_traefik_labels')\n"
+        "load('@NETWORKING/traefik_static_routes.star', 'generate_static_wake_route')\n"
+        f"manifest = {MANIFEST!r}\n"
+        "docker_labels = get_backend_traefik_labels(\n"
+        "    'data-governance-api', 'analytics.backend.tdk_erp_system.local', '',\n"
+        "    'data-governance-api', 4604, '/health', manifest=manifest,\n"
+        ")\n"
+        "static_yaml = generate_static_wake_route(\n"
+        "    'data-governance-api', 'analytics-autogenerated', manifest, 4604,\n"
+        "    'tdk-wake-gateway', 9999,\n"
+        "    dependencies=[('postgres', 'analytics-autogenerated')],\n"
+        ")\n"
+        "r = {'docker_labels': docker_labels, 'static_yaml': static_yaml}\n",
+    )
+
+    docker_rule_match = re.search(
+        r'traefik\.http\.routers\.data-governance-api-project\.rule=(.+?)"', r["docker_labels"]
+    )
+    docker_priority_match = re.search(
+        r'traefik\.http\.routers\.data-governance-api-project\.priority=(\d+)"', r["docker_labels"]
+    )
+    assert docker_rule_match and docker_priority_match
+
+    static_rule_match = re.search(r'rule:\s*"(.+?)"', r["static_yaml"])
+    static_priority_match = re.search(r"priority:\s*(\d+)", r["static_yaml"])
+    assert static_rule_match and static_priority_match
+
+    # Same routing rule as the Docker-label path (task 4.2)...
+    assert static_rule_match.group(1) == docker_rule_match.group(1)
+    # ...but a fixed low priority, not the computed one (task 1.4's finding:
+    # at equal priority the file-provider router won even over a healthy
+    # Docker-discovered backend).
+    assert int(static_priority_match.group(1)) == 1
+    assert int(static_priority_match.group(1)) < int(docker_priority_match.group(1))
+
+
+def test_static_route_headers_carry_container_names_not_just_resource_names(tmp_path):
+    r = run_starlark(
+        tmp_path,
+        "load('@NETWORKING/traefik_static_routes.star', 'generate_static_wake_route')\n"
+        f"manifest = {MANIFEST!r}\n"
+        "r = {'yaml': generate_static_wake_route(\n"
+        "    'data-governance-api', 'analytics-autogenerated', manifest, 4604,\n"
+        "    'tdk-wake-gateway', 9999,\n"
+        "    dependencies=[('postgres', 'analytics-autogenerated')],\n"
+        ")}\n",
+    )
+    yaml = r["yaml"]
+    assert 'X-Wake-Resource: "data-governance-api"' in yaml
+    # Container name follows Compose's own <project>-<service>-<replica>
+    # convention, confirmed empirically against a live TDK container.
+    assert 'X-Wake-Container: "analytics-autogenerated-data-governance-api-1"' in yaml
+    assert 'X-Wake-Deps: "postgres=analytics-autogenerated-postgres-1"' in yaml
+    assert 'X-Wake-Proxy-Port: "4604"' in yaml
+
+
+def test_static_route_strips_the_same_api_path_prefix_the_docker_router_does(tmp_path):
+    """Found live against tdk-erp-system (task 7.2): the app itself only
+    serves its bare health path (e.g. `/health`), not the full
+    `/api/data-governance/health` the public route matches on -- the real
+    Docker-label `-project` router strips that prefix (traefik.star), and
+    the wake route's own proxy-through must do the same or a woken resource
+    404s even though the wake itself succeeded."""
+    r = run_starlark(
+        tmp_path,
+        "load('@NETWORKING/traefik_static_routes.star', 'generate_static_wake_route')\n"
+        f"manifest = {MANIFEST!r}\n"
+        "r = {'yaml': generate_static_wake_route(\n"
+        "    'data-governance-api', 'analytics-autogenerated', manifest, 4604,\n"
+        "    'tdk-wake-gateway', 9999,\n"
+        ")}\n",
+    )
+    yaml = r["yaml"]
+    assert "data-governance-api-wake-strip" in yaml
+    assert 'prefixes:\n          - "/api/data-governance"' in yaml
+    # Both middlewares must actually be attached to the router, in strip-then-headers order.
+    strip_idx = yaml.index("- data-governance-api-wake-strip")
+    headers_idx = yaml.index("- data-governance-api-wake-headers")
+    assert strip_idx < headers_idx
+
+
+def test_static_route_with_no_dependencies_omits_deps_header_value(tmp_path):
+    r = run_starlark(
+        tmp_path,
+        "load('@NETWORKING/traefik_static_routes.star', 'generate_static_wake_route')\n"
+        f"manifest = {MANIFEST!r}\n"
+        "r = {'yaml': generate_static_wake_route(\n"
+        "    'data-governance-api', 'analytics-autogenerated', manifest, 4604,\n"
+        "    'tdk-wake-gateway', 9999,\n"
+        ")}\n",
+    )
+    assert 'X-Wake-Deps: ""' in r["yaml"]
+    # No compose details passed -> the gateway can only use `tilt trigger`.
+    assert "X-Wake-Compose-" not in r["yaml"]
+    assert "X-Wake-Image" not in r["yaml"]
+
+
+def test_normalize_abs_path_collapses_dot_segments(tmp_path):
+    """Tilt's os.path.abspath leaves `..` in place; the generated Tiltfile's
+    project root is config.main_dir + '/../..', so this must collapse it."""
+    r = run_starlark(
+        tmp_path,
+        "load('@NETWORKING/traefik_static_routes.star', 'normalize_abs_path')\n"
+        "r = {\n"
+        "  'root': normalize_abs_path('/Users/dev/tdk-erp-system/.tdk/.tdk-out/../..'),\n"
+        "  'dot': normalize_abs_path('/a/./b//c/'),\n"
+        "  'empty': normalize_abs_path(''),\n"
+        "}\n",
+    )
+    assert r == {"root": "/Users/dev/tdk-erp-system", "dot": "/a/b/c", "empty": ""}
+
+
+def test_static_route_carries_compose_invocation_for_direct_start(tmp_path):
+    """With compose details, the gateway can `docker compose up --no-build` the
+    resource itself instead of waiting in Tilt's build queue (task 7.2 finding)."""
+    root = "/Users/dev/tdk-erp-system"
+    compose_file = root + "/services/analytics/.autogenerated/docker-compose.app.autogenerated.yml"
+    override_file = root + "/services/analytics/.autogenerated/docker-compose.port-override.yml"
+    r = run_starlark(
+        tmp_path,
+        "load('@NETWORKING/traefik_static_routes.star', 'generate_static_wake_route')\n"
+        f"manifest = {MANIFEST!r}\n"
+        "r = {'yaml': generate_static_wake_route(\n"
+        "    'data-governance-api', 'analytics-autogenerated', manifest, 4604,\n"
+        "    'tdk-wake-gateway', 9999,\n"
+        f"    compose_files=[{compose_file!r}, {override_file!r}],\n"
+        f"    env_file={root + '/.env'!r},\n"
+        "    image='analytics_data-governance-api:dev',\n"
+        ")}\n",
+    )
+    yaml = r["yaml"]
+    assert 'X-Wake-Compose-Project: "analytics-autogenerated"' in yaml
+    assert f'X-Wake-Compose-Files: "{compose_file},{override_file}"' in yaml
+    assert f'X-Wake-Env-File: "{root}/.env"' in yaml
+    assert 'X-Wake-Image: "analytics_data-governance-api:dev"' in yaml