@golden-frijoles/kit 0.0.0 → 0.2.0

package/dist/lib/pmo-metrics.mjs

@@ -0,0 +1,200 @@
+const HOUR_MS = 60 * 60 * 1000;
+const DAY_MS = 24 * HOUR_MS;
+
+function toMs(value) {
+  if (!value) return null;
+  const ms = new Date(value).getTime();
+  return Number.isFinite(ms) ? ms : null;
+}
+
+function round(value, digits = 1) {
+  if (value === null || value === undefined || Number.isNaN(value)) return null;
+  const factor = 10 ** digits;
+  return Math.round(value * factor) / factor;
+}
+
+export function inWindow(value, sinceISO, untilISO) {
+  const t = toMs(value);
+  const since = toMs(sinceISO);
+  const until = toMs(untilISO);
+  if (t === null || since === null || until === null) return false;
+  return t >= since && t < until;
+}
+
+export function median(values) {
+  const nums = values.filter((v) => Number.isFinite(v)).sort((a, b) => a - b);
+  if (!nums.length) return null;
+  const mid = Math.floor(nums.length / 2);
+  return nums.length % 2 ? nums[mid] : (nums[mid - 1] + nums[mid]) / 2;
+}
+
+export function percentile(values, p) {
+  const nums = values.filter((v) => Number.isFinite(v)).sort((a, b) => a - b);
+  if (!nums.length) return null;
+  if (nums.length === 1) return nums[0];
+  const idx = Math.ceil((p / 100) * nums.length) - 1;
+  return nums[Math.max(0, Math.min(nums.length - 1, idx))];
+}
+
+export function parseStoryProgress(value) {
+  const m = /^(\d+)\/(\d+)\s+stories\b/i.exec(String(value ?? '').trim());
+  if (!m) return { done: 0, total: 0 };
+  return { done: Number(m[1]), total: Number(m[2]) };
+}
+
+export function summarizePrCycleTimes(prs, { sinceISO, untilISO } = {}) {
+  const merged = prs.filter((pr) => {
+    if (!pr.mergedAt || !pr.createdAt) return false;
+    return sinceISO && untilISO ? inWindow(pr.mergedAt, sinceISO, untilISO) : true;
+  });
+  const hours = merged
+    .map((pr) => (toMs(pr.mergedAt) - toMs(pr.createdAt)) / HOUR_MS)
+    .filter((v) => Number.isFinite(v) && v >= 0);
+  const total = hours.reduce((sum, v) => sum + v, 0);
+  return {
+    count: hours.length,
+    averageHours: hours.length ? round(total / hours.length) : null,
+    medianHours: round(median(hours)),
+    p90Hours: round(percentile(hours, 90)),
+  };
+}
+
+export function summarizeEpicLeadTime(epics, { sinceISO, untilISO } = {}) {
+  const shipped = epics.filter((epic) => {
+    if (!epic.scaffoldedAt || !epic.shippedAt) return false;
+    return sinceISO && untilISO ? inWindow(epic.shippedAt, sinceISO, untilISO) : true;
+  });
+  const days = shipped
+    .map((epic) => (toMs(epic.shippedAt) - toMs(epic.scaffoldedAt)) / DAY_MS)
+    .filter((v) => Number.isFinite(v) && v >= 0);
+  const total = days.reduce((sum, v) => sum + v, 0);
+  return {
+    count: days.length,
+    averageDays: days.length ? round(total / days.length) : null,
+    medianDays: round(median(days)),
+  };
+}
+
+export function summarizeDeployFrequency(repoResults, { deployRepos = [] } = {}) {
+  const allowed = deployRepos.length ? new Set(deployRepos) : null;
+  const byRepo = {};
+  let total = 0;
+  let unavailable = 0;
+  for (const result of repoResults) {
+    if (allowed && !allowed.has(result.repo)) continue;
+    if (!result.available) {
+      byRepo[result.repo] = null;
+      unavailable += 1;
+      continue;
+    }
+    const count = result.prs?.length ?? 0;
+    byRepo[result.repo] = count;
+    total += count;
+  }
+  return { total, byRepo, unavailable };
+}
+
+export function summarizeChangeFailProxy(items, { sinceISO, untilISO } = {}) {
+  const matches = [];
+  for (const item of items) {
+    const date = item.mergedAt || item.date || item.createdAt;
+    if (sinceISO && untilISO && !inWindow(date, sinceISO, untilISO)) continue;
+    const text = `${item.title ?? ''} ${item.message ?? ''}`.toLowerCase();
+    if (/\brevert\b/.test(text) || /\bhotfix\b/.test(text)) {
+      matches.push(item);
+    }
+  }
+  return { count: matches.length, items: matches };
+}
+
+export function summarizeThroughput({
+  roadmapRows = [],
+  epicStatusFlips = [],
+  storyShipEvents = [],
+  sinceISO,
+  untilISO,
+}) {
+  const shippedEpicFlips = epicStatusFlips.filter(
+    (flip) => flip.status === 'shipped' && inWindow(flip.date, sinceISO, untilISO)
+  );
+  const closedEpicFlips = epicStatusFlips.filter(
+    (flip) => ['shipped', 'archived'].includes(flip.status) && inWindow(flip.date, sinceISO, untilISO)
+  );
+  const shippedStories = storyShipEvents.filter((event) =>
+    inWindow(event.shippedAt || event.date, sinceISO, untilISO)
+  );
+  const currentStoryProgress = roadmapRows
+    .filter((row) => row.grain === 'Sprint' || row.grain === 'Epic')
+    .map((row) => parseStoryProgress(row.sprint_progress))
+    .reduce(
+      (acc, progress) => ({
+        done: acc.done + progress.done,
+        total: acc.total + progress.total,
+      }),
+      { done: 0, total: 0 }
+    );
+
+  return {
+    shippedStories: shippedStories.length,
+    shippedEpics: shippedEpicFlips.length,
+    closedEpics: closedEpicFlips.length,
+    currentStoryProgress,
+  };
+}
+
+export function summarizeDocOps({ docChanges = [], learningsPromotions = [], shippedEpics = [] } = {}) {
+  const docsTouchedByEpic = {};
+  for (const change of docChanges) {
+    if (!change.epicSlug) continue;
+    if (!docsTouchedByEpic[change.epicSlug]) docsTouchedByEpic[change.epicSlug] = new Set();
+    docsTouchedByEpic[change.epicSlug].add(change.path);
+  }
+  const docsTouchedPerEpic = Object.fromEntries(
+    Object.entries(docsTouchedByEpic).map(([slug, paths]) => [slug, paths.size])
+  );
+  const retroCovered = shippedEpics.filter((epic) => epic.hasRetrospective).length;
+  return {
+    docsTouchedPerEpic,
+    learningsPromotions: learningsPromotions.length,
+    retroCoverage: {
+      covered: retroCovered,
+      total: shippedEpics.length,
+      percent: shippedEpics.length ? round((retroCovered / shippedEpics.length) * 100, 0) : null,
+    },
+  };
+}
+
+export function baselineSummary({ repoResults = [], roadmapRows = [], docChanges = [] } = {}) {
+  const openPrs = repoResults.reduce((sum, result) => sum + (result.openPrs?.length ?? 0), 0);
+  const recentlyMergedPrs = repoResults.reduce((sum, result) => sum + (result.prs?.length ?? 0), 0);
+  const roadmapItems = roadmapRows.length;
+  return {
+    openPrs,
+    recentlyMergedPrs,
+    roadmapItems,
+    docChanges: docChanges.length,
+  };
+}
+
+export function formatBaselineSummary(summary) {
+  return [
+    'PMO baseline established',
+    `${summary.openPrs} open PRs`,
+    `${summary.recentlyMergedPrs} recently merged PRs`,
+    `${summary.roadmapItems} Roadmap rows`,
+    `${summary.docChanges} doc changes`,
+  ].join(' · ');
+}
+
+export function summarizePmoMetrics(input) {
+  const { sinceISO, untilISO } = input;
+  return {
+    window: { sinceISO, untilISO },
+    throughput: summarizeThroughput(input),
+    prCycleTime: summarizePrCycleTimes(input.prs || [], { sinceISO, untilISO }),
+    epicLeadTime: summarizeEpicLeadTime(input.epics || [], { sinceISO, untilISO }),
+    deployFrequency: summarizeDeployFrequency(input.repoResults || [], input),
+    changeFailProxy: summarizeChangeFailProxy(input.changeItems || input.prs || [], { sinceISO, untilISO }),
+    docOps: summarizeDocOps(input),
+  };
+}

package/dist/lib/pmo-templates.mjs

@@ -0,0 +1,132 @@
+import { brotliCompressSync, constants as zlibConstants } from 'node:zlib';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { kitRoot } from './project-root.mjs';
+
+
+const TEMPLATE_DIR = join(kitRoot(), 'pmo', 'templates'); // D2: a kit asset
+
+const TEMPLATE_FILES = {
+  weekly: 'weekly-story-deck.md',
+  monthly: 'monthly-stakeholder-packet.md',
+  sheet: 'metrics-sheet.md',
+};
+
+function getPath(obj, path) {
+  return path.split('.').reduce((cur, part) => (cur == null ? undefined : cur[part]), obj);
+}
+
+function formatNumber(value, fallback = 0) {
+  if (value === null || value === undefined || Number.isNaN(value)) return fallback;
+  return value;
+}
+
+function round(value, digits = 1) {
+  if (!Number.isFinite(value)) return 0;
+  const factor = 10 ** digits;
+  return Math.round(value * factor) / factor;
+}
+
+function windowDays(metrics) {
+  const since = new Date(metrics.window.sinceISO).getTime();
+  const until = new Date(metrics.window.untilISO).getTime();
+  if (!Number.isFinite(since) || !Number.isFinite(until) || until <= since) return 7;
+  return (until - since) / (24 * 60 * 60 * 1000);
+}
+
+function benchmarkSourceLine(benchmarks) {
+  const firstSource = benchmarks.sources?.[0];
+  if (!firstSource) return 'Benchmarks no cargados.';
+  return `${firstSource.publisher} (${firstSource.publishedDate}; accessed ${firstSource.accessedDate})`;
+}
+
+export function buildTemplateData(metrics, { benchmarks = {}, generatedAt = new Date() } = {}) {
+  const generatedDate = generatedAt.toISOString().slice(0, 10);
+  const days = windowDays(metrics);
+  const deploysPerWeek = round((formatNumber(metrics.deployFrequency.total) / days) * 7);
+  const changeFailureRatePercent = metrics.deployFrequency.total
+    ? round((formatNumber(metrics.changeFailProxy.count) / metrics.deployFrequency.total) * 100)
+    : 0;
+  return {
+    window: {
+      sinceISO: metrics.window.sinceISO,
+      untilISO: metrics.window.untilISO,
+      label: `${metrics.window.sinceISO.slice(0, 10)} to ${metrics.window.untilISO.slice(0, 10)}`,
+      generatedDate,
+    },
+    throughput: {
+      shippedStories: formatNumber(metrics.throughput.shippedStories),
+      shippedEpics: formatNumber(metrics.throughput.shippedEpics),
+      closedEpics: formatNumber(metrics.throughput.closedEpics),
+    },
+    cycle: {
+      medianHours: formatNumber(metrics.prCycleTime.medianHours),
+      averageHours: formatNumber(metrics.prCycleTime.averageHours),
+      p90Hours: formatNumber(metrics.prCycleTime.p90Hours),
+    },
+    epics: {
+      medianDays: formatNumber(metrics.epicLeadTime.medianDays),
+      averageDays: formatNumber(metrics.epicLeadTime.averageDays),
+    },
+    deploys: {
+      total: formatNumber(metrics.deployFrequency.total),
+      perWeek: deploysPerWeek,
+    },
+    quality: {
+      changeFailProxy: formatNumber(metrics.changeFailProxy.count),
+      changeFailureRatePercent,
+    },
+    docOps: {
+      learningsPromotions: formatNumber(metrics.docOps.learningsPromotions),
+      retroCovered: formatNumber(metrics.docOps.retroCoverage.covered),
+      retroTotal: formatNumber(metrics.docOps.retroCoverage.total),
+      retroPercent: formatNumber(metrics.docOps.retroCoverage.percent),
+    },
+    benchmarks: {
+      deploysPerWeek: formatNumber(benchmarks.deploysPerWeek),
+      prCycleMedianHours: formatNumber(benchmarks.prCycleMedianHours),
+      epicLeadMedianDays: formatNumber(benchmarks.epicLeadMedianDays),
+      changeFailureRatePercent: formatNumber(benchmarks.changeFailureRatePercent),
+      restoreTimeHours: formatNumber(benchmarks.restoreTimeHours),
+      framing: benchmarks.framing || 'Diferencial operativo, no experimento controlado.',
+      sourceLine: benchmarkSourceLine(benchmarks),
+    },
+  };
+}
+
+export function fillTemplate(template, metrics, options = {}) {
+  const data = buildTemplateData(metrics, options);
+  return template.replace(/\{\{\s*([A-Za-z0-9_.]+)\s*\}\}/g, (match, key) => {
+    const value = getPath(data, key);
+    return value === undefined ? match : String(value);
+  });
+}
+
+export function loadPmoTemplate(name) {
+  const file = TEMPLATE_FILES[name];
+  if (!file) throw new Error(`Unknown PMO template "${name}"`);
+  return readFileSync(join(TEMPLATE_DIR, file), 'utf8');
+}
+
+export function fillPmoTemplate(name, metrics, options = {}) {
+  return fillTemplate(loadPmoTemplate(name), metrics, options);
+}
+
+function toBase64Url(buffer) {
+  return Buffer.from(buffer).toString('base64url');
+}
+
+// A URL-hash markdown viewer: the whole document rides in the fragment (brotli + base64url), so the
+// viewer never stores anything and the link IS the artifact. `baseUrl` is the project's own viewer
+// deployment (reporting.config.json → artifacts.docViewerUrl) and is REQUIRED — there is no default,
+// because a default points every project's reports at one project's hosting.
+export function buildDocViewerUrl(markdown, { baseUrl, present = false } = {}) {
+  if (!baseUrl)
+    throw new Error('buildDocViewerUrl: no baseUrl — set artifacts.docViewerUrl in reporting.config.json');
+  const compressed = brotliCompressSync(Buffer.from(markdown, 'utf8'), {
+    params: { [zlibConstants.BROTLI_PARAM_QUALITY]: 11 },
+  });
+  const params = new URLSearchParams({ md: toBase64Url(compressed) });
+  if (present) params.set('present', '0');
+  return `${baseUrl}/#${params.toString()}`;
+}

package/dist/lib/pmo-window-log.mjs

@@ -0,0 +1,99 @@
+const DEFAULT_WINDOW_DAYS = 7;
+const DAY_MS = 24 * 60 * 60 * 1000;
+const HOUR_MS = 60 * 60 * 1000;
+
+function floorToHour(date) {
+  return new Date(Math.floor(date.getTime() / HOUR_MS) * HOUR_MS);
+}
+
+export function parsePmoLog(content) {
+  if (!content) return [];
+  return content
+    .trim()
+    .split('\n')
+    .filter(Boolean)
+    .flatMap((line) => {
+      try {
+        return [JSON.parse(line)];
+      } catch {
+        return [];
+      }
+    });
+}
+
+export function lastPmoLogEntry(content) {
+  const entries = parsePmoLog(content);
+  return entries.length ? entries[entries.length - 1] : null;
+}
+
+export function computePmoWindow(lastLogEntry, now, { sinceISO = null, untilISO = null } = {}) {
+  const roundedNow = floorToHour(now);
+  const end = untilISO || roundedNow.toISOString();
+  if (sinceISO) return { sinceISO, untilISO: end };
+  if (lastLogEntry?.windowEnd) return { sinceISO: lastLogEntry.windowEnd, untilISO: end };
+  return {
+    sinceISO: new Date(new Date(end).getTime() - DEFAULT_WINDOW_DAYS * DAY_MS).toISOString(),
+    untilISO: end,
+    baseline: true,
+  };
+}
+
+export function pmoLogLine({ window, metrics, baselineEstablished }) {
+  return (
+    JSON.stringify({
+      ts: new Date().toISOString(),
+      windowStart: window.sinceISO,
+      windowEnd: window.untilISO,
+      baselineEstablished: !!baselineEstablished,
+      summary: {
+        shippedStories: metrics.throughput.shippedStories,
+        shippedEpics: metrics.throughput.shippedEpics,
+        deploys: metrics.deployFrequency.total,
+        changeFailProxy: metrics.changeFailProxy.count,
+        learningsPromotions: metrics.docOps.learningsPromotions,
+      },
+    }) + '\n'
+  );
+}
+
+export function formatPmoReport({ metrics, baselineLine = null }) {
+  const { sinceISO, untilISO } = metrics.window;
+  const hours = (value) => (value === null || value === undefined ? 'n/a' : `${value}h`);
+  const lines = [`PMO operational report · ${sinceISO} → ${untilISO}`];
+  if (baselineLine) lines.push(baselineLine);
+
+  const progress = metrics.throughput.currentStoryProgress;
+  lines.push(
+    `Throughput: ${metrics.throughput.shippedStories} stories shipped · ${metrics.throughput.shippedEpics} epics shipped · ${metrics.throughput.closedEpics} epics closed · Roadmap progress ${progress.done}/${progress.total} stories`
+  );
+  lines.push(
+    `PR cycle time: ${metrics.prCycleTime.count} merged PRs · median ${hours(metrics.prCycleTime.medianHours)} · avg ${hours(metrics.prCycleTime.averageHours)} · p90 ${hours(metrics.prCycleTime.p90Hours)}`
+  );
+
+  const repoCounts = Object.entries(metrics.deployFrequency.byRepo)
+    .map(([repo, count]) => `${repo.split('/').pop()}: ${count ?? 'unavailable'}`)
+    .join(' · ');
+  lines.push(
+    `Deploy frequency: ${metrics.deployFrequency.total} merges to main${repoCounts ? ` (${repoCounts})` : ''}`
+  );
+  lines.push(`Change-fail proxy: ${metrics.changeFailProxy.count} revert/hotfix PRs`);
+
+  const docCounts = Object.entries(metrics.docOps.docsTouchedPerEpic);
+  const shownDocCounts = docCounts.slice(0, 12);
+  const docSummary = docCounts.length
+    ? shownDocCounts
+        .map(([slug, count]) => `${slug}: ${count}`)
+        .concat(
+          docCounts.length > shownDocCounts.length
+            ? [`and ${docCounts.length - shownDocCounts.length} more`]
+            : []
+        )
+        .join(' · ')
+    : 'none';
+  const retro = metrics.docOps.retroCoverage;
+  lines.push(
+    `Doc-ops: Roadmap docs touched per epic: ${docSummary} · LEARNINGS promotions ${metrics.docOps.learningsPromotions} · retro coverage ${retro.covered}/${retro.total}${retro.percent === null ? '' : ` (${retro.percent}%)`}`
+  );
+
+  return lines.join('\n');
+}

package/dist/lib/project-root.mjs

@@ -0,0 +1,78 @@
+// project-root.mjs — the three path classes every kit script resolves through (golden-frijoles-plugin D2).
+//
+// A script in this set runs in one of two places:
+//   • COPIED:    the project's own `scripts/<x>.mjs` (a project spawned from the template, or a deliberate fork).
+//   • INSTALLED: `@golden-frijoles/kit`, run by `npx … gf-kit <x>` from npm's cache, far from the project.
+// The same bytes run in both. What differs is only where "the project" and "my own files" are, so every
+// path goes through exactly one of:
+//
+//   kitRoot()          the directory holding this script set: the project's `scripts/` when copied, the kit's
+//                      `dist/` when installed. Kit assets (templates, task prompts, benchmarks) and SIBLING
+//                      scripts a script spawns resolve here. Never the project's files.
+//   projectRoot()      the user's project. `GF_PROJECT_ROOT` wins. Otherwise, COPIED: exactly `scripts/..`, as
+//                      every script computed it before this module existed. INSTALLED: walk up from cwd to the
+//                      nearest dir holding `Roadmap/` or `.git`, falling back to cwd.
+//   projectAsset(rel)  a file the PROJECT owns but the kit supplies a default for (a TEMPLATE FILL-IN persona, a
+//                      lessons file that grows per project, a per-project enforcement list): the project's
+//                      `scripts/<rel>` when it has one, else the kit's copy. In copied mode those are one file.
+//
+// Why copied mode does NOT walk up from cwd: this repo's CI runs `node template/scripts/<x>.mjs` from the repo
+// root, and consumers' tests pass explicit roots. A walk from cwd would silently retarget both at a different
+// directory. The mode is a detected fact (the kit's package.json sits above dist/), never a guess.
+//
+// `--root <dir>` is parsed by kit/bin.mjs only, which exports it as GF_PROJECT_ROOT — no script's own argument
+// parser ever sees a new flag. Zero deps; no side effects at import.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const KIT_PACKAGE_NAME = '@golden-frijoles/kit';
+
+const HERE = dirname(fileURLToPath(import.meta.url)); // <set>/lib
+
+/** The directory holding this script set: the project's `scripts/` (copied) or the kit's `dist/` (installed). */
+export function kitRoot() {
+  return resolve(HERE, '..');
+}
+
+/** True when this set runs from the published kit rather than a project's own `scripts/`. */
+export function isInstalled({ root = kitRoot(), read = readFileSync, exists = existsSync } = {}) {
+  const pkg = join(root, '..', 'package.json');
+  if (!exists(pkg)) return false;
+  try {
+    return JSON.parse(read(pkg, 'utf8')).name === KIT_PACKAGE_NAME;
+  } catch {
+    return false;
+  }
+}
+
+/** Walk up from `start` to the nearest directory holding `Roadmap/` or `.git`; null when there is none. */
+export function findProjectRoot(start, { exists = existsSync } = {}) {
+  let dir = resolve(start);
+  for (;;) {
+    if (exists(join(dir, 'Roadmap')) || exists(join(dir, '.git'))) return dir;
+    const up = dirname(dir);
+    if (up === dir) return null;
+    dir = up;
+  }
+}
+
+/** The user's project. See the header for the precedence. */
+export function projectRoot({
+  env = process.env,
+  cwd = process.cwd(),
+  root = kitRoot(),
+  installed = isInstalled({ root }),
+  exists = existsSync,
+} = {}) {
+  if (env.GF_PROJECT_ROOT) return resolve(cwd, env.GF_PROJECT_ROOT);
+  if (!installed) return resolve(root, '..');
+  return findProjectRoot(cwd, { exists }) ?? resolve(cwd);
+}
+
+/** A project-owned file with a kit default: the project's `scripts/<rel>` if present, else the kit's `<rel>`. */
+export function projectAsset(rel, { project = projectRoot(), root = kitRoot(), exists = existsSync } = {}) {
+  const own = join(project, 'scripts', rel);
+  return exists(own) ? own : join(root, rel);
+}