sdtk-wiki-kit 0.2.1 → 0.3.0

package/src/lib/wiki-kaban-parse.js

@@ -0,0 +1,529 @@
+"use strict";
+
+// BK-272: Agent Kaban — pure parser (no I/O). Caller passes file text.
+// Spec §D3: view model; §D4: column derivation rules; §D5: liveness.
+
+const KABAN_LIVENESS_MIN = 15;
+const COLUMNS = ["todo", "in_progress", "pending", "done"];
+const AGENT_ORDER = ["PM", "BA", "ARCH", "DEV", "QA"];
+const DONE_STATUSES = new Set(["done", "complete", "example complete"]);
+
+// Normalize agent identifier to canonical form (PM/BA/ARCH/DEV/QA)
+function normalizeAgent(raw) {
+  if (!raw) return null;
+  const s = raw.replace(/[`*@]/g, "").trim().toLowerCase();
+  if (!s) return null;
+  if (s.startsWith("pm")) return "PM";
+  if (s.startsWith("ba")) return "BA";
+  if (s.startsWith("arch")) return "ARCH";
+  if (s.startsWith("dev")) return "DEV";
+  if (s.startsWith("qa")) return "QA";
+  return null;
+}
+
+// Extract a header field matching **FieldName:** `value` or FieldName: value
+function getHeaderField(text) {
+  for (let i = 1; i < arguments.length; i++) {
+    const fieldName = arguments[i];
+    const patterns = [
+      new RegExp("\\*\\*" + fieldName + "[:\\s]*\\*\\*\\s*[:`]?\\s*`?([^`\\n]+)`?", "i"),
+      new RegExp("^\\s*\\*\\*" + fieldName + ":\\*\\*\\s+`?([^`\\n]+)`?", "im"),
+      new RegExp("^\\s*" + fieldName + ":\\s+([^\\n]+)", "im"),
+    ];
+    for (const re of patterns) {
+      const m = text.match(re);
+      if (m) return m[1].trim().replace(/`/g, "").replace(/\*\*/g, "");
+    }
+  }
+  return null;
+}
+
+// Parse a markdown table block from an array of pipe-delimited lines.
+// Returns { headerCols: string[], rows: string[][] }
+function parseMarkdownTable(tableLines) {
+  const rows = [];
+  let headerCols = null;
+  for (const line of tableLines) {
+    const t = line.trim();
+    if (!t.startsWith("|")) continue;
+    const cells = t.slice(1, t.endsWith("|") ? -1 : undefined)
+      .split("|")
+      .map((c) => c.trim());
+    if (headerCols === null) {
+      headerCols = cells.map((c) =>
+        c.replace(/\*\*/g, "").replace(/`/g, "").toLowerCase().trim()
+      );
+      continue;
+    }
+    if (cells.every((c) => /^[-: ]+$/.test(c) || c === "")) continue;
+    rows.push(cells);
+  }
+  return { headerCols: headerCols || [], rows };
+}
+
+// Find the first table in text whose header columns match all required patterns.
+function findTable(text, requiredColPatterns) {
+  const allLines = text.split("\n");
+  let i = 0;
+  while (i < allLines.length) {
+    const line = allLines[i].trim();
+    if (!line.startsWith("|")) {
+      i++;
+      continue;
+    }
+    const tableLines = [];
+    while (i < allLines.length && allLines[i].trim().startsWith("|")) {
+      tableLines.push(allLines[i]);
+      i++;
+    }
+    if (tableLines.length < 2) continue;
+    const parsed = parseMarkdownTable(tableLines);
+    const matches = requiredColPatterns.every((p) =>
+      parsed.headerCols.some((h) => p.test(h))
+    );
+    if (matches) return parsed;
+  }
+  return null;
+}
+
+// Parse planning file header (featureKey, featureName, lastUpdated)
+function parsePlanningHeader(text) {
+  return {
+    featureKey: getHeaderField(text, "Current Feature", "Feature key"),
+    featureName: getHeaderField(text, "Feature Name"),
+    lastUpdated: getHeaderField(text, "Last Updated"),
+    pipelineStatus: getHeaderField(text, "Pipeline Status", "Status"),
+  };
+}
+
+// Parse the pipeline status table into phase objects.
+// Handles both canonical shape (8 cols) and simplified demo shape (5 cols).
+function parsePipelinePhases(text) {
+  const result = findTable(text, [/phase/, /status/]);
+  if (!result) return [];
+  const { headerCols, rows } = result;
+
+  const phaseIdx = headerCols.findIndex((h) => h.includes("phase"));
+  const statusIdx = headerCols.findIndex((h) => h.includes("status"));
+  const ownerIdx = headerCols.findIndex((h) => h.includes("owner"));
+  const artifactIdx = headerCols.findIndex(
+    (h) => h.includes("artifact") || h.includes("output")
+  );
+  const notesIdx = headerCols.findIndex(
+    (h) => h.includes("notes") || h.includes("blockers")
+  );
+
+  if (phaseIdx < 0 || statusIdx < 0) return [];
+
+  const phases = [];
+  for (const cells of rows) {
+    const phase = (cells[phaseIdx] || "")
+      .replace(/\*\*/g, "")
+      .replace(/`/g, "")
+      .trim();
+    const rawStatus = (cells[statusIdx] || "")
+      .replace(/\*\*/g, "")
+      .replace(/`/g, "")
+      .trim();
+    const owner =
+      ownerIdx >= 0 ? (cells[ownerIdx] || "").trim() : "";
+    const artifact =
+      artifactIdx >= 0
+        ? (cells[artifactIdx] || "").replace(/`/g, "").trim()
+        : "";
+    const notes =
+      notesIdx >= 0
+        ? (cells[notesIdx] || "").replace(/\*\*/g, "").replace(/`/g, "").trim()
+        : "";
+
+    if (!phase || !rawStatus) continue;
+
+    phases.push({
+      phase,
+      rawStatus,
+      owner,
+      artifact,
+      notes,
+      agent: normalizeAgent(owner),
+    });
+  }
+  return phases;
+}
+
+// Extract blocker strings; returns [] if sentinel NO BLOCKERS or section absent.
+function parseBlockers(text) {
+  const m = text.match(
+    /##\s+CURRENT BLOCKERS[^\n]*([\s\S]*?)(?=\n##\s+|$)/i
+  );
+  if (!m) return [];
+  const section = m[1];
+  if (section.includes("NO BLOCKERS")) return [];
+  return section
+    .split("\n")
+    .map((l) => l.trim())
+    .filter((l) => l && l !== "```" && !l.startsWith("#"));
+}
+
+// Extract OPEN open questions from the OQ table.
+function parseOpenQuestions(text) {
+  const result = findTable(text, [/q-id|^id$/, /status/]);
+  if (!result) return [];
+  const { headerCols, rows } = result;
+
+  const idIdx = headerCols.findIndex((h) => h === "q-id" || h === "id");
+  const statusIdx = headerCols.findIndex((h) => h.includes("status"));
+  const ownerIdx = headerCols.findIndex((h) => h.includes("owner"));
+  const summaryIdx = headerCols.findIndex((h) => h.includes("summary"));
+
+  return rows
+    .filter((cells) => {
+      const st = (statusIdx >= 0 ? cells[statusIdx] || "" : "").trim().toUpperCase();
+      return st.includes("OPEN");
+    })
+    .map((cells) => ({
+      id: idIdx >= 0 ? (cells[idIdx] || "").trim() : "",
+      status: (statusIdx >= 0 ? cells[statusIdx] || "" : "").trim(),
+      owner: ownerIdx >= 0 ? (cells[ownerIdx] || "").trim() : "",
+      summary: summaryIdx >= 0 ? (cells[summaryIdx] || "").trim() : "",
+    }));
+}
+
+// Parse activity log lines for timestamps and @handoff hints.
+function parseActivityEntries(text) {
+  const re = /(\d{4}-\d{2}-\d{2}[ T]\d{2}:\d{2})[^|\n]*\|[^|\n]*\|[^|\n]*\|[^|\n]*?(\@\w+)?(?=\n|$)/g;
+  const entries = [];
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    entries.push({ ts: m[1].trim(), handoffNext: m[2] ? m[2].trim() : null });
+  }
+  return entries;
+}
+
+// Derive pipeline card column per spec §D4.
+function derivePipelineColumn(rawStatus, hasOpenOQ, hasBlocker, trustMismatch) {
+  const s = rawStatus.toLowerCase();
+  const isDone = DONE_STATUSES.has(s);
+  if (isDone && !trustMismatch && !hasOpenOQ && !hasBlocker) {
+    return { column: "done", attention: false };
+  }
+  if (hasOpenOQ || hasBlocker || trustMismatch) {
+    return { column: "pending", attention: true };
+  }
+  if (s === "in_progress" || s === "in progress") {
+    return { column: "in_progress", attention: false };
+  }
+  return { column: "todo", attention: false };
+}
+
+// Derive quality card column per spec §D4.
+function deriveQualityColumn(checked, phaseHasBlocker, phaseHasOpenOQ, hasIssue, phaseStatus) {
+  if (checked) return { column: "done", attention: false };
+  if (phaseHasBlocker || phaseHasOpenOQ || hasIssue) {
+    return { column: "pending", attention: true };
+  }
+  const s = (phaseStatus || "").toLowerCase();
+  if (s === "in_progress" || s === "in progress") {
+    return { column: "in_progress", attention: false };
+  }
+  return { column: "todo", attention: false };
+}
+
+// Derive agent from QUALITY_CHECKLIST.md phase section heading.
+function deriveAgentFromPhaseName(name) {
+  const u = name.toUpperCase();
+  if (u.includes("PM") || u.includes("CLOSURE")) return "PM";
+  if (u.includes("BA") || u.includes("BUSINESS ANALYSIS")) return "BA";
+  if (u.includes("ARCH") || u.includes("ARCHITECTURE")) return "ARCH";
+  if (u.includes("DEV") || u.includes("DEVELOPMENT") || u.includes("IMPLEMENTATION")) return "DEV";
+  if (u.includes("QA") || u.includes("QUALITY")) return "QA";
+  return "PM";
+}
+
+// Parse QUALITY_CHECKLIST.md into phase objects with criteria + gate rows.
+function parseQualityCriteria(text) {
+  const phases = [];
+  const lines = text.split("\n");
+  let currentPhase = null;
+
+  for (const line of lines) {
+    const phaseMatch = line.match(
+      /^#{1,3}\s+PHASE\s+(\d+[+]?)[\s:]+(.+?)\s*(?:CHECKLIST)?\s*$/i
+    );
+    if (phaseMatch) {
+      currentPhase = {
+        phaseNum: phaseMatch[1],
+        phaseName: phaseMatch[2].replace(/\(.*?\)/g, "").trim(),
+        agent: deriveAgentFromPhaseName(phaseMatch[2]),
+        criteria: [],
+        gate: null,
+      };
+      phases.push(currentPhase);
+      continue;
+    }
+    if (!currentPhase) continue;
+
+    const t = line.trim();
+    if (!t.startsWith("|")) continue;
+    if (t.replace(/[\-:|]/g, "").trim() === "") continue;
+
+    const cells = t
+      .slice(1, t.endsWith("|") ? -1 : undefined)
+      .split("|")
+      .map((c) => c.trim());
+    if (cells.length < 3) continue;
+
+    const numRaw = cells[0].replace(/\*\*/g, "").trim();
+    if (!numRaw || numRaw === "#" || numRaw === "num") continue;
+
+    const criteriaRaw = cells[1] || "";
+    const statusRaw = cells[2] || "";
+    const verifiedByRaw = cells[3] || "";
+    const notesRaw = cells[4] || "";
+
+    const criteria = criteriaRaw.replace(/\*\*/g, "").replace(/`/g, "").trim();
+    if (!criteria) continue;
+
+    const verifiedByClean = verifiedByRaw.replace(/\*\*/g, "").trim();
+    const isGate = verifiedByClean.toLowerCase().includes("gate");
+
+    const checked =
+      statusRaw.includes("[x]") ||
+      statusRaw.toLowerCase() === "done" ||
+      statusRaw.toLowerCase() === "complete";
+
+    const issue = notesRaw.replace(/\*\*/g, "").replace(/`/g, "").trim();
+    const agent = normalizeAgent(verifiedByClean) || currentPhase.agent;
+
+    const item = {
+      criteria,
+      checked,
+      isGate,
+      issue,
+      agent,
+      phaseNum: currentPhase.phaseNum,
+      phaseName: currentPhase.phaseName,
+    };
+
+    if (isGate) {
+      currentPhase.gate = item;
+    } else {
+      currentPhase.criteria.push(item);
+    }
+  }
+  return phases;
+}
+
+// Fuzzy-match a phase name in a map to find the closest entry.
+function findMatchingEntry(map, targetName) {
+  const tn = targetName.toLowerCase().replace(/^\d+[+]?\.\s*/, "").replace(/\s*checklist\s*$/i, "").trim();
+  for (const [key, val] of Object.entries(map)) {
+    const k = key.replace(/^\d+[+]?\.\s*/, "").trim();
+    const firstWord = tn.split(/\s+/)[0];
+    if (k.includes(tn) || tn.includes(k) || k.startsWith(firstWord)) {
+      return val;
+    }
+  }
+  return null;
+}
+
+// Main parser — pure, no I/O.
+// Input: { planningText: string|null, qualityText: string|null, now: Date }
+// Output: { meta, agents, pipeline: { cards }, quality: { cards } }
+function parseKaban({ planningText, qualityText, now }) {
+  const nowDate = now instanceof Date ? now : new Date();
+  const errors = [];
+
+  const meta = {
+    featureKey: null,
+    featureName: null,
+    lastUpdated: null,
+    generatedAt: nowDate.toISOString(),
+    pipelinePresent: !!planningText,
+    qualityPresent: !!qualityText,
+  };
+
+  const pipeline = { cards: [] };
+  const quality = { cards: [] };
+
+  let phases = [];
+  let blockers = [];
+  let openQuestions = [];
+  let activityEntries = [];
+
+  // --- Parse SHARED_PLANNING.md ---
+  if (planningText) {
+    try {
+      const header = parsePlanningHeader(planningText);
+      meta.featureKey = header.featureKey;
+      meta.featureName = header.featureName;
+      meta.lastUpdated = header.lastUpdated;
+      phases = parsePipelinePhases(planningText);
+      blockers = parseBlockers(planningText);
+      openQuestions = parseOpenQuestions(planningText);
+      activityEntries = parseActivityEntries(planningText);
+    } catch (e) {
+      errors.push("planning parse error: " + e.message);
+    }
+  }
+
+  // --- Parse QUALITY_CHECKLIST.md ---
+  let qualityPhases = [];
+  const qualityGateByPhaseName = {};
+
+  if (qualityText) {
+    try {
+      const qHeader = parsePlanningHeader(qualityText);
+      if (!meta.featureKey) meta.featureKey = qHeader.featureKey;
+      if (!meta.lastUpdated) meta.lastUpdated = qHeader.lastUpdated;
+      qualityPhases = parseQualityCriteria(qualityText);
+      for (const qp of qualityPhases) {
+        qualityGateByPhaseName[qp.phaseName.toLowerCase()] = qp.gate;
+      }
+    } catch (e) {
+      errors.push("quality parse error: " + e.message);
+    }
+  }
+
+  // --- Enrich pipeline phases with OQ/blocker flags ---
+  const enrichedPhases = phases.map((phase) => {
+    const phaseKey = phase.phase.toLowerCase();
+    const hasOpenOQ = openQuestions.some((oq) => {
+      const oqAgent = normalizeAgent(oq.owner);
+      const firstWord = phaseKey.split(/[\s.]+/)[0];
+      return (
+        oqAgent === phase.agent ||
+        (oq.id || "").toLowerCase().includes(firstWord) ||
+        (oq.summary || "").toLowerCase().includes(firstWord)
+      );
+    });
+    const hasBlocker =
+      blockers.length > 0 &&
+      blockers.some((b) => {
+        const bl = b.toLowerCase();
+        const firstWord = phaseKey.split(/[\s.]+/)[0];
+        return (
+          bl.includes(firstWord) ||
+          (phase.agent && bl.includes(phase.agent.toLowerCase()))
+        );
+      });
+    return { ...phase, hasOpenOQ, hasBlocker };
+  });
+
+  // --- Build pipeline cards ---
+  for (const phase of enrichedPhases) {
+    const phaseKey = phase.phase.toLowerCase();
+
+    const matchedGate = findMatchingEntry(qualityGateByPhaseName, phaseKey);
+    const statusLower = phase.rawStatus.toLowerCase();
+    const isDone = DONE_STATUSES.has(statusLower);
+    const trustMismatch =
+      matchedGate !== null && isDone && matchedGate !== null && !matchedGate.checked;
+
+    const { column, attention } = derivePipelineColumn(
+      phase.rawStatus,
+      phase.hasOpenOQ,
+      phase.hasBlocker,
+      trustMismatch
+    );
+
+    const agentLower = (phase.agent || "").toLowerCase();
+    const relevantActivity = activityEntries.filter(
+      (e) => e.handoffNext && e.handoffNext.toLowerCase().includes(agentLower)
+    );
+    const lastActivity =
+      relevantActivity.length > 0
+        ? relevantActivity[relevantActivity.length - 1]
+        : activityEntries.length > 0
+        ? activityEntries[activityEntries.length - 1]
+        : null;
+
+    pipeline.cards.push({
+      id: "phase-" + phaseKey.replace(/[^a-z0-9]/g, "-"),
+      title: phase.phase
+        .replace(/^\*{0,2}\d+[+]?\.\s*\*{0,2}/, "")
+        .replace(/\*\*/g, "")
+        .trim(),
+      agent: phase.agent || "OTHER",
+      column,
+      rawStatus: phase.rawStatus,
+      owner: phase.owner,
+      artifact: phase.artifact,
+      notes: phase.notes,
+      attention,
+      lastUpdate: lastActivity ? lastActivity.ts : null,
+      handoffNext: lastActivity ? lastActivity.handoffNext : null,
+    });
+  }
+
+  // --- Build quality cards ---
+  const phaseInfoByName = {};
+  for (const p of enrichedPhases) {
+    phaseInfoByName[p.phase.toLowerCase()] = {
+      rawStatus: p.rawStatus,
+      hasBlocker: p.hasBlocker,
+      hasOpenOQ: p.hasOpenOQ,
+    };
+  }
+
+  for (const qPhase of qualityPhases) {
+    const phaseInfo = findMatchingEntry(phaseInfoByName, qPhase.phaseName);
+    const phaseStatus = phaseInfo ? phaseInfo.rawStatus : "";
+    const phaseHasBlocker = phaseInfo ? phaseInfo.hasBlocker : false;
+    const phaseHasOpenOQ = phaseInfo ? phaseInfo.hasOpenOQ : false;
+
+    const allItems = [
+      ...qPhase.criteria,
+      ...(qPhase.gate ? [qPhase.gate] : []),
+    ];
+
+    for (let i = 0; i < allItems.length; i++) {
+      const item = allItems[i];
+      // Issue is meaningful if it's not just an @-mention (those are handoff hints)
+      const hasIssue =
+        item.issue &&
+        item.issue.length > 0 &&
+        !item.issue.trim().startsWith("@");
+
+      const { column, attention } = deriveQualityColumn(
+        item.checked,
+        phaseHasBlocker,
+        phaseHasOpenOQ,
+        hasIssue,
+        phaseStatus
+      );
+
+      quality.cards.push({
+        id: "q-" + qPhase.phaseNum + "-" + i,
+        title: item.criteria,
+        agent: item.agent || qPhase.agent || "OTHER",
+        phase: qPhase.phaseName,
+        column,
+        checked: item.checked,
+        isGate: item.isGate,
+        issue: item.issue,
+        attention,
+      });
+    }
+  }
+
+  // --- Derive agents list (canonical order first, extras appended) ---
+  const seenAgents = new Set();
+  for (const c of [...pipeline.cards, ...quality.cards]) {
+    if (c.agent && c.agent !== "OTHER") seenAgents.add(c.agent);
+  }
+  const agents = AGENT_ORDER.filter((a) => seenAgents.has(a));
+  for (const a of seenAgents) {
+    if (!AGENT_ORDER.includes(a)) agents.push(a);
+  }
+  if (agents.length === 0) agents.push(...AGENT_ORDER);
+
+  meta.errors = errors;
+  return { meta, agents, pipeline, quality };
+}
+
+module.exports = {
+  parseKaban,
+  KABAN_LIVENESS_MIN,
+  COLUMNS,
+  AGENT_ORDER,
+};

package/src/lib/wiki-runner.js

@@ -9,6 +9,7 @@ const { spawn, execFile } = require("child_process");
 const { CliError, DependencyError } = require("./errors");
 const { resolveBuilderPath } = require("./wiki-config");
 const { openBrowser } = require("./browser-open");
+const { parseKaban } = require("./wiki-kaban-parse");
 
 const HEALTH_CHECK_RETRIES = 20;
 const HEALTH_CHECK_INTERVAL_MS = 300;
@@ -248,6 +249,51 @@ function startWikiServer(host, port, outputDir, projectPath) {
         return;
       }
 
+      if (url === "/api/kaban" || url === "/api/kaban/") {
+        const projectRoot = projectPath || outputDir;
+        let planningText = null;
+        let qualityText = null;
+
+        const planningFile = path.resolve(projectRoot, "SHARED_PLANNING.md");
+        const qualityFile = path.resolve(projectRoot, "QUALITY_CHECKLIST.md");
+        const inRoot = (f) =>
+          f.startsWith(projectRoot + path.sep) || f === projectRoot;
+
+        try {
+          if (inRoot(planningFile) && fs.existsSync(planningFile)) {
+            planningText = fs.readFileSync(planningFile, "utf-8");
+          }
+        } catch (_) {}
+        try {
+          if (inRoot(qualityFile) && fs.existsSync(qualityFile)) {
+            qualityText = fs.readFileSync(qualityFile, "utf-8");
+          }
+        } catch (_) {}
+
+        let viewModel;
+        try {
+          viewModel = parseKaban({ planningText, qualityText, now: new Date() });
+        } catch (e) {
+          viewModel = {
+            meta: {
+              errors: ["Server error: " + e.message],
+              pipelinePresent: false,
+              qualityPresent: false,
+            },
+            agents: [],
+            pipeline: { cards: [] },
+            quality: { cards: [] },
+          };
+        }
+
+        res.writeHead(200, {
+          "Content-Type": "application/json",
+          "Cache-Control": "no-cache",
+        });
+        res.end(JSON.stringify(viewModel));
+        return;
+      }
+
       if (url.startsWith("/api/note")) {
         const qs = new URL(url, `http://${host}:${port}`).searchParams;
         const notePath = qs.get("path");