ralph-hero-mcp-server 2.4.17 → 2.4.22

package/dist/lib/filter-profiles.js

@@ -0,0 +1,55 @@
+/**
+ * Named filter profiles for Ralph agent roles.
+ *
+ * Maps profile names (e.g., "analyst-triage", "builder-active") to sets of
+ * filter parameters for list_issues and list_project_items. Agents use profiles
+ * instead of hardcoding individual filter params.
+ */
+// --- Profile Registry ---
+/**
+ * Named filter profiles mapping to concrete filter parameter objects.
+ * Profiles use kebab-case with role prefix: role-purpose.
+ */
+export const FILTER_PROFILES = {
+    "analyst-triage": {
+        workflowState: "Backlog",
+        // TODO: add `no: "estimate"` when GH-141 (has/no presence filters) lands
+    },
+    "analyst-research": {
+        workflowState: "Research Needed",
+    },
+    "builder-active": {
+        workflowState: "In Progress",
+    },
+    "builder-planned": {
+        workflowState: "Plan in Review",
+    },
+    "validator-review": {
+        workflowState: "Plan in Review",
+        // TODO: multi-value workflowState for "Plan in Review" OR "In Review" when supported
+    },
+    "integrator-merge": {
+        workflowState: "In Review",
+    },
+};
+/**
+ * Valid profile names, derived from the registry keys.
+ */
+export const VALID_PROFILE_NAMES = Object.keys(FILTER_PROFILES);
+// --- Public API ---
+/**
+ * Expand a named profile into its filter parameters.
+ *
+ * Returns a shallow copy of the profile's filter params (safe to mutate).
+ * Throws if the profile name is not recognized.
+ */
+export function expandProfile(name) {
+    const profile = FILTER_PROFILES[name];
+    if (!profile) {
+        throw new Error(`Unknown filter profile "${name}". ` +
+            `Valid profiles: ${VALID_PROFILE_NAMES.join(", ")}. ` +
+            `Recovery: retry with one of the valid profile names listed above.`);
+    }
+    return { ...profile };
+}
+//# sourceMappingURL=filter-profiles.js.map

package/dist/lib/metrics.js

@@ -0,0 +1,98 @@
+/**
+ * Velocity metrics, risk scoring, and auto-status determination — pure functions.
+ *
+ * All functions are side-effect-free: dashboard data in, metrics out.
+ * Designed to complement lib/dashboard.ts without modifying it.
+ */
+export const DEFAULT_METRICS_CONFIG = {
+    velocityWindowDays: 7,
+    atRiskThreshold: 2,
+    offTrackThreshold: 6,
+    severityWeights: { critical: 3, warning: 1, info: 0 },
+};
+// ---------------------------------------------------------------------------
+// calculateVelocity
+// ---------------------------------------------------------------------------
+/**
+ * Count items that moved to Done within a time window.
+ *
+ * Uses closedAt if available, otherwise falls back to updatedAt.
+ * Only counts items whose workflowState is "Done".
+ */
+export function calculateVelocity(items, windowDays, now) {
+    const windowMs = windowDays * 24 * 60 * 60 * 1000;
+    return items.filter((item) => {
+        if (item.workflowState !== "Done")
+            return false;
+        const ts = item.closedAt ?? item.updatedAt;
+        return now - new Date(ts).getTime() <= windowMs;
+    }).length;
+}
+// ---------------------------------------------------------------------------
+// calculateRiskScore
+// ---------------------------------------------------------------------------
+/**
+ * Aggregate health warnings into a numeric risk score.
+ *
+ * Each warning contributes its severity weight. Unknown severities
+ * default to 0.
+ */
+export function calculateRiskScore(warnings, weights) {
+    return warnings.reduce((score, w) => score + (weights[w.severity] ?? 0), 0);
+}
+// ---------------------------------------------------------------------------
+// determineStatus
+// ---------------------------------------------------------------------------
+/**
+ * Map a risk score to a project health status using configurable thresholds.
+ */
+export function determineStatus(riskScore, config) {
+    if (riskScore >= config.offTrackThreshold)
+        return "OFF_TRACK";
+    if (riskScore >= config.atRiskThreshold)
+        return "AT_RISK";
+    return "ON_TRACK";
+}
+// ---------------------------------------------------------------------------
+// extractHighlights
+// ---------------------------------------------------------------------------
+/**
+ * Extract recently completed and newly added items from dashboard data.
+ *
+ * - recentlyCompleted: items in the "Done" phase (already time-filtered
+ *   by aggregateByPhase)
+ * - newlyAdded: items in "Backlog" whose ageHours is within the window
+ *   (approximation since DashboardItem lacks createdAt)
+ */
+export function extractHighlights(data, windowDays, now) {
+    void now; // reserved for future createdAt-based filtering
+    const donePhase = data.phases.find((p) => p.state === "Done");
+    const recentlyCompleted = (donePhase?.issues ?? []).map((i) => ({
+        number: i.number,
+        title: i.title,
+    }));
+    const backlogPhase = data.phases.find((p) => p.state === "Backlog");
+    const maxAgeHours = windowDays * 24;
+    const newlyAdded = (backlogPhase?.issues ?? [])
+        .filter((i) => i.ageHours < maxAgeHours)
+        .map((i) => ({
+        number: i.number,
+        title: i.title,
+    }));
+    return { recentlyCompleted, newlyAdded };
+}
+// ---------------------------------------------------------------------------
+// calculateMetrics
+// ---------------------------------------------------------------------------
+/**
+ * Convenience orchestrator: compute all metrics from raw items and
+ * dashboard data in one call.
+ */
+export function calculateMetrics(items, data, config = DEFAULT_METRICS_CONFIG, now = Date.now()) {
+    const velocity = calculateVelocity(items, config.velocityWindowDays, now);
+    const riskScore = calculateRiskScore(data.health.warnings, config.severityWeights);
+    const status = determineStatus(riskScore, config);
+    const highlights = extractHighlights(data, config.velocityWindowDays, now);
+    return { velocity, riskScore, status, highlights };
+}
+//# sourceMappingURL=metrics.js.map

package/dist/tools/dashboard-tools.js

@@ -9,6 +9,7 @@ import { z } from "zod";
 import { paginateConnection } from "../lib/pagination.js";
 import { buildDashboard, formatMarkdown, formatAscii, DEFAULT_HEALTH_CONFIG, } from "../lib/dashboard.js";
 import { toolSuccess, toolError, resolveProjectOwner } from "../types.js";
+import { calculateMetrics, DEFAULT_METRICS_CONFIG, } from "../lib/metrics.js";
 // ---------------------------------------------------------------------------
 // Helper: Ensure field option cache is populated
 // ---------------------------------------------------------------------------
@@ -176,6 +177,26 @@ export function registerDashboardTools(server, client, fieldCache) {
             .optional()
             .default(10)
             .describe("Max issues to list per phase (default: 10)"),
+        includeMetrics: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Include velocity metrics, risk score, and auto-status (default: false)"),
+        velocityWindowDays: z
+            .number()
+            .optional()
+            .default(7)
+            .describe("Days to look back for velocity calculation (default: 7)"),
+        atRiskThreshold: z
+            .number()
+            .optional()
+            .default(2)
+            .describe("Risk score threshold for AT_RISK status (default: 2)"),
+        offTrackThreshold: z
+            .number()
+            .optional()
+            .default(6)
+            .describe("Risk score threshold for OFF_TRACK status (default: 6)"),
     }, async (args) => {
         try {
             const owner = args.owner || resolveProjectOwner(client.config);
@@ -215,6 +236,17 @@ export function registerDashboardTools(server, client, fieldCache) {
             for (const phase of dashboard.phases) {
                 phase.issues = phase.issues.slice(0, issuesPerPhase);
             }
+            // Compute metrics if requested
+            let metrics;
+            if (args.includeMetrics) {
+                const metricsConfig = {
+                    ...DEFAULT_METRICS_CONFIG,
+                    velocityWindowDays: args.velocityWindowDays ?? 7,
+                    atRiskThreshold: args.atRiskThreshold ?? 2,
+                    offTrackThreshold: args.offTrackThreshold ?? 6,
+                };
+                metrics = calculateMetrics(dashboardItems, dashboard, metricsConfig);
+            }
             // Format output
             const format = args.format ?? "json";
             let formatted;
@@ -227,6 +259,7 @@ export function registerDashboardTools(server, client, fieldCache) {
             return toolSuccess({
                 ...dashboard,
                 ...(formatted !== undefined ? { formatted } : {}),
+                ...(metrics !== undefined ? { metrics } : {}),
             });
         }
         catch (error) {

package/dist/tools/issue-tools.js

@@ -11,6 +11,7 @@ import { detectPipelinePosition, } from "../lib/pipeline-detection.js";
 import { isValidState, VALID_STATES, LOCK_STATES, } from "../lib/workflow-states.js";
 import { resolveState } from "../lib/state-resolution.js";
 import { parseDateMath } from "../lib/date-math.js";
+import { expandProfile } from "../lib/filter-profiles.js";
 import { toolSuccess, toolError } from "../types.js";
 import { ensureFieldCache, resolveIssueNodeId, resolveProjectItemId, updateProjectItemField, getCurrentFieldValue, resolveConfig, resolveFullConfig, syncStatusField, } from "../lib/helpers.js";
 // ---------------------------------------------------------------------------
@@ -29,6 +30,11 @@ export function registerIssueTools(server, client, fieldCache) {
             .string()
             .optional()
             .describe("Repository name. Defaults to GITHUB_REPO env var"),
+        profile: z
+            .string()
+            .optional()
+            .describe("Named filter profile (e.g., 'analyst-triage', 'builder-active'). " +
+            "Profile filters are defaults; explicit params override them."),
         workflowState: z
             .string()
             .optional()
@@ -72,6 +78,15 @@ export function registerIssueTools(server, client, fieldCache) {
             .describe("Max items to return (default 50)"),
     }, async (args) => {
         try {
+            // Expand profile into filter defaults (explicit args override)
+            if (args.profile) {
+                const profileFilters = expandProfile(args.profile);
+                for (const [key, value] of Object.entries(profileFilters)) {
+                    if (args[key] === undefined) {
+                        args[key] = value;
+                    }
+                }
+            }
             const { owner, repo, projectNumber, projectOwner } = resolveFullConfig(client, args);
             // Ensure field cache is populated
             await ensureFieldCache(client, fieldCache, projectOwner, projectNumber);

package/dist/tools/project-tools.js

@@ -7,6 +7,7 @@
 import { z } from "zod";
 import { paginateConnection } from "../lib/pagination.js";
 import { parseDateMath } from "../lib/date-math.js";
+import { expandProfile } from "../lib/filter-profiles.js";
 import { toolSuccess, toolError } from "../types.js";
 import { resolveProjectOwner } from "../types.js";
 const WORKFLOW_STATE_OPTIONS = [
@@ -240,6 +241,11 @@ export function registerProjectTools(server, client, fieldCache) {
             .number()
             .optional()
             .describe("Project number. Defaults to RALPH_GH_PROJECT_NUMBER env var"),
+        profile: z
+            .string()
+            .optional()
+            .describe("Named filter profile (e.g., 'analyst-triage', 'builder-active'). " +
+            "Profile filters are defaults; explicit params override them."),
         workflowState: z
             .string()
             .optional()
@@ -271,6 +277,15 @@ export function registerProjectTools(server, client, fieldCache) {
             .describe("Max items to return (default 50)"),
     }, async (args) => {
         try {
+            // Expand profile into filter defaults (explicit args override)
+            if (args.profile) {
+                const profileFilters = expandProfile(args.profile);
+                for (const [key, value] of Object.entries(profileFilters)) {
+                    if (args[key] === undefined) {
+                        args[key] = value;
+                    }
+                }
+            }
             const owner = args.owner || resolveProjectOwner(client.config);
             const projectNumber = args.number || client.config.projectNumber;
             if (!owner) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-hero-mcp-server",
-  "version": "2.4.17",
+  "version": "2.4.22",
   "description": "MCP server for GitHub Projects V2 - Ralph workflow automation",
   "type": "module",
   "main": "dist/index.js",