zephyr-enterprise-tools 1.2.8 → 1.3.1

package/README.md

@@ -11,6 +11,7 @@ Comprehensive tools for Zephyr Enterprise — Release Readiness, Project Health,
 | Tool | Description | Thresholds |
 |------|-------------|------------|
 | `release-readiness` | Run all 4 quality gates | Combined assessment |
+| `compare-releases` | Compare readiness across two releases | MCP/programmatic API |
 | `requirement-coverage` | Are requirements covered by tests? | ≥70% = GO |
 | `test-plan` | Are tests planned and assigned? | <80% = NO GO, 80–90% = CONDITIONAL, ≥90% = GO |
 | `test-execution` | Have tests been executed? | <90% = NO GO, 90–97% = CONDITIONAL, ≥97% = GO |
@@ -28,7 +29,10 @@ Comprehensive tools for Zephyr Enterprise — Release Readiness, Project Health,
 | `search-tests` | Search test cases by keyword query |
 | `user-activity` | User activity and productivity metrics |
 | `user-trend` | Full audit log history for a user — every action across the system, filterable by date range, entity type, and operation |
+| `execution-burnup` | Day-by-day execution burnup (cumulative executed vs ideal and total scope), supports optional date range filtering |
 | `execution-burndown` | Day-by-day execution burndown (remaining vs ideal), supports optional date range filtering |
+| `list-cycles` | List all test cycles for a release, including phases and execution status counts |
+| `get-cycle` | Get full details for a single test cycle |
 
 ---
 
@@ -66,6 +70,7 @@ Use `zephyr-enterprise-tools` as an MCP (Model Context Protocol) server with you
 | `list_projects` | _(none)_ | List all Zephyr projects |
 | `list_releases` | `projectId` | List releases for a project |
 | `release_readiness` | `projectId`, `releaseId` | Run all 4 quality gates |
+| `compare_releases` | `projectId`, `releaseId1`, `releaseId2`, `query?` _(ZQL)_ | Compare readiness between two releases in the same project |
 | `requirement_coverage` | `projectId`, `releaseId` | Check requirement coverage |
 | `test_plan_analysis` | `projectId`, `releaseId`, `query?` _(ZQL)_ | Analyze test planning status — supports ZQL filter e.g. `priority = "P1"` |
 | `test_execution` | `projectId`, `releaseId` | Check test execution progress |
@@ -77,13 +82,18 @@ Use `zephyr-enterprise-tools` as an MCP (Model Context Protocol) server with you
 | `search_test_cases` | `projectId`, `releaseId`, `query?`, `limit?` | Search test cases by keyword |
 | `user_activity` | `projectId`, `releaseId`, `days?` | Get user activity metrics |
 | `user_trend` | `userName`*, `fromDate?`, `toDate?`, `entity?`, `operation?`, `pageSize?`, `offset?` | Full audit log history for a user |
+| `execution_burnup` | `projectId`, `releaseId`, `startDate?`, `endDate?` | Day-by-day burnup chart data with cumulative executed, ideal, and scope counts |
 | `execution_burndown` | `projectId`, `releaseId`, `startDate?`, `endDate?` | Day-by-day burndown chart data |
+| `list_cycles` | `releaseId` | List all test cycles for a release, including phases and execution status counts |
+| `get_cycle` | `cycleId` | Get full details for a single test cycle, including phases |
 
 > **\* `user_trend` — `userName` must be the user's full email address** (e.g. `jane.doe@yourcompany.com`). Short names or display names will return 0 results. `pageSize` supports up to 1000 records per request.
 
 > **`test_plan_analysis` ZQL filter** — Use the `query` parameter to scope results to a specific priority, e.g. `priority = "P1"`. This is the recommended way to filter test plan metrics by priority. Note: `search_test_cases` accepts keyword queries but does not support ZQL priority filtering.
 
-> **`execution_burndown` date range** — Use `startDate` and `endDate` (format: `YYYY-MM-DD`) to scope the burndown to a specific period within the release window.
+> **Execution chart date range** — Use `startDate` and `endDate` (format: `YYYY-MM-DD`) to scope `execution_burnup` and `execution_burndown` to a specific period within the release window.
+
+> **Execution status IDs** — Test execution, failed tests, trends, user activity, burnup, burndown, and cycle status counts resolve status IDs from Zephyr v4 system preferences using `testresult.testresultStatus.LOV` from `/admin/preference/all/system`. Built-in IDs are used only as a fallback when the preference cannot be loaded or parsed.
 
 ---
 
@@ -179,6 +189,15 @@ zephyr-enterprise-tools -p 364 -r 4312 -t test-plan -q 'priority = "P1"'
 # Get trends for last 14 days
 zephyr-enterprise-tools -p 364 -r 4312 -t test-trends -d 14
 
+# Get execution burnup chart data
+zephyr-enterprise-tools -p 364 -r 4312 -t execution-burnup --start-date 2026-07-22 --end-date 2026-08-27
+
+# List all cycles and phase details for a release
+zephyr-enterprise-tools -p 364 -r 4312 -t list-cycles
+
+# Get one cycle by ID
+zephyr-enterprise-tools -p 364 -r 4312 -t get-cycle -c 98765
+
 # Get user audit log (full email required)
 zephyr-enterprise-tools -t user-trend --user jane.doe@yourcompany.com --page-size 1000
 
@@ -199,6 +218,7 @@ zephyr-enterprise-tools --help
 | `-q, --query <text>` | Keyword query (for `search-tests`) or ZQL expression (for `test-plan`) |
 | `-d, --days <n>` | Days for trends/activity (default: 30) |
 | `-l, --limit <n>` | Max results (default: 50) |
+| `-c, --cycle <id>` | Cycle ID for `get-cycle` |
 | `--user <email>` | Full email address for `user-trend` |
 | `--page-size <n>` | Records per page for `user-trend` (max: 1000) |
 | `--start-date <YYYY-MM-DD>` | Start date for `execution-burndown` |
@@ -230,6 +250,9 @@ const tools = new ZephyrEnterpriseTools({
 const report = await tools.runAllGates(364, 4312);
 console.log(report.overallStatus); // "GO" | "CONDITIONAL GO" | "NO GO"
 
+const comparison = await tools.compareReleases(364, 4312, 4313, { query: 'priority = "P1"' });
+console.log(comparison.overallStatusChanged); // true when release readiness status changed
+
 // Individual gates
 const coverage  = await tools.requirementCoverageGate(364, 4312);
 const planning  = await tools.testPlanAnalysisGate(364, 4312);
@@ -247,6 +270,14 @@ const reqCoverage = await tools.getRequirementCoverage(364, 4312);
 const trends      = await tools.getTestCaseTrends(364, 4312, { days: 14 });
 const results     = await tools.searchTestCases(364, 4312, { query: 'login' });
 const activity    = await tools.getUserActivity(364, 4312, { days: 30 });
+const cycles      = await tools.listCycles(4312);
+const cycle       = await tools.getCycle(98765);
+
+// Burnup with optional date range
+const burnup      = await tools.getExecutionBurnup(364, 4312, {
+  startDate: '2026-07-22',
+  endDate:   '2026-08-27',
+});
 
 // User audit log — full email address required; pageSize up to 1000
 const auditLog    = await tools.getUserTrend({

package/cli.js

@@ -42,6 +42,9 @@ function parseArgs() {
     query: '',
     days: 30,
     limit: 50,
+    cycleId: null,
+    startDate: null,
+    endDate: null,
   };
   
   for (let i = 0; i < args.length; i++) {
@@ -76,6 +79,16 @@ function parseArgs() {
       case '--limit':
         options.limit = parseInt(args[++i], 10) || 50;
         break;
+      case '-c':
+      case '--cycle':
+        options.cycleId = Number(args[++i]);
+        break;
+      case '--start-date':
+        options.startDate = args[++i] || null;
+        break;
+      case '--end-date':
+        options.endDate = args[++i] || null;
+        break;
       case '--json':
         options.format = 'json';
         break;
@@ -117,6 +130,7 @@ OPTIONS:
   -q, --query <text>    Search query (for search-tests)
   -d, --days <n>        Number of days for trends/activity (default: 30)
   -l, --limit <n>       Max results to return (default: 50)
+  -c, --cycle <id>      Cycle ID (for get-cycle)
       --json            Output as JSON
       --table           Output as table (default)
   -h, --help            Show this help
@@ -140,6 +154,10 @@ AVAILABLE TOOLS:
   │  test-trends           Test execution trends over time                      │
   │  search-tests          Search test cases by query                           │
   │  user-activity         User activity and productivity metrics               │
+  │  execution-burnup      Day-by-day execution burnup chart                    │
+  │  execution-burndown    Day-by-day execution burndown chart                  │
+  │  list-cycles           List all cycles for a release with phase details      │
+  │  get-cycle             Get full details for one cycle (-c <cycleId>)         │
   └─────────────────────────────────────────────────────────────────────────────┘
 
 ENVIRONMENT VARIABLES:
@@ -165,6 +183,15 @@ EXAMPLES:
   # Get user activity report
   zephyr-tools -p 364 -r 4312 -t user-activity
 
+  # Get execution burnup chart data
+  zephyr-tools -p 364 -r 4312 -t execution-burnup --start-date 2026-07-22 --end-date 2026-08-27
+
+  # List all cycles and phase details for a release
+  zephyr-tools -p 364 -r 4312 -t list-cycles
+
+  # Get a single cycle detail
+  zephyr-tools -p 364 -r 4312 -t get-cycle -c 98765
+
 QUALITY GATE THRESHOLDS:
   Requirement Coverage:  ≥70% = GO
   Test Plan Analysis:    <80% = NO GO, 80-90% = CONDITIONAL, ≥90% = GO
@@ -412,6 +439,27 @@ function formatGenericResult(result) {
     }
     console.log('   └────────────┴───────┴────────┴────────┴─────────┘');
   }
+
+  if (result.dailyBurnup && result.dailyBurnup.length > 0) {
+    console.log('\n📈 DAILY BURNUP (last 10 days):');
+    console.log('   ┌────────────┬────────┬────────────┬───────┬───────┐');
+    console.log('   │ Date       │ Today  │ Cumulative │ Ideal │ Scope │');
+    console.log('   ├────────────┼────────┼────────────┼───────┼───────┤');
+    for (const day of result.dailyBurnup.slice(-10)) {
+      console.log(`   │ ${day.date} │ ${String(day.executedToday).padEnd(6)} │ ${String(day.cumulativeExecuted).padEnd(10)} │ ${String(day.ideal).padEnd(5)} │ ${String(day.scope).padEnd(5)} │`);
+    }
+    console.log('   └────────────┴────────┴────────────┴───────┴───────┘');
+  }
+
+  // Cycles list/detail
+  if (result.cycles && result.cycles.length > 0) {
+    console.log(`\n🔁 CYCLES (${result.total || result.cycles.length}):`);
+    for (const cycle of result.cycles) {
+      printCycleDetail(cycle);
+    }
+  } else if (result.tool === 'Get Cycle' || result.cycleId) {
+    printCycleDetail(result);
+  }
   
   // Recommendations
   if (result.recommendations) {
@@ -449,6 +497,35 @@ function formatKey(key) {
     .trim();
 }
 
+function printCycleDetail(cycle) {
+  console.log(`   • ${cycle.name || 'Unnamed Cycle'} [ID: ${cycle.id || cycle.cycleId}]`);
+  if (cycle.environment || cycle.build || cycle.status) {
+    console.log(`     Environment: ${cycle.environment || 'N/A'} | Build: ${cycle.build || 'N/A'} | Status: ${cycle.status || 'N/A'}`);
+  }
+  if (cycle.startDate || cycle.endDate) {
+    console.log(`     Dates: ${cycle.startDate || 'N/A'} → ${cycle.endDate || 'N/A'}`);
+  }
+  if (cycle.executionStatusCounts?.breakdown?.length) {
+    const breakdown = cycle.executionStatusCounts.breakdown
+      .map(item => `${item.label}: ${item.count}`)
+      .join(', ');
+    console.log(`     Execution Status: total ${cycle.executionStatusCounts.total}; ${breakdown}`);
+  }
+  if (cycle.phases?.length) {
+    console.log(`     Phases (${cycle.phases.length}):`);
+    for (const phase of cycle.phases) {
+      const dates = phase.startDate || phase.endDate ? ` (${phase.startDate || 'N/A'} → ${phase.endDate || 'N/A'})` : '';
+      console.log(`       - ${phase.name || 'Unnamed Phase'} [ID: ${phase.id}]${dates}`);
+      if (phase.executionStatusCounts?.breakdown?.length) {
+        const breakdown = phase.executionStatusCounts.breakdown
+          .map(item => `${item.label}: ${item.count}`)
+          .join(', ');
+        console.log(`         Execution Status: total ${phase.executionStatusCounts.total}; ${breakdown}`);
+      }
+    }
+  }
+}
+
 // ─── Main ─────────────────────────────────────────────────────────────────────
 
 async function main() {
@@ -515,6 +592,28 @@ async function main() {
       case 'user-activity':
         result = await tools.getUserActivity(projectId, releaseId, { days });
         break;
+      case 'execution-burnup':
+        result = await tools.getExecutionBurnup(projectId, releaseId, {
+          startDate: options.startDate,
+          endDate: options.endDate,
+        });
+        break;
+      case 'execution-burndown':
+        result = await tools.getExecutionBurndown(projectId, releaseId, {
+          startDate: options.startDate,
+          endDate: options.endDate,
+        });
+        break;
+      case 'list-cycles':
+        result = await tools.listCycles(releaseId);
+        break;
+      case 'get-cycle':
+        if (!options.cycleId) {
+          console.error('Error: --cycle is required for get-cycle.');
+          process.exit(1);
+        }
+        result = await tools.getCycle(options.cycleId);
+        break;
         
       default:
         console.error(`Unknown tool: ${tool}`);

package/mcp-server.js

@@ -31,6 +31,20 @@ const TOOLS = [
       required: ['projectId', 'releaseId'],
     },
   },
+  {
+    name: 'compare_releases',
+    description: 'Run release readiness for two releases in the same project and return a side-by-side diff across all 4 gates, including which gate statuses changed and their metric deltas.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectId: { type: 'number', description: 'Zephyr project ID' },
+        releaseId1: { type: 'number', description: 'First (baseline) Zephyr release ID' },
+        releaseId2: { type: 'number', description: 'Second (comparison) Zephyr release ID' },
+        query: { type: 'string', description: 'Optional Zephyr ZQL expression for Test Plan Analysis, e.g. priority = "P1"' },
+      },
+      required: ['projectId', 'releaseId1', 'releaseId2'],
+    },
+  },
   {
     name: 'requirement_coverage',
     description: 'Check if requirements are covered by test cases. Threshold: ≥70% = GO.',
@@ -183,6 +197,20 @@ const TOOLS = [
       required: ['projectId', 'releaseId'],
     },
   },
+  {
+    name: 'execution_burnup',
+    description: 'Generate a day-by-day execution burnup chart for a release. Returns cumulative executed vs ideal and total scope counts for charting progress over time.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectId: { type: 'number', description: 'Zephyr project ID' },
+        releaseId: { type: 'number', description: 'Zephyr release ID' },
+        startDate: { type: 'string', description: 'Burnup start date YYYY-MM-DD (default: earliest execution date)' },
+        endDate:   { type: 'string', description: 'Burnup end date YYYY-MM-DD (default: today)' },
+      },
+      required: ['projectId', 'releaseId'],
+    },
+  },
   {
     name: 'user_trend',
     description: 'Get full audit log activity for a user — every action they performed across the system. Filter by date range and optionally by entity type (project or release).',
@@ -220,6 +248,39 @@ const TOOLS = [
       required: ['projectId'],
     },
   },
+  {
+    name: 'list_users',
+    description: 'List all users assigned to a project, with name, email, role, and account status.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectId: { type: 'number', description: 'Zephyr project ID' },
+      },
+      required: ['projectId'],
+    },
+  },
+  {
+    name: 'list_cycles',
+    description: 'List all test cycles for a release, including their phases and date ranges.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        releaseId: { type: 'number', description: 'Zephyr release ID' },
+      },
+      required: ['releaseId'],
+    },
+  },
+  {
+    name: 'get_cycle',
+    description: 'Get full detail for a single test cycle, including its phases.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        cycleId: { type: 'number', description: 'Zephyr cycle ID' },
+      },
+      required: ['cycleId'],
+    },
+  },
 ];
 
 // ─── MCP Server ───────────────────────────────────────────────────────────────
@@ -269,6 +330,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         result = await tools.runAllGates(projectId, releaseId, { query: args.query });
         break;
         
+      case 'compare_releases':
+        result = await tools.compareReleases(projectId, args.releaseId1, args.releaseId2, { query: args.query });
+        break;
+        
       case 'requirement_coverage':
         result = await tools.requirementCoverageGate(projectId, releaseId);
         break;
@@ -323,6 +388,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         });
         break;
 
+      case 'execution_burnup':
+        result = await tools.getExecutionBurnup(projectId, releaseId, {
+          startDate: args.startDate || null,
+          endDate:   args.endDate   || null,
+        });
+        break;
+
       case 'user_trend':
         result = await tools.getUserTrend({
           userName:  args.userName,
@@ -363,6 +435,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           })),
         };
         break;
+
+      case 'list_users':
+        result = await tools.listUsers(projectId);
+        break;
+
+      case 'list_cycles':
+        result = await tools.listCycles(releaseId);
+        break;
+
+      case 'get_cycle':
+        result = await tools.getCycle(args.cycleId);
+        break;
         
       default:
         return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zephyr-enterprise-tools",
-  "version": "1.2.8",
+  "version": "1.3.1",
   "description": "Comprehensive Zephyr Enterprise Tools - Release Readiness, Project Health, Test Analytics & More",
   "main": "zephyr-enterprise-tools.js",
   "types": "zephyr-enterprise-tools.d.ts",

package/zephyr-enterprise-tools.d.ts

@@ -88,6 +88,30 @@ export interface ReleaseReadinessResult {
   };
 }
 
+export interface GateComparison {
+  metric: string;
+  releaseA: { status: GateStatus; value: number };
+  releaseB: { status: GateStatus; value: number };
+  delta: number;
+  statusChanged: boolean;
+  trend: 'improved' | 'regressed' | 'unchanged';
+}
+
+export interface CompareReleasesResult {
+  projectId: number;
+  timestamp: string;
+  query?: string;
+  releaseA: { releaseId: number; projectName: string; releaseName: string; generatedAt: string; fileName: string; overallStatus: GateStatus };
+  releaseB: { releaseId: number; projectName: string; releaseName: string; generatedAt: string; fileName: string; overallStatus: GateStatus };
+  overallStatusChanged: boolean;
+  gates: {
+    requirementCoverage: GateComparison;
+    testPlanAnalysis: GateComparison;
+    testExecution: GateComparison;
+    defectQuality: GateComparison;
+  };
+}
+
 export interface ProjectHealthResult {
   tool: string;
   projectId: number;
@@ -164,6 +188,14 @@ export interface UserActivityOptions {
   days?: number;
 }
 
+export interface UserActivityTrendSummary {
+  mostActiveUser: { userId: number; name: string; executed: number } | null;
+  leastActiveUser: { userId: number; name: string; executed: number } | null;
+  avgCompletionRate: number;
+  teamVelocityTrend: 'increasing' | 'decreasing' | 'steady' | 'insufficient data';
+  velocity: { firstHalfAvgPerDay: number; secondHalfAvgPerDay: number; changePct: number } | null;
+}
+
 export interface UserActivityResult {
   tool: string;
   projectId: number;
@@ -171,6 +203,7 @@ export interface UserActivityResult {
   timestamp: string;
   period: { days: number };
   teamSummary: Record<string, unknown>;
+  trendSummary: UserActivityTrendSummary;
   assignedTo: unknown[];
   executedBy: unknown[];
   topExecutors: unknown[];
@@ -184,6 +217,121 @@ export interface TrendsOptions {
   days?: number;
 }
 
+export interface ListUsersOptions {
+  pageSize?: number;
+}
+
+export interface ExecutionChartOptions {
+  startDate?: string | null;
+  endDate?: string | null;
+}
+
+export interface ExecutionBurnupDay {
+  date: string;
+  executedToday: number;
+  cumulativeExecuted: number;
+  remaining: number;
+  completionPct: number;
+  ideal: number;
+  scope: number;
+}
+
+export interface ExecutionBurnupResult {
+  tool: string;
+  projectId: number;
+  releaseId: number;
+  timestamp: string;
+  dateRange?: { from: string; to: string };
+  total: number;
+  totalPlanned: number;
+  summary?: Record<string, unknown>;
+  message?: string;
+  dailyBurnup: ExecutionBurnupDay[];
+}
+
+export interface ZephyrUser {
+  id: number;
+  fullName: string;
+  userName: string;
+  email: string;
+  title?: string;
+  location?: string;
+  accountEnabled: boolean;
+  roles: number[];
+}
+
+export interface ListUsersResult {
+  tool: string;
+  projectId: number;
+  timestamp: string;
+  total: number;
+  returned: number;
+  note?: string;
+  users: ZephyrUser[];
+}
+
+export interface ExecutionStatusBreakdown {
+  statusCode: number;
+  label: string;
+  count: number;
+}
+
+export interface ExecutionStatusCounts {
+  total: number;
+  breakdown: ExecutionStatusBreakdown[];
+}
+
+export interface CyclePhase {
+  id: number;
+  name: string;
+  startDate: string;
+  endDate: string;
+  executionStatusCounts: ExecutionStatusCounts | null;
+}
+
+export interface ZephyrCycle {
+  id: number;
+  name: string;
+  environment?: string;
+  build?: string;
+  startDate: string;
+  endDate: string;
+  status: number;
+  executionStatusCounts: ExecutionStatusCounts | null;
+  phases: CyclePhase[];
+}
+
+export interface ListCyclesResult {
+  tool: string;
+  releaseId: number;
+  timestamp: string;
+  total: number;
+  cycles: ZephyrCycle[];
+}
+
+export interface CyclePhaseDetail extends CyclePhase {
+  freeForm?: boolean;
+  resetExecution?: boolean;
+  hasChild?: boolean;
+}
+
+export interface GetCycleResult {
+  tool: string;
+  cycleId: number;
+  timestamp: string;
+  id: number;
+  name: string;
+  environment?: string;
+  build?: string;
+  startDate: string;
+  endDate: string;
+  status: number;
+  releaseId: number;
+  hasChild?: boolean;
+  executionStatusCounts: ExecutionStatusCounts | null;
+  phases: CyclePhaseDetail[];
+}
+
 export declare class QualityGates {
   constructor(config: ZephyrConfig);
 
@@ -193,6 +341,7 @@ export declare class QualityGates {
   testExecutionGate(projectId: number, releaseId: number): Promise<TestExecutionResult>;
   defectQualityGate(projectId: number, releaseId: number): Promise<DefectQualityResult>;
   runAllGates(projectId: number, releaseId: number, options?: TestPlanOptions): Promise<ReleaseReadinessResult>;
+  compareReleases(projectId: number, releaseId1: number, releaseId2: number, options?: TestPlanOptions): Promise<CompareReleasesResult>;
 
   // Analytics & Insights
   getProjectHealth(projectId: number, releaseId: number): Promise<ProjectHealthResult>;
@@ -202,6 +351,11 @@ export declare class QualityGates {
   getTestCaseTrends(projectId: number, releaseId: number, options?: TrendsOptions): Promise<TestTrendsResult>;
   searchTestCases(projectId: number, releaseId: number, options?: SearchTestCasesOptions): Promise<SearchTestCasesResult>;
   getUserActivity(projectId: number, releaseId: number, options?: UserActivityOptions): Promise<UserActivityResult>;
+  getExecutionBurndown(projectId: number, releaseId: number, options?: ExecutionChartOptions): Promise<Record<string, unknown>>;
+  getExecutionBurnup(projectId: number, releaseId: number, options?: ExecutionChartOptions): Promise<ExecutionBurnupResult>;
+  listUsers(projectId: number, options?: ListUsersOptions): Promise<ListUsersResult>;
+  listCycles(releaseId: number): Promise<ListCyclesResult>;
+  getCycle(cycleId: number): Promise<GetCycleResult>;
 }
 
 export declare const THRESHOLDS: ThresholdConfig;