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

package/engine/spec.master.example

@@ -0,0 +1,341 @@
+#!/usr/bin/env starlark
+# BEFORE/AFTER: Making Tilt Obvious (Zig-Style Explicitness)
+# 
+# This file demonstrates how the new spec.master makes the system
+# completely explicit - addressing the Zig developer's critique about
+# "hidden control flow" and "no hidden allocations"
+
+# =============================================================================
+# ❌ BEFORE: Implicit, Hidden, Magic
+# =============================================================================
+
+# Magic load - where does this file live? Who knows.
+# load("./discovery/registry.star", "get_app_resources")
+
+# Magic context - what's inside ctx? Runtime mystery.
+# ctx = Context.build(full_graph, manifest)
+
+# Magic path construction - where does this write?
+# output_path = path.join(resource_path, "tsconfig.json")
+
+# Magic feature check - is this enabled? Where defined?
+# if features.is_enabled("istio"):
+
+# Magic port allocation - algorithm hidden
+# port = allocate_port(resource_name)
+
+# Magic dependency resolution - how does this work?
+# deps = resolve_dependencies(manifest)
+
+# =============================================================================
+# ✅ AFTER: Explicit, Obvious, No Magic
+# =============================================================================
+
+# Load the master spec - ALL paths are explicit constants
+load("{PROJECT_ROOT}/.tilt/spec.master", "SPEC", "CONSTANTS", "VALIDATION", "FEATURES", "OUTPUT", "DEBUG")
+
+# 💡 ALTERNATIVE: Use the easier-to-remember alias names
+# Both work identically - use whichever you prefer!
+#
+#     load("{PROJECT_ROOT}/.tilt/paths.star", "SPEC", "CONSTANTS", "DEBUG")
+#     load("{PROJECT_ROOT}/.tilt/where-things-live.star", "SPEC", "CONSTANTS", "DEBUG")
+#
+# Why aliases? Because "paths" is easier to remember than "spec.master" 😊
+
+# Explicit imports - you SEE exactly what files are loaded
+load(SPEC.DISCOVERY.REGISTRY, "get_app_resources", "get_resource_by_name")
+load(SPEC.DISCOVERY.LOADING, "load_manifest")
+load(SPEC.GENERATORS.VITE, "generate_vite_config")
+load(SPEC.GENERATORS.TSCONFIG, "generate_tsconfig")
+load(SPEC.GENERATORS.DOCKERFILE, "generate_dockerfile")
+load(SPEC.GENERATORS.MANIFEST_RESOURCE, "ManifestResource")
+
+# EXPLICIT path construction - no hidden logic
+def get_resource_path(resource_name):
+    """Build service path EXPLICITLY from constants."""
+    return SPEC.RESOURCES_DIR + "/product/" + resource_name
+
+def get_manifest_path(resource_path):
+    """Manifest path is EXPLICIT, not discovered."""
+    return resource_path + "/" + RESOURCE_PATTERNS.MANIFEST_FILE
+
+def get_output_path(resource_name, filename):
+    """Output path is EXPLICIT, constructed from constants."""
+    return OUTPUT.CONFIGS + "/" + resource_name + "/" + filename
+
+# =============================================================================
+# EXPLICIT CONFIGURATION GENERATION
+# =============================================================================
+
+def generate_resource_configs(resource_name, manifest):
+    """
+    Generate configs with EXPLICIT paths and constraints.
+    No hidden allocations. No magic context.
+    """
+    
+    # EXPLICIT: Validate inputs (Zig-style defensive programming)
+    if not resource_name:
+        fail("resource_name is empty - explicit validation")
+    
+    if not manifest:
+        fail("manifest is empty - explicit validation")
+    
+    # EXPLICIT: Port validation with visible constraints
+    port = manifest.get("port")
+    if port < VALIDATION.MIN_PORT or port > VALIDATION.MAX_PORT:
+        fail("port {} outside valid range [{}-{}]".format(
+            port, VALIDATION.MIN_PORT, VALIDATION.MAX_PORT
+        ))
+    
+    if port in VALIDATION.RESERVED_PORTS:
+        fail("port {} is in RESERVED_PORTS list".format(port))
+    
+    # EXPLICIT: Feature check - visible toggle
+    if FEATURES.ISTIO_INTEGRATION:
+        # 🗓️ ROADMAP: Will generate Istio configs when implemented
+        istio_config = generate_istio_config(manifest)
+    else:
+        # EXPLICIT: Currently using Traefik
+        istio_config = None
+    
+    # EXPLICIT: Path construction - you SEE where files go
+    resource_path = get_resource_path(resource_name)
+    output_dir = get_output_path(resource_name, "")
+    
+    configs = {
+        "tsconfig": {
+            "input": get_manifest_path(resource_path),
+            "output": output_dir + RESOURCE_PATTERNS.GENERATED_TSCONFIG,
+            "generator": SPEC.GENERATORS.TSCONFIG,
+        },
+        "vite": {
+            "input": get_manifest_path(resource_path),
+            "output": output_dir + RESOURCE_PATTERNS.GENERATED_VITE_CONFIG,
+            "generator": SPEC.GENERATORS.VITE,
+        },
+        "dockerfile": {
+            "input": get_manifest_path(resource_path),
+            "output": resource_path + "/" + RESOURCE_PATTERNS.DOCKERFILE,
+            "generator": SPEC.GENERATORS.DOCKERFILE,
+        },
+    }
+    
+    # EXPLICIT: Debug output (visible when DEBUG.DUMP_GENERATED_CONFIGS)
+    if DEBUG.DUMP_GENERATED_CONFIGS:
+        print("[DEBUG] Generated configs for {}:".format(resource_name))
+        for name, cfg in configs.items():
+            print("  {}: {}".format(name, cfg["output"]))
+    
+    return configs
+
+# =============================================================================
+# EXPLICIT SERVICE DISCOVERY (No Magic Globbing)
+# =============================================================================
+
+def discover_services_explicit():
+    """
+    Discover services with EXPLICIT search paths.
+    No hidden glob patterns. Everything visible.
+    """
+    discovered = []
+    
+    # EXPLICIT: Iterate declared search paths
+    for search_path in DISCOVERY.RESOURCE_SEARCH_PATHS:
+        # EXPLICIT: Glob pattern is declared in spec.master
+        pattern = search_path + "/" + DISCOVERY.MANIFEST_PATTERNS[0]  # service.json
+        
+        # EXPLICIT: Check exclusions
+        matches = glob([pattern], exclude=DISCOVERY.EXCLUDE_PATTERNS)
+        
+        for match in matches:
+            # EXPLICIT: Construct service info from path
+            resource_dir = os.path.dirname(match)
+            resource_name = os.path.basename(resource_dir)
+            
+            discovered.append({
+                "name": resource_name,
+                "path": resource_dir,
+                "manifest_path": match,
+            })
+    
+    return discovered
+
+# =============================================================================
+# EXPLICIT CONTEXT BUILDING (No Black Box)
+# =============================================================================
+
+def build_explicit_context(resource_manifest, all_services):
+    """
+    Build context EXPLICITLY - every field is visible.
+    No mystery black box.
+    """
+    ctx = struct(
+        # EXPLICIT: Source data
+        manifest = resource_manifest,
+        all_services = all_services,
+        
+        # EXPLICIT: Computed values (transparent logic)
+        resource_name = resource_manifest.get("appName"),
+        resource_path = get_resource_path(resource_manifest.get("appName")),
+        port = resource_manifest.get("port"),
+        
+        # EXPLICIT: Dependencies (resolved, not hidden)
+        dependencies = resolve_explicit_dependencies(
+            resource_manifest.get("dependsOn", []),
+            all_services
+        ),
+        
+        # EXPLICIT: System constants
+        constants = CONSTANTS,
+        validation = VALIDATION,
+        features = FEATURES,
+    )
+    
+    # EXPLICIT: Debug inspection
+    if DEBUG.DUMP_CONTEXT_ON_GENERATION:
+        print("[DEBUG] Context for {}:".format(ctx.resource_name))
+        print("  port: {}".format(ctx.port))
+        print("  dependencies: {}".format([d["name"] for d in ctx.dependencies]))
+        print("  features enabled: {}".format([f for f in dir(FEATURES) if not f.startswith("_")]))
+    
+    return ctx
+
+def resolve_explicit_dependencies(dep_names, all_services):
+    """
+    Resolve dependencies EXPLICITLY.
+    No hidden graph traversal.
+    """
+    resolved = []
+    
+    for dep_name in dep_names:
+        # EXPLICIT: Lookup in explicit list
+        found = None
+        for svc in all_services:
+            if svc["name"] == dep_name:
+                found = svc
+                break
+        
+        if not found:
+            fail("Dependency '{}' not found in explicit service list".format(dep_name))
+        
+        # EXPLICIT: Check for circular dependencies
+        if dep_name in resolved:
+            fail("Circular dependency detected involving '{}'".format(dep_name))
+        
+        resolved.append(found)
+    
+    return resolved
+
+# =============================================================================
+# EXPLICIT GENERATION ENTRY POINT
+# =============================================================================
+
+def generate_all_explicit():
+    """
+    Main generation with EXPLICIT flow.
+    Every step is visible. No magic.
+    """
+    
+    print("=" * 60)
+    print("TILT GENERATION - EXPLICIT MODE")
+    print("=" * 60)
+    
+    # EXPLICIT: Step 1 - Discovery
+    print("\n[1/5] DISCOVERY")
+    print("  Search paths: {}".format(DISCOVERY.RESOURCE_SEARCH_PATHS))
+    services = discover_services_explicit()
+    print("  Found {} services".format(len(services)))
+    for svc in services:
+        print("    - {} at {}".format(svc["name"], svc["path"]))
+    
+    # EXPLICIT: Step 2 - Validation
+    print("\n[2/5] VALIDATION")
+    for svc in services:
+        port = svc.get("port", 0)
+        if port < VALIDATION.MIN_PORT:
+            fail("  ❌ {}: port {} below minimum {}".format(
+                svc["name"], port, VALIDATION.MIN_PORT
+            ))
+        print("  ✅ {}: port {} valid".format(svc["name"], port))
+    
+    # EXPLICIT: Step 3 - Context Building
+    print("\n[3/5] CONTEXT BUILDING")
+    contexts = {}
+    for svc in services:
+        ctx = build_explicit_context(svc, services)
+        contexts[svc["name"]] = ctx
+        print("  ✅ {}: context built".format(svc["name"]))
+    
+    # EXPLICIT: Step 4 - Generation
+    print("\n[4/5] GENERATION")
+    generated = {}
+    for svc in services:
+        configs = generate_resource_configs(svc["name"], svc)
+        generated[svc["name"]] = configs
+        print("  ✅ {}: {} configs generated".format(svc["name"], len(configs)))
+    
+    # EXPLICIT: Step 5 - Output
+    print("\n[5/5] OUTPUT")
+    print("  Output directory: {}".format(OUTPUT.CONFIGS))
+    for svc_name, configs in generated.items():
+        for cfg_name, cfg in configs.items():
+            print("  Writing: {}".format(cfg["output"]))
+            # write_file(cfg["output"], cfg["content"])
+    
+    print("\n" + "=" * 60)
+    print("GENERATION COMPLETE")
+    print("  Services: {}".format(len(services)))
+    print("  Configs: {}".format(sum(len(c) for c in generated.values())))
+    print("  Output: {}".format(OUTPUT.CONFIGS))
+    print("=" * 60)
+
+# =============================================================================
+# ZIG-STYLE MANIFESTO APPLIED
+# =============================================================================
+
+"""
+WHAT CHANGED:
+
+BEFORE (Implicit):
+  - Paths discovered at runtime
+  - Features checked magically  
+  - Context is black box
+  - Errors at runtime
+
+AFTER (Explicit - Zig-style):
+  - Paths are CONSTANTS in spec.master
+  - Features are EXPLICIT STRUCT toggles
+  - Context is EXPLICIT STRUCT (every field visible)
+  - Errors at "compile time" (Tiltfile load)
+
+PRINCIPLES APPLIED:
+  ✅ No hidden control flow
+  ✅ No hidden allocations (paths explicit)
+  ✅ No magic (everything declared in spec.master)
+  ✅ Explicit is better than implicit
+  ✅ Fail fast with clear messages
+
+ANSWER TO ZIG DEVELOPER:
+  "You wanted obvious. Now it's obvious."
+  "Every path is a constant."
+  "Every feature is a toggle."
+  "Every context field is visible."
+  "No magic. No surprises."
+"""
+
+# =============================================================================
+# USAGE EXAMPLE
+# =============================================================================
+
+# To use in your Tiltfile:
+#
+# load("{}/.tilt/spec.master".format(PROJECT_ROOT), "SPEC", "CONSTANTS")
+# 
+# # Now EVERYTHING is explicit and obvious
+# print("Registry path: {}".format(SPEC.DISCOVERY.REGISTRY))
+# print("Max port: {}".format(VALIDATION.MAX_PORT))
+# print("Istio enabled: {}".format(FEATURES.ISTIO_INTEGRATION))
+#
+# # No more guessing where files live
+# # No more wondering what ctx contains
+# # No more hidden feature flags

package/engine/topologies/README.md

@@ -0,0 +1,34 @@
+---
+title: Topologies (Incremental Migration)
+status: backlog
+created: 2026-03-31
+updated: 2026-03-31
+---
+
+# Topologies (Incremental Migration)
+
+This folder is the new destination for Tilt topology modules.
+
+Current migrated modules (only currently needed runtime pieces):
+- `platform/docker/*` (native compose/dockerfile/dockerignore/golden-layer generators + layers)
+- `platform/net/proxy.star`
+- `platform/state/relational.star`
+- `platform/security/secrets.star`
+- `platform/registries/local.star`
+- `platform/observability/logging.star`
+- `tilt/common/utils.star` (shared runtime utilities)
+- `tilt/discovery/*` (native registry + native manifest scanner/grouping/dependency graph)
+- `tilt/discovery/manifest/*` (native manifest constants/loading/normalize/validation)
+- `tilt/config/{global,defaults,profiles,feature_flags}.star` (native config + native focus profile logic)
+- `tilt/generators/*` (native vite/typescript/npmrc/nginx modules)
+- `tilt/resources/*` (native libs/databases/infra-loader/watchers/orchestrator modules)
+- `product_autogenerated_services_list/services.star`
+- `product_autogenerated_resource_manifests/*`
+
+Explicitly not created yet (not needed by current runtime):
+- `platform/net/firewall.star`
+- Most unreferenced files from the full target map.
+
+Migration strategy:
+- Keep behavior stable while moving runtime code out of `compat/`.
+- Keep `compat/` as fallback shims during incremental cleanup.

package/engine/topologies/platform/docker/AGENTS.md

@@ -0,0 +1,59 @@
+# AGENTS.md - Docker Platform Infrastructure
+
+## Purpose
+
+Docker image building, golden image layers, and Dockerfile generation for all services.
+
+## Key Concepts
+
+### Golden Image Architecture (L1-L4)
+```
+L1: Base (Bun, Node, essential tools)
+L2: Dependencies (cached node_modules)
+L3: Builder (build tools)
+L4: Runtime (minimal production image)
+```
+
+## Key Files
+
+### Golden Images
+- **`golden_image.star`** - GoldenImage struct with L1-L4 builders
+- **`dockerfile.star`** - Dockerfile generation for apps
+- **`constants.star`** - Docker constants, image names
+
+### Layer Building
+- **`layers/l1_base_layers.star`** - Base image with Bun/Node
+- **`layers/l2_dependency_layers.star`** - Dependency installation
+- **`layers/l3_builder_layers.star`** - Build stage
+- **`layers/l4_runtime_layers.star`** - Minimal runtime
+
+### Specialized
+- **`layers/prisma/`** - Prisma-specific Docker layers
+- **`generators/golden_docker_generator.star`** - Old generator (v1)
+- **`generators/golden_docker_generator_v2.star`** - Current generator (v2)
+
+## Common Tasks
+
+### Generate Dockerfile for service
+```starlark
+load("./dockerfile.star", "generate_app_dockerfile")
+dockerfile = generate_app_dockerfile(path, resource_name, start_command)
+```
+
+### Get golden image
+```starlark
+load("./golden_image.star", "GoldenImage")
+digest = GoldenImage.get_digest("l2")
+```
+
+## Integration
+
+- Called by `generators/manifest_resource.star` - when building service resources
+- Used by discovery - to determine Dockerfile paths
+- Outputs to services' `autogenerated/Dockerfile.*.autogenerated`
+
+## Important Notes
+
+- Golden images use digests for cache invalidation
+- L2 layer caches `node_modules` for faster rebuilds
+- Each service's Dockerfile starts `FROM {project}/golden-image-l4:latest`

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

@@ -0,0 +1,167 @@
+# =============================================================================
+# 🔐 TILT SDK - AUTH CONFIGURATION UTILITIES
+# =============================================================================
+# Path: .tilt/topologies/platform/docker/auth.star
+# Purpose: Centralized authentication configuration helpers for docker-compose
+#          and environment file generation across the platform.
+# 
+# Design Principle: This module is decoupled from manifest.json structure.
+#          It accepts auth configuration as a dictionary parameter and does
+#          not know where the config comes from. Callers (env.star, compose.star)
+#          are responsible for extracting auth fields from manifest and passing
+#          them as the auth_config dict.
+# =============================================================================
+
+# Default values for auth configuration
+DEFAULT_AUTH_MODE = 'local-jwt'
+DEFAULT_JWT_SECRET = 'local-development-secret-min-32-chars-long'
+DEFAULT_IDENTITY_RESOURCE_URL = 'http://identity-service:3000'
+
+
+def get_auth_mode(auth_config):
+    """Get auth mode from auth config with default fallback.
+
+    Args:
+        auth_config: Auth configuration dictionary (may be None or empty)
+
+    Returns:
+        str: Auth mode ('local-jwt' or 'identity-service')
+    """
+    if not auth_config:
+        return DEFAULT_AUTH_MODE
+    return auth_config.get('authMode', DEFAULT_AUTH_MODE)
+
+
+def get_jwt_secret(auth_config):
+    """Get JWT secret from auth config with default fallback.
+
+    Args:
+        auth_config: Auth configuration dictionary (may be None or empty)
+
+    Returns:
+        str: JWT secret for local-jwt mode
+    """
+    if not auth_config:
+        return DEFAULT_JWT_SECRET
+    return auth_config.get('jwtSecret', DEFAULT_JWT_SECRET)
+
+
+def get_identity_resource_url(auth_config):
+    """Get identity service URL from auth config with default fallback.
+
+    Args:
+        auth_config: Auth configuration dictionary (may be None or empty)
+
+    Returns:
+        str: URL for identity service
+    """
+    if not auth_config:
+        return DEFAULT_IDENTITY_RESOURCE_URL
+    return auth_config.get('identityServiceUrl', DEFAULT_IDENTITY_RESOURCE_URL)
+
+
+def get_auth_config(auth_config):
+    """Get complete auth configuration from auth config dict.
+
+    Args:
+        auth_config: Auth configuration dictionary (may be None or empty)
+
+    Returns:
+        struct: Auth configuration with mode, jwt_secret, and identity_resource_url
+    """
+    return struct(
+        mode = get_auth_mode(auth_config),
+        jwt_secret = get_jwt_secret(auth_config),
+        identity_resource_url = get_identity_resource_url(auth_config),
+    )
+
+
+def is_local_jwt_mode(auth_config):
+    """Check if auth mode is local-jwt.
+
+    Args:
+        auth_config: Auth configuration dictionary (may be None or empty)
+
+    Returns:
+        bool: True if auth mode is 'local-jwt'
+    """
+    return get_auth_mode(auth_config) == 'local-jwt'
+
+
+def is_identity_resource_mode(auth_config):
+    """Check if auth mode is identity-service.
+
+    Args:
+        auth_config: Auth configuration dictionary (may be None or empty)
+
+    Returns:
+        bool: True if auth mode is 'identity-service'
+    """
+    return get_auth_mode(auth_config) == 'identity-service'
+
+
+def generate_docker_compose_auth_env(auth_config):
+    """Generate docker-compose environment variables for auth configuration.
+
+    This function returns the properly formatted environment variable block
+    for docker-compose.yml files based on the auth mode.
+
+    Args:
+        auth_config: Auth configuration dictionary (may be None or empty)
+
+    Returns:
+        str: Formatted auth environment variables for docker-compose
+    """
+    auth_mode = get_auth_mode(auth_config)
+    jwt_secret = get_jwt_secret(auth_config)
+    identity_resource_url = get_identity_resource_url(auth_config)
+
+    if auth_mode == 'local-jwt':
+        return """      - AUTH_MODE=local-jwt
+      - JWT_SECRET=${JWT_SECRET:-%(jwt_secret)s}""" % {'jwt_secret': jwt_secret}
+    else:
+        return """      - AUTH_MODE=identity-service
+      - IDENTITY_RESOURCE_URL=${IDENTITY_RESOURCE_URL:-%(identity_resource_url)s}""" % {'identity_resource_url': identity_resource_url}
+
+
+def generate_env_file_auth_section(auth_config):
+    """Generate .env file auth section content.
+
+    This function returns the formatted authentication configuration section
+    for .env.backend.autogenerated files.
+
+    Args:
+        auth_config: Auth configuration dictionary (may be None or empty)
+
+    Returns:
+        str: Formatted auth section for .env files
+    """
+    auth_mode = get_auth_mode(auth_config)
+    jwt_secret = get_jwt_secret(auth_config)
+    identity_resource_url = get_identity_resource_url(auth_config)
+
+    content = """
+# Authentication Configuration
+# Mode: {auth_mode} (options: local-jwt, identity-service)
+AUTH_MODE={auth_mode}
+""".format(auth_mode=auth_mode)
+
+    if auth_mode == 'local-jwt':
+        content += "JWT_SECRET={jwt_secret}\n".format(jwt_secret=jwt_secret)
+    else:
+        content += "IDENTITY_RESOURCE_URL={identity_resource_url}\n".format(identity_resource_url=identity_resource_url)
+
+    return content
+
+
+# Export all functions as a struct for easy importing
+AuthConfig = struct(
+    get_auth_mode = get_auth_mode,
+    get_jwt_secret = get_jwt_secret,
+    get_identity_resource_url = get_identity_resource_url,
+    get_auth_config = get_auth_config,
+    is_local_jwt_mode = is_local_jwt_mode,
+    is_identity_resource_mode = is_identity_resource_mode,
+    generate_docker_compose_auth_env = generate_docker_compose_auth_env,
+    generate_env_file_auth_section = generate_env_file_auth_section,
+)

package/engine/topologies/platform/docker/build/golden_image.star

@@ -0,0 +1,37 @@
+# =============================================================================
+# 🏗️ TILT SDK - GOLDEN LAYERED IMAGES PROVIDER
+# =============================================================================
+# Purpose: Public API facade for golden layered image orchestration.
+# =============================================================================
+
+load('./golden_image_constants.star',
+    'GOLDEN_IMAGE_PREFIX',
+    'GOLDEN_LAYERS',
+    'get_layer_reference',
+)
+load('./golden_image_build.star', 'build_golden_layers')
+load('./golden_image_dockerfile.star', 'generate_golden_dockerfile')
+
+
+GoldenImage = struct(
+    # Build functions
+    build = build_golden_layers,
+
+    # Reference getters
+    get_layer = get_layer_reference,
+    l1 = lambda: get_layer_reference('l1'),
+    l2 = lambda: get_layer_reference('l2'),
+    l3_backend = lambda: get_layer_reference('l3-backend'),
+    l3_frontend = lambda: get_layer_reference('l3-frontend'),
+    l3_migrator = lambda: get_layer_reference('l3-migrator'),
+    l4_backend = lambda: get_layer_reference('l4-backend'),
+    l4_frontend = lambda: get_layer_reference('l4-frontend'),
+    l4_migrator = lambda: get_layer_reference('l4-migrator'),
+
+    # Constants
+    layers = GOLDEN_LAYERS,
+    prefix = GOLDEN_IMAGE_PREFIX,
+
+    # Generators
+    generate_dockerfile = generate_golden_dockerfile,
+)