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

package/engine/schemas/manifest-schema.json

@@ -0,0 +1,301 @@
+{
+  "$id": "https://TDK Landscape.local/schemas/service-schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "appType": {
+            "const": "backend"
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "port": {
+            "maximum": 5999,
+            "minimum": 4000
+          }
+        },
+        "required": [
+          "port"
+        ]
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "appType": {
+            "const": "frontend"
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "port": {
+            "maximum": 3999,
+            "minimum": 3000
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "appType": {
+            "const": "worker"
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "features": {
+            "contains": {
+              "const": "nats"
+            }
+          }
+        },
+        "required": [
+          "features"
+        ]
+      }
+    }
+  ],
+  "description": "Configuration for TDK Landscape services. Drives Tilt orchestration, Docker Compose generation, and dependency resolution. Supports both explicit service.json files and synthesis from directory structure (CEO Review: rename-service-manifest).",
+  "properties": {
+    "$schema": {
+      "description": "JSON Schema reference for IDE validation",
+      "type": "string"
+    },
+    "apiBasePath": {
+      "default": "/api",
+      "description": "Base path for API routes in Traefik.",
+      "pattern": "^/[a-z0-9/-]*$",
+      "type": "string"
+    },
+    "appName": {
+      "description": "Unique resource identifier. Must match directory name.\nFormat: {stack}-{function}-{type}\nExample: 'user-management-backend'",
+      "examples": [
+        "user-management-backend",
+        "order-planner-frontend"
+      ],
+      "maxLength": 64,
+      "minLength": 3,
+      "pattern": "^[a-z][a-z0-9-]*[a-z0-9]$",
+      "type": "string"
+    },
+    "appType": {
+      "description": "Service type determining build strategy:\n• backend - Hono/Express API server\n• frontend - Vite/React application\n• sdk - Shared library package\n• worker - Background job processor\n• migrator - Database migration runner\n• library - Shared code library",
+      "enum": [
+        "backend",
+        "frontend",
+        "sdk",
+        "worker",
+        "migrator",
+        "library"
+      ],
+      "type": "string"
+    },
+    "backendName": {
+      "description": "For frontends: associated backend service.\nAuto-computed from appName if not specified.",
+      "pattern": "^[a-z][a-z0-9-]*-backend$",
+      "type": "string"
+    },
+    "basePath": {
+      "description": "Base path for frontend routing on TDK Landscape.localhost. Default is /{stack}s when omitted.",
+      "pattern": "^/[a-z0-9/-]*$",
+      "type": "string"
+    },
+    "databaseName": {
+      "description": "Override auto-generated DB name.\nDefault: TDK_{stack}",
+      "pattern": "^TDK_[a-z_]+$",
+      "type": "string"
+    },
+    "dependencies": {
+      "description": "Deprecated. Use 'dependsOn' instead.",
+      "deprecated": true,
+      "items": {
+        "pattern": "^[a-z][a-z0-9-]*$",
+        "type": "string"
+      },
+      "type": "array",
+      "uniqueItems": true
+    },
+    "dockerfile": {
+      "default": "autogenerated/Dockerfile.app.autogenerated",
+      "description": "Custom Dockerfile path relative to service directory.",
+      "type": "string"
+    },
+    "stack": {
+      "description": "Technology stack this resource belongs to.\nUsed for:\n• Database naming: TDK_{stack}\n• Traefik routing: /api/{stack}\n• NATS queue: {stack}_backend_svc",
+      "enum": [
+        "user",
+        "team",
+        "auth",
+        "order",
+        "order-planner",
+        "service",
+        "inventory",
+        "billing",
+        "notification",
+        "analytics",
+        "profile",
+        "platform",
+        "product"
+      ],
+      "type": "string"
+    },
+    "params": {
+      "additionalProperties": {
+        "type": "string"
+      },
+      "description": "Non-secret configuration parameters (BASE_URL, PORT, etc.). Secrets use 'secrets' section below.",
+      "type": "object"
+    },
+    "secrets": {
+      "description": "Secret references resolved via Infisical. NO secrets in params/envVars - security violation.",
+      "properties": {
+        "required": {
+          "description": "Required secret names. Service CRASHES if any are missing.",
+          "items": {
+            "type": "string",
+            "pattern": "^[A-Z_][A-Z0-9_]*$"
+          },
+          "type": "array",
+          "uniqueItems": true
+        },
+        "optional": {
+          "description": "Optional secret names. Service starts but warns if missing.",
+          "items": {
+            "type": "string",
+            "pattern": "^[A-Z_][A-Z0-9_]*$"
+          },
+          "type": "array",
+          "uniqueItems": true
+        }
+      },
+      "required": [
+        "required"
+      ],
+      "type": "object"
+    },
+    "features": {
+      "description": "Platform features:\n• nats - NATS JetStream eventing\n• prisma - DB ORM & migrations\n• redis - Caching layer\n• infisical - Secrets management\n• vitest - Test framework\n• traefik - Reverse proxy routing\n• websocket - WS support\n• graphql - GraphQL server\n• grpc - gRPC protocol",
+      "items": {
+        "enum": [
+          "nats",
+          "prisma",
+          "redis",
+          "infisical",
+          "vitest",
+          "traefik",
+          "websocket",
+          "graphql",
+          "grpc"
+        ],
+        "type": "string"
+      },
+      "type": "array",
+      "uniqueItems": true
+    },
+    "healthCheckPath": {
+      "default": "/health",
+      "description": "HTTP endpoint for health checks. Must return 200 OK.",
+      "pattern": "^/[a-z0-9/-]*$",
+      "type": "string"
+    },
+    "dependsOn": {
+      "description": "Resource dependencies used for startup ordering and frontend dependency env generation.\nEach entry can be a stack name (e.g. 'user') or resource name (e.g. 'user-management-backend').\nServices listed here start before this service. Used for focus mode, health checks, migration order.",
+      "items": {
+        "pattern": "^[a-z][a-z0-9-]*$",
+        "type": "string"
+      },
+      "type": "array",
+      "uniqueItems": true
+    },
+    "nats": {
+      "description": "Custom NATS configuration. Auto-generated if 'nats' in features.",
+      "properties": {
+        "queueGroup": {
+          "description": "NATS queue group for load balancing",
+          "type": "string"
+        },
+        "subjects": {
+          "description": "NATS subjects to subscribe",
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        }
+      },
+      "type": "object"
+    },
+    "playwright": {
+      "default": false,
+      "description": "Generate Playwright config in .autogenerated/playwright.config.autogenerated.ts when true.",
+      "type": "boolean"
+    },
+    "port": {
+      "description": "External dev port (internal always 3000).\nAssignments:\n• 4000: user\n• 4001: service\n• 4002: order\n• 4003: team\n• 4004: auth",
+      "examples": [
+        4000,
+        4001,
+        4002,
+        4003,
+        4004
+      ],
+      "maximum": 9999,
+      "minimum": 3000,
+      "type": "integer"
+    },
+    "replicas": {
+      "default": 1,
+      "description": "Container instances to run.\nCreates separate containers (service-1, service-2).\nTraefik load-balances between all replicas.",
+      "maximum": 10,
+      "minimum": 1,
+      "type": "integer"
+    },
+    "runtime": {
+      "default": "bun",
+      "description": "Runtime to use for this service",
+      "enum": [
+        "node",
+        "bun"
+      ],
+      "type": "string"
+    },
+    "syncs": {
+      "description": "Directories to sync for hot-reload.\nAuto-computed if not specified:\n• backend: ['src', 'prisma']\n• frontend: ['src', 'public']",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "traefik": {
+      "description": "Custom Traefik routing. Auto-generated if not specified.",
+      "properties": {
+        "healthCheck": {
+          "description": "Health check path for Traefik",
+          "type": "string"
+        },
+        "host": {
+          "description": "Custom hostname (e.g., 'user.backend.{project}.local')",
+          "type": "string"
+        },
+        "pathPrefix": {
+          "description": "URL path prefix (e.g., '/api/user')",
+          "type": "string"
+        }
+      },
+      "type": "object"
+    }
+  },
+  "required": [
+    "appName",
+    "appType",
+    "stack"
+  ],
+  "title": "TDK Landscape Service Configuration",
+  "type": "object"
+}

package/engine/schemas/service-schema.json

@@ -0,0 +1,301 @@
+{
+  "$id": "https://TDK Landscape.local/schemas/service-schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "appType": {
+            "const": "backend"
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "port": {
+            "maximum": 5999,
+            "minimum": 4000
+          }
+        },
+        "required": [
+          "port"
+        ]
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "appType": {
+            "const": "frontend"
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "port": {
+            "maximum": 3999,
+            "minimum": 3000
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "appType": {
+            "const": "worker"
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "features": {
+            "contains": {
+              "const": "nats"
+            }
+          }
+        },
+        "required": [
+          "features"
+        ]
+      }
+    }
+  ],
+  "description": "Configuration for TDK Landscape resources. Drives Tilt orchestration, Docker Compose generation, and dependency resolution. Supports both explicit service.json files and synthesis from directory structure.",
+  "properties": {
+    "$schema": {
+      "description": "JSON Schema reference for IDE validation",
+      "type": "string"
+    },
+    "apiBasePath": {
+      "default": "/api",
+      "description": "Base path for API routes in Traefik.",
+      "pattern": "^/[a-z0-9/-]*$",
+      "type": "string"
+    },
+    "appName": {
+      "description": "Unique resource identifier. Must match directory name.\nFormat: {stack}-{function}-{type}\nExample: 'user-management-backend'",
+      "examples": [
+        "user-management-backend",
+        "order-planner-frontend"
+      ],
+      "maxLength": 64,
+      "minLength": 3,
+      "pattern": "^[a-z][a-z0-9-]*[a-z0-9]$",
+      "type": "string"
+    },
+    "appType": {
+      "description": "Resource type determining build strategy:\n• backend - Hono/Express API server\n• frontend - Vite/React application\n• sdk - Shared library package\n• worker - Background job processor\n• migrator - Database migration runner\n• library - Shared code library",
+      "enum": [
+        "backend",
+        "frontend",
+        "sdk",
+        "worker",
+        "migrator",
+        "library"
+      ],
+      "type": "string"
+    },
+    "backendName": {
+      "description": "For frontends: associated backend resource.\nAuto-computed from appName if not specified.",
+      "pattern": "^[a-z][a-z0-9-]*-backend$",
+      "type": "string"
+    },
+    "basePath": {
+      "description": "Base path for frontend routing on TDK Landscape.localhost. Default is /{stack}s when omitted.",
+      "pattern": "^/[a-z0-9/-]*$",
+      "type": "string"
+    },
+    "databaseName": {
+      "description": "Override auto-generated DB name.\nDefault: TDK_{stack}",
+      "pattern": "^TDK_[a-z_]+$",
+      "type": "string"
+    },
+    "dependencies": {
+      "description": "Deprecated. Use 'dependsOn' instead.",
+      "deprecated": true,
+      "items": {
+        "pattern": "^[a-z][a-z0-9-]*$",
+        "type": "string"
+      },
+      "type": "array",
+      "uniqueItems": true
+    },
+    "dockerfile": {
+      "default": "autogenerated/Dockerfile.app.autogenerated",
+      "description": "Custom Dockerfile path relative to resource directory.",
+      "type": "string"
+    },
+    "stack": {
+      "description": "Technology stack this resource belongs to.\nUsed for:\n• Database naming: TDK_{stack}\n• Traefik routing: /api/{stack}\n• NATS queue: {stack}_backend_svc",
+      "enum": [
+        "user",
+        "team",
+        "auth",
+        "order",
+        "order-planner",
+        "service",
+        "inventory",
+        "billing",
+        "notification",
+        "analytics",
+        "profile",
+        "platform",
+        "product"
+      ],
+      "type": "string"
+    },
+    "params": {
+      "additionalProperties": {
+        "type": "string"
+      },
+      "description": "Non-secret configuration parameters (BASE_URL, PORT, etc.). Secrets use 'secrets' section below.",
+      "type": "object"
+    },
+    "secrets": {
+      "description": "Secret references resolved via Infisical. NO secrets in params/envVars - security violation.",
+      "properties": {
+        "required": {
+          "description": "Required secret names. Resource CRASHES if any are missing.",
+          "items": {
+            "type": "string",
+            "pattern": "^[A-Z_][A-Z0-9_]*$"
+          },
+          "type": "array",
+          "uniqueItems": true
+        },
+        "optional": {
+          "description": "Optional secret names. Resource starts but warns if missing.",
+          "items": {
+            "type": "string",
+            "pattern": "^[A-Z_][A-Z0-9_]*$"
+          },
+          "type": "array",
+          "uniqueItems": true
+        }
+      },
+      "required": [
+        "required"
+      ],
+      "type": "object"
+    },
+    "features": {
+      "description": "Platform features:\n• nats - NATS JetStream eventing\n• prisma - DB ORM & migrations\n• redis - Caching layer\n• infisical - Secrets management\n• vitest - Test framework\n• traefik - Reverse proxy routing\n• websocket - WS support\n• graphql - GraphQL server\n• grpc - gRPC protocol",
+      "items": {
+        "enum": [
+          "nats",
+          "prisma",
+          "redis",
+          "infisical",
+          "vitest",
+          "traefik",
+          "websocket",
+          "graphql",
+          "grpc"
+        ],
+        "type": "string"
+      },
+      "type": "array",
+      "uniqueItems": true
+    },
+    "healthCheckPath": {
+      "default": "/health",
+      "description": "HTTP endpoint for health checks. Must return 200 OK.",
+      "pattern": "^/[a-z0-9/-]*$",
+      "type": "string"
+    },
+    "dependsOn": {
+      "description": "Resource dependencies used for startup ordering and frontend dependency env generation.\nEach entry can be a stack (e.g. 'service') or resource name (e.g. 'user-admin-api').\nResources listed here start before this resource. Used for focus mode, health checks, migration order.",
+      "items": {
+        "pattern": "^[a-z][a-z0-9-]*$",
+        "type": "string"
+      },
+      "type": "array",
+      "uniqueItems": true
+    },
+    "nats": {
+      "description": "Custom NATS configuration. Auto-generated if 'nats' in features.",
+      "properties": {
+        "queueGroup": {
+          "description": "NATS queue group for load balancing",
+          "type": "string"
+        },
+        "subjects": {
+          "description": "NATS subjects to subscribe",
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        }
+      },
+      "type": "object"
+    },
+    "playwright": {
+      "default": false,
+      "description": "Generate Playwright config in .autogenerated/playwright.config.autogenerated.ts when true.",
+      "type": "boolean"
+    },
+    "port": {
+      "description": "External dev port (internal always 3000).\nAssignments:\n• 4000: user\n• 4001: service\n• 4002: order\n• 4003: team\n• 4004: auth",
+      "examples": [
+        4000,
+        4001,
+        4002,
+        4003,
+        4004
+      ],
+      "maximum": 9999,
+      "minimum": 3000,
+      "type": "integer"
+    },
+    "replicas": {
+      "default": 1,
+      "description": "Container instances to run.\nCreates separate containers (resource-1, resource-2).\nTraefik load-balances between all replicas.",
+      "maximum": 10,
+      "minimum": 1,
+      "type": "integer"
+    },
+    "runtime": {
+      "default": "bun",
+      "description": "Runtime to use for this resource",
+      "enum": [
+        "node",
+        "bun"
+      ],
+      "type": "string"
+    },
+    "syncs": {
+      "description": "Directories to sync for hot-reload.\nAuto-computed if not specified:\n• backend: ['src', 'prisma']\n• frontend: ['src', 'public']",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "traefik": {
+      "description": "Custom Traefik routing. Auto-generated if not specified.",
+      "properties": {
+        "healthCheck": {
+          "description": "Health check path for Traefik",
+          "type": "string"
+        },
+        "host": {
+          "description": "Custom hostname (e.g., 'user.backend.{project}.local')",
+          "type": "string"
+        },
+        "pathPrefix": {
+          "description": "URL path prefix (e.g., '/api/user')",
+          "type": "string"
+        }
+      },
+      "type": "object"
+    }
+  },
+  "required": [
+    "appName",
+    "appType",
+    "stack"
+  ],
+  "title": "TDK Landscape Resource Configuration",
+  "type": "object"
+}

package/engine/scripts/README.md

@@ -0,0 +1,89 @@
+---
+title: Tilt Library Build Caching
+status: backlog
+created: 2026-03-31
+updated: 2026-03-31
+---
+
+# Tilt Library Build Caching
+
+## Overview
+
+These scripts implement intelligent caching for library builds to avoid unnecessary rebuilds and republishes during `tilt up`.
+
+## How It Works
+
+### Check Script (`check-lib-publish.sh`)
+
+1. **Registry Check**: Queries Verdaccio to see if the package version is already published
+2. **Source Hash Check**: Computes a SHA-256 hash of all source files (src/, package.json, tsconfig.json)
+3. **Comparison**: Compares current hash with cached hash from last successful build
+4. **Decision**:
+   - If package published AND sources unchanged → **Skip rebuild** (exit 1)
+   - If package not published OR sources changed → **Rebuild needed** (exit 0)
+
+### Build Script (`build-and-publish-lib.sh`)
+
+1. Calls `check-lib-publish.sh` to determine if rebuild needed
+2. If skip indicated, exits early
+3. If rebuild needed:
+   - Runs full build pipeline (install, tsc, link, publish)
+   - Saves source hash to `.tilt-cache/source-hash.txt` on success
+   - Links package to consumer services if specified
+
+## Cache Location
+
+Each library maintains its own cache:
+```
+shared-platform-engineering/platform-logger/
+├── .tilt-cache/
+│   └── source-hash.txt  # SHA-256 hash of source files
+├── src/
+├── package.json
+└── tsconfig.json
+```
+
+## Benefits
+
+- **Faster `tilt up`**: Libraries only rebuild when sources actually change
+- **Idempotent**: Running `tilt up` multiple times doesn't cause unnecessary work
+- **Version Safety**: Warns if sources changed but version not bumped
+- **Verdaccio-aware**: Checks actual registry state, not just local build state
+
+## Manual Cache Clearing
+
+To force a rebuild of a specific library:
+```bash
+rm -rf shared-platform-engineering/platform-logger/.tilt-cache
+```
+
+To clear all library caches:
+```bash
+find . -type d -name '.tilt-cache' -path '*/shared-*' -exec rm -rf {} +
+```
+
+## Troubleshooting
+
+### Library not rebuilding when it should
+
+1. Check if version was bumped in package.json
+2. Verify source files are actually changing
+3. Clear cache and rebuild: `rm -rf <lib-path>/.tilt-cache && tilt up`
+
+### "Version already published" warning
+
+This means source files changed but package.json version wasn't bumped. Either:
+- Bump the version if this is a real change
+- Revert source changes if they were experimental
+- Manually unpublish from Verdaccio if needed
+
+## Implementation Details
+
+**Cache Key**: SHA-256 hash of concatenated contents of:
+- All files in `src/` directory
+- `package.json`
+- `tsconfig.json`
+
+**Registry Check**: HTTP GET to `<verdaccio-url>/<package-name>/<version>`
+- 200 = published
+- 404 = not published