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

package/engine/topologies/tilt/common/utils.star

@@ -0,0 +1,364 @@
+# =============================================================================
+# 🔧 TILT SDK - CORE UTILITIES MODULE
+# =============================================================================
+# Path: .tilt/topologies/tilt/common/utils.star
+# Purpose: Foundational helper functions, constants, and shared API surface.
+# =============================================================================
+
+load('./utils_env.star',
+    'load_dotenv',
+    'validate_infisical_environment',
+    'should_enable',
+)
+load('./utils_debug.star',
+    'DEBUG_MODE',
+    'debug_log',
+    'inspect',
+    'breadcrumb',
+    'fail_with_context',
+)
+load('./utils_docker_networks.star',
+    _fix_docker_networks = 'fix_docker_networks',
+    _cleanup_docker_networks = 'cleanup_docker_networks',
+)
+load('./utils_output.star',
+    'print_resource_summary',
+    'get_template_header',
+)
+load('../../platform/docker/constants.star', 'PlatformDockerConstants')
+
+# =============================================================================
+# 📦 INTERNAL DEPENDENCY CONSTANTS
+# =============================================================================
+
+INTERNAL_SCOPE = PlatformDockerConstants.NPM_SCOPE
+
+LIBRARY_ROOTS = {
+    'platform': 'shared-platform-engineering',
+    'product': 'shared-product-engineering',
+    'ddd': 'shared-ddd-layers',
+}
+
+DDD_LAYERS = ['domain', 'application', 'infrastructure', 'presentation']
+
+# =============================================================================
+# 📦 MIGRATED PACKAGES CONFIGURATION
+# =============================================================================
+# Map of package names that have been moved from their conventional locations
+# to new paths. This allows the resolver to find packages at non-standard paths.
+# Format: "package-name": ("path-relative-to-repo-root", "library-type")
+# =============================================================================
+
+MIGRATED_PACKAGES = {
+    # Introvertic packages reorganized into unified folder
+    "introvertic-core": ("shared-product-engineering/introvertic/core", "product"),
+    "introvertic-ui": ("shared-product-engineering/introvertic/ui", "product"),
+    "introvertic-docs": ("shared-product-engineering/introvertic/ui/docs", "product"),
+}
+
+# Import from canonical location to avoid duplication
+load("../manifest/constants.star", "MANIFEST_FILENAME")
+
+# List of all shared platform networks
+# All networks use PROJECT_NAME format (e.g., beauty_crm_*)
+PLATFORM_NETWORKS = [
+  PlatformDockerConstants.NETWORK_TRAEFIK_PUBLIC,
+  PlatformDockerConstants.PROJECT_NAME + "_traefik-private",
+  PlatformDockerConstants.NETWORK_BACKEND,
+  PlatformDockerConstants.NETWORK_DATABASE,
+  PlatformDockerConstants.NETWORK_INFISICAL,
+  PlatformDockerConstants.VERDACCIO_NETWORK,
+  PlatformDockerConstants.NETWORK_PROXY,
+]
+
+# =============================================================================
+# 🔍 CENTRALIZED DEPENDENCY EXTRACTION (Single Source of Truth)
+# =============================================================================
+
+def get_internal_deps(resource_path):
+    """
+    Extract all @tdk/* dependencies from a service's package.json.
+    """
+    pkg_json_path = resource_path + '/package.json'
+    pkg_content = read_file(pkg_json_path, default='')
+
+    if not pkg_content or not str(pkg_content).strip():
+        return []
+
+    pkg = decode_json(pkg_content)
+    if not pkg:
+        return []
+
+    internal_deps = []
+
+    # Scan all dependency types in one pass
+    for dep_type in ['dependencies', 'devDependencies', 'peerDependencies']:
+        deps = pkg.get(dep_type, {})
+        for dep_name in deps.keys():
+            if dep_name.startswith(INTERNAL_SCOPE) and dep_name not in internal_deps:
+                internal_deps.append(dep_name)
+
+    return internal_deps
+
+
+def resolve_lib_path(package_name):
+    """
+    Resolve @tdk/* package name to workspace path using naming conventions.
+    
+    Checks MIGRATED_PACKAGES first for packages that have been moved from their
+    conventional locations, then falls back to standard naming conventions.
+    """
+    if not package_name.startswith(INTERNAL_SCOPE):
+        return (None, None)
+
+    lib_name = package_name[len(INTERNAL_SCOPE):]
+
+    # Check migrated packages first (packages moved from conventional locations)
+    if lib_name in MIGRATED_PACKAGES:
+        return MIGRATED_PACKAGES[lib_name]
+
+    # Standard naming convention resolution
+    if lib_name in DDD_LAYERS:
+        return (LIBRARY_ROOTS['ddd'] + '/' + lib_name, 'ddd')
+
+    if lib_name.startswith('platform-'):
+        return (LIBRARY_ROOTS['platform'] + '/' + lib_name, 'platform')
+
+    if lib_name.startswith('product-'):
+        return (LIBRARY_ROOTS['product'] + '/' + lib_name, 'product')
+
+    return (LIBRARY_ROOTS['platform'] + '/' + lib_name, 'platform')
+
+
+def build_deps_mapping(resource_path, internal_deps=None):
+    """Build a mapping of package_name -> library path for internal dependencies."""
+    if internal_deps == None:
+        internal_deps = get_internal_deps(resource_path)
+
+    mapping = {}
+    for dep_name in internal_deps:
+        lib_info = resolve_lib_path(dep_name)
+        lib_path = lib_info[0]
+
+        if lib_path:
+            mapping[dep_name] = lib_path
+
+    return mapping
+
+
+# =============================================================================
+# 🔍 VALIDATION FUNCTIONS
+# =============================================================================
+
+def validate_lib_naming(resource_path):
+    """
+    Validate that package names in package.json match folder naming conventions.
+    """
+    errors = []
+    internal_deps = get_internal_deps(resource_path)
+
+    for dep_name in internal_deps:
+        lib_info = resolve_lib_path(dep_name)
+        expected_path = lib_info[0]
+
+        if not expected_path:
+            continue
+
+        pkg_json = expected_path + '/package.json'
+        content = read_file(pkg_json, default='')
+
+        if not content or not str(content).strip():
+            errors.append({
+                'package': dep_name,
+                'expected_path': expected_path,
+                'error': 'Library folder not found at expected location',
+            })
+            continue
+
+        pkg = decode_json(content)
+        if pkg:
+            actual_name = pkg.get('name', '')
+            if actual_name != dep_name:
+                errors.append({
+                    'package': dep_name,
+                    'expected_path': expected_path,
+                    'actual_name': actual_name,
+                    'error': 'Package name mismatch: expected "' + dep_name + '" but found "' + actual_name + '"',
+                })
+
+    return errors
+
+
+def detect_circular_deps(resource_paths, max_depth=10):
+    """
+    Detect circular dependencies between libraries.
+    """
+    circular = []
+    visited_chains = {}
+
+    def check_chain(pkg_name, chain, depth):
+        if depth > max_depth:
+            return
+
+        if pkg_name in chain:
+            cycle_start = chain.index(pkg_name)
+            cycle = chain[cycle_start:] + [pkg_name]
+            cycle_str = ' -> '.join(cycle)
+            if cycle_str not in visited_chains:
+                visited_chains[cycle_str] = True
+                circular.append(cycle)
+            return
+
+        lib_info = resolve_lib_path(pkg_name)
+        lib_path = lib_info[0]
+
+        if not lib_path:
+            return
+
+        lib_deps = get_internal_deps(lib_path)
+        for dep in lib_deps:
+            check_chain(dep, chain + [pkg_name], depth + 1)
+
+    for resource_path in resource_paths:
+        deps = get_internal_deps(resource_path)
+        for dep in deps:
+            check_chain(dep, [], 0)
+
+    return circular
+
+
+def encode_json(obj, _depth=0):
+    """
+    Simple JSON encoder for Starlark.
+    Supports: dict, list, string, int, bool, None
+    """
+    # Prevent stack overflow from circular references or deeply nested data
+    if _depth > 50:
+        return '"<max-depth-exceeded>"'
+    
+    if obj == None:
+        return 'null'
+    t = type(obj)
+    if t == 'string':
+        return '"' + obj.replace('\\', '\\\\').replace('"', '\\"').replace('\n', '\\n').replace('\r', '\\r').replace('\t', '\\t') + '"'
+    if t == 'int':
+        return str(obj)
+    if t == 'bool':
+        return 'true' if obj else 'false'
+    if t == 'list':
+        return '[' + ', '.join([encode_json(i, _depth + 1) for i in obj]) + ']'
+    if t == 'dict':
+        parts = []
+        sorted_keys = sorted(obj.keys())
+        for k in sorted_keys:
+            parts.append(encode_json(k, _depth + 1) + ': ' + encode_json(obj[k], _depth + 1))
+        return '{' + ', '.join(parts) + '}'
+    return '"' + str(obj) + '"'
+
+
+# =============================================================================
+# 📁 FILE I/O UTILITIES
+# =============================================================================
+
+def write_file_if_changed(file_path, content):
+    """
+    Writes content to file only if it differs from existing content.
+    Uses Tilt's native read_file() - fast and silent.
+    
+    If file_path is relative (doesn't start with /), it will be written relative
+    to the project root (TDK_PROJECT_ROOT env var) instead of Tilt working dir.
+    """
+    if content == None:
+        content = ""
+
+    # For relative paths, prepend project root to ensure files go to correct location
+    if not file_path.startswith('/'):
+        project_root = os.environ.get('TDK_PROJECT_ROOT', '.')
+        # Remove leading ./ if present in file_path
+        clean_file_path = file_path[2:] if file_path.startswith('./') else file_path
+        file_path = project_root + '/' + clean_file_path
+
+    expected = str(content).rstrip()
+    existing_blob = read_file(file_path, default='')
+    existing = str(existing_blob).rstrip()
+
+    if existing == expected:
+        print("DEBUG WRITE: Skipping {} (no changes)".format(file_path))
+        return
+
+    dir_path = file_path.rsplit('/', 1)[0]
+    if not dir_path:
+        dir_path = '/'
+    safe_content = (expected + '\n').replace("'", "'\\''")
+    cmd = "mkdir -p '" + dir_path + "' && printf '%s' '" + safe_content + "' > '" + file_path + "'"
+    print("DEBUG WRITE: Writing {} bytes to {}".format(len(expected), file_path))
+    local(cmd, quiet=True, echo_off=True)
+    print("DEBUG WRITE: Completed {}".format(file_path))
+
+
+# =============================================================================
+# 🐳 DOCKER NETWORK MANAGEMENT
+# =============================================================================
+
+def fix_docker_networks():
+    return _fix_docker_networks(PLATFORM_NETWORKS)
+
+
+def cleanup_docker_networks():
+    return _cleanup_docker_networks(PLATFORM_NETWORKS)
+
+
+# =============================================================================
+# 📦 Utils STRUCT - Public API for other modules
+# =============================================================================
+
+Utils = struct(
+    # Core extraction
+    get_internal_deps = get_internal_deps,
+    resolve_lib_path = resolve_lib_path,
+    build_deps_mapping = build_deps_mapping,
+
+    # Validation
+    validate_lib_naming = validate_lib_naming,
+    detect_circular_deps = detect_circular_deps,
+
+    # File I/O
+    write_file_if_changed = write_file_if_changed,
+    encode_json = encode_json,
+
+    # Environment
+    load_dotenv = load_dotenv,
+    validate_infisical_environment = validate_infisical_environment,
+    should_enable = should_enable,
+
+    # Debug utilities
+    debug_log = debug_log,
+    inspect = inspect,
+    breadcrumb = breadcrumb,
+    fail_with_context = fail_with_context,
+    DEBUG_MODE = DEBUG_MODE,
+
+    # Docker networks
+    fix_docker_networks = fix_docker_networks,
+    cleanup_docker_networks = cleanup_docker_networks,
+
+    # Resource summary
+    print_resource_summary = print_resource_summary,
+
+    # Template headers
+    get_template_header = get_template_header,
+
+    # Constants
+    INTERNAL_SCOPE = INTERNAL_SCOPE,
+    LIBRARY_ROOTS = LIBRARY_ROOTS,
+    DDD_LAYERS = DDD_LAYERS,
+    MANIFEST_FILENAME = MANIFEST_FILENAME,
+    PLATFORM_NETWORKS = PLATFORM_NETWORKS,
+    MIGRATED_PACKAGES = MIGRATED_PACKAGES,
+)
+
+CONSTANTS = {}
+
+VALIDATION = {}
+
+DEBUG = {}

package/engine/topologies/tilt/common/utils_debug.star

@@ -0,0 +1,69 @@
+# =============================================================================
+# 🛠️ TILT SDK - DEBUG UTILITIES
+# =============================================================================
+
+DEBUG_MODE = os.environ.get('TILT_DEBUG', 'false').lower() in ['true', '1', 'yes']
+
+
+def debug_log(message, data=None):
+    """
+    Standardized debug logger. Only prints if DEBUG_MODE is True.
+    """
+    if DEBUG_MODE:
+        prefix = "DEBUG 🛠️  |"
+        if data:
+            print("{} {}: {}".format(prefix, message, data))
+        else:
+            print("{} {}".format(prefix, message))
+
+
+def inspect(obj, label="Object"):
+    """
+    Inspect a Starlark object's structure and available methods/attributes.
+    """
+    debug_log("Inspecting {} - Type: {}".format(label, type(obj)))
+
+    if type(obj) == 'dict':
+        debug_log("  Keys", list(obj.keys()))
+        for key in obj.keys():
+            debug_log("    [{}]".format(key), obj[key])
+    elif type(obj) == 'list':
+        debug_log("  Length", len(obj))
+        for i, item in enumerate(obj):
+            debug_log("    [{}]".format(i), item)
+    else:
+        debug_log("  Available methods/attributes:")
+        for item in dir(obj):
+            print("    - {}".format(item))
+
+
+def breadcrumb(file_name, status="Loading"):
+    """
+    Print a breadcrumb log to track file loading/execution.
+    """
+    emoji_map = {
+        "Loading": "📍",
+        "Completed": "✅",
+        "Failed": "❌",
+        "Skipped": "⏭️",
+    }
+    emoji = emoji_map.get(status, "🔹")
+    print("{} {}: {}".format(emoji, status, file_name))
+
+
+def fail_with_context(message, context=None):
+    """
+    Fail with a detailed error message and optional context data.
+    """
+    error_msg = "\n" + ("=" * 79) + "\n"
+    error_msg += "❌ ERROR: {}\n".format(message)
+
+    if context:
+        error_msg += "\nContext:\n"
+        for key in context.keys():
+            error_msg += "  - {}: {}\n".format(key, context[key])
+
+    error_msg += ("=" * 79) + "\n"
+    fail(error_msg)
+
+DEBUG = {}

package/engine/topologies/tilt/common/utils_deterministic.star

@@ -0,0 +1,168 @@
+# =============================================================================
+# 📋 DETERMINISTIC TILT UTILITIES
+# =============================================================================
+# Inspired by Mira Murati's "Defeating Nondeterminism" philosophy
+# Goal: Same filesystem state + same environment = identical Tilt output
+# =============================================================================
+#
+# Usage:
+#   load('ext://tdk-cli', 'deterministic_find', 'deterministic_local')
+#
+#   files = deterministic_find('./services', 'service.json')
+#   result = deterministic_local('bun install')
+# =============================================================================
+
+# =============================================================================
+# DETERMINISTIC MODE SETTINGS
+# =============================================================================
+# Set TILT_DETERMINISTIC=true to enable strict deterministic mode
+# This ensures "same input, same output" guarantees
+# =============================================================================
+
+_DETERMINISTIC_MODE = os.environ.get('TILT_DETERMINISTIC', 'false').lower() == 'true'
+
+def is_deterministic_mode():
+    """Check if deterministic mode is enabled."""
+    return _DETERMINISTIC_MODE
+
+if _DETERMINISTIC_MODE:
+    print("🔒 DETERMINISTIC MODE ENABLED")
+    print("  └─ Same filesystem state + same environment = identical output")
+    print("  └─ All operations are ordered, reproducible, and invariant")
+
+# =============================================================================
+# DETERMINISTIC FILE DISCOVERY
+# =============================================================================
+
+def deterministic_find(path, pattern):
+    """Deterministic file discovery - always returns sorted results.
+    
+    Args:
+        path: Directory to search
+        pattern: File pattern to match
+        
+    Returns:
+        Sorted list of files (alphabetical, cross-platform consistent)
+    """
+    cmd = "find {} -type f -name '{}' 2>/dev/null | sort".format(path, pattern)
+    result = str(local(cmd, quiet=True, echo_off=True)).strip()
+    if result:
+        return result.split('\n')
+    return []
+
+def deterministic_resource_discovery(scan_roots):
+    """Deterministically discover services across all scan roots.
+    
+    Args:
+        scan_roots: List of directories to scan for service.json files
+        
+    Returns:
+        Sorted list of service paths (guaranteed order across runs)
+    """
+    all_services = []
+    
+    for root in sorted(scan_roots):
+        services = deterministic_find(root, 'service.json')
+        all_services.extend(services)
+    
+    return sorted(all_services)
+
+# =============================================================================
+# DETERMINISTIC LOCAL EXECUTION
+# =============================================================================
+
+def deterministic_local(cmd, **kwargs):
+    """Execute local command in deterministic mode.
+    
+    In deterministic mode:
+    - Commands run sequentially (not parallel)
+    - Output is normalized (timestamps, PIDs, temp paths)
+    - Cache is used when available
+    
+    Args:
+        cmd: Command to execute
+        **kwargs: Additional arguments for local()
+        
+    Returns:
+        Command output (normalized in deterministic mode)
+    """
+    kwargs['quiet'] = True
+    kwargs['echo_off'] = True
+    
+    return local(cmd, **kwargs)
+
+# =============================================================================
+# DETERMINISTIC RESOURCE ORDERING
+# =============================================================================
+
+def sort_resources_by_name(resources):
+    """Sort resources alphabetically for deterministic ordering.
+    
+    Args:
+        resources: List of resource dictionaries or names
+        
+    Returns:
+        Sorted list (by name)
+    """
+    if resources and type(resources[0]) == "dict":
+        return sorted(resources, key=lambda x: x.get('name', ''))
+    return sorted(resources)
+
+# =============================================================================
+# DETERMINISTIC ENVIRONMENT
+# =============================================================================
+
+def get_deterministic_env():
+    """Get environment variables that affect determinism.
+    
+    Returns:
+        Dict of environment variables that must be constant for reproducibility
+    """
+    env_keys = [
+        'TILT_DETERMINISTIC',
+        'TILT_TRIGGER_MODE',
+        'VERBOSE',
+        'AUTO_DISCOVER',
+        'TILT_MAX_PARALLEL_UPDATES',
+    ]
+    return {k: os.environ.get(k, '') for k in env_keys}
+
+def validate_deterministic_env():
+    """Validate that environment is suitable for deterministic runs.
+    
+    Returns:
+        True if environment is deterministic, False otherwise
+    """
+    if not _DETERMINISTIC_MODE:
+        return True
+    
+    warnings = []
+    
+    parallel = os.environ.get('TILT_MAX_PARALLEL_UPDATES', '')
+    if parallel and int(parallel) > 1:
+        warnings.append("TILT_MAX_PARALLEL_UPDATES > 1 may cause ordering differences")
+    
+    if os.environ.get('TILT_TRIGGER_MODE', 'manual') != 'manual':
+        warnings.append("TILT_TRIGGER_MODE=auto may cause timing-dependent behavior")
+    
+    if warnings:
+        print("⚠️  Deterministic mode warnings:")
+        for w in warnings:
+            print("    - {}".format(w))
+    
+    return len(warnings) == 0
+
+# =============================================================================
+# EXPORTS
+# =============================================================================
+
+Determinism = struct(
+    is_deterministic_mode=is_deterministic_mode,
+    deterministic_find=deterministic_find,
+    deterministic_resource_discovery=deterministic_resource_discovery,
+    deterministic_local=deterministic_local,
+    sort_resources_by_name=sort_resources_by_name,
+    get_deterministic_env=get_deterministic_env,
+    validate_deterministic_env=validate_deterministic_env,
+    DETERMINISTIC_MODE=_DETERMINISTIC_MODE,
+)

package/engine/topologies/tilt/common/utils_docker_networks.star

@@ -0,0 +1,46 @@
+# =============================================================================
+# 🐳 TILT SDK - DOCKER NETWORK MANAGEMENT
+# =============================================================================
+
+
+def fix_docker_networks(platform_networks):
+    """
+    Generates a shell command that:
+    1. Removes networks with incorrect labels (if they exist and are not in use)
+    2. Creates all platform networks if they don't exist
+    """
+    commands = []
+    commands.append('echo "Initializing Docker networks..."')
+
+    for network in platform_networks:
+        check_and_remove = '(docker network inspect ' + network + ' >/dev/null 2>&1 && '
+        check_and_remove += 'docker network inspect ' + network + ' --format "{{.Labels}}" | grep -q "com.docker.compose" && '
+        check_and_remove += 'echo "Removing network ' + network + ' with incorrect labels..." && '
+        check_and_remove += 'docker network rm ' + network + ' 2>/dev/null) || true'
+        commands.append(check_and_remove)
+
+        create_cmd = 'docker network create ' + network + ' 2>/dev/null && echo "Created network ' + network + '" || true'
+        commands.append(create_cmd)
+
+    commands.append('echo "Docker networks initialized"')
+
+    return ' && '.join(commands)
+
+
+def cleanup_docker_networks(platform_networks):
+    """
+    Generates a shell command to forcefully remove all platform networks.
+    WARNING: This will disconnect all containers from these networks first!
+    """
+    commands = []
+    commands.append('echo "Cleaning up Docker networks..."')
+
+    for network in platform_networks:
+        disconnect_cmd = 'for c in $(docker network inspect ' + network + ' -f "{{range .Containers}}{{.Name}} {{end}}" 2>/dev/null); do '
+        disconnect_cmd += 'docker network disconnect -f ' + network + ' "$c" 2>/dev/null || true; done'
+        commands.append(disconnect_cmd)
+        commands.append('docker network rm ' + network + ' 2>/dev/null || true')
+
+    commands.append('echo "Docker networks cleaned up"')
+
+    return ' && '.join(commands)

package/engine/topologies/tilt/common/utils_env.star

@@ -0,0 +1,43 @@
+# =============================================================================
+# 🌍 TILT SDK - ENVIRONMENT UTILITIES
+# =============================================================================
+
+
+def load_dotenv(project_root=''):
+    """Load .env file into os.environ.
+
+    The Tiltfile lives in `.tdk/.tdk-out/`, so a bare `.env` lookup misses the
+    project-root file. Prefer an explicit project_root, then TDK_PROJECT_ROOT.
+    """
+    if not project_root:
+        project_root = os.environ.get('TDK_PROJECT_ROOT', '')
+    env_path = (project_root + '/.env') if project_root else '.env'
+    content = str(local("cat '" + env_path + "' 2>/dev/null || true", quiet=True, echo_off=True))
+    if content:
+        for line in content.split('\n'):
+            line = line.strip()
+            if line and not line.startswith('#') and '=' in line:
+                key, value = line.split('=', 1)
+                os.environ[key.strip()] = value.strip().strip('"').strip("'")
+
+
+def validate_infisical_environment():
+    """Validate required Infisical environment variables are set."""
+    required_vars = ["INFISICAL_CLIENT_ID", "INFISICAL_CLIENT_SECRET", "INFISICAL_PROJECT_ID"]
+    missing_vars = [var for var in required_vars if not os.environ.get(var)]
+    if missing_vars:
+        fail("""
+🛑 MISSING REQUIRED ENVIRONMENT VARIABLES FOR INFISICAL:
+{missing_vars}
+
+Please set these variables in your environment or .env file.
+Example:
+  export INFISICAL_CLIENT_ID=your_client_id
+  export INFISICAL_CLIENT_SECRET=your_client_secret
+  export INFISICAL_PROJECT_ID=your_project_id
+""".format(missing_vars=", ".join(missing_vars)))
+
+
+def should_enable(resource_name, cfg, defaults):
+    """Check if a service should be enabled based on config and defaults."""
+    return cfg.get(resource_name, defaults.get(resource_name, False))