feat: unify API contracts and add contract schema validation

- Config endpoint now returns {name, desc} objects instead of flat strings
  for packages, casks, and npm arrays
- New GET /api/packages endpoint serves full package catalog with
  installer type (formula/cask/npm) for CLI consumption
- Snapshot upload validates packages is structured object format
- CI validates responses against openboot-contract JSON schemas
- CI triggers on contract-updated repository_dispatch events
- Update tests and docs to match new response format
- Add post-deploy smoke test script (scripts/smoke-test-api.sh)

Author: fullstackjam

.github/workflows/ci.yml

@@ -5,6 +5,8 @@ on:
     branches: [main]
   pull_request:
     branches: [main]
+  repository_dispatch:
+    types: [contract-updated]
 
 jobs:
   check:
@@ -41,6 +43,43 @@ jobs:
       - name: Build
         run: npm run build
 
+      - name: Contract schema validation
+        run: |
+          git clone --depth 1 https://github.com/openbootdotdev/openboot-contract.git /tmp/contract
+          pip install jsonschema
+
+          python3 -c "
+          import json, jsonschema, sys
+
+          checks = [
+            ('/tmp/contract/schemas/remote-config.json', '/tmp/contract/fixtures/config-v1.json'),
+            ('/tmp/contract/schemas/snapshot.json', '/tmp/contract/fixtures/snapshot-v1.json'),
+          ]
+
+          failed = 0
+          for schema_path, fixture_path in checks:
+            schema = json.load(open(schema_path))
+            data = json.load(open(fixture_path))
+            try:
+              jsonschema.validate(data, schema)
+              print(f'  ✓ {fixture_path.split(\"/\")[-1]} matches {schema_path.split(\"/\")[-1]}')
+            except jsonschema.ValidationError as e:
+              print(f'  ✗ {fixture_path.split(\"/\")[-1]}: {e.message}')
+              failed += 1
+
+          # Also validate the packages schema structure against package-metadata expectations
+          pkg_schema = json.load(open('/tmp/contract/schemas/packages.json'))
+          required_fields = set(pkg_schema['properties']['packages']['items']['required'])
+          expected = {'name', 'desc', 'category', 'type', 'installer'}
+          if required_fields != expected:
+            print(f'  ✗ packages schema required fields mismatch: {required_fields} vs {expected}')
+            failed += 1
+          else:
+            print(f'  ✓ packages schema has correct required fields')
+
+          sys.exit(1 if failed else 0)
+          "
+
   deploy:
     needs: check
     if: github.event_name == 'push' && github.ref == 'refs/heads/main'

.gitignore

@@ -25,3 +25,4 @@ coverage/
 vite.config.js.timestamp-*
 vite.config.ts.timestamp-*
 .claude/
+.dev.vars

CLAUDE.md

@@ -42,7 +42,7 @@ Local dev requires `.dev.vars` with `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`,
 | `src/lib/server/` | Server-only: `auth.ts` (JWT + OAuth), `install-script.ts`, `rate-limit.ts`, `validation.ts` |
 | `src/lib/stores/` | Svelte stores: `auth.ts` (user state), `theme.ts` (light/dark) |
 | `src/lib/presets.ts` | Package presets (minimal, developer, full) |
-| `src/lib/package-metadata.ts` | Descriptions for 100+ packages |
+| `src/lib/package-metadata.ts` | Source of truth for package metadata (100+ packages). Served via `/api/packages` for CLI consumption |
 | `src/routes/api/` | REST API endpoints (`+server.ts` convention) |
 | `src/routes/[username]/[slug]/` | Config page, install endpoint, config JSON, OG image |
 | `src/docs/` | Markdown docs (mdsvex preprocessed) |
@@ -57,7 +57,7 @@ Three auth flows:
 
 ### Database
 
-D1 (SQLite), no ORM — direct parameterized SQL via `env.DB.prepare(sql).bind(...)`. Four tables: `users`, `configs`, `api_tokens`, `cli_auth_codes`. The `configs.packages` field is a JSON array of `{name, type, desc}`. Config visibility: `public` (discoverable), `unlisted` (accessible but not listed), `private` (owner-only, 403 on install).
+D1 (SQLite), no ORM — direct parameterized SQL via `env.DB.prepare(sql).bind(...)`. Four tables: `users`, `configs`, `api_tokens`, `cli_auth_codes`. The `configs.packages` field is a JSON array (stored as `{name, type}` objects; the config endpoint transforms to `{name, desc}` on read, filling descriptions from `package-metadata.ts`). Config visibility: `public` (discoverable), `unlisted` (accessible but not listed), `private` (owner-only, 403 on install).
 
 **D1 limitation**: No `ALTER TABLE DROP COLUMN`. Plan column removals via new table + data migration.
 

scripts/smoke-test-api.sh

@@ -0,0 +1,146 @@
+#!/bin/bash
+# Post-deployment smoke test for openboot.dev API.
+# Tests that critical endpoints return the expected response shape.
+#
+# Usage:
+#   ./scripts/smoke-test-api.sh                    # test production
+#   ./scripts/smoke-test-api.sh http://localhost:5173  # test local
+#
+set -euo pipefail
+
+BASE_URL="${1:-https://openboot.dev}"
+PASS=0
+FAIL=0
+
+pass() { PASS=$((PASS + 1)); echo "  ✓ $1"; }
+fail() { FAIL=$((FAIL + 1)); echo "  ✗ $1: $2"; }
+
+echo "Smoke testing $BASE_URL"
+echo ""
+
+# --- Health ---
+echo "=== /api/health ==="
+HEALTH=$(curl -sf "$BASE_URL/api/health" 2>/dev/null || echo '{}')
+if echo "$HEALTH" | python3 -c "import sys,json; d=json.load(sys.stdin); assert d.get('status') in ('healthy','degraded')" 2>/dev/null; then
+  pass "health endpoint responds"
+else
+  fail "health endpoint" "unexpected response"
+fi
+
+# --- /api/packages ---
+echo ""
+echo "=== /api/packages ==="
+PKGS=$(curl -sf "$BASE_URL/api/packages" 2>/dev/null || echo '{}')
+
+# Has packages array
+if echo "$PKGS" | python3 -c "import sys,json; d=json.load(sys.stdin); assert len(d['packages']) > 50" 2>/dev/null; then
+  pass "returns 50+ packages"
+else
+  fail "package count" "expected 50+ packages"
+fi
+
+# Each package has required fields
+if echo "$PKGS" | python3 -c "
+import sys,json
+d=json.load(sys.stdin)
+p=d['packages'][0]
+for f in ('name','desc','category','type','installer'):
+    assert f in p, f'missing {f}'
+assert p['installer'] in ('formula','cask','npm'), f'bad installer: {p[\"installer\"]}'
+" 2>/dev/null; then
+  pass "packages have name, desc, category, type, installer"
+else
+  fail "package shape" "missing required fields"
+fi
+
+# Installer breakdown has all three types
+if echo "$PKGS" | python3 -c "
+import sys,json
+d=json.load(sys.stdin)
+types = set(p['installer'] for p in d['packages'])
+assert 'formula' in types and 'cask' in types and 'npm' in types
+" 2>/dev/null; then
+  pass "has formula, cask, and npm installers"
+else
+  fail "installer types" "missing formula/cask/npm"
+fi
+
+# --- /api/homebrew/search ---
+echo ""
+echo "=== /api/homebrew/search ==="
+SEARCH=$(curl -sf "$BASE_URL/api/homebrew/search?q=git" 2>/dev/null || echo '{}')
+if echo "$SEARCH" | python3 -c "
+import sys,json
+d=json.load(sys.stdin)
+assert 'formulae' in d or 'results' in d
+" 2>/dev/null; then
+  pass "homebrew search responds"
+else
+  fail "homebrew search" "unexpected response shape"
+fi
+
+# --- Config endpoint (using a known public config if available) ---
+echo ""
+echo "=== Config endpoint ==="
+# Try the official openboot config first, fall back to any public config.
+CONFIG=$(curl -sf "$BASE_URL/openboot/developer/config" 2>/dev/null || echo '')
+if [ -z "$CONFIG" ]; then
+  # Try fetching public configs list.
+  CONFIG=$(curl -sf "$BASE_URL/api/configs/public" 2>/dev/null | python3 -c "
+import sys,json
+configs=json.load(sys.stdin)
+if configs and len(configs)>0:
+    c=configs[0]
+    print(c.get('username',''),c.get('slug',''))
+" 2>/dev/null || echo '')
+  if [ -n "$CONFIG" ]; then
+    read -r USER SLUG <<< "$CONFIG"
+    CONFIG=$(curl -sf "$BASE_URL/$USER/$SLUG/config" 2>/dev/null || echo '')
+  fi
+fi
+
+if [ -n "$CONFIG" ] && [ "$CONFIG" != "{}" ]; then
+  # packages should be objects with name+desc
+  if echo "$CONFIG" | python3 -c "
+import sys,json
+d=json.load(sys.stdin)
+assert 'packages' in d
+assert 'casks' in d
+assert 'taps' in d
+assert 'npm' in d
+if len(d['packages']) > 0:
+    p = d['packages'][0]
+    assert isinstance(p, dict), f'expected object, got {type(p).__name__}'
+    assert 'name' in p, 'missing name'
+    assert 'desc' in p, 'missing desc'
+" 2>/dev/null; then
+    pass "config returns {name, desc} objects for packages"
+  else
+    fail "config format" "packages not in expected {name, desc} format"
+  fi
+
+  # taps should be plain strings
+  if echo "$CONFIG" | python3 -c "
+import sys,json
+d=json.load(sys.stdin)
+if len(d.get('taps',[])) > 0:
+    assert isinstance(d['taps'][0], str), 'taps should be strings'
+" 2>/dev/null; then
+    pass "taps are plain strings"
+  else
+    fail "taps format" "expected string array"
+  fi
+else
+  echo "  - skipped (no public config found)"
+fi
+
+# --- Summary ---
+echo ""
+TOTAL=$((PASS + FAIL))
+echo "Results: $PASS/$TOTAL passed"
+if [ "$FAIL" -gt 0 ]; then
+  echo "FAILED"
+  exit 1
+else
+  echo "ALL PASSED"
+fi

src/docs/api-reference.md

@@ -76,8 +76,7 @@ GET /api/configs/:slug
   "description": "Personal development environment",
   "base_preset": "developer",
   "packages": [
-    { "name": "node", "type": "formula" },
-    { "name": "visual-studio-code", "type": "cask" }
+    { "name": "node", "type": "formula", "desc": "JavaScript runtime built on V8 engine" }
   ],
   "custom_script": "mkdir -p ~/projects",
   "dotfiles_repo": "https://github.com/user/dotfiles.git",
@@ -217,6 +216,57 @@ GET /:username/:slug/install
 
 ---
 
+## Package Catalog
+
+### List All Packages
+
+Returns the complete package catalog with metadata. Used by the CLI to fetch package descriptions and installer types. Responses are cached (1h client, 24h CDN).
+
+```
+GET /api/packages
+```
+
+**Auth required:** No
+
+**Response:**
+
+```json
+{
+  "packages": [
+    {
+      "name": "git",
+      "desc": "Distributed version control system",
+      "category": "essential",
+      "type": "cli",
+      "installer": "formula"
+    },
+    {
+      "name": "visual-studio-code",
+      "desc": "Code editor with extensions and debugging",
+      "category": "essential",
+      "type": "gui",
+      "installer": "cask"
+    },
+    {
+      "name": "typescript",
+      "desc": "Typed superset of JavaScript",
+      "category": "essential",
+      "type": "language",
+      "installer": "npm"
+    }
+  ]
+}
+```
+
+**Fields:**
+- `name` — Package identifier
+- `desc` — Human-readable description
+- `category` — `essential`, `development`, `productivity`, or `optional`
+- `type` — Package kind: `cli`, `gui`, `language`, `devops`, or `database`
+- `installer` — Install method: `formula` (Homebrew), `cask` (Homebrew Cask), or `npm`
+
+---
+
 ## Package Search
 
 ### Search Homebrew Packages
@@ -400,8 +450,8 @@ curl -X POST https://openboot.dev/api/configs \
     "name": "My Setup",
     "base_preset": "developer",
     "packages": [
-      {"name": "node", "type": "formula"},
-      {"name": "visual-studio-code", "type": "cask"}
+      {"name": "node", "type": "formula", "desc": "JavaScript runtime"},
+      {"name": "visual-studio-code", "type": "cask", "desc": "Code editor"}
     ]
   }'
 ```

src/routes/[username]/[slug]/config/+server.ts

@@ -1,5 +1,6 @@
 import { json } from '@sveltejs/kit';
 import type { RequestHandler } from './$types';
+import { getPackageDescription } from '$lib/package-metadata';
 
 export const GET: RequestHandler = async ({ platform, params, request }) => {
 	const env = platform?.env;
@@ -75,30 +76,33 @@ export const GET: RequestHandler = async ({ platform, params, request }) => {
 	}
 
 	const rawPackages: any[] = JSON.parse(config.packages || '[]');
-	const packageNames: string[] = [];
-	const caskNames: string[] = [];
-	const npmNames: string[] = [];
+	const formulae: { name: string; desc: string }[] = [];
+	const casks: { name: string; desc: string }[] = [];
+	const npms: { name: string; desc: string }[] = [];
 
 	for (const pkg of rawPackages) {
+		const name = typeof pkg === 'string' ? pkg : pkg.name;
+		const desc = (typeof pkg === 'object' && pkg.desc) || getPackageDescription(name);
+
 		if (typeof pkg === 'string') {
 			if (snapshotCasks.has(pkg)) {
-				caskNames.push(pkg);
+				casks.push({ name, desc });
 			} else {
-				packageNames.push(pkg);
+				formulae.push({ name, desc });
 			}
 		} else {
 			if (pkg.type === 'npm') {
-				npmNames.push(pkg.name);
+				npms.push({ name, desc });
 			} else if (pkg.type === 'cask') {
-				caskNames.push(pkg.name);
+				casks.push({ name, desc });
 			} else {
-				packageNames.push(pkg.name);
+				formulae.push({ name, desc });
 			}
 		}
 	}
 
-	for (const pkg of packageNames) {
-		const parts = pkg.split('/');
+	for (const pkg of formulae) {
+		const parts = pkg.name.split('/');
 		if (parts.length === 3) {
 			tapsSet.add(`${parts[0]}/${parts[1]}`);
 		}
@@ -111,10 +115,10 @@ export const GET: RequestHandler = async ({ platform, params, request }) => {
 		slug: config.slug,
 		name: config.name,
 		preset: config.base_preset,
-		packages: packageNames,
-		casks: caskNames,
-		taps: taps,
-		npm: npmNames,
+		packages: formulae,
+		casks,
+		taps,
+		npm: npms,
 		dotfiles_repo: config.dotfiles_repo || '',
 		post_install: config.custom_script
 			? config.custom_script.split('\n').map((s: string) => s.trim()).filter((s: string) => s.length > 0)