create-pmos 0.57.0 → 0.58.0

package/workspace/lib/jira-status.js

@@ -0,0 +1,239 @@
+'use strict';
+/* jira-status.js — the status of the Jira tickets PMOS pushed, read back read-only (initiative jira-wbs, PRD J11, J13).
+ *
+ * THE READ PATH. An agent session reads Jira read-only with the PM's own Atlassian connection (D53: PMOS holds no
+ * tracker credential; D71: an agent skill reads a source, the server does not) and saves the search result to a file.
+ * This module reads that file and writes a snapshot the initiative's Jira tickets tab shows. It writes nothing else:
+ * no plan item, no record, no ledger line (D88: the Breakdown is the handoff checklist, not a copy of Jira).
+ *
+ *   queryFor(root, initiative)          → { linked, query }     the JQL for the tickets this initiative pushed
+ *   linkedInitiatives(root)             → [{ initiative, query }]
+ *   normalize(raw)                      → { issues, skipped } | { error }
+ *   sync(root, initiative, raw, opts)   → the snapshot, written to <state>/tracker/jira/<initiative>.md
+ *   readSnapshot(root, initiative)      → { fetchedAt, query, tickets: Map<key, reading> } | null
+ *   which(root, key)                    → the initiative and ticket a key belongs to
+ *
+ * A READING is { key, summary, status, category: todo|doing|done, sprint: { name, state: active|future|closed } | null,
+ * subtasks: { done, total }, flagged, reason, url }. A ticket the search did not return keeps its last reading, marked
+ * stale. Titles and statuses only: never a description, a comment or a person.
+ *
+ * BOUNDARY (J15). No network module, no child process. The only write is the snapshot file.
+ */
+const fs = require('fs');
+const path = require('path');
+const jiraTickets = require('./jira-tickets.js');
+
+const KEY_RE = /^[A-Za-z][A-Za-z0-9_]*-\d+$/;
+const isStr = (v) => typeof v === 'string';
+const oneLine = (s) => String(s == null ? '' : s).replace(/[\r\n\t]+/g, ' ').replace(/\s{2,}/g, ' ').trim();
+const clip = (s, n) => (s.length > n ? s.slice(0, n - 1).trimEnd() + '…' : s);
+const nowIso = (now) => new Date(now == null ? Date.now() : now).toISOString().replace(/\.\d{3}Z$/, 'Z');
+
+// ── the query ──────────────────────────────────────────────────────────────────────────────────────
+function queryFor(root, initiative) {
+  if (!jiraTickets.recordFm(root, initiative)) return { ok: false, error: `no initiative ${initiative} in this repository` };
+  const keys = [...jiraTickets.pushedTickets(root, initiative).tickets.keys()];
+  if (!keys.length) return { ok: true, initiative, linked: false, keys: [], query: null };
+  return { ok: true, initiative, linked: true, keys, query: `key in (${keys.join(', ')}) ORDER BY key` };
+}
+function linkedInitiatives(root) {
+  return jiraTickets.draftedInitiatives(root).map((id) => queryFor(root, id)).filter((q) => q.ok);
+}
+
+// ── reading a saved search result ──────────────────────────────────────────────────────────────────
+function issuesList(raw) {
+  if (Array.isArray(raw)) return raw;
+  if (!raw || typeof raw !== 'object') return null;
+  if (Array.isArray(raw.issues)) return raw.issues;
+  if (raw.issues && Array.isArray(raw.issues.nodes)) return raw.issues.nodes;
+  if (Array.isArray(raw.values)) return raw.values;
+  if (raw.data && typeof raw.data === 'object') return issuesList(raw.data);
+  return null;
+}
+const nameOf = (v) => (v && typeof v === 'object' ? oneLine(v.name || v.value || '') : oneLine(v));
+function categoryOf(status, cat) {
+  const key = String((cat && typeof cat === 'object' ? (cat.key || cat.name) : cat) || '').toLowerCase();
+  if (key === 'done' || key === 'complete') return 'done';
+  if (key === 'indeterminate' || key === 'in progress' || key === 'doing') return 'doing';
+  if (key === 'new' || key === 'to do' || key === 'todo') return 'todo';
+  const s = String(status || '').toLowerCase();
+  if (/done|closed|resolved|released|complete|shipped|deployed/.test(s)) return 'done';
+  if (/progress|doing|started|review|\bqa\b|test|verif|\buat\b|block/.test(s)) return 'doing';
+  return 'todo';
+}
+/** Jira's Flagged field is a custom field whose id differs per site: any field holding the value "Impediment". */
+function flaggedIn(fields) {
+  if (fields.flagged === true) return true;
+  for (const v of Object.values(fields)) {
+    if (Array.isArray(v) && v.some((x) => x && typeof x === 'object' && /impediment/i.test(String(x.value || '')))) return true;
+  }
+  return false;
+}
+const SPRINT_STATES = ['active', 'future', 'closed'];
+/** One sprint, from an object { name, state } or a bare name. */
+function sprintOne(v) {
+  if (!v) return null;
+  if (isStr(v)) { const name = clip(oneLine(v), 80); return name ? { name, state: 'active' } : null; }
+  if (typeof v !== 'object') return null;
+  const name = clip(oneLine(v.name), 80);
+  const state = String(v.state || '').toLowerCase();
+  if (!name) return null;
+  return { name, state: SPRINT_STATES.includes(state) ? state : 'active' };
+}
+/** The sprint that matters: the active one, else the next, else the last closed. null is the backlog. */
+function sprintOf(v) {
+  const all = (Array.isArray(v) ? v : [v]).map(sprintOne).filter(Boolean);
+  return all.find((s) => s.state === 'active') || all.find((s) => s.state === 'future') || all[all.length - 1] || null;
+}
+/** Jira Cloud keeps the sprint in a custom field: any array of objects that carry a sprint's name and state. */
+function sprintIn(fields) {
+  if ('sprint' in fields) return sprintOf(fields.sprint);
+  for (const v of Object.values(fields)) {
+    if (Array.isArray(v) && v.length && v.every((x) => x && typeof x === 'object' && 'name' in x && 'state' in x && ('boardId' in x || 'id' in x))) return sprintOf(v);
+  }
+  return null;
+}
+function subtasksOf(v) {
+  if (Array.isArray(v)) {
+    const done = v.filter((s) => {
+      const st = s && (s.fields ? s.fields.status : s.status);
+      return categoryOf(nameOf(st), st && typeof st === 'object' ? st.statusCategory : (s && s.category)) === 'done';
+    }).length;
+    return { done, total: v.length };
+  }
+  if (v && typeof v === 'object' && Number.isInteger(v.total) && v.total >= 0) {
+    const done = Number.isInteger(v.done) ? Math.max(0, Math.min(v.done, v.total)) : 0;
+    return { done, total: v.total };
+  }
+  return { done: 0, total: 0 };
+}
+/** https://site.atlassian.net/rest/api/3/issue/10001 → https://site.atlassian.net/browse/KEY */
+function urlOf(x, key) {
+  const raw = isStr(x.url) ? x.url : isStr(x.self) ? x.self : '';
+  let u;
+  try { u = new URL(raw); } catch { return null; }
+  if (u.protocol !== 'https:') return null;
+  if (/\/browse\//.test(u.pathname)) return u.origin + u.pathname;
+  return `${u.origin}/browse/${key}`;
+}
+/** One issue of either shape → a reading, or null when it has no key or no summary. */
+function normalizeIssue(x) {
+  if (!x || typeof x !== 'object') return null;
+  const key = oneLine(x.key).toUpperCase();
+  if (!KEY_RE.test(key)) return null;
+  if (x.fields && typeof x.fields === 'object') {
+    const f = x.fields;
+    const summary = clip(oneLine(f.summary), 250);
+    if (!summary) return null;
+    const st = f.status || {};
+    const status = nameOf(st) || 'Unknown';
+    const flagged = flaggedIn(f) || /block|impediment|on hold/i.test(status);
+    return { key, summary, status, category: categoryOf(status, st.statusCategory), sprint: sprintIn(f), subtasks: subtasksOf(f.subtasks),
+      flagged, reason: flagged ? (flaggedIn(f) ? 'Flagged in Jira' : `Status: ${status}`) : null, url: urlOf(x, key) };
+  }
+  // The flat shape: what the skill tells the agent to write when it is unsure of the connector's shape.
+  const summary = clip(oneLine(x.summary || x.title), 250);
+  if (!summary) return null;
+  const status = oneLine(x.status) || 'Unknown';
+  const flagged = x.flagged === true || /block|impediment|on hold/i.test(status);
+  return { key, summary, status, category: categoryOf(status, x.category), sprint: sprintOf(x.sprint), subtasks: subtasksOf(x.subtasks),
+    flagged, reason: flagged ? clip(oneLine(x.reason || x.flag_reason || (x.flagged === true ? 'Flagged in Jira' : `Status: ${status}`)), 160) : null,
+    url: urlOf(x, key) };
+}
+function normalize(raw) {
+  const list = issuesList(raw);
+  if (!list) return { error: 'the file holds no list of Jira issues (expected "issues": [...], "issues": {"nodes": [...]} or a list)' };
+  const issues = []; const seen = new Set(); let skipped = 0;
+  for (const x of list) {
+    const n = normalizeIssue(x);
+    if (!n || seen.has(n.key)) { skipped++; continue; }
+    seen.add(n.key);
+    issues.push(n);
+  }
+  return { issues, skipped };
+}
+
+// ── the snapshot ───────────────────────────────────────────────────────────────────────────────────
+function snapshotPath(root, initiative) { return path.join(jiraTickets.jiraDir(root), `${initiative}.md`); }
+function snapshotRel(root, initiative) { return jiraTickets.relOf(root, snapshotPath(root, initiative)); }
+const cell = (s) => oneLine(s).replace(/\\/g, '\\\\').replace(/\|/g, '\\|') || '—';
+const SPRINT_WORD = { active: 'Active sprint', future: 'Next sprint', closed: 'Closed sprint' };
+function sprintLabel(s) { return s ? `${SPRINT_WORD[s.state] || 'Sprint'}: ${s.name}` : 'Backlog'; }
+function renderSnapshot({ initiative, fetchedAt, query, readings, ids }) {
+  const rows = readings.map((r) => `| ${cell(ids.get(r.key) || '')} | ${cell(r.key)} | ${cell(r.summary)} | ${cell(r.status)} | ${cell(r.category === 'done' ? 'Done' : sprintLabel(r.sprint))} | ${r.subtasks.total ? `${r.subtasks.done} of ${r.subtasks.total}` : '—'} | ${cell(r.flagged ? r.reason : '')} |${r.stale ? ' not in the last read |' : ''}`);
+  return [
+    '---', 'type: Reference', `title: "Jira status: ${initiative}"`, `timestamp: ${fetchedAt}`, `initiative: ${initiative}`, '---', '',
+    `# Jira status: ${initiative}`, '',
+    `Read from Jira at ${fetchedAt} by the Jira status check, read-only. The Jira tickets tab of the initiative shows it. Written by \`pmos jira sync\`; do not edit by hand.`, '',
+    query ? `Search: \`${query.replace(/`/g, "'")}\`` : 'Search: not recorded', '',
+    '| Ticket | Key | Summary | Status | Sprint | Subtasks | Blocked |', '|---|---|---|---|---|---|---|', ...rows, '',
+    '```json', JSON.stringify({ fetched_at: fetchedAt, query: query || null, tickets: readings }, null, 0), '```', '',
+  ].join('\n');
+}
+function readSnapshot(root, initiative) {
+  let text;
+  try { text = fs.readFileSync(snapshotPath(root, initiative), 'utf8'); } catch { return null; }
+  const m = /```json\n([\s\S]*?)\n```/.exec(text);
+  if (!m) return null;
+  let data;
+  try { data = JSON.parse(m[1]); } catch { return null; }
+  const tickets = new Map();
+  for (const r of Array.isArray(data.tickets) ? data.tickets : []) if (r && KEY_RE.test(String(r.key || ''))) tickets.set(r.key, r);
+  return { fetchedAt: isStr(data.fetched_at) ? data.fetched_at : null, query: isStr(data.query) ? data.query : null, tickets };
+}
+
+/**
+ * Write the snapshot from a saved search result. Only the tickets this initiative pushed are kept; any other issue in
+ * the result is counted and ignored. A pushed ticket missing from the result keeps its last reading, marked stale.
+ */
+function sync(root, initiative, raw, { query, dryRun = false, now } = {}) {
+  if (!jiraTickets.recordFm(root, initiative)) return { ok: false, error: `no initiative ${initiative} in this repository` };
+  const n = normalize(raw);
+  if (n.error) return { ok: false, error: n.error };
+  const pushed = jiraTickets.pushedTickets(root, initiative).tickets;
+  if (!pushed.size) return { ok: false, error: `${initiative} has no ticket in Jira yet — push its tickets first` };
+  const prev = readSnapshot(root, initiative);
+  const got = new Map(n.issues.filter((i) => pushed.has(i.key)).map((i) => [i.key, i]));
+  const ignored = n.issues.length - got.size;
+  const ids = new Map([...pushed].map(([k, v]) => [k, v.id]));
+  const readings = []; const changes = []; const missing = [];
+  for (const key of pushed.keys()) {
+    const r = got.get(key);
+    const was = prev ? prev.tickets.get(key) : null;
+    if (!r) {
+      missing.push(key);
+      if (was) readings.push({ ...was, stale: true });
+      continue;
+    }
+    readings.push(r);
+    if (!was) { changes.push({ key, what: 'first read', status: r.status }); continue; }
+    if (was.status !== r.status) changes.push({ key, what: 'status', from: was.status, to: r.status });
+    const sw = sprintLabel(was.sprint); const sn = sprintLabel(r.sprint);
+    if (sw !== sn) changes.push({ key, what: 'sprint', from: sw, to: sn });
+    if (!!was.flagged !== !!r.flagged) changes.push({ key, what: r.flagged ? 'blocked' : 'unblocked', reason: r.reason || null });
+  }
+  const fetchedAt = nowIso(now);
+  const result = { ok: true, initiative, read: got.size, ignored, skipped: n.skipped, missing, changes, snapshot: snapshotRel(root, initiative), dryRun: !!dryRun };
+  if (dryRun) return result;
+  const file = snapshotPath(root, initiative);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, renderSnapshot({ initiative, fetchedAt, query: query || (prev && prev.query) || null, readings, ids }));
+  fs.renameSync(tmp, file);
+  return { ...result, fetchedAt };
+}
+
+// ── J13 · which initiative ─────────────────────────────────────────────────────────────────────────
+function which(root, key) {
+  const k = String(key || '').trim().toUpperCase();
+  if (!KEY_RE.test(k)) return { ok: false, error: `${JSON.stringify(key)} is not a Jira key like ATL-482` };
+  const hits = [];
+  for (const id of jiraTickets.draftedInitiatives(root)) {
+    const p = jiraTickets.pushedTickets(root, id);
+    if (p.epic === k) hits.push({ initiative: id, role: 'epic' });
+    else if (p.tickets.has(k)) hits.push({ initiative: id, role: 'ticket', ticket: p.tickets.get(k).id, summary: p.tickets.get(k).summary });
+  }
+  return { ok: true, key: k, initiatives: hits };
+}
+
+module.exports = { queryFor, linkedInitiatives, normalize, sync, readSnapshot, which, sprintLabel, snapshotPath, snapshotRel };