TICKET MATE

$3

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.

$3

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

``bash


vercel logs ticket-mate.app

`

Vercel Environment Variables

`bash


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:sk_IJnKo655RyEjZhfoDiGel@db.prisma.io: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

`

$3

`bash
ssh root@72.61.71.227


ssh -i /Users/amirmeshkin/.ssh/hostinger_ollama root@72.61.71.227

ollama pull qwen2.5-coder:14b

ollama run qwen2.5-coder:14b


ollama pull deepseek-coder


`

$3

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/"

`bash

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"

`

$3

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

demo@gmail.com
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

$3

- ✅ 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

$3

- ✅ 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.

$3

- ✅ 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

$3

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

`typescript
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..."
`

$3

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

`bash


Process a bugs.json file and create/update Jira tickets


ticket-mate process-bugs --file ./reports/security-audit.json --sync-status
`

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

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

$3

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

`env


Mode 1: Personal Access Token (CLI / Local)

ATLASSIAN_AUTH_MODE=PAT
ATLASSIAN_EMAIL=me@example.com
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

$3

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

`bash


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:

`bash
npm install @ameshkin/ticket-mate
`

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

Configuration

$3

Create a .env file or set environment variables:

#### Required Jira Configuration

`env
ATLASSIAN_BASE_URL=https://pamcms.atlassian.net
ATLASSIAN_EMAIL=your-email@example.com
ATLASSIAN_API_KEY=your-api-token
`

Optional:

`env
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:

`env
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:

`json
{
"baseUrl": "https://pamcms.atlassian.net",
"email": "your-email@example.com",
"apiToken": "your-token",
"cloudId": "your-cloud-id",
"useCloudApi": true
}
`

#### API Authentication (for Next.js API routes)

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

#### Dashboard Configuration (for Next.js dashboard)

`env
NEXT_PUBLIC_ATLASSIAN_BASE_URL=https://pamcms.atlassian.net
`

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

Quick Start

$3

`bash


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"
`

$3

`typescript
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();
`

$3

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

`bash
npm run dev
`

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

Usage

$3

#### Sync Commands

`bash


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

`bash


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

`bash


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

`bash


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

`bash


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

`bash


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

`bash


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
`

$3

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.

$3

`bash


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
`

$3

The .ticket-mate directory structure:

`
.ticket-mate/
config.json # Repository configuration
tickets/
/
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)
`

$3

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

`json
{
"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"
}
}
}
`

$3

#### tm init-repo

Initialize a repository for Ticket Mate integration:

`bash
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 - Jira base URL
- --jira-project-key - Jira project key
- --jira-cloud-id - Optional cloud ID
- --default-branch - Default Git branch (default: main)
- --enable-replit - Enable Replit integration
- --replit-webhook-url - Replit webhook URL
- --enable-cursor - Enable Cursor integration

#### tm sync-tickets

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

`bash


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/:

`bash


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:

`bash


Generic instructions

tm emit-agent-instructions

Cursor-specific

tm emit-agent-instructions --agent cursor

Replit-specific

jm emit-agent-instructions --agent replit
`

$3

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:

`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:

`json
{
"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"
}
`

$3

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

`
.ticket-mate/
config.json # Global configuration
projects/
/
project.meta.json # Project metadata
tickets/
/
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.

$3

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

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

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

$3

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.

$3

- 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:

`bash
npm run dev:server
`

#### Authentication

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

`bash


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

`bash
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"}'
`

$3

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:

`bash
npm run dev
`

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

$3

#### bugs-wip.json Format

The automation system can process JSON files containing bug information:

`json
{
"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:

`json
{
"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

$3

`typescript
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);
`

$3

`typescript
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);
`

$3

`typescript
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);
`

$3

`typescript
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

$3

`bash


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
`

$3

`
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
`

$3

`bash


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

$3

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.

$3

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

`bash


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

$3

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