@pukujan/create-modular-monolith 2.0.0 → 2.2.0

package/template/work-log/dev-logs/schemas/dev-log-agent.v1.schema.json

@@ -0,0 +1,119 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://legal-prmpt-eng.local/schemas/dev-log-agent.v1.json",
+  "title": "Agent audit dev log",
+  "description": "Machine-readable pre-push audit log for Cursor agents. Pair with human dev-log in work-log/dev-logs/human/.",
+  "type": "object",
+  "required": ["meta", "summary", "apis", "git", "tests", "repositoryTree", "changes", "decisions", "iterations", "tradeoffs", "improvements", "regressions", "risks", "followUps"],
+  "properties": {
+    "meta": {
+      "type": "object",
+      "required": ["schemaVersion", "entryId", "slug", "generatedAt", "humanLogPath", "audience"],
+      "properties": {
+        "schemaVersion": { "const": "1.0.0" },
+        "entryId": { "type": "string", "pattern": "^[0-9]{3}$" },
+        "slug": { "type": "string" },
+        "generatedAt": { "type": "string", "format": "date-time" },
+        "humanLogPath": { "type": "string" },
+        "audience": { "const": "agent" },
+        "filledBy": { "type": "string", "enum": ["script", "agent", "human"] },
+        "handoffRefs": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "summary": { "type": "string" },
+    "apis": {
+      "type": "object",
+      "description": "HTTP routes, versioned contracts, deprecated surfaces",
+      "properties": {
+        "capturedAt": { "type": "string" },
+        "sourceDocs": { "type": "array", "items": { "type": "string" } },
+        "http": {
+          "type": "object",
+          "properties": {
+            "active": { "type": "array" },
+            "stub": { "type": "array" },
+            "deprecated": { "type": "array" }
+          }
+        },
+        "moduleStatus": { "type": "array" },
+        "versioned": { "type": "object" },
+        "deprecated": { "type": "object" },
+        "cli": { "type": "array" }
+      }
+    },
+    "git": {
+      "type": "object",
+      "properties": {
+        "branch": { "type": "string" },
+        "sha": { "type": "string" },
+        "shortSha": { "type": "string" },
+        "changedFiles": { "type": "array" },
+        "diffStatAgainstHead": { "type": "string" },
+        "recentCommits": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "tests": {
+      "type": "object",
+      "properties": {
+        "ran": { "type": "boolean" },
+        "exitCode": { "type": ["integer", "null"] },
+        "summary": { "type": "string" },
+        "passed": { "type": "array", "items": { "type": "string" } },
+        "failed": { "type": "array", "items": { "type": "string" } },
+        "commands": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "repositoryTree": {
+      "type": "object",
+      "properties": {
+        "capturedAt": { "type": "string" },
+        "excludeDirs": { "type": "array", "items": { "type": "string" } },
+        "treeIgnoreFlag": { "type": "string" },
+        "stats": { "type": "object" },
+        "treeText": { "type": "string" },
+        "flatPathCount": { "type": "integer" }
+      }
+    },
+    "changes": {
+      "type": "object",
+      "properties": {
+        "byArea": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } },
+        "added": { "type": "array", "items": { "type": "string" } },
+        "modified": { "type": "array", "items": { "type": "string" } },
+        "deleted": { "type": "array", "items": { "type": "string" } },
+        "narrative": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "decisions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "decision", "rationale"],
+        "properties": {
+          "id": { "type": "string" },
+          "decision": { "type": "string" },
+          "rationale": { "type": "string" },
+          "alternativesRejected": { "type": "array", "items": { "type": "string" } },
+          "tradeoff": { "type": "string" }
+        }
+      }
+    },
+    "iterations": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "attempt": { "type": "integer" },
+          "action": { "type": "string" },
+          "outcome": { "type": "string" },
+          "blockedBy": { "type": "string" }
+        }
+      }
+    },
+    "tradeoffs": { "type": "array", "items": { "type": "string" } },
+    "improvements": { "type": "array", "items": { "type": "string" } },
+    "regressions": { "type": "array", "items": { "type": "string" } },
+    "risks": { "type": "array", "items": { "type": "string" } },
+    "followUps": { "type": "array", "items": { "type": "string" } }
+  }
+}

package/template/work-log/dev-logs/templates/dev-log-human.template.md

@@ -0,0 +1,10 @@
+# Dev log (human) — two-part layout
+
+Generated by `npm run dev-log:pre-push`. Do not edit this file directly.
+
+The generator builds:
+
+1. **Part I — Summary** (top): TOC, mermaid diagrams, audit tables (API, versions/prompts, tests, git, condensed tree).
+2. **Part II — Detailed** (bottom): decisions, iterations, full API registry, full git snapshot, full tree.
+
+See `scripts/lib/dev-log-human-format.mjs`.

package/template/work-log/handoffs/README.md

@@ -0,0 +1,36 @@
+# Handoffs
+
+Implementation specs and starter packs. Parent folder: [work-log](../README.md).
+
+Study logs and planning notes live in **[../study-docs/](../study-docs/)** — not here.
+
+## Layout
+
+```text
+work-log/handoffs/
+  001_*_starter_*/     ← starter pack (folder)
+  002_*_handoff_*.md
+  005_*_handoff_*.md   ← original, v2, v3
+```
+
+Full index: [../INDEX.md](../INDEX.md).
+
+## Filename convention
+
+```text
+{NNN}_{YYYY-MM-DD}_{HH-MM}_{kind}_{short-slug}.md
+```
+
+| Part | Example |
+|------|---------|
+| Date | `2026-05-23` |
+| Time | `10-49` (24h, optional) |
+| Kind | `handoff`, `handoff-v2`, `handoff-v3`, `handoff-original` |
+
+Same pattern in [study-docs](../study-docs/README.md) (`study-log`) and [dev-logs](../dev-logs/README.md) (`dev-log`).
+
+## 005 execution order
+
+1. [Original](./005_2026-05-23_10-49_handoff-original_parsed-cache-rule-authority.md) — requirements  
+2. [v3](./005_2026-05-23_11-20_handoff-v3_filing-structure-architecture.md) — architecture first  
+3. [v2](./005_2026-05-23_11-14_handoff-v2_planned-review-in-cursor.md) — pipeline implementation  

package/template/work-log/study-docs/README.md

@@ -0,0 +1,13 @@
+# Study docs
+
+Design rationale, planning conversations, and portfolio study logs. Parent: [work-log](../README.md).
+
+Implementation specs are in **[../handoffs/](../handoffs/)**.
+
+## Filename convention
+
+Same as [handoffs](../handoffs/README.md) and [dev-logs](../dev-logs/README.md):
+
+`{NNN}_{YYYY-MM-DD}_{HH-MM}_study-log_{slug}.md`
+
+Full index: [../INDEX.md](../INDEX.md).

package/bin/create-modular-monolith.js

@@ -1,132 +0,0 @@
-#!/usr/bin/env node
-import {
-  cpSync,
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  readdirSync,
-  writeFileSync
-} from "fs";
-import { join, resolve, basename } from "path";
-import { fileURLToPath } from "url";
-import { spawnSync } from "child_process";
-
-const __dirname = fileURLToPath(new URL(".", import.meta.url));
-const templateDir = join(__dirname, "..", "template");
-
-const args = process.argv.slice(2).filter((a) => a !== "--");
-const installDeps = args.includes("--install");
-const initGit = args.includes("--git");
-const positional = args.filter((a) => !a.startsWith("--"));
-
-const targetArg = positional[0];
-const cwd = process.cwd();
-const targetDir = targetArg ? resolve(cwd, targetArg) : resolve(cwd, "my-platform");
-const projectName = basename(targetDir);
-
-if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(projectName)) {
-  console.error(
-    "Project folder name must be kebab-case (example: my-platform).\n",
-    "Usage: npm create @pukujan/modular-monolith@2 my-platform"
-  );
-  process.exit(1);
-}
-
-if (!existsSync(templateDir)) {
-  console.error("Template missing. Reinstall @pukujan/create-modular-monolith.");
-  process.exit(1);
-}
-
-if (existsSync(targetDir)) {
-  try {
-    const entries = readdirSync(targetDir);
-    if (entries.length > 0) {
-      console.error(`Target directory is not empty: ${targetDir}`);
-      process.exit(1);
-    }
-  } catch {
-    console.error(`Cannot use target: ${targetDir}`);
-    process.exit(1);
-  }
-}
-
-const displayName = toTitleCase(projectName);
-
-console.log(`\nCreating modular monolith starter: ${projectName}`);
-console.log(`  → ${targetDir}\n`);
-
-mkdirSync(targetDir, { recursive: true });
-cpSync(templateDir, targetDir, { recursive: true });
-
-replaceInTree(targetDir, [
-  ["modular-monolith-starter-backend", `${projectName}-backend`],
-  ["modular-monolith-starter-frontend", `${projectName}-frontend`],
-  ["modular-monolith-starter", projectName],
-  ["Modular Monolith Platform Starter", displayName]
-]);
-
-if (installDeps) {
-  console.log("Installing dependencies…");
-  run("npm", ["install"], join(targetDir, "backend"));
-  run("npm", ["install"], join(targetDir, "frontend"));
-}
-
-if (initGit) {
-  run("git", ["init"], targetDir);
-  run("git", ["add", "."], targetDir);
-  run("git", ["commit", "-m", "chore: scaffold modular monolith starter"], targetDir);
-}
-
-console.log("\nDone.\n");
-console.log("Next steps:");
-console.log(`  cd ${targetArg || projectName}`);
-if (!installDeps) {
-  console.log("  cd backend && npm install");
-  console.log("  cd ../frontend && npm install");
-}
-console.log("  npm run dev:backend    # terminal 1");
-console.log("  npm run dev:frontend   # terminal 2");
-console.log(`  npm run new:module -- my-feature --label "My Feature"`);
-console.log("  npm run lint:architecture && npm test\n");
-
-function replaceInTree(dir, pairs) {
-  for (const file of walkFiles(dir)) {
-    if (!/\.(json|md|js|jsx|mjs|html)$/.test(file)) continue;
-    let content = readFileSync(file, "utf8");
-    let changed = false;
-    for (const [from, to] of pairs) {
-      if (content.includes(from)) {
-        content = content.split(from).join(to);
-        changed = true;
-      }
-    }
-    if (changed) writeFileSync(file, content, "utf8");
-  }
-}
-
-function walkFiles(dir, acc = []) {
-  for (const entry of readdirSync(dir, { withFileTypes: true })) {
-    const full = join(dir, entry.name);
-    if (entry.isDirectory()) {
-      if (entry.name === "node_modules") continue;
-      walkFiles(full, acc);
-    } else {
-      acc.push(full);
-    }
-  }
-  return acc;
-}
-
-function toTitleCase(value) {
-  return value
-    .split("-")
-    .map((p) => p.charAt(0).toUpperCase() + p.slice(1))
-    .join(" ");
-}
-
-function run(cmd, cmdArgs, dir) {
-  const result = spawnSync(cmd, cmdArgs, { cwd: dir, stdio: "inherit" });
-  if (result.status !== 0) {
-    console.warn(`Warning: ${cmd} ${cmdArgs.join(" ")} exited with ${result.status}`);
-  }
-}

package/template/backend/src/modules/_reference/evals/README.md

@@ -1,6 +0,0 @@
-# Evals — _reference
-
-- **datasets/** — fixtures (input, expected constraints).
-- **runners/** — `*.eval.mjs` files executed via `npm run test:evals`.
-
-Run: `npm run test:evals -- _reference`

package/template/backend/src/modules/_reference/evals/datasets/example.cases.json

@@ -1,12 +0,0 @@
-{
-  "cases": [
-    {
-      "id": "health-shape",
-      "description": "Health payload includes module name",
-      "input": {},
-      "expect": {
-        "status": "ok"
-      }
-    }
-  ]
-}

package/template/backend/src/modules/_reference/evals/runners/example.eval.mjs

@@ -1,25 +0,0 @@
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { readFileSync } from "fs";
-import { join, dirname } from "path";
-import { fileURLToPath } from "url";
-import { getHealth } from "../../services/health.service.js";
-import { renderPrompt } from "../../../../shared/ai/prompt-registry.js";
-import * as examplePrompt from "../../prompts/templates/example.prompt.js";
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-
-test("_reference: health service matches dataset", () => {
-  const dataset = JSON.parse(
-    readFileSync(join(__dirname, "../datasets/example.cases.json"), "utf8")
-  );
-  const expected = dataset.cases[0].expect;
-  const result = getHealth({ name: "_reference" });
-  assert.equal(result.status, expected.status);
-  assert.equal(result.module, "_reference");
-});
-
-test("_reference: example prompt renders variables", () => {
-  const rendered = renderPrompt(examplePrompt.template, { matterId: "MAT-001" });
-  assert.match(rendered, /MAT-001/);
-});

package/template/scripts/sync-cli-template.mjs

@@ -1,44 +0,0 @@
-#!/usr/bin/env node
-/**
- * Copies the v2 starter into packages/create-modular-monolith/template
- * for publishing with the npm CLI.
- */
-import { cpSync, existsSync, mkdirSync, rmSync } from "fs";
-import { join } from "path";
-
-const root = new URL("../", import.meta.url).pathname;
-const target = join(root, "packages/create-modular-monolith/template");
-
-const COPY_ROOTS = ["backend", "frontend", "docs", "scripts", "README.md", ".gitignore", "package.json"];
-
-const EXCLUDE_DIRS = new Set([
-  "node_modules",
-  ".git",
-  "dist",
-  "coverage",
-  "packages"
-]);
-
-if (existsSync(target)) {
-  rmSync(target, { recursive: true, force: true });
-}
-mkdirSync(target, { recursive: true });
-
-for (const item of COPY_ROOTS) {
-  const src = join(root, item);
-  if (!existsSync(src)) {
-    console.warn(`Skip missing: ${item}`);
-    continue;
-  }
-  const dest = join(target, item);
-  cpSync(src, dest, {
-    recursive: true,
-    filter: (sourcePath) => {
-      const parts = sourcePath.split(/[/\\]/);
-      return !parts.some((part) => EXCLUDE_DIRS.has(part));
-    }
-  });
-  console.log(`✓ ${item}`);
-}
-
-console.log(`\nTemplate synced to ${target}`);