@haystackeditor/cli 0.8.0 → 0.9.0

package/dist/assets/skills/prepare-haystack.md

@@ -0,0 +1,323 @@
+# Prepare Codebase for Verification
+
+> **PRO Feature**: Verification Flow requires a Haystack PRO subscription to run cloud sandboxes. Free users can still prepare their codebase — it will be ready when they upgrade. See https://haystackeditor.com/pricing for details.
+
+**Your job**: Make this codebase easy to verify by adding semantic identifiers that the verification system can target.
+
+The verification Planner needs to find UI elements by selectors. Generic selectors like `div` or `.flex` are useless. Your job is to add meaningful identifiers throughout the codebase.
+
+---
+
+## What to Add
+
+### 1. `aria-label` on Interactive Elements
+
+Every clickable/interactive element should have an aria-label describing what it does:
+
+```tsx
+// Before
+<button onClick={onSave}>💾</button>
+<button onClick={() => setOpen(true)}>
+  <MenuIcon />
+</button>
+
+// After
+<button onClick={onSave} aria-label="Save document">💾</button>
+<button onClick={() => setOpen(true)} aria-label="Open menu">
+  <MenuIcon />
+</button>
+```
+
+**Target elements:**
+- Buttons (especially icon-only buttons)
+- Links without descriptive text
+- Toggle switches
+- Dropdown triggers
+- Modal open/close buttons
+- Form submit buttons
+
+### 2. `data-testid` on Key Sections
+
+Major UI sections should have data-testid for easy targeting:
+
+```tsx
+// Before
+<div className="flex flex-col p-4">
+  <h1>Dashboard</h1>
+  {/* content */}
+</div>
+
+// After
+<div className="flex flex-col p-4" data-testid="dashboard-container">
+  <h1>Dashboard</h1>
+  {/* content */}
+</div>
+```
+
+**Target sections:**
+- Page containers (dashboard, settings, profile)
+- Navigation bars/sidebars
+- Modal/dialog content
+- Form containers
+- Data tables/lists
+- Card components
+- Loading states
+- Error states
+- Empty states
+
+### 3. `role` Attributes for Semantic Structure
+
+Add ARIA roles where HTML semantics aren't clear:
+
+```tsx
+// Before
+<div className="modal-overlay">
+  <div className="modal-content">
+
+// After
+<div className="modal-overlay" role="presentation">
+  <div className="modal-content" role="dialog" aria-modal="true">
+```
+
+**Common roles:**
+- `role="dialog"` - Modals/dialogs
+- `role="navigation"` - Nav sections
+- `role="main"` - Main content area
+- `role="alert"` - Error/success messages
+- `role="status"` - Loading indicators
+- `role="tablist"`, `role="tab"`, `role="tabpanel"` - Tab interfaces
+
+### 4. State Indicators
+
+Add attributes that indicate UI state:
+
+```tsx
+// Before
+<button onClick={toggle}>
+  {isOpen ? 'Close' : 'Open'}
+</button>
+
+// After
+<button
+  onClick={toggle}
+  aria-expanded={isOpen}
+  aria-label={isOpen ? 'Close panel' : 'Open panel'}
+>
+  {isOpen ? 'Close' : 'Open'}
+</button>
+```
+
+**State attributes:**
+- `aria-expanded` - Collapsible sections
+- `aria-selected` - Selected items in lists
+- `aria-checked` - Checkboxes/toggles
+- `aria-disabled` - Disabled elements
+- `aria-busy` - Loading states
+- `data-state="loading|error|success"` - Custom states
+
+### 5. Form Accessibility
+
+Forms should have proper labels and descriptions:
+
+```tsx
+// Before
+<input type="email" placeholder="Email" />
+<span className="text-red-500">{error}</span>
+
+// After
+<input
+  type="email"
+  placeholder="Email"
+  aria-label="Email address"
+  aria-describedby={error ? "email-error" : undefined}
+  aria-invalid={!!error}
+/>
+{error && <span id="email-error" role="alert" className="text-red-500">{error}</span>}
+```
+
+---
+
+## Step 1: Scan for Missing Identifiers
+
+```bash
+# Find buttons without aria-label
+grep -rn "<button" src/ --include="*.tsx" | grep -v "aria-label" | head -20
+
+# Find icon-only buttons (likely missing labels)
+grep -rn "<button.*Icon\|<button.*>.*</.*Icon>" src/ --include="*.tsx" | head -20
+
+# Find modals/dialogs without role
+grep -rn "modal\|dialog\|Modal\|Dialog" src/ --include="*.tsx" | grep -v "role=" | head -20
+
+# Find forms without proper labeling
+grep -rn "<input\|<select\|<textarea" src/ --include="*.tsx" | grep -v "aria-label\|id=" | head -20
+
+# Find major components (likely need data-testid)
+ls src/components/ src/pages/ 2>/dev/null
+```
+
+---
+
+## Step 2: Prioritize by Impact
+
+Focus on elements the verification system is most likely to need:
+
+**High Priority (do first):**
+1. Navigation elements (header, sidebar, menu buttons)
+2. Primary actions (submit buttons, save buttons, CTAs)
+3. Modal triggers and dialogs
+4. Form inputs and submit buttons
+5. Page-level containers
+
+**Medium Priority:**
+1. Toggle switches and checkboxes
+2. Dropdown menus
+3. Tab interfaces
+4. Cards and list items
+5. Loading/error states
+
+**Lower Priority:**
+1. Decorative elements
+2. Static content sections
+3. Footer links
+
+---
+
+## Step 3: Add Identifiers Systematically
+
+Go component by component. For each component:
+
+1. **Check the component's purpose** - What does it DO?
+2. **Add aria-label** to interactive elements describing the ACTION
+3. **Add data-testid** to the container if it's a major section
+4. **Add role** if the semantic HTML isn't clear
+5. **Add state attributes** if the component has dynamic states
+
+### Naming Conventions
+
+**aria-label**: Describe the action, not the element
+- ✅ `aria-label="Close modal"`
+- ✅ `aria-label="Submit contact form"`
+- ❌ `aria-label="Button"`
+- ❌ `aria-label="Click here"`
+
+**data-testid**: Use kebab-case, describe the section
+- ✅ `data-testid="user-profile-card"`
+- ✅ `data-testid="search-results-list"`
+- ❌ `data-testid="div1"`
+- ❌ `data-testid="container"`
+
+---
+
+## Step 4: Verify Coverage
+
+After adding identifiers, check coverage:
+
+```bash
+# Count aria-labels added
+grep -r "aria-label" src/ --include="*.tsx" | wc -l
+
+# Count data-testid added
+grep -r "data-testid" src/ --include="*.tsx" | wc -l
+
+# Count role attributes
+grep -r "role=" src/ --include="*.tsx" | wc -l
+
+# List all data-testid values (check for meaningful names)
+grep -oh 'data-testid="[^"]*"' src/ -r --include="*.tsx" | sort -u
+```
+
+---
+
+## Step 5: Commit
+
+```bash
+git add src/
+git commit -m "Add accessibility attributes for verification
+
+- Added aria-labels to interactive elements
+- Added data-testid to major sections
+- Added ARIA roles for semantic structure
+- Added state indicators (aria-expanded, etc.)"
+```
+
+---
+
+## Quick Reference: Common Patterns
+
+### Icon Button
+```tsx
+<button onClick={onAction} aria-label="Descriptive action name">
+  <Icon />
+</button>
+```
+
+### Modal
+```tsx
+<div role="dialog" aria-modal="true" aria-labelledby="modal-title" data-testid="settings-modal">
+  <h2 id="modal-title">Settings</h2>
+  <button onClick={onClose} aria-label="Close settings">×</button>
+</div>
+```
+
+### Navigation
+```tsx
+<nav aria-label="Main navigation" data-testid="main-nav">
+  <a href="/dashboard" aria-current={isActive ? "page" : undefined}>Dashboard</a>
+</nav>
+```
+
+### Toggle
+```tsx
+<button
+  onClick={toggle}
+  aria-pressed={isOn}
+  aria-label={`${isOn ? 'Disable' : 'Enable'} notifications`}
+>
+  {isOn ? 'On' : 'Off'}
+</button>
+```
+
+### Loading State
+```tsx
+<div data-testid="content-area" aria-busy={isLoading}>
+  {isLoading ? (
+    <div role="status" aria-label="Loading content">
+      <Spinner />
+    </div>
+  ) : (
+    content
+  )}
+</div>
+```
+
+### Form Field
+```tsx
+<div data-testid="email-field">
+  <label htmlFor="email">Email</label>
+  <input
+    id="email"
+    type="email"
+    aria-describedby={error ? "email-error" : "email-hint"}
+    aria-invalid={!!error}
+  />
+  <span id="email-hint">We'll never share your email</span>
+  {error && <span id="email-error" role="alert">{error}</span>}
+</div>
+```
+
+### Expandable Section
+```tsx
+<div data-testid="faq-section">
+  <button
+    onClick={() => setExpanded(!expanded)}
+    aria-expanded={expanded}
+    aria-controls="faq-content"
+  >
+    FAQ
+  </button>
+  <div id="faq-content" hidden={!expanded}>
+    {content}
+  </div>
+</div>
+```

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