@pukujan/create-modular-monolith 2.0.0

package/README.md

@@ -0,0 +1,43 @@
+# @pukujan/create-modular-monolith
+
+CLI for a **scalable modular monolith** starter: feature modules with strict boundaries, internal MVC layers, prompts, evals, tests, and automated architecture lint. Domain-agnostic — use it for any platform that should grow without rewrite.
+
+## Create a project
+
+```bash
+npm create @pukujan/modular-monolith@2 my-platform
+cd my-platform
+cd backend && npm install && cd ../frontend && npm install
+```
+
+Options:
+
+```bash
+npm create @pukujan/modular-monolith@2 my-platform -- --install --git
+```
+
+| Flag | Effect |
+| --- | --- |
+| `--install` | Run `npm install` in backend and frontend |
+| `--git` | `git init` and initial commit |
+
+## What you get
+
+- **Modular monolith** — auto-loaded backend modules + frontend route discovery
+- **Internal contract** — routes → services → repositories / domain / adapters
+- **AI-ready** — versioned `prompts/` and `evals/` per feature module
+- **Lint** — cross-module boundaries + layer direction (`lint:architecture`)
+
+## Publish (maintainers)
+
+From repo root on branch `v2`:
+
+```bash
+npm run sync:cli-template
+cd packages/create-modular-monolith
+npm publish --access public
+```
+
+## Source
+
+[litigation-workflow-application](https://github.com/Pukujan/litigation-workflow-application) branch `v2` (originated for legal workflows; architecture is industry-agnostic).

package/bin/create-modular-monolith.js

@@ -0,0 +1,132 @@
+#!/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/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@pukujan/create-modular-monolith",
+  "version": "2.0.0",
+  "description": "Scaffold a scalable modular monolith: strict module boundaries, MVC layers, prompts, evals, and architecture lint",
+  "type": "module",
+  "bin": {
+    "create-modular-monolith": "bin/create-modular-monolith.js"
+  },
+  "files": [
+    "bin",
+    "template"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "modular-monolith",
+    "monolith",
+    "architecture",
+    "scaffold",
+    "create-app",
+    "platform",
+    "microservices-ready",
+    "legal-tech"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Pukujan/litigation-workflow-application.git",
+    "directory": "packages/create-modular-monolith"
+  },
+  "bugs": {
+    "url": "https://github.com/Pukujan/litigation-workflow-application/issues"
+  },
+  "homepage": "https://github.com/Pukujan/litigation-workflow-application#readme"
+}

package/template/README.md

@@ -0,0 +1,73 @@
+# Modular Monolith Platform Starter (v2)
+
+A **scalable modular monolith** boilerplate: strict feature-module boundaries, internal MVC layers, prompts/evals for AI workflows, and automated architecture lint. Built for platforms that should grow toward services **without** a rewrite.
+
+Domain-agnostic — use it for legal tech, ops, marketplaces, or any multi-feature product. (This repo started as a litigation workflow; the architecture is not limited to that.)
+
+> **v1 (minimal)** — branch [`main`](https://github.com/Pukujan/litigation-workflow-application/tree/main). **v2 (platform)** — this branch + npm CLI.
+
+**Documentation:** [docs/README.md](./docs/README.md) · [DEVLOG v2](./docs/DEVLOG_V2.md) · [guardrails](./docs/architecture/ARCHITECTURE_GUARDRAILS.md) · [internal contract](./docs/architecture/MODULE_INTERNAL_CONTRACT.md)
+
+**Repository:** [github.com/Pukujan/litigation-workflow-application](https://github.com/Pukujan/litigation-workflow-application)
+
+## What is included
+
+- Backend module auto-loader + frontend route discovery
+- **Inter-module** guardrails (no cross-feature imports; event bus + HTTP)
+- **Intra-module** contract (routes → services → repositories / domain / adapters)
+- Prompts + evals colocated per feature module
+- `lint:architecture`, `npm test`, `npm run test:evals`
+- `_reference` example module (documentation only; not loaded at runtime)
+
+## Create a new project (npm CLI)
+
+```bash
+npm create @pukujan/modular-monolith@2 my-platform
+cd my-platform
+cd backend && npm install && cd ../frontend && npm install
+```
+
+Publish first: `@pukujan/create-modular-monolith` — see [docs/PUBLISHING.md](./docs/PUBLISHING.md).
+
+Local (without publish):
+
+```bash
+node packages/create-modular-monolith/bin/create-modular-monolith.js ../my-platform
+```
+
+## Repo structure
+
+```text
+modular-monolith-starter/
+├── backend/src/{core,shared,modules}/
+├── frontend/src/{core,shared,modules}/
+├── docs/architecture/
+├── scripts/new-module.mjs
+└── packages/create-modular-monolith/   # npm CLI
+```
+
+## Run locally (this repo)
+
+```bash
+cd backend && npm install && npm run dev
+# other terminal:
+cd frontend && npm install && npm run dev
+```
+
+## Create your first module
+
+```bash
+npm run new:module -- billing --label "Billing"
+```
+
+Restart backend; refresh frontend.
+
+## Architecture checks
+
+```bash
+npm run lint:architecture
+npm test
+npm run test:evals
+```
+
+See `backend/src/modules/_reference/` for the full internal layout.