Initial commit: Product OS platform

- Control Plane API with Gemini integration - Executors: Deploy, Analytics, Marketing - MCP Adapter for Continue integration - VSCode/VSCodium extension - Tool registry and run tracking - In-memory storage for local dev - Terraform infrastructure setup
2026-01-19 20:34:43 -08:00
commit b6d7148ded
58 changed files with 5365 additions and 0 deletions
--- a/platform/docs/GETTING_STARTED.md
+++ b/platform/docs/GETTING_STARTED.md
@@ -0,0 +1,143 @@
+# Product OS - Getting Started
+
+## Project Structure
+
+```
+platform/
+├── backend/
+│   └── control-plane/       # Fastify API server
+├── client-ide/
+│   └── extensions/
+│       └── gcp-productos/   # VSCodium/VS Code extension
+├── contracts/               # Tool registry schemas
+├── infra/
+│   └── terraform/           # GCP infrastructure
+├── docs/                    # Documentation
+└── docker-compose.yml       # Local development
+```
+
+## Quick Start (Local Development)
+
+### Prerequisites
+
+- Node.js 22+
+- Docker & Docker Compose
+- (Optional) VS Code or VSCodium for extension development
+
+### 1. Start Local Services
+
+```bash
+cd platform
+docker-compose up -d
+```
+
+This starts:
+- Firestore emulator on port 8081
+- GCS emulator on port 4443
+- Control Plane API on port 8080
+
+### 2. Run Control Plane in Dev Mode
+
+For faster iteration without Docker:
+
+```bash
+cd platform/backend/control-plane
+cp env.example .env
+npm install
+npm run dev
+```
+
+### 3. Test the API
+
+```bash
+# Health check
+curl http://localhost:8080/healthz
+
+# List tools (empty initially)
+curl http://localhost:8080/tools
+
+# Invoke a tool (dry run)
+curl -X POST http://localhost:8080/tools/invoke \
+  -H "Content-Type: application/json" \
+  -d '{
+    "tool": "cloudrun.deploy_service",
+    "tenant_id": "t_dev",
+    "input": {"service_name": "test"},
+    "dry_run": true
+  }'
+```
+
+### 4. Build & Install the Extension
+
+```bash
+cd platform/client-ide/extensions/gcp-productos
+npm install
+npm run build
+```
+
+Then in VS Code / VSCodium:
+1. Open Command Palette (Cmd+Shift+P)
+2. Run "Developer: Install Extension from Location..."
+3. Select the `gcp-productos` folder
+
+Or use the VSIX package:
+```bash
+npx vsce package
+code --install-extension gcp-productos-0.0.1.vsix
+```
+
+## Extension Usage
+
+Once installed, use the Command Palette:
+
+- **Product OS: Configure Backend** - Set the Control Plane URL
+- **Product OS: List Tools** - View available tools
+- **Product OS: Invoke Tool** - Execute a tool
+- **Product OS: Open Run** - View run details
+
+## Deploying to GCP
+
+### 1. Configure Terraform
+
+```bash
+cd platform/infra/terraform
+cp terraform.tfvars.example terraform.tfvars
+# Edit terraform.tfvars with your project details
+```
+
+### 2. Build & Push Container
+
+```bash
+cd platform/backend/control-plane
+
+# Build
+docker build -t us-central1-docker.pkg.dev/YOUR_PROJECT/productos/control-plane:latest .
+
+# Push (requires gcloud auth)
+docker push us-central1-docker.pkg.dev/YOUR_PROJECT/productos/control-plane:latest
+```
+
+### 3. Apply Terraform
+
+```bash
+cd platform/infra/terraform
+terraform init
+terraform plan
+terraform apply
+```
+
+## Seeding Tools
+
+To add tools to the registry, you can:
+
+1. Use the Firestore console to add documents to the `tools` collection
+2. Create a seed script that loads `contracts/tool-registry.yaml`
+3. Build an admin endpoint (coming in v2)
+
+## Next Steps
+
+- [ ] Build Deploy Executor
+- [ ] Build Analytics Executor  
+- [ ] Add Gemini integration
+- [ ] Add OAuth/IAP authentication
+- [ ] Create Product-Centric UI panels