@pukujan/create-modular-monolith 2.0.0 → 2.1.0

package/template/file-exchange/README.md

@@ -0,0 +1,41 @@
+# File exchange
+
+Dated folders for human ↔ agent file handoff. **No sensitive filing text in git** — use synthetic fixtures only.
+
+## Layout
+
+```text
+file-exchange/
+  imports/{2026-05-23_15-59-43Z}/          ← inbound bundles
+  exports/{2026-05-23_15-59-43Z_...}/      ← session deliverables (batch runs, curl logs)
+  exports/consolidated-models.json         ← repo snapshots (regenerate with condense:all)
+  exports/consolidated-prompts.json
+  exports/consolidated-file-structure.json
+```
+
+**Stamp format:** `YYYY-MM-DD_HH-MM-SSZ` via `formatExchangeTimestamp()` in `backend/src/shared/utils/formatExchangeTimestamp.js`.
+
+## Consolidated exports (in `exports/`)
+
+```bash
+npm run condense:all
+```
+
+| File in `exports/` | Mirror (API) |
+|--------------------|--------------|
+| `consolidated-models.json` | `models/consolidated-models.json` |
+| `consolidated-prompts.json` | `models/consolidated-prompts.json` |
+| `consolidated-file-structure.json` | `models/consolidated-file-structure.json` |
+
+**Open `file-exchange/exports/`** — all three consolidated files sit next to dated batch export folders.
+
+## Workflow
+
+1. Triage loose files into `imports/{stamp}/` (`npm run import:file-exchange -- <path>`).
+2. Process via case-filing APIs using files **under that stamp** only.
+3. Copy batch bundles / reports to `exports/{stamp}/` when done.
+4. Refresh consolidated snapshots: `npm run condense:all`.
+
+**Cursor agents:** mandatory — see [AGENTS.md](../AGENTS.md) and `.cursor/rules/file-exchange-inbox.mdc`.
+
+See [docs/architecture/REPO_ARTIFACT_LAYOUT.md](../docs/architecture/REPO_ARTIFACT_LAYOUT.md).

package/template/frontend/.env.example

@@ -0,0 +1,2 @@
+# Frontend — copy to frontend/.env.local (optional)
+VITE_API_BASE_URL=http://localhost:3001

package/template/frontend/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "modular-monolith-starter-frontend",
+  "name": "legal-prmpt-eng-frontend",
   "private": true,
   "version": "1.0.0",
   "type": "module",

package/template/frontend/src/index.css

@@ -51,3 +51,314 @@ a {
 .muted {
   color: #a8b4d8;
 }
+
+.upload-panel {
+  margin-top: 20px;
+}
+
+.upload-label {
+  display: block;
+  margin-bottom: 8px;
+  font-weight: 600;
+}
+
+.upload-panel input[type="file"] {
+  display: block;
+  width: 100%;
+  margin-bottom: 12px;
+  padding: 10px;
+  border: 1px dashed #3657a7;
+  border-radius: 8px;
+  background: #0b1020;
+  color: #f5f7ff;
+}
+
+.upload-actions {
+  display: flex;
+  gap: 12px;
+  align-items: center;
+  flex-wrap: wrap;
+}
+
+.upload-actions button {
+  background: #3657a7;
+  color: #fff;
+  border: none;
+  border-radius: 8px;
+  padding: 10px 16px;
+  cursor: pointer;
+}
+
+.upload-actions button:disabled {
+  opacity: 0.6;
+  cursor: not-allowed;
+}
+
+.error-text {
+  color: #ff8f8f;
+  margin-top: 12px;
+}
+
+.results-panel,
+.documents-list {
+  margin-top: 20px;
+}
+
+.result-card {
+  border: 1px solid #233257;
+  border-radius: 8px;
+  padding: 12px;
+  margin-top: 12px;
+  background: #0b1020;
+}
+
+.result-card pre {
+  white-space: pre-wrap;
+  word-break: break-word;
+  margin: 12px 0 0;
+  font-size: 13px;
+  line-height: 1.5;
+}
+
+.documents-list ul {
+  padding-left: 20px;
+}
+
+.panel {
+  border: 1px solid #233257;
+  border-radius: 8px;
+  padding: 14px;
+  margin-top: 16px;
+  background: #0b1020;
+}
+
+.rule-textarea {
+  width: 100%;
+  margin-top: 8px;
+  padding: 10px;
+  border: 1px solid #3657a7;
+  border-radius: 8px;
+  background: #121a31;
+  color: #f5f7ff;
+  font-family: inherit;
+  resize: vertical;
+}
+
+.rule-upload-row {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 12px;
+  margin-top: 12px;
+}
+
+.status-panel {
+  margin-top: 16px;
+}
+
+.results-panel details {
+  margin-top: 12px;
+}
+
+.results-panel summary {
+  cursor: pointer;
+  font-weight: 600;
+  margin-bottom: 8px;
+}
+
+.file-dropzone {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 12px;
+  margin-top: 10px;
+  padding: 16px;
+  border: 1px dashed #3657a7;
+  border-radius: 8px;
+  background: #121a31;
+}
+
+.pdf-filings-dropzone {
+  margin-top: 16px;
+  padding: 4px;
+  border-radius: 10px;
+  border: 2px dashed transparent;
+  transition: border-color 0.15s ease, background 0.15s ease;
+}
+
+.pdf-filings-dropzone.drag-active {
+  border-color: #6b9bff;
+  background: rgba(54, 87, 167, 0.12);
+}
+
+.pdf-filings-dropzone.disabled {
+  opacity: 0.7;
+  pointer-events: none;
+}
+
+.file-dropzone-inner {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 12px;
+  margin-top: 10px;
+  padding: 16px;
+  border: 1px dashed #3657a7;
+  border-radius: 8px;
+  background: #121a31;
+}
+
+.filing-upload-panel {
+  margin-top: 0;
+}
+
+.filing-upload-panel .supported-types {
+  font-size: 13px;
+  margin-top: 4px;
+}
+
+.pdf-file-list {
+  margin-top: 12px;
+}
+
+.file-list-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+}
+
+.file-list-header h3 {
+  margin: 0;
+}
+
+.file-list-hint {
+  margin-top: 12px;
+  margin-bottom: 0;
+}
+
+.link-button {
+  background: none;
+  border: none;
+  color: #a8c1ff;
+  cursor: pointer;
+  padding: 0;
+  font-size: 14px;
+}
+
+.link-button:hover {
+  text-decoration: underline;
+}
+
+.remove-file {
+  margin-left: 12px;
+}
+
+.pdf-file-list li {
+  margin-bottom: 6px;
+}
+
+.file-input-native-hidden {
+  display: none;
+}
+
+.file-picker-button {
+  display: inline-block;
+  background: #3657a7;
+  color: #fff;
+  border: none;
+  border-radius: 8px;
+  padding: 10px 16px;
+  cursor: pointer;
+  font: inherit;
+  font-weight: 600;
+}
+
+.file-picker-button:hover:not(:disabled) {
+  background: #4a6bc0;
+}
+
+.file-picker-button:disabled {
+  opacity: 0.6;
+  cursor: not-allowed;
+}
+
+.eval-panel {
+  margin-bottom: 20px;
+  padding-bottom: 0;
+}
+
+.eval-report-list {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  margin-top: 12px;
+}
+
+.eval-card {
+  border: 1px solid #233257;
+  border-radius: 8px;
+  padding: 12px;
+  background: #121a31;
+}
+
+.eval-card-header {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 8px;
+  margin-bottom: 8px;
+}
+
+.eval-badge {
+  font-size: 12px;
+  padding: 2px 8px;
+  border-radius: 999px;
+  text-transform: uppercase;
+  font-weight: 600;
+}
+
+.eval-status-pass {
+  border-color: #2d6a4f;
+}
+
+.eval-status-pass .eval-badge {
+  background: #1b4332;
+  color: #95d5b2;
+}
+
+.eval-status-partial {
+  border-color: #b08900;
+}
+
+.eval-status-partial .eval-badge {
+  background: #5c4a00;
+  color: #ffd166;
+}
+
+.eval-status-fail {
+  border-color: #9b2226;
+}
+
+.eval-status-fail .eval-badge {
+  background: #5c1a1d;
+  color: #ff8f8f;
+}
+
+.eval-critical ul,
+.eval-scores ul,
+.eval-mismatches {
+  margin: 8px 0 0;
+  padding-left: 20px;
+}
+
+.eval-scores ul li {
+  display: flex;
+  justify-content: space-between;
+  gap: 12px;
+}
+
+.eval-notes {
+  margin-top: 8px;
+  font-size: 13px;
+}

package/template/frontend/src/modules/_reference/services/health-api.js

@@ -1,4 +1,4 @@
-import { apiGet } from "../../shared/api/client.js";
+import { apiGet } from "../../../shared/api/client.js";
 
 export function fetchModuleHealth() {
   return apiGet("/api/_reference/health");

package/template/frontend/src/shared/api/client.js

@@ -1,10 +1,72 @@
 const BASE_URL = import.meta.env.VITE_API_BASE_URL || "http://localhost:3001";
 
-export async function apiGet(path) {
-  const response = await fetch(`${BASE_URL}${path}`);
+async function readResponseBody(response) {
+  const raw = await response.text();
+  if (!raw) return null;
+
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return raw;
+  }
+}
+
+function errorMessageFromBody(body, status) {
+  if (typeof body === "string" && body.trim()) {
+    return body.trim();
+  }
+  if (body && typeof body === "object") {
+    return body.error || body.message || `Request failed: ${status}`;
+  }
+  return `Request failed: ${status}`;
+}
+
+async function parseResponse(response) {
+  const body = await readResponseBody(response);
+
   if (!response.ok) {
-    const text = await response.text();
-    throw new Error(text || `Request failed: ${response.status}`);
+    throw new Error(errorMessageFromBody(body, response.status));
   }
-  return response.json();
+
+  return body;
+}
+
+export async function apiGet(path) {
+  const response = await fetch(`${BASE_URL}${path}`);
+  return parseResponse(response);
+}
+
+export async function apiPost(path, body) {
+  const response = await fetch(`${BASE_URL}${path}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body)
+  });
+  return parseResponse(response);
+}
+
+export async function apiPostForm(path, formData) {
+  const response = await fetch(`${BASE_URL}${path}`, {
+    method: "POST",
+    body: formData
+  });
+  return parseResponse(response);
+}
+
+export async function apiPatch(path, body) {
+  const response = await fetch(`${BASE_URL}${path}`, {
+    method: "PATCH",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body)
+  });
+  return parseResponse(response);
+}
+
+export async function apiDelete(path, body) {
+  const response = await fetch(`${BASE_URL}${path}`, {
+    method: "DELETE",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body ?? {})
+  });
+  return parseResponse(response);
 }

package/template/package.json

@@ -1,16 +1,23 @@
 {
-  "name": "modular-monolith-starter",
+  "name": "my-modular-monolith",
   "private": true,
   "version": "2.0.0",
   "scripts": {
-    "sync:cli-template": "node scripts/sync-cli-template.mjs",
     "dev:backend": "npm --prefix backend run dev",
     "dev:frontend": "npm --prefix frontend run dev",
     "lint:boundaries": "npm --prefix backend run lint:boundaries",
     "lint:layers": "npm --prefix backend run lint:layers",
+    "lint:api-docs": "node scripts/check-api-docs.mjs",
+    "lint:contracts": "node scripts/lint-contracts.mjs",
+    "lint:repo-artifacts": "node scripts/lint-repo-artifacts.mjs",
     "lint:architecture": "npm --prefix backend run lint:architecture",
     "test": "npm --prefix backend test && npm --prefix frontend test",
-    "test:evals": "node scripts/run-module-evals.mjs",
-    "new:module": "node scripts/new-module.mjs"
+    "new:module": "node scripts/new-module.mjs",
+    "condense-prompts": "node scripts/condense-prompts.mjs",
+    "condense-file-structure": "node scripts/condense-file-structure.mjs",
+    "condense:all": "npm run condense-prompts && npm run condense-file-structure && npm --prefix backend run condense-models -- --local",
+    "dev-log:pre-push": "node scripts/write-pre-push-dev-log.mjs",
+    "dev-log:verify": "node scripts/verify-dev-log.mjs",
+    "import:file-exchange": "node scripts/import-to-file-exchange.mjs"
   }
 }

package/template/scripts/check-api-docs.mjs

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+/**
+ * Ensures every Express route under backend/src/modules is documented in:
+ * - docs/<module>/API.md (path + method)
+ * - docs/API.md endpoint registry (full path + method)
+ */
+import { readFileSync, readdirSync, statSync, existsSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+const modulesDir = join(repoRoot, "backend/src/modules");
+const masterApiPath = join(repoRoot, "docs/API.md");
+
+const SKIP_MODULES = new Set(["_reference"]);
+const ROUTE_RE = /router\.(get|post|put|patch|delete)\(\s*["'`]([^"'`]+)["'`]/gi;
+const BASE_PATH_RE = /app\.use\(\s*["'`](\/api\/[^"'`]+)["'`]/;
+
+function readText(path) {
+  return readFileSync(path, "utf8");
+}
+
+function listRouteFiles(moduleDir) {
+  const routesDir = join(moduleDir, "routes");
+  if (!existsSync(routesDir)) return [];
+  return readdirSync(routesDir)
+    .filter((f) => f.endsWith(".js"))
+    .map((f) => join(routesDir, f));
+}
+
+function extractRoutesFromFile(filePath) {
+  const content = readText(filePath);
+  const routes = [];
+  let match;
+  ROUTE_RE.lastIndex = 0;
+  while ((match = ROUTE_RE.exec(content)) !== null) {
+    routes.push({
+      method: match[1].toUpperCase(),
+      path: match[2]
+    });
+  }
+  return routes;
+}
+
+function extractBasePath(moduleDir) {
+  const indexPath = join(moduleDir, "index.js");
+  if (!existsSync(indexPath)) return null;
+  const match = readText(indexPath).match(BASE_PATH_RE);
+  return match ? match[1] : null;
+}
+
+function normalizePath(path) {
+  return path.replace(/\/+/g, "/");
+}
+
+function moduleDocPath(moduleName) {
+  return join(repoRoot, "docs", moduleName, "API.md");
+}
+
+function pathDocumentedInModuleDoc(docText, method, routePath) {
+  const methodOk =
+    new RegExp(`\\b${method}\\b`, "i").test(docText) ||
+    new RegExp(`\\| ${method} \\|`, "i").test(docText);
+  const pathVariants = [
+    routePath,
+    routePath.replace(/:([A-Za-z0-9_]+)/g, ":$1"),
+    `\`${routePath}\``,
+    `\`${method} ${routePath}\``,
+    `\`${method.toLowerCase()} ${routePath}\``
+  ];
+  const pathOk = pathVariants.some((p) => docText.includes(p));
+  return methodOk && pathOk;
+}
+
+function parseRegistryRows(masterText) {
+  const start = masterText.indexOf("## Endpoint registry");
+  if (start < 0) return [];
+  const section = masterText.slice(start);
+  const end = section.indexOf("\n## ", 4);
+  const body = end >= 0 ? section.slice(0, end) : section;
+  const rows = [];
+  for (const line of body.split("\n")) {
+    if (!line.startsWith("|") || line.includes("---") || line.toLowerCase().includes("method")) {
+      continue;
+    }
+    const cols = line
+      .split("|")
+      .map((c) => c.trim())
+      .filter(Boolean);
+    if (cols.length >= 4) {
+      rows.push({
+        method: cols[0].toUpperCase(),
+        fullPath: cols[1].replace(/^`/, "").replace(/`$/, ""),
+        module: cols[2],
+        description: cols[3]
+      });
+    }
+  }
+  return rows;
+}
+
+function registryHasRoute(registryRows, method, fullPath) {
+  return registryRows.some(
+    (r) => r.method === method && normalizePath(r.fullPath) === normalizePath(fullPath)
+  );
+}
+
+function collectModules() {
+  return readdirSync(modulesDir).filter((name) => {
+    if (SKIP_MODULES.has(name)) return false;
+    const full = join(modulesDir, name);
+    return statSync(full).isDirectory() && existsSync(join(full, "index.js"));
+  });
+}
+
+function main() {
+  const errors = [];
+  const masterText = readText(masterApiPath);
+  const registryRows = parseRegistryRows(masterText);
+
+  if (!masterText.includes("## Endpoint registry")) {
+    errors.push("docs/API.md is missing ## Endpoint registry section");
+  }
+
+  for (const moduleName of collectModules()) {
+    const moduleDir = join(modulesDir, moduleName);
+    const basePath = extractBasePath(moduleDir);
+    if (!basePath) {
+      errors.push(`${moduleName}: could not read app.use base path from index.js`);
+      continue;
+    }
+
+    const docPath = moduleDocPath(moduleName);
+    if (!existsSync(docPath)) {
+      errors.push(`${moduleName}: missing ${docPath.replace(repoRoot + "/", "")}`);
+      continue;
+    }
+
+    const docText = readText(docPath);
+    const routes = [];
+    for (const file of listRouteFiles(moduleDir)) {
+      routes.push(...extractRoutesFromFile(file));
+    }
+
+    for (const { method, path: routePath } of routes) {
+      const fullPath = normalizePath(`${basePath}${routePath}`);
+
+      if (!pathDocumentedInModuleDoc(docText, method, routePath)) {
+        errors.push(
+          `${moduleName}: ${method} ${routePath} not documented in docs/${moduleName}/API.md`
+        );
+      }
+
+      if (!registryHasRoute(registryRows, method, fullPath)) {
+        errors.push(
+          `${moduleName}: ${method} ${fullPath} missing from docs/API.md Endpoint registry`
+        );
+      } else {
+        const row = registryRows.find(
+          (r) => r.method === method && normalizePath(r.fullPath) === fullPath
+        );
+        if (row && row.description.length < 8) {
+          errors.push(
+            `${moduleName}: ${fullPath} registry description too short (min ~8 chars)`
+          );
+        }
+      }
+    }
+  }
+
+  if (errors.length) {
+    console.error("API documentation check failed:\n");
+    for (const err of errors) {
+      console.error(`  - ${err}`);
+    }
+    console.error("\nSee docs/architecture/API_DOCUMENTATION_CONTRACT.md");
+    process.exit(1);
+  }
+
+  console.log(`API documentation OK (${registryRows.length} registry rows)`);
+}
+
+main();