@tdk-landscape/tdk-cli-core 1.3.53 → 1.3.54

package/engine/docs/AUTODISCOVERY_TEST.md

@@ -1,182 +0,0 @@
-# 🧪 Tilt Auto-Discovery Verification Test
-
-## ✅ Zero-Config Resource Discovery
-
-This system implements **manifest-driven auto-discovery** - no hardcoded resource lists!
-
----
-
-## 🚀 The "New Resource" Test
-
-Create a new resource and watch Tilt auto-discover it:
-
-```bash
-# 1️⃣ Create new resource directory
-mkdir -p services/product/billing/billing-backend
-
-# 2️⃣ Add minimal manifest
-cat > services/product/billing/billing-backend/service.json << 'EOF'
-{
-  "appName": "billing-backend",
-  "appType": "backend",
-  "stack": "billing",
-  "port": 4010
-}
-EOF
-
-# 3️⃣ Add package.json
-cat > services/product/billing/billing-backend/package.json << 'EOF'
-{
-  "name": "billing-backend",
-  "version": "1.0.0",
-  "scripts": {
-    "dev": "bun run src/index.ts"
-  }
-}
-EOF
-
-# 4️⃣ Add basic source file
-mkdir -p services/product/billing/billing-backend/src
-cat > services/product/billing/billing-backend/src/index.ts << 'EOF'
-console.log('Billing resource started!');
-EOF
-
-# 5️⃣ Restart Tilt
-tilt down
-tilt up
-
-# ✅ RESULT: billing-backend is auto-discovered!
-# Check Tilt UI at http://localhost:10350
-# You should see "billing-backend" in the resource list
-```
-
----
-
-## 🧹 The "Ghost" Test (Cleanup Verification)
-
-```bash
-# 1️⃣ Remove the test resource
-rm -rf services/product/billing
-
-# 2️⃣ Restart Tilt
-tilt down
-tilt up
-
-# ✅ RESULT: billing-backend disappears from Tilt UI
-# No stale configurations or errors
-```
-
----
-
-## 📋 Manifest Examples
-
-### Minimal Backend (Convention over Configuration)
-```json
-{
-  "appName": "my-resource-backend",
-  "appType": "backend",
-  "stack": "mystack",
-  "port": 4020
-}
-```
-
-**Auto-generated defaults:**
-- ✅ `databaseName`: `TDK_mystack`
-- ✅ `internalPort`: `3000` (container)
-- ✅ `traefik.host`: `mystack.backend.{project}.local`
-- ✅ `syncs`: `['src', '.npmrc', '.autogenerated/.npmrc.docker.autogenerated', '.autogenerated/bunfig.docker.autogenerated.toml']`
-
-### Backend with Prisma
-```json
-{
-  "appName": "order-backend",
-  "appType": "backend",
-  "stack": "order",
-  "port": 4002,
-  "features": ["nats", "prisma"],
-  "dependsOn": ["identity", "user"]
-}
-```
-
-**Auto-detects:**
-- ✅ Adds `prisma/` to syncs
-- ✅ Enables migrator (`order-db-migrator`)
-- ✅ Creates dependency graph
-
-### Frontend with Backend Proxy
-```json
-{
-  "appName": "user-frontend",
-  "appType": "frontend",
-  "stack": "user",
-  "port": 3001,
-  "backendName": "user-management-backend"
-}
-```
-
-**Auto-generates:**
-- ✅ Vite proxy configuration
-- ✅ Frontend → Backend dependency
-- ✅ HMR port configuration
-
----
-
-## 🔍 Discovery Output
-
-When Tilt starts, you'll see:
-
-```
-🔍 ═══════════════════════════════════════════════════════════════
-🔍  MANIFEST-DRIVEN RESOURCE DISCOVERY
-🔍 ═══════════════════════════════════════════════════════════════
-   📂 Working directory: /private/var/www/2025/ollamar1/tdk/.tilt/core
-   📂 Resources root check: ../../services/product
-   📋 Found 8 manifest files
-   ✅ user-management-backend | backend | Port: 4000 | Stack: user
-   ✅ user-management-frontend | frontend | Port: 3001 | Stack: user
-   ✅ order-management-backend | backend | Port: 4002 | Stack: order
-   ✅ staff-management-backend | backend | Port: 4004 | Stack: staff
-   ✅ identity-management-backend | backend | Port: 4006 | Stack: identity
-   ✅ treatment-management-backend | backend | Port: 4008 | Stack: treatment
-   ✅ inventory-management-backend | backend | Port: 4012 | Stack: inventory
-   ✅ order-planner-backend | backend | Port: 4014 | Stack: order-planner
-🔍 ═══════════════════════════════════════════════════════════════
-   🎯 Discovered 8 stacks with 8 resources
-🔍 ═══════════════════════════════════════════════════════════════
-```
-
----
-
-## 🎯 Key Benefits
-
-1. **Zero Manual Registration**: No hardcoded resource lists
-2. **Convention over Configuration**: Minimal manifest = full resource
-3. **Merge Conflict Free**: No central file to edit
-4. **Self-Documenting**: Filesystem = source of truth
-5. **Smart Defaults**: Port ranges, syncs, dependencies auto-computed
-
----
-
-## 📚 Related Files
-
-- **Discovery Engine**: `.tilt/core/registry.star` (lines 212-638)
-- **Manifest Loader**: `.tilt/core/manifest.star`
-- **Tiltfile Integration**: `Tiltfile` (imports `APP_RESOURCES` from registry)
-
----
-
-## 🔧 Advanced: Custom Discovery Paths
-
-Edit `.tilt/core/registry.star` to scan additional paths:
-
-```starlark
-GLOBAL_CONFIG = {
-    'services_root': '../../services/product',  # Current
-    # Add more roots if needed:
-    # 'additional_roots': ['../../services/internal', '../../services/external']
-}
-```
-
----
-
-**Status**: ✅ Auto-discovery is ACTIVE and working!

package/engine/docs/C4-ARCHITECTURE-operations.md

@@ -1,396 +0,0 @@
-## Detailed Architecture Breakdown
-
-### **Core Layer** (Foundation)
-
-```
-core/
-├── utils.star              # Shared utilities, I/O, validation
-├── manifest.star           # Service manifest loading & Smart Defaults
-├── registry.star           # Single Source of Truth for all services
-└── dependency-sync.star    # Automatic config regeneration
-```
-
-**Responsibilities**:
-- File I/O with change detection
-- JSON manifest parsing & validation
-- Service discovery (auto-scans `services/product/`)
-- Dependency resolution (package names → paths)
-- Network repair utilities
-- Environment validation
-
-**Key Pattern**: Pure functions, no mutable global state (Starlark-safe)
-
----
-
-### **Provider Layer** (Config Generators)
-
-```
-providers/
-├── docker/
-│   ├── layers/
-│   │   ├── l1_base_layers.star       # OS base + runtime env
-│   │   ├── l2_dependency_layers.star # Package manifest + install
-│   │   ├── l3_builder_layers.star    # Compilation stage
-│   │   └── l4_runtime_layers.star    # Final runtime
-│   ├── compose.star                  # docker-compose generation
-│   ├── dockerignore.star             # .dockerignore generation
-│   └── golden-image.star             # Golden image workflow
-├── typescript/
-│   ├── backend_tsconfig.star         # Backend TypeScript config
-│   ├── frontend_tsconfig.star        # Frontend TypeScript config
-│   └── prisma_config.star            # Prisma-specific config
-├── vite.star                         # Vite dev server config
-└── npmrc.star                        # Package registry config
-```
-
-**Responsibilities**:
-- Generate configuration files from manifests
-- Multi-stage Dockerfile orchestration (L1→L2→L3→L4)
-- TypeScript path mapping automation
-- Vite alias synchronization
-- Registry configuration (.npmrc, bunfig.toml)
-
-**Key Innovation**: Layered Docker builds with surgical cache invalidation
-
----
-
-### **Lifecycle Layer** (Orchestration)
-
-```
-lifecycle/
-├── libs.star              # Shared library management
-├── databases.star         # Database virtualization (per-service DBs)
-├── orchestrator.star      # Service coordination & dependencies
-├── infra-loader.star      # Infrastructure provisioning
-└── watchers.star          # File change detection & triggers
-```
-
-**Responsibilities**:
-- Shared library build orchestration
-- Per-service database provisioning (`TDK_{domain}`)
-- Service startup order (via dependency graph)
-- Infrastructure bootstrapping (Postgres, NATS, Traefik)
-- Hot-reload triggers on file changes
-
-**Key Pattern**: Resource dependency graphs ensure correct startup order
-
----
-
-### **Configuration Layer**
-
-```
-config.star               # Global config & Focus Mode
-focus-mode.star           # Service filtering (--focus=user)
-```
-
-**Responsibilities**:
-- CLI argument parsing (`--focus`, `--no-frontend`)
-- Service enablement logic
-- Environment variable loading
-- Context building for all modules
-
----
-
-## Data Flow Diagrams
-
-### **1. Service Discovery Flow**
-
-```mermaid
-graph TD
-    A[Tilt Startup] --> B[Scan services/product/]
-    B --> C{Find manifests}
-    C -->|Found| D[Load JSON]
-    C -->|Not found| E[Skip directory]
-    D --> F[Apply Smart Defaults]
-    F --> G[Validate manifest]
-    G --> H{Valid?}
-    H -->|Yes| I[Add to APP_RESOURCES]
-    H -->|No| J[Log error, skip]
-    I --> K[Generate all configs]
-    K --> L[Create Tilt resources]
-    
-    style A fill:#f9f,stroke:#333,stroke-width:3px
-    style I fill:#9f9,stroke:#333,stroke-width:2px
-    style J fill:#f99,stroke:#333,stroke-width:2px
-```
-
-### **2. Manifest-Driven Config Generation**
-
-```mermaid
-graph LR
-    subgraph "Single Source of Truth"
-        M[service.manifest.json]
-    end
-    
-    subgraph "Generated Configs"
-        D1[Dockerfile.app]
-        D2[Dockerfile.migrator]
-        DC[docker-compose.yml]
-        TS[tsconfig.json]
-        V[vite.config.ts]
-        N[.npmrc]
-        B[bunfig.toml]
-    end
-    
-    M -->|Docker Provider| D1
-    M -->|Docker Provider| D2
-    M -->|Compose Provider| DC
-    M -->|TS Provider| TS
-    M -->|Vite Provider| V
-    M -->|Package Provider| N
-    M -->|Package Provider| B
-    
-    style M fill:#ff9,stroke:#333,stroke-width:4px
-```
-
-### **3. Golden Image Build Strategy**
-
-```mermaid
-graph TB
-    subgraph "One-Time Build"
-        GD[docker/golden.Dockerfile]
-        GB[Golden Image Build]
-        GI[TDK Landscape-base:latest]
-    end
-    
-    subgraph "Per-Service Builds (Fast)"
-        S1[user-backend]
-        S2[order-backend]
-        S3[treatment-backend]
-    end
-    
-    subgraph "Service Dockerfiles"
-        DF1[FROM TDK Landscape-base:latest]
-        DF2[COPY service code]
-        DF3[RUN bun build]
-    end
-    
-    GD --> GB
-    GB --> GI
-    GI --> S1
-    GI --> S2
-    GI --> S3
-    S1 --> DF1
-    DF1 --> DF2
-    DF2 --> DF3
-    
-    style GI fill:#f9f,stroke:#333,stroke-width:4px
-    style DF3 fill:#9f9,stroke:#333,stroke-width:2px
-```
-
----
-
-## Key Design Principles
-
-### **1. Convention over Configuration**
-```
-Package name → Directory path (automatic)
-
-@tdk-landscape/eventing → platform/packages/eventing/src
-@tdk/domain            → shared-ddd-layers/domain/src
-```
-
-### **2. Single Source of Truth**
-```
-service.manifest.json → Everything else
-
-One file defines:
-- Service name, type, domain
-- Port mapping
-- Database name
-- Dependencies
-- Feature flags (prisma, nats, etc.)
-```
-
-### **3. Fail-Fast Validation**
-```
-Checks at tilt up:
-✓ Manifest schema validation
-✓ Circular dependency detection
-✓ Network conflict resolution
-✓ Infisical environment check
-✓ Required secrets present
-```
-
-### **4. Self-Healing Systems**
-```
-Automatic fixes:
-✓ Docker network conflicts → recreate networks
-✓ Bun install cache corruption → retry without cache
-✓ Missing golden image → build automatically
-✓ Dependency changes → regenerate all configs
-```
-
----
-
-## Performance Optimizations
-
-### **Build Time Reduction**
-
-| Strategy | Impact | Implementation |
-|----------|--------|----------------|
-| **Golden images** | 98% faster | Pre-built base layers |
-| **L1-L4 layering** | 5x cache hits | Surgical invalidation |
-| **Parallel builds** | 3x faster | Tilt's concurrent resource loading |
-| **Bun runtime** | 2x faster | vs Node.js |
-| **Multi-stage builds** | 80% smaller images | Production purge layer |
-
-### **Developer Productivity**
-
-| Feature | Time Saved | Comparison |
-|---------|-----------|------------|
-| **Auto-discovery** | 30 min/service | vs manual Tiltfile edits |
-| **Dependency sync** | 10 min/change | vs manual config updates |
-| **Focus mode** | 5 min/restart | vs full stack rebuild |
-| **Healthchecks** | 2 hours/incident | vs blind debugging |
-| **Network auto-repair** | 15 min/conflict | vs manual Docker cleanup |
-
----
-
-## System Boundaries
-
-### **What Tilt Controls**
-✅ Docker image generation  
-✅ Container orchestration  
-✅ Configuration file generation  
-✅ Dependency graph management  
-✅ Local development environment  
-✅ Hot reload triggers  
-
-### **What Tilt Doesn't Control**
-❌ Production deployment  
-❌ Cloud infrastructure  
-❌ Monitoring/observability  
-❌ CI/CD pipelines (that's GitHub Actions)  
-❌ Application business logic  
-
----
-
-## Integration Points
-
-```mermaid
-graph TB
-    subgraph "External Systems"
-        Git[Git Repository]
-        Docker[Docker Engine]
-        Bun[Bun Runtime]
-        Infisical[Infisical Secrets]
-    end
-    
-    subgraph "Tilt Ecosystem"
-        Tiltfile[Tiltfile]
-        SDK[Tilt SDK Modules]
-        Resources[Tilt Resources]
-    end
-    
-    subgraph "Generated Artifacts"
-        Dockerfiles[Auto-generated Dockerfiles]
-        Configs[Auto-generated Configs]
-        Compose[Docker Compose Files]
-    end
-    
-    subgraph "Running System"
-        Containers[Service Containers]
-        Databases[Per-Service DBs]
-        Infrastructure[NATS, Traefik, etc.]
-    end
-    
-    Git -->|watches| Tiltfile
-    Tiltfile -->|loads| SDK
-    SDK -->|generates| Dockerfiles
-    SDK -->|generates| Configs
-    SDK -->|generates| Compose
-    
-    Dockerfiles -->|builds via| Docker
-    Compose -->|orchestrates| Containers
-    
-    Containers -->|connects to| Databases
-    Containers -->|uses| Infrastructure
-    
-    Bun -->|runs in| Containers
-    Infisical -->|provides secrets to| Containers
-    
-    style Tiltfile fill:#f9f,stroke:#333,stroke-width:4px
-    style SDK fill:#9cf,stroke:#333,stroke-width:3px
-    style Containers fill:#9f9,stroke:#333,stroke-width:3px
-```
-
----
-
-## Deployment View
-
-```mermaid
-graph TB
-    subgraph "Developer Machine"
-        Editor[VS Code / Cursor]
-        Git[Git]
-        Tilt[Tilt]
-        Docker[Docker / OrbStack]
-    end
-    
-    subgraph "Tilt SDK (Starlark)"
-        Core[Core Modules]
-        Providers[Config Generators]
-        Lifecycle[Orchestration]
-    end
-    
-    subgraph "Generated Artifacts (Git-ignored)"
-        DF[*.autogenerated Dockerfiles]
-        DC[docker-compose.autogenerated.yml]
-        TS[tsconfig.docker.autogenerated.json]
-    end
-    
-    subgraph "Running Containers"
-        Services[30+ Microservices]
-        DBs[PostgreSQL Instances]
-        Infra[NATS, Traefik, Verdaccio]
-    end
-    
-    Editor -->|edits code| Git
-    Git -->|triggers| Tilt
-    Tilt -->|executes| Core
-    Core --> Providers
-    Providers --> Lifecycle
-    Lifecycle --> DF
-    Lifecycle --> DC
-    Lifecycle --> TS
-    
-    DF -->|builds| Docker
-    DC -->|orchestrates| Docker
-    Docker -->|runs| Services
-    Docker -->|runs| DBs
-    Docker -->|runs| Infra
-    
-    style Editor fill:#bbf,stroke:#333,stroke-width:2px
-    style Tilt fill:#f9f,stroke:#333,stroke-width:4px
-    style Services fill:#9f9,stroke:#333,stroke-width:3px
-```
-
----
-
-## Comparison to Production Architecture
-
-| Aspect | Tilt (Local Dev) | Production |
-|--------|------------------|------------|
-| **Orchestration** | Tilt + Docker Compose | Kubernetes / Cloud Run |
-| **Service Discovery** | Manifest files | Service mesh / DNS |
-| **Config Management** | Auto-generated files | ConfigMaps / Secrets |
-| **Networking** | Docker networks | Cloud VPC / Load balancers |
-| **Databases** | Local Postgres containers | Managed Postgres (Neon/RDS) |
-| **Secrets** | Infisical CLI | Infisical API / Vault |
-| **Observability** | Docker logs + Tilt UI | Prometheus + Grafana + Sentry |
-| **Deployment** | `tilt up` | CI/CD → Cloud deploy |
-
----
-
-## Conclusion
-
-**Tilt SDK Architecture** = 5000+ lines of infrastructure-as-code that:
-
-1. **Eliminates manual toil** (19% of files autogenerated)
-2. **Enforces consistency** (one template → 30 services)
-3. **Enables rapid development** (`git clone && tilt up`)
-4. **Scales horizontally** (manifest discovery = no central file edits)
-5. **Provides escape hatches** (can override any generated config)
-
-**This is enterprise-grade developer tooling** built by one engineer over one year.