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

package/engine/docs/MANIFEST_DRIVEN_ARCHITECTURE.md

@@ -1,357 +0,0 @@
-# Manifest-Driven Architecture Refactor
-
-## 🎯 Problem Statement
-
-**User Request**: "I thought the right way is not just running dozens of generators always. I thought manifest will be autoscanned, then based on manifest it should create tilt resource that will trigger 10 generators for that manifest. So I mean tsconfig gen won't be creating 100 of tsconfigs in one function, it's manifest based not function based."
-
-### The Issue with Bulk Generation
-
-**Before** (`.tilt/provisioner/orchestrator/apply.star` lines 112-251):
-
-```starlark
-# ❌ Bulk generation loops - No per-resource granularity
-for resource in resource_config.get('resources', []):
-    Vite.for_manifest(...)              # Loop 1: ALL vite configs
-
-for resource in resource_config.get('resources', []):
-    Docker.backend(...)                 # Loop 2: ALL dockerfiles
-    
-for resource in resource_config.get('resources', []):
-    TSConfig.backend(...)               # Loop 3: ALL tsconfigs
-    TSConfig.prisma(...)
-    
-for resource in resource_config.get('resources', []):
-    PackageConfig.npmrc(...)            # Loop 4: ALL package configs
-    PackageConfig.bunfig(...)
-
-# Problems:
-# 1. No tracking in Tilt UI (where did this config come from?)
-# 2. Change 1 manifest → regenerate ALL configs (inefficient)
-# 3. No dependency chain (Docker doesn't wait for configs)
-# 4. Can't see which resource is generating what
-```
-
----
-
-## ✅ Solution: Manifest-Driven Resources
-
-### Architecture
-
-**After** (`.tilt/provisioner/orchestrator/apply.star` lines 114-136):
-
-```starlark
-# ✅ Manifest-driven: 1 manifest → 1 Tilt resource → 10 generators
-for resource in resource_config.get('resources', []):
-    manifest = Manifest.load_manifest(resource_path)
-    
-    # Create a VISIBLE Tilt resource for this specific manifest
-    config_gen_resource = ManifestResource.create_config_resource(
-        resource_name,
-        resource,
-        resource_path,
-        manifest,
-        backend_manifest,
-        ctx
-    )
-    
-    # Result: user-management-backend-config-gen
-    # Watches: manifest.json, package.json
-    # Generates: tsconfig, vite, dockerfile, npmrc, bunfig, etc.
-    # Labels: ['config-gen', resource_name]
-```
-
-### New Module: `manifest_resource.star`
-
-**Path**: `.tilt/provisioner/orchestrator/generators/manifest_resource.star`
-
-**Exports**:
-- `ManifestResource.create_config_resource()` - Creates per-manifest Tilt resource
-- `ManifestResource.generate_all_configs()` - Generates all 10+ configs for ONE service
-
-**Key Function**:
-```starlark
-def create_manifest_config_resource(
-    resource_name,
-    resource_config,
-    resource_path,
-    manifest,
-    backend_manifest,
-    ctx
-):
-    """
-    Creates a Tilt local_resource that:
-    1. Generates ALL configs for THIS specific manifest
-    2. Watches manifest.json and package.json
-    3. Shows up in Tilt UI as {resource-name}-config-gen
-    4. Becomes a dependency for the Docker build
-    """
-```
-
----
-
-## 📊 Visual Comparison
-
-### Bulk Generation (Old)
-
-```
-Tilt Orchestrator
-  │
-  ├─ Loop 1: Generate ALL vite configs ────────┐
-  ├─ Loop 2: Generate ALL dockerfiles ─────────┤
-  ├─ Loop 3: Generate ALL tsconfigs ───────────┤ 300+ configs
-  ├─ Loop 4: Generate ALL package configs ─────┤ in 10 loops
-  └─ ... 6 more loops ─────────────────────────┘
-        │
-        └─ Docker builds (no explicit dependency on configs)
-
-❌ Problems:
-  - No visibility (which loop generated which config?)
-  - No granularity (can't track per-service)
-  - No efficiency (change 1 manifest → regenerate ALL)
-```
-
-### Manifest-Driven (New)
-
-```
-Tilt Orchestrator
-  │
-  ├─ user-management-backend
-  │    ├─ user-management-backend-config-gen (Tilt resource)
-  │    │    ├─ Watches: manifest.json, package.json
-  │    │    └─ Generates: tsconfig, vite, dockerfile, npmrc, bunfig...
-  │    └─ user-management-backend (Docker) [depends on config-gen]
-  │
-  ├─ user-management-frontend
-  │    ├─ user-management-frontend-config-gen (Tilt resource)
-  │    │    └─ Generates: 10+ configs
-  │    └─ user-management-frontend (Docker) [depends on config-gen]
-  │
-  └─ identity-management-backend
-       ├─ identity-management-backend-config-gen (Tilt resource)
-       │    └─ Generates: 10+ configs
-       └─ identity-management-backend (Docker) [depends on config-gen]
-
-✅ Benefits:
-  - Full visibility (each resource visible in Tilt UI)
-  - Perfect granularity (per-manifest tracking)
-  - Maximum efficiency (change 1 manifest → regenerate 10 configs for THAT service)
-  - Explicit dependencies (Docker waits for config-gen)
-```
-
----
-
-## 🎨 Tilt UI Example
-
-### Before (Bulk)
-
-```
-📁 user
-  ├─ user-management-backend ✅
-  └─ user-management-frontend ✅
-  
-# ❌ Where are the configs? Who generated them? 
-# No visibility into config generation process.
-```
-
-### After (Manifest-Driven)
-
-```
-📁 config-gen (new label)
-  ├─ user-management-backend-config-gen ✅
-  ├─ user-management-frontend-config-gen ✅
-  ├─ identity-management-backend-config-gen ✅
-  └─ staff-management-backend-config-gen ✅
-
-📁 user
-  ├─ user-management-backend-config-gen ⬆️ (dependency)
-  ├─ user-management-backend ✅ (depends on config-gen)
-  ├─ user-management-frontend-config-gen ⬆️ (dependency)
-  └─ user-management-frontend ✅ (depends on config-gen)
-
-# ✅ Clear hierarchy:
-#   manifest → config-gen → Docker build
-```
-
----
-
-## 🔍 Dependency Chain
-
-### Resource Dependencies (per manifest)
-
-```
-manifest.json  ─┐
-package.json   ─┼─→ {service}-config-gen ───→ {service} (Docker)
-                │    (10+ generators)           (depends on configs)
-                │
-                ├─ tsconfig.json (Docker)
-                ├─ tsconfig.json (local)
-                ├─ vite.config.ts
-                ├─ Dockerfile.app.autogenerated
-                ├─ .dockerignore
-                ├─ .env.autogenerated
-                ├─ .npmrc (Docker)
-                ├─ .npmrc (local)
-                ├─ bunfig.toml (Docker)
-                ├─ bunfig.toml (local)
-                ├─ nginx.conf (if frontend)
-                └─ prisma.config.ts (if backend)
-```
-
-### Full System Dependency Chain
-
-```
-Infrastructure (independent, no runtime dependency between them):
-  golden-image (L1-L4, build-cache optimization only)
-  postgres (database-management)  - Free, on by default
-  verdaccio (npm registry)        - Premium, requires TDK_LICENSE_KEY
-
-Per-Service:
-  manifest.json → {service}-config-gen → {service} (Docker)
-```
-
----
-
-## 📈 Performance & Efficiency
-
-### Update Scenario: Change 1 Manifest
-
-**Before (Bulk)**:
-```
-Change: services/product/user/user-backend/service.json
-Triggers:
-  ├─ Regenerate ALL vite configs (30 services)
-  ├─ Regenerate ALL dockerfiles (30 services)
-  ├─ Regenerate ALL tsconfigs (30 services)
-  └─ Regenerate ALL package configs (30 services)
-  
-Total: 300+ config files regenerated for 1 change
-Time: ~10 seconds
-```
-
-**After (Manifest-Driven)**:
-```
-Change: services/product/user/user-backend/service.json
-Triggers:
-  └─ user-management-backend-config-gen
-      ├─ Regenerate tsconfig.json (2 files)
-      ├─ Regenerate vite.config.ts (1 file)
-      ├─ Regenerate Dockerfile.app.autogenerated (1 file)
-      ├─ Regenerate .npmrc (2 files)
-      └─ Regenerate bunfig.toml (2 files)
-      
-Total: 10 config files regenerated for 1 change
-Time: <1 second
-```
-
----
-
-## 🧪 Verification
-
-### Check Config-Gen Resources Exist
-
-```bash
-cd /workspace/tdk-project
-tilt get uiresources | grep config-gen
-
-# Expected output:
-# user-management-backend-config-gen
-# user-management-frontend-config-gen
-# identity-management-backend-config-gen
-# identity-management-frontend-config-gen
-# staff-management-backend-config-gen
-# staff-management-frontend-config-gen
-```
-
-### Check Resource Dependencies
-
-```bash
-tilt describe uiresource user-management-backend | grep "Depends On"
-
-# Expected: Should depend on user-management-backend-config-gen
-```
-
----
-
-## 📝 Files Changed
-
-### New Files
-
-1. **`.tilt/provisioner/orchestrator/generators/manifest_resource.star`**
-   - 215 lines
-   - Exports: `ManifestResource` struct
-   - Key functions:
-     - `create_config_resource()` - Creates per-manifest Tilt resource
-     - `generate_all_configs()` - Generates 10+ configs for one service
-
-### Modified Files
-
-1. **`.tilt/provisioner/orchestrator/apply.star`**
-   - Lines 22: Added `load('./generators/manifest_resource.star', 'ManifestResource')`
-   - Lines 91-136: Refactored from bulk loops to per-manifest resources
-   - Lines 215-216: Added config-gen resource as dependency
-   - **Removed**: Lines 112-251 (bulk generation loops)
-
-2. **`.tilt/core/registry/libraries.star`**
-   - Line 8: Fixed import to include `PRODUCT_LIBS_FRONTEND`
-
-3. **`Tiltfile`**
-   - Line 179: Fixed `Vite.generate_for_manifest` → `Vite.for_manifest`
-
-4. **`.tilt/C4-ARCHITECTURE.md`**
-   - Added: Level 4A section documenting manifest-driven architecture
-   - Added: Before/After comparison diagrams
-   - Added: Tilt UI visibility examples
-
----
-
-## 🎯 Alignment with User Requirements
-
-> "i thought manifest will be autoscanned. then based on manifest it should create tilt resource that will trigger 10 generators for that manifest"
-
-✅ **Implemented**: Each manifest creates ONE Tilt resource (`{service}-config-gen`) that triggers ALL 10+ generators
-
-> "so i mean tsconfig gen wont be creating 100 of tsconfigs in one function, its manifest based not function based"
-
-✅ **Implemented**: `TSConfig.backend()` is called ONCE per manifest (inside `ManifestResource.generate_all_configs()`), not in bulk loops
-
-> "you see what i mean??"
-
-✅ **Yes!** The architecture is now:
-- **Manifest-based**: 1 manifest → 1 resource → all generators
-- **NOT function-based**: No bulk loops generating 100 configs at once
-- **Granular tracking**: Each service has its own `{service}-config-gen` resource in Tilt UI
-
----
-
-## 🚀 Benefits Achieved
-
-1. **Visibility**: Every manifest has a dedicated Tilt resource
-2. **Efficiency**: Change 1 manifest → regenerate 10 configs (not 300)
-3. **Dependency Management**: Docker builds explicitly depend on config-gen
-4. **Developer Experience**: Clear labels and resource names in Tilt UI
-5. **Scalability**: Adding new manifests automatically creates new resources
-6. **Debugging**: Can track which resource generated which config
-
----
-
-## 📚 Next Steps (Optional Enhancements)
-
-1. **Parallel Execution**: Config-gen resources can run in parallel (already enabled via `allow_parallel=True`)
-2. **Caching**: Could cache generated configs and skip regeneration if manifest unchanged
-3. **Validation**: Add pre-generation validation (e.g., check manifest schema)
-4. **Metrics**: Track config generation time per resource
-5. **Live Updates**: Could trigger live updates when only specific configs change
-
----
-
-## 🏆 Conclusion
-
-The Tilt infrastructure has evolved from **bulk generation** to **manifest-driven resource creation**, achieving:
-
-- ✅ Per-resource granularity
-- ✅ Efficient updates (10 configs vs 300)
-- ✅ Clear dependency chains
-- ✅ Full visibility in Tilt UI
-- ✅ Alignment with user's architectural vision
-
-The system now follows the **"1 manifest → 1 resource → N generators"** pattern instead of **"N manifests → 1 loop → N×M configs"**.

package/engine/docs/README.md

@@ -1,284 +0,0 @@
-# TDK Landscape Tilt SDK
-
-## 🏗️ Architecture Overview
-
-This SDK provides a **professional, layered architecture** for managing 5000+ lines of Tilt/Starlark configuration code.
-
-```
-.tilt/
-├── core/                         # 🔧 Foundational Layer (Low-level)
-│   ├── utils.star                # Shared helpers, I/O, validation
-│   ├── manifest.star             # JSON manifest loading & expansion
-│   ├── registry.star             # Service definitions (Single Source of Truth)
-│   └── dependency-sync.star      # Workspace discovery & package.json sync
-│
-├── providers/                    # ⚡ Configuration Generators (Mid-level)
-│   ├── vite.star                 # Vite configuration generation
-│   ├── typescript/               # TSConfig generation (modular)
-│   │   └── include.star          # Entry point
-│   ├── docker/                    # Dockerfile / Compose generation (modularized)
-│   └── npmrc.star                # .npmrc / bunfig.toml generation
-│
-├── lifecycle/                    # 🚀 Service Lifecycle (High-level)
-│   ├── libs.star                 # Library management & Verdaccio
-│   └── databases.star            # Database virtualization (BigTech pattern)
-│
-├── config.star                   # 🎯 Global Config & Focus Mode
-├── legacy/                       # 📦 Legacy modules (backward compatibility)
-└── README.md                     # 📖 This file
-```
-
-## 🎯 Main Tiltfile Structure
-
-```starlark
-# =============================================================================
-# 🎯 TDK Landscape TILT ENTRYPOINT
-# =============================================================================
-
-# 1️⃣ LOAD CORE MODULES
-load('./.tilt/core/utils.star', 'Utils')
-load('./.tilt/core/manifest.star', 'Manifest')
-load('./.tilt/core/dependency-sync.star', 'DepSync')
-
-# 2️⃣ LOAD CONFIGURATION & SERVICE REGISTRY
-load('./.tilt/config.star', 'Config')
-load('./.tilt/core/registry.star', 'APP_RESOURCES', 'DEFAULTS', ...)
-
-# 3️⃣ LOAD PROVIDERS (Generators)
-load('./.tilt/providers/vite.star', 'Vite')
-load('./.tilt/providers/typescript/include.star', 'TSConfig')
-load('./.tilt/providers/docker/index.star', 'Docker')
-load('./.tilt/providers/npmrc.star', 'PackageConfig')
-
-# 4️⃣ LOAD LIFECYCLE MODULES
-load('./.tilt/provisioner/libs.star', 'Libs')
-load('./.tilt/provisioner/databases.star', 'Database')
-
-# 5️⃣ INITIALIZE INFRASTRUCTURE
-Utils.load_dotenv()
-Utils.validate_infisical_environment()
-
-local_resource('init-networks', cmd=Utils.fix_docker_networks(), labels=['infra'])
-```
-
-## 📋 Module Reference
-
-### Core Layer (`core/`)
-
-#### `utils.star` - Foundational Utilities
-
-```starlark
-load('./.tilt/core/utils.star', 'Utils')
-
-Utils.get_internal_deps("services/product/user/user-management-backend")
-Utils.resolve_lib_path("@tdk-landscape/eventing")
-Utils.write_file_if_changed("path/to/file.txt", "content")
-Utils.fix_docker_networks()
-Utils.validate_infisical_environment()
-Utils.detect_circular_deps(["path1", "path2"])
-```
-
-#### `manifest.star` - Manifest Loading
-
-```starlark
-load('./.tilt/core/manifest.star', 'Manifest')
-
-# Load and expand manifest with Smart Defaults
-manifest = Manifest.load_manifest("services/product/user/user-management-backend")
-
-# Load related backend for frontend
-backend = Manifest.load_related(frontend_manifest)
-
-# Validation
-issues = Manifest.validate(manifest)
-
-# Accessors
-port = Manifest.get_port(manifest)
-db_url = Manifest.get_database_url(manifest)
-```
-
-#### `dependency-sync.star` - Automatic Configuration Sync
-
-```starlark
-load('./.tilt/core/dependency-sync.star', 'DepSync')
-
-deps = DepSync.extract_internal_deps("services/product/user/user-management-backend")
-paths = DepSync.generate_tsconfig_paths(deps)
-aliases = DepSync.generate_vite_aliases(deps)
-DepSync.sync_all_configs_for_service("services/product/user/user-management-backend")
-```
-
----
-
-### Provider Layer (`providers/`)
-
-#### `vite.star` - Vite Configuration Generation
-
-```starlark
-load('./.tilt/providers/vite.star', 'Vite')
-
-# Generate for specific type
-Vite.frontend(manifest, backend_manifest, write_fn)
-Vite.backend(manifest, write_fn)
-Vite.library(manifest, write_fn)
-Vite.sdk(manifest, write_fn)
-
-# Universal dispatcher (recommended)
-Vite.for_manifest(manifest, backend_manifest, write_fn)
-```
-
-#### `typescript/include.star` - TSConfig Generation
-
-```starlark
-load('./.tilt/providers/typescript/include.star', 'TSConfig')
-
-TSConfig.backend(path, prisma_path, write_fn, internal_deps, is_docker)
-TSConfig.frontend(path, write_fn, internal_deps, is_docker)
-TSConfig.library_backend(path, write_fn, internal_deps)
-TSConfig.library_frontend(path, write_fn, internal_deps)
-TSConfig.prisma(path, resource_name, db_name, write_fn)
-```
-
-#### `docker/` - Dockerfile & Compose Generation (modularized)
-
-```starlark
-load('./.tilt/providers/docker/index.star', 'Docker')
-
-Docker.generate_frontend_dockerfile(path, name, target_path, use_nginx)
-Docker.generate_app_dockerfile(path, resource_name, start_command)
-Docker.generate_migrator_dockerfile(path, resource_name)
-Docker.generate_backend_compose_entry(path, resource_name, resource, manifest)
-```
-
-#### `npmrc.star` - Registry Configuration
-
-```starlark
-load('./.tilt/providers/npmrc.star', 'PackageConfig')
-
-PackageConfig.generate_npmrc(path, registry_url, is_docker)
-PackageConfig.generate_bunfig(path, registry_url, is_docker)
-```
-
----
-
-### Lifecycle Layer (`lifecycle/`)
-
-#### `libs.star` - Library Management
-
-```starlark
-load('./.tilt/provisioner/libs.star', 'Libs')
-
-lib_deps = Libs.discover_resource_libraries(ctx, resource_path)
-Libs.define_library_resource(ctx, lib_name, lib_config, should_enable)
-library_map = Libs.setup_libraries(ctx, should_enable, DDD_LIBS, PLATFORM_LIBS, PRODUCT_LIBS, generators)
-```
-
-#### `databases.star` - Database Virtualization
-
-```starlark
-load('./.tilt/provisioner/databases.star', 'Database')
-
-Database.provision("user")  # Creates TDK_user
-url = Database.get_database_url("user")
-Database.status_resource(enabled=True)
-Database.memory_summary()
-```
-
----
-
-### Config Layer (`config.star`)
-
-```starlark
-load('./.tilt/config.star', 'Config')
-
-# Focus Mode (tilt up -- --focus=user,treatment)
-FOCUS_MODE, FOCUS_ALL, FOCUS_RESOURCES = Config.apply_focus(cfg)
-
-# Build context
-ctx = Config.build_context()
-
-# Create should_enable wrapper
-should_enable = Config.create_should_enable_wrapper(...)
-```
-
----
-
-## 🧠 Why This Structure?
-
-### 1. **Encapsulation**
-When a developer needs to fix a Vite config bug, they go directly to `.tilt/providers/vite.star` — not search through 5000 lines.
-
-### 2. **Prevents Frozen Hash Table**
-Splitting into small files reduces the chance of mutating an object that's already "frozen" by another load.
-
-### 3. **Easy Testing**
-You can load only `.tilt/core/utils.star` in a test script without loading heavy Docker logic.
-
-### 4. **Scalability**
-Adding a new generator (e.g., for Kubernetes) = create new file in `providers/`.
-
----
-
-## 📊 File Sizes
-
-| Module | Lines | Purpose |
-|--------|-------|---------|
-| `core/utils.star` | ~400 | Shared utilities |
-| `core/manifest.star` | ~350 | Manifest loading |
-| `core/registry.star` | ~500 | Service definitions |
-| `core/dependency-sync.star` | ~350 | Config sync engine |
-| `providers/vite.star` | ~550 | Vite generation |
-| `providers/typescript/` | ~300 | TSConfig generation (modular) |
-| `providers/docker/` | ~500 | Docker generation (modularized) |
-| `providers/npmrc.star` | ~100 | Registry configs |
-| `lifecycle/libs.star` | ~400 | Library management |
-| `lifecycle/databases.star` | ~200 | Database virtualization |
-| `config.star` | ~250 | Global config |
-| **Total** | **~3900** | **Organized vs 5000+ chaotic** |
-
----
-
-## 🚀 Usage Patterns
-
-### Adding a New Service
-
-1. Add to `.tilt/core/registry.star`:
-```starlark
-APP_RESOURCES.append({
-    'name': 'my-service',
-    'path': 'services/product/my-domain/my-service',
-    'labels': ['app.my-domain'],
-    'resources': [...],
-})
-```
-
-2. Done! Tilt auto-generates everything.
-
-### Focus Mode Development
-
-```bash
-tilt up -- --focus=user                    # Only user + dependencies
-tilt up -- --focus=user,treatment          # Multiple services
-tilt up -- --focus=user --no-frontend      # Skip frontends
-tilt up -- --focus=user --include-monitoring
-```
-
-### Automatic Dependency Sync
-
-```bash
-bun add @tdk-landscape/eventing  # In any service
-# → Tilt watches package.json
-# → TSConfig/Vite auto-regenerate
-# → Service rebuilds
-```
-
----
-
-## 🔑 Key Design Principles
-
-1. **Single Source of Truth**: All service definitions in `registry.star`
-2. **Convention over Configuration**: Package names map to paths automatically
-3. **Struct-based APIs**: Clean `Vite.frontend()`, `Manifest.load_manifest()` interfaces
-4. **Pure Functions**: No global mutable state (Starlark-safe)
-5. **Layered Architecture**: Core → Providers → Lifecycle → Config
-6. **Backward Compatibility**: Legacy modules in `.tilt/legacy/`

package/install.sh

@@ -1,19 +0,0 @@
-#!/usr/bin/env bash
-# Legacy installer URL for the TDK CLI.
-#
-# The official installer is https://tdk-landscape.github.io/install.sh. It
-# installs the prebuilt `tdk` binary plus its bundled engine, verified
-# against the release checksums, with no Node or Bun required. This script
-# used to clone this repo and `bun link` it instead; it now hands off to the
-# official installer so old
-#   curl -fsSL https://raw.githubusercontent.com/tdk-landscape/tdk-cli-core/main/install.sh | bash
-# commands keep working and every install method gets the same result.
-#
-# To work on TDK itself, clone the repo instead (see CONTRIBUTING.md).
-
-set -euo pipefail
-
-readonly OFFICIAL_INSTALLER="https://tdk-landscape.github.io/install.sh"
-
-echo "Using the official TDK installer: ${OFFICIAL_INSTALLER}" >&2
-curl -fsSL "${OFFICIAL_INSTALLER}" | sh

package/knip.json

@@ -1,10 +0,0 @@
-{
-  "$schema": "https://unpkg.com/knip@6/schema.json",
-  "workspaces": {
-    "cli": {
-      "entry": ["src/cli.ts"],
-      "project": ["src/**/*.ts", "src/**/*.tsx"],
-      "ignoreBinaries": ["vi", "colima", "podman", "killall", "file", "tdk", "tilt"]
-    }
-  }
-}

package/openspec/changes/add-vscode-tdk-troubleshooter-plugin/.openspec.yaml

@@ -1,2 +0,0 @@
-schema: spec-driven
-created: 2026-09-21