@haystackeditor/cli 0.8.1 → 0.10.0

package/dist/assets/skills/secrets.md

@@ -0,0 +1,164 @@
+# /secrets
+
+Manage secrets for Haystack sandbox access to external services.
+
+## Purpose
+
+Store sensitive values (API keys, database URLs, tokens) that your sandbox needs to access external services. Secrets are:
+- **Zero-knowledge encrypted** - Encrypted locally before leaving your machine
+- **Injected at runtime** - Available as environment variables in the sandbox
+- **Scoped** - User, org, or repo level with cascading resolution
+
+## When to Use This
+
+Use secrets when your project needs:
+- Database connections (`DATABASE_URL`)
+- API keys for external services (`STRIPE_SECRET_KEY`, `OPENAI_API_KEY`)
+- Authentication tokens (`GITHUB_TOKEN`, `AWS_ACCESS_KEY_ID`)
+- Any sensitive values referenced in `.haystack.json`
+
+## Workflow
+
+### 1. Check for Existing Secrets
+
+First, see what secrets are already configured:
+
+```
+Call haystack_secrets_list
+
+If user wants org/repo scope:
+  haystack_secrets_list with scope="org" and scope_id="<org-name>"
+  haystack_secrets_list with scope="repo" and scope_id="<owner/repo>"
+```
+
+### 2. Set a Secret
+
+```
+Call haystack_secrets_set with:
+  key: "DATABASE_URL"      # Must be UPPERCASE_WITH_UNDERSCORES
+  value: "postgres://..."  # The secret value (encrypted before sending)
+  scope: "user"            # Optional: user (default), org, or repo
+  scope_id: "acme/myapp"   # Required for org/repo scope
+```
+
+### 3. Reference in Config
+
+Update `.haystack.json` to use the secret:
+
+```yaml
+dev_server:
+  command: pnpm dev
+  env:
+    DATABASE_URL: $DATABASE_URL      # Injected from secrets
+    STRIPE_KEY: $STRIPE_SECRET_KEY   # Another secret
+
+fixtures:
+  "/api/external":
+    source: "https://api.example.com/data"
+    headers:
+      Authorization: "Bearer $API_TOKEN"   # Secret in headers
+```
+
+### 4. Delete a Secret
+
+```
+Call haystack_secrets_delete with:
+  key: "OLD_API_KEY"
+  scope: "user"        # Match the scope where it was set
+  scope_id: "..."      # Required for org/repo
+```
+
+## Scopes Explained
+
+| Scope | Who Can Access | Use Case |
+|-------|----------------|----------|
+| `user` | Only you | Personal API keys, dev credentials |
+| `org` | All org members | Shared staging credentials |
+| `repo` | Repo collaborators | Project-specific secrets |
+
+**Resolution order** (first match wins):
+1. `repo` secrets (most specific)
+2. `org` secrets
+3. `user` secrets (fallback)
+
+This allows repo-specific overrides of org defaults.
+
+## Examples
+
+### Add a Database URL
+
+```
+User: "I need to connect to my Postgres database in the sandbox"
+
+1. Call haystack_secrets_set:
+   key: "DATABASE_URL"
+   value: "postgres://user:pass@host:5432/db"
+
+2. Update .haystack.json:
+   dev_server:
+     env:
+       DATABASE_URL: $DATABASE_URL
+
+3. Confirm: "Added DATABASE_URL. Your sandbox will now have access to your database."
+```
+
+### Add Stripe Keys for a Repo
+
+```
+User: "Set up Stripe keys for this project"
+
+1. Call haystack_secrets_set:
+   key: "STRIPE_SECRET_KEY"
+   value: "sk_test_..."
+   scope: "repo"
+   scope_id: "acme/checkout-service"
+
+2. Call haystack_secrets_set:
+   key: "STRIPE_WEBHOOK_SECRET"
+   value: "whsec_..."
+   scope: "repo"
+   scope_id: "acme/checkout-service"
+
+3. Update .haystack.json with $STRIPE_SECRET_KEY and $STRIPE_WEBHOOK_SECRET
+```
+
+### Check What Secrets Are Configured
+
+```
+User: "What secrets do I have?"
+
+1. Call haystack_secrets_list (user scope)
+2. Call haystack_secrets_list with scope="org", scope_id="acme" (if applicable)
+3. Call haystack_secrets_list with scope="repo", scope_id="acme/myapp" (if applicable)
+
+Report: "You have 3 user secrets, 2 org secrets, and 1 repo secret configured."
+```
+
+## Tips
+
+- **Key naming**: Use `UPPERCASE_WITH_UNDERSCORES` (e.g., `DATABASE_URL`, `API_SECRET_KEY`)
+- **Never log secrets**: The MCP tools never return secret values, only keys
+- **Rotation**: To rotate, just call `haystack_secrets_set` again with the new value
+- **Cleanup**: Use `haystack_secrets_delete` to remove unused secrets
+
+## Troubleshooting
+
+### "Not authenticated"
+Run `haystack login` first to authenticate with Haystack.
+
+### "scope_id required"
+For `org` or `repo` scope, you must provide `scope_id`:
+- Org: `scope_id: "my-org-name"`
+- Repo: `scope_id: "owner/repo-name"`
+
+### "Invalid key format"
+Secret keys must be:
+- Start with a letter
+- Uppercase letters only
+- Underscores allowed
+- Examples: `DATABASE_URL`, `AWS_ACCESS_KEY_ID`, `STRIPE_SECRET_KEY`
+
+### Secret not available in sandbox
+1. Check the secret exists: `haystack_secrets_list`
+2. Verify `.haystack.json` references it with `$KEY_NAME`
+3. Check resolution order - repo secrets override org/user secrets

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

@@ -0,0 +1,243 @@
+# 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