@jenga-ai/agent 3.2.0 → 3.4.0

package/project/app/api/parsers/rapports.js

@@ -0,0 +1,148 @@
+/**
+ * @file project/app/api/parsers/rapports.js
+ * Lists rapport markdown files and extracts summary metadata.
+ *
+ * Also exports `readRapportsFull()` (E58_S01_T03) — a full-content, 6-category aggregate built
+ * on `./lib/markdown-dir-reader`'s `readMarkdownDirRecursive()` (E58_S01_T01) and `./ideas`'s
+ * `readIdeas()` (E58_S01_T02), covering `project/rapports/{analysis,problems,tests}`,
+ * `project/documentation/{summaries,plans}`, and `project/ideas.md`. This coexists with, and does
+ * not alter, the original `readRapports()` below — that function and its truncated
+ * `content_summary` shape are `GET /v1/history`'s exclusive, unchanged dependency.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const matter = require('gray-matter');
+const { resolveProjectRoot } = require('../lib/resolve-project-root');
+const { readMarkdownDirRecursive } = require('./lib/markdown-dir-reader');
+const { readIdeas } = require('./ideas');
+
+// Resolved relative to the invoking project's own root (E47_S02_T01/T02), not a fixed __dirname
+// climb — see project/app/api/lib/resolve-project-root.js.
+const RAPPORTS_ROOT = path.join(resolveProjectRoot(), 'project', 'rapports');
+const DOCUMENTATION_SUMMARIES_ROOT = path.join(
+  resolveProjectRoot(),
+  'project',
+  'documentation',
+  'summaries'
+);
+const DOCUMENTATION_PLANS_ROOT = path.join(
+  resolveProjectRoot(),
+  'project',
+  'documentation',
+  'plans'
+);
+const DATE_PATTERN = /(\d{4}-\d{2}-\d{2})/;
+
+// Maps project/rapports/*'s top-level subdirectories onto the 6-category taxonomy named in
+// E58_S01's story description ("Rapports: analysis/problems/tests/summaries/plans/ideas").
+const RAPPORTS_CATEGORIZE = { analysis: 'analysis', problems: 'problems', tests: 'tests' };
+
+/**
+ * Recursively list .md files under a directory.
+ * @param {string} dir
+ * @returns {string[]} absolute file paths
+ */
+function listMdFiles(dir) {
+  if (!fs.existsSync(dir)) return [];
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...listMdFiles(full));
+    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      files.push(full);
+    }
+  }
+  return files;
+}
+
+/**
+ * Read rapport files and return summary objects.
+ * Returns [] if the rapports directory does not exist.
+ * @returns {Promise<Object[]>}
+ */
+async function readRapports() {
+  if (!fs.existsSync(RAPPORTS_ROOT)) return [];
+
+  const files = listMdFiles(RAPPORTS_ROOT);
+  const results = [];
+
+  for (const filePath of files) {
+    try {
+      const raw = fs.readFileSync(filePath, 'utf8');
+      const { data: frontmatter, content } = matter(raw);
+      const filename = path.relative(RAPPORTS_ROOT, filePath);
+
+      // Date: prefer frontmatter, then extract from filename
+      let date = frontmatter.date || null;
+      if (!date) {
+        const match = DATE_PATTERN.exec(path.basename(filePath));
+        if (match) date = match[1];
+      }
+
+      const content_summary = content.trim().slice(0, 300);
+
+      results.push({
+        type: 'rapport',
+        filename,
+        date: date ? String(date) : null,
+        content_summary,
+      });
+    } catch (err) {
+      console.warn(`[rapports] Skipping malformed file: ${filePath} — ${err.message}`);
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Resolve a `date` field for a `readMarkdownDirRecursive()` entry, mirroring the exact
+ * frontmatter-then-filename fallback rule `readRapports()` already uses above — factored out here
+ * so `readRapportsFull()` can apply the identical rule across all of its directory-reader sources
+ * without duplicating it per call site. Does not alter `readRapports()` itself.
+ * @param {Object} data - gray-matter-parsed frontmatter object.
+ * @param {string} relFile - path relative to the source root (used for filename-based fallback).
+ * @returns {string|null}
+ */
+function extractDate(data, relFile) {
+  let date = (data && data.date) || null;
+  if (!date) {
+    const match = DATE_PATTERN.exec(path.basename(relFile));
+    if (match) date = match[1];
+  }
+  return date ? String(date) : null;
+}
+
+/**
+ * Aggregate full (untruncated) content across the 6-category taxonomy named in E58_S01's story
+ * description: `analysis`/`problems`/`tests` (from `project/rapports/*`), `summaries`/`plans`
+ * (from `project/documentation/*`), and `idea` (from `project/ideas.md`).
+ *
+ * Each entry carries: `{ file, data, content, category, date }` — `file` is a path relative to
+ * its own source root (POSIX-style, per `readMarkdownDirRecursive()`'s contract), `data` is the
+ * parsed frontmatter object (`{}` if none), `content` is the full untruncated markdown body, and
+ * `date` follows the same frontmatter-then-filename fallback rule as `readRapports()`. A missing
+ * source directory/file contributes zero entries rather than throwing (inherited from
+ * `readMarkdownDirRecursive()`'s and `readIdeas()`'s own non-throwing guards).
+ *
+ * Does not alter `readRapports()` or its truncated `content_summary` shape — `GET /v1/history`
+ * is unaffected by this function's existence.
+ * @returns {Promise<Object[]>}
+ */
+async function readRapportsFull() {
+  const withDates = (entries) => entries.map((e) => ({ ...e, date: extractDate(e.data, e.file) }));
+
+  const rapportEntries = withDates(readMarkdownDirRecursive(RAPPORTS_ROOT, RAPPORTS_CATEGORIZE));
+  const summaryEntries = withDates(
+    readMarkdownDirRecursive(DOCUMENTATION_SUMMARIES_ROOT, () => 'summaries')
+  );
+  const planEntries = withDates(readMarkdownDirRecursive(DOCUMENTATION_PLANS_ROOT, () => 'plans'));
+  const ideaEntries = await readIdeas();
+
+  return [...rapportEntries, ...summaryEntries, ...planEntries, ...ideaEntries];
+}
+
+module.exports = { readRapports, readRapportsFull };

package/project/app/api/parsers/todo.js

@@ -0,0 +1,179 @@
+/**
+ * @file project/app/api/parsers/todo.js
+ *
+ * Reads the invoking project's `project/todo.md` and extracts the board refs its **active**
+ * (non-comment) entries name, so the dashboard can tell which board items the user has already
+ * queued for execution. Consumed by `parsers/board.js`, which tags each matching epic/story/task
+ * with `_queued: true` (E06_S05_T04) — the Active Sprint tab's In Progress column promotes those
+ * items even though their board status hasn't moved yet.
+ *
+ * ── Path resolution ───────────────────────────────────────────────────────────────────────────
+ * `todo.md` is resolved via `resolveProjectRoot()` (`../lib/resolve-project-root.js`), exactly the
+ * way `parsers/board.js` resolves `BOARD_ROOT` — never a fixed `path.resolve(__dirname, '../../..')`
+ * climb. A `__dirname` climb only ever lands correctly inside this monorepo's own checkout; from a
+ * consumer's `node_modules/@jenga-ai/agent/` it lands inside or above `node_modules` and silently
+ * reads the wrong file (or none). That is the exact E46 / E47_S02 defect pattern.
+ *
+ * Unlike `board.js`, the path is resolved **inside** `readTodoRefs()` rather than at module load.
+ * Two reasons: requiring this module can then never throw at import time (a board read must not be
+ * taken down by an unresolvable root before the route handler can even produce an error envelope),
+ * and tests can pass an explicit path without touching `JENGA_PROJECT_ROOT`. Since `server.js`
+ * pins the resolved root into that env var before any parser loads, the per-call resolution is a
+ * cheap env-var read, not a repeated filesystem walk.
+ *
+ * ── Line shapes in the real file ──────────────────────────────────────────────────────────────
+ * `project/todo.md`'s documented format is `<mission title>: <E##_S##>` with the ref **optional**
+ * (its own header comment says so). The live file contains all of these, and all of them must be
+ * handled:
+ *
+ *   1. `Implement set-break.sh and clear-break.sh: E44_S01_T02`     → task ref, extracted
+ *   2. `Handoff document schema & ... checkpoint: E23_S01`          → story ref, extracted
+ *   3. `invoke /brainstorm project/rapports/analysis/...md`         → no ref, ignored
+ *   4. `<!-- RECONCILED: ...: E32_S01_T01 -->`                      → comment, skipped entirely
+ *   5. `# Todo` / `<!-- Format: ... -->` / blank lines               → ignored
+ *   6. `Fix hardcoded project/ paths ... (see project/rapports/problems/E31_S05_T01-hidden-mode-path-resolution-gaps.md, F1/F2): E34`
+ *
+ * Shape 6 is why the ref pattern is **end-anchored and colon-preceded** rather than "any ref
+ * anywhere in the line": that single real line both embeds `E31_S05_T01` inside a rapport filename
+ * and ends in the epic-only ref `E34`. A loose `/E\d+_S\d+(_T\d+)?/g` scan would spuriously report
+ * `E31_S05_T01` as queued — a board item that line is merely *citing*, not queueing.
+ *
+ * ── Epic-only refs are deliberately not matched ───────────────────────────────────────────────
+ * A trailing `E##` (e.g. `E34`, `E15_S04` is a story so it matches, but bare `E34` does not) is
+ * ignored. E06_S05_T04's Acceptance Criteria scope resolvable refs to `E##_S##` / `E##_S##_T##`,
+ * and its Description states a ref "may point at a story or at a task". Promoting a whole epic off
+ * a single queued line would also drag an item with a much wider blast radius into the In Progress
+ * column than the user queued. This is a decision, not an oversight.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { resolveProjectRoot } = require('../lib/resolve-project-root');
+
+/**
+ * Matches a whole line of the documented `<mission title>: <ref>` form, where `<ref>` is a story or
+ * task id and is the last non-whitespace token on the line. `.*?` for the title is lazy but the
+ * `$` anchor forces the ref to be the final token regardless. Case-insensitive so a hand-typed
+ * `e06_s05_t04` still resolves; refs are upper-cased on the way out and `board.js` matches ids
+ * case-insensitively too, so the whole path is case-agnostic.
+ */
+const TODO_ENTRY_PATTERN = /^(.*?):[ \t]*(E\d+_S\d+(?:_T\d+)?)[ \t]*$/i;
+
+/** A balanced HTML comment block, `s`-flag-free so it works on older Node too. */
+const HTML_COMMENT_BLOCK = /<!--[\s\S]*?-->/g;
+
+/**
+ * Removes every balanced `<!-- ... -->` block, then drops everything from an unterminated trailing
+ * `<!--` onward (matching how a browser/markdown renderer treats it: the rest of the document is
+ * commented out). Blocks are replaced with a single space rather than deleted so a comment that
+ * opens mid-line can't silently glue the surrounding text into a fake `title: ref` pair.
+ *
+ * The replacement is **newline-preserving**: a block spanning N newlines is replaced with a space
+ * followed by those N newlines, so every surviving line keeps its original 1-based line number and
+ * any text trailing a multi-line comment's `-->` stays on the line it was actually written on.
+ * Collapsing the block to a bare space instead (the original behavior) shifted every subsequent
+ * line up by N, which made `parseTodoContent`'s `entries[].line` wrong for any file containing a
+ * multi-line comment — and `project/todo.md` contains several.
+ *
+ * The dangling-open truncation needs no equivalent treatment: it only ever discards lines *after*
+ * the unterminated `<!--`, so the line numbers of everything that survives are untouched.
+ *
+ * @param {string} content
+ * @returns {string}
+ */
+function stripComments(content) {
+  const withoutBalanced = String(content == null ? '' : content).replace(
+    HTML_COMMENT_BLOCK,
+    (block) => ' ' + '\n'.repeat((block.match(/\n/g) || []).length)
+  );
+  const danglingOpen = withoutBalanced.indexOf('<!--');
+  return danglingOpen === -1 ? withoutBalanced : withoutBalanced.slice(0, danglingOpen);
+}
+
+/**
+ * Pure parse of `todo.md` content into the board refs its active entries name.
+ *
+ * @param {string} content raw file content
+ * @returns {{ refs: string[], entries: { title: string, ref: string, line: number }[] }}
+ *   `refs` is upper-cased and de-duplicated, in first-appearance order. `entries` keeps every
+ *   matching line for debuggability; its 1-based `line` numbers always match the original content,
+ *   since `stripComments` preserves the newlines of the blocks it removes.
+ */
+function parseTodoContent(content) {
+  const lines = stripComments(content).split(/\r?\n/);
+  const entries = [];
+  const seen = new Set();
+  const refs = [];
+
+  lines.forEach((rawLine, index) => {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) return;
+
+    const match = TODO_ENTRY_PATTERN.exec(line);
+    if (!match) return;
+
+    const title = match[1].trim();
+    const ref = match[2].toUpperCase();
+
+    entries.push({ title, ref, line: index + 1 });
+    if (!seen.has(ref)) {
+      seen.add(ref);
+      refs.push(ref);
+    }
+  });
+
+  return { refs, entries };
+}
+
+/**
+ * Absolute path to the invoking project's `project/todo.md`.
+ * @returns {string}
+ */
+function resolveTodoPath() {
+  return path.join(resolveProjectRoot(), 'project', 'todo.md');
+}
+
+/**
+ * Read and parse the project's `todo.md`.
+ *
+ * A missing file is a first-class, non-exceptional case: it returns `{ exists: false, refs: [] }`,
+ * which makes every downstream consumer behave exactly as it did before this feature existed. An
+ * unreadable file (permissions, a directory where a file was expected) is likewise reported as
+ * `exists: false` with the reason attached, never thrown — a broken `todo.md` must not be able to
+ * take down `GET /v1/board`.
+ *
+ * @param {string} [filePath] explicit path; defaults to `<projectRoot>/project/todo.md`
+ * @returns {{ exists: boolean, path: string, refs: string[], entries: Object[], error?: string }}
+ */
+function readTodoRefs(filePath) {
+  let todoPath;
+  try {
+    todoPath = filePath || resolveTodoPath();
+  } catch (err) {
+    return { exists: false, path: '', refs: [], entries: [], error: err.message };
+  }
+
+  let raw;
+  try {
+    raw = fs.readFileSync(todoPath, 'utf8');
+  } catch (err) {
+    if (err.code !== 'ENOENT') {
+      console.warn(`[todo] Could not read ${todoPath} — ${err.message}`);
+      return { exists: false, path: todoPath, refs: [], entries: [], error: err.message };
+    }
+    return { exists: false, path: todoPath, refs: [], entries: [] };
+  }
+
+  const { refs, entries } = parseTodoContent(raw);
+  return { exists: true, path: todoPath, refs, entries };
+}
+
+module.exports = {
+  readTodoRefs,
+  parseTodoContent,
+  stripComments,
+  resolveTodoPath,
+  TODO_ENTRY_PATTERN,
+};

package/project/app/api/response.js

@@ -0,0 +1,47 @@
+/**
+ * @file api/response.js
+ * Helper functions for building consistent API response envelopes.
+ */
+
+const API_VERSION = '1.0.0';
+
+/**
+ * Build a success envelope.
+ * @template T
+ * @param {T} data
+ * @param {Object} [extraMeta] - Additional meta fields to merge
+ * @returns {import('./types').ApiEnvelope<T>}
+ */
+function successResponse(data, extraMeta = {}) {
+  return {
+    data,
+    meta: {
+      timestamp: new Date().toISOString(),
+      version: API_VERSION,
+      ...extraMeta,
+    },
+    error: null,
+  };
+}
+
+/**
+ * Build an error envelope.
+ * @param {string} code    - Error code from ERROR_CODES
+ * @param {string} message - Human-readable message
+ * @param {Object} [details]
+ * @returns {import('./types').ApiEnvelope<null>}
+ */
+function errorResponse(code, message, details) {
+  const err = { code, message };
+  if (details !== undefined) err.details = details;
+  return {
+    data: null,
+    meta: {
+      timestamp: new Date().toISOString(),
+      version: API_VERSION,
+    },
+    error: err,
+  };
+}
+
+module.exports = { successResponse, errorResponse, API_VERSION };

package/project/app/api/routes/architecture.js

@@ -0,0 +1,23 @@
+/**
+ * @file project/app/api/routes/architecture.js
+ * GET /architecture — tech stack and dependency metadata
+ */
+
+const { Router } = require('express');
+const { parseArchitecture } = require('../parsers/architecture');
+const { successResponse, errorResponse } = require('../response');
+const { ERROR_CODES } = require('../types');
+
+const router = Router();
+
+router.get('/', async (req, res) => {
+  try {
+    const arch = await parseArchitecture();
+    res.json(successResponse(arch));
+  } catch (err) {
+    console.error('[architecture] error:', err.message);
+    res.status(500).json(errorResponse(ERROR_CODES.INTERNAL_ERROR, err.message));
+  }
+});
+
+module.exports = router;

package/project/app/api/routes/board.js

@@ -0,0 +1,46 @@
+/**
+ * @file project/app/api/routes/board.js
+ * GET /board          — full nested board
+ * GET /board/:epicId  — single epic (case-insensitive)
+ */
+
+const { Router } = require('express');
+const { parseBoard } = require('../parsers/board');
+const { successResponse, errorResponse } = require('../response');
+const { ERROR_CODES } = require('../types');
+
+const router = Router();
+
+router.get('/', async (req, res) => {
+  try {
+    const board = await parseBoard();
+    res.json(successResponse(board));
+  } catch (err) {
+    console.error('[board] parse error:', err.message);
+    res.status(500).json(errorResponse(ERROR_CODES.PARSE_ERROR, err.message));
+  }
+});
+
+router.get('/:epicId', async (req, res) => {
+  try {
+    const board = await parseBoard();
+    const id = req.params.epicId.toLowerCase();
+    const epic = board.find((e) => e.id && e.id.toLowerCase() === id);
+    if (!epic) {
+      return res
+        .status(404)
+        .json(
+          errorResponse(
+            ERROR_CODES.EPIC_NOT_FOUND,
+            `Epic '${req.params.epicId}' not found`
+          )
+        );
+    }
+    res.json(successResponse(epic));
+  } catch (err) {
+    console.error('[board/:epicId] parse error:', err.message);
+    res.status(500).json(errorResponse(ERROR_CODES.PARSE_ERROR, err.message));
+  }
+});
+
+module.exports = router;

package/project/app/api/routes/documentation.js

@@ -0,0 +1,24 @@
+/**
+ * @file project/app/api/routes/documentation.js
+ * GET / — full documentation aggregate (summary/readme/strategy/example), untruncated, no query
+ * params or pagination — matches GET /v1/board's bulk-fetch precedent.
+ */
+
+const { Router } = require('express');
+const { readDocumentation } = require('../parsers/documentation');
+const { successResponse, errorResponse } = require('../response');
+const { ERROR_CODES } = require('../types');
+
+const router = Router();
+
+router.get('/', async (req, res) => {
+  try {
+    const documentation = await readDocumentation();
+    res.json(successResponse(documentation));
+  } catch (err) {
+    console.error('[documentation] parse error:', err.message);
+    res.status(500).json(errorResponse(ERROR_CODES.PARSE_ERROR, err.message));
+  }
+});
+
+module.exports = router;

package/project/app/api/routes/health.js

@@ -0,0 +1,25 @@
+/**
+ * @file project/app/api/routes/health.js
+ * GET /health — server liveness check
+ */
+
+const { Router } = require('express');
+const { successResponse } = require('../response');
+const { API_VERSION } = require('../response');
+
+const router = Router();
+
+const startTime = Date.now();
+
+router.get('/', (req, res) => {
+  const uptime = (Date.now() - startTime) / 1000;
+  res.json(
+    successResponse({
+      status: 'ok',
+      version: API_VERSION,
+      uptime,
+    })
+  );
+});
+
+module.exports = router;

package/project/app/api/routes/history.js

@@ -0,0 +1,55 @@
+/**
+ * @file project/app/api/routes/history.js
+ * GET /history — merged git commits + rapport files, sorted by date desc
+ * Query params:
+ *   ?limit=N          — return first N items
+ *   ?type=git_commit|rapport — filter by type
+ */
+
+const { Router } = require('express');
+const { readGitLog } = require('../parsers/git-log');
+const { readRapports } = require('../parsers/rapports');
+const { successResponse, errorResponse } = require('../response');
+const { ERROR_CODES } = require('../types');
+
+const router = Router();
+
+router.get('/', async (req, res) => {
+  const { limit, type } = req.query;
+
+  if (limit !== undefined && (isNaN(Number(limit)) || Number(limit) < 1)) {
+    return res
+      .status(400)
+      .json(
+        errorResponse(ERROR_CODES.INVALID_QUERY_PARAM, '`limit` must be a positive integer')
+      );
+  }
+  if (type !== undefined && !['git_commit', 'rapport'].includes(type)) {
+    return res
+      .status(400)
+      .json(
+        errorResponse(ERROR_CODES.INVALID_QUERY_PARAM, '`type` must be git_commit or rapport')
+      );
+  }
+
+  try {
+    const [commits, rapports] = await Promise.all([readGitLog(), readRapports()]);
+    let items = [...commits, ...rapports];
+
+    items.sort((a, b) => {
+      const da = new Date(a.date || 0).getTime();
+      const db = new Date(b.date || 0).getTime();
+      return db - da;
+    });
+
+    if (type) items = items.filter((i) => i.type === type);
+    if (limit) items = items.slice(0, Number(limit));
+
+    res.json(successResponse(items));
+  } catch (err) {
+    console.error('[history] error:', err.message);
+    res.status(500).json(errorResponse(ERROR_CODES.INTERNAL_ERROR, err.message));
+  }
+});
+
+module.exports = router;

package/project/app/api/routes/rapports.js

@@ -0,0 +1,24 @@
+/**
+ * @file project/app/api/routes/rapports.js
+ * GET / — full rapports aggregate (analysis/problems/tests/summaries/plans/idea), untruncated,
+ * no query params or pagination — matches GET /v1/board's bulk-fetch precedent.
+ */
+
+const { Router } = require('express');
+const { readRapportsFull } = require('../parsers/rapports');
+const { successResponse, errorResponse } = require('../response');
+const { ERROR_CODES } = require('../types');
+
+const router = Router();
+
+router.get('/', async (req, res) => {
+  try {
+    const rapports = await readRapportsFull();
+    res.json(successResponse(rapports));
+  } catch (err) {
+    console.error('[rapports] parse error:', err.message);
+    res.status(500).json(errorResponse(ERROR_CODES.PARSE_ERROR, err.message));
+  }
+});
+
+module.exports = router;