@flisk-sh/flisk 0.0.0-stage → 1.3.190

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

@@ -0,0 +1,148 @@
+#!/usr/bin/env starlark
+# Copyright (c) 2026 Flisk Landscape contributors
+# SPDX-License-Identifier: MIT
+# =============================================================================
+# 🐳 TILT SDK - TRAEFIK CONSTANTS
+# =============================================================================
+# STORY 4 FIX: API Gateway 504 Error Prevention
+# - Startup grace period: 30s (allows services to fully initialize)
+# - Extended timeouts for cold-start services
+# - Proper health check sequencing
+# =============================================================================
+
+# === INLINED CONSTANTS for pure extension loading ===
+TRAEFIK_CONFIG = {
+    "entrypoint": "web",
+    "web_entrypoint": "web",
+    "network": "traefik-public",
+    "default_host": "localhost",
+    "default_port": 8080,
+    "tls_enabled": False,
+    "entrypoints": ["web"],
+    "middlewares": [],
+    "tls": {"enabled": False},
+    "healthcheck_path": "/health",
+    "healthcheck_interval": "10s",
+    "healthcheck_timeout": "5s",
+    "frontend_priority_base": 100,
+    "websecure_entrypoint": "websecure",
+    "enable_strip_prefix": True,
+    "localhost_suffix": ".localhost",
+    "healthcheck_retries": 3,
+    "resource_startup_delay": "30s",
+    "startup_grace_period": "30s",
+    "response_timeout": "30s",
+    "connection_timeout": "10s",
+    "retry_attempts": 3,
+    "circuit_breaker_threshold": 5,
+    "strip_prefix_middleware_suffix": "-strip-prefix",
+    "retry_initial_interval": "1s",
+    "retry_max_interval": "10s",
+    "rate_limit_requests": 100,
+    "rate_limit_period": "1m",
+    "buffer_request_body": True,
+    "forward_auth_url": "",
+    "api_base_path": "/api",
+    "api_version": "v1"
+}
+DEFAULTS = {}
+
+# === END INLINED CONSTANTS ===
+
+
+load("../constants.star", "PlatformDockerConstants")
+# =============================================================================
+# MASTER CONFIG IMPORTS - Use centralized configuration
+# =============================================================================
+
+
+# =============================================================================
+# API PATH CONSTANTS - Import for dynamic API path generation
+# =============================================================================
+load("./api_path_constants.star",
+     "get_api_path_for_domain",
+     "get_api_path_for_service",
+     "build_traefik_url",
+     "build_health_endpoint")
+
+TRAEFIK_ENABLE_LABEL = "traefik.enable=true"
+TRAEFIK_DOCKER_NETWORK = PlatformDockerConstants.NETWORK_TRAEFIK_PUBLIC
+
+# Entrypoints from master config
+TRAEFIK_WEBSECURE_ENTRYPOINT = TRAEFIK_CONFIG["websecure_entrypoint"]
+
+TRAEFIK_FRONTEND_ENABLE_HTTP = True
+TRAEFIK_FRONTEND_ENABLE_HTTPS = True
+TRAEFIK_BACKEND_ENABLE_HTTP = True
+TRAEFIK_BACKEND_ENABLE_HTTPS = False
+
+# Middleware settings from master config
+TRAEFIK_ENABLE_STRIP_PREFIX_MIDDLEWARE = TRAEFIK_CONFIG["enable_strip_prefix"]
+TRAEFIK_ENABLE_FRONTEND_HOST_RULE = True
+TRAEFIK_ENABLE_FRONTEND_PATH_RULE = True
+TRAEFIK_ENABLE_BACKEND_HOST_RULE = True
+TRAEFIK_ENABLE_BACKEND_PATH_RULE = True
+
+TRAEFIK_PROJECT_HOST = PlatformDockerConstants.LOCAL_DOMAIN
+TRAEFIK_PROJECT_APP_HOST = PlatformDockerConstants.APP_LOCAL_DOMAIN
+TRAEFIK_PROJECT_API_HOST = PlatformDockerConstants.API_LOCAL_DOMAIN
+TRAEFIK_FRONTEND_LOCALHOST_SUFFIX = TRAEFIK_CONFIG["localhost_suffix"]
+
+# Priority from master config
+TRAEFIK_FRONTEND_PRIORITY_BASE = TRAEFIK_CONFIG["frontend_priority_base"]
+
+# =============================================================================
+# STORY 4 FIX: Health check configuration with 30-second grace period
+# =============================================================================
+# From TILT_RESOURCE_DEFAULTS.star - centralized configuration
+# Health check configuration - optimized to prevent 504s on startup
+TRAEFIK_HEALTHCHECK_RETRIES = TRAEFIK_CONFIG["healthcheck_retries"]
+
+# STORY 4 FIX: 30-second grace period (matches issue requirement)
+TRAEFIK_RESOURCE_STARTUP_DELAY = TRAEFIK_CONFIG["resource_startup_delay"]
+TRAEFIK_HEALTHY_THRESHOLD = TRAEFIK_CONFIG["retry_attempts"]
+TRAEFIK_MIDDLEWARE_SUFFIX = TRAEFIK_CONFIG["strip_prefix_middleware_suffix"]
+
+# =============================================================================
+# API ROUTING PATHS - Dynamic from Manifests
+# =============================================================================
+# API paths are generated dynamically from manifest domain and appName fields
+# No hardcoded service names - all from service.json
+# =============================================================================
+
+# Planner service paths are generated dynamically from manifests
+# Use get_api_path_for_domain() function instead of hardcoded constants
+
+# API paths are now generated dynamically - no hardcoded constants
+# Use get_api_path_for_domain() function instead
+
+# =============================================================================
+# API ROUTING PATTERN
+# =============================================================================
+# Standard API path pattern generated from manifest: /api/v1/{appName}
+# Domain comes from service manifest, allowing dynamic service discovery
+# No hardcoded examples - all paths from service.json
+# =============================================================================
+# TRAEFIK_API_VERSION and TRAEFIK_API_BASE_PATH now imported from master config
+
+# =============================================================================
+# STORY 4 FIX: Retry middleware configuration for transient failures
+# =============================================================================
+TRAEFIK_RETRY_ATTEMPTS = TRAEFIK_CONFIG["retry_attempts"]
+TRAEFIK_RETRY_INITIAL_INTERVAL = TRAEFIK_CONFIG["retry_initial_interval"]
+
+# =============================================================================
+# MASTER CONFIG RE-EXPORTS
+# =============================================================================
+# Re-export all values imported from master config so other files can load them
+# from this module. This maintains backward compatibility.
+
+# Define traefik constants from master config (available for other files to load)
+TRAEFIK_WEB_ENTRYPOINT = TRAEFIK_CONFIG["web_entrypoint"]
+TRAEFIK_WEBSECURE_ENTRYPOINT = TRAEFIK_CONFIG["websecure_entrypoint"]
+TRAEFIK_HEALTHCHECK_INTERVAL = TRAEFIK_CONFIG["healthcheck_interval"]
+TRAEFIK_HEALTHCHECK_TIMEOUT = TRAEFIK_CONFIG["healthcheck_timeout"]
+TRAEFIK_HEALTHCHECK_RETRIES = TRAEFIK_CONFIG["healthcheck_retries"]
+TRAEFIK_STARTUP_GRACE_PERIOD = TRAEFIK_CONFIG["startup_grace_period"]
+TRAEFIK_API_BASE_PATH = TRAEFIK_CONFIG["api_base_path"]
+TRAEFIK_API_VERSION = TRAEFIK_CONFIG["api_version"]

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

@@ -0,0 +1,162 @@
+# Copyright (c) 2026 Flisk Landscape contributors
+# SPDX-License-Identifier: MIT
+# =============================================================================
+# 🐳 TILT SDK - TRAEFIK HELPERS
+# =============================================================================
+
+# === INLINED CONSTANTS for pure extension loading ===
+TRAEFIK_API_BASE_PATH = "/api"
+# === END INLINED CONSTANTS ===
+
+
+load(
+    "./traefik_constants.star",
+    "TRAEFIK_PROJECT_HOST",
+    "TRAEFIK_PROJECT_APP_HOST",
+    "TRAEFIK_PROJECT_API_HOST",
+    "TRAEFIK_ENABLE_BACKEND_PATH_RULE",
+    "TRAEFIK_ENABLE_BACKEND_HOST_RULE",
+    "TRAEFIK_ENABLE_FRONTEND_HOST_RULE",
+    "TRAEFIK_ENABLE_FRONTEND_PATH_RULE",
+    "TRAEFIK_FRONTEND_LOCALHOST_SUFFIX",
+    "TRAEFIK_WEB_ENTRYPOINT",
+    "TRAEFIK_WEBSECURE_ENTRYPOINT",
+    "TRAEFIK_API_VERSION",
+)
+
+
+
+def build_entrypoints(enable_http, enable_https):
+    entrypoints = []
+    if enable_http:
+        entrypoints.append(TRAEFIK_WEB_ENTRYPOINT)
+    if enable_https:
+        entrypoints.append(TRAEFIK_WEBSECURE_ENTRYPOINT)
+    if len(entrypoints) == 0:
+        entrypoints.append(TRAEFIK_WEB_ENTRYPOINT)
+    return ",".join(entrypoints)
+
+
+def frontend_rule(res_name, base_path, traefik_host):
+    parts = []
+    if TRAEFIK_ENABLE_FRONTEND_HOST_RULE:
+        parts.append(
+            "Host(`{res_name}{suffix}`)".format(
+                res_name=res_name,
+                suffix=TRAEFIK_FRONTEND_LOCALHOST_SUFFIX,
+            ),
+        )
+    if traefik_host:
+        parts.append("Host(`{traefik_host}`)".format(traefik_host=traefik_host))
+    if TRAEFIK_ENABLE_FRONTEND_PATH_RULE:
+        parts.append(
+            "(Host(`{host}`) && PathPrefix(`{base_path}`))".format(
+                host=TRAEFIK_PROJECT_APP_HOST,
+                base_path=base_path,
+            ),
+        )
+        # Also accept localhost for local testing
+        parts.append(
+            "(Host(`localhost`) && PathPrefix(`{base_path}`))".format(
+                base_path=base_path,
+            ),
+        )
+    return " || ".join(parts)
+
+
+def backend_rule(traefik_host, traefik_path):
+    parts = []
+    if TRAEFIK_ENABLE_BACKEND_HOST_RULE and traefik_host:
+        parts.append("Host(`{host}`)".format(host=traefik_host))
+    if TRAEFIK_ENABLE_BACKEND_PATH_RULE and traefik_path:
+        parts.append("PathPrefix(`{path}`)".format(path=traefik_path))
+    return " || ".join(parts)
+
+
+def _pluralize_stack(stack):
+    """Convert stack to proper plural form.
+
+    Handles irregular plurals and special cases.
+
+    Args:
+        stack: Singular stack name (e.g., "user", "order", "product")
+
+    Returns:
+        str: Pluralized stack name (e.g., "users", "orders", "products")
+    """
+    # Already plural
+    if stack.endswith("s"):
+        return stack
+
+    # Irregular plurals that don't follow normal rules
+    irregulars = {
+        "identity": "identity",
+        "profile": "profile",  # profiles is wrong, profile is correct
+        "staff": "staff",
+        "inventory": "inventory",
+    }
+
+    if stack in irregulars:
+        return irregulars[stack]
+
+    # Words ending in 'y' preceded by a consonant -> 'ies'
+    if stack.endswith("y") and len(stack) > 1 and stack[-2] not in "aeiou":
+        return stack[:-1] + "ies"
+
+    # Words ending in ch, sh, ss, x, z, o -> 'es'
+    if stack.endswith(("ch", "sh", "ss", "x", "z", "o")):
+        return stack + "es"
+
+    return stack + "s"
+
+
+def get_api_path(stack, manifest=None):
+    """Generate API path from stack. Converts stack to proper resource name.
+
+    URL Restructuring: Changed from /api/v1/{stack} to /api/{resource-name}
+
+    Args:
+        stack: Resource stack from manifest (from service.json)
+
+    Returns:
+        str: API path like "/api/{stack}-management"
+    """
+    # NEW: Use {stack}-management pattern instead of pluralized stack
+    # This matches the resource naming convention ({stack}-management)
+    return "{base}/{stack}-management".format(
+        base=TRAEFIK_API_BASE_PATH,
+        stack=stack,
+    )
+
+
+def cli_api_path(resource_name, manifest=None):
+    """API path printed by `flisk up` and served on api.{project}.localhost.
+
+    Matches cli/src/commands/up.ts: `/api/{name}` with a trailing `-api` stripped.
+    """
+    if manifest and manifest.get("apiPath"):
+        return manifest.get("apiPath")
+    name = resource_name or (manifest.get("appName", "") if manifest else "")
+    if name.endswith("-api"):
+        name = name[:-4]
+    return TRAEFIK_API_BASE_PATH + "/" + name
+
+
+def project_backend_rule(manifest, resource_name=None):
+    """Generate routing rule for api.{project}.localhost from manifest.
+
+    Args:
+        manifest: Service manifest dictionary
+        resource_name: Runtime resource name (e.g. auth-api-backend)
+
+    Returns:
+        str: Traefik routing rule for project localhost domain
+    """
+    if not manifest and not resource_name:
+        return ""
+
+    api_path = cli_api_path(resource_name, manifest)
+    return "Host(`{host}`) && PathPrefix(`{path}`)".format(
+        host=TRAEFIK_PROJECT_API_HOST,
+        path=api_path,
+    )

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

@@ -0,0 +1,165 @@
+# Copyright (c) 2026 Flisk contributors
+# SPDX-License-Identifier: MIT
+# =============================================================================
+# 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. The route still strips the same `apiPath` prefix the real
+# Docker-label `-project` router strips (get_backend_traefik_labels) before
+# forwarding -- confirmed live against tdk-erp-system (task 7.2) that a
+# backend's app only serves its bare health path (e.g. `/health`), not the
+# full `/api/{name}/health` the public route is matched on; without this, the
+# gateway's own proxy-through would forward the unstripped path once healthy
+# and the app would 404 on it, even though the wake itself succeeded.
+
+load("./traefik_helpers.star", "project_backend_rule", "cli_api_path", "build_entrypoints")
+load("./traefik_constants.star",
+    "TRAEFIK_BACKEND_ENABLE_HTTP",
+    "TRAEFIK_BACKEND_ENABLE_HTTPS",
+)
+
+STATIC_ROUTE_PRIORITY = 1
+
+
+def normalize_abs_path(path):
+    """Absolute path with `.`/`..` segments collapsed, or "" for "".
+
+    Tilt's os.path.abspath does not collapse `..` (confirmed:
+    abspath("/a/.tdk/.tdk-out/../..") comes back unchanged), and the
+    generated Tiltfile's project root is exactly that shape
+    (config.main_dir + "/../.."). The gateway's project mount and the compose
+    paths in its route headers must match byte-for-byte, so both go through here.
+    """
+    if not path:
+        return ""
+    parts = []
+    for segment in os.path.abspath(path).split("/"):
+        if segment == "" or segment == ".":
+            continue
+        if segment == "..":
+            if parts:
+                parts.pop()
+            continue
+        parts.append(segment)
+    return "/" + "/".join(parts)
+
+
+def _container_name(compose_project_name, res_name):
+    """Docker Compose's own naming convention: <project>-<service>-<replica>.
+
+    Confirmed empirically against a live Flisk container (analytics-autogenerated
+    -data-governance-api-1) -- see design.md D2 Context. Compose projects are now
+    <project>-<stack>-autogenerated, so the name starts with the Flisk project too
+    (tdk-erp-system-analytics-autogenerated-data-governance-api-1). 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,
+    compose_files=None,
+    env_file="",
+    image="",
+):
+    """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.
+
+    `compose_files` (absolute paths), `env_file` and `image` let the gateway
+    create the container itself with `docker compose up --no-build` when the
+    image already exists, instead of waiting in Tilt's build queue behind
+    `tilt trigger`. Omitted headers make the gateway use `tilt trigger` only.
+
+    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)
+    api_path = cli_api_path(resource_entry_name, manifest)
+    entrypoints = build_entrypoints(TRAEFIK_BACKEND_ENABLE_HTTP, TRAEFIK_BACKEND_ENABLE_HTTPS)
+    router_name = resource_entry_name + "-wake"
+    headers_middleware_name = resource_entry_name + "-wake-headers"
+    strip_middleware_name = resource_entry_name + "-wake-strip"
+    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
+    ])
+    compose_headers = ""
+    if compose_files and image:
+        compose_headers = (
+            '\n          X-Wake-Compose-Project: "' + compose_project_name + '"'
+            + '\n          X-Wake-Compose-Files: "' + ",".join(compose_files) + '"'
+            + '\n          X-Wake-Env-File: "' + env_file + '"'
+            + '\n          X-Wake-Image: "' + image + '"'
+        )
+
+    return """# SYSTEM-GENERATED - DO NOT EDIT (sablier.deferStart static wake route)
+http:
+  routers:
+    {router_name}:
+      rule: "{rule}"
+      entryPoints:
+        - {entrypoint}
+      service: {service_name}
+      middlewares:
+        - {strip_middleware_name}
+        - {headers_middleware_name}
+      priority: {priority}
+  middlewares:
+    {strip_middleware_name}:
+      stripPrefix:
+        prefixes:
+          - "{api_path}"
+    {headers_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}"{compose_headers}
+  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,
+        strip_middleware_name=strip_middleware_name,
+        headers_middleware_name=headers_middleware_name,
+        api_path=api_path,
+        priority=STATIC_ROUTE_PRIORITY,
+        resource_entry_name=resource_entry_name,
+        container_name=container_name,
+        deps_header=deps_header,
+        internal_port=internal_port,
+        compose_headers=compose_headers,
+        gateway_host=gateway_host,
+        gateway_port=gateway_port,
+    )

package/engine/topologies/platform/docker/secrets/env_secrets.star

@@ -0,0 +1,74 @@
+# Copyright (c) 2026 Flisk contributors
+# SPDX-License-Identifier: MIT
+# =============================================================================
+# 🔑 SECRETS FROM THE PROJECT .env
+# =============================================================================
+# Purpose: Make `secrets.required` / `secrets.optional` in service.json real for local development.
+#
+# The default provider is `env-file`: a secret's value lives in the project `.env` (gitignored) and reaches the container through
+# Docker Compose's own `${NAME}` interpolation, so nothing secret is ever written to a generated, committed file. A required secret
+# uses `${NAME:?message}`, so Compose refuses to start the service when the name is missing; an optional one defaults to empty.
+#
+# `TDK_SECRET_PROVIDER=infisical` leaves the names to Infisical instead, and nothing is injected here.
+# =============================================================================
+
+DEFAULT_SECRET_PROVIDER = 'env-file'
+
+_NAME_FIRST = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz_'
+_NAME_REST = _NAME_FIRST + '0123456789'
+
+
+def get_secret_provider():
+    """The selected provider: `env-file` (default) or `infisical`."""
+    provider = str(os.environ.get('TDK_SECRET_PROVIDER', '')).strip().lower()
+    return provider if provider else DEFAULT_SECRET_PROVIDER
+
+
+def _is_valid_env_name(name):
+    if type(name) != 'string' or not name:
+        return False
+    if name[0] not in _NAME_FIRST:
+        return False
+    for i in range(len(name)):
+        if name[i] not in _NAME_REST:
+            return False
+    return True
+
+
+def _names(manifest, resource_name, kind):
+    secrets = manifest.get('secrets') or {}
+    names = secrets.get(kind) or []
+    if type(names) != 'list':
+        fail("{}: secrets.{} must be a list of environment variable names".format(resource_name, kind))
+    for name in names:
+        if not _is_valid_env_name(name):
+            fail("{}: invalid secret name '{}' in secrets.{}: use letters, digits and underscores, not starting with a digit".format(resource_name, name, kind))
+    return names
+
+
+def get_secret_environment_lines(manifest, resource_name):
+    """Compose `environment:` list lines (each starting with a newline) for a resource's secrets, or '' when there are none.
+
+    Args:
+        manifest: The service manifest (reads secrets.required and secrets.optional)
+        resource_name: Used in error messages and in the text Compose shows for a missing required secret
+
+    Returns:
+        str: Lines to append to the Compose environment block
+    """
+    if not manifest or not manifest.get('secrets'):
+        return ''
+
+    required = _names(manifest, resource_name, 'required')
+    optional = _names(manifest, resource_name, 'optional')
+
+    if get_secret_provider() != DEFAULT_SECRET_PROVIDER:
+        return ''
+
+    lines = ''
+    for name in required:
+        lines += '\n      - {name}=${{{name}:?{name} is required by {resource}. Add it to the project .env}}'.format(name=name, resource=resource_name)
+    for name in optional:
+        if name not in required:
+            lines += '\n      - {name}=${{{name}:-}}'.format(name=name)
+    return lines

package/engine/topologies/platform/docker/secrets/infisical.star

@@ -0,0 +1,109 @@
+# Copyright (c) 2026 Flisk contributors
+# SPDX-License-Identifier: MIT
+# =============================================================================
+# 🔐 LOCAL ENVIRONMENT GENERATOR
+# =============================================================================
+# Free-tier service env injection. Premium overlays may replace this module with
+# Infisical-backed secret injection.
+# =============================================================================
+#
+# This module provides:
+#   - Environment variable generation for docker-compose/.env injection
+#   - No external secret manager required in the public/free engine
+#
+# Usage:
+#   load("../secrets/infisical.star", "InfisicalEnv")
+#   env_vars = InfisicalEnv.get_for_service("my-service")
+# =============================================================================
+
+load("../constants.star", "PlatformDockerConstants")
+
+def _get_infisical_base_url():
+    """Get the Infisical base URL."""
+    return "http://{}-infisical:8080".format(PlatformDockerConstants.PROJECT_NAME)
+
+def get_infisical_environment_vars(as_array=True, resource_name=None, resource_type="backend"):
+    """
+    Generate environment variables for local Compose/.env injection.
+
+    Kept under the historical function name so existing Starlark callers do not
+    break. The free engine intentionally avoids Infisical credentials; premium
+    overlays can replace this implementation with a real secret-provider bridge.
+    
+    Args:
+        as_array: If True, return as YAML array format; else as dict format
+        resource_name: Optional service name for service-specific configuration
+        resource_type: Service type for path generation
+    
+    Returns:
+        String with environment variables in YAML format
+    """
+    env = {
+        "TDK_SECRET_PROVIDER": "${TDK_SECRET_PROVIDER:-env-file}",
+        "TDK_ENV": "${TILT_ENV:-development}",
+    }
+
+    if resource_name:
+        env["TDK_RESOURCE_NAME"] = resource_name
+        env["TDK_RESOURCE_TYPE"] = resource_type
+    
+    if as_array:
+        lines = []
+        for key, value in env.items():
+            lines.append("      - {}={}".format(key, value))
+        return "\n".join(lines)
+    else:
+        lines = []
+        for key, value in env.items():
+            lines.append("      {}: {}".format(key, value))
+        return "\n".join(lines)
+
+def get_for_service(resource_name, resource_type="backend", as_array=True):
+    """
+    Get Infisical environment variables for a specific service.
+    
+    Args:
+        resource_name: Name of the service
+        resource_type: Type of service
+        as_array: Return format (array or dict style)
+    
+    Returns:
+        String with environment variables
+    """
+    return get_infisical_environment_vars(
+        as_array=as_array,
+        resource_name=resource_name,
+        resource_type=resource_type,
+    )
+
+def get_batch_for_services(resource_configs):
+    """
+    Get Infisical environment variables for multiple services.
+    
+    Args:
+        resource_configs: List of dicts with 'name' and optional 'type'
+    
+    Returns:
+        Dict mapping service names to environment variable strings
+    """
+    results = {}
+    
+    for config in resource_configs:
+        name = config.get("name")
+        svc_type = config.get("type", "backend")
+        
+        if name:
+            results[name] = get_for_service(name, svc_type)
+    
+    return results
+
+# =============================================================================
+# Public API
+# =============================================================================
+
+InfisicalEnv = struct(
+    get_base_url=_get_infisical_base_url,
+    get_infisical_environment_vars=get_infisical_environment_vars,
+    get_for_service=get_for_service,
+    get_batch_for_services=get_batch_for_services,
+)