@haystackeditor/cli 0.10.1 → 0.10.2

package/dist/assets/skills/setup-external-sandbox.md

@@ -1,243 +0,0 @@
-# External Sandbox Setup
-
-**Your job**: Help the user connect Haystack to their existing sandbox infrastructure instead of using Haystack's built-in sandboxes.
-
----
-
-## When to Use This
-
-External sandboxes are for users who:
-- Have their own background agent (e.g., custom AI coding agent)
-- Already spin up development environments (e.g., Codespaces, Gitpod, custom VMs)
-- Want Haystack's review UI (browser, editor, terminal) to connect to THEIR sandbox
-
-If the user doesn't have their own sandbox infrastructure, they should use Haystack's built-in sandboxes instead.
-
----
-
-## Step 1: Understand Their Setup
-
-**Ask the user:**
-
-> Do you have your own background agent or sandbox infrastructure?
->
-> Haystack can connect to your existing sandbox instead of spinning up its own. This is useful if:
-> - You have a custom AI agent that makes code changes
-> - You use Codespaces, Gitpod, or similar cloud dev environments
-> - You want to share a single sandbox between your agent and Haystack's review UI
->
-> **How does your sandbox provide access?**
->
-> 1. **HTTP API** - Your sandbox exposes an endpoint that returns URLs (recommended)
-> 2. **Webhook push** - Your agent calls Haystack when the sandbox is ready
-> 3. **Neither yet** - I need help designing the integration
-
-**Wait for the user's response before continuing.**
-
----
-
-## Step 2: Configure Based on Response
-
-### Option 1: HTTP API (Pull)
-
-The user's sandbox exposes an endpoint that Haystack queries.
-
-**Their endpoint must return:**
-
-```json
-{
-  "devUrl": "https://sandbox.example.com:3000",       // Browser preview
-  "opencodeUrl": "https://sandbox.example.com:8080",  // Code editor (OpenCode)
-  "terminalUrl": "https://sandbox.example.com/term",  // Web terminal
-  "status": "ready"  // "starting" | "ready" | "stopped" | "error"
-}
-```
-
-**Query parameters Haystack sends:**
-
-| Param | Description |
-|-------|-------------|
-| `session_id` | Haystack session ID |
-| `repo` | Repository name (e.g., `owner/repo`) |
-| `branch` | Branch name |
-| `pr_number` | PR number (if applicable) |
-
-**Add to `.haystack.json`:**
-
-```json
-{
-  "sandbox": {
-    "external": {
-      "pullEndpoint": "https://your-api.example.com/sandbox",
-      "authHeader": "X-API-Key"
-    }
-  }
-}
-```
-
-If they need authentication, tell them:
-> Add your API key as a Haystack secret:
-> ```bash
-> npx @haystackeditor/cli secrets set SANDBOX_API_KEY "your-key"
-> ```
-> Then reference it in the config:
-> ```json
-> {
->   "sandbox": {
->     "external": {
->       "pullEndpoint": "https://your-api.example.com/sandbox",
->       "authHeader": "X-API-Key",
->       "authValue": "$SANDBOX_API_KEY"
->     }
->   }
-> }
-> ```
-
----
-
-### Option 2: Webhook Push
-
-The user's agent calls Haystack when the sandbox is ready.
-
-**Webhook endpoint:**
-
-```
-POST https://haystack-agent.akshaysg.workers.dev/sessions/{session_id}/external-sandbox
-```
-
-**Request body:**
-
-```json
-{
-  "devUrl": "https://sandbox.example.com:3000",
-  "opencodeUrl": "https://sandbox.example.com:8080",
-  "terminalUrl": "https://sandbox.example.com/term",
-  "status": "ready"
-}
-```
-
-**Add to `.haystack.json`:**
-
-```json
-{
-  "sandbox": {
-    "external": {
-      "mode": "push"
-    }
-  }
-}
-```
-
-**Tell the user:**
-> Your agent needs to POST to Haystack when the sandbox is ready.
->
-> **Webhook URL pattern:**
-> ```
-> https://haystack-agent.akshaysg.workers.dev/sessions/{SESSION_ID}/external-sandbox
-> ```
->
-> The `SESSION_ID` is passed to your agent when Haystack requests a sandbox.
-> Your agent should call this endpoint with the sandbox URLs when ready.
-
----
-
-### Option 3: Neither (Help Design)
-
-If they don't have an existing API, help them add one.
-
-**Questions to ask:**
-
-1. What language/framework is your agent built with?
-2. Where does your agent store sandbox URLs? (DB, memory, file)
-3. How does your sandbox expose services? (tunnels, direct ports, custom domain)
-
-**Provide a minimal implementation example based on their stack:**
-
-**Node.js/Express:**
-```javascript
-app.get('/sandbox', (req, res) => {
-  const { session_id, repo, branch, pr_number } = req.query;
-
-  // Look up or create sandbox for this session
-  const sandbox = getSandboxFor(session_id, repo, branch);
-
-  res.json({
-    devUrl: sandbox.devServerUrl,
-    opencodeUrl: sandbox.editorUrl,
-    terminalUrl: sandbox.terminalUrl,
-    status: sandbox.status  // "starting" | "ready" | "stopped" | "error"
-  });
-});
-```
-
-**Python/FastAPI:**
-```python
-@app.get("/sandbox")
-async def get_sandbox(
-    session_id: str,
-    repo: str,
-    branch: str,
-    pr_number: Optional[int] = None
-):
-    sandbox = await get_or_create_sandbox(session_id, repo, branch)
-    return {
-        "devUrl": sandbox.dev_server_url,
-        "opencodeUrl": sandbox.editor_url,
-        "terminalUrl": sandbox.terminal_url,
-        "status": sandbox.status
-    }
-```
-
----
-
-## Step 3: Verify the Configuration
-
-After adding the config to `.haystack.json`, verify it works:
-
-```bash
-# If using pull mode, test the endpoint directly
-curl "https://your-api.example.com/sandbox?session_id=test&repo=owner/repo&branch=main"
-
-# Should return:
-# {"devUrl": "...", "opencodeUrl": "...", "terminalUrl": "...", "status": "ready"}
-```
-
----
-
-## Step 4: Commit
-
-```bash
-git add .haystack.json
-git commit -m "Configure external sandbox integration"
-```
-
-Done! Haystack will now use your sandbox infrastructure instead of its built-in sandboxes.
-
----
-
-## URL Requirements
-
-Your sandbox URLs must be:
-
-| URL | Purpose | Requirements |
-|-----|---------|--------------|
-| `devUrl` | Browser preview | HTTPS, iframe-embeddable, serves your dev server |
-| `opencodeUrl` | Code editor | HTTPS, serves OpenCode web UI on port 8080 |
-| `terminalUrl` | Web terminal | HTTPS, WebSocket-capable, ttyd or xterm.js |
-
-**Common Issues:**
-
-- **CORS**: Your sandbox must allow requests from `https://haystackeditor.com`
-- **X-Frame-Options**: Set to `ALLOWALL` or `ALLOW-FROM https://haystackeditor.com`
-- **Mixed content**: All URLs must be HTTPS (no HTTP)
-
----
-
-## Debugging
-
-If the integration isn't working:
-
-1. **Check the endpoint returns valid JSON** with all required fields
-2. **Check status** - must be one of: `starting`, `ready`, `stopped`, `error`
-3. **Check URLs are accessible** - Haystack can't access localhost or private IPs
-4. **Check CORS headers** - your sandbox must allow cross-origin requests