@pukujan/create-modular-monolith 2.0.0 → 2.2.0

package/template/scripts/lib/dev-log-human-format.mjs

@@ -0,0 +1,360 @@
+/**
+ * Build two-part human dev log: Part I Summary (TOC, mermaid, audit tables) + Part II Detailed.
+ */
+
+function anchor(slug) {
+  return slug.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
+
+function condensedTree(treeText, maxLines = 48) {
+  const lines = treeText.split("\n");
+  if (lines.length <= maxLines) return treeText;
+  return `${lines.slice(0, maxLines).join("\n")}\n│   └── … (${lines.length - maxLines} more lines — [full tree](#${anchor("repository-tree-full")}))`;
+}
+
+function buildMermaidModuleMap(apis) {
+  const modules = new Map();
+  for (const r of [...apis.http.active, ...apis.http.stub]) {
+    const id = r.module.replace(/\s+/g, "");
+    if (!modules.has(id)) {
+      modules.set(id, r.module);
+    }
+  }
+  const lines = ["flowchart LR", "  client[Client / Frontend]"];
+  let i = 0;
+  for (const [, label] of modules) {
+    const node = `m${i}[${label}]`;
+    lines.push(`  client --> ${node}`);
+    i += 1;
+  }
+  return lines.join("\n");
+}
+
+function buildMermaidPipeline(apis) {
+  const p = apis.versioned.pipeline;
+  return `flowchart TB
+  upload[Upload PDFs] --> parse[Parse cache ${p.parsedArtifacts}]
+  parse --> master[Master prompt ${p.masterPrompt}]
+  master --> out[Batch outputs]
+  rules[Rule fixtures ${p.ruleSet}] -.-> master
+  golden[Golden ${p.goldenDataset}] -.-> evals[Eval runner]`;
+}
+
+function buildMermaidPrePush() {
+  return `flowchart LR
+  code[Code changes] --> devlog[npm run dev-log:pre-push]
+  devlog --> human[human/*.md]
+  devlog --> agent[agent/*.json]
+  human --> push[git push]
+  agent --> push`;
+}
+
+function formatApiSummaryTable(apis) {
+  const rows = [
+    "| Kind | Count | Notes |",
+    "|------|------:|-------|",
+    `| Active HTTP routes | ${apis.http.active.length} | Case-filing-ai + condenser + pipeline |`,
+    `| Stub modules (health only) | ${apis.http.stub.length} | Workflow, court-rules, vault, review, docketing |`,
+    `| Deprecated HTTP | ${apis.http.deprecated.length} | From docs/API.md descriptions |`,
+    `| Deprecated CLI | ${apis.deprecated.cli.length} | See version audit |`
+  ];
+  const key = apis.http.active
+    .filter((r) => /process-batch|parsed-documents|condense/.test(r.path))
+    .slice(0, 6);
+  if (key.length) {
+    rows.push("", "**Key routes this program:**", "");
+    rows.push("| Method | Path |", "|--------|------|");
+    for (const r of key) {
+      rows.push(`| ${r.method} | \`${r.path}\` |`);
+    }
+  }
+  return rows.join("\n");
+}
+
+function formatVersionAuditTable(apis) {
+  const p = apis.versioned.pipeline;
+  const rows = [
+    "| Contract | Version | Status |",
+    "|----------|---------|--------|",
+    `| App (package.json) | ${p.app} | current |`,
+    `| Storage layout | ${p.storageLayout} | current |`,
+    `| Parsed artifacts | ${p.parsedArtifacts} | current |`,
+    `| Master prompt (default) | ${p.masterPrompt} | env \`${apis.versioned.prompts.envVar}\` |`,
+    `| Rule prompt | ${p.rulePrompt} | current |`,
+    `| Golden dataset | ${p.goldenDataset} | current |`,
+    `| Parser | ${p.parser} | current |`,
+    `| OCR | ${p.ocr} | current |`
+  ];
+  rows.push("", "**Master prompt keys:**", "");
+  rows.push("| Key | Template | Notes |", "|-----|----------|-------|");
+  for (const [key, spec] of Object.entries(apis.versioned.prompts.specs)) {
+    const status = key === "v2" ? "alias → compact" : key === "v001" ? "opt-in" : key === apis.versioned.prompts.defaultEnv ? "default" : "available";
+    rows.push(`| ${key} | \`${spec.masterCaseFiling}\` | ${status} |`);
+  }
+  if (apis.deprecated.cli.length) {
+    rows.push("", "**Deprecated surfaces:**", "");
+    for (const d of apis.deprecated.cli) {
+      rows.push(`- \`${d.command}\` → ${d.replacement}`);
+    }
+  }
+  return rows.join("\n");
+}
+
+function formatTestAuditTable(tests) {
+  if (!tests.ran) {
+    return "| Status | Value |\n|--------|-------|\n| Tests | _not run_ (`--no-tests` or fill after run) |";
+  }
+  return [
+    "| Status | Value |",
+    "|--------|-------|",
+    `| Ran | yes |`,
+    `| Exit code | ${tests.exitCode} |`,
+    `| Summary | ${tests.summary} |`,
+    `| Passed (sample) | ${tests.passed.length} lines captured |`,
+    `| Failed (sample) | ${tests.failed.length} lines captured |`
+  ].join("\n");
+}
+
+function formatGitAuditTable(git) {
+  const changed = git.changedFiles?.length ?? 0;
+  return [
+    "| Field | Value |",
+    "|-------|-------|",
+    `| Branch | \`${git.branch}\` |`,
+    `| Commit | \`${git.shortSha}\` (\`${git.sha}\`) |`,
+    `| Changed paths (porcelain) | ${changed} |`,
+    `| Recent commits | ${git.recentCommits?.length ?? 0} listed below |`
+  ].join("\n");
+}
+
+function formatRepoShapeTable(tree) {
+  return [
+    "| Metric | Value |",
+    "|--------|------:|",
+    `| Files | ${tree.stats.fileCount} |`,
+    `| Directories | ${tree.stats.directoryCount} |`,
+    `| Tree ignores | node_modules, .git, dist, build |`,
+    `| Top extensions | ${Object.entries(tree.stats.byExtension || {})
+      .slice(0, 5)
+      .map(([k, v]) => `${k} (${v})`)
+      .join(", ")} |`
+  ].join("\n");
+}
+
+/**
+ * @param {object} opts
+ */
+export function buildHumanDevLog(opts) {
+  const {
+    title,
+    entryId,
+    date,
+    time,
+    humanFilename,
+    agentFilename,
+    git,
+    tests,
+    apis,
+    apisDetailedMarkdown,
+    tree,
+    treeIgnoreList
+  } = opts;
+
+  const p1 = "part-i-summary";
+  const p2 = "part-ii-detailed";
+
+  const toc = [
+    "## Table of contents",
+    "",
+    "### [Part I — Summary](#" + anchor(p1) + ") _(read first)_",
+    "- [I.1 At a glance](#" + anchor("i1-at-a-glance") + ")",
+    "- [I.2 Diagrams](#" + anchor("i2-diagrams") + ")",
+    "- [I.3 API surface (summary)](#" + anchor("i3-api-surface-summary") + ")",
+    "- [I.4 Version & prompt audit](#" + anchor("i4-version-prompt-audit") + ")",
+    "- [I.5 Test audit](#" + anchor("i5-test-audit") + ")",
+    "- [I.6 Git audit](#" + anchor("i6-git-audit") + ")",
+    "- [I.7 Repository shape](#" + anchor("i7-repository-shape") + ")",
+    "",
+    "### [Part II — Detailed](#" + anchor(p2) + ") _(full audit trail)_",
+    "- [II.1 Goals and scope](#" + anchor("ii1-goals-and-scope") + ")",
+    "- [II.2 Decisions](#" + anchor("ii2-decisions") + ")",
+    "- [II.3 Changes by area](#" + anchor("ii3-changes-by-area") + ")",
+    "- [II.4 Iterations](#" + anchor("ii4-iterations") + ")",
+    "- [II.5 Tests (detail)](#" + anchor("ii5-tests-detail") + ")",
+    "- [II.6 What got better / trade-offs / risks](#" + anchor("ii6-outcomes") + ")",
+    "- [II.7 Follow-ups](#" + anchor("ii7-follow-ups") + ")",
+    "- [II.8 APIs (full registry)](#" + anchor("ii8-apis-full-registry") + ")",
+    "- [II.9 Git snapshot (full)](#" + anchor("ii9-git-snapshot-full") + ")",
+    "- [II.10 Repository tree (full)](#" + anchor("repository-tree-full") + ")"
+  ].join("\n");
+
+  const summary = [
+    `# Dev log (human): ${title}`,
+    "",
+    "| Field | Value |",
+    "|-------|--------|",
+    `| **Entry** | ${entryId} |`,
+    `| **Date** | ${date} |`,
+    `| **Time** | ${time} |`,
+    `| **Filename** | \`${humanFilename}\` |`,
+    `| **Agent audit** | [${agentFilename}](../agent/${agentFilename}) |`,
+    `| **Git** | \`${git.branch}\` @ \`${git.shortSha}\` |`,
+    "",
+    toc,
+    "",
+    "---",
+    "",
+    `## Part I — Summary {#${anchor(p1)}}`,
+    "",
+    `> **Purpose:** One-screen picture for reviewers — APIs, versions, tests, git, repo shape.  `,
+    `> **Detail:** [Part II](#${anchor(p2)}) below.`,
+    "",
+    `### I.1 At a glance {#${anchor("i1-at-a-glance")}}`,
+    "",
+    "_FILL: 2–4 sentences — what shipped, why it matters, current blockers._",
+    "",
+    `### I.2 Diagrams {#${anchor("i2-diagrams")}}`,
+    "",
+    "**HTTP modules (active + stub)**",
+    "",
+    "```mermaid",
+    buildMermaidModuleMap(apis),
+    "```",
+    "",
+    "**Pipeline versions (defaults at push)**",
+    "",
+    "```mermaid",
+    buildMermaidPipeline(apis),
+    "```",
+    "",
+    "**Pre-push dev log flow**",
+    "",
+    "```mermaid",
+    buildMermaidPrePush(),
+    "```",
+    "",
+    `### I.3 API surface (summary) {#${anchor("i3-api-surface-summary")}}`,
+    "",
+    formatApiSummaryTable(apis),
+    "",
+    `_Session API changes not in docs/API.md — FILL in [II.8](#${anchor("ii8-apis-full-registry")})._`,
+    "",
+    `### I.4 Version & prompt audit {#${anchor("i4-version-prompt-audit")}}`,
+    "",
+    formatVersionAuditTable(apis),
+    "",
+    `### I.5 Test audit {#${anchor("i5-test-audit")}}`,
+    "",
+    formatTestAuditTable(tests),
+    "",
+    `### I.6 Git audit {#${anchor("i6-git-audit")}}`,
+    "",
+    formatGitAuditTable(git),
+    "",
+    `### I.7 Repository shape {#${anchor("i7-repository-shape")}}`,
+    "",
+    formatRepoShapeTable(tree),
+    "",
+    "_Condensed tree (full tree in [II.10](#repository-tree-full)):_",
+    "",
+    "```text",
+    condensedTree(tree.treeText),
+    "```",
+    "",
+    "---",
+    "",
+    `## Part II — Detailed {#${anchor(p2)}}`,
+    "",
+    `> **Purpose:** Decisions, iterations, narrative, and full machine-captured snapshots.`,
+    "",
+    `### II.1 Goals and scope {#${anchor("ii1-goals-and-scope")}}`,
+    "",
+    "- **In scope:** _FILL_",
+    "- **Out of scope:** _FILL_",
+    "",
+    `### II.2 Decisions {#${anchor("ii2-decisions")}}`,
+    "",
+    "| ID | Decision | Rationale | Alternatives rejected |",
+    "|----|----------|-----------|------------------------|",
+    "| D1 | _FILL_ | _FILL_ | _FILL_ |",
+    "",
+    `### II.3 Changes by area {#${anchor("ii3-changes-by-area")}}`,
+    "",
+    "#### Backend / API",
+    "- _FILL_",
+    "",
+    "#### Frontend",
+    "- _FILL_",
+    "",
+    "#### Data / contracts / prompts",
+    "- _FILL_",
+    "",
+    "#### Tooling / CI / docs",
+    "- _FILL_",
+    "",
+    `### II.4 Iterations {#${anchor("ii4-iterations")}}`,
+    "",
+    "1. **Attempt 1** — _FILL_ → _outcome_",
+    "",
+    `### II.5 Tests (detail) {#${anchor("ii5-tests-detail")}}`,
+    "",
+    "#### Passed",
+    "- _FILL_",
+    "",
+    "#### Failed",
+    "- _FILL or none_",
+    "",
+    tests.ran && tests.rawTail
+      ? `#### Raw tail (auto)\n\n\`\`\`\n${tests.rawTail.slice(-2000)}\n\`\`\``
+      : "",
+    "",
+    `### II.6 What got better / trade-offs / risks {#${anchor("ii6-outcomes")}}`,
+    "",
+    "**Better**",
+    "- _FILL_",
+    "",
+    "**Trade-offs**",
+    "- _FILL_",
+    "",
+    "**Regressions / risks**",
+    "- _FILL_",
+    "",
+    `### II.7 Follow-ups {#${anchor("ii7-follow-ups")}}`,
+    "",
+    "- [ ] _FILL_",
+    "",
+    `### II.8 APIs (full registry) {#${anchor("ii8-apis-full-registry")}}`,
+    "",
+    apisDetailedMarkdown,
+    "",
+    `### II.9 Git snapshot (full) {#${anchor("ii9-git-snapshot-full")}}`,
+    "",
+    "**Changed files (porcelain)**",
+    "",
+    "```",
+    git.statusPorcelain || "(clean)",
+    "```",
+    "",
+    "**Diff stat vs HEAD**",
+    "",
+    "```",
+    git.diffStatAgainstHead || "(no diff)",
+    "```",
+    "",
+    "**Recent commits**",
+    "",
+    "```",
+    (git.recentCommits || []).join("\n"),
+    "```",
+    "",
+    `### II.10 Repository tree (full) {#${anchor("repository-tree-full")}}`,
+    "",
+    `_Ignores: \`${treeIgnoreList}\` — equivalent to \`tree -I "node_modules|.git|dist|build"\`._`,
+    "",
+    "```text",
+    tree.treeText,
+    "```"
+  ];
+
+  return summary.join("\n");
+}

package/template/scripts/lib/git-snapshot.mjs

@@ -0,0 +1,46 @@
+import { execFile } from "child_process";
+import { promisify } from "util";
+
+const exec = promisify(execFile);
+
+async function git(args, cwd) {
+  try {
+    const { stdout } = await exec("git", args, { cwd, maxBuffer: 10 * 1024 * 1024 });
+    return stdout.trim();
+  } catch (err) {
+    return err.stdout?.trim() || "";
+  }
+}
+
+/**
+ * @param {string} repoRoot
+ */
+export async function collectGitSnapshot(repoRoot) {
+  const branch = await git(["rev-parse", "--abbrev-ref", "HEAD"], repoRoot);
+  const sha = await git(["rev-parse", "HEAD"], repoRoot);
+  const shortSha = await git(["rev-parse", "--short", "HEAD"], repoRoot);
+  const statusPorcelain = await git(["status", "--porcelain"], repoRoot);
+  const diffStat = await git(["diff", "--stat", "HEAD"], repoRoot);
+  const diffCachedStat = await git(["diff", "--cached", "--stat"], repoRoot);
+  const logOneline = await git(["log", "-5", "--oneline"], repoRoot);
+
+  const changedFiles = statusPorcelain
+    .split("\n")
+    .filter(Boolean)
+    .map((line) => {
+      const code = line.slice(0, 2);
+      const path = line.slice(3);
+      return { code, path };
+    });
+
+  return {
+    branch: branch || "unknown",
+    sha: sha || "unknown",
+    shortSha: shortSha || "unknown",
+    statusPorcelain,
+    changedFiles,
+    diffStatAgainstHead: diffStat,
+    diffCachedStat,
+    recentCommits: logOneline.split("\n").filter(Boolean)
+  };
+}

package/template/scripts/lib/module-scaffold.mjs

@@ -257,6 +257,8 @@ test("GET /api/${moduleName}/health", async () => {
 
 See [Module internal contract](../../../docs/architecture/MODULE_INTERNAL_CONTRACT.md).
 
+**HTTP API:** [docs/${moduleName}/API.md](../../../docs/${moduleName}/API.md) · [All modules](../../../docs/API.md)
+
 ## Layout
 
 \`routes\` → \`services\` → \`repositories\` / \`domain\` / \`adapters\`
@@ -355,7 +357,7 @@ export function useModuleHealth() {
 
   add(
     "services/health-api.js",
-    `import { apiGet } from "../../shared/api/client.js";
+    `import { apiGet } from "../../../shared/api/client.js";
 
 export function fetchModuleHealth() {
   return apiGet("/api/${moduleName}/health");
@@ -407,3 +409,37 @@ See [Module internal contract](../../../docs/architecture/MODULE_INTERNAL_CONTRA
 
   return files;
 }
+
+/** @param {string} moduleName kebab-case */
+export function getModuleApiDocContent(moduleName, label = toTitleCase(moduleName)) {
+  return `# ${label} — HTTP API
+
+**Base path:** \`/api/${moduleName}\`
+
+**Routes:** [\`backend/src/modules/${moduleName}/routes/\`](../../backend/src/modules/${moduleName}/routes/)
+
+**Contract:** [API documentation contract](../architecture/API_DOCUMENTATION_CONTRACT.md)
+
+---
+
+## Endpoint quick reference
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | \`/health\` | Module health |
+
+---
+
+## Health
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | \`/health\` | Module health and config summary |
+
+---
+
+## Master index
+
+[docs/API.md](../API.md) — add new rows to **Endpoint registry** when you add routes.
+`;
+}

package/template/scripts/lib/repo-tree.mjs

@@ -0,0 +1,127 @@
+import { readdir, stat } from "fs/promises";
+import { join, extname } from "path";
+
+/** Same ignores as `tree -I "node_modules|.git|dist|build"` */
+export const TREE_IGNORE_DIRS = ["node_modules", ".git", "dist", "build", ".DS_Store"];
+export const TREE_IGNORE_FILES = [".DS_Store"];
+
+const EXCLUDE_DIRS = new Set(TREE_IGNORE_DIRS);
+const EXCLUDE_FILES = new Set(TREE_IGNORE_FILES);
+
+function renderTreeText(nodes, prefix = "") {
+  const lines = [];
+  for (let i = 0; i < nodes.length; i += 1) {
+    const n = nodes[i];
+    const last = i === nodes.length - 1;
+    const branch = last ? "└── " : "├── ";
+    const childPrefix = prefix + (last ? "    " : "│   ");
+    const label = n.type === "directory" ? `${n.name}/` : n.name;
+    lines.push(`${prefix}${branch}${label}`);
+    if (n.type === "directory" && n.children?.length) {
+      lines.push(...renderTreeText(n.children, childPrefix));
+    }
+  }
+  return lines;
+}
+
+async function walkDir(absDir, relBase = "") {
+  const entries = await readdir(absDir, { withFileTypes: true });
+  const dirs = [];
+  const files = [];
+
+  for (const ent of entries) {
+    if (ent.isDirectory()) {
+      if (EXCLUDE_DIRS.has(ent.name)) continue;
+      dirs.push(ent.name);
+    } else if (ent.isFile()) {
+      if (EXCLUDE_FILES.has(ent.name)) continue;
+      files.push(ent.name);
+    }
+  }
+
+  dirs.sort((a, b) => a.localeCompare(b));
+  files.sort((a, b) => a.localeCompare(b));
+
+  const children = [];
+  const flatPaths = [];
+
+  for (const name of files) {
+    const rel = relBase ? `${relBase}/${name}` : name;
+    const st = await stat(join(absDir, name));
+    flatPaths.push(rel);
+    children.push({
+      name,
+      type: "file",
+      path: rel,
+      byteLength: st.size,
+      modifiedAt: st.mtime.toISOString()
+    });
+  }
+
+  for (const name of dirs) {
+    const rel = relBase ? `${relBase}/${name}` : name;
+    const sub = await walkDir(join(absDir, name), rel);
+    flatPaths.push(...sub.flatPaths);
+    children.push({
+      name,
+      type: "directory",
+      path: rel,
+      childCount: sub.childCount,
+      children: sub.children
+    });
+  }
+
+  return { children, flatPaths, childCount: children.length };
+}
+
+function countStats(flatPaths, treeChildren) {
+  const byExtension = {};
+  let fileCount = 0;
+  let dirCount = 0;
+
+  function walk(nodes) {
+    for (const n of nodes) {
+      if (n.type === "file") {
+        fileCount += 1;
+        const ext = extname(n.name).toLowerCase() || "(no extension)";
+        byExtension[ext] = (byExtension[ext] ?? 0) + 1;
+      } else {
+        dirCount += 1;
+        if (n.children) walk(n.children);
+      }
+    }
+  }
+  walk(treeChildren);
+
+  return {
+    fileCount,
+    directoryCount: dirCount,
+    pathCount: flatPaths.length,
+    byExtension: Object.fromEntries(
+      Object.entries(byExtension).sort((a, b) => b[1] - a[1])
+    )
+  };
+}
+
+/**
+ * @param {string} repoRoot
+ * @returns {Promise<{ rootName: string, tree: object, treeText: string, stats: object, flatPaths: string[] }>}
+ */
+export async function buildRepoTree(repoRoot) {
+  const rootName = repoRoot.split("/").pop() || "repo";
+  const walked = await walkDir(repoRoot);
+  const stats = countStats(walked.flatPaths, walked.children);
+  const treeText = [rootName + "/", ...renderTreeText(walked.children)].join("\n");
+  return {
+    rootName,
+    tree: {
+      name: rootName,
+      type: "directory",
+      path: "",
+      children: walked.children
+    },
+    treeText,
+    stats,
+    flatPaths: walked.flatPaths.sort((a, b) => a.localeCompare(b))
+  };
+}

package/template/scripts/lib/run-tests.mjs

@@ -0,0 +1,60 @@
+import { spawn } from "child_process";
+import { join } from "path";
+
+/**
+ * @param {string} repoRoot
+ * @param {{ run?: boolean }} options
+ */
+export function runTestSuite(repoRoot, { run = true } = {}) {
+  if (!run) {
+    return Promise.resolve({
+      ran: false,
+      exitCode: null,
+      passed: [],
+      failed: [],
+      summary: "skipped (--no-tests)"
+    });
+  }
+
+  return new Promise((resolve) => {
+    const child = spawn("npm", ["test"], {
+      cwd: repoRoot,
+      shell: true,
+      env: { ...process.env, FORCE_COLOR: "0" }
+    });
+
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (d) => {
+      stdout += d.toString();
+    });
+    child.stderr.on("data", (d) => {
+      stderr += d.toString();
+    });
+
+    child.on("close", (code) => {
+      const combined = `${stdout}\n${stderr}`;
+      const passed = [];
+      const failed = [];
+
+      for (const line of combined.split("\n")) {
+        if (/✔|✓|pass/i.test(line) && line.length < 200) passed.push(line.trim());
+        if (/✖|✗|fail/i.test(line) && line.length < 200) failed.push(line.trim());
+      }
+
+      const suitesMatch = combined.match(/ℹ tests (\d+)[\s\S]*?ℹ pass (\d+)[\s\S]*?ℹ fail (\d+)/);
+      const summary = suitesMatch
+        ? `tests=${suitesMatch[1]} pass=${suitesMatch[2]} fail=${suitesMatch[3]} exit=${code}`
+        : `exit=${code}`;
+
+      resolve({
+        ran: true,
+        exitCode: code ?? 1,
+        passed: [...new Set(passed)].slice(0, 80),
+        failed: [...new Set(failed)].slice(0, 80),
+        summary,
+        rawTail: combined.slice(-8000)
+      });
+    });
+  });
+}