TICKET MATE

QUICK NOTES

1. Test tickets with ticket-mate sync --ticket NOVA-123

CURSOR DO NOT UPDATE THIS FILE

Jira integration and AI execution layer - Bridges Jira tickets and AI-assisted development workflows.

Jira AppSettings

https://developer.atlassian.com/console/myapps/

Overview

@ameshkin/ticket-mate is a production-ready npm package that provides comprehensive Jira integration capabilities. It includes a CLI interface, REST API server, Next.js dashboard, and automation features for managing Jira tickets, syncing progress files, generating AI prompts, building PR descriptions, and automating ticket creation from JSON files.

Database

https://console.prisma.io/cmixzg6nk03vo2sflg2pzq64u/cmixzgvue03sd1efplmdnimkj/cmixzgvue03se1efpm49q18z0/studio#table=users&schema=public&view=table

Error Logs

vercel logs ticket-mate.app

Vercel Environment Variables

# list env
vercel env ls


# pull all production vars into a test file .test-prod.env
vercel env pull .test-prod.env --environment=production


# Or if you want all environments in one file:
vercel env pull .env.vercel.production --environment=production

            "code": "OLLAMA_MODEL_MISSING",
            "message": "Model \"qwen2.5-coder:latest\n\" is not installed on http://72.61.71.227:11434. Using fallback \"qwen2.5-coder:latest\".",
            "requested": "qwen2.5-coder:latest\n",
            "fallbackUsed": "qwen2.5-coder:latest"


vercel env add GITHUB_CLIENT_ID development
# paste the value when prompted

vercel env add GITHUB_CLIENT_SECRET development

vercel env add NEXTAUTH_URL development


#remove if exists undefined
#https://jira-mate.vercel.app
vercel env ls production
vercel env rm NEXTAUTH_URL production --yes


vercel env add OLLAMA_DEMO_MODEL production
vercel env add OLLAMA_DEMO_MODEL development
vercel env add OLLAMA_DEMO_MODEL preview

vercel env add OLLAMA_CODE_MODEL development

OLLAMA_CODE_MODEL

qwen2.5-coder:7b

vercel env add NEXTAUTH_URL production
=https://ticket-mate.app


#https://ticket-mate.app

OLLAMA_CODE_MODEL=
OLLAMA_DEMO_MODEL=

# AI Runtime Configuration
AI_RUNTIME=auto


# VERCEL LOGS


vercel logs ticket-mate.app

RESEND_API_KEY=re_36qa2oNt_HyHhz8N9AXjtmnCkcDUGa3Wh



vercel env add DATABASE_URL production
#postgres://3bc59484969a8f4dd008a6300b7c79daa72fc00ec9db1d3545013fe8e48afd0c:[email protected]:5432/postgres?sslmode=require
#
#
#ATLASSIAN_WEBHOOK_PATH="/api/webhooks/jira"
#ATLASSIAN_PROJECT_KEY=JM


hostinger ollama
root

Brootgroot17+

export OLLAMA_BASE_URL="http://72.61.71.227:8080"
export OLLAMA_DEMO_MODEL="qwen2.5-coder:latest"



vercel env add GITHUB_CLIENT_ID development



cp /Users/amirmeshkin/_code/_work/proveoautomation/CHAT/Web/frontend/src/pages/admin/profile/ProfilePage.tsx




OLLAMA_BASE_URL

Ollama Server

ssh [email protected]


ssh -i /Users/amirmeshkin/.ssh/hostinger_ollama [email protected]



ollama pull qwen2.5-coder:14b

ollama run qwen2.5-coder:14b


ollama pull deepseek-coder

ORC MCP

LOCAL

ORC_MCP_BASE_URL=http://localhost:7777


ORC_MCP_BASE_URL=http://localhost:7777
ORC_MCP_CLIENT_ID=ticket-mate-internal
ORC_MCP_CLIENT_SECRET=sfagsdgfhmfghjrty
ORC_MCP_TIMEOUT_MS=30000
ORC_MCP_DRY_RUN_DEFAULT=true

cp -R
"/Users/amirmeshkin/_code/my-npm-packages/orchestrator-core"
"/Users/amirmeshkin/_code/my-npm-packages/orchestrator/_packages/nevaroAI/"

# copy CHAT from component examples to CHAT


cp -R \
"/Users/amirmeshkin/_code/_work/proveoautomation/component-examples/CHAT/" \
"/Users/amirmeshkin/_code/_work/proveoautomation/CHAT"





# copy CHAT from CHAT back to COMPONENT


cp -R \
"/Users/amirmeshkin/_code/_work/proveoautomation/CHAT/" \
"/Users/amirmeshkin/_code/_work/proveoautomation/component-examples/CHAT"

Demo Account and Page

https://www.ticket-mate.app/demo

[email protected] welcome123

Ticket Mate v1.0 Roadmap

Ticket Mate v1.0 unifies four pillars into a single coherent flow:

• ✅ Ticket Mate CLI + .ticket-mate - Command-line tools that sync Jira tickets to local markdown files
• ✅ Next.js Admin UI + Webhook - Web interface for viewing and managing tickets, bugs, and AI-assisted planning
• ⏳ Replit Extension - In-editor tool tab for working with tickets and bugs directly in Replit
• ✅ Orchestrator-derived bugs.json - Unified bug tracking that can be promoted to Jira Bug issues

All four pillars share the same data structures and read from the same .ticket-mate directory, ensuring consistency across tools.

Progress: 75% Complete (3 of 4 pillars fully implemented)

Completed Features:

• ✅ CLI with 20+ commands (tm, ticket-mate)
• ✅ .ticket-mate file-based integration
• ✅ Next.js Admin UI with full dashboard
• ✅ OAuth authentication (GitHub, Google, Atlassian, Apple, Credentials)
• ✅ Jira REST API client
• ✅ Ticket syncing to markdown files
• ✅ AI prompt generation
• ✅ Board management with AI columns
• ✅ Bugs.json integration
• ✅ Webhook handling
• ✅ Git integration (branch/commit validation)

In Progress:

• ⏳ Replit Extension (planned - architecture defined, implementation pending)

Recent Completions (2025-01-12):

• ✅ Local email/password authentication
• ✅ OAuth security enhancements (CSRF protection, token encryption)
• ✅ Authentication-aware data fetching
• ✅ Production deployment (ticket-mate.app)
• ✅ Branding update (Ticket Mate → Ticket Mate)
• ✅ Ticket organization restructured (.orchestrator/tickets/)

Tracking:

• Progress: .orchestrator/tickets/
  • Epics: .orchestrator/tickets/epics/ (2 files)
  • Stories: .orchestrator/tickets/stories/ (1 file)
  • Bugs: .orchestrator/tickets/bugs/ (5 files)
  • Tasks: .orchestrator/tickets/tasks/ (9 files)
• Master Progress: .orchestrator/master-progress.md

Documentation:

• User Guide - Comprehensive guide for features and usage.
• API Documentation - Reference for API endpoints.

Features

Core Features

• ✅ Jira Integration - Full REST API client for Jira operations (OAuth + PAT support)
• ✅ Ticket Syncing - Sync Jira tickets to markdown files for documentation
• ✅ AI Prompts - Generate AI-consumable prompts from ticket briefs
• ✅ PR Builder - Generate structured PR descriptions from tickets
• ✅ CLI Interface - 20+ command-line tools (tm, ticket-mate)
• ✅ REST API Server - Next.js API routes with authentication
• ✅ Next.js Dashboard - Full web UI for projects, boards, tickets, and admin
• ✅ Board Management - Create boards, add columns (including "AI: In Progress")
• ✅ Automation - Process JSON files (bugs-wip.json) and create Jira tickets
• ✅ Git Integration - Branch and commit message validation
• ✅ Webhook Handling - Process Jira webhook events with security validation
• ✅ Acceptance Criteria - Extract and sync from test files
• ✅ File-based Integration - Repository-based ticket management for AI agents
• ✅ Authentication - Local email/password + OAuth (GitHub, Google, Atlassian, Apple)
• ✅ Token Management - AI token usage tracking and limits

Phase 5 Features (Completed)

• ✅ Authority - End-to-end provenance for audits.
• ✅ Reliability - Quality gates and health scorecards.
• ✅ Contracts - Team agreement management.
• ✅ Automation - Workflow builder (Triggers/Actions).
• ✅ Events - Real-time observability feed.
• ✅ Usage - Credit consumption tracking.

Advanced Features

• ✅ AI Execution Integration - Execute tickets with AI agents
• ✅ Queue Processing - Process queues of AI-ready tickets
• ✅ Batch Operations - Bulk sync and status updates
• ✅ Observability - Metrics and logging
• ✅ Template System - Customizable markdown templates
• ✅ Multi-tenant Support - Account-based organization with seat management
• ✅ Subscription Management - Plan tiers, billing, and usage limits

Feature Spotlight

🤖 AI-Driven Workflow

Ticket Mate bridges the gap between Jira and AI agents. It converts tickets into context-rich prompts that agents can understand.

import { buildTicketPrompts } from "@ameshkin/ticket-mate";

// Generate a comprehensive prompt for an AI agent
const prompts = await buildTicketPrompts({
  ticketKey: "NOVA-123",
  // Includes ticket details, acceptance criteria, and plan
  markdownPath: ".orchestrator/tickets/tasks/NOVA-123.md",
  repoRoot: process.cwd(),
});

console.log(prompts.system); // "You are an expert engineer..."
console.log(prompts.task); // "Implement feature X following these criteria..."

⚡ Automated Bug Filing

Turn JSON reports or linter output into Jira tickets automatically, preventing issue drift.

# Process a bugs.json file and create/update Jira tickets
ticket-mate process-bugs --file ./reports/security-audit.json --sync-status

// Programmatic automation
import { processJsonInstructionsDirect } from "@ameshkin/ticket-mate/api/automation";

await processJsonInstructionsDirect(
  {
    bugs: [{ title: "Memory Leak in Auth", severity: "critical" }],
  },
  { projectKey: "PROJ" }
);

🔐 Secure Multi-Mode Auth

Switch seamlessly between Personal Access Tokens for CLI usage and OAuth for SaaS deployment.

# Mode 1: Personal Access Token (CLI / Local)
ATLASSIAN_AUTH_MODE=PAT
[email protected]
ATLASSIAN_API_KEY=my-token

# Mode 2: OAuth 2.0 (SaaS / Multi-user)
ATLASSIAN_AUTH_MODE=OAUTH
ATLASSIAN_CLIENT_ID=...
ATLASSIAN_CLIENT_SECRET=...

For a deep dive into all features and architecture, see the Developer Documentation Index.

Installation

From GitHub Packages (Private)

First, configure npm to use GitHub Packages for the @ameshkin scope:

# Create or edit .npmrc in your project root
echo "@ameshkin:registry=https://npm.pkg.github.com" >> .npmrc
echo "//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN" >> .npmrc

Then install:

npm install @ameshkin/ticket-mate

Note: You need a GitHub Personal Access Token (PAT) with read:packages permission to install private packages.

Configuration

Environment Variables

Create a .env file or set environment variables:

Required Jira Configuration

ATLASSIAN_BASE_URL=https://pamcms.atlassian.net
[email protected]
ATLASSIAN_API_KEY=your-api-token

Optional:

ATLASSIAN_PROJECT_KEY=YOUR_PROJECT  # Optional: CLI prefers --project flag or config file

• Generate your Jira API token at: https://id.atlassian.com/manage-profile/security/api-tokens
• Important: Your Jira user must have "Create Issues" permission in the project
• Setup Jira Keys Guide - Complete guide for getting and configuring all Jira keys
• See Permissions & Access Guide for complete setup
• See Quick Permission Fix if you get permission errors
• See Jira Setup Guide for detailed instructions
• See ATLASSIAN_SCOPES.md for required OAuth scopes

Authentication Modes

ticket-mate supports two authentication modes:

1. Personal Access Token (PAT) - Default mode

   • Uses ATLASSIAN_EMAIL + ATLASSIAN_API_KEY for Basic Auth
   • Simple setup, good for local dev and single-user scenarios
   • Optional: ATLASSIAN_CLOUD_ID for Cloud API calls (not required)
   • Set ATLASSIAN_AUTH_MODE=PAT explicitly, or leave unset (defaults to PAT)

2. OAuth 2.0 - For production/SaaS

   • Uses ATLASSIAN_CLIENT_ID + ATLASSIAN_CLIENT_SECRET in env
   • Per-user tokens and cloudId stored in database (not in env)
   • Multi-user support, per-user authentication
   • Set ATLASSIAN_AUTH_MODE=OAUTH to enable
   • Atlassian Developer Console: View/Manage OAuth Apps
   • Required Callback URLs (register both in Atlassian Developer Console, one per line):
     • http://localhost:4000/api/auth/callback/atlassian (local dev)
     • https://ticket-mate.app/api/auth/callback/atlassian (production)
   • Environment Variables:
     • Local: NEXTAUTH_URL="http://localhost:4000", ATLASSIAN_CLIENT_ID, ATLASSIAN_CLIENT_SECRET
     • Production: NEXTAUTH_URL="https://ticket-mate.app", ATLASSIAN_CLIENT_ID, ATLASSIAN_CLIENT_SECRET
   • See OAuth Setup Guide for details
   • See OAuth Callback URL Setup for callback URL configuration

Important Notes:

• ATLASSIAN_CLOUD_ID is not required in env. In PAT mode it's optional for Cloud API. In OAuth mode it's stored per-connection in the database.
• ATLASSIAN_PROJECT_KEY is optional. CLI prefers --project flag or config file. Use env only as fallback.
• If you previously used ATLASSIAN_API_TOKEN, rename it to ATLASSIAN_API_KEY. The old variable is deprecated.

Cloud API Configuration (for Scoped API Tokens)

If you're using Atlassian scoped API tokens and projects/keys don't appear, enable cloud API mode:

ATLASSIAN_USE_CLOUD_API=true
ATLASSIAN_CLOUD_ID=your-cloud-id

How to find your Cloud ID:

1. Go to https://admin.atlassian.com
2. Select your site
3. Copy the Cloud ID from the URL or site settings

When to use Cloud API:

• Using scoped API tokens (long tokens starting with ATATT3x...)
• Projects are not appearing with standard configuration
• Getting 403/404 errors when listing projects

Cloud API URL format:

• Standard: https://pamcms.atlassian.net/rest/api/3
• Cloud API: https://api.atlassian.com/ex/jira/{cloudId}/rest/api/3

Alternatively, add to your jira.json:

{
  "baseUrl": "https://pamcms.atlassian.net",
  "email": "[email protected]",
  "apiToken": "your-token",
  "cloudId": "your-cloud-id",
  "useCloudApi": true
}

API Authentication (for Next.js API routes)

TICKET_MATE_API_KEY=your-secure-api-key
NEXT_PUBLIC_TICKET_MATE_API_KEY=your-secure-api-key

Dashboard Configuration (for Next.js dashboard)

NEXT_PUBLIC_ATLASSIAN_BASE_URL=https://pamcms.atlassian.net

Important: Never commit .env files - they contain sensitive credentials.

Quick Start

CLI Usage

# Test configuration
ticket-mate config:test

# Sync a single ticket
ticket-mate sync --ticket NOVA-123

# Sync all tickets in project
ticket-mate sync --all

# Generate AI prompt from ticket
ticket-mate prompt NOVA-123

# List projects
ticket-mate ls-projects

# List issues
ticket-mate ls-issues --status "In Progress"

# Create a board with AI column
ticket-mate create-board --name "Cursor Board" --ai-column

# Process bugs from JSON file
ticket-mate process-bugs --file public/bugs.json

# Show project information
ticket-mate project-info
ticket-mate project-info --health  # Include health check

# Run health check
ticket-mate health-check
ticket-mate health-check --fix  # Attempt to fix issues

# Quick sync with progress indicators
ticket-mate quick-sync --ticket NOVA-123
ticket-mate quick-sync --all

# Export tickets to various formats
ticket-mate export --format json --output tickets.json
ticket-mate export --format csv --status "In Progress"
ticket-mate export --format markdown --label "AI-READY"

# Batch operations
ticket-mate batch --keys "NOVA-123,NOVA-124" --action transition --status "Done"
ticket-mate batch --file tickets.txt --action comment --comment "Reviewed"
ticket-mate batch --keys "NOVA-123" --action update --labels "reviewed,tested"

# Export and batch operations
ticket-mate export --format json --output tickets.json
ticket-mate batch --keys "NOVA-123,NOVA-124" --action transition --status "Done"

Programmatic Usage

import {
  getJiraConfig,
  syncSingleTicket,
  buildTicketPrompts,
  listProjects,
} from "@ameshkin/ticket-mate";

// Get configuration
const config = getJiraConfig();

// Sync a ticket
const result = await syncSingleTicket("NOVA-123", config);

// Generate AI prompts
const prompts = await buildTicketPrompts({
  ticketKey: "NOVA-123",
  markdownPath: ".orchestrator/tickets/epics/NOVA-10/NOVA-123.md",
  repoRoot: process.cwd(),
});

// List projects
const projects = await listProjects();

Next.js Dashboard

The package includes a Next.js dashboard. Start it with:

npm run dev

Then visit http://localhost:4000 to see the dashboard with projects and boards.

Usage

CLI Commands

Sync Commands

# Sync specific ticket
ticket-mate sync --ticket NOVA-123

# Sync epic and all tickets
ticket-mate sync --epic NOVA-10

# Sync all tickets
ticket-mate sync --all

# Custom output directory
ticket-mate sync --all --output .custom-progress

Issue Management

# List projects
ticket-mate ls-projects

# List issues with filters
ticket-mate ls-issues --project NOVA --status "In Progress"
ticket-mate ls-issues --assignee me --label AI-READY
ticket-mate ls-issues --jql "project = NOVA AND status = 'In Progress'"

# Show issue details
ticket-mate show-issue NOVA-123

Board Management

# Create board with AI column
ticket-mate create-board --name "Cursor Board" --ai-column

# List boards for project
ticket-mate create-board --list

# Create board without AI column
ticket-mate create-board --name "Team Board" --no-ai-column

Automation

# Process bugs from JSON file
ticket-mate process-bugs --file public/bugs.json

# Watch for changes and auto-process
ticket-mate watch-bugs --file public/bugs.json --auto-process

# Sync bug statuses from Jira
ticket-mate process-bugs --file public/bugs.json --sync-status

AI & Prompts

# Generate AI prompt from a ticket
ticket-mate prompt NOVA-123

# Save prompt to file
ticket-mate prompt NOVA-123 --output nova-123.md

# Execute AI-assisted work
ticket-mate execute NOVA-123

# Process queue of AI-ready tickets
ticket-mate queue

Git Validation

# Validate branch name
ticket-mate validate-branch feature/NOVA-123-checkout

# Validate commit message
ticket-mate validate-commit "NOVA-123: Add checkout functionality"

Other Commands

# Check sync status
ticket-mate status

# Test configuration
ticket-mate config:test

# Create task folder
ticket-mate create-task-folder NOVA-123

# Sync acceptance criteria
ticket-mate sync-acceptance NOVA-123

# Interactive menu
ticket-mate interactive

File-based Integration: .ticket-mate

Ticket Mate provides a file-based integration system that allows AI agents (Cursor, Replit, etc.) to work with Jira tickets directly in your repository. This integration uses a .ticket-mate directory structure that is committed to Git and can be used by any AI agent.

Quick Start

# Initialize repository for Ticket Mate integration
tm init-repo --jira-base-url https://pamcms.atlassian.net --jira-project-key YOUR_PROJECT

# Sync tickets from Jira
tm sync-tickets

# Show status of local tickets
tm status

# Emit instructions for AI agents
tm emit-agent-instructions --agent cursor

Directory Structure

The .ticket-mate directory structure:

.ticket-mate/
  config.json              # Repository configuration
  tickets/
    <ATLASSIAN_KEY>/
      ticket.meta.json     # Ticket metadata (status, summary, etc.)
      plan.md              # High-level plan and objectives
      tasks.md             # Detailed task checklist
      progress.log.md      # Append-only progress log
      notes.md             # Free-form notes (user-editable)

Configuration

The .ticket-mate/config.json file contains:

{
  "jiraBaseUrl": "https://pamcms.atlassian.net",
  "jiraProjectKey": "YOUR_PROJECT",
  "jiraCloudId": "optional-cloud-id",
  "defaultBranch": "main",
  "integrations": {
    "cursor": {
      "enabled": true
    },
    "replit": {
      "enabled": true,
      "webhookUrl": "https://your-replit-webhook-url"
    }
  }
}

CLI Commands

tm init-repo

Initialize a repository for Ticket Mate integration:

tm init-repo --jira-base-url https://pamcms.atlassian.net --jira-project-key YOUR_PROJECT
tm init-repo --enable-replit --replit-webhook-url https://your-webhook-url

Options:

• --jira-base-url <url> - Jira base URL
• --jira-project-key <key> - Jira project key
• --jira-cloud-id <id> - Optional cloud ID
• --default-branch <branch> - Default Git branch (default: main)
• --enable-replit - Enable Replit integration
• --replit-webhook-url <url> - Replit webhook URL
• --enable-cursor - Enable Cursor integration

tm sync-tickets

Sync Jira issues into .ticket-mate/tickets/:

# Sync all tickets with default statuses
tm sync-tickets

# Sync specific statuses
tm sync-tickets --status "Ready for Dev" --status "In Progress"

# Limit number of tickets
tm sync-tickets --limit 10

# Dry run (show what would be created)
tm sync-tickets --dry-run

# Skip webhook notification
tm sync-tickets --no-webhook

tm status

Show status of tickets in .ticket-mate/tickets/:

# Show all tickets
tm status

# Filter by status
tm status --filter-status "In Progress"

# JSON output
tm status --json

tm emit-agent-instructions

Emit instructions for AI agents:

# Generic instructions
tm emit-agent-instructions

# Cursor-specific
tm emit-agent-instructions --agent cursor

# Replit-specific
jm emit-agent-instructions --agent replit

Replit Integration

Ticket Mate can notify Replit automations when tickets are synced:

1. Create a Replit Automation with a Custom Webhook Trigger
2. Copy the webhook URL provided by Replit
3. Configure in .ticket-mate/config.json:

{
  "integrations": {
    "replit": {
      "enabled": true,
      "webhookUrl": "https://your-replit-webhook-url"
    }
  }
}

4. Run tm sync-tickets - Ticket Mate will POST a JSON payload to the webhook:

{
  "event": "tickets_synced",
  "projectKey": "YOUR_PROJECT",
  "tickets": [
    {
      "key": "PROJ-123",
      "status": "In Progress",
      "summary": "Implement feature X",
      "url": "https://pamcms.atlassian.net/browse/PROJ-123"
    }
  ],
  "syncedAt": "2025-12-09T22:35:00.000Z"
}

Directory Structure (Multi-Project)

The .ticket-mate directory uses a project-based structure:

.ticket-mate/
  config.json              # Global configuration
  projects/
    <projectKey>/
      project.meta.json    # Project metadata
      tickets/
        <ticketKey>/
          ticket.meta.json # Ticket metadata
          plan.md          # High-level plan
          tasks.md         # Task checklist
          progress.log.md  # Progress log
          notes.md         # Free-form notes

Each project has its own folder, and tickets are organized within their project. This allows multiple Jira projects to coexist in the same repository.

Using with AI Agents

AI agents (Cursor, Replit Agent, etc.) should:

1. Read ticket metadata from .ticket-mate/projects/<projectKey>/tickets/<ticketKey>/ticket.meta.json
2. Follow the plan in .ticket-mate/projects/<projectKey>/tickets/<ticketKey>/plan.md
3. Complete tasks from .ticket-mate/projects/<projectKey>/tickets/<ticketKey>/tasks.md
4. Log progress in .ticket-mate/projects/<projectKey>/tickets/<ticketKey>/progress.log.md
5. Commit changes with the Jira key in the message (e.g., feat(PROJ-123): ...)

Use tm emit-agent-instructions --agent <agent> to get specific instructions for your agent.

Admin UI

Ticket Mate includes admin UI pages for browsing .ticket-mate content:

• /admin/ticket-mate - Overview of all projects in .ticket-mate
• /admin/ticket-mate/[projectKey] - Ticket list for a specific project
• /admin/ticket-mate/[projectKey]/[ticketKey] - Detailed ticket view with plan, tasks, progress, and notes

These pages read directly from the .ticket-mate filesystem structure and provide a read-only view of your tickets. All data is sourced from .ticket-mate on disk, not directly from Jira.

Best Practices

• Never delete user-edited content in plan.md, tasks.md, or notes.md
• Always append to progress.log.md (never overwrite)
• Check ticket status before starting work (only work on "Ready for Dev" or "In Progress")
• Update task checklists as you complete items
• Commit with Jira keys in commit messages for traceability

API Integration

The package includes a REST API server. Start it with:

npm run dev:server

Authentication

All API routes require authentication via API key. Include it in requests:

# Using X-API-Key header
curl -H "X-API-Key: your-api-key" http://localhost:3001/api/projects

# Using Authorization header
curl -H "Authorization: Bearer your-api-key" http://localhost:3001/api/projects

API Endpoints

Projects

• GET /api/projects - List all accessible Jira projects

Boards

• GET /api/boards?projectKey=NOVA - List boards for a project

Automation

• POST /api/automation/tickets/from-bugs - Create tickets from bugs-wip.json
• POST /api/automation/tickets/from-json - Create tickets from JSON instructions
• POST /api/automation/bugs/sync-status - Sync bug statuses from Jira
• GET /api/automation/bugs/statistics - Get bug statistics
• POST /api/automation/bugs/fix-now - Process "fix now" bug

Example Request

curl -X POST http://localhost:3001/api/automation/tickets/from-bugs \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"filePath": "public/bugs.json"}'

Next.js Dashboard

The package includes a Next.js dashboard that provides a web interface for:

• Viewing all Jira projects
• Expanding projects to see their boards
• Direct links to Jira backlog for each board

Start the dashboard:

npm run dev

The dashboard is available at http://localhost:4000.

Automation Features

bugs-wip.json Format

The automation system can process JSON files containing bug information:

{
  "bugs": [
    {
      "id": "bug-1",
      "title": "Checkout button not working",
      "category": "bug_report",
      "status": "open",
      "severity": "high",
      "summary": "The checkout button does not respond when clicked",
      "rootCause": "Event listener not attached",
      "metadata": {
        "jiraIssueKey": "NOVA-456",
        "jiraIssueUrl": "https://.../browse/NOVA-456"
      }
    }
  ]
}

Status Flow

Bugs go through these statuses:

• open - New bug, needs ticket
• sending_to_jira - Currently being sent to Jira
• sent_to_jira - Ticket created in Jira
• fixed - Bug is fixed
• resolved - Bug is resolved
• closed - Bug is closed
• unfixable - Bug cannot be fixed
• fix now - Priority bug, needs immediate attention

Orchestrator Integration

The package can process instructions directly from an orchestrator:

{
  "items": [
    {
      "id": "task-1",
      "title": "Implement feature X",
      "summary": "Add new feature",
      "category": "feature_request",
      "priority": "high"
    }
  ]
}

API Reference

For detailed API documentation, see:

• API Reference
• Automation Guide
• Host Integration

Examples

Sync Tickets to Progress Files

import { syncAll, getJiraConfig } from "@ameshkin/ticket-mate";

const config = getJiraConfig();
const result = await syncAll(config, {
  baseDir: "./ticket-mate",
  generateReports: true,
  generateIndex: true,
});

console.log(`Synced ${result.ticketsSynced} tickets`);

Create Jira Tickets from JSON

import { processBugsJson } from "@ameshkin/ticket-mate";

const result = await processBugsJson("public/bugs.json", {
  projectKey: "NOVA",
  issueType: "Bug",
  epicKey: "NOVA-10",
  labels: ["automated", "from-json"],
});

console.log(`Created ${result.created} tickets`);

Generate AI Prompts

import { buildTicketPrompts } from "@ameshkin/ticket-mate";

const prompts = await buildTicketPrompts({
  ticketKey: "NOVA-123",
  markdownPath: ".orchestrator/epics/NOVA-10/NOVA-123.md",
  repoRoot: process.cwd(),
});

console.log(prompts.systemPrompt);
console.log(prompts.userPrompt);

Create Board with AI Column

import {
  createCursorBoard,
  ensureAiInProgressColumn,
} from "@ameshkin/ticket-mate";

const board = await createCursorBoard("NOVA", "Cursor Board");
await ensureAiInProgressColumn(board.id);
console.log(`Board created: ${board.name} (ID: ${board.id})`);

Development

Setup

# Install dependencies
npm install

# Build the package
npm run build

# Run tests
npm run test

# Run type checking
npm run typecheck

# Start development server
npm run dev

# Start API server
npm run dev:server

# Start both
npm run dev:all

Project Structure

ticket-mate/
├── src/
│   ├── cli/              # CLI commands
│   ├── client/           # Jira REST API client
│   ├── config/           # Configuration management
│   ├── sync/             # Ticket syncing
│   ├── prompts/          # AI prompt generation
│   ├── automation/       # Automation features
│   ├── jira-management/  # Board, label, epic management
│   └── server/           # REST API server
├── app/                  # Next.js dashboard
│   ├── api/              # Next.js API routes
│   └── page.tsx          # Dashboard UI
└── dist/                 # Built output

Testing

# Run all tests
npm run test

# Run tests in watch mode
npm run test:watch

# Run with coverage
npm run test:coverage

# Run E2E tests
npm run test:e2e

Database Access

Prisma Studio (Cloud)

Access the database via Prisma Studio Cloud:

Direct Link:

• Prisma Studio Cloud

How to Access:

1. Click the link above or navigate to Prisma Console
2. Log in with your Prisma account credentials
3. Select the project: ticket-mate
4. Navigate to the database you want to view
5. Use the table browser to explore data

Note: You must have access to the Prisma project to view the database. Contact the project owner if you need access.

Local Prisma Studio

You can also run Prisma Studio locally to view and edit the database:

# Make sure DATABASE_URL is set in your .env file
npx prisma studio

This will open Prisma Studio at http://localhost:5555 where you can:

• Browse all tables
• View and edit records
• Run queries
• Export data

Prerequisites:

• DATABASE_URL must be configured in .env
• Database must be accessible from your local machine
• Prisma client must be generated: npm run prisma:generate

Database Schema

The database schema is defined in prisma/schema.prisma. Key models include:

• User - User accounts and authentication
• Account - Tenant/organization accounts
• JiraCredential - Per-user Jira OAuth credentials
• TokenUsage - AI token usage tracking
• PlanTier - Subscription plan tiers
• Project - Jira project mappings
• IntegrationConnection - Third-party integrations

See prisma/schema.prisma for the complete schema definition.

License

MIT

Author

Amir Meshkin [email protected]