@tdk-landscape/tdk-cli-core 1.3.14 → 1.3.22

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

@@ -0,0 +1,636 @@
+# =============================================================================
+# 🐳 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
+HEALTH_CHECK_PATH = "/health"
+OUTPUT = struct(AUTOGENERATED_FOLDER = ".autogenerated")
+# === END INLINED CONSTANTS ===
+
+
+load("./compose_helpers.star", "with_runtime_image_tag", "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")
+load("../secrets/infisical.star", "get_infisical_environment_vars")
+load("../auth/auth.star", "AuthConfig")
+
+load("../constants.star", "PlatformDockerConstants")
+
+# 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 = with_runtime_image_tag(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'
+    # Read port from manifest (service.json), fallback to BASE_PORT_FRONTEND or 80 for nginx
+    port = manifest.get('port', 80 if use_nginx else BASE_PORT_FRONTEND)
+    
+    # Base path for routing on {project}.localhost
+    base_path = '/' + manifest.get('basePath', stack + 's').lstrip('/')
+    
+    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}
+{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}"]
+      interval: 10s
+      timeout: 5s
+      retries: 3
+      # STORY 4 FIX: 30s grace period to prevent 504 errors on startup
+      start_period: 30s
+""".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,
+    )
+
+
+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
+    
+    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 - use centralized auth utilities
+    # Extract auth config from manifest to decouple auth.star from manifest structure
+    # Auto-detect identity-service mode if 'identity' is in dependsOn
+    internal_deps = manifest.get('dependsOn', []) if manifest else []
+    has_identity_dep = 'identity' in internal_deps
+    
+    # If manifest has authMode, use it; otherwise auto-detect based on identity dependency
+    manifest_auth_mode = manifest.get('authMode') if manifest else None
+    if manifest_auth_mode:
+        auth_mode = manifest_auth_mode
+    elif has_identity_dep:
+        auth_mode = 'identity-service'
+    else:
+        auth_mode = None
+    
+    auth_config = {
+        'authMode': auth_mode,
+        'jwtSecret': manifest.get('jwtSecret') if manifest else None,
+        'identityServiceUrl': manifest.get('envVars', {}).get('IDENTITY_RESOURCE_URL') if manifest else None,
+    }
+    
+    # If we auto-detected identity-service mode but no URL is set, use default
+    if auth_mode == 'identity-service' and not auth_config['identityServiceUrl']:
+        auth_config['identityServiceUrl'] = AuthConfig.get_identity_resource_url(None)
+    
+    auth_env = AuthConfig.generate_docker_compose_auth_env(auth_config)
+    
+    # Use .autogenerated/Dockerfile.app.autogenerated by default for build config (primary only)
+    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}
+    # Internal port 3000 is accessible within Docker network for service-to-service communication
+    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)
+    
+    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=health_path,
+        manifest=manifest,
+    )
+    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}
+    restart: unless-stopped
+{build_config}
+{ports_section}
+    env_file:
+      - {env_file_rel_path}
+    environment:
+{infisical_env}
+      - RESOURCE_NAME={stack}
+      - PORT={port_anchor}
+      - 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}
+{auth_env}
+    labels:
+{traefik_labels}
+    networks:
+      - {network_traefik_public}
+      - {network_backend}
+      - {network_database}
+      - {network_infisical}
+    healthcheck:
+      test: ["CMD", "curl", "-f", "--max-time", "5", "http://localhost:{internal_port}{health_path}"]
+      interval: 10s
+      timeout: 5s
+      retries: 6
+      # STORY 4 FIX: 30s grace period to prevent 504 errors during startup
+      # Services get 30s to initialize before health checks begin
+      start_period: 30s
+    # 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=with_runtime_image_tag(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,
+        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,
+        infisical_env=infisical_env,
+        auth_env=auth_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 _detect_sdk_in_entries(resource_entries):
+    """Check if any entry is an SDK."""
+    for entry in resource_entries:
+        if "-sdk:" in entry or entry.strip().startswith("identity-sdk:"):
+            return True
+    return False
+
+def _detect_frontend_in_entries(resource_entries):
+    """Check if any entry is a frontend."""
+    for entry in resource_entries:
+        if "<<: *frontend-memory-limit" in entry:
+            return True
+    return False
+
+def _detect_backend_in_entries(resource_entries):
+    """Check if any entry is a backend."""
+    for entry in resource_entries:
+        if _is_backend_entry(entry):
+            return True
+    return False
+
+def _is_sdk_entry(entry):
+    """Check if a specific entry is an SDK."""
+    return "-sdk:" in entry or entry.strip().startswith("identity-sdk:")
+
+def _is_backend_entry(entry):
+    """Check if a specific entry is a backend (not frontend, not SDK)."""
+    if "-sdk:" in entry or entry.strip().startswith("identity-sdk:"):
+        return False
+    if "<<: *frontend-memory-limit" in entry:
+        return False
+    # Backend entries have healthcheck with backend port pattern
+    if "healthcheck:" in entry and "curl" in entry:
+        return True
+    return False
+
+def _replace_ports_with_anchors(entry, has_sdk=False, has_frontend=False, has_backend=False):
+    """Replace hardcoded ports with YAML anchors in an entry."""
+    is_sdk = _is_sdk_entry(entry)
+    is_backend = _is_backend_entry(entry)
+    lines = entry.split("\n")
+    result = []
+
+    for line in lines:
+        new_line = line
+        # NOTE: We do NOT replace PORT=3000 with an anchor because YAML anchors
+        # in environment variable values are treated as literal strings, not resolved.
+        # The actual port value is already correctly set by _generate_single_backend_entry
+        # using the internal_port variable. Keep PORT=3000 as-is.
+
+        # YAML anchors do not resolve inside quoted Docker labels. Traefik must
+        # see a numeric loadbalancer.port (e.g. 4000), not `*backend-port`.
+        # NOTE: We do NOT replace healthcheck URLs with YAML anchors because anchors
+        # don't work inside quoted strings. The wget healthcheck URLs must use actual
+        # port numbers (e.g., http://127.0.0.1:3000), not anchor references.
+        # The correct port is already set by generate_frontend_compose.
+        # NOTE: We do NOT replace healthcheck URLs with anchors because YAML anchors
+        # don't work inside quoted strings. The healthcheck URL must use the actual
+        # port number (e.g., http://localhost:3000/health), not an anchor reference.
+        # The _generate_single_backend_entry function already uses the correct port
+        # via the internal_port variable in the healthcheck URL.
+
+        result.append(new_line)
+
+    return "\n".join(result)
+
+def _process_entries_with_anchors(resource_entries, has_sdk, has_frontend, has_backend):
+    """Replace ports with anchors in all entries."""
+    result = []
+    for entry in resource_entries:
+        result.append(_replace_ports_with_anchors(entry, has_sdk, has_frontend, has_backend))
+    return result
+
+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
+    """
+
+    # Detect service types
+    has_sdk = _detect_sdk_in_entries(resource_entries)
+    has_frontend = _detect_frontend_in_entries(resource_entries)
+    has_backend = _detect_backend_in_entries(resource_entries)
+
+    # Replace ports with anchors in entries
+    processed_entries = _process_entries_with_anchors(resource_entries, has_sdk, has_frontend, has_backend)
+
+    # 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)
+
+    footer = """
+networks:
+  {network_traefik_public}:
+    external: true
+  {network_backend}:
+    external: true
+  {network_database}:
+    external: true
+  {network_infisical}:
+    external: true
+""".format(
+        network_traefik_public=PlatformDockerConstants.NETWORK_TRAEFIK_PUBLIC,
+        network_backend=PlatformDockerConstants.NETWORK_BACKEND,
+        network_database=PlatformDockerConstants.NETWORK_DATABASE,
+        network_infisical=PlatformDockerConstants.NETWORK_INFISICAL,
+    )
+
+    content = header + "\n".join(processed_entries) + footer
+
+    if write_fn:
+        compose_path = resource_path + '/' + OUTPUT.AUTOGENERATED_FOLDER + '/docker-compose.app.autogenerated.yml'
+        print("DEBUG COMPOSE GEN: Writing {} bytes to {}".format(len(content), compose_path))
+        write_fn(compose_path, content)
+        print("DEBUG COMPOSE GEN: Write completed")
+    else:
+        print("DEBUG COMPOSE GEN: No write_fn provided!")
+
+    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 = with_runtime_image_tag(resource_name + '-db-migrator')
+    
+    # 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

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

@@ -0,0 +1,52 @@
+# =============================================================================
+# 🐳 TILT SDK - COMPOSE HELPERS
+# =============================================================================
+
+
+
+# === INLINED CONSTANTS for pure extension loading ===
+OUTPUT = struct(AUTOGENERATED_FOLDER = ".autogenerated")
+# === END INLINED CONSTANTS ===
+
+
+def with_runtime_image_tag(image_name):
+    """Apply stable local image tag (:dev)."""
+    tag = 'dev'
+
+    last_segment = image_name.split('/')[-1]
+    if ':' in last_segment:
+        return image_name[:image_name.rfind(':')] + ':' + tag
+
+    return image_name + ':' + tag
+
+def compose_build_config(resource_path, res_name, dockerfile=OUTPUT.AUTOGENERATED_FOLDER + '/Dockerfile.app.autogenerated', target=None):
+    """Generate build config for docker-compose."""
+    # Check if dockerfile is already a full path (contains resource_path)
+    if dockerfile.startswith(resource_path + '/'):
+        # dockerfile is already a full path, use it directly
+        full_dockerfile_path = dockerfile
+    elif res_name:
+        # Nested structure: construct path as resource_path/res_name/dockerfile
+        full_dockerfile_path = "{resource_path}/{res_name}/{dockerfile}".format(
+            resource_path=resource_path,
+            res_name=res_name,
+            dockerfile=dockerfile
+        )
+    else:
+        # Flat structure: construct path as resource_path/dockerfile
+        full_dockerfile_path = "{resource_path}/{dockerfile}".format(
+            resource_path=resource_path,
+            dockerfile=dockerfile
+        )
+    
+    base_config = """    build:
+      context: ../../../../.
+      dockerfile: {full_dockerfile_path}""".format(
+        full_dockerfile_path=full_dockerfile_path
+    )
+    
+    if target:
+        base_config += """
+      target: {target}""".format(target=target)
+    
+    return base_config