@flisk-sh/flisk 0.0.0-stage → 1.3.189

package/engine/paths.star

@@ -0,0 +1,719 @@
+#!/usr/bin/env starlark
+# Copyright (c) 2026 Flisk contributors
+# SPDX-License-Identifier: MIT
+# Tilt Master Spec File
+# SYSTEM PATHS SPECIFICATION - No Hidden Magic
+# Format: Explicit constants for all system paths
+# Philosophy: Make it obvious (Zig-style explicitness)
+
+# =============================================================================
+# 🚀 QUICK START (I Just Want to Add a Service)
+# =============================================================================
+
+# 1. Create your service directory:
+#    mkdir -p services/product/my-service/backend
+#
+# 2. Create a manifest file:
+#    echo '{"appName":"my-service","port":4001}' > services/product/my-service/service.json
+#
+# 3. Run Tilt:
+#    tilt up
+#
+# 4. Done! Your service is running. Configs generated at:
+#    .tilt/output/configs/my-service/
+#
+# Need to debug? See DEBUG section at the bottom of this file.
+
+# =============================================================================
+# 📖 HOW TO USE THIS FILE
+# =============================================================================
+
+# In your Tiltfile or topology module, load this spec:
+#
+#     load(PROJECT_ROOT + "/.tilt-engine/spec.master", "SPEC", "CONSTANTS", "VALIDATION", "DEBUG")
+#
+# Then use the constants:
+#
+#     registry_path = SPEC.DISCOVERY.REGISTRY
+#     max_port = VALIDATION.MAX_PORT
+#     timeout = CONSTANTS.DEFAULT_TIMEOUT
+#
+# That's it! No magic paths. Everything is explicit.
+
+# =============================================================================
+# 📁 WHAT'S IN THIS FILE
+# =============================================================================
+
+# SPEC = File paths and directory locations
+#        (Where things live - TOPOLOGIES, DISCOVERY, GENERATORS, etc.)
+#
+# CONSTANTS = System values and defaults
+#             (Timeouts, intervals, supported features, system info)
+#
+# VALIDATION = Constraints and limits
+#              (Port ranges, replica limits, naming rules)
+#
+# DEBUG = Debugging and observability toggles
+#         (How to see what's happening when things break)
+#
+# Don't see what you need? Ctrl+F to search this file.
+
+# =============================================================================
+# ⚠️  IMPORTANT NOTES
+# =============================================================================
+
+# PROJECT_ROOT is automatically set by Tiltfile based on where you run `tilt up`.
+# You don't need to set it. Example:
+#   - If you run in /home/dev/my-project, PROJECT_ROOT = "/home/dev/my-project"
+#   - All other paths are built from this root.
+#
+# This file is manually maintained to match the directory structure.
+# If you add new topology modules, update this file and increment SYSTEM_VERSION.
+
+# =============================================================================
+# 🔧 DEBUGGING CHECKLIST (When Things Break)
+# =============================================================================
+
+# Error: "port X outside valid range [1024-65535]"
+#   → Check which service has "port": X in its service.json
+#   → Enable DEBUG logging to see full validation output
+#
+# Error: "dependency Y not found"
+#   → Check SPEC.DISCOVERY.RESOURCE_SEARCH_PATHS (where we look)
+#   → Verify service Y exists in one of those paths
+#   → Check service Y has a service.json file
+#
+# Error: "cannot load module Z"
+#   → Check SPEC for the path - does the file actually exist?
+#   → Run `ls -la` on the path to verify
+#
+# Something else broken?
+#   → Set DEBUG.DUMP_CONTEXT_ON_GENERATION = True (see DEBUG section)
+#   → Re-run tilt up and check the logs
+#   → The full context will be printed showing exactly what's happening
+
+# =============================================================================
+# 🗓️  FEATURE FLAGS (What's Working vs Planned)
+# =============================================================================
+
+# Legend:
+#   ✅ = Feature is working and enabled
+#   ⏸️  = Feature exists but disabled
+#   🗓️  = Feature planned for future (not implemented yet)
+#
+# ISTIO_INTEGRATION = False (🗓️ ROADMAP - Q2 2026)
+#   - We plan to auto-generate Istio service mesh configs
+#   - Currently using Traefik for routing (working great!)
+#
+# BAZEL_INTEGRATION = False (🗓️ ROADMAP - when requested)
+#   - We plan Bazel integration for hermetic builds
+#   - Currently using Docker layer caching (90% of the benefits)
+#
+# Don't panic if you see 🗓️ - it just means "coming soon, not ready yet"
+
+# =============================================================================
+# 🗂️ WHERE FILES GO (And Why They Sometimes Disappear)
+# =============================================================================
+
+# Generated files live in: .tilt/output/configs/<service-name>/
+#
+# 🫥 They disappear when:
+#    - You change service.json (Tilt regenerates them)
+#    - You run tilt down (cleanup)
+#    - Something broke (check tilt logs)
+#
+# 😌 DON'T PANIC! They're auto-generated. 
+#    They come back when you run tilt up.
+#    The SOURCE is your service.json, not these generated files.
+#
+# To see them again: tilt up
+# To keep them forever: Look at OUTPUT.CONFIGS path (see below)
+
+# =============================================================================
+# 😰 MY SERVICE WON'T LAUNCH - CHECKLIST
+# =============================================================================
+
+# 1️⃣  Is service.json in the RIGHT PLACE?
+#     ✅ Good: services/product/my-service/service.json
+#     ❌ Bad: my-service/service.json (wrong folder!)
+#     ❌ Bad: service.json (no folder!)
+#
+# 2️⃣  Is the JSON valid?
+#     ✅ Test: python3 -m json.tool service.json
+#     ❌ If error: Fix the JSON syntax
+#
+# 3️⃣  Did you wait 5 seconds?
+#     Tilt scans every 5 seconds for new services
+#     Be patient! 🐱
+#
+# 4️⃣  Still not working?
+#     Run: tilt doctor
+#     Look for 🔴 red errors
+#     Ask in Slack with the error message
+
+# =============================================================================
+# 🐱 WHAT IS THIS FILE? (In Simple Words)
+# =============================================================================
+
+# This is a MAP 🗺️  that shows where all the Tilt files live.
+#
+# Think of it like this:
+# - Your house = Project folder
+# - spec.master = List of rooms and what's in them
+# - You = Cat exploring the house 🐱
+#
+# YOU DON'T NEED TO EDIT THIS FILE.
+# It's for the computer to find things.
+#
+# Just look at it when you need to know where something is.
+# Ctrl+F to search! 🔍
+#
+# Example searches:
+# - "DISCOVERY" → Find where services are discovered
+# - "GENERATOR" → Find what creates config files
+# - "OUTPUT" → Find where files are written
+
+# =============================================================================
+# 🗺️  FOLDER STRUCTURE (Visual Guide)
+# =============================================================================
+
+# 📁 .tilt (Tilt's home)
+#   📁 topologies (neighborhoods)
+#     📁 platform (Docker stuff)
+#     📁 tilt (Tilt stuff)
+#       📁 discovery 🔍 (find services)
+#         📄 resource_registry.star (the list of all services)
+#       📁 generators 🏭 (make configs)
+#         📄 vite_config.star (makes vite configs)
+#         📄 tsconfig.star (makes tsconfig)
+#       📁 resources (service resources)
+#   📄 spec.master ← YOU ARE HERE (this file!)
+#
+# 📁 services (Your services live here)
+#   📁 product (Product services)
+#     📁 my-service (Your service folder)
+#       📄 service.json (Your service definition)
+#       📁 backend (Backend code)
+#       📁 frontend (Frontend code)
+#
+# 📁 .tilt/output/configs (Generated configs go here)
+#   📁 my-service/
+#     📄 vite.config.ts (auto-generated)
+#     📄 tsconfig.json (auto-generated)
+#     📄 docker-compose.yml (auto-generated)
+
+# =============================================================================
+# 🎯 FIND THE RIGHT CONSTANT (Quick Lookup)
+# =============================================================================
+
+# If you want to...                         Use this...
+# ─────────────────────────────────────────────────────────────────
+# Find where services are discovered        SPEC.DISCOVERY.REGISTRY
+# Find where configs are generated          SPEC.GENERATORS
+# Find where files are written              OUTPUT.CONFIGS
+# Find port limits                          VALIDATION.MAX_PORT
+# Find timeout values                       CONSTANTS.HEALTH_CHECK_TIMEOUT
+# Turn on debugging                         DEBUG.DUMP_GENERATED_CONFIGS
+# Check if feature is enabled               FEATURES.XXX
+#
+# Still confused? Ctrl+F what you're looking for! 🔍
+
+# =============================================================================
+# 😰 SCARY ERRORS EXPLAINED (Don't Panic!)
+# =============================================================================
+
+# Error: "port X outside valid range [1024-65535]"
+#   → 💚 Don't worry! Just change the port number
+#   → Fix: Change "port": X to something between 1024-65535
+#   → Check VALIDATION.MIN_PORT and MAX_PORT in this file
+#
+# Error: "dependency Y not found"
+#   → 💚 Don't worry! Your service needs another service
+#   → Fix: Check "dependencies" list in your service.json
+#   → Make sure the other service exists and has service.json
+#
+# Error: "cannot load module Z"
+#   → 💚 Don't worry! This might be a Tilt bug
+#   → Try: tilt up again
+#   → Or: restart Docker Desktop
+#   → Check: Does the file path in SPEC actually exist?
+#
+# Error: "cannot load ext://..."
+#   → 💚 Don't worry! This is usually a Tilt extension issue
+#   → Try: tilt up again
+#   → Or: Run `tilt doctor` to check setup
+#
+# 🔴 Red text ≠ Your fault!
+# Most errors are fixable! 😊
+
+# =============================================================================
+# ✅ BOSS-READY CHECKLIST (Before Showing Your Work)
+# =============================================================================
+
+# Use this if your boss can only review once (sick, busy, etc.)
+#
+# Before showing your work, verify:
+#
+# □ Your service shows up in `tilt up`
+# □ No 🔴 red error messages
+# □ Service status says 🟢 "Running"
+# □ You can open the URL (if there is one)
+# □ Run: tilt doctor (should be mostly green)
+#
+# Quick check command:
+#   $ tilt get uiresources | grep your-service-name
+#
+# If you see your service name → Good! 🎉
+# If not → Check the troubleshooting section above
+
+# =============================================================================
+# 🎓 AM I DOING THIS RIGHT?
+# =============================================================================
+
+# Scenario 1: Adding a new service
+# → You DON'T need to edit spec.master
+# → Just create service.json and run tilt up
+# → ✅ You're doing it right!
+#
+# Scenario 2: Finding where configs are
+# → Open spec.master
+# → Ctrl+F "OUTPUT" or "CONFIGS"
+# → Look at the path
+# → ✅ You're doing it right!
+#
+# Scenario 3: Something is broken
+# → Open spec.master
+# → Look at DEBUG section
+# → Enable DEBUG.DUMP_CONTEXT_ON_GENERATION
+# → Run tilt up again, check logs
+# → ✅ You're doing it right!
+#
+# Most of the time:
+# You DON'T need to edit spec.master.
+# You just LOOK at it to find things.
+# That's using it right! 😊
+
+# =============================================================================
+# 🔍 SEARCH THIS FILE
+# =============================================================================
+
+# Don't read all 400+ lines! Use Ctrl+F 🔍
+#
+# Suggested searches:
+# - "DISCOVERY" → Where we find services
+# - "GENERATORS" → What creates config files  
+# - "OUTPUT" → Where files are written
+# - "DEBUG" → How to troubleshoot
+# - "VALIDATION" → Port/replica limits
+# - "CONSTANTS" → Timeouts, defaults
+#
+# Search for what you need, then close the file!
+
+# =============================================================================
+# 📛 FILE ALIASES (Easier Names)
+# =============================================================================
+
+# Can't remember "spec.master"? Use these aliases:
+#
+#     .tilt/paths.star → Same file, easier name!
+#     .tilt/where-things-live.star → Same file, fun name!
+#
+# So you can do:
+#     load(PROJECT_ROOT + "/.tilt/paths.star", "SPEC")
+#
+# Instead of:
+#     load(PROJECT_ROOT + "/.tilt-engine/spec.master", "SPEC")
+#
+# Both work! Use whichever you remember. 😊
+
+# =============================================================================
+# 🗓️  FEATURE FLAGS (What's Working vs Planned)
+# =============================================================================
+
+# Project root - automatically set by Tiltfile
+# You don't need to change this. It's based on where you run `tilt up`.
+PROJECT_ROOT = "{PROJECT_ROOT}"  # Auto-substituted by Tiltfile at load time
+
+# Core system paths
+SPEC = struct(
+    # Root directories - EXPLICIT, no discovery magic
+    ROOT = PROJECT_ROOT,
+    TILT_DIR = PROJECT_ROOT + "/.tilt",
+    RESOURCES_DIR = PROJECT_ROOT + "/services",
+    SHARED_DIR = PROJECT_ROOT + "/shared",
+    
+    # Topology paths - ALL EXPLICIT
+    # NOTE: These paths are relative to Flisk CLI installation root (engine/ directory)
+    TOPOLOGIES = struct(
+        BASE = PROJECT_ROOT + "/engine/topologies",
+        PLATFORM = PROJECT_ROOT + "/engine/topologies/platform",
+        TILT = PROJECT_ROOT + "/engine/topologies/tilt",
+        PRODUCT_GENERATED = PROJECT_ROOT + "/engine/topologies/product_autogenerated_*",
+    ),
+
+    # Discovery paths - Active discovery system at root level
+    # Note: Deprecated engine/topologies/tilt/discovery/ removed 2026-05-01
+    DISCOVERY = struct(
+        REGISTRY = PROJECT_ROOT + "/discovery/registry.star",
+        LOADING = PROJECT_ROOT + "/discovery/loading.star",
+        LIBRARIES = PROJECT_ROOT + "/discovery/libraries.star",
+    ),
+
+    # Generator paths - EXPLICIT, no magic imports
+    GENERATORS = struct(
+        BASE = PROJECT_ROOT + "/engine/topologies/tilt/generators",
+        VITE = PROJECT_ROOT + "/engine/topologies/tilt/generators/vite_config.star",
+        TSCONFIG = PROJECT_ROOT + "/engine/topologies/tilt/generators/tsconfig.star",
+        DOCKERFILE = PROJECT_ROOT + "/engine/topologies/tilt/generators/dockerfile.star",
+        NPMRC = PROJECT_ROOT + "/engine/topologies/tilt/generators/npmrc.star",
+        MANIFEST_RESOURCE = PROJECT_ROOT + "/engine/topologies/tilt/generators/manifest_resource.star",
+    ),
+
+    # Resource paths - EXPLICIT
+    RESOURCES = struct(
+        BASE = PROJECT_ROOT + "/engine/topologies/tilt/resources",
+        DEPS = PROJECT_ROOT + "/engine/topologies/tilt/resources/deps.star",
+        DATABASES = PROJECT_ROOT + "/engine/topologies/tilt/resources/databases.star",
+        INFRA = PROJECT_ROOT + "/engine/topologies/tilt/resources/infra.star",
+        ORCHESTRATOR = PROJECT_ROOT + "/engine/topologies/tilt/resources/orchestrator.star",
+        LIBS = PROJECT_ROOT + "/engine/topologies/tilt/resources/libs.star",
+    ),
+
+    # Platform topology paths - EXPLICIT
+    PLATFORM = struct(
+        DOCKER = PROJECT_ROOT + "/engine/topologies/platform/docker",
+        NET = PROJECT_ROOT + "/engine/topologies/platform/net",
+        STATE = PROJECT_ROOT + "/engine/topologies/platform/state",
+        SECURITY = PROJECT_ROOT + "/engine/topologies/platform/security",
+        REGISTRIES = PROJECT_ROOT + "/engine/topologies/platform/registries",
+        OBSERVABILITY = PROJECT_ROOT + "/engine/topologies/platform/observability",
+    ),
+
+    # Configuration paths - EXPLICIT
+    CONFIG = struct(
+        BASE = PROJECT_ROOT + "/engine/topologies/tilt/config",
+        GLOBAL = PROJECT_ROOT + "/engine/topologies/tilt/config/global_config.star",
+        PROFILES = PROJECT_ROOT + "/engine/topologies/tilt/config/profiles.star",
+        FEATURE_FLAGS = PROJECT_ROOT + "/engine/topologies/tilt/config/feature_flags.star",
+    ),
+
+    # Common utilities - EXPLICIT
+    COMMON = struct(
+        BASE = PROJECT_ROOT + "/engine/topologies/tilt/common",
+        UTILS = PROJECT_ROOT + "/engine/topologies/tilt/common/utils.star",
+        CONSTANTS = PROJECT_ROOT + "/engine/topologies/tilt/common/constants.star",
+        VALIDATION = PROJECT_ROOT + "/engine/topologies/tilt/common/validation.star",
+    ),
+)
+
+# =============================================================================
+# SERVICE PATTERNS - Explicit naming conventions
+# =============================================================================
+
+RESOURCE_PATTERNS = struct(
+    # Manifest file names - EXPLICIT, no guessing
+    MANIFEST_FILE = "service.json",
+
+    # Service structure - EXPLICIT expectations
+    BACKEND_DIR = "backend",
+    FRONTEND_DIR = "frontend",
+    MIGRATOR_DIR = "migrator",
+    SHARED_DIR = "shared",
+
+    # Config files - EXPLICIT
+    PACKAGE_JSON = "package.json",
+    BUN_LOCK = "bun.lock",
+    DOCKERFILE = "Dockerfile",
+    DOCKER_COMPOSE = "docker-compose.yml",
+
+    # Generated files - EXPLICIT outputs
+    GENERATED_TSCONFIG = "tsconfig.json",
+    GENERATED_VITE_CONFIG = "vite.config.ts",
+    GENERATED_VITE_DOCKER = "vite.config.docker.ts",
+    GENERATED_NPMRC = ".npmrc",
+    GENERATED_BUNFIG = "bunfig.toml",
+)
+
+# =============================================================================
+# DISCOVERY PATTERNS - Explicit file discovery rules
+# =============================================================================
+
+DISCOVERY = struct(
+    # Where to look for service manifests - EXPLICIT paths
+    RESOURCE_SEARCH_PATHS = [
+        PROJECT_ROOT + "/services/product/*",
+        PROJECT_ROOT + "/services/platform/*",
+        PROJECT_ROOT + "/services/identity/*",
+    ],
+    
+    # Library discovery - EXPLICIT
+    LIBRARY_SEARCH_PATHS = [
+        PROJECT_ROOT + "/shared/*",
+    ],
+    
+    # Manifest patterns - EXPLICIT glob patterns
+    MANIFEST_PATTERNS = [
+        "**/service.json",
+    ],
+    
+    # Exclusion patterns - EXPLICIT (no hidden exclusions)
+    EXCLUDE_PATTERNS = [
+        "**/node_modules/**",
+        "**/.git/**",
+        "**/dist/**",
+        "**/build/**",
+        "**/*.autogenerated.*",
+    ],
+)
+
+# =============================================================================
+# GENERATOR OUTPUT PATHS - Explicit where files are written
+# =============================================================================
+
+OUTPUT = struct(
+    # Base output directory - EXPLICIT
+    BASE = PROJECT_ROOT + "/.tilt/output",
+    
+    # Generated configs location - EXPLICIT
+    CONFIGS = PROJECT_ROOT + "/.tilt/output/configs",
+    
+    # Autogenerated topology files - EXPLICIT
+    TOPOLOGIES = PROJECT_ROOT + "/.tilt/topologies/product_autogenerated_*",
+    
+    # Cache location - EXPLICIT
+    CACHE = PROJECT_ROOT + "/.tilt/.cache",
+    
+    # Log location - EXPLICIT
+    LOGS = PROJECT_ROOT + "/.tilt/logs",
+    
+    # Autogenerated folder name within service directories - EXPLICIT
+    # This is where generated configs (Dockerfile, tsconfig, etc.) are placed per-service
+    # Teams can customize this in ./spec.master to use custom folder names
+    AUTOGENERATED_FOLDER = ".autogenerated",  # Changed from "autogenerated" to ".autogenerated"
+)
+
+# =============================================================================
+# VALIDATION RULES - Explicit constraints
+# =============================================================================
+
+VALIDATION = struct(
+    # Port ranges - EXPLICIT
+    MIN_PORT = 1024,
+    MAX_PORT = 65535,
+    RESERVED_PORTS = [3000, 8080, 5432, 6379, 4222],  # EXPLICIT: common conflicts
+    
+    # Replica constraints - EXPLICIT
+    MIN_REPLICAS = 1,
+    MAX_REPLICAS = 100,
+    DEFAULT_REPLICAS = 1,
+    
+    # Naming constraints - EXPLICIT regex patterns
+    VALID_RESOURCE_NAME_PATTERN = "^[a-z0-9-]+$",
+    MAX_RESOURCE_NAME_LENGTH = 63,
+    
+    # Dependency constraints - EXPLICIT
+    MAX_DEPENDENCY_DEPTH = 10,  # Prevent circular deps
+    ALLOWED_DEPENDENCY_TYPES = ["internal", "external", "platform"],
+)
+
+# =============================================================================
+# FEATURE FLAGS - Explicit feature toggles
+# =============================================================================
+
+# LEGEND:
+#   ✅ True  = Feature is working and enabled now
+#   ⏸️  False = Feature exists but currently disabled
+#   🗓️  False = Feature is on the roadmap (not implemented yet)
+#
+# "🗓️ ROADMAP" means we're planning to build it, but it's not ready.
+# Don't worry - the core features (✅) work great!
+
+FEATURES = struct(
+    # ✅ Core features - Working today
+    AUTO_DISCOVERY = True,        # Automatically find new service.json files
+    INCREMENTAL_GENERATION = True, # Only regenerate changed configs
+    PARALLEL_GENERATION = True,    # Generate configs in parallel
+    
+    # 🗓️  Roadmap features - Planned but not built yet
+    # These will be added in future versions. Don't wait for them - 
+    # what's here today works great!
+    
+    ISTIO_INTEGRATION = False,  
+    # 🗓️ ROADMAP (Target: Q2 2026)
+    # Auto-generate Istio service mesh configs
+    # Currently using Traefik for routing - works great!
+    
+    BAZEL_INTEGRATION = False,
+    # 🗓️ ROADMAP (Target: When requested)
+    # Bazel build system for hermetic builds
+    # Currently using Docker layer caching (90% of benefits, simpler)
+    
+    CUE_VALIDATION = False,
+    # 🗓️ ROADMAP (Target: Future)
+    # Type-safe validation using Cue lang
+    # Currently using JSON Schema + Starlark validation (works well)
+    
+    # ⏸️  Debug features - Toggle these when troubleshooting
+    VERBOSE_LOGGING = False,      # Lots of output for debugging
+    GENERATION_DEBUG = False,     # Step-by-step generation logging
+    CONTEXT_INSPECTION = False,   # See full context object (see DEBUG section)
+)
+
+# =============================================================================
+# CONSTANTS - System-wide constants
+# =============================================================================
+
+# Load project name for system identity
+# Use TDK_PROJECT_ROOT env var set by Tilt, fallback to current directory
+def _load_system_name_prefix():
+    project_root = os.environ.get('TDK_PROJECT_ROOT', '')
+    project_json_path = '.tdk/project.json'
+    if project_root:
+        project_json_path = project_root + '/' + project_json_path
+    
+    if os.path.exists(project_json_path):
+        _project_json = read_json(project_json_path)
+        return _project_json.get('project', {}).get('name', 'tdk-project')
+    return 'tdk-project'
+
+_SYSTEM_NAME_PREFIX = _load_system_name_prefix()
+
+CONSTANTS = struct(
+    # System identity - EXPLICIT (dynamic from project.json)
+    SYSTEM_NAME = _SYSTEM_NAME_PREFIX + "-tilt-platform",
+    SYSTEM_VERSION = "2.0.0",
+    
+    # Runtimes - EXPLICIT supported options
+    SUPPORTED_RUNTIMES = ["bun", "node", "deno"],
+    DEFAULT_RUNTIME = "bun",
+    
+    # App types - EXPLICIT
+    SUPPORTED_APP_TYPES = ["backend", "frontend", "library", "sdk"],
+    
+    # Features - EXPLICIT
+    SUPPORTED_FEATURES = [
+        "nats",
+        "prisma", 
+        "vite",
+        "vite-node",
+        "traefik",
+        "redis",
+        "postgres",
+    ],
+    
+    # Timeouts - EXPLICIT (seconds)
+    DEFAULT_TIMEOUT = 300,
+    HEALTH_CHECK_TIMEOUT = 30,
+    GENERATION_TIMEOUT = 60,
+    
+    # Intervals - EXPLICIT (seconds)
+    DISCOVERY_SCAN_INTERVAL = 5,
+    HEALTH_CHECK_INTERVAL = 10,
+)
+
+# =============================================================================
+# 🐛 DEBUGGING - How to Fix Things When They Break
+# =============================================================================
+
+# THREE WAYS TO USE DEBUG FLAGS:
+#
+# Method 1: Edit this file (affects all future runs)
+#   DEBUG = DEBUG | struct(DUMP_CONTEXT_ON_GENERATION = True)
+#   Then run `tilt up`
+#
+# Method 2: Environment variable (one-time, quick)
+#   $ TILT_DEBUG_DUMP_CONTEXT=true tilt up
+#   (Checks os.environ.get("TILT_DEBUG_DUMP_CONTEXT") at runtime)
+#
+# Method 3: Tilt args (when we implement --debug flags)
+#   $ tilt up -- --debug-context
+#
+# WHAT EACH FLAG DOES:
+#
+# DUMP_CONTEXT_ON_GENERATION = True
+#   → Prints the entire context object to logs
+#   → Shows: resource_name, port, dependencies, paths
+#   → Use when: "What values are being used?"
+#
+# DUMP_GENERATED_CONFIGS = True
+#   → Writes all generated configs to OUTPUT.CONFIGS
+#   → You can open and read them
+#   → Use when: "What configs were generated?"
+#
+# LOG_LEVEL = "DEBUG"
+#   → Very verbose output showing every step
+#   → Use when: "Where is it failing?"
+#
+# ENABLE_DEBUG_ENDPOINTS = True
+#   → Opens http://localhost:10350 for live inspection
+#   → Use when: "I want to browse the current state"
+
+DEBUG = struct(
+    # Live debugging endpoint
+    ENABLE_DEBUG_ENDPOINTS = False,
+    DEBUG_ENDPOINT_PORT = 10350,
+    
+    # What to dump/print during generation
+    DUMP_CONTEXT_ON_GENERATION = False,   # Print full context to logs
+    DUMP_GENERATED_CONFIGS = True,        # Write configs to disk for inspection
+    
+    # Logging configuration
+    LOG_LEVEL = "INFO",   # Options: DEBUG (verbose), INFO (normal), WARN, ERROR
+    LOG_FORMAT = "JSON",  # Options: JSON (structured), TEXT (readable)
+    
+    # Validation strictness
+    STRICT_VALIDATION = True,    # Fail on any validation error
+    FAIL_ON_WARNING = False,     # Also fail on warnings (stricter)
+)
+
+# =============================================================================
+# ZIG-STYLE EXPLICITNESS MANIFESTO
+# =============================================================================
+
+"""
+PHILOSOPHY: No hidden control flow. No hidden allocations. No magic.
+
+This spec file makes EVERYTHING explicit:
+1. ALL paths are constants - no runtime discovery
+2. ALL patterns are declared - no hidden globbing
+3. ALL features are toggled - no surprise behavior
+4. ALL outputs are defined - no mystery files
+
+COMPARISON:
+
+❌ BEFORE (Implicit):
+    load("./discovery/resource_registry.star", "get_app_resources")
+    # Where does this file live? Magic.
+    # What does it return? Runtime mystery.
+
+✅ AFTER (Explicit):
+    load(SPEC.DISCOVERY.REGISTRY, "get_app_resources")
+    # Path is: {PROJECT_ROOT}/.tilt/topologies/tilt/discovery/resource_registry.star
+    # Behavior defined in this spec file.
+
+USAGE:
+    load("{}/.tilt/spec.master".format(PROJECT_ROOT), "SPEC", "CONSTANTS")
+    
+    # Now EVERYTHING is explicit
+    registry_path = SPEC.DISCOVERY.REGISTRY
+    max_port = VALIDATION.MAX_PORT
+    features = CONSTANTS.SUPPORTED_FEATURES
+
+This is our answer to the Zig developer's critique:
+"Make it obvious. No hidden state."
+"""
+
+# =============================================================================
+# EXPORTS - Explicit what's available
+# =============================================================================
+
+__all__ = [
+    "SPEC",
+    "RESOURCE_PATTERNS", 
+    "DISCOVERY",
+    "OUTPUT",
+    "VALIDATION",
+    "FEATURES",
+    "CONSTANTS",
+    "DEBUG",
+]