# 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