@tdk-landscape/tdk-cli-core 1.3.15 → 1.3.26

package/engine/topologies/tilt/generators/api_gateway.star

@@ -0,0 +1,145 @@
+# =============================================================================
+# 🌐 TILT SDK - API GATEWAY (Referer-Based Context Routing)
+# =============================================================================
+# Path: .tilt/topologies/tilt/generators/api_gateway.star
+# Purpose: Auto-discover backends and generate referer-based routing map
+# =============================================================================
+
+load('../../../../discovery/registry.star', 'get_app_resources', 'get_resource_aliases')
+
+
+def _extract_referer_pattern(base_path, stack):
+    """Extract referer pattern from basePath or stack - use actual names."""
+    if base_path:
+        return base_path.strip('/').lower()
+    if stack:
+        return stack.lower()
+    return None
+
+
+def _collect_backend_dependencies(frontend_manifest):
+    """
+    Resolve backend resource names for a frontend manifest's declared dependencies.
+    Includes frontend's own backend and backend resources from dependency aliases.
+    """
+    if frontend_manifest == None:
+        return None
+
+    allowed = {}
+
+    frontend_backend = frontend_manifest.get('backendName')
+    if frontend_backend:
+        allowed[frontend_backend] = True
+
+    manifest_deps = frontend_manifest.get('dependencies')
+    if manifest_deps == None:
+        manifest_deps = frontend_manifest.get('dependsOn', [])
+
+    aliases = get_resource_aliases()
+    for dep in manifest_deps:
+        dep_name = str(dep)
+        if dep_name.endswith('-backend'):
+            allowed[dep_name] = True
+            continue
+
+        alias_targets = aliases.get(dep_name, [])
+        for target in alias_targets:
+            if target.endswith('-backend'):
+                allowed[target] = True
+
+    return allowed
+
+
+def _get_backend_port(backend_name, fallback = 4000):
+    for service in get_app_resources():
+        for resource in service.get('resources', []):
+            if resource.get('name') == backend_name:
+                manifest = resource.get('_manifest', {})
+                app_type = manifest.get('appType', resource.get('app_type', 'backend'))
+                if app_type == 'backend':
+                    return manifest.get('containerPort', 3000)
+                return resource.get('port', fallback)
+    return fallback
+
+
+def get_backend_routing_map(frontend_manifest = None):
+    """
+    Auto-scan all backends from discovered manifests and build referer-based routing map.
+    Returns dict: {referer_pattern: {backend_name, port}}
+    """
+    routing_map = {}
+    default_backend = None
+    
+    allowed_backends = _collect_backend_dependencies(frontend_manifest)
+
+    for resource_group in get_app_resources():
+        stack_name = resource_group.get('name', '')
+        
+        for resource in resource_group.get('resources', []):
+            manifest = resource.get('_manifest', {})
+            app_type = manifest.get('appType', resource.get('app_type', 'backend'))
+            
+            if app_type != 'backend':
+                continue
+            
+            backend_name = resource.get('name', '')
+            if allowed_backends != None and backend_name not in allowed_backends:
+                continue
+            if app_type == 'backend':
+                port = manifest.get('containerPort', 3000)
+            else:
+                port = resource.get('port', 4000)
+            
+            base_path = manifest.get('basePath', '')
+            stack = manifest.get('stack', stack_name)
+            
+            pattern = _extract_referer_pattern(base_path, stack)
+            
+            if pattern:
+                routing_map[pattern] = {'name': backend_name, 'port': port}
+            elif not default_backend:
+                default_backend = {'name': backend_name, 'port': port}
+    
+    return routing_map, default_backend
+
+
+def build_referer_map_block(frontend_manifest = None):
+    """
+    Build the nginx map block by scanning all manifests.
+    Routes are sorted by specificity (longest path first) to ensure proper matching.
+    Uses flexible matching to handle both /order/ and /orders paths.
+    """
+    routing_map, default_backend = get_backend_routing_map(frontend_manifest)
+    
+    sorted_patterns = sorted(routing_map.keys(), key=len, reverse=True)
+    
+    lines = [
+        '    # Auto-discovered backend routing map (referer-based context routing)',
+        '    map $http_referer $api_backend {'
+    ]
+    
+    for pattern in sorted_patterns:
+        backend = routing_map[pattern]
+        backend_url = 'http://{}:{}'.format(backend['name'], backend['port'])
+        lines.append('        ~*{} {};'.format(pattern, backend_url))
+    
+    if default_backend:
+        default_url = 'http://{}:{}'.format(default_backend['name'], default_backend['port'])
+        lines.append('        default {};'.format(default_url))
+    elif frontend_manifest != None and frontend_manifest.get('backendName'):
+        backend_name = frontend_manifest.get('backendName')
+        backend_port = _get_backend_port(backend_name, 4000)
+        lines.append('        default http://{}:{};'.format(backend_name, backend_port))
+    else:
+        # No hardcoded fallback - backendName must be specified in manifest
+        lines.append('        default http://backend-not-configured:4000;')
+    
+    lines.append('    }')
+    
+    return '\n'.join(lines)
+
+
+ApiGateway = struct(
+    get_backend_routing_map = get_backend_routing_map,
+    build_referer_map_block = build_referer_map_block,
+)

package/engine/topologies/tilt/generators/index.star

@@ -0,0 +1,124 @@
+# =============================================================================
+# 🎯 GENERATORS - Master Index
+# =============================================================================
+# All generators for Tilt topology configuration
+# =============================================================================
+
+# =============================================================================
+# Legacy Generators (existing)
+# =============================================================================
+
+# Load individual generator functions (they export functions, not structs)
+load("./typescript/backend_tsconfig.star", "generate_backend_tsconfig")
+load("./typescript/frontend_tsconfig.star", "generate_frontend_tsconfig")
+load("./typescript/frontend_library_tsconfig.star", "generate_frontend_library_tsconfig")
+load("./typescript/backend_library_tsconfig.star", "generate_backend_library_tsconfig")
+load("./typescript/prisma_config.star", "generate_prisma_config")
+load("./typescript/playwright_config.star", "generate_playwright_config")
+
+load("./vite/generators.star", "generate_for_manifest")
+load("./npmrc.star", "PackageConfig")
+load("./agents_md.star", "AgentsMd")
+# NOTE: nginx_conf.star and api_gateway.star loaded from manifest_resource.star
+# to avoid circular imports with discovery/registry
+
+# =============================================================================
+# NEW: Pre-Flight Validation Generators (v2.0)
+# =============================================================================
+# These generators prevent vibe-coding failures by validating before build
+
+load("./validators.star", "Validators")
+# fixed_frontend_tsconfig.star, dependency_manifest.star, and
+# database_provisioner.star moved to premium/ - none had any call sites
+# outside this file, so they were dead code in the free engine.
+
+# =============================================================================
+# 🔐 INFISICAL Secrets Management Generators
+# =============================================================================
+# Provides complete Infisical integration for secret management
+
+load("./infisical/index.star", "Infisical")
+
+# =============================================================================
+# Legacy Exports (for backward compatibility)
+# =============================================================================
+
+# Functions are already loaded directly
+# Vite generator
+Vite = struct(
+    for_manifest = generate_for_manifest,
+)
+
+# =============================================================================
+# NEW: Pre-Flight Validation Exports
+# =============================================================================
+
+# Validators - Pre-flight checks
+Validate = Validators
+
+# =============================================================================
+# 🔐 INFISICAL Secrets Management Exports
+# =============================================================================
+
+# Complete Infisical integration
+SecretsManagement = Infisical
+
+# =============================================================================
+# Master Generation Orchestrator
+# =============================================================================
+
+def run_pre_flight_validations(resource_path, manifest, all_services, global_config):
+    """
+    Runs all pre-flight validations for a service.
+    
+    This is the main entry point for validation. Call this during config-gen
+    to catch issues before they cause build failures.
+    
+    Args:
+        resource_path: Path to service directory
+        manifest: Service manifest dict
+        all_services: List of all services for dependency checking
+        global_config: Global topology config
+    
+    Returns:
+        Validation report dict
+    """
+    return Validators.run_all_validations(
+        resource_path,
+        manifest,
+        all_services,
+        global_config,
+        None,  # write_fn - will write to .autogenerated/
+    )
+
+# generate_fixed_frontend_tsconfig, resolve_missing_dependencies, and
+# provision_resource_database moved to premium/ along with the modules
+# they wrapped (fixed_frontend_tsconfig.star, dependency_manifest.star,
+# database_provisioner.star) - none had call sites outside this file.
+
+# =============================================================================
+# Exports
+# =============================================================================
+
+Generators = struct(
+    # Legacy
+    generate_backend_tsconfig=generate_backend_tsconfig,
+    generate_frontend_tsconfig=generate_frontend_tsconfig,
+    generate_frontend_library_tsconfig=generate_frontend_library_tsconfig,
+    generate_backend_library_tsconfig=generate_backend_library_tsconfig,
+    generate_prisma_config=generate_prisma_config,
+    generate_playwright_config=generate_playwright_config,
+    Vite=Vite,
+
+    # NEW: Pre-flight validation
+    Validate=Validate,
+
+    # NEW: Orchestrators
+    run_pre_flight_validations=run_pre_flight_validations,
+
+    # NEW: Infisical Secrets Management
+    SecretsManagement=SecretsManagement,
+
+    # NEW: AGENTS.md Generator for .autogenerated/ folder
+    AgentsMd=AgentsMd,
+)

package/engine/topologies/tilt/generators/infisical/README.md

@@ -0,0 +1,424 @@
+# 🔐 Infisical Starlark Generators - Complete Documentation
+
+## Overview
+
+The Infisical Starlark generators provide a complete, programmatic way to manage secret injection in the TDK CLI. This replaces shell-based configuration with type-safe Starlark code.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    INFISICAL GENERATORS                         │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  1. SECRETS GENERATOR (secrets_generator.star)                  │
+│     ├── generate_for_service() - Service secret config         │
+│     ├── generate_docker_compose_env() - Docker Compose env   │
+│     ├── generate_entrypoint_env() - Entrypoint configuration │
+│     └── generate_local_env_template() - Local dev .env       │
+│                                                                 │
+│  2. PATH MANAGER (path_manager.star)                            │
+│     ├── plan_resource_path() - Plan Infisical path              │
+│     ├── validate_path() - Path validation                      │
+│     ├── known_paths - 14 predefined service paths              │
+│     └── ROOT_PATHS, PLATFORM_PATHS - Path constants            │
+│                                                                 │
+│  3. MACHINE IDENTITY (machine_identity.star)                    │
+│     ├── generate_universal_auth() - Client ID/Secret auth    │
+│     ├── generate_development_machine() - Dev machine config  │
+│     ├── generate_ci_machine() - CI/CD machine config         │
+│     └── AUTH_METHODS - All supported auth methods              │
+│                                                                 │
+│  4. ORGANIZATION (organization.star)                            │
+│     ├── generate_config() - Complete org setup                 │
+│     ├── ENVIRONMENTS - dev, staging, prod configs              │
+│     ├── ROLES - Admin, developer, readonly, etc.             │
+│     └── SECRET_TEMPLATES - DATABASE_URL, JWT_SECRET, etc.      │
+│                                                                 │
+│  5. DOCKER INTEGRATION (infisical_docker.star)                │
+│     ├── runtime_setup() - L4 runtime secret injection          │
+│     ├── builder_setup() - L3 builder CLI setup                 │
+│     └── generate_compose_env() - Docker Compose environment  │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Quick Start
+
+### 1. Load the Modules
+
+```starlark
+# Option 1: Load complete Infisical module
+load("engine/topologies/tilt/generators/infisical/index.star", "Infisical")
+
+# Option 2: Load from generators index (recommended)
+load("engine/topologies/tilt/generators/index.star", "Generators")
+Infisical = Generators.SecretsManagement
+
+# Option 3: Load from security module (full integration)
+load("engine/topologies/platform/security/secrets.star", "Secrets")
+```
+
+### 2. Configure Service Secrets
+
+```starlark
+# Generate complete configuration for a service
+config = Infisical.Secrets.generate_for_service(
+    resource_name="user-management-backend",
+    secret_path="/services/user",
+    resource_type="backend",
+    command="bun run src/index.ts",
+)
+
+# Access generated configuration
+print(config["resource_name"])        # "user-management-backend"
+print(config["secret_path"])         # "/services/user"
+print(config["required_secrets"])    # ["DATABASE_URL", "JWT_SECRET", "RESOURCE_API_KEY"]
+print(config["docker_compose"]["environment"])
+```
+
+### 3. Use in Dockerfile Generation
+
+```starlark
+# In L4 runtime layer generation
+load("engine/topologies/platform/docker/layers/infisical/index.star", "InfisicalLayers")
+
+def generate_backend_runtime(resource_name, cmd="bun run start"):
+    parts = []
+    
+    # ... other Dockerfile setup ...
+    
+    # Use InfisicalDocker for runtime secret injection
+    infisical_setup = InfisicalLayers.Docker.runtime_setup(
+        resource_name=resource_name,
+        resource_type="backend",
+        command=cmd,
+        use_entrypoint=True,
+    )
+    parts.append(infisical_setup)
+    
+    return "".join(parts)
+```
+
+### 4. Use in Docker Compose
+
+```starlark
+# Generate environment variables for docker-compose
+env = Infisical.Docker.generate_compose_env(
+    resource_name="user-management-backend",
+    resource_type="backend",
+)
+
+# Use in dc_resource
+dc_resource("user-management-backend", env=env)
+```
+
+## Detailed API Reference
+
+### Secrets Generator
+
+#### `generate_for_service(resource_name, secret_path, resource_type, command, additional_vars)`
+
+Generates complete secret configuration for a service.
+
+**Parameters:**
+- `resource_name` (str): Name of the service (e.g., "user-management-backend")
+- `secret_path` (str): Infisical path (e.g., "/services/user")
+- `resource_type` (str): Type of service (backend, frontend, payment, notification)
+- `command` (str): Command to run after secret injection (optional)
+- `additional_vars` (dict): Additional environment variables (optional)
+
+**Returns:**
+```starlark
+{
+    "resource_name": str,
+    "secret_path": str,
+    "resource_type": str,
+    "validation": {"valid": bool, "errors": [str]},
+    "docker_compose": {"environment": dict},
+    "entrypoint": {"environment": dict},
+    "kubernetes": {"secret_ref": dict},
+    "local_template": str,
+    "required_secrets": [str],
+}
+```
+
+#### `generate_for_services_batch(services_config)`
+
+Batch configuration for multiple services.
+
+```starlark
+services = [
+    {"name": "user", "path": "/services/user", "type": "backend"},
+    {"name": "payment", "path": "/services/payment", "type": "payment"},
+]
+configs = Infisical.Secrets.generate_for_services_batch(services)
+```
+
+### Path Manager
+
+#### `plan_resource_path(resource_name, resource_type, parent_path)`
+
+Plans the Infisical path for a service.
+
+```starlark
+plan = Infisical.Paths.plan_resource_path(
+    resource_name="user-management-backend",
+    resource_type="backend",
+)
+
+# Returns:
+# {
+#     "resource_name": "user-management-backend",
+#     "resource_type": "backend",
+#     "parent_path": "/services",
+#     "resource_folder": "user",
+#     "full_path": "/services/user",
+#     "validation": {"valid": True, "errors": [], "warnings": []},
+#     "subpaths": ["/services/user/database", ...],
+# }
+```
+
+#### Predefined Service Paths
+
+14 services have predefined paths:
+
+```starlark
+# Access all known paths
+print(Infisical.Paths.known_paths)
+
+# Get specific service path
+path = Infisical.Paths.get_known_resource_path("user-management-backend")
+# Returns: "/services/user"
+```
+
+| Service | Path |
+|---------|------|
+| user-management-backend | /services/user |
+| order-management-backend | /services/order |
+| order-planner-backend | /services/order-planner |
+| staff-management-backend | /services/staff |
+| treatment-management-backend | /services/treatment |
+| inventory-management-backend | /services/inventory |
+| website-management-backend | /services/website |
+| gdpr-compliance-backend | /services/gdpr |
+| payment-management-backend | /services/payment |
+| payment-processing-backend | /services/billing |
+| api-gateway | /services/api-gateway |
+| api-gateway-test | /services/api-gateway-test |
+| orchestrator-glue-backend | /services/orchestrator-glue |
+
+### Machine Identity
+
+#### `generate_universal_auth(identity_name, access_paths, project_id, environment)`
+
+Generates Universal Auth (Client ID + Client Secret) configuration.
+
+```starlark
+config = Infisical.Identity.generate_universal_auth(
+    identity_name="dev-machine",
+    access_paths=["/services/*", "/platform/*"],
+    project_id="bc7cf07f-4002-4148-bca8-78a05c95dea2",
+    environment="dev",
+)
+```
+
+#### Predefined Machine Templates
+
+```starlark
+# Development machine (broad access)
+dev_machine = Infisical.Identity.generate_development_machine("dev-machine")
+
+# CI/CD machine (for GitHub Actions)
+ci_machine = Infisical.Identity.generate_ci_machine("github-actions")
+
+# Service-specific machine (restricted access)
+resource_machine = Infisical.Identity.generate_resource_specific_machine("user")
+```
+
+### Organization
+
+#### `generate_config(org_name, env_names, resource_names)`
+
+Generates complete organization configuration.
+
+```starlark
+org = Infisical.Org.generate_config(
+    org_name="{project}",
+    env_names=["dev", "staging", "prod"],
+    resource_names=["user", "order", "payment"],
+)
+
+# Returns complete setup including:
+# - Organization metadata
+# - Project configuration
+# - Environments
+# - Roles
+# - Folder structure
+# - Secret templates
+```
+
+## Migration from Shell Scripts
+
+### Before (Shell-based)
+
+```dockerfile
+# Hardcoded in Dockerfile generation
+COPY --chmod=0755 shared-platform-engineering/docker-templates/infisical-entrypoint.sh /entrypoint.sh
+ENV RESOURCE_NAME=my-service
+ENV INFISICAL_SECRET_PATH=/services/my-service
+ENTRYPOINT ["/entrypoint.sh"]
+CMD ["bun", "run", "start"]
+```
+
+### After (Starlark generators)
+
+```starlark
+# In your Tiltfile or .star file
+load("engine/topologies/platform/docker/layers/infisical/index.star", "InfisicalLayers")
+
+# Generate Dockerfile snippet dynamically
+infisical_setup = InfisicalLayers.Docker.runtime_setup(
+    resource_name="my-service",
+    secret_path="/services/my-service",  # Auto-generated if not provided
+    resource_type="backend",
+    command="bun run start",
+)
+
+# Returns:
+# COPY --chmod=0755 shared-platform-engineering/docker-templates/infisical-entrypoint.sh /entrypoint.sh
+# ENV RESOURCE_NAME=my-service
+# ENV INFISICAL_SECRET_PATH=/services/my-service
+# ENV INFISICAL_TOKEN=${INFISICAL_TOKEN:-}
+# ... (all env vars from generator)
+# ENTRYPOINT ["/entrypoint.sh"]
+# CMD ["bun", "run", "start"]
+```
+
+## Usage in Tiltfile
+
+### Complete Example
+
+```starlark
+# Load modules
+load("engine/topologies/platform/security/secrets.star", "Secrets")
+load("engine/topologies/tilt/generators/infisical/index.star", "Infisical")
+
+# Define services to configure
+services = [
+    "user-management-backend",
+    "order-management-backend",
+    "payment-management-backend",
+]
+
+# Configure all services
+for service in services:
+    # Get predefined configuration
+    config = Secrets.configure_predefined_service(service)
+    
+    if config:
+        # Use in docker_compose
+        docker_compose("services/{}/docker-compose.yml".format(service))
+        dc_resource(
+            service,
+            env=config["docker_compose"]["environment"],
+            labels=["backend"],
+        )
+
+# Or configure all at once
+all_configs = Secrets.configure_all_predefined_services()
+```
+
+## Testing
+
+### Validate Paths
+
+```starlark
+# Validate a custom path
+result = Infisical.Paths.validate_path("/services/my-service")
+print(result["valid"])      # True/False
+print(result["errors"])     # [] or [error messages]
+print(result["normalized"]) # Normalized path
+```
+
+### Validate Machine Identity
+
+```starlark
+# Check auth method
+result = Infisical.Identity.validate_auth_method("universal-auth")
+print(result["valid"])      # True
+print(result["supported"])  # True
+print(result["deprecated"]) # False
+```
+
+## File Structure
+
+```
+tdk-cli/engine/topologies/
+├── tilt/generators/infisical/
+│   ├── index.star              # Master module export
+│   ├── secrets_generator.star  # Secret injection config
+│   ├── path_manager.star       # Path/folder management
+│   ├── machine_identity.star   # Machine ID configuration
+│   ├── organization.star       # Org setup templates
+│   └── examples.star           # Usage examples
+│
+└── platform/docker/layers/infisical/
+    ├── index.star              # Docker layers index
+    └── infisical_docker.star   # Dockerfile generation
+```
+
+## Best Practices
+
+1. **Use Predefined Services**: When possible, use `Secrets.PREDEFINED_RESOURCES` instead of manual configuration.
+
+2. **Validate Early**: Always validate paths and configurations before using them:
+   ```starlark
+   validation = Infisical.Paths.validate_path(path)
+   if not validation["valid"]:
+       fail("Invalid path: " + str(validation["errors"]))
+   ```
+
+3. **Don't Hardcode Secrets**: Always use generators for secret paths and never hardcode secret values.
+
+4. **Batch Configuration**: Use `generate_for_services_batch()` when configuring multiple services.
+
+5. **Environment Separation**: Use different configurations for dev/staging/prod:
+   ```starlark
+   if environment == "prod":
+       config = Infisical.Identity.generate_production_machine(...)
+   else:
+       config = Infisical.Identity.generate_development_machine(...)
+   ```
+
+## Troubleshooting
+
+### Path Validation Failures
+
+```starlark
+result = Infisical.Paths.validate_path("/invalid/path with spaces")
+# Returns: {"valid": False, "errors": ["Invalid characters: [' ']"]}
+```
+
+Fix: Use the path normalizer
+```starlark
+normalized = Infisical.Paths.normalize_path("/invalid/path with spaces")
+# Returns: "/invalid/path-with-spaces"
+```
+
+### Unknown Service
+
+```starlark
+path = Infisical.Paths.get_known_resource_path("unknown-service")
+# Returns: None
+
+# Solution: Plan a new path
+plan = Infisical.Paths.plan_resource_path("unknown-service")
+path = plan["full_path"]  # "/services/unknown-service"
+```
+
+## See Also
+
+- `examples.star` - Complete usage examples
+- `SECRETS_SETUP_COMPLETE.md` - Infisical setup documentation
+- `MACHINE_IDENTITY.md` - Machine identity setup guide