@flisk-sh/flisk 0.0.0-stage → 1.3.190

package/engine/topologies/platform/docker/compose/compose.star

@@ -0,0 +1,637 @@
+# Copyright (c) 2026 Flisk contributors
+# SPDX-License-Identifier: MIT
+# =============================================================================
+# 🐳 TILT SDK - DOCKER COMPOSE GENERATORS (modular)
+# =============================================================================
+# Path: .tilt/topologies/platform/docker/compose.star
+# Purpose: docker-compose generation helpers extracted from .tilt/providers/docker.star
+# =============================================================================
+
+# === INLINED CONSTANTS for pure extension loading ===
+BASE_PORT_FRONTEND = 3000
+BASE_PORT_BACKEND = 4000
+# The nginx frontend runtime layer always serves on 80: L4_generate_frontend_runtime
+# emits a fixed `EXPOSE 80` and the generated nginx.conf has a fixed `listen 80`.
+NGINX_CONTAINER_PORT = 80
+HEALTH_CHECK_PATH = "/health"
+NO_HTTP_HEALTHCHECK = "    healthcheck:\n      disable: true\n"
+OUTPUT = struct(AUTOGENERATED_FOLDER = ".autogenerated")
+# === END INLINED CONSTANTS ===
+
+
+load("./compose_helpers.star", "compose_build_config")
+load("../networking/traefik.star", "get_frontend_traefik_labels", "get_backend_traefik_labels")
+load("../networking/api_path_constants.star", "get_api_path_for_domain", "get_frontend_base_path")
+load("../secrets/infisical.star", "get_infisical_environment_vars")
+load("../secrets/env_secrets.star", "get_secret_environment_lines")
+load("../auth/auth.star", "AuthConfig")
+
+load("../constants.star", "PlatformDockerConstants")
+load("../config/healthcheck.star", "DOCKER_HEALTHCHECK", "compose_healthcheck_timing")
+
+# Load project name for dynamic host naming
+# Use TDK_PROJECT_ROOT env var set by Tilt, fallback to current directory
+def _load_project_name():
+    project_root = os.environ.get('TDK_PROJECT_ROOT', '')
+    project_json_path = '.tdk/project.json'
+    if project_root:
+        project_json_path = project_root + '/' + project_json_path
+    
+    if os.path.exists(project_json_path):
+        _project_json = read_json(project_json_path)
+        return _project_json.get('project', {}).get('name', 'tdk-project')
+    return 'tdk-project'
+
+_PROJECT_NAME = _load_project_name()
+
+
+def _compute_env_file_rel_path(resource_path, full_resource_path, env_filename):
+    """
+    Compute the relative path from compose file location to env file.
+    
+    The compose file is at: resource_path + '/' + OUTPUT.AUTOGENERATED_FOLDER/docker-compose.app.autogenerated.yml'
+    The env file is at: full_resource_path + '/' + OUTPUT.AUTOGENERATED_FOLDER + '/' + env_filename
+    
+    Args:
+        resource_path: The domain/service group path (e.g., 'services/product/users' or 'services/platform')
+        full_resource_path: The actual service path (e.g., 'services/product/users/user-management-backend' or 'shared-platform-engineering/my-lib/infra')
+        env_filename: The env file name (e.g., '.env.frontend.autogenerated' or '.env.backend.autogenerated')
+    
+    Returns:
+        Relative path from compose file to env file
+    """
+    # Count how many levels deep the compose file is
+    # resource_path like 'services/product/users' has 3 parts
+    # compose file is at resource_path + '/' + OUTPUT.AUTOGENERATED_FOLDER + '/', so we need len(parts) + 1 levels of ../
+    resource_path_parts = resource_path.split('/')
+    num_dotdots = len(resource_path_parts) + 1  # +1 for the autogenerated directory
+    
+    # Build the dotdot prefix
+    dotdot_prefix = '/'.join(['..'] * num_dotdots)
+    
+    # The env file is at full_resource_path + '/' + OUTPUT.AUTOGENERATED_FOLDER + '/' + env_filename
+    return dotdot_prefix + '/' + full_resource_path + '/' + OUTPUT.AUTOGENERATED_FOLDER + '/' + env_filename
+
+# =============================================================================
+# 🚦 FRONTEND / BACKEND ENTRIES
+# =============================================================================
+
+def generate_frontend_compose(resource_path, resource_name, res, manifest=None):
+    """Generate frontend docker-compose entry with Traefik routing."""
+    res_name = res['name']
+    image_name = PlatformDockerConstants.app_image_name(resource_name, res_name)
+    stack = manifest.get('stack', resource_name) if manifest else resource_name
+    
+    target_path = res.get('target_path', manifest.get('target_path', '/usr/share/nginx/html'))
+    use_nginx = 'nginx' in target_path or target_path == '/usr/share/nginx/html'
+    # The manifest `port` is the Vite dev-server port. These compose entries always
+    # build the `production` target, so for an nginx runtime the port inside the
+    # container is 80, not the dev port. Using the dev port here made the container
+    # healthcheck probe a port nothing listens on, which left the container marked
+    # unhealthy -- and Traefik's Docker provider skips unhealthy containers, so the
+    # router was never registered and every request 404'd.
+    port = NGINX_CONTAINER_PORT if use_nginx else manifest.get('port', BASE_PORT_FRONTEND)
+    
+    # Base path for routing on {project}.localhost. Shared with the Vite config and
+    # PUBLIC_URL generators -- see get_frontend_base_path for why they must agree.
+    base_path = get_frontend_base_path(manifest, res_name)
+    
+    traefik_cfg = manifest.get('traefik', {}) if manifest else {}
+    traefik_host = traefik_cfg.get('host')
+    # Use custom dockerfile from manifest if specified, otherwise use autogenerated default
+    dockerfile_path = res.get('dockerfile', OUTPUT.AUTOGENERATED_FOLDER + '/Dockerfile.app.autogenerated')
+    # Handle flat service structure (e.g., services/product/identity-management-frontend) vs nested (services/product/domain/service)
+    # Detect flat structure: services/product/{service} (3 path parts after root) 
+    # vs nested: services/product/{domain}/{service} (4+ path parts)
+    full_resource_path = res.get('_resource_path', resource_path + '/' + res_name)
+    path_parts = full_resource_path.split('/')
+    # If path is like services/product/xxx (3 parts), it's flat - use path directly
+    # If path is like services/product/domain/xxx (4 parts), it's nested - use standard construction
+    if len(path_parts) <= 3:
+        # Flat structure: resource_path already includes res_name
+        build_config = compose_build_config(full_resource_path, '', dockerfile_path, 'production')
+    else:
+        # Nested structure: use resource_path and res_name separately
+        build_config = compose_build_config(resource_path, res_name, dockerfile_path, 'production')
+    
+    # Calculate correct relative path to env_file from compose file location
+    # The compose file is at: resource_path + '/' + OUTPUT.AUTOGENERATED_FOLDER/docker-compose.app.autogenerated.yml'
+    # The env file is at: full_resource_path + '/' + OUTPUT.AUTOGENERATED_FOLDER/.env.frontend.autogenerated'
+    env_file_rel_path = _compute_env_file_rel_path(resource_path, full_resource_path, '.env.frontend.autogenerated')
+    
+    traefik_labels = get_frontend_traefik_labels(
+        res_name,
+        stack,
+        base_path,
+        port,
+        traefik_host=traefik_host,
+        manifest=manifest,
+    )
+    
+    return """  {res_name}:
+    image: {image_name}
+    init: true
+{build_config}
+    <<: *frontend-memory-limit
+    env_file:
+      - {env_file_rel_path}
+    environment:
+        - VITE_APP_ENV=development
+    labels:
+{traefik_labels}
+    networks:
+        - {network_traefik_public}
+        - {network_backend}
+    healthcheck:
+      test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://127.0.0.1:{port}"]
+{healthcheck_timing}""".format(
+        res_name=res_name, 
+        image_name=image_name,
+        build_config=build_config,
+        env_file_rel_path=env_file_rel_path,
+        traefik_labels=traefik_labels,
+        port=port,
+        network_traefik_public=PlatformDockerConstants.NETWORK_TRAEFIK_PUBLIC,
+        network_backend=PlatformDockerConstants.NETWORK_BACKEND,
+        healthcheck_timing=compose_healthcheck_timing(DOCKER_HEALTHCHECK["frontend_start_period_seconds"]),
+    )
+
+
+def _generate_single_backend_entry(resource_path, resource_name, res, manifest, instance_id=None):
+    """
+    Generate a single backend docker-compose entry.
+    """
+    res_name = res['name']
+    stack = manifest.get('stack', resource_name) if manifest else resource_name
+    
+    # Get full service path from resource (for cross-root service support)
+    full_resource_path = res.get('_resource_path', resource_path + '/' + res_name)
+    
+    # Calculate correct relative path to env_file from compose file location
+    env_file_rel_path = _compute_env_file_rel_path(resource_path, full_resource_path, '.env.backend.autogenerated')
+    
+    internal_port = manifest.get('port', BASE_PORT_BACKEND) if manifest else BASE_PORT_BACKEND
+    dev_port = internal_port
+    # Use PROJECT_NAME from PlatformDockerConstants for portable database naming
+    _db_prefix = PlatformDockerConstants.PROJECT_NAME + "_"
+    db_name = manifest.get('databaseName', _db_prefix + stack) if manifest else _db_prefix + stack
+    
+    # Compute database URLs using centralized constants
+    db_url_for_tilt = PlatformDockerConstants.get_database_url_for_env(db_name)
+    db_url_with_fallback = PlatformDockerConstants.get_compose_env_database_url(db_name)
+    
+    health_path = manifest.get('healthCheckPath', HEALTH_CHECK_PATH) if manifest else HEALTH_CHECK_PATH
+    # A bring-your-own service without healthCheckPath may not serve HTTP. None means no HTTP probe: no Traefik health check labels.
+    if manifest and manifest.get('appType') == 'bring-your-own' and not manifest.get('healthCheckPath'):
+        health_path = None
+    
+    traefik_cfg = manifest.get('traefik', {}) if manifest else {}
+    traefik_host = traefik_cfg.get('host', stack + '.backend.' + _PROJECT_NAME + '.local')
+    # ALPHA: Use proper API v1 path with -management suffix via api_path_constants
+    # Old default: '/api/' + stack
+    # New default: get_api_path_for_domain → /api/v1/{stack}-management
+    traefik_path = traefik_cfg.get('pathPrefix', get_api_path_for_domain(stack, manifest))
+    
+    nats_cfg = manifest.get('nats', {}) if manifest else {}
+    nats_queue = nats_cfg.get('queueGroup', stack + '_backend_svc')
+    nats_url = PlatformDockerConstants.NATS_URL
+    
+    # Auth configuration: one shared builder keeps this identical to the generated env file (see AuthConfig.from_manifest).
+    auth_config = AuthConfig.from_manifest(manifest)
+    
+    auth_env = AuthConfig.generate_docker_compose_auth_env(auth_config)
+    # secrets.required / secrets.optional, read from the project .env by Compose (empty with TDK_SECRET_PROVIDER=infisical)
+    secrets_env = get_secret_environment_lines(manifest, res_name)
+    
+    # Use .autogenerated/Dockerfile.app.autogenerated by default for build config (primary only)
+    if manifest and manifest.get('appType') == 'bring-your-own':
+        if manifest.get('image'):
+            build_config = ""
+        else:
+            # A BYO Dockerfile copies paths relative to the service directory
+            # (for example, `COPY app.py .`). Build with that directory as the
+            # context instead of the project root used by generated Flisk apps.
+            context_prefix = '/'.join(['..'] * (len(resource_path.split('/')) + 1))
+            build_context = context_prefix + '/' + full_resource_path
+            # `buildContext` (relative to the service directory) moves the context
+            # to the source tree an imported Dockerfile lives in; `dockerfile` is then
+            # relative to that context, as in Compose.
+            custom_context = manifest.get('buildContext')
+            if custom_context and custom_context != '.':
+                build_context = build_context + '/' + custom_context
+            dockerfile = manifest.get('dockerfile', 'Dockerfile')
+            if dockerfile.startswith('./'):
+                dockerfile = dockerfile[2:]
+            build_config = """    build:
+      context: {build_context}
+      dockerfile: {dockerfile}""".format(
+                build_context=build_context,
+                dockerfile=dockerfile,
+            )
+    else:
+        build_config = compose_build_config(resource_path, res_name)
+    
+    # REMOVED: External port exposure - all services accessed via Traefik only
+    # Services are available at {project}.localhost/api/v1/{service}
+    # Inside the Docker network a service listens on its own port (manifest.port, passed to it as PORT), for service-to-service calls
+    ports_section = ""  # No external ports - Traefik-only access
+    
+    # Determine service name based on instance
+    if instance_id:
+        # Replica instance: add instance suffix
+        resource_entry_name = res_name + '-' + str(instance_id)
+        instance_label = str(instance_id)
+        # Replicas should reuse the already-built image; avoid per-replica builds
+        build_config = ""
+    else:
+        # Primary instance
+        resource_entry_name = res_name
+        instance_label = '0'
+    
+    # All instances share the same Traefik service for load balancing
+    traefik_resource_name = res_name  # LB service name (shared)
+    
+    # Workers have no HTTP server: they consume from NATS and exit-on-crash. Giving
+    # them a Traefik route advertises an endpoint that can never answer, and giving
+    # them an HTTP healthcheck marks a perfectly healthy worker as unhealthy forever.
+    is_worker = manifest.get('appType') == 'worker' if manifest else False
+    is_byo = manifest.get('appType') == 'bring-your-own' if manifest else False
+    is_proxy_disabled_byo = (
+        is_byo and not manifest.get('exposeViaProxy', True)
+    ) if manifest else False
+
+    # One-shot jobs (migrations, seeders) must not be restarted after they exit 0, so a
+    # bring-your-own resource can choose its Compose restart policy. Default is unchanged.
+    restart_policy = 'unless-stopped'
+    if is_byo and manifest.get('restart') in ['no', 'on-failure', 'unless-stopped', 'always']:
+        restart_policy = manifest.get('restart')
+    restart_policy = '"no"' if restart_policy == 'no' else restart_policy
+
+    # No HTTP server means no HTTP probe. Disable explicitly: the image HEALTHCHECK would otherwise probe a port nothing listens on.
+    no_http_healthcheck_section = NO_HTTP_HEALTHCHECK if (is_worker or health_path == None) else ""
+    # Backends with a health path get it in the env, so the shared golden image's HEALTHCHECK can probe it.
+    health_env = "      - TDK_HEALTH_PATH={}\n".format(health_path) if health_path else ""
+    # An agent with files durability keeps its session checkpoints in a named volume. The volume is declared at the top of the
+    # generated file (generate_app_compose_from_entries reads the marker line below), so flisk down keeps it.
+    agent_env = ""
+    agent_volume_section = ""
+    if manifest and type(manifest.get('agent')) == 'dict':
+        agent_durability = manifest['agent'].get('durability', 'files')
+        agent_env = "      - AGENT_DURABILITY={}\n".format(agent_durability)
+        if agent_durability == 'files':
+            agent_volume = res_name + '-agent-state'
+            agent_env += "      - AGENT_STATE_DIR=/var/lib/tdk-agent\n"
+            agent_volume_section = "    # tdk-agent-volume: {vol}\n    volumes:\n      - {vol}:/var/lib/tdk-agent\n".format(vol=agent_volume)
+
+    if is_worker or is_proxy_disabled_byo:
+        traefik_labels = '      - "traefik.enable=false"'
+        healthcheck_section = no_http_healthcheck_section
+    else:
+        # Traefik's load-balancer check can be overridden separately in service.json
+        # (`traefik.healthCheck`); it defaults to the container check's path.
+        traefik_health_path = traefik_cfg.get('healthCheck') or health_path
+        traefik_labels = get_backend_traefik_labels(
+            resource_entry_name=resource_entry_name,
+            traefik_host=traefik_host,
+            traefik_path=traefik_path,
+            traefik_resource_name=traefik_resource_name,
+            internal_port=internal_port,
+            health_path=traefik_health_path,
+            manifest=manifest,
+        )
+        # BYO images may not contain curl. Traefik uses its own HTTP health
+        # check labels above, so don't mark an otherwise healthy container
+        # unhealthy because the image lacks a command Flisk cannot require.
+        healthcheck_section = no_http_healthcheck_section if no_http_healthcheck_section else "" if is_byo else """    healthcheck:
+      test: ["CMD", "curl", "-f", "--max-time", "5", "http://localhost:{internal_port}{health_path}"]
+""".format(internal_port=internal_port, health_path=health_path) + compose_healthcheck_timing()
+    infisical_env = get_infisical_environment_vars(as_array=True, resource_name=res_name)
+    
+    # Build auth environment variables section using centralized auth utilities
+    
+    return """
+  {resource_entry_name}:
+    image: {image_name}
+    init: true
+    restart: {restart_policy}
+{build_config}
+{ports_section}
+    env_file:
+      - {env_file_rel_path}
+    environment:
+{infisical_env}
+      - RESOURCE_NAME={stack}
+      - PORT={port_anchor}
+{health_env}{agent_env}      - INSTANCE_ID={instance_label}
+      - NATS_QUEUE_GROUP={nats_queue}
+      - TILT_DATABASE_URL={db_url_for_tilt}
+      - TILT_NATS_URL={nats_url}
+      - NODE_ENV=development
+      - DATABASE_URL={db_url_for_tilt}
+      # Per-project escape hatch: set AUTO_MIGRATE=false in the project root .env
+      # to skip Prisma auto-migration at container boot (e.g. while diagnosing a
+      # migration/CLI issue) without touching the generator or any service code.
+      - AUTO_MIGRATE=${{AUTO_MIGRATE:-true}}
+{auth_env}{secrets_env}
+{agent_volume_section}    labels:
+{traefik_labels}
+    networks:
+      - {network_traefik_public}
+      - {network_backend}
+      - {network_database}
+      - {network_infisical}
+{healthcheck_section}    # Note: depends_on removed - Tilt manages service startup order
+    deploy:
+      resources:
+        limits:
+          cpus: '0.5'
+          memory: 512M
+        reservations:
+          cpus: '0.2'
+          memory: 256M
+""".format(
+        resource_entry_name=resource_entry_name,
+        res_name=res_name,
+        resource_name=resource_name,
+        image_name=(
+            manifest.get('image')
+            if manifest and manifest.get('appType') == 'bring-your-own' and manifest.get('image')
+            else PlatformDockerConstants.app_image_name(resource_name, res_name)
+        ),
+        build_config=build_config,
+        ports_section=ports_section,
+        env_file_rel_path=env_file_rel_path,
+        stack=stack,
+        internal_port=internal_port,
+        port_anchor=internal_port,
+        restart_policy=restart_policy,
+        dev_port=dev_port,
+        db_name=db_name,
+        db_url_for_tilt=db_url_for_tilt,
+        db_url_with_fallback=db_url_with_fallback,
+        instance_label=instance_label,
+        health_path=health_path,
+        traefik_host=traefik_host,
+        traefik_path=traefik_path,
+        traefik_resource_name=traefik_resource_name,
+        nats_queue=nats_queue,
+        nats_url=nats_url,
+        traefik_labels=traefik_labels,
+        healthcheck_section=healthcheck_section,
+        health_env=health_env,
+        agent_env=agent_env,
+        agent_volume_section=agent_volume_section,
+        infisical_env=infisical_env,
+        auth_env=auth_env,
+        secrets_env=secrets_env,
+        network_traefik_public=PlatformDockerConstants.NETWORK_TRAEFIK_PUBLIC,
+        network_backend=PlatformDockerConstants.NETWORK_BACKEND,
+        network_database=PlatformDockerConstants.NETWORK_DATABASE,
+        network_infisical=PlatformDockerConstants.NETWORK_INFISICAL,
+    )
+
+
+def generate_backend_compose_entry(resource_path, resource_name, res, manifest=None):
+    """
+    Generate backend docker-compose entries with TRUE multi-replica support.
+    """
+    replicas = manifest.get('replicas', 1) if manifest else 1
+    
+    if replicas <= 1:
+        # Single instance - simple case
+        return _generate_single_backend_entry(resource_path, resource_name, res, manifest, instance_id=None)
+    
+    # Multi-replica: generate separate service entries
+    entries = []
+    
+    # Primary instance (gets the port mapping)
+    entries.append(_generate_single_backend_entry(resource_path, resource_name, res, manifest, instance_id=None))
+    
+    # Additional replicas (numbered, expose only)
+    for i in range(1, replicas):
+        entries.append(_generate_single_backend_entry(resource_path, resource_name, res, manifest, instance_id=i))
+    
+    return ''.join(entries)
+
+
+def _generate_port_anchors(resource_entries):
+    """Extract unique ports and generate YAML anchors for them."""
+    backend_port = None
+    frontend_port = None
+    sdk_port = None
+    has_backend = False
+    has_sdk = False
+    has_frontend = False
+
+    for entry in resource_entries:
+        # Check if this is an SDK (ends with -sdk)
+        if "-sdk:" in entry or entry.strip().startswith("identity-sdk:"):
+            has_sdk = True
+            # Extract SDK port from entry
+            if "loadbalancer.server.port=" in entry:
+                for line in entry.split("\n"):
+                    if "loadbalancer.server.port=" in line:
+                        # Safe parsing without try/except
+                        port_str = line.split("loadbalancer.server.port=")[-1].split('"')[0]
+                        if port_str.isdigit():
+                            sdk_port = int(port_str)
+                            break
+        # Check if this is a frontend (has frontend-memory-limit but not SDK)
+        elif "<<: *frontend-memory-limit" in entry and not ("-sdk:" in entry or entry.strip().startswith("identity-sdk:")):
+            has_frontend = True
+            # Extract frontend port from entry
+            if "loadbalancer.server.port=" in entry:
+                for line in entry.split("\n"):
+                    if "loadbalancer.server.port=" in line:
+                        # Safe parsing without try/except
+                        port_str = line.split("loadbalancer.server.port=")[-1].split('"')[0]
+                        if port_str.isdigit():
+                            frontend_port = int(port_str)
+                            break
+        # Check if this is a backend (has a port, not frontend, not SDK)
+        # Backend entries have "healthcheck:" section with backend port
+        elif "healthcheck:" in entry and "<<: *frontend-memory-limit" not in entry and not ("-sdk:" in entry or entry.strip().startswith("identity-sdk:")):
+            has_backend = True
+            # Extract backend port from entry
+            if "loadbalancer.server.port=" in entry:
+                for line in entry.split("\n"):
+                    if "loadbalancer.server.port=" in line:
+                        # Safe parsing without try/except
+                        port_str = line.split("loadbalancer.server.port=")[-1].split('"')[0]
+                        if port_str.isdigit():
+                            backend_port = int(port_str)
+                            break
+
+    # Build anchors - use extracted port or fall back to default
+    anchors = []
+    anchors.append("x-backend-port: &backend-port {}".format(backend_port if backend_port else BASE_PORT_BACKEND))
+    if has_frontend and frontend_port:
+        anchors.append("x-frontend-port: &frontend-port {}".format(frontend_port))
+    if has_sdk and sdk_port:
+        anchors.append("x-sdk-port: &sdk-port {}".format(sdk_port))
+
+    return "\n".join(anchors)
+
+
+def generate_app_compose_from_entries(resource_path, resource_entries, write_fn=None):
+    """Generate docker-compose.app.autogenerated.yml from service entries with port anchors.
+
+    Args:
+        resource_path: Path to the resource directory
+        resource_entries: List of docker-compose entries for services
+        write_fn: Optional write function for file output
+
+    Returns:
+        str: Generated docker-compose YAML content
+    """
+
+    # Generate port anchors
+    port_anchors = _generate_port_anchors(resource_entries)
+
+    header = """###############################################################################
+# 🛑 CRITICAL: SYSTEM-GENERATED FILE - DO NOT MODIFY DIRECTLY
+#
+# ANY MANUAL CHANGES MADE TO THIS FILE WILL BE WIPED ON THE NEXT 'tilt up'.
+# Generation Source: .tilt/topologies/platform/docker/index.star
+###############################################################################
+
+# =============================================================================
+# PORT DEFINITIONS - Change these to change ports everywhere
+# =============================================================================
+{port_anchors}
+
+# =============================================================================
+# MEMORY LIMITS
+# =============================================================================
+x-nix-any-m1-arm64-memory-limit: &nix-any-m1-arm64-memory-limit
+  deploy:
+    resources:
+      limits:
+        memory: 192M
+      reservations:
+        memory: 64M
+
+x-frontend-memory-limit: &frontend-memory-limit
+  deploy:
+    resources:
+      limits:
+        memory: 64M
+        cpus: '0.15'
+      reservations:
+        memory: 32M
+
+services:
+""".format(port_anchors=port_anchors)
+
+    # Named volumes used by services (agent session state) must be declared at the top level. Services mark them with a
+    # "# tdk-agent-volume: <name>" line, so the declaration follows the services without a separate registry.
+    volume_names = []
+    for entry in resource_entries:
+        for line in entry.split("\n"):
+            if line.strip().startswith("# tdk-agent-volume: "):
+                name = line.strip()[len("# tdk-agent-volume: "):]
+                # Replicas of one agent repeat the marker; Compose rejects a duplicate key under volumes:.
+                if name not in volume_names:
+                    volume_names.append(name)
+    volumes_section = ""
+    if volume_names:
+        volumes_section = "\nvolumes:\n" + "".join(["  {}:\n".format(name) for name in volume_names])
+
+    footer = """
+networks:
+  {network_traefik_public}:
+    external: true
+  {network_backend}:
+    external: true
+  {network_database}:
+    external: true
+  {network_infisical}:
+    external: true
+{volumes_section}""".format(
+        network_traefik_public=PlatformDockerConstants.NETWORK_TRAEFIK_PUBLIC,
+        network_backend=PlatformDockerConstants.NETWORK_BACKEND,
+        network_database=PlatformDockerConstants.NETWORK_DATABASE,
+        network_infisical=PlatformDockerConstants.NETWORK_INFISICAL,
+        volumes_section=volumes_section,
+    )
+
+    content = header + "\n".join(resource_entries) + footer
+
+    if write_fn:
+        compose_path = resource_path + '/' + OUTPUT.AUTOGENERATED_FOLDER + '/docker-compose.app.autogenerated.yml'
+        write_fn(compose_path, content)
+
+    return content
+
+
+def generate_migrator_compose(resource_path, resource_name, dockerfile_path=None, write_fn=None):
+    """Generate docker-compose for database migrators.
+
+    Args:
+        resource_path: Path to the resource directory
+        resource_name: Name of the resource
+        dockerfile_path: Optional path to Dockerfile
+        write_fn: Optional write function for file output
+
+    Returns:
+        str: Generated docker-compose YAML content
+    """
+    migrator_name = resource_name + '-db-migrator'
+    image_name = PlatformDockerConstants.migrator_image_name(resource_name)
+    
+    # Use PROJECT_NAME from PlatformDockerConstants for portable database naming
+    db_name = PlatformDockerConstants.PROJECT_NAME + '_' + resource_name
+    default_db_url = PlatformDockerConstants.get_database_url_for_env(db_name)
+
+    dockerfile_ref = dockerfile_path if dockerfile_path else resource_path + "/" + OUTPUT.AUTOGENERATED_FOLDER + "/Dockerfile.migrator.autogenerated"
+    infisical_env = get_infisical_environment_vars(as_array=False)
+    
+    content = """###############################################################################
+# 🛑 CRITICAL: SYSTEM-GENERATED FILE - DO NOT MODIFY DIRECTLY
+# Generation Source: .tilt/topologies/platform/docker/index.star
+###############################################################################
+# 🔐 Infisical Zero-Code Integration Enabled
+# 🗃️ Database Virtualization: Connects to shared PostgreSQL instance
+services:
+  {migrator_name}:
+    image: {image_name}
+    build:
+      context: ../../../.
+      dockerfile: {dockerfile_ref}
+      target: migrator
+    environment:
+{infisical_env}
+      RESOURCE_NAME: {resource_name}
+      TILT_DATABASE_URL: "{default_db_url}"
+      DATABASE_URL: ${{DATABASE_URL:-{default_db_url}}}
+    networks:
+      - {network_database}
+      - {network_backend}
+      - {network_infisical}
+    restart: "no"
+
+networks:
+  {network_database}:
+    external: true
+  {network_backend}:
+    external: true
+  {network_infisical}:
+    external: true
+""".format(
+        migrator_name=migrator_name, 
+        image_name=image_name, 
+        resource_path=resource_path,
+        dockerfile_ref=dockerfile_ref,
+        resource_name=resource_name,
+        db_name=db_name,
+        default_db_url=default_db_url,
+        infisical_env=infisical_env,
+        network_database=PlatformDockerConstants.NETWORK_DATABASE,
+        network_backend=PlatformDockerConstants.NETWORK_BACKEND,
+        network_infisical=PlatformDockerConstants.NETWORK_INFISICAL,
+    )
+
+    if write_fn:
+        write_fn(resource_path + '/' + OUTPUT.AUTOGENERATED_FOLDER + '/docker-compose.migrator.autogenerated.yml', content)
+
+    return content