@pukujan/create-modular-monolith 2.0.0 → 2.2.0

package/template/scripts/condense-models.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * Model condenser CLI — calls POST /api/model-condenser/condense (or --local direct service).
+ * Always copies consolidated-models.json → file-exchange/exports/.
+ *
+ * Usage:
+ *   npm run condense-models
+ *   node scripts/condense-models.mjs --local
+ */
+import { readFile } from "fs/promises";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const args = new Set(process.argv.slice(2));
+const useLocal = args.has("--local");
+const includePayload = args.has("--include-payload");
+const baseUrl = process.env.API_BASE_URL || "http://localhost:3001";
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+async function condenseViaApi() {
+  const res = await fetch(`${baseUrl}/api/model-condenser/condense`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ includePayload })
+  });
+
+  const body = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    throw new Error(body.error || body.message || `HTTP ${res.status}`);
+  }
+  return body;
+}
+
+async function condenseLocal() {
+  const { getModuleConfig } = await import(
+    "../backend/src/modules/model-condenser/config/index.js"
+  );
+  const { condenseModels } = await import(
+    "../backend/src/modules/model-condenser/services/modelCondenser.service.js"
+  );
+  const config = getModuleConfig();
+  return condenseModels({
+    repoRoot: config.repoRoot,
+    modelsDir: config.modelsDir,
+    consolidatedFileName: config.consolidatedFileName,
+    includePayload
+  });
+}
+
+try {
+  const result = useLocal ? await condenseLocal() : await condenseViaApi();
+  const { CONSOLIDATED_EXPORT_DIR, CONSOLIDATED_FILENAMES, writeConsolidatedExport } =
+    await import("../backend/src/shared/utils/consolidatedExport.js");
+  const modelsPath = join(repoRoot, "models", CONSOLIDATED_FILENAMES.models);
+  const json = await readFile(modelsPath, "utf8");
+  await writeConsolidatedExport(repoRoot, CONSOLIDATED_FILENAMES.models, json);
+  const exportRel = `${CONSOLIDATED_EXPORT_DIR}/${CONSOLIDATED_FILENAMES.models}`;
+
+  console.log(`Model condenser: ${result.modelCount} models`);
+  console.log(`  → ${exportRel}`);
+  console.log(`  → models/${CONSOLIDATED_FILENAMES.models} (API mirror)`);
+  console.log(`Generated at: ${result.generatedAt}`);
+} catch (error) {
+  if (!useLocal) {
+    console.error(`API condense failed (${error.message}). Retry with --local or start the backend.`);
+  } else {
+    console.error(error.message);
+  }
+  process.exit(1);
+}

package/template/scripts/condense-prompts.mjs

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+/**
+ * Collect all versioned prompt templates into models/consolidated-prompts.json
+ * Usage: node scripts/condense-prompts.mjs
+ */
+import { readFile, readdir, stat, access } from "fs/promises";
+import { existsSync } from "fs";
+import { join, relative, dirname } from "path";
+import { fileURLToPath } from "url";
+import { writeConsolidatedArtifact } from "./consolidated-output.mjs";
+
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+const SCAN_ROOTS = ["backend/src/modules"];
+
+const PROMPT_EXTENSIONS = [".prompt.md", ".prompt.js"];
+
+function extractVariables(text) {
+  const vars = new Set();
+  const re = /\{\{(\w+)\}\}/g;
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    vars.add(m[1]);
+  }
+  return [...vars].sort();
+}
+
+async function walk(dir, acc = []) {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return acc;
+  }
+  for (const ent of entries) {
+    const full = join(dir, ent.name);
+    if (ent.isDirectory()) {
+      if (ent.name === "node_modules" || ent.name.startsWith(".")) continue;
+      await walk(full, acc);
+    } else if (PROMPT_EXTENSIONS.some((ext) => ent.name.endsWith(ext))) {
+      acc.push(full);
+    }
+  }
+  return acc;
+}
+
+async function findManifests() {
+  const manifests = {};
+  async function scanManifests(dir) {
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const ent of entries) {
+      const full = join(dir, ent.name);
+      if (ent.isDirectory()) {
+        if (ent.name === "node_modules" || ent.name.startsWith(".")) continue;
+        await scanManifests(full);
+      } else if (ent.name === "manifest.json" && full.includes("/prompts/")) {
+        const rel = relative(repoRoot, full);
+        try {
+          manifests[rel] = JSON.parse(await readFile(full, "utf8"));
+        } catch {
+          /* skip */
+        }
+      }
+    }
+  }
+  await scanManifests(join(repoRoot, "backend/src/modules"));
+  return manifests;
+}
+
+async function loadDomainPromptVersions() {
+  const path = join(
+    repoRoot,
+    "backend/src/modules/case-filing-ai/prompts/promptVersions.js"
+  );
+  if (!existsSync(path)) {
+    return { sourcePath: null, versions: {} };
+  }
+  const raw = await readFile(path, "utf8");
+  const versions = {};
+  const blockRe = /(\w+):\s*\{[^}]*id:\s*"([^"]+)"[^}]*masterCaseFiling:\s*"([^"]+)"[^}]*description:\s*"([^"]+)"/gs;
+  let m;
+  while ((m = blockRe.exec(raw)) !== null) {
+    versions[m[2]] = {
+      key: m[1],
+      id: m[2],
+      masterCaseFiling: m[3],
+      description: m[4]
+    };
+  }
+  return { sourcePath: relative(repoRoot, path), versions };
+}
+
+async function main() {
+  const promptFiles = [];
+  for (const root of SCAN_ROOTS) {
+    const found = await walk(join(repoRoot, root));
+    promptFiles.push(...found.filter((f) => !f.endsWith("manifest.json")));
+  }
+
+  promptFiles.sort();
+
+  const inventory = [];
+  const prompts = {};
+
+  for (const abs of promptFiles) {
+    const rel = relative(repoRoot, abs);
+    const content = await readFile(abs, "utf8");
+    const st = await stat(abs);
+    const moduleMatch = rel.match(/^backend\/src\/modules\/([^/]+)/);
+    const module = moduleMatch ? moduleMatch[1] : "starter-handoff";
+    const id = rel
+      .replace(/^backend\/src\/modules\/[^/]+\/prompts\//, "")
+      .replace(/^work-log\/handoffs\/[^/]+\/prompts\//, "starter/")
+      .replace(/[/.]/g, "_");
+
+    const entry = {
+      id,
+      path: rel,
+      module,
+      fileName: abs.split("/").pop(),
+      variables: extractVariables(content),
+      byteLength: Buffer.byteLength(content, "utf8"),
+      modifiedAt: st.mtime.toISOString()
+    };
+    inventory.push(entry);
+    prompts[rel] = {
+      ...entry,
+      content
+    };
+  }
+
+  const domainPromptVersions = await loadDomainPromptVersions();
+  const moduleManifests = await findManifests();
+
+  const doc = {
+    meta: {
+      generatedAt: new Date().toISOString(),
+      repositoryRoot: repoRoot,
+      condensedBy: "condense-prompts",
+      description: "Consolidated prompt templates across backend modules.",
+      promptCount: inventory.length
+    },
+    domainPromptVersions,
+    moduleManifests,
+    inventory,
+    prompts
+  };
+
+  const { exportPath, modelsPath } = await writeConsolidatedArtifact("prompts", doc);
+  console.log(`Consolidated ${inventory.length} prompts → ${exportPath} (+ ${modelsPath})`);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/template/scripts/consolidated-output.mjs

@@ -0,0 +1,49 @@
+import { mkdir, writeFile } from "fs/promises";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import {
+  CONSOLIDATED_EXPORT_DIR,
+  CONSOLIDATED_FILENAMES,
+  writeConsolidatedExport
+} from "../backend/src/shared/utils/consolidatedExport.js";
+
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+export { CONSOLIDATED_EXPORT_DIR, CONSOLIDATED_FILENAMES };
+
+/** Repo-relative paths: exports/ is primary; models/ mirrors for model-condenser API. */
+export const CONSOLIDATED_ARTIFACTS = {
+  models: {
+    filename: CONSOLIDATED_FILENAMES.models,
+    exportPath: `${CONSOLIDATED_EXPORT_DIR}/${CONSOLIDATED_FILENAMES.models}`,
+    modelsPath: `models/${CONSOLIDATED_FILENAMES.models}`
+  },
+  prompts: {
+    filename: CONSOLIDATED_FILENAMES.prompts,
+    exportPath: `${CONSOLIDATED_EXPORT_DIR}/${CONSOLIDATED_FILENAMES.prompts}`,
+    modelsPath: `models/${CONSOLIDATED_FILENAMES.prompts}`
+  },
+  fileStructure: {
+    filename: CONSOLIDATED_FILENAMES.fileStructure,
+    exportPath: `${CONSOLIDATED_EXPORT_DIR}/${CONSOLIDATED_FILENAMES.fileStructure}`,
+    modelsPath: `models/${CONSOLIDATED_FILENAMES.fileStructure}`
+  }
+};
+
+/**
+ * Write JSON to file-exchange/exports/ (primary) and models/ (API mirror).
+ * @param {"models"|"prompts"|"fileStructure"} kind
+ * @param {object} doc
+ */
+export async function writeConsolidatedArtifact(kind, doc) {
+  const spec = CONSOLIDATED_ARTIFACTS[kind];
+  const json = JSON.stringify(doc, null, 2);
+  await writeConsolidatedExport(repoRoot, spec.filename, json);
+  const modelsAbs = join(repoRoot, spec.modelsPath);
+  await mkdir(dirname(modelsAbs), { recursive: true });
+  await writeFile(modelsAbs, json);
+  return {
+    exportPath: spec.exportPath,
+    modelsPath: spec.modelsPath
+  };
+}

package/template/scripts/export-consolidated-models.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/** @deprecated Use `npm run condense-models` (model condenser API) instead. */
+import { spawn } from "child_process";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+
+const script = join(dirname(fileURLToPath(import.meta.url)), "condense-models.mjs");
+const child = spawn(process.execPath, [script, ...process.argv.slice(2)], {
+  stdio: "inherit"
+});
+child.on("exit", (code) => process.exit(code ?? 0));

package/template/scripts/git-hooks/pre-push.sample

@@ -0,0 +1,15 @@
+#!/bin/sh
+# Optional pre-push reminder — install:
+#   cp scripts/git-hooks/pre-push.sample .git/hooks/pre-push && chmod +x .git/hooks/pre-push
+#
+# Enforce agent log for HEAD (strict):
+#   DEVLOG_STRICT=1 npm run dev-log:pre-push -- --check
+
+if [ "$DEVLOG_STRICT" = "1" ]; then
+  npm run dev-log:pre-push -- --check || exit 1
+else
+  echo "pre-push: consider npm run dev-log:pre-push -- --slug <topic> (human + agent audit)"
+  echo "pre-push: strict check: DEVLOG_STRICT=1 (set in hook or env)"
+fi
+
+exit 0

package/template/scripts/import-to-file-exchange.mjs

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+/**
+ * Copy an inbound bundle into file-exchange/imports/{UTC-stamp}/
+ * Usage: node scripts/import-to-file-exchange.mjs /path/to/bundle [optional-stamp]
+ */
+import { cp, mkdir, access } from "fs/promises";
+import { join, basename, dirname } from "path";
+import { fileURLToPath } from "url";
+import { formatExchangeTimestamp } from "../backend/src/shared/utils/formatExchangeTimestamp.js";
+
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+async function main() {
+  const source = process.argv[2];
+  if (!source) {
+    console.error("Usage: node scripts/import-to-file-exchange.mjs <sourceDirOrZipParent> [UTC-stamp]");
+    process.exit(1);
+  }
+
+  const stamp = process.argv[3] || formatExchangeTimestamp();
+  const dest = join(repoRoot, "file-exchange/imports", stamp);
+  const absSource = join(process.cwd(), source);
+
+  try {
+    await access(absSource);
+  } catch {
+    console.error("Source not found:", absSource);
+    process.exit(1);
+  }
+
+  await mkdir(dest, { recursive: true });
+  const folderName = basename(absSource);
+  const target = join(dest, folderName);
+  await cp(absSource, target, { recursive: true });
+
+  console.log(`Imported → file-exchange/imports/${stamp}/${folderName}`);
+  console.log(`Use this stamp for ingest scripts or pass paths under imports/${stamp}/`);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/template/scripts/lib/api-inventory.mjs

@@ -0,0 +1,182 @@
+import { readFileSync, existsSync } from "fs";
+import { join } from "path";
+
+function readText(path) {
+  return readFileSync(path, "utf8");
+}
+
+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(),
+        path: cols[1].replace(/^`/, "").replace(/`$/, ""),
+        module: cols[2],
+        description: cols[3]
+      });
+    }
+  }
+  return rows;
+}
+
+function parseModuleIndex(masterText) {
+  const start = masterText.indexOf("## Module index");
+  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("module")) {
+      continue;
+    }
+    const cols = line
+      .split("|")
+      .map((c) => c.trim())
+      .filter(Boolean);
+    if (cols.length >= 3) {
+      rows.push({
+        module: cols[0],
+        basePath: cols[1].replace(/^`/, "").replace(/`$/, ""),
+        status: cols[3] || cols[2]
+      });
+    }
+  }
+  return rows;
+}
+
+function classifyRoute(row) {
+  const desc = row.description.toLowerCase();
+  if (desc.includes("deprecated")) return "deprecated";
+  if (desc.includes("stub") || desc.includes("health only")) return "stub";
+  return "active";
+}
+
+/**
+ * @param {string} repoRoot
+ */
+export async function collectApiInventory(repoRoot) {
+  const masterApiPath = join(repoRoot, "docs/API.md");
+  const masterText = existsSync(masterApiPath) ? readText(masterApiPath) : "";
+  const registry = parseRegistryRows(masterText);
+  const moduleIndex = parseModuleIndex(masterText);
+
+  const http = { active: [], stub: [], deprecated: [] };
+  for (const row of registry) {
+    http[classifyRoute(row)].push({
+      method: row.method,
+      path: row.path,
+      module: row.module,
+      description: row.description
+    });
+  }
+
+  const pkg = JSON.parse(readText(join(repoRoot, "package.json")));
+
+  const versioned = {
+    pipeline: {
+      app: pkg.version ?? "2.0.0",
+      note: "Add pipelineVersions.contract.js in domain modules when you introduce batch workflows"
+    },
+    prompts: {
+      defaultEnv: "n/a",
+      envVar: "MASTER_PROMPT_VERSION",
+      allowed: [],
+      specs: {},
+      notes: ["Add promptVersions.js in your domain module when you introduce LLM workflows"]
+    },
+    storage: {},
+    app: { packageJson: pkg.version }
+  };
+
+  const deprecated = { http: http.deprecated, cli: [], prompts: [], notes: [] };
+  const exportDeprecated = join(repoRoot, "scripts/export-consolidated-models.mjs");
+  if (existsSync(exportDeprecated)) {
+    const t = readText(exportDeprecated);
+    if (/@deprecated/i.test(t)) {
+      deprecated.cli.push({
+        command: "scripts/export-consolidated-models.mjs",
+        replacement: "npm run condense-models or POST /api/model-condenser/condense"
+      });
+    }
+  }
+
+  const cli = [
+    { command: "npm run test:ci", purpose: "All CI gates (lint + test + evals)" },
+    { command: "npm run dev-log:pre-push", purpose: "Paired human + agent dev logs" },
+    { command: "npm run condense:all", purpose: "Snapshots → file-exchange/exports/" },
+    { command: "npm run import:file-exchange", purpose: "Inbound → file-exchange/imports/{stamp}/" },
+    { command: "npm run lint:contracts", purpose: "Verify contract manifest paths" },
+    { command: "npm --prefix backend run condense-models", purpose: "Regenerate consolidated-models.json" }
+  ];
+
+  return {
+    capturedAt: new Date().toISOString(),
+    sourceDocs: ["docs/API.md", "backend/src/modules/*/routes/"],
+    http,
+    moduleStatus: moduleIndex.map((m) => ({
+      module: m.module,
+      basePath: m.basePath,
+      status: m.status
+    })),
+    versioned,
+    deprecated,
+    cli
+  };
+}
+
+/**
+ * @param {Awaited<ReturnType<typeof collectApiInventory>>} apis
+ */
+export function formatApisMarkdown(apis) {
+  const lines = [
+    "### HTTP — active",
+    "",
+    "| Method | Path | Module | Description |",
+    "|--------|------|--------|-------------|"
+  ];
+  for (const r of apis.http.active) {
+    lines.push(`| ${r.method} | \`${r.path}\` | ${r.module} | ${r.description} |`);
+  }
+  lines.push("", "### HTTP — stub (health only)", "");
+  if (apis.http.stub.length) {
+    lines.push("| Method | Path | Module | Description |", "|--------|------|--------|-------------|");
+    for (const r of apis.http.stub) {
+      lines.push(`| ${r.method} | \`${r.path}\` | ${r.module} | ${r.description} |`);
+    }
+  } else {
+    lines.push("_none_");
+  }
+  lines.push("", "### HTTP — deprecated", "");
+  if (apis.http.deprecated.length) {
+    lines.push("| Method | Path | Module | Description |", "|--------|------|--------|-------------|");
+    for (const r of apis.http.deprecated) {
+      lines.push(`| ${r.method} | \`${r.path}\` | ${r.module} | ${r.description} |`);
+    }
+  } else {
+    lines.push("_none registered in docs/API.md_");
+  }
+  lines.push("", "### Versioned contracts (platform)", "", "```json");
+  lines.push(JSON.stringify(apis.versioned.pipeline, null, 2));
+  lines.push("```");
+  if (apis.deprecated.cli.length) {
+    lines.push("", "### Deprecated CLI", "");
+    for (const d of apis.deprecated.cli) {
+      lines.push(`- \`${d.command}\` → ${d.replacement}`);
+    }
+  }
+  return lines.join("\n");
+}