@mcptoolshop/promo-kit 0.1.0

package/scripts/gen-queue-health.mjs

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+
+/**
+ * Queue Health Analyzer
+ *
+ * Analyzes submissions.json for queue health metrics:
+ * time-in-status, stuck submissions, lint failure reasons, throughput.
+ *
+ * Usage:
+ *   node scripts/gen-queue-health.mjs [--dry-run]
+ *
+ * Reads:
+ *   site/src/data/submissions.json
+ *   lint-reports/*.json (if present)
+ *
+ * Writes:
+ *   site/src/data/queue-health.json
+ */
+
+import { readFileSync, readdirSync, writeFileSync, existsSync } from "node:fs";
+import { resolve, join } from "node:path";
+import { getConfig, getRoot } from "./lib/config.mjs";
+
+const ROOT = getRoot();
+const config = getConfig();
+
+const STUCK_THRESHOLD_DAYS = 7;
+const THROUGHPUT_WINDOW_DAYS = 30;
+
+// ── Helpers ───────────────────────────────────────────────────
+
+function daysBetween(isoA, isoB) {
+  const a = new Date(isoA);
+  const b = new Date(isoB);
+  return Math.abs(b - a) / (1000 * 60 * 60 * 24);
+}
+
+function median(values) {
+  if (values.length === 0) return null;
+  const sorted = [...values].sort((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+  return sorted.length % 2 === 0
+    ? (sorted[mid - 1] + sorted[mid]) / 2
+    : sorted[mid];
+}
+
+// ── Core analysis ─────────────────────────────────────────────
+
+/**
+ * Compute time-in-status for submissions that have updatedAt.
+ * @param {object[]} submissions
+ * @returns {Record<string, number|null>} status → median days
+ */
+export function computeTimeInStatus(submissions) {
+  const durationsByStatus = {};
+
+  for (const s of submissions) {
+    if (!s.submittedAt) continue;
+    const endDate = s.updatedAt || new Date().toISOString();
+    const days = daysBetween(s.submittedAt, endDate);
+
+    if (!durationsByStatus[s.status]) durationsByStatus[s.status] = [];
+    durationsByStatus[s.status].push(Math.round(days * 10) / 10);
+  }
+
+  const result = {};
+  for (const [status, durations] of Object.entries(durationsByStatus)) {
+    result[status] = median(durations);
+  }
+  return result;
+}
+
+/**
+ * Analyze queue health from submissions data.
+ * @param {object[]} submissions
+ * @param {{ lintReports?: Record<string, object>, now?: Date }} opts
+ * @returns {object}
+ */
+export function analyzeQueueHealth(submissions, opts = {}) {
+  const { lintReports = {}, now = new Date() } = opts;
+  const nowIso = now.toISOString();
+
+  if (!submissions || submissions.length === 0) {
+    return {
+      generatedAt: nowIso,
+      submissions: 0,
+      byStatus: {},
+      stuckCount: 0,
+      stuckSlugs: [],
+      topLintFailures: [],
+      medianDaysPending: null,
+      throughput: 0,
+    };
+  }
+
+  // Count by status
+  const byStatus = {};
+  for (const s of submissions) {
+    byStatus[s.status] = (byStatus[s.status] || 0) + 1;
+  }
+
+  // Stuck submissions (pending or needs-info > 7 days)
+  const stuckSlugs = [];
+  for (const s of submissions) {
+    if (s.status === "pending" || s.status === "needs-info") {
+      const days = daysBetween(s.submittedAt, nowIso);
+      if (days > STUCK_THRESHOLD_DAYS) {
+        stuckSlugs.push({ slug: s.slug, status: s.status, daysPending: Math.round(days) });
+      }
+    }
+  }
+
+  // Median days pending (for completed submissions: accepted or rejected)
+  const completedDays = submissions
+    .filter((s) => (s.status === "accepted" || s.status === "rejected") && s.updatedAt)
+    .map((s) => daysBetween(s.submittedAt, s.updatedAt));
+  const medianDaysPending = median(completedDays);
+
+  // Throughput (accepted in trailing 30 days)
+  const windowStart = new Date(now.getTime() - THROUGHPUT_WINDOW_DAYS * 24 * 60 * 60 * 1000);
+  const throughput = submissions.filter(
+    (s) => s.status === "accepted" && s.updatedAt && new Date(s.updatedAt) >= windowStart,
+  ).length;
+
+  // Top lint failures from lint reports
+  const failureCounts = {};
+  for (const report of Object.values(lintReports)) {
+    if (report.errors) {
+      for (const err of report.errors) {
+        failureCounts[err] = (failureCounts[err] || 0) + 1;
+      }
+    }
+    if (report.warnings) {
+      for (const warn of report.warnings) {
+        failureCounts[warn] = (failureCounts[warn] || 0) + 1;
+      }
+    }
+  }
+  const topLintFailures = Object.entries(failureCounts)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 10)
+    .map(([reason, count]) => ({ reason, count }));
+
+  return {
+    generatedAt: nowIso,
+    submissions: submissions.length,
+    byStatus,
+    stuckCount: stuckSlugs.length,
+    stuckSlugs,
+    topLintFailures,
+    medianDaysPending: medianDaysPending !== null ? Math.round(medianDaysPending * 10) / 10 : null,
+    throughput,
+  };
+}
+
+// ── Pipeline ──────────────────────────────────────────────────
+
+/**
+ * Read submissions + lint reports, analyze, write output.
+ * @param {{ submissionsPath?: string, lintDir?: string, outputPath?: string, dryRun?: boolean }} opts
+ */
+export function genQueueHealth(opts = {}) {
+  const {
+    submissionsPath = join(ROOT, config.paths.dataDir, "submissions.json"),
+    lintDir = join(ROOT, "lint-reports"),
+    outputPath = join(ROOT, config.paths.dataDir, "queue-health.json"),
+    dryRun = false,
+  } = opts;
+
+  // Load submissions
+  let submissions = [];
+  try {
+    const data = JSON.parse(readFileSync(submissionsPath, "utf8"));
+    submissions = data.submissions || [];
+  } catch {
+    // no submissions file
+  }
+
+  // Load lint reports
+  const lintReports = {};
+  if (existsSync(lintDir)) {
+    const files = readdirSync(lintDir).filter((f) => f.endsWith(".json"));
+    for (const file of files) {
+      try {
+        const slug = file.replace(".json", "");
+        lintReports[slug] = JSON.parse(readFileSync(join(lintDir, file), "utf8"));
+      } catch {
+        // skip malformed
+      }
+    }
+  }
+
+  const result = analyzeQueueHealth(submissions, { lintReports });
+
+  if (dryRun) {
+    console.log(`  [dry-run] Queue health analysis complete.`);
+    console.log(`    Submissions: ${result.submissions}`);
+    console.log(`    Stuck: ${result.stuckCount}`);
+    console.log(`    Throughput (30d): ${result.throughput}`);
+    return result;
+  }
+
+  writeFileSync(outputPath, JSON.stringify(result, null, 2) + "\n", "utf8");
+  return result;
+}
+
+// ── Entry point ───────────────────────────────────────────────
+
+const isMain = process.argv[1] && resolve(process.argv[1]).endsWith("gen-queue-health.mjs");
+if (isMain) {
+  const dryRun = process.argv.includes("--dry-run");
+  console.log("Analyzing queue health...");
+  if (dryRun) console.log("  Mode: DRY RUN");
+
+  const result = genQueueHealth({ dryRun });
+  if (!dryRun) {
+    console.log(`  Submissions: ${result.submissions}`);
+    console.log(`  By status: ${JSON.stringify(result.byStatus)}`);
+    console.log(`  Stuck: ${result.stuckCount}`);
+    console.log(`  Median days pending: ${result.medianDaysPending ?? "N/A"}`);
+    console.log(`  Throughput (30d): ${result.throughput}`);
+  }
+}

package/scripts/gen-recommendation-patch.mjs

@@ -0,0 +1,352 @@
+#!/usr/bin/env node
+/**
+ * gen-recommendation-patch.mjs
+ *
+ * Translates advisory recommendations into governed, auditable patches.
+ * Only certain recommendation categories produce actual data file changes;
+ * the rest become advisory notes included in the PR body.
+ *
+ * Respects freeze modes, promo queue caps, and max patch limits.
+ * Deterministic: same inputs → same patch plan (timestamps only in audit artifact).
+ *
+ * Usage:
+ *   node scripts/gen-recommendation-patch.mjs [--dry-run]
+ *
+ * Reads:
+ *   site/src/data/recommendations.json
+ *   site/src/data/governance.json
+ *   site/src/data/promo-queue.json
+ *   site/src/data/experiments.json
+ *
+ * Writes:
+ *   site/src/data/promo-queue.json      (if re-feature patches)
+ *   site/src/data/experiments.json       (if graduation patches)
+ *   site/src/data/recommendation-patch.json (audit artifact, always)
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { getConfig, getRoot } from "./lib/config.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = getRoot();
+const config = getConfig();
+const DATA_DIR = path.join(ROOT, config.paths.dataDir);
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url));
+
+// ── Constants ────────────────────────────────────────────────
+
+export const ALLOWED_TARGET_FILES = new Set(["promo-queue.json", "experiments.json"]);
+export const MAX_DATA_PATCHES_DEFAULT = 5;
+
+// Categories that produce actual data file changes
+const PATCHABLE_CATEGORIES = new Set(["re-feature", "experiment-graduation"]);
+
+// ── Helpers ──────────────────────────────────────────────────
+
+function loadJsonSafe(filePath, fallback = null) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    return fallback;
+  }
+}
+
+// ── Core Functions (exported for testing) ────────────────────
+
+/**
+ * Translate a single recommendation into a patch, advisory note, or frozen action.
+ * @param {object} rec - recommendation from recommendations.json
+ * @param {object} governance - governance.json contents
+ * @param {object} currentData - { promoQueue, experiments }
+ * @returns {{ type: "patch"|"advisory"|"frozen", patch?: object, note: string, riskNote?: string }}
+ */
+export function translateRecommendation(rec, governance, currentData) {
+  const { category, slug } = rec;
+
+  // ── re-feature: add slug to promo queue ──
+  if (category === "re-feature") {
+    if (governance.decisionsFrozen) {
+      return {
+        type: "frozen",
+        note: `decisionsFrozen — skipped re-feature for "${slug}"`,
+      };
+    }
+
+    const queue = currentData.promoQueue;
+    const currentSlugs = queue.slugs || [];
+    const maxPerWeek = governance.maxPromosPerWeek || 3;
+
+    if (currentSlugs.includes(slug)) {
+      return {
+        type: "advisory",
+        note: `Already in promo queue`,
+      };
+    }
+
+    if (currentSlugs.length >= maxPerWeek) {
+      return {
+        type: "advisory",
+        note: `Promo queue full (${currentSlugs.length}/${maxPerWeek})`,
+      };
+    }
+
+    const newSlugs = [...currentSlugs, slug];
+    return {
+      type: "patch",
+      patch: {
+        category: "re-feature",
+        slug,
+        targetFile: "promo-queue.json",
+        description: `Add ${slug} to promo queue (${rec.evidence?.proofEngagementScore ? `proof engagement: ${rec.evidence.proofEngagementScore}` : "re-feature"})`,
+        riskNote: `Promo queue now has ${newSlugs.length}/${maxPerWeek} slots filled`,
+        apply: { slugs: newSlugs },
+      },
+      note: `Add to promo queue`,
+      riskNote: `Promo queue now has ${newSlugs.length}/${maxPerWeek} slots filled`,
+    };
+  }
+
+  // ── experiment-graduation: set experiment status to concluded ──
+  if (category === "experiment-graduation") {
+    if (governance.experimentsFrozen) {
+      return {
+        type: "frozen",
+        note: `experimentsFrozen — skipped graduation for "${slug}"`,
+      };
+    }
+
+    const experiments = currentData.experiments.experiments || [];
+    const match = experiments.find((e) => e.id === slug);
+
+    if (!match) {
+      return {
+        type: "advisory",
+        note: `Experiment "${slug}" not found in experiments.json`,
+      };
+    }
+
+    if (match.status === "concluded") {
+      return {
+        type: "advisory",
+        note: `Experiment "${slug}" already concluded`,
+      };
+    }
+
+    const updatedExperiments = experiments.map((e) =>
+      e.id === slug ? { ...e, status: "concluded" } : e,
+    );
+
+    return {
+      type: "patch",
+      patch: {
+        category: "experiment-graduation",
+        slug,
+        targetFile: "experiments.json",
+        description: `Graduate experiment ${slug} (winner: ${rec.evidence?.winnerKey || "unknown"})`,
+        riskNote: `Experiment ${slug} will be marked concluded`,
+        apply: { experiments: updatedExperiments },
+      },
+      note: `Graduate experiment`,
+      riskNote: `Experiment ${slug} will be marked concluded`,
+    };
+  }
+
+  // ── Advisory-only categories ──
+  if (category === "improve-proof") {
+    return {
+      type: "advisory",
+      note: `${rec.insight || "Low proof engagement — improve evidence quality"}`,
+    };
+  }
+
+  if (category === "stuck-submission") {
+    return {
+      type: "advisory",
+      note: `${rec.insight || "High friction submission — needs attention"}`,
+    };
+  }
+
+  if (category === "lint-promotion") {
+    return {
+      type: "advisory",
+      note: `${rec.insight || "Lint warning pattern — consider promoting to error"}`,
+    };
+  }
+
+  // ── Unknown category fallback ──
+  return {
+    type: "advisory",
+    note: `Unknown category "${category}" — advisory only`,
+  };
+}
+
+/**
+ * Build a complete patch plan from all recommendations.
+ * @param {object[]} recommendations
+ * @param {object} governance
+ * @param {object} currentData - { promoQueue, experiments }
+ * @param {{ maxPatches?: number }} opts
+ * @returns {{ patches: object[], advisoryNotes: object[], riskNotes: string[], frozenActions: object[] }}
+ */
+export function buildPatchPlan(recommendations, governance, currentData, opts = {}) {
+  const { maxPatches = MAX_DATA_PATCHES_DEFAULT } = opts;
+
+  const patches = [];
+  const advisoryNotes = [];
+  const riskNotes = [];
+  const frozenActions = [];
+
+  // Track evolving state for incremental queue fills
+  const evolving = {
+    promoQueue: JSON.parse(JSON.stringify(currentData.promoQueue)),
+    experiments: JSON.parse(JSON.stringify(currentData.experiments)),
+  };
+
+  for (const rec of recommendations) {
+    const result = translateRecommendation(rec, governance, evolving);
+
+    if (result.type === "patch") {
+      if (patches.length >= maxPatches) {
+        // Exceeded cap — downgrade to advisory
+        advisoryNotes.push({
+          category: rec.category,
+          slug: rec.slug,
+          note: `Exceeded max patch cap (${maxPatches}) — ${result.note}`,
+        });
+        continue;
+      }
+
+      patches.push(result.patch);
+      if (result.riskNote) riskNotes.push(result.riskNote);
+
+      // Update evolving state so subsequent recommendations see the changes
+      if (result.patch.targetFile === "promo-queue.json" && result.patch.apply?.slugs) {
+        evolving.promoQueue = { ...evolving.promoQueue, slugs: result.patch.apply.slugs };
+      }
+      if (result.patch.targetFile === "experiments.json" && result.patch.apply?.experiments) {
+        evolving.experiments = { ...evolving.experiments, experiments: result.patch.apply.experiments };
+      }
+    } else if (result.type === "frozen") {
+      frozenActions.push({
+        category: rec.category,
+        slug: rec.slug,
+        note: result.note,
+      });
+    } else {
+      // advisory
+      advisoryNotes.push({
+        category: rec.category,
+        slug: rec.slug,
+        note: result.note,
+      });
+    }
+  }
+
+  return { patches, advisoryNotes, riskNotes, frozenActions };
+}
+
+/**
+ * Apply patch plan to data files on disk.
+ * @param {object[]} patches - from buildPatchPlan().patches
+ * @param {object} currentData - { promoQueue, experiments }
+ * @param {{ dataDir?: string }} opts
+ * @returns {{ filesWritten: string[] }}
+ */
+export function applyPatchesToFiles(patches, currentData, opts = {}) {
+  const { dataDir = DATA_DIR } = opts;
+  const filesWritten = [];
+
+  // Group patches by target file to coalesce writes
+  const byFile = {};
+  for (const p of patches) {
+    if (!byFile[p.targetFile]) byFile[p.targetFile] = [];
+    byFile[p.targetFile].push(p);
+  }
+
+  for (const [file, filePatches] of Object.entries(byFile)) {
+    const filePath = path.join(dataDir, file);
+    let current = loadJsonSafe(filePath, {});
+
+    // Apply each patch's changes sequentially
+    for (const p of filePatches) {
+      if (p.apply) {
+        current = { ...current, ...p.apply };
+      }
+    }
+
+    fs.writeFileSync(filePath, JSON.stringify(current, null, 2) + "\n");
+    filesWritten.push(file);
+  }
+
+  return { filesWritten };
+}
+
+// ── Pipeline ─────────────────────────────────────────────────
+
+/**
+ * Generate and optionally apply recommendation patches.
+ * @param {{ dataDir?: string, dryRun?: boolean, maxPatches?: number }} opts
+ * @returns {object} The patch plan with metadata
+ */
+export function genRecommendationPatch(opts = {}) {
+  const { dataDir = DATA_DIR, dryRun = false, maxPatches = MAX_DATA_PATCHES_DEFAULT } = opts;
+
+  console.log("Generating recommendation patches...");
+  console.log(`  Mode: ${dryRun ? "DRY RUN" : "LIVE"}`);
+
+  // Load inputs (fail-soft)
+  const recommendations = loadJsonSafe(path.join(dataDir, "recommendations.json"), { recommendations: [] });
+  const governance = loadJsonSafe(path.join(dataDir, "governance.json"), {});
+  const promoQueue = loadJsonSafe(path.join(dataDir, "promo-queue.json"), { slugs: [] });
+  const experiments = loadJsonSafe(path.join(dataDir, "experiments.json"), { experiments: [] });
+
+  const currentData = { promoQueue, experiments };
+
+  // Build patch plan
+  const plan = buildPatchPlan(
+    recommendations.recommendations || [],
+    governance,
+    currentData,
+    { maxPatches },
+  );
+
+  // Audit artifact (includes timestamp — only non-deterministic part)
+  const artifact = {
+    generatedAt: new Date().toISOString(),
+    ...plan,
+  };
+
+  if (dryRun) {
+    console.log(`  [dry-run] ${plan.patches.length} data patches, ${plan.advisoryNotes.length} advisory, ${plan.frozenActions.length} frozen`);
+  } else {
+    // Apply data file changes
+    if (plan.patches.length > 0) {
+      const { filesWritten } = applyPatchesToFiles(plan.patches, currentData, { dataDir });
+      console.log(`  Applied patches to: ${filesWritten.join(", ")}`);
+    } else {
+      console.log("  No data patches to apply.");
+    }
+
+    // Write audit artifact
+    const artifactPath = path.join(dataDir, "recommendation-patch.json");
+    fs.writeFileSync(artifactPath, JSON.stringify(artifact, null, 2) + "\n");
+    console.log(`  Wrote audit artifact: ${artifactPath}`);
+  }
+
+  // Summary
+  console.log(`    Patches: ${plan.patches.length}`);
+  console.log(`    Advisory: ${plan.advisoryNotes.length}`);
+  console.log(`    Frozen: ${plan.frozenActions.length}`);
+  console.log(`    Risk notes: ${plan.riskNotes.length}`);
+
+  return artifact;
+}
+
+// ── CLI ──────────────────────────────────────────────────────
+
+if (isMain) {
+  const dryRun = process.argv.includes("--dry-run");
+  genRecommendationPatch({ dryRun });
+}