@pukujan/create-modular-monolith 2.0.0 → 2.2.0

package/template/scripts/lint-contracts.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+import { readFileSync, existsSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+const manifestPath = join(repoRoot, "docs/architecture/contracts/manifest.json");
+
+const PATH_KEYS = [
+  "file",
+  "doc",
+  "overview",
+  "userDoc",
+  "timestampHelper",
+  "importScript",
+  "utility",
+  "schema",
+  "generator",
+  "humanFormat",
+  "verify",
+  "apiInventory",
+  "repoTree",
+  "workLogReadme",
+  "registry",
+  "lintScript",
+  "architectureDoc",
+  "promptVersions"
+];
+
+if (!existsSync(manifestPath)) {
+  console.error("Missing contracts manifest:", manifestPath);
+  process.exit(1);
+}
+
+const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+const failures = [];
+
+for (const [key, entry] of Object.entries(manifest)) {
+  const paths = PATH_KEYS.map((k) => entry?.[k]).filter(Boolean);
+  if (!paths.length) {
+    failures.push(`${key}: no documented paths in manifest`);
+    continue;
+  }
+  for (const rel of paths) {
+    const abs = join(repoRoot, rel);
+    if (!existsSync(abs)) {
+      failures.push(`${key}: path not found — ${rel}`);
+    }
+  }
+}
+
+if (failures.length) {
+  console.error("Contract lint failed:\n" + failures.map((f) => `  - ${f}`).join("\n"));
+  process.exit(1);
+}
+
+console.log(`Contract lint OK (${Object.keys(manifest).length} entries)`);

package/template/scripts/lint-repo-artifacts.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import { existsSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+const requiredPaths = [
+  "docs/architecture/CONTRACTS_OVERVIEW.md",
+  "docs/architecture/REPO_ARTIFACT_LAYOUT.md",
+  "docs/architecture/contracts/manifest.json",
+  "docs/architecture/contracts/changelog.jsonl",
+  "docs/architecture/contracts/fileExchange.contract.md",
+  "docs/architecture/contracts/consolidatedExports.contract.md",
+  "docs/architecture/contracts/prePushDevLog.contract.md",
+  "docs/architecture/contracts/apiDocumentationRegistry.contract.md",
+  "backend/src/shared/contracts/prePushDevLog.contract.js",
+  "backend/src/shared/contracts/consolidatedExports.contract.js",
+  "work-log/dev-logs/schemas/dev-log-agent.v1.schema.json",
+  "work-log/dev-logs/human",
+  "work-log/dev-logs/agent",
+  "file-exchange/README.md",
+  "file-exchange/imports",
+  "file-exchange/exports",
+  "docs/API.md",
+  "backend/src/modules/_reference/index.js",
+  "backend/src/modules/model-condenser/index.js"
+];
+
+const failures = requiredPaths.filter((rel) => !existsSync(join(repoRoot, rel)));
+
+if (failures.length) {
+  console.error("Repo artifact lint failed — missing:\n" + failures.map((f) => `  - ${f}`).join("\n"));
+  process.exit(1);
+}
+
+console.log(`Repo artifact lint OK (${requiredPaths.length} paths)`);

package/template/scripts/new-module.mjs

@@ -4,6 +4,7 @@ import { join } from "path";
 import {
   getBackendFiles,
   getFrontendFiles,
+  getModuleApiDocContent,
   toTitleCase
 } from "./lib/module-scaffold.mjs";
 
@@ -47,11 +48,17 @@ function writeTree(baseDir, files) {
 writeTree(backendDir, getBackendFiles(name));
 writeTree(frontendDir, getFrontendFiles(name, label));
 
+const docsDir = join(root, "docs", name);
+mkdirSync(docsDir, { recursive: true });
+writeFileSync(join(docsDir, "API.md"), getModuleApiDocContent(name, label), "utf8");
+
 console.log(`Created module: ${name}`);
 console.log(`  backend/src/modules/${name}/`);
 console.log(`  frontend/src/modules/${name}/`);
+console.log(`  docs/${name}/API.md`);
 console.log("");
 console.log("Next:");
+console.log(`  Add rows to docs/API.md (Module index + Endpoint registry) for /api/${name}`);
 console.log("  npm run lint:architecture");
 console.log(`  npm test`);
 console.log(`  npm run test:evals -- ${name}`);

package/template/scripts/resolve-import-stamp.mjs

@@ -0,0 +1,50 @@
+import { access } from "fs/promises";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { normalizeExchangeStamp } from "../backend/src/shared/utils/formatExchangeTimestamp.js";
+
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+/**
+ * Resolve imports/{stamp}/ — accepts human or legacy compact stamps.
+ * @param {string} [stamp]
+ * @returns {Promise<string>} resolved stamp folder name under imports/
+ */
+export async function resolveImportStamp(stamp) {
+  const candidates = [];
+  if (stamp) {
+    candidates.push(stamp, normalizeExchangeStamp(stamp));
+  }
+  const importsRoot = join(repoRoot, "file-exchange/imports");
+  const { readdir } = await import("fs/promises");
+  let dirs = [];
+  try {
+    dirs = await readdir(importsRoot);
+  } catch {
+    dirs = [];
+  }
+  if (!stamp && dirs.length) {
+    dirs.sort();
+    candidates.push(dirs[dirs.length - 1]);
+  }
+  const seen = new Set();
+  for (const c of candidates) {
+    if (!c || seen.has(c)) continue;
+    seen.add(c);
+    try {
+      await access(join(importsRoot, c));
+      return c;
+    } catch {
+      /* try next */
+    }
+  }
+  throw new Error(
+    stamp
+      ? `No import folder for stamp: ${stamp}`
+      : "No file-exchange/imports/{stamp}/ folder found"
+  );
+}
+
+export function importDirForStamp(stamp) {
+  return join(repoRoot, "file-exchange/imports", stamp);
+}

package/template/scripts/verify-dev-log.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+import { readFile, readdir } from "fs/promises";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+const agentDir = join(repoRoot, "work-log/dev-logs/agent");
+
+const files = (await readdir(agentDir)).filter((f) => f.endsWith(".json")).sort();
+const latest = files[files.length - 1];
+const agentPath = join(agentDir, latest);
+const humanName = latest.replace("_dev-log-agent_", "_dev-log_").replace(/\.json$/, ".md");
+const humanPath = join(repoRoot, "work-log/dev-logs/human", humanName);
+
+const agent = JSON.parse(await readFile(agentPath, "utf8"));
+const human = await readFile(humanPath, "utf8");
+
+const required = ["meta", "summary", "apis", "git", "tests", "repositoryTree", "changes", "decisions"];
+const missing = required.filter((k) => !(k in agent));
+
+console.log("Latest pair:");
+console.log("  agent:", agentPath.replace(repoRoot + "/", ""));
+console.log("  human:", humanPath.replace(repoRoot + "/", ""));
+
+let failed = 0;
+function assert(name, ok) {
+  console.log(ok ? "  PASS" : "  FAIL", name);
+  if (!ok) failed += 1;
+}
+
+assert("agent JSON has required keys", missing.length === 0);
+assert("apis.http.active > 0", agent.apis.http.active.length > 0);
+assert("repositoryTree.treeText present", agent.repositoryTree.treeText.length > 100);
+assert("treeIgnoreFlag set", agent.repositoryTree.treeIgnoreFlag?.includes("node_modules"));
+assert("tests ran", agent.tests.ran === true);
+
+assert("human: TOC", human.includes("## Table of contents"));
+assert("human: Part I", human.includes("Part I — Summary"));
+assert("human: Part II", human.includes("Part II — Detailed"));
+assert("human: mermaid blocks", (human.match(/```mermaid/g) || []).length >= 3);
+assert("human: I.3 API summary", human.includes("I.3 API surface"));
+assert("human: I.5 test audit", human.includes("I.5 Test audit"));
+assert("human: II.10 full tree", human.includes("II.10 Repository tree"));
+
+const treeSection = human.split("II.10 Repository tree")[1] || "";
+assert("tree excludes node_modules dir", !treeSection.includes("node_modules/"));
+
+console.log("\nTests:", agent.tests.summary);
+console.log(failed === 0 ? "\nAll checks passed." : `\n${failed} check(s) failed.`);
+process.exit(failed === 0 ? 0 : 1);

package/template/scripts/write-pre-push-dev-log.mjs

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+/**
+ * Create paired pre-push dev logs: human (markdown) + agent (JSON audit).
+ *
+ * Usage:
+ *   npm run dev-log:pre-push -- --slug consolidated-exports
+ *   npm run dev-log:pre-push -- --slug my-topic --program 005 --no-tests
+ *   npm run dev-log:pre-push -- --check   # verify agent log exists for HEAD
+ */
+import { readFile, writeFile, mkdir, readdir } from "fs/promises";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { formatWorkLogTimestamp } from "../backend/src/shared/utils/formatExchangeTimestamp.js";
+import { buildRepoTree, TREE_IGNORE_DIRS } from "./lib/repo-tree.mjs";
+import { collectGitSnapshot } from "./lib/git-snapshot.mjs";
+import { runTestSuite } from "./lib/run-tests.mjs";
+import { collectApiInventory, formatApisMarkdown } from "./lib/api-inventory.mjs";
+import { buildHumanDevLog } from "./lib/dev-log-human-format.mjs";
+
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+const humanDir = join(repoRoot, "work-log/dev-logs/human");
+const agentDir = join(repoRoot, "work-log/dev-logs/agent");
+
+function parseArgs(argv) {
+  const out = { slug: "", program: "005", noTests: false, check: false, title: "" };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === "--slug" && argv[i + 1]) out.slug = argv[++i];
+    else if (a === "--program" && argv[i + 1]) out.program = argv[++i];
+    else if (a === "--title" && argv[i + 1]) out.title = argv[++i];
+    else if (a === "--no-tests") out.noTests = true;
+    else if (a === "--check") out.check = true;
+  }
+  return out;
+}
+
+function slugify(s) {
+  return String(s)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+function classifyChangedFiles(changedFiles) {
+  const byArea = {};
+  const added = [];
+  const modified = [];
+  const deleted = [];
+
+  for (const { code, path } of changedFiles) {
+    const area = path.split("/")[0] || "root";
+    if (!byArea[area]) byArea[area] = [];
+    byArea[area].push(path);
+    if (code.includes("A") || code === "??") added.push(path);
+    else if (code.includes("D")) deleted.push(path);
+    else modified.push(path);
+  }
+
+  return { byArea, added, modified, deleted };
+}
+
+async function findAgentLogForSha(sha) {
+  let files;
+  try {
+    files = await readdir(agentDir);
+  } catch {
+    return null;
+  }
+  for (const f of files.filter((x) => x.endsWith(".json")).sort().reverse()) {
+    const raw = await readFile(join(agentDir, f), "utf8");
+    const doc = JSON.parse(raw);
+    if (doc.git?.sha === sha) return join(agentDir, f);
+  }
+  return null;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const git = await collectGitSnapshot(repoRoot);
+
+  if (args.check) {
+    const found = await findAgentLogForSha(git.sha);
+    if (!found) {
+      console.error(`No agent dev-log for HEAD (${git.shortSha}). Run: npm run dev-log:pre-push -- --slug <topic>`);
+      process.exit(1);
+    }
+    console.log(`OK: agent dev-log matches HEAD → ${found.replace(repoRoot + "/", "")}`);
+    return;
+  }
+
+  if (!args.slug) {
+    console.error("Usage: npm run dev-log:pre-push -- --slug <kebab-topic> [--program 005] [--no-tests]");
+    process.exit(1);
+  }
+
+  const { date, time, folder: stamp } = formatWorkLogTimestamp();
+  const entryId = String(args.program).padStart(3, "0");
+  const slug = slugify(args.slug);
+  const base = `${entryId}_${date}_${time}`;
+  const humanFilename = `${base}_dev-log_${slug}.md`;
+  const agentFilename = `${base}_dev-log-agent_${slug}.json`;
+  const humanPath = join(humanDir, humanFilename);
+  const agentPath = join(agentDir, agentFilename);
+  const humanRel = `work-log/dev-logs/human/${humanFilename}`;
+  const agentRel = `work-log/dev-logs/agent/${agentFilename}`;
+
+  console.log("Building repository tree…");
+  const tree = await buildRepoTree(repoRoot);
+
+  console.log("Collecting API inventory…");
+  const apis = await collectApiInventory(repoRoot);
+  const apisMarkdown = formatApisMarkdown(apis);
+  const treeIgnoreList = TREE_IGNORE_DIRS.filter((d) => d !== ".DS_Store").join("`, `");
+
+  console.log(args.noTests ? "Skipping tests." : "Running npm test…");
+  const tests = await runTestSuite(repoRoot, { run: !args.noTests });
+  const changes = classifyChangedFiles(git.changedFiles);
+
+  const title = args.title || slug.replace(/-/g, " ");
+  const apisDetailedMarkdown = apisMarkdown;
+
+  const humanBody = buildHumanDevLog({
+    title,
+    entryId,
+    date,
+    time,
+    humanFilename,
+    agentFilename,
+    git,
+    tests,
+    apis,
+    apisDetailedMarkdown,
+    tree,
+    treeIgnoreList
+  });
+
+  const agentDoc = {
+    meta: {
+      schemaVersion: "1.0.0",
+      entryId,
+      slug,
+      generatedAt: new Date().toISOString(),
+      humanLogPath: humanRel,
+      audience: "agent",
+      filledBy: "script",
+      handoffRefs: []
+    },
+    summary:
+      "FILL: One-paragraph audit summary for the next agent. What shipped, current state, blockers.",
+    apis,
+    git: {
+      branch: git.branch,
+      sha: git.sha,
+      shortSha: git.shortSha,
+      changedFiles: git.changedFiles,
+      diffStatAgainstHead: git.diffStatAgainstHead,
+      diffCachedStat: git.diffCachedStat,
+      recentCommits: git.recentCommits
+    },
+    tests: {
+      ran: tests.ran,
+      exitCode: tests.exitCode,
+      summary: tests.summary,
+      passed: tests.passed,
+      failed: tests.failed,
+      commands: tests.ran ? ["npm test"] : []
+    },
+    repositoryTree: {
+      capturedAt: new Date().toISOString(),
+      excludeDirs: TREE_IGNORE_DIRS,
+      treeIgnoreFlag: 'tree -I "node_modules|.git|dist|build"',
+      stats: tree.stats,
+      treeText: tree.treeText,
+      flatPathCount: tree.flatPaths.length
+    },
+    changes: {
+      ...changes,
+      narrative: ["FILL: bullet list of intentional behavioral / API changes"]
+    },
+    decisions: [
+      {
+        id: "D1",
+        decision: "FILL",
+        rationale: "FILL",
+        alternativesRejected: ["FILL"],
+        tradeoff: "FILL"
+      }
+    ],
+    iterations: [
+      {
+        attempt: 1,
+        action: "FILL: what was tried",
+        outcome: "FILL: pass/fail/deferred",
+        blockedBy: ""
+      }
+    ],
+    tradeoffs: ["FILL"],
+    improvements: ["FILL"],
+    regressions: ["FILL"],
+    risks: ["FILL"],
+    followUps: ["FILL"]
+  };
+
+  await mkdir(humanDir, { recursive: true });
+  await mkdir(agentDir, { recursive: true });
+  await writeFile(humanPath, humanBody);
+  await writeFile(agentPath, JSON.stringify(agentDoc, null, 2));
+
+  console.log("\nPre-push dev logs created:");
+  console.log(`  Human: ${humanRel}`);
+  console.log(`  Agent: ${agentRel}`);
+  console.log(`  Git:   ${git.branch} @ ${git.shortSha}`);
+  console.log(`  Tests: ${tests.summary}`);
+  console.log("\nNext: fill FILL sections in the agent JSON and narrative sections in the human MD, then add rows to work-log/INDEX.md");
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/template/work-log/INDEX.md

@@ -0,0 +1,3 @@
+# Work log — index
+
+See [README.md](./README.md). Add handoffs, study-docs, and dev-log rows as you work.

package/template/work-log/README.md

@@ -0,0 +1,40 @@
+# Work log
+
+Planning artifacts for this repo: **what to build** (handoffs) and **how we decided** (study docs).
+
+```text
+work-log/
+  README.md       ← you are here
+  INDEX.md        ← full index (handoffs + study-docs + dev-logs)
+  handoffs/       ← numbered specs, starter packs (002, 005, …)
+  study-docs/     ← study logs, planning notes, blog drafts
+  dev-logs/       ← pre-push audit: human/ + agent/ (paired per push)
+```
+
+## When to use which folder
+
+| Folder | Put here |
+|--------|----------|
+| **handoffs/** | Implementation specs, second/third handoffs, starter pack snapshots |
+| **study-docs/** | Conversation study logs, design rationale, portfolio / recruiter logs |
+| **dev-logs/** | What shipped — **paired human MD + agent JSON** before each push |
+
+## Filename convention (all three folders)
+
+```text
+{NNN}_{YYYY-MM-DD}_{HH-MM}_{kind}_{short-slug}.md
+```
+
+| Folder | `kind` value | Example |
+|--------|----------------|---------|
+| handoffs/ | `handoff`, `handoff-v2`, `handoff-original`, … | `005_2026-05-23_10-49_handoff-original_…` |
+| study-docs/ | `study-log` | `006_2026-05-23_11-21_study-log_cursor-planning-phase` |
+| dev-logs/ | `dev-log` (fixed) | `001_2026-05-24_14-30_dev-log_work-log-reorg` |
+
+Details: [handoffs/README.md](./handoffs/README.md) · [study-docs/README.md](./study-docs/README.md) · [dev-logs/README.md](./dev-logs/README.md)
+
+## 005 program order
+
+1. Original spec → [handoffs/005_…_handoff-original_…](./handoffs/005_2026-05-23_10-49_handoff-original_parsed-cache-rule-authority.md)
+2. v3 architecture → [handoffs/005_…_handoff-v3_…](./handoffs/005_2026-05-23_11-20_handoff-v3_filing-structure-architecture.md)
+3. v2 pipeline → [handoffs/005_…_handoff-v2_…](./handoffs/005_2026-05-23_11-14_handoff-v2_planned-review-in-cursor.md)

package/template/work-log/dev-logs/README.md

@@ -0,0 +1,97 @@
+# Dev logs
+
+Session **what we shipped** notes — written **before each push** as a paired human + agent audit.
+
+## Two types (required before push)
+
+| Type | Folder | Format | Audience |
+|------|--------|--------|----------|
+| **Human** | `human/` | Markdown (narrative, tables) | You, reviewers, GitHub |
+| **Agent audit** | `agent/` | JSON (`dev-log-agent.v1`) | Cursor / automation — fast structured read |
+
+Same timestamp prefix on both files so they stay paired:
+
+```text
+005_2026-05-23_17-30_dev-log_consolidated-exports.md          ← human/
+005_2026-05-23_17-30_dev-log-agent_consolidated-exports.json  ← agent/
+```
+
+## Pre-push workflow
+
+```bash
+# 1. Generate pair (git + npm test + full repo tree auto-filled)
+npm run dev-log:pre-push -- --slug <kebab-topic> --program 005
+
+# 2. Fill FILL sections in agent JSON, then human markdown
+
+# 3. Optional: block push if no agent log for HEAD
+npm run dev-log:pre-push -- --check
+```
+
+Cursor: use command **Pre-push dev log** (`.cursor/commands/pre-push-dev-log.md`).
+
+### Human log (two-part markdown)
+
+Each `human/*.md` file has:
+
+**Part I — Summary** (read first): table of contents, mermaid diagrams (HTTP modules, pipeline versions, pre-push flow), audit tables for APIs, prompt/version contracts, tests, git, condensed repo tree.
+
+**Part II — Detailed**: goals, decisions, changes, iterations, full API registry, full git snapshot, full repository tree.
+
+Generator: `scripts/lib/dev-log-human-format.mjs`
+
+### Agent log schema
+
+`schemas/dev-log-agent.v1.schema.json` — machine-readable:
+
+- `meta`, `summary`, `apis` (HTTP active/stub/deprecated, versioned contracts, CLI), `git`, `tests`, `repositoryTree`
+- `changes`, `decisions[]`, `iterations[]`
+- `tradeoffs`, `improvements`, `regressions`, `risks`, `followUps`
+
+Agents should read the **JSON** first when resuming work; humans read **markdown**.
+
+## vs other work-log folders
+
+| Folder | Audience | Content |
+|--------|----------|---------|
+| **handoffs/** | Implementers | Spec — what to build |
+| **study-docs/** | You + recruiters | Why — planning conversation |
+| **dev-logs/** | You + agents + reviewers | What landed — audit per push |
+
+## vs `docs/DEVLOG_V2.md`
+
+| Location | Use |
+|----------|-----|
+| [docs/DEVLOG_V2.md](../../docs/DEVLOG_V2.md) | Long-lived architecture narrative |
+| **dev-logs/** | Incremental per-push audit entries |
+
+## Legacy entries
+
+Older single-file logs at `dev-logs/*.md` (repo root of this folder) predate the human/agent split. New entries go only under `human/` and `agent/`.
+
+## Filename convention
+
+```text
+{NNN}_{YYYY-MM-DD}_{HH-MM}_dev-log_{slug}.md           → human/
+{NNN}_{YYYY-MM-DD}_{HH-MM}_dev-log-agent_{slug}.json    → agent/
+```
+
+| Part | Meaning |
+|------|---------|
+| `NNN` | Program id (`005`) or global sequence (`001`) |
+| `YYYY-MM-DD` | Session date |
+| `HH-MM` | Finish time (24h) |
+| `slug` | Kebab-case topic |
+
+## Git hook (optional)
+
+```bash
+cp scripts/git-hooks/pre-push.sample .git/hooks/pre-push
+chmod +x .git/hooks/pre-push
+```
+
+Reminds you to run `dev-log:pre-push`; use `--check` to enforce agent log for current `HEAD`.
+
+## GitHub
+
+Track in git. No secrets, credentials, or real filing text. Update [../INDEX.md](../INDEX.md) after each pair.