swarm-tickets 1.0.0

package/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Swarm Tickets
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,238 @@
+# 🎫 Swarm Tickets
+
+Lightweight ticket tracking system designed for AI-powered bug fixing workflows with Claude-flow/Claude Code.
+
+Track bugs, errors, and issues in a simple JSON file that both humans and AI agents can read and update. Perfect for projects where you want Claude to autonomously fix tickets.
+
+## ✨ Features
+
+- 📝 **Simple JSON-based storage** - No database required
+- 🤖 **AI-friendly format** - Designed for Claude swarm workflows
+- 🎨 **Beautiful web UI** - View and manage tickets in your browser
+- 💾 **Automatic backups** - Never lose ticket history
+- 🔧 **RESTful API** - Integrate with any tool
+- ⚙️ **Configurable labels** - Customize field names for your project
+- 📋 **Quick prompt generation** - Copy Claude-ready prompts with one click
+- 🔄 **Auto port detection** - No conflicts with existing services
+
+## 📦 Installation
+
+```bash
+npm install swarm-tickets
+```
+
+After installation, the package will automatically set up:
+- `.claude/skills/swarm-tickets/` - Claude skill documentation
+- `ticket-tracker.html` - Web interface (in your project root)
+- `tickets.json` - Ticket storage file
+
+## 🚀 Quick Start
+
+### 1. Start the server
+
+```bash
+npx swarm-tickets
+```
+
+This starts the API server on port 3456 (or next available port).
+
+### 2. Open the web UI
+
+Navigate to `http://localhost:3456/ticket-tracker.html`
+
+### 3. Create your first ticket
+
+Use the web UI or API:
+
+```bash
+curl -X POST http://localhost:3456/api/tickets \
+  -H "Content-Type: application/json" \
+  -d '{
+    "route": "/dashboard/users",
+    "f12Errors": "TypeError: Cannot read property...",
+    "serverErrors": "Error connecting to database",
+    "description": "User list not loading",
+    "status": "open"
+  }'
+```
+
+### 4. Let Claude fix it
+
+Click the "📋 Quick Prompt" button on any ticket, paste into Claude Code/flow, and watch it work!
+
+## 🤖 Using with Claude
+
+The package includes a Claude skill that teaches Claude how to:
+- Read and update tickets from `tickets.json`
+- Set priorities and track related tickets
+- Add swarm actions documenting fixes
+- Update status as work progresses
+
+Just reference the ticket ID in your prompt:
+
+```
+Please investigate and fix ticket TKT-1234567890
+```
+
+Claude will:
+1. Read the ticket details from `tickets.json`
+2. Investigate the errors
+3. Fix the issue
+4. Update the ticket with status and actions taken
+
+## ⚙️ Configuration
+
+### Custom Project Name & Labels
+
+Go to Settings in the web UI to customize:
+- Project name
+- Field labels (e.g., "Location" instead of "Route/Webpage")
+- Error section names
+- Quick prompt template
+
+Settings are saved to localStorage and persist across sessions.
+
+### Custom Port
+
+```bash
+PORT=4000 npx swarm-tickets
+```
+
+Or the server will automatically find the next available port if 3456 is busy.
+
+## 📖 API Reference
+
+### Get all tickets
+```
+GET /api/tickets
+```
+
+### Get single ticket
+```
+GET /api/tickets/:id
+```
+
+### Create ticket
+```
+POST /api/tickets
+Content-Type: application/json
+
+{
+  "route": "/page/path",
+  "f12Errors": "Browser console errors",
+  "serverErrors": "Server console errors", 
+  "description": "Optional description",
+  "status": "open|in-progress|fixed|closed"
+}
+```
+
+### Update ticket
+```
+PATCH /api/tickets/:id
+Content-Type: application/json
+
+{
+  "status": "fixed",
+  "priority": "high",
+  "namespace": "components/UserList",
+  "swarmActions": [...]
+}
+```
+
+### Add swarm action
+```
+POST /api/tickets/:id/swarm-action
+Content-Type: application/json
+
+{
+  "action": "Fixed null reference in UserList component",
+  "result": "Tested and verified working"
+}
+```
+
+### Delete ticket
+```
+DELETE /api/tickets/:id
+```
+
+### Get stats
+```
+GET /api/stats
+```
+
+## 📁 File Structure
+
+After installation:
+
+```
+your-project/
+├── .claude/
+│   └── skills/
+│       └── swarm-tickets/
+│           └── SKILL.md          # Claude skill documentation
+├── ticket-backups/               # Automatic backups (last 10)
+├── ticket-tracker.html           # Web UI
+├── tickets.json                  # Your tickets
+└── node_modules/
+    └── swarm-tickets/
+```
+
+## 🔧 Local Development
+
+Testing the package locally before publishing:
+
+```bash
+# In your test project
+npm install /path/to/swarm-tickets
+
+# If files weren't copied automatically (local install issue)
+node node_modules/swarm-tickets/setup.js
+
+# Start the server
+npx swarm-tickets
+```
+
+## 🗑️ .gitignore
+
+Add to your `.gitignore` if you don't want to commit tickets:
+
+```
+tickets.json
+ticket-backups/
+```
+
+## 📜 License
+
+MIT
+
+## 🤝 Contributing
+
+Built for the Claude community! Issues and PRs welcome.
+
+## 💡 Tips
+
+- Use the **Quick Prompt** button to generate Claude-ready prompts
+- Set **priorities** to help Claude focus on critical issues first
+- Add **swarm actions** to document what was fixed and how
+- Use **namespaces** to track which files/components were modified
+- Link **related tickets** to help Claude understand patterns
+
+## 🐛 Troubleshooting
+
+### Postinstall script didn't run (local install)
+```bash
+node node_modules/swarm-tickets/setup.js
+```
+
+### Port 3456 is busy
+The server will automatically find the next available port. Or set a custom port:
+```bash
+PORT=4000 npx swarm-tickets
+```
+
+### Files not showing up
+Make sure you're in your project directory when running `npx swarm-tickets`. The server looks for `tickets.json` in the current directory.
+
+---
+
+Made with ❤️ for Claude-powered development workflows

package/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: Swarm Tickets
+description: Track and manage bug tickets for swarm-based development. Use when working with project tickets, bugs, or when asked to check open issues, fix tickets, or update ticket status.
+---
+
+# Swarm Tickets Skill
+
+This skill enables you to track and manage bug tickets in the project.
+
+## Overview
+
+The project uses `swarm-tickets` for bug tracking. Tickets are stored in `./tickets.json` at the project root.
+
+## Ticket Structure
+
+```json
+{
+  "tickets": [
+    {
+      "id": "TKT-1234567890",
+      "route": "/dashboard/users",
+      "f12Errors": "Browser console errors",
+      "serverErrors": "Server-side errors",
+      "description": "Additional context",
+      "status": "open|in-progress|fixed|closed",
+      "priority": "critical|high|medium|low",
+      "relatedTickets": ["TKT-xxx"],
+      "swarmActions": [
+        {
+          "timestamp": "ISO timestamp",
+          "action": "What you did",
+          "result": "What happened"
+        }
+      ],
+      "namespace": "where/fixes/applied",
+      "createdAt": "ISO timestamp",
+      "updatedAt": "ISO timestamp"
+    }
+  ]
+}
+```
+
+## Working with Tickets
+
+### Before You Start
+
+Always create a backup before modifying tickets.json:
+
+```javascript
+const fs = require('fs').promises;
+await fs.copyFile('tickets.json', `tickets.backup.${Date.now()}.json`);
+```
+
+### Reading Tickets
+
+```javascript
+const fs = require('fs').promises;
+const data = JSON.parse(await fs.readFile('tickets.json', 'utf8'));
+const tickets = data.tickets;
+
+// Find open tickets
+const openTickets = tickets.filter(t => t.status === 'open');
+
+// Find high priority tickets
+const highPriority = tickets.filter(t => t.priority === 'high' || t.priority === 'critical');
+
+// Find tickets for a specific route
+const routeTickets = tickets.filter(t => t.route.includes('/dashboard'));
+```
+
+### Updating Tickets
+
+When working on a ticket:
+
+```javascript
+// 1. Set status to in-progress
+ticket.status = 'in-progress';
+
+// 2. Add a swarm action
+ticket.swarmActions.push({
+  timestamp: new Date().toISOString(),
+  action: 'Investigating database connection error',
+  result: null
+});
+
+// 3. Update timestamp
+ticket.updatedAt = new Date().toISOString();
+
+// 4. Write back
+await fs.writeFile('tickets.json', JSON.stringify(data, null, 2));
+```
+
+When you fix a ticket:
+
+```javascript
+ticket.status = 'fixed';
+ticket.namespace = 'database/connection';
+ticket.swarmActions.push({
+  timestamp: new Date().toISOString(),
+  action: 'Added connection retry logic and proper error handling',
+  result: 'Fixed - tested with 3 connection failures, all recovered successfully'
+});
+ticket.updatedAt = new Date().toISOString();
+
+await fs.writeFile('tickets.json', JSON.stringify(data, null, 2));
+```
+
+### Setting Priority
+
+Assign priority based on severity:
+
+- **critical**: System down, auth broken, payment failures, data loss
+- **high**: Major features broken, uncaught errors, crashes
+- **medium**: Minor features broken, non-critical errors
+- **low**: UI issues, warnings, optimization opportunities
+
+```javascript
+if (!ticket.priority) {
+  // Analyze errors and set priority
+  if (ticket.route.includes('auth') || ticket.route.includes('payment')) {
+    ticket.priority = 'critical';
+  } else if (ticket.serverErrors.includes('crash') || ticket.f12Errors.includes('Uncaught')) {
+    ticket.priority = 'high';
+  } else if (ticket.serverErrors.includes('Error') || ticket.f12Errors.includes('Error')) {
+    ticket.priority = 'medium';
+  } else {
+    ticket.priority = 'low';
+  }
+}
+```
+
+### Linking Related Tickets
+
+Find and link related tickets:
+
+```javascript
+// Find tickets on the same route
+const related = tickets
+  .filter(t => t.id !== ticket.id && t.route === ticket.route)
+  .map(t => t.id);
+
+if (related.length > 0) {
+  ticket.relatedTickets = related;
+}
+```
+
+### Setting Namespace
+
+Document where fixes were applied:
+
+```javascript
+// Examples:
+ticket.namespace = 'auth/login';
+ticket.namespace = 'database/connection';
+ticket.namespace = 'ui/dashboard';
+ticket.namespace = 'api/users';
+```
+
+## Best Practices
+
+1. **Always backup before modifying** - Copy tickets.json before changes
+2. **Update timestamps** - Set `updatedAt` when changing tickets
+3. **Log your actions** - Add entries to `swarmActions` for everything you do
+4. **Set priorities** - Help triage by assigning priority levels
+5. **Link related tickets** - Connect tickets that affect the same area
+6. **Document namespaces** - Record where fixes were applied
+7. **Be specific** - In swarm actions, explain what you did and why
+
+## Workflow Example
+
+```javascript
+const fs = require('fs').promises;
+
+// 1. Backup
+await fs.copyFile('tickets.json', `tickets.backup.${Date.now()}.json`);
+
+// 2. Read tickets
+const data = JSON.parse(await fs.readFile('tickets.json', 'utf8'));
+
+// 3. Find open tickets
+const openTickets = data.tickets.filter(t => t.status === 'open');
+
+// 4. Work on highest priority first
+openTickets.sort((a, b) => {
+  const priority = { critical: 4, high: 3, medium: 2, low: 1 };
+  return (priority[b.priority] || 0) - (priority[a.priority] || 0);
+});
+
+// 5. Update ticket as you work
+const ticket = openTickets[0];
+ticket.status = 'in-progress';
+ticket.swarmActions.push({
+  timestamp: new Date().toISOString(),
+  action: 'Started fixing database column issue',
+  result: null
+});
+ticket.updatedAt = new Date().toISOString();
+
+// 6. Write back after each change
+await fs.writeFile('tickets.json', JSON.stringify(data, null, 2));
+
+// ... do the fix ...
+
+// 7. Mark as fixed
+ticket.status = 'fixed';
+ticket.namespace = 'database/schema';
+ticket.swarmActions.push({
+  timestamp: new Date().toISOString(),
+  action: 'Added missing org_id column to committees table',
+  result: 'Fixed - column added via migration, tested successfully'
+});
+ticket.updatedAt = new Date().toISOString();
+
+await fs.writeFile('tickets.json', JSON.stringify(data, null, 2));
+```
+
+## UI Access
+
+Users can view and create tickets via the web UI:
+
+- Start server: `npm start` (in project root or `npx swarm-tickets`)
+- Open: http://localhost:3456/ticket-tracker.html
+
+The UI allows users to:
+- Create new tickets with F12 and server errors
+- View all tickets with filtering and search
+- See ticket status, priority, and swarm actions
+
+## Notes
+
+- Tickets persist in `tickets.json` at project root
+- The server auto-backs up to `ticket-backups/` before writes (if running)
+- Manual backups recommended: Copy tickets.json before major changes
+- Recovery: Restore from `ticket-backups/` folder (keeps last 10)
+- The UI and the swarm both work with the same `tickets.json` file

package/backup-tickets.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+
+# Ticket tracker backup script
+# Keeps last 20 backups, rotates automatically
+
+BACKUP_DIR="./ticket-backups"
+TIMESTAMP=$(date +%Y%m%d-%H%M%S)
+
+# Create backup directory if it doesn't exist
+mkdir -p "$BACKUP_DIR"
+
+# Check if tickets.json exists
+if [ ! -f "tickets.json" ]; then
+    echo "❌ tickets.json not found"
+    exit 1
+fi
+
+# Create backup
+cp tickets.json "$BACKUP_DIR/tickets-$TIMESTAMP.json"
+
+if [ $? -eq 0 ]; then
+    echo "✅ Backup created: $BACKUP_DIR/tickets-$TIMESTAMP.json"
+else
+    echo "❌ Backup failed"
+    exit 1
+fi
+
+# Keep only last 20 backups
+BACKUP_COUNT=$(ls -1 "$BACKUP_DIR"/tickets-*.json 2>/dev/null | wc -l)
+
+if [ "$BACKUP_COUNT" -gt 20 ]; then
+    REMOVE_COUNT=$((BACKUP_COUNT - 20))
+    ls -t "$BACKUP_DIR"/tickets-*.json | tail -n "$REMOVE_COUNT" | xargs rm
+    echo "🗑️  Removed $REMOVE_COUNT old backup(s)"
+fi
+
+# Show backup count
+FINAL_COUNT=$(ls -1 "$BACKUP_DIR"/tickets-*.json 2>/dev/null | wc -l)
+echo "📦 Total backups: $FINAL_COUNT"

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "swarm-tickets",
+  "version": "1.0.0",
+  "description": "Lightweight ticket tracking system for AI-powered bug fixing with Claude-flow/Claude Code",
+  "main": "ticket-server.js",
+  "bin": {
+    "swarm-tickets": "./ticket-server.js"
+  },
+  "scripts": {
+    "start": "node ticket-server.js",
+    "ticket": "node ticket-cli.js",
+    "postinstall": "node setup.js"
+  },
+  "files": [
+    "ticket-server.js",
+    "ticket-cli.js",
+    "ticket-tracker.html",
+    "backup-tickets.sh",
+    "tickets.example.json",
+    "setup.js",
+    "SKILL.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "tickets",
+    "bug-tracker",
+    "issue-tracker",
+    "swarm",
+    "claude",
+    "claude-flow",
+    "claude-code",
+    "ai",
+    "automation",
+    "development-tools"
+  ],
+  "dependencies": {
+    "express": "^4.18.2",
+    "cors": "^2.8.5"
+  },
+"repository": {
+  "type": "git",
+  "url": "git+https://github.com/AIWhispererGal/swarm-tickets.git"
+},
+"bugs": {
+  "url": "https://github.com/AIWhispererGal/swarm-tickets/issues"
+},
+"homepage": "https://github.com/AIWhispererGal/swarm-tickets#readme",
+  "author": "AIWhispererGal and Claude Sonnet 4.5",
+  "license": "MIT",
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}

package/setup.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+console.log('\n🎫 Setting up Swarm Tickets...\n');
+
+// Get the project root (where package.json is)
+const projectRoot = process.cwd();
+
+// Create .claude/skills/swarm-tickets directory (correct location!)
+const skillsDir = path.join(projectRoot, '.claude', 'skills', 'swarm-tickets');
+
+try {
+  // Create directories
+  fs.mkdirSync(skillsDir, { recursive: true });
+  console.log('✅ Created .claude/skills/swarm-tickets/');
+
+  // Copy SKILL.md to the skills directory
+  const skillSource = path.join(__dirname, 'SKILL.md');
+  const skillDest = path.join(skillsDir, 'SKILL.md');
+  
+  if (fs.existsSync(skillSource)) {
+    fs.copyFileSync(skillSource, skillDest);
+    console.log('✅ Installed swarm skill');
+  }
+
+  // Copy ticket-tracker.html to project root
+  const htmlSource = path.join(__dirname, 'ticket-tracker.html');
+  const htmlDest = path.join(projectRoot, 'ticket-tracker.html');
+  
+  if (!fs.existsSync(htmlDest)) {
+    fs.copyFileSync(htmlSource, htmlDest);
+    console.log('✅ Copied ticket-tracker.html to project root');
+  } else {
+    console.log('⚠️  ticket-tracker.html already exists, skipping');
+  }
+
+  // Create tickets.json if it doesn't exist
+  const ticketsFile = path.join(projectRoot, 'tickets.json');
+  if (!fs.existsSync(ticketsFile)) {
+    fs.writeFileSync(ticketsFile, JSON.stringify({ tickets: [] }, null, 2));
+    console.log('✅ Created tickets.json');
+  }
+
+  console.log('\n🎉 Setup complete!\n');
+  console.log('To start the ticket tracker:');
+  console.log('  npm start\n');
+  console.log('Then open: http://localhost:3456/ticket-tracker.html\n');
+  console.log('The swarm can now access tickets via ./tickets.json');
+  console.log('Skill documentation: .claude/skills/swarm-tickets/SKILL.md\n');
+  
+  console.log('📝 Note: Add these to your .gitignore if you don\'t want to commit tickets:');
+  console.log('  tickets.json');
+  console.log('  ticket-backups/\n');
+
+} catch (error) {
+  console.error('❌ Setup failed:', error.message);
+  process.exit(1);
+}