zephyr-enterprise-tools 1.1.0 → 1.2.2

package/cli.js

@@ -15,17 +15,19 @@
  *   zephyr-tools mcp   # Start MCP server
  */
 
+import QualityGates from './zephyr-enterprise-tools.js';
+
 // Check if MCP server mode
 if (process.argv[2] === 'mcp') {
   import('./mcp-server.js');
 } else {
-  // Normal CLI mode
-  runCLI();
+  main().catch(err => {
+    console.error(`Error: ${err.message}`);
+    if (process.env.DEBUG) console.error(err.stack);
+    process.exit(1);
+  });
 }
 
-async function runCLI() {
-  const { default: QualityGates } = await import('./zephyr-enterprise-tools.js');
-
 // ─── Parse Arguments ──────────────────────────────────────────────────────────
 
 function parseArgs() {
@@ -545,6 +547,3 @@ async function main() {
     process.exit(1);
   }
 }
-
-main();
-} // end runCLI

package/mcp-server.js

@@ -167,6 +167,23 @@ const TOOLS = [
       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).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        userName:  { type: 'string', description: 'Username to look up (e.g. "dylan.garcia")' },
+        fromDate:  { type: 'string', description: 'Start date YYYY-MM-DD (e.g. "2026-08-01")' },
+        toDate:    { type: 'string', description: 'End date YYYY-MM-DD (e.g. "2026-08-18")' },
+        entity:    { type: 'string', description: 'Filter by entity type: "project", "release", or "" for all', enum: ['project', 'release', ''] },
+        operation: { type: 'string', description: 'Filter by operation (e.g. "CREATE", "UPDATE"). Omit for all.' },
+        offset:    { type: 'number', description: 'Pagination offset (default 0)' },
+        pageSize:  { type: 'number', description: 'Records per page (default 25)' },
+      },
+      required: ['userName'],
+    },
+  },
   {
     name: 'list_projects',
     description: 'List all available Zephyr projects.',
@@ -282,6 +299,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       case 'user_activity':
         result = await tools.getUserActivity(projectId, releaseId, { days: args.days || 30 });
         break;
+
+      case 'user_trend':
+        result = await tools.getUserTrend({
+          userName:  args.userName,
+          fromDate:  args.fromDate  || null,
+          toDate:    args.toDate    || null,
+          entity:    args.entity    || '',
+          operation: args.operation || null,
+          offset:    args.offset    || 0,
+          pageSize:  args.pageSize  || 25,
+        });
+        break;
         
       case 'list_projects':
         const projects = await tools.GET('/project');

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "zephyr-enterprise-tools",
-  "version": "1.1.0",
+  "version": "1.2.2",
   "description": "Comprehensive Zephyr Enterprise Tools - Release Readiness, Project Health, Test Analytics & More",
   "main": "zephyr-enterprise-tools.js",
+  "types": "zephyr-enterprise-tools.d.ts",
   "exports": {
-    ".": "./zephyr-enterprise-tools.js",
+    ".": {
+      "import": "./zephyr-enterprise-tools.js",
+      "types": "./zephyr-enterprise-tools.d.ts"
+    },
     "./cli": "./cli.js",
     "./mcp": "./mcp-server.js"
   },
@@ -52,6 +56,7 @@
   },
   "files": [
     "zephyr-enterprise-tools.js",
+    "zephyr-enterprise-tools.d.ts",
     "cli.js",
     "mcp-server.js",
     "README.md",

package/zephyr-enterprise-tools.d.ts

@@ -0,0 +1,202 @@
+/**
+ * Zephyr Enterprise Tools - TypeScript Declarations
+ */
+
+export interface ZephyrConfig {
+  baseUrl?: string;
+  token?: string;
+}
+
+export interface ThresholdConfig {
+  requirementCoverage: { go: number; description: string };
+  testPlanAnalysis: { noGo: number; conditionalGo: number; description: string };
+  testExecution: { noGo: number; conditionalGo: number; description: string };
+  defectQuality: { blockerLimit: number; highRiskLimit: number; description: string };
+}
+
+export type GateStatus = "GO" | "CONDITIONAL GO" | "NO GO";
+export type HealthStatus = "HEALTHY" | "MODERATE" | "AT RISK" | "CRITICAL";
+
+export interface GateResult {
+  gate: string;
+  status: GateStatus;
+  statusMessage: string;
+  [key: string]: unknown;
+}
+
+export interface RequirementCoverageResult extends GateResult {
+  coveragePercentage: number;
+  coveredRequirements: number;
+  notCoveredRequirements: number;
+  totalRequirements: number;
+}
+
+export interface TestPlanResult extends GateResult {
+  overallPlanningPercentage: number;
+  totalTests: number;
+  plannedTests: number;
+  assignedTests: number;
+}
+
+export interface TestExecutionResult extends GateResult {
+  executionPercentage: number;
+  completedTests: number;
+  totalPlannedTests: number;
+  breakdown: {
+    passed: number;
+    failed: number;
+    blocked: number;
+    wip: number;
+    notExecuted: number;
+  };
+}
+
+export interface DefectQualityResult extends GateResult {
+  totalDefects: number;
+  breakdown: {
+    blocker: { count: number; defects: unknown[] };
+    highRisk: { count: number; defects: unknown[] };
+    lowRisk: { count: number; defects: unknown[] };
+    resolved: { count: number };
+  };
+}
+
+export interface ReleaseReadinessResult {
+  projectId: number;
+  releaseId: number;
+  timestamp: string;
+  overallStatus: GateStatus;
+  summary: { passed: number; failed: number; conditional: number };
+  recommendation: string;
+  gates: {
+    requirementCoverage: RequirementCoverageResult;
+    testPlanAnalysis: TestPlanResult;
+    testExecution: TestExecutionResult;
+    defectQuality: DefectQualityResult;
+  };
+}
+
+export interface ProjectHealthResult {
+  tool: string;
+  projectId: number;
+  releaseId: number;
+  timestamp: string;
+  healthScore: number;
+  healthStatus: HealthStatus;
+  summary: Record<string, unknown>;
+  metrics: Record<string, Record<string, unknown>>;
+  recommendations: string[];
+}
+
+export interface TestCoverageResult {
+  tool: string;
+  projectId: number;
+  releaseId: number;
+  timestamp: string;
+  summary: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export interface FailedTest {
+  testcaseId: number;
+  testcaseKey: string;
+  testcaseName: string;
+  executedBy?: string;
+  [key: string]: unknown;
+}
+
+export interface FailedTestsResult {
+  tool: string;
+  projectId: number;
+  releaseId: number;
+  timestamp: string;
+  failedTests: FailedTest[];
+  total: number;
+}
+
+export interface RequirementCoverageDetailResult {
+  tool: string;
+  projectId: number;
+  releaseId: number;
+  timestamp: string;
+  results: unknown[];
+  [key: string]: unknown;
+}
+
+export interface TestTrendsResult {
+  tool: string;
+  projectId: number;
+  releaseId: number;
+  timestamp: string;
+  dailyTrends: Array<{ date: string; total: number; passed: number; failed: number; blocked: number }>;
+  [key: string]: unknown;
+}
+
+export interface SearchTestCasesOptions {
+  query?: string;
+  limit?: number;
+}
+
+export interface SearchTestCasesResult {
+  tool: string;
+  projectId: number;
+  releaseId: number;
+  timestamp: string;
+  results: Array<{ id: number; key: string; name: string; status?: string }>;
+  totalMatches: number;
+  returned: number;
+}
+
+export interface UserActivityOptions {
+  days?: number;
+}
+
+export interface UserActivityResult {
+  tool: string;
+  projectId: number;
+  releaseId: number;
+  timestamp: string;
+  period: { days: number };
+  teamSummary: Record<string, unknown>;
+  assignedTo: unknown[];
+  executedBy: unknown[];
+  topExecutors: unknown[];
+}
+
+export interface FailedTestsOptions {
+  limit?: number;
+}
+
+export interface TrendsOptions {
+  days?: number;
+}
+
+export declare class QualityGates {
+  constructor(config: ZephyrConfig);
+
+  // Quality Gates (Release Readiness)
+  requirementCoverageGate(projectId: number, releaseId: number): Promise<RequirementCoverageResult>;
+  testPlanAnalysisGate(projectId: number, releaseId: number): Promise<TestPlanResult>;
+  testExecutionGate(projectId: number, releaseId: number): Promise<TestExecutionResult>;
+  defectQualityGate(projectId: number, releaseId: number): Promise<DefectQualityResult>;
+  runAllGates(projectId: number, releaseId: number): Promise<ReleaseReadinessResult>;
+
+  // Analytics & Insights
+  getProjectHealth(projectId: number, releaseId: number): Promise<ProjectHealthResult>;
+  getTestCoverage(projectId: number, releaseId: number): Promise<TestCoverageResult>;
+  getFailedTests(projectId: number, releaseId: number, options?: FailedTestsOptions): Promise<FailedTestsResult>;
+  getRequirementCoverage(projectId: number, releaseId: number): Promise<RequirementCoverageDetailResult>;
+  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>;
+}
+
+export declare const THRESHOLDS: ThresholdConfig;
+export declare const RESOLVED_STATUSES: string[];
+export declare const BLOCKER_PRIORITIES: string[];
+export declare const HIGH_RISK_PRIORITIES: string[];
+export declare const LOW_RISK_PRIORITIES: string[];
+
+/** Alias for QualityGates — kept for backward compatibility */
+export { QualityGates as ZephyrTools };
+export default QualityGates;

package/zephyr-enterprise-tools.js

@@ -1285,6 +1285,99 @@ export class QualityGates {
       topExecutors: executors.slice(0, 5),
     };
   }
+
+  // ─── User Trend (Audit Logs) ─────────────────────────────────────────────────
+
+  async getUserTrend(options = {}) {
+    const {
+      userName = "",
+      fromDate = null,   // "YYYY-MM-DD"
+      toDate = null,     // "YYYY-MM-DD"
+      entity = "",       // "project", "release", or "" for all
+      operation = null,  // specific operation or null for all
+      offset = 0,
+      pageSize = 25,
+    } = options;
+
+    const v3BaseUrl = this.baseUrl.replace('/latest', '/v3');
+    const url = new URL(`${v3BaseUrl}/ui/auditLogs`);
+    url.searchParams.set("offset", String(offset));
+    url.searchParams.set("pagesize", String(pageSize));
+    url.searchParams.set("isascorder", "false");
+    url.searchParams.set("order", "id");
+    url.searchParams.set("isExport", "false");
+
+    const body = { entity, operation, userName };
+
+    if (fromDate) {
+      body.fromDate = fromDate;
+      body.fromDateVal = `${fromDate}T00:00:00.000Z`;
+    }
+    if (toDate) {
+      body.toDate = toDate;
+      body.toDateVal = `${toDate}T00:00:00.000Z`;
+    }
+
+    const res = await fetch(url.toString(), {
+      method: "POST",
+      headers: {
+        Accept: "application/json",
+        "Content-Type": "application/json",
+        ...this.authHeader(),
+      },
+      body: JSON.stringify(body),
+    });
+
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new Error(`Zephyr audit logs API ${res.status}: ${text}`);
+    }
+
+    const data = await res.json();
+    const logs = data.results || data || [];
+
+    // Summarise by operation and entity type
+    const byOperation = {};
+    const byEntity = {};
+    for (const log of logs) {
+      const op  = log.operation || "Unknown";
+      const ent = log.entity    || "Unknown";
+      byOperation[op]  = (byOperation[op]  || 0) + 1;
+      byEntity[ent]    = (byEntity[ent]    || 0) + 1;
+    }
+
+    return {
+      tool: "User Trend",
+      userName,
+      dateRange: { from: fromDate || "all", to: toDate || "all" },
+      entity: entity || "all",
+      timestamp: new Date().toISOString(),
+      totalRecords: data.totalCount ?? logs.length,
+      offset,
+      pageSize,
+      operationSummary: Object.entries(byOperation)
+        .map(([operation, count]) => ({ operation, count }))
+        .sort((a, b) => b.count - a.count),
+      entitySummary: Object.entries(byEntity)
+        .map(([entity, count]) => ({ entity, count }))
+        .sort((a, b) => b.count - a.count),
+      auditLogs: logs.map(log => ({
+        id:          log.id,
+        userName:    log.userName,
+        entity:      log.entity,
+        entityName:  log.entityName,
+        operation:   log.operation,
+        description: log.description,
+        detail:      log.detail,
+        projectId:   log.projectId,
+        projectName: log.projectName,
+        releaseId:   log.releaseId,
+        releaseName: log.releaseName,
+        createdOn:   log.createdOn,
+        ipAddress:   log.ipAddress,
+      })),
+    };
+  }
 }
 
 // Export with both names for backward compatibility