@datatamer.ai/agentdev 1.0.7 → 1.0.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datatamer.ai/agentdev",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "description": "AgentDev distributed agent client for processing GitHub tickets",
   "type": "module",
   "main": "src/index.js",

package/skills/agentdev-artifact.md

@@ -0,0 +1,417 @@
+# agentdev artifact — Artifact Management
+
+Create and manage artifacts (HTML previews, images, videos, etc.) with semantic search powered by Voyage AI embeddings.
+
+## What are Artifacts?
+
+Artifacts are interactive files created during the development workflow:
+- **HTML previews** — Interactive mockups, prototypes, dashboards
+- **Images** — Screenshots, diagrams, wireframes
+- **Videos** — Demo recordings, tutorials
+- **JSON/Markdown** — Configuration files, documentation
+
+All artifacts are stored with vector embeddings for semantic search and are accessible via secure preview URLs.
+
+---
+
+## Create Artifact
+
+Upload a file as an artifact with automatic embedding generation:
+
+```bash
+# Create HTML artifact
+agentdev artifact create \
+  --file /path/to/preview.html \
+  --title "Homepage Redesign Preview" \
+  --desc "Interactive Tailwind CSS prototype" \
+  --ticket 123
+
+# Create image artifact
+agentdev artifact create \
+  --file /tmp/screenshot.png \
+  --title "Login Page Screenshot" \
+  --ticket 456 \
+  --type "image/png"
+
+# Create with custom metadata
+agentdev artifact create \
+  --file dashboard.html \
+  --title "Analytics Dashboard" \
+  --metadata '{"framework":"react","responsive":true}'
+```
+
+**Output:**
+```
+✅ Artifact created successfully!
+   ID: aa891069-14f9-43e8-8ea9-de6438e501c9
+   Preview: https://agentdev.datatamer.ai/preview/aa891069-14f9-43e8-8ea9-de6438e501c9
+```
+
+**Important:**
+- Preview URL is automatically posted as a GitHub comment on the associated ticket
+- Embedding is generated asynchronously (takes ~800ms)
+- Max file size: 10MB
+
+---
+
+## Read Artifact
+
+Get artifact details and metadata:
+
+```bash
+# Human-readable output
+agentdev artifact read aa891069-14f9-43e8-8ea9-de6438e501c9
+
+# JSON output (for parsing)
+agentdev artifact read aa891069-14f9-43e8-8ea9-de6438e501c9 --json
+```
+
+**Output:**
+```
+Artifact Details:
+  ID: aa891069-14f9-43e8-8ea9-de6438e501c9
+  Title: Homepage Redesign Preview
+  Description: Interactive Tailwind CSS prototype
+  Type: text/html
+  Size: 15360 bytes
+  Ticket: 123
+  Created: 2026-02-16T10:30:00Z
+  Has Embedding: Yes
+  Preview: https://agentdev.datatamer.ai/preview/aa891069-...
+  Metadata: {"framework":"tailwind","responsive":true}
+```
+
+---
+
+## List Artifacts
+
+List all artifacts or filter by ticket:
+
+```bash
+# List all artifacts (default limit: 50)
+agentdev artifact list
+
+# Filter by ticket
+agentdev artifact list --ticket 123
+
+# Limit results
+agentdev artifact list --limit 10
+
+# JSON output
+agentdev artifact list --ticket 123 --json
+```
+
+**Output:**
+```
+Found 3 artifact(s):
+
+1. Homepage Redesign Preview
+   ID: aa891069-14...
+   Type: text/html
+   Size: 15360 bytes
+   Created: 2/16/2026, 10:30:00 AM
+
+2. Login Page Screenshot
+   ID: ef4c103a-1d...
+   Type: image/png
+   Size: 248576 bytes
+   Created: 2/16/2026, 11:15:00 AM
+```
+
+---
+
+## Search Artifacts (Semantic)
+
+Search artifacts by natural language query using vector similarity:
+
+```bash
+# Search by content/description
+agentdev artifact search "landing page designs"
+
+# Limit results
+agentdev artifact search "dashboard mockups" --limit 5
+
+# Filter by ticket
+agentdev artifact search "homepage" --ticket 123
+
+# JSON output
+agentdev artifact search "authentication UI" --json
+```
+
+**Output:**
+```
+Found 2 similar artifact(s):
+
+1. Homepage Redesign Preview
+   Similarity: 87.3%
+   Type: text/html
+   ID: aa891069-14...
+   Created: 2/16/2026
+
+2. Landing Page Wireframe
+   Similarity: 75.6%
+   Type: image/png
+   ID: 962bae25-65...
+   Created: 2/15/2026
+```
+
+**How it works:**
+- Query is converted to a 1024-dimensional embedding via Voyage AI
+- PostgreSQL pgvector performs cosine similarity search
+- Results ranked by similarity percentage
+
+---
+
+## Update Artifact
+
+Update artifact content, title, or metadata:
+
+```bash
+# Update file content
+agentdev artifact update aa891069-14f9-43e8-8ea9-de6438e501c9 \
+  --file /path/to/updated.html
+
+# Update title and description
+agentdev artifact update aa891069-14f9-43e8-8ea9-de6438e501c9 \
+  --title "Homepage v2" \
+  --desc "Updated with user feedback"
+
+# Update metadata
+agentdev artifact update aa891069-14f9-43e8-8ea9-de6438e501c9 \
+  --metadata '{"version":"2.0","responsive":true}'
+```
+
+**Note:** Updating content triggers automatic re-generation of embeddings
+
+---
+
+## Delete Artifact
+
+Permanently delete an artifact:
+
+```bash
+agentdev artifact delete aa891069-14f9-43e8-8ea9-de6438e501c9
+```
+
+**Output:**
+```
+✅ Artifact aa891069-14f9-43e8-8ea9-de6438e501c9 deleted successfully
+```
+
+**Important:**
+- Artifacts are automatically deleted when their associated ticket is deleted (CASCADE)
+- Orphaned artifacts (no ticket) are auto-deleted after 30 days
+
+---
+
+## Preview Artifact
+
+Open artifact preview in browser:
+
+```bash
+agentdev artifact preview aa891069-14f9-43e8-8ea9-de6438e501c9
+```
+
+Opens the preview URL in the default browser. Preview URLs are:
+- **Authenticated** — Requires session login
+- **Sandboxed** — HTML rendered in iframe with CSP headers
+- **Secure** — No external script execution
+
+---
+
+## Workflow Integration
+
+### Phase 2.5: OpenSpec Preview (Auto-Ticket Workflow)
+
+After generating the OpenSpec in Phase 2, create an artifact for the preview:
+
+```bash
+# Generate HTML preview from OpenSpec
+openspec_html="/tmp/openspec-preview-${TICKET_ID}.html"
+cat > "$openspec_html" <<EOF
+<!DOCTYPE html>
+<html>
+<head>
+  <title>${TICKET_TITLE} - OpenSpec Preview</title>
+  <style>
+    body { font-family: system-ui; max-width: 900px; margin: 40px auto; padding: 20px; }
+    .task { background: #f5f5f5; padding: 15px; margin: 10px 0; border-radius: 8px; }
+  </style>
+</head>
+<body>
+  <h1>${TICKET_TITLE}</h1>
+  <div class="task">
+    <h3>Task 1: Implement Feature</h3>
+    <p>Details...</p>
+  </div>
+</body>
+</html>
+EOF
+
+# Upload artifact
+ARTIFACT_OUTPUT=$(agentdev artifact create \
+  --file "$openspec_html" \
+  --title "${TICKET_TITLE} - OpenSpec Preview" \
+  --desc "Interactive preview of proposed implementation" \
+  --ticket "$TICKET_ID")
+
+# Extract artifact ID from output
+ARTIFACT_ID=$(echo "$ARTIFACT_OUTPUT" | grep "ID:" | awk '{print $2}')
+
+echo "✅ OpenSpec artifact created: $ARTIFACT_ID"
+# Preview URL automatically posted to GitHub issue
+```
+
+---
+
+## Supported File Types
+
+| Type | MIME Type | Extension | Storage |
+|------|-----------|-----------|---------|
+| HTML | `text/html` | `.html` | TEXT |
+| JSON | `application/json` | `.json` | TEXT |
+| Markdown | `text/markdown` | `.md` | TEXT |
+| Plain Text | `text/plain` | `.txt` | TEXT |
+| PNG Image | `image/png` | `.png` | BYTEA (Base64) |
+| JPEG Image | `image/jpeg` | `.jpg`, `.jpeg` | BYTEA (Base64) |
+| GIF Image | `image/gif` | `.gif` | BYTEA (Base64) |
+| SVG Image | `image/svg+xml` | `.svg` | TEXT |
+| MP4 Video | `video/mp4` | `.mp4` | BYTEA (Base64) |
+| PDF Document | `application/pdf` | `.pdf` | BYTEA (Base64) |
+
+**Auto-detection:** MIME type is auto-detected from file extension if `--type` is omitted
+
+---
+
+## Preview Rendering
+
+Different file types are rendered differently in the preview:
+
+- **HTML** → Sandboxed iframe with full CSS support
+- **Images** → Full-size display with zoom controls
+- **Videos** → HTML5 video player
+- **JSON** → Syntax-highlighted pretty-print
+- **PDF** → Embedded PDF viewer or download link
+- **Markdown** → Rendered HTML preview
+
+---
+
+## Security
+
+All artifacts follow these security rules:
+
+1. **Session Authentication** — Preview URLs require valid session cookie
+2. **Iframe Sandbox** — HTML rendered with `sandbox="allow-scripts allow-same-origin"` (no top navigation)
+3. **CSP Headers** — `Content-Security-Policy: default-src 'self' 'unsafe-inline'`
+4. **No External Resources** — Blocks loading external scripts, images, or fonts
+5. **File Size Limit** — 10MB maximum per artifact
+6. **UUID-based URLs** — Non-guessable preview URLs (e.g., `/preview/aa891069-14f9-43e8-8ea9-de6438e501c9`)
+
+---
+
+## API Endpoints (For Reference)
+
+The CLI uses these server endpoints:
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/agent/artifact` | POST | Create artifact (requires JWT token) |
+| `/api/artifacts/:id` | GET | Get artifact metadata |
+| `/api/artifacts` | GET | List artifacts (filter by ticket) |
+| `/api/artifacts/:id` | PUT | Update artifact |
+| `/api/artifacts/:id` | DELETE | Delete artifact |
+| `/api/artifacts/search` | POST | Semantic search |
+| `/preview/:id` | GET | Preview artifact (session auth) |
+
+---
+
+## Examples
+
+### Create HTML Dashboard
+
+```bash
+# Save HTML to file
+cat > /tmp/dashboard.html <<'EOF'
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Sales Dashboard</title>
+  <style>
+    body { font-family: Arial; padding: 20px; background: #f0f0f0; }
+    .card { background: white; padding: 20px; margin: 10px; border-radius: 8px; }
+    .metric { font-size: 48px; color: #2563eb; font-weight: bold; }
+  </style>
+</head>
+<body>
+  <div class="card">
+    <h2>Total Sales</h2>
+    <div class="metric">$125,430</div>
+  </div>
+</body>
+</html>
+EOF
+
+# Create artifact
+agentdev artifact create \
+  --file /tmp/dashboard.html \
+  --title "Q1 Sales Dashboard" \
+  --desc "Real-time sales metrics" \
+  --ticket 789 \
+  --metadata '{"quarter":"Q1","year":2026}'
+```
+
+### Find Similar Artifacts
+
+```bash
+# Search for dashboard-related artifacts
+agentdev artifact search "sales dashboard analytics" --limit 10
+
+# Filter by specific ticket
+agentdev artifact search "UI mockup" --ticket 123
+```
+
+---
+
+## Performance
+
+| Operation | Time | Notes |
+|-----------|------|-------|
+| Create artifact | ~100ms | Database insert only |
+| Generate embedding | ~800ms | Voyage AI API call (async) |
+| Store embedding | ~50ms | PostgreSQL vector insert |
+| Retrieve artifact | ~30ms | Database query |
+| Semantic search | ~200ms | pgvector cosine similarity |
+| **Total workflow** | **~1.2s** | Create + embed + store + search |
+
+---
+
+## Notes
+
+- **Embeddings are generated asynchronously** — Artifact is created immediately, embedding generated in background
+- **Preview links auto-posted to GitHub** — When ticket_id is provided, preview URL is commented on the issue
+- **Cascade deletion** — Artifacts deleted when parent ticket is deleted
+- **Auto-cleanup** — Orphaned artifacts (no ticket) deleted after 30 days
+- **Voyage AI 3.5 Lite** — Uses 1024-dimensional embeddings optimized for semantic search
+- **pgvector** — PostgreSQL extension for efficient vector similarity search
+
+---
+
+## Troubleshooting
+
+**Error: "File too large"**
+- Max file size is 10MB
+- Compress images or split videos before uploading
+
+**Error: "VOYAGE_API_KEY not configured"**
+- Contact admin to add API key to server configuration
+- Embeddings cannot be generated without API key
+
+**Preview not loading**
+- Ensure you're logged in (session cookie required)
+- Check that artifact ID is correct
+- Verify artifact hasn't been deleted
+
+**Search returns no results**
+- Wait ~2 seconds for embedding generation after creation
+- Try broader search terms
+- Check that artifacts have embeddings (`Has Embedding: Yes` in read output)