ralph-hero-mcp-server 2.5.94 → 2.5.106

package/dist/index.js

@@ -29,6 +29,7 @@ import { registerDecomposeTools } from "./tools/decompose-tools.js";
 import { registerViewTools } from "./tools/view-tools.js";
 import { registerPlanGraphTools } from "./tools/plan-graph-tools.js";
 import { registerActivityTools } from "./tools/activity-tools.js";
+import { registerTrendsTools } from "./tools/trends-tools.js";
 /**
  * Initialize the GitHub client from environment variables.
  */
@@ -404,6 +405,8 @@ async function main() {
     registerPlanGraphTools(server, client);
     // Activity log reader (recent_activity tool — pure filesystem, no GitHub client)
     registerActivityTools(server);
+    // Trends tools (capture_snapshot — JSONL persistence under ~/.ralph-hero/snapshots/)
+    registerTrendsTools(server, client, fieldCache);
     // Debug tools (only when RALPH_DEBUG=true)
     if (process.env.RALPH_DEBUG === 'true') {
         registerDebugTools(server, client);

package/dist/lib/cycle-times.js

@@ -0,0 +1,161 @@
+/**
+ * Pure cycle-time rollup over `TransitionRecord[]` extracted from
+ * issue comments by `parseAllTransitions()`.
+ *
+ * Phase 2 (GH-1023) of the product-performance-over-time epic (#1019).
+ *
+ * Inputs are a list of `TransitionedIssue` (issueNumber + transitions
+ * + optional `closedAt`). Output is a `CycleTimeRollup` with p50/p90
+ * lead-time across issues and per-phase dwell percentiles.
+ *
+ * Semantics:
+ *   - **Lead-time** per issue = `(last.at - first.at)` in hours. Issues
+ *     with `< 2` valid transitions are excluded from the lead-time
+ *     sample. `sampleSize` counts only included issues.
+ *   - **Per-phase dwell** = consecutive `(transition[i+1].at -
+ *     transition[i].at)` keyed by `transition[i].from`. The terminal
+ *     state's dwell uses `closedAt ?? now` as the upper bound when the
+ *     issue has not transitioned out of it. If `closedAt` is missing
+ *     (issue still open), the open-ended terminal dwell is excluded.
+ *   - **Out-of-order tolerance**: transitions are defensively sorted
+ *     by `at` ascending before computation. Original arrays are not
+ *     mutated.
+ *   - **Malformed timestamps**: any transition whose `at` does not
+ *     parse to a finite epoch (`Number.isFinite(Date.parse(at)) ===
+ *     false`) is skipped without throwing.
+ *   - **Percentiles**: linear-interpolation nearest-rank. With `n =
+ *     1`, both p50 and p90 equal the single value. With `n = 0`, the
+ *     phase entry is omitted from `perPhaseDwellHours`; lead-time
+ *     fields are `null`.
+ *
+ * Pure: no I/O, deterministic, safe to call from any context.
+ */
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+const MS_PER_HOUR = 3_600_000;
+/** Parse an ISO timestamp; return `null` when not finite. */
+function parseAt(at) {
+    const ms = Date.parse(at);
+    return Number.isFinite(ms) ? ms : null;
+}
+/**
+ * Linear-interpolation nearest-rank percentile over a sorted (ascending)
+ * array of finite numbers. `p` is in [0, 1]. Caller must ensure the
+ * array is non-empty and sorted.
+ */
+function percentile(sorted, p) {
+    const n = sorted.length;
+    if (n === 1)
+        return sorted[0];
+    // rank in [0, n-1] (zero-indexed)
+    const rank = p * (n - 1);
+    const lo = Math.floor(rank);
+    const hi = Math.ceil(rank);
+    if (lo === hi)
+        return sorted[lo];
+    const frac = rank - lo;
+    return sorted[lo] + (sorted[hi] - sorted[lo]) * frac;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Roll up lead-time and per-phase dwell-time across a batch of
+ * transitioned issues.
+ *
+ * @param records  One entry per issue with parsed transitions.
+ * @param now      Epoch milliseconds — used to bound the terminal-state
+ *                 dwell when `closedAt` is missing on a non-terminal
+ *                 issue. Always pass `Date.now()` from production code;
+ *                 tests inject a fixed value for determinism.
+ */
+export function rollupCycleTimes(records, now) {
+    const leadTimes = [];
+    const phaseBuckets = {};
+    for (const rec of records) {
+        // Filter + parse + sort defensively. Do not mutate the caller's array.
+        const valid = rec.transitions
+            .map((t) => {
+            const ms = parseAt(t.at);
+            return ms === null ? null : { t, ms };
+        })
+            .filter((x) => x !== null)
+            .sort((a, b) => a.ms - b.ms);
+        if (valid.length === 0)
+            continue;
+        // Lead-time: only when the issue has >= 2 valid transitions.
+        if (valid.length >= 2) {
+            const firstMs = valid[0].ms;
+            const lastMs = valid[valid.length - 1].ms;
+            const hours = (lastMs - firstMs) / MS_PER_HOUR;
+            if (Number.isFinite(hours) && hours >= 0) {
+                leadTimes.push(hours);
+            }
+        }
+        // Per-phase dwell from consecutive intervals.
+        for (let i = 0; i < valid.length - 1; i++) {
+            const fromState = valid[i].t.from;
+            const dwellHours = (valid[i + 1].ms - valid[i].ms) / MS_PER_HOUR;
+            if (!Number.isFinite(dwellHours) || dwellHours < 0)
+                continue;
+            (phaseBuckets[fromState] ??= []).push(dwellHours);
+        }
+        // Terminal-state dwell: from the last transition's `to` state until
+        // either `closedAt` (if present) or `now` (if the issue is open).
+        // If the issue is open AND `closedAt` is missing, the terminal
+        // dwell is open-ended and excluded — matches the Phase 2 spec.
+        const last = valid[valid.length - 1];
+        const terminalState = last.t.to;
+        let upperMs = null;
+        if (rec.closedAt) {
+            const cMs = parseAt(rec.closedAt);
+            if (cMs !== null)
+                upperMs = cMs;
+        }
+        else {
+            // Open issue: skip open-ended terminal dwell rather than
+            // synthesising a value from `now`. (Spec: open-ended terminal
+            // dwell is excluded when `closedAt` is missing AND the issue is
+            // open.)
+            upperMs = null;
+        }
+        if (upperMs !== null) {
+            const dwellHours = (upperMs - last.ms) / MS_PER_HOUR;
+            if (Number.isFinite(dwellHours) && dwellHours >= 0) {
+                (phaseBuckets[terminalState] ??= []).push(dwellHours);
+            }
+        }
+    }
+    // ----- assemble percentile output -----------------------------------------
+    const perPhaseDwellHours = {};
+    for (const [phase, samples] of Object.entries(phaseBuckets)) {
+        if (samples.length === 0)
+            continue;
+        const sorted = [...samples].sort((a, b) => a - b);
+        perPhaseDwellHours[phase] = {
+            p50: percentile(sorted, 0.5),
+            p90: percentile(sorted, 0.9),
+            n: sorted.length,
+        };
+    }
+    let leadTimeP50Hours = null;
+    let leadTimeP90Hours = null;
+    if (leadTimes.length > 0) {
+        const sorted = [...leadTimes].sort((a, b) => a - b);
+        leadTimeP50Hours = percentile(sorted, 0.5);
+        leadTimeP90Hours = percentile(sorted, 0.9);
+    }
+    // Reference `now` for callers that want to bound things in the future.
+    // The current spec excludes open-ended terminal dwell, but `now` is
+    // retained in the API surface for forward-compat. Touch it here so
+    // strict-mode TS does not flag it as unused.
+    void now;
+    return {
+        leadTimeP50Hours,
+        leadTimeP90Hours,
+        perPhaseDwellHours,
+        sampleSize: leadTimes.length,
+    };
+}
+//# sourceMappingURL=cycle-times.js.map

package/dist/lib/dashboard-fetch.js

@@ -0,0 +1,194 @@
+/**
+ * Reusable helper for fetching project items as DashboardItem[].
+ *
+ * Owns the GraphQL query (`DASHBOARD_ITEMS_QUERY`), the raw item shape
+ * (`RawDashboardItem`), and the raw→DashboardItem conversion
+ * (`toDashboardItems`). Previously these lived inline in
+ * `tools/dashboard-tools.ts`; centralising them lets
+ * `ralph_hero__capture_snapshot` and any future tool reuse the same
+ * fetch path without duplicating the GraphQL or conversion logic.
+ *
+ * Behaviour mirrors the inline fetch loop the dashboard tool used to
+ * run:
+ *   - Resolve target project numbers (explicit arg →
+ *     projectNumbers config → projectNumber config).
+ *   - For each project: ensure field cache, look up project ID, fetch
+ *     project title (best-effort), paginate the items connection,
+ *     convert to DashboardItems tagged with project metadata.
+ *   - Skip a project on field-cache failure or missing project ID;
+ *     record a human-readable warning so the caller can surface it.
+ */
+import { ensureFieldCache } from "./helpers.js";
+import { paginateConnection } from "./pagination.js";
+import { resolveProjectNumbers, resolveProjectOwner } from "../types.js";
+function getFieldValue(item, fieldName) {
+    const fv = item.fieldValues.nodes.find((n) => n.field?.name === fieldName &&
+        n.__typename === "ProjectV2ItemFieldSingleSelectValue");
+    return fv?.name ?? null;
+}
+/**
+ * Convert raw GraphQL project items to DashboardItem[].
+ * When projectNumber/projectTitle are provided, they are set on each item
+ * for multi-project dashboard support.
+ */
+export function toDashboardItems(raw, projectNumber, projectTitle) {
+    const items = [];
+    for (const r of raw) {
+        // Only include issues (not PRs or drafts)
+        if (!r.content || r.content.__typename !== "Issue")
+            continue;
+        if (r.content.number === undefined)
+            continue;
+        // Extract iteration value (if any)
+        const iterFv = r.fieldValues.nodes.find((n) => n.__typename === "ProjectV2ItemFieldIterationValue");
+        items.push({
+            number: r.content.number,
+            title: r.content.title ?? "(untitled)",
+            updatedAt: r.content.updatedAt ?? new Date(0).toISOString(),
+            closedAt: r.content.closedAt ?? null,
+            workflowState: getFieldValue(r, "Workflow State"),
+            priority: getFieldValue(r, "Priority"),
+            estimate: getFieldValue(r, "Estimate"),
+            assignees: r.content.assignees?.nodes?.map((a) => a.login) ?? [],
+            subIssueCount: r.content.subIssues?.totalCount ?? 0,
+            blockedBy: r.content.trackedIssues?.nodes?.map((n) => ({
+                number: n.number,
+                workflowState: n.state === "CLOSED" ? "Done" : null,
+            })) ?? [],
+            parentNumber: r.content.trackedInIssues?.nodes?.[0]?.number ?? null,
+            parentState: r.content.trackedInIssues?.nodes?.[0]?.state ?? null,
+            ...(projectNumber !== undefined ? { projectNumber } : {}),
+            ...(projectTitle !== undefined ? { projectTitle } : {}),
+            ...(r.content.repository ? { repository: r.content.repository.nameWithOwner } : {}),
+            ...(iterFv?.iterationId ? {
+                iterationId: iterFv.iterationId,
+                iterationTitle: iterFv.title ?? undefined,
+                iterationStartDate: iterFv.startDate ?? undefined,
+                iterationDuration: iterFv.duration ?? undefined,
+            } : {}),
+        });
+    }
+    return items;
+}
+// ---------------------------------------------------------------------------
+// GraphQL query for dashboard items
+// ---------------------------------------------------------------------------
+export const DASHBOARD_ITEMS_QUERY = `query($projectId: ID!, $cursor: String, $first: Int!) {
+  node(id: $projectId) {
+    ... on ProjectV2 {
+      items(first: $first, after: $cursor) {
+        totalCount
+        pageInfo { hasNextPage endCursor }
+        nodes {
+          id
+          type
+          content {
+            ... on Issue {
+              __typename
+              number
+              title
+              state
+              updatedAt
+              closedAt
+              assignees(first: 5) { nodes { login } }
+              repository { nameWithOwner name }
+              subIssues { totalCount }
+              trackedIssues(first: 10) { nodes { number state } }
+              trackedInIssues(first: 3) { nodes { number state closedAt } }
+            }
+            ... on PullRequest {
+              __typename
+              number
+              title
+              state
+            }
+            ... on DraftIssue {
+              __typename
+              title
+            }
+          }
+          fieldValues(first: 20) {
+            nodes {
+              ... on ProjectV2ItemFieldSingleSelectValue {
+                __typename
+                name
+                field { ... on ProjectV2FieldCommon { name } }
+              }
+              ... on ProjectV2ItemFieldIterationValue {
+                __typename
+                iterationId
+                title
+                startDate
+                duration
+                field { ... on ProjectV2FieldCommon { name } }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}`;
+/**
+ * Resolve project numbers to fetch from arg + client config.
+ *
+ * Priority:
+ *   1. Explicit `projectNumber` argument (single project).
+ *   2. `client.config.projectNumbers` (multi-project).
+ *   3. `client.config.projectNumber` (single project).
+ */
+function resolveTargetProjectNumbers(client, projectNumber) {
+    if (projectNumber !== undefined)
+        return [projectNumber];
+    return resolveProjectNumbers(client.config);
+}
+/**
+ * Fetch dashboard items for one or more projects, returning a flat
+ * `DashboardItem[]` plus any per-project fetch warnings.
+ *
+ * The owner is resolved from `client.config` via `resolveProjectOwner`.
+ *
+ * Throws if no owner can be resolved or if no project numbers are
+ * configured. Per-project failures (missing project, field-cache
+ * failure, missing project ID) are non-fatal — those projects are
+ * skipped with a warning so a partial dashboard is still produced.
+ */
+export async function fetchDashboardItems(client, fieldCache, projectNumber) {
+    const owner = resolveProjectOwner(client.config);
+    if (!owner) {
+        throw new Error("owner is required (set RALPH_GH_OWNER)");
+    }
+    const projectNumbers = resolveTargetProjectNumbers(client, projectNumber);
+    if (projectNumbers.length === 0) {
+        throw new Error("No project numbers configured. Set RALPH_GH_PROJECT_NUMBER or RALPH_GH_PROJECT_NUMBERS.");
+    }
+    const items = [];
+    const warnings = [];
+    for (const pn of projectNumbers) {
+        try {
+            await ensureFieldCache(client, fieldCache, owner, pn);
+        }
+        catch (e) {
+            warnings.push(`Project #${pn}: ${e instanceof Error ? e.message : String(e)}, skipping`);
+            continue;
+        }
+        const projectId = fieldCache.getProjectId(pn);
+        if (!projectId) {
+            warnings.push(`Project #${pn}: could not resolve project ID, skipping`);
+            continue;
+        }
+        // Fetch project title (non-fatal on failure)
+        let projectTitle;
+        try {
+            const titleResult = await client.projectQuery(`query($projectId: ID!) { node(id: $projectId) { ... on ProjectV2 { title } } }`, { projectId });
+            projectTitle = titleResult.node?.title;
+        }
+        catch {
+            // Non-fatal — proceed without title.
+        }
+        const result = await paginateConnection((q, v) => client.projectQuery(q, v), DASHBOARD_ITEMS_QUERY, { projectId, first: 100 }, "node.items", { maxItems: 500 });
+        items.push(...toDashboardItems(result.nodes, pn, projectTitle));
+    }
+    return { items, warnings };
+}
+//# sourceMappingURL=dashboard-fetch.js.map

package/dist/lib/hygiene.js

@@ -5,6 +5,7 @@
  * I/O (GraphQL fetching) lives in tools/hygiene-tools.ts.
  */
 import { TERMINAL_STATES } from "./workflow-states.js";
+import { groupDashboardItemsByRepo } from "./dashboard.js";
 export const DEFAULT_HYGIENE_CONFIG = {
     archiveDays: 14,
     staleDays: 7,
@@ -24,6 +25,7 @@ function toHygieneItem(item, now) {
         title: item.title,
         workflowState: item.workflowState,
         ageDays: Math.round(ageDays(item.updatedAt, now) * 10) / 10,
+        ...(item.repository ? { repository: item.repository } : {}),
     };
 }
 // ---------------------------------------------------------------------------
@@ -190,6 +192,45 @@ export function findDuplicateCandidates(items, now, threshold) {
 // ---------------------------------------------------------------------------
 // Orchestrator
 // ---------------------------------------------------------------------------
+/**
+ * Build a per-repo hygiene breakdown. Runs each section function over the
+ * supplied items (a single repo's subset of the merged item set).
+ *
+ * Does NOT recursively emit `repoBreakdowns` — per-repo breakdowns are flat.
+ */
+function buildRepoBreakdown(repoName, items, config, now) {
+    const archiveCandidates = findArchiveCandidates(items, now, config.archiveDays);
+    const staleItems = findStaleItems(items, now, config.staleDays);
+    const orphanedItems = findOrphanedItems(items, now, config.orphanDays);
+    const fieldGaps = findFieldGaps(items, now);
+    const wipViolations = findWipViolations(items, now, config.wipLimits);
+    const duplicateCandidates = findDuplicateCandidates(items, now, config.similarityThreshold);
+    const nonTerminal = items.filter((item) => {
+        const ws = item.workflowState;
+        return !ws || !TERMINAL_STATES.includes(ws);
+    });
+    const withBothFields = nonTerminal.filter((item) => item.estimate !== null && item.priority !== null);
+    const fieldCoveragePercent = nonTerminal.length > 0
+        ? Math.round((withBothFields.length / nonTerminal.length) * 100)
+        : 100;
+    return {
+        repoName,
+        archiveCandidates,
+        staleItems,
+        orphanedItems,
+        fieldGaps,
+        wipViolations,
+        duplicateCandidates,
+        summary: {
+            archiveCandidateCount: archiveCandidates.length,
+            staleCount: staleItems.length,
+            orphanCount: orphanedItems.length,
+            fieldCoveragePercent,
+            wipViolationCount: wipViolations.length,
+            duplicateCandidateCount: duplicateCandidates.length,
+        },
+    };
+}
 /**
  * Build a complete hygiene report from project items.
  */
@@ -209,6 +250,16 @@ export function buildHygieneReport(items, config = DEFAULT_HYGIENE_CONFIG, now =
     const fieldCoveragePercent = nonTerminal.length > 0
         ? Math.round((withBothFields.length / nonTerminal.length) * 100)
         : 100;
+    // Per-repo breakdown (only emitted when items span 2+ repos, mirroring
+    // buildDashboard's repoBreakdowns threshold at lib/dashboard.ts:781).
+    const repoGroups = groupDashboardItemsByRepo(items);
+    let repoBreakdowns;
+    if (Object.keys(repoGroups).length >= 2) {
+        repoBreakdowns = {};
+        for (const [repoName, repoItems] of Object.entries(repoGroups)) {
+            repoBreakdowns[repoName] = buildRepoBreakdown(repoName, repoItems, config, now);
+        }
+    }
     return {
         generatedAt: new Date(now).toISOString(),
         totalItems: items.length,
@@ -226,6 +277,7 @@ export function buildHygieneReport(items, config = DEFAULT_HYGIENE_CONFIG, now =
             wipViolationCount: wipViolations.length,
             duplicateCandidateCount: duplicateCandidates.length,
         },
+        ...(repoBreakdowns ? { repoBreakdowns } : {}),
     };
 }
 // ---------------------------------------------------------------------------
@@ -331,6 +383,101 @@ export function formatHygieneMarkdown(report) {
         }
         lines.push("");
     }
+    // Per-repository breakdown (only for multi-repo). Mirrors
+    // formatMarkdown's per-repo rendering at lib/dashboard.ts:948+.
+    if (report.repoBreakdowns &&
+        Object.keys(report.repoBreakdowns).length >= 2) {
+        lines.push("## Per-Repository Breakdown");
+        lines.push("");
+        const sortedRepos = Object.values(report.repoBreakdowns).sort((a, b) => a.repoName.localeCompare(b.repoName));
+        for (const repo of sortedRepos) {
+            lines.push(`### ${repo.repoName}`);
+            lines.push("");
+            let renderedAny = false;
+            if (repo.archiveCandidates.length > 0) {
+                lines.push("#### Archive Candidates");
+                lines.push("| Issue | Title | State | Age |");
+                lines.push("|-------|-------|-------|-----|");
+                for (const item of repo.archiveCandidates) {
+                    lines.push(formatItemRow(item));
+                }
+                lines.push("");
+                renderedAny = true;
+            }
+            if (repo.staleItems.length > 0) {
+                lines.push("#### Stale Items");
+                lines.push("| Issue | Title | State | Age |");
+                lines.push("|-------|-------|-------|-----|");
+                for (const item of repo.staleItems) {
+                    lines.push(formatItemRow(item));
+                }
+                lines.push("");
+                renderedAny = true;
+            }
+            if (repo.orphanedItems.length > 0) {
+                lines.push("#### Orphaned Items");
+                lines.push("| Issue | Title | State | Age |");
+                lines.push("|-------|-------|-------|-----|");
+                for (const item of repo.orphanedItems) {
+                    lines.push(formatItemRow(item));
+                }
+                lines.push("");
+                renderedAny = true;
+            }
+            const repoTotalGaps = repo.fieldGaps.missingEstimate.length +
+                repo.fieldGaps.missingPriority.length;
+            if (repoTotalGaps > 0) {
+                lines.push("#### Field Gaps");
+                if (repo.fieldGaps.missingEstimate.length > 0) {
+                    lines.push("##### Missing Estimate");
+                    lines.push("| Issue | Title | State | Age |");
+                    lines.push("|-------|-------|-------|-----|");
+                    for (const item of repo.fieldGaps.missingEstimate) {
+                        lines.push(formatItemRow(item));
+                    }
+                    lines.push("");
+                }
+                if (repo.fieldGaps.missingPriority.length > 0) {
+                    lines.push("##### Missing Priority");
+                    lines.push("| Issue | Title | State | Age |");
+                    lines.push("|-------|-------|-------|-----|");
+                    for (const item of repo.fieldGaps.missingPriority) {
+                        lines.push(formatItemRow(item));
+                    }
+                    lines.push("");
+                }
+                renderedAny = true;
+            }
+            if (repo.wipViolations.length > 0) {
+                lines.push("#### WIP Violations");
+                for (const v of repo.wipViolations) {
+                    lines.push(`##### ${v.state}: ${v.count} items (limit: ${v.limit})`);
+                    lines.push("| Issue | Title | State | Age |");
+                    lines.push("|-------|-------|-------|-----|");
+                    for (const item of v.items) {
+                        lines.push(formatItemRow(item));
+                    }
+                    lines.push("");
+                }
+                renderedAny = true;
+            }
+            if (repo.duplicateCandidates.length > 0) {
+                lines.push("#### Duplicate Candidates");
+                lines.push("| Issue A | Title A | Issue B | Title B | Similarity |");
+                lines.push("|---------|---------|---------|---------|------------|");
+                for (const dup of repo.duplicateCandidates) {
+                    const [a, b] = dup.items;
+                    lines.push(`| #${a.number} | ${a.title} | #${b.number} | ${b.title} | ${dup.similarity.toFixed(2)} |`);
+                }
+                lines.push("");
+                renderedAny = true;
+            }
+            if (!renderedAny) {
+                lines.push("_No hygiene issues_");
+                lines.push("");
+            }
+        }
+    }
     return lines.join("\n");
 }
 //# sourceMappingURL=hygiene.js.map

package/dist/lib/pagination.js

@@ -18,20 +18,6 @@ function getNestedValue(obj, path) {
     }
     return current;
 }
-/**
- * Set a nested value on an object using a dot-separated path.
- */
-function setNestedValue(obj, path, value) {
-    const parts = path.split(".");
-    let current = obj;
-    for (let i = 0; i < parts.length - 1; i++) {
-        if (current[parts[i]] == null || typeof current[parts[i]] !== "object") {
-            current[parts[i]] = {};
-        }
-        current = current[parts[i]];
-    }
-    current[parts[parts.length - 1]] = value;
-}
 /**
  * Paginate a GraphQL connection query.
  *