diff --git a/readme-setup.md b/readme-setup.md new file mode 100644 index 0000000..edacd42 --- /dev/null +++ b/readme-setup.md @@ -0,0 +1,117 @@ +# Setup Guide (for future Replit Agents) + +A short, copy-paste-friendly checklist to get this project running from a clean clone. Read this **before** restarting workflows or asking the user for credentials. + +## What this project is + +A pnpm monorepo with three artifacts: + +| Artifact | Path | Port | Purpose | +| --- | --- | --- | --- | +| `api-server` | `artifacts/api-server` | `8080` | Express server. `/api/*` (health) + `/v1/*` OpenAI-compatible reverse proxy in front of OpenAI and Anthropic. | +| `api-portal` | `artifacts/api-portal` | `24927` | React + Vite frontend that shows connection info and CherryStudio setup. | +| `mockup-sandbox` | `artifacts/mockup-sandbox` | `8081` | Vite dev server for component previews. | + +The proxy exposes `GET /v1/models` and `POST /v1/chat/completions`. Model variants are auto-generated by suffixing the base id with a reasoning effort, e.g. `gpt-5.2-low`, `claude-opus-4-6-high`. For Anthropic models the suffix maps to `thinking.budget_tokens`. + +## Workflows (already configured in `.replit-artifact/artifact.toml` per artifact) + +- `artifacts/api-portal: web` → `pnpm --filter @workspace/api-portal run dev` +- `artifacts/api-server: API Server` → `pnpm --filter @workspace/api-server run dev` +- `artifacts/mockup-sandbox: Component Preview Server` → `pnpm --filter @workspace/mockup-sandbox run dev` + +Do **not** edit `artifact.toml` directly — use the artifacts skill helpers (`createArtifact`, `verifyAndReplaceArtifactToml`). + +## Required env vars / secrets + +The api-server instantiates the OpenAI and Anthropic SDKs at import time. If any of these are missing it crashes immediately on startup with `OpenAIError: Missing credentials` or similar. + +| Name | How to set | Notes | +| --- | --- | --- | +| `AI_INTEGRATIONS_OPENAI_BASE_URL` | `setupReplitAIIntegrations({ providerSlug: "openai", ... })` | auto-set | +| `AI_INTEGRATIONS_OPENAI_API_KEY` | same call | auto-set (dummy string for SDK; works alongside BASE_URL) | +| `AI_INTEGRATIONS_ANTHROPIC_BASE_URL` | `setupReplitAIIntegrations({ providerSlug: "anthropic", ... })` | auto-set | +| `AI_INTEGRATIONS_ANTHROPIC_API_KEY` | same call | auto-set | +| `PROXY_API_KEY` | `requestEnvVar({ requestType: "secret", keys: ["PROXY_API_KEY"] })` | user-defined; bearer token clients send | + +## One-shot setup script (in the JS sandbox) + +```javascript +// 1. Provision OpenAI + Anthropic via Replit AI Integrations +await setupReplitAIIntegrations({ + providerSlug: "openai", + providerUrlEnvVarName: "AI_INTEGRATIONS_OPENAI_BASE_URL", + providerApiKeyEnvVarName: "AI_INTEGRATIONS_OPENAI_API_KEY", +}); +await setupReplitAIIntegrations({ + providerSlug: "anthropic", + providerUrlEnvVarName: "AI_INTEGRATIONS_ANTHROPIC_BASE_URL", + providerApiKeyEnvVarName: "AI_INTEGRATIONS_ANTHROPIC_API_KEY", +}); + +// 2. Ask the user for their proxy bearer token (suggest a random one) +const crypto = await import("node:crypto"); +const suggested = crypto.randomBytes(24).toString("base64url"); +await requestEnvVar({ + requestType: "secret", + keys: ["PROXY_API_KEY"], + userMessage: `Bearer token for /v1/* on the proxy. Suggested: ${suggested}`, +}); +``` + +Then in the shell: + +```bash +pnpm install +``` + +And restart all three workflows (in any order). + +## Verification + +```bash +# health +curl -s http://localhost:8080/api/healthz +# → {"status":"ok"} + +# auth gate +curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8080/v1/models +# → 401 + +# model list (replace with your secret) +curl -s -H "Authorization: Bearer $PROXY_API_KEY" http://localhost:8080/v1/models | head -c 200 + +# portal +curl -s http://localhost:24927/ | head -c 80 +# → ... +``` + +## Common gotchas + +- **Port 8080 already in use after a crash loop.** Stale `node ./dist/index.mjs` processes from a previous failed start can hold the port. `ps -ef | grep dist/index.mjs` then `kill -9 ` before restarting the workflow. +- **mockup-sandbox transient `Cannot find package 'vite'` on first start.** It's a vite restart race after `pnpm install` invalidates `.vite-temp/`. A second restart of the workflow clears it. +- **Do not edit `lib/integrations-*-server/src/client.ts`** if those packages are added later — the env-var wiring is auto-managed. +- **`PROXY_API_KEY` is a bearer token, not an OAuth secret.** It only gates `/v1/*`; pick anything. Clients send `Authorization: Bearer `. +- **Adding routes to the proxy:** the file is `artifacts/api-server/src/routes/proxy.ts`, mounted at `/v1` in `artifacts/api-server/src/app.ts`. Health/utility routes live under `artifacts/api-server/src/routes/` and are mounted at `/api`. + +## File map (key paths) + +``` +artifacts/ + api-server/ + src/app.ts # express setup, mounts /api and /v1 + src/routes/proxy.ts # /v1/models + /v1/chat/completions, OpenAI+Anthropic + src/routes/health.ts # /api/healthz + build.mjs # esbuild bundler + api-portal/ + src/App.tsx # connection info + CherryStudio instructions + vite.config.ts + mockup-sandbox/ + vite.config.ts +lib/ + api-spec/openapi.yaml # OpenAPI source for codegen + api-zod/ # generated zod schemas + api-client-react/ # generated react-query hooks + db/ # drizzle schema (unused by the proxy itself) +replit.md # high-level project overview +```