create-project-arch 1.0.0

package/README.md

@@ -0,0 +1,58 @@
+# create-project-arch
+
+A scaffolding tool designed to bootstrap a new Turborepo monorepo with `project-arch` integrated natively.
+
+## Usage
+
+You can use `npx` or `pnpx` to run the scaffolder directly:
+
+```bash
+npx create-project-arch my-new-architecture
+```
+
+### Under the Hood
+
+When executed, `create-project-arch`:
+
+1. Runs `npx create-turbo` to generate the raw workspace.
+2. Invokes `pa init` to seed an `arch-model/` directory.
+3. Injects architecture applications (`apps/arch` and `packages/ui`) from internal templates.
+4. Auto-wires the `package.json` configurations so `project-arch` commands are available out of the box.
+
+## Options
+
+```bash
+create-project-arch <project-name> [options]
+
+Options:
+  --template <name>      template (default: "nextjs-turbo")
+  --apps <items>         comma-separated apps (default: "web,docs")
+  --pm <name>            package manager (default: "pnpm")
+  --with-ai              create ai/indexing directory (default: false)
+  --with-docs-site       create docs app (default: enabled)
+  --force                allow scaffolding in a non-empty target directory
+```
+
+## Developing the Architecture UI (Arch-UI)
+The `arch-ui` Next.js application and `@repo/ui` packages are stored as static templates inside `templates/`. To iterate on them with full IDE support and hot-reloading, use the Sandbox DX flow provided in the monorepo root:
+
+1. **Initialize the Sandbox:**
+   ```bash
+   pnpm run sandbox:init
+   ```
+   *This scaffolds `testProject` and runs `pnpm install` inside it.*
+
+2. **Start the Dev Server:**
+   ```bash
+   pnpm run sandbox:dev
+   ```
+   *This boots up Next.js for the `arch-ui` inside the sandbox on port 4020.*
+
+3. **Develop & Iterate:**
+   Open the files located in `testProject/apps/arch/` and `testProject/packages/ui/`. Your changes will hot-reload.
+
+4. **Sync Changes Back:**
+   When you are satisfied with your UI changes, sync them back to the static `templates/` directory so they are included in the next CLI release:
+   ```bash
+   pnpm run sandbox:sync
+   ```

package/dist/cli.js

@@ -0,0 +1,232 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const path_1 = __importDefault(require("path"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const child_process_1 = require("child_process");
+const commander_1 = require("commander");
+function getTemplatesRoot() {
+    return path_1.default.resolve(__dirname, "../templates");
+}
+async function getProjectArchVersion() {
+    const projectArchEntry = require.resolve("project-arch");
+    const projectArchPkgPath = path_1.default.resolve(projectArchEntry, "../../../package.json");
+    const sourceProjectArchPkg = await fs_extra_1.default.readJSON(projectArchPkgPath);
+    return String(sourceProjectArchPkg.version ?? "1.0.0");
+}
+function normalizePathForPackageJson(value) {
+    return value.split(path_1.default.sep).join("/");
+}
+async function getProjectArchDependencySpec(targetDir, consumerDir) {
+    const localProjectArchPath = path_1.default.resolve(targetDir, "..", "packages", "project-arch");
+    const localProjectArchPkgPath = path_1.default.join(localProjectArchPath, "package.json");
+    if (await fs_extra_1.default.pathExists(localProjectArchPkgPath)) {
+        const localProjectArchPkg = await fs_extra_1.default.readJSON(localProjectArchPkgPath);
+        if (localProjectArchPkg.name === "project-arch") {
+            const relative = path_1.default.relative(consumerDir, localProjectArchPath);
+            return `link:${normalizePathForPackageJson(relative)}`;
+        }
+    }
+    const projectArchVersion = await getProjectArchVersion();
+    return `^${projectArchVersion}`;
+}
+function runCreateTurbo(projectName, options) {
+    const args = [
+        "--yes",
+        "create-turbo@latest",
+        projectName,
+        "--package-manager",
+        options.pm,
+        "--skip-install",
+    ];
+    const result = (0, child_process_1.spawnSync)("npx", args, {
+        cwd: process.cwd(),
+        stdio: "inherit",
+    });
+    if (result.error) {
+        throw result.error;
+    }
+    if (typeof result.status === "number" && result.status !== 0) {
+        process.exit(result.status);
+    }
+}
+async function runPaInit(targetDir, options) {
+    const { runCli } = await import("project-arch/cli");
+    const argv = [
+        "node",
+        "pa",
+        "init",
+        "--template",
+        options.template,
+        "--apps",
+        options.apps,
+        "--pm",
+        options.pm,
+    ];
+    if (options.withAi) {
+        argv.push("--with-ai");
+    }
+    if (options.withDocsSite) {
+        argv.push("--with-docs-site");
+    }
+    const previousCwd = process.cwd();
+    process.chdir(targetDir);
+    try {
+        await runCli(argv);
+    }
+    finally {
+        process.chdir(previousCwd);
+    }
+}
+async function wireProjectArchUsage(targetDir) {
+    const rootPackageJsonPath = path_1.default.join(targetDir, "package.json");
+    if (!(await fs_extra_1.default.pathExists(rootPackageJsonPath))) {
+        throw new Error(`Missing generated package.json in ${targetDir}`);
+    }
+    const projectArchDependency = await getProjectArchDependencySpec(targetDir, targetDir);
+    const pkg = await fs_extra_1.default.readJSON(rootPackageJsonPath);
+    const nextPkg = {
+        ...pkg,
+        scripts: {
+            ...(pkg.scripts ?? {}),
+            pa: "pa",
+            "arch:check": "pa check",
+            "arch:report": "pa report",
+        },
+        devDependencies: {
+            ...(pkg.devDependencies ?? {}),
+            "project-arch": projectArchDependency,
+        },
+    };
+    await fs_extra_1.default.writeJSON(rootPackageJsonPath, nextPkg, { spaces: 2 });
+    await fs_extra_1.default.appendFile(rootPackageJsonPath, "\n");
+}
+async function scaffoldArchitectureApps(targetDir) {
+    const templatesRoot = getTemplatesRoot();
+    const archUiTemplate = path_1.default.join(templatesRoot, "arch-ui");
+    const uiPackageTemplate = path_1.default.join(templatesRoot, "ui-package");
+    const appsRoot = path_1.default.join(targetDir, "apps");
+    const packagesRoot = path_1.default.join(targetDir, "packages");
+    const archUiTarget = path_1.default.join(appsRoot, "arch");
+    const uiPackageTarget = path_1.default.join(packagesRoot, "ui");
+    if (!(await fs_extra_1.default.pathExists(archUiTemplate))) {
+        throw new Error(`Missing architecture app templates at ${templatesRoot}`);
+    }
+    if (!(await fs_extra_1.default.pathExists(uiPackageTemplate))) {
+        throw new Error(`Missing ui package templates at ${templatesRoot}`);
+    }
+    await fs_extra_1.default.ensureDir(appsRoot);
+    await fs_extra_1.default.ensureDir(packagesRoot);
+    await fs_extra_1.default.copy(uiPackageTemplate, uiPackageTarget, { overwrite: true });
+    await fs_extra_1.default.copy(archUiTemplate, archUiTarget, { overwrite: true });
+    const projectArchDependency = await getProjectArchDependencySpec(targetDir, archUiTarget);
+    const archUiPkgPath = path_1.default.join(archUiTarget, "package.json");
+    const archUiPkg = await fs_extra_1.default.readJSON(archUiPkgPath);
+    const nextArchUiPkg = {
+        ...archUiPkg,
+        dependencies: {
+            ...(archUiPkg.dependencies ?? {}),
+            "project-arch": projectArchDependency,
+        },
+    };
+    await fs_extra_1.default.writeJSON(archUiPkgPath, nextArchUiPkg, { spaces: 2 });
+    await fs_extra_1.default.appendFile(archUiPkgPath, "\n");
+}
+async function upsertArchModulesInMap(targetDir) {
+    const modulesPath = path_1.default.join(targetDir, "arch-model", "modules.json");
+    if (!(await fs_extra_1.default.pathExists(modulesPath))) {
+        return;
+    }
+    const existing = (await fs_extra_1.default.readJSON(modulesPath));
+    const currentModules = Array.isArray(existing.modules) ? existing.modules : [];
+    const byName = new Map();
+    for (const moduleDef of currentModules) {
+        if (!moduleDef || typeof moduleDef.name !== "string") {
+            continue;
+        }
+        byName.set(moduleDef.name, {
+            name: moduleDef.name,
+            type: typeof moduleDef.type === "string" ? moduleDef.type : "application",
+            description: typeof moduleDef.description === "string"
+                ? moduleDef.description
+                : "Module in the monorepo.",
+        });
+    }
+    byName.set("apps/arch", {
+        name: "apps/arch",
+        type: "application",
+        description: "Architecture control surface UI.",
+    });
+    byName.delete("apps/arch-api");
+    const merged = [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+    await fs_extra_1.default.writeJSON(modulesPath, { modules: merged }, { spaces: 2 });
+    await fs_extra_1.default.appendFile(modulesPath, "\n");
+}
+async function ensureTargetDir(targetDir, force) {
+    if (!(await fs_extra_1.default.pathExists(targetDir))) {
+        return;
+    }
+    const entries = await fs_extra_1.default.readdir(targetDir);
+    if (entries.length === 0) {
+        await fs_extra_1.default.remove(targetDir);
+        return;
+    }
+    if (!force) {
+        throw new Error(`Target directory '${targetDir}' is not empty. Use --force to overwrite.`);
+    }
+    await fs_extra_1.default.remove(targetDir);
+}
+async function main() {
+    const program = new commander_1.Command();
+    program
+        .name("create-project-arch")
+        .description("Create a project-arch monorepo")
+        .argument("<project-name>", "target directory name")
+        .option("--template <name>", "template", "nextjs-turbo")
+        .option("--apps <items>", "comma-separated apps", "web,docs")
+        .option("--pm <name>", "package manager", "pnpm")
+        .option("--with-ai", "create ai/indexing directory", false)
+        .option("--with-docs-site", "create docs app (default: enabled)", true)
+        .option("--force", "allow scaffolding in a non-empty target directory", false)
+        .action(async (projectName, options) => {
+        if (projectName === "." || projectName === "./") {
+            throw new Error("Refusing to scaffold into current directory. Provide a new project directory name.");
+        }
+        if (!/^[a-zA-Z0-9-_]+$/.test(projectName)) {
+            throw new Error("Invalid project name. Only alphanumeric characters, dashes, and underscores are allowed.");
+        }
+        const targetDir = path_1.default.resolve(process.cwd(), projectName);
+        await ensureTargetDir(targetDir, options.force);
+        runCreateTurbo(projectName, options);
+        // Ensure empty scaffolded packages have a .gitkeep so they are tracked by git
+        const emptyPackages = ["api", "config", "database", "types"];
+        for (const pkg of emptyPackages) {
+            const pkgDir = path_1.default.join(targetDir, "packages", pkg);
+            if (await fs_extra_1.default.pathExists(pkgDir)) {
+                const entries = await fs_extra_1.default.readdir(pkgDir);
+                if (entries.length === 0) {
+                    await fs_extra_1.default.writeFile(path_1.default.join(pkgDir, ".gitkeep"), "");
+                }
+            }
+        }
+        await runPaInit(targetDir, options);
+        await scaffoldArchitectureApps(targetDir);
+        await upsertArchModulesInMap(targetDir);
+        await wireProjectArchUsage(targetDir);
+        const relativeTarget = path_1.default.relative(process.cwd(), targetDir) || ".";
+        console.log(`\nCreated project-arch repo at ${relativeTarget}`);
+        console.log("\nNext steps:");
+        console.log(`  cd ${relativeTarget}`);
+        console.log("  pnpm install");
+        console.log("  pnpm arch:check");
+    });
+    await program.parseAsync(process.argv);
+}
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(message);
+    process.exit(1);
+});

package/dist/cli.test.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+(0, vitest_1.describe)("create-project-arch CLI", () => {
+    (0, vitest_1.it)("runs test suite successfully", () => {
+        (0, vitest_1.expect)(true).toBe(true);
+    });
+});

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "create-project-arch",
+  "version": "1.0.0",
+  "description": "Scaffold a project-arch monorepo",
+  "bin": {
+    "create-project-arch": "dist/cli.js"
+  },
+  "main": "dist/cli.js",
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "dependencies": {
+    "commander": "^12.1.0",
+    "fs-extra": "^11.3.0",
+    "project-arch": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^22.13.8",
+    "typescript": "^5.8.2"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint \"src/**/*.ts\"",
+    "test": "vitest run"
+  }
+}

package/templates/arch-ui/.arch/edges/decision_to_domain.json

@@ -0,0 +1,4 @@
+{
+  "edges": []
+}
+

package/templates/arch-ui/.arch/edges/milestone_to_task.json

@@ -0,0 +1,4 @@
+{
+  "edges": []
+}
+

package/templates/arch-ui/.arch/edges/task_to_decision.json

@@ -0,0 +1,4 @@
+{
+  "edges": []
+}
+

package/templates/arch-ui/.arch/edges/task_to_module.json

@@ -0,0 +1,4 @@
+{
+  "edges": []
+}
+

package/templates/arch-ui/.arch/graph.json

@@ -0,0 +1,17 @@
+{
+  "schemaVersion": "1.0",
+  "nodes": {
+    "domains": 0,
+    "decisions": 0,
+    "milestones": 0,
+    "tasks": 0,
+    "modules": 0
+  },
+  "edges": {
+    "task_to_decision": 0,
+    "task_to_module": 0,
+    "decision_to_domain": 0,
+    "milestone_to_task": 0
+  }
+}
+

package/templates/arch-ui/.arch/nodes/decisions.json

@@ -0,0 +1,4 @@
+{
+  "decisions": []
+}
+

package/templates/arch-ui/.arch/nodes/domains.json

@@ -0,0 +1,4 @@
+{
+  "domains": []
+}
+

package/templates/arch-ui/.arch/nodes/milestones.json

@@ -0,0 +1,4 @@
+{
+  "milestones": []
+}
+

package/templates/arch-ui/.arch/nodes/modules.json

@@ -0,0 +1,4 @@
+{
+  "modules": []
+}
+

package/templates/arch-ui/.arch/nodes/tasks.json

@@ -0,0 +1,4 @@
+{
+  "tasks": []
+}
+

package/templates/arch-ui/app/api/architecture/map/route.ts

@@ -0,0 +1,13 @@
+import { NextResponse } from "next/server";
+import { graph } from "project-arch";
+import { readArchitectureMap } from "../../../../lib/arch-model";
+import { getProjectRoot } from "../../../../lib/project-root";
+
+export const runtime = "nodejs";
+
+export async function GET() {
+  const root = getProjectRoot();
+  process.env.PROJECT_ROOT = root;
+  await graph.graphBuild();
+  return NextResponse.json(await readArchitectureMap(root));
+}

package/templates/arch-ui/app/api/decisions/route.ts

@@ -0,0 +1,23 @@
+import { NextRequest, NextResponse } from "next/server";
+import { decisions } from "project-arch";
+import { getProjectRoot } from "../../../lib/project-root";
+
+export const runtime = "nodejs";
+
+export async function POST(request: NextRequest) {
+  const root = getProjectRoot();
+  const body = (await request.json()) as {
+    scope?: "project" | "phase" | "milestone";
+    phase?: string;
+    milestone?: string;
+    slug?: string;
+    title?: string;
+  };
+  if (!body.scope || !["project", "phase", "milestone"].includes(body.scope)) {
+    return NextResponse.json(
+      { success: false, errors: ["scope must be one of: project, phase, milestone"] },
+      { status: 400 },
+    );
+  }
+  return NextResponse.json(await decisions.decisionCreate({ ...body, cwd: root }));
+}

package/templates/arch-ui/app/api/domain-docs/route.ts

@@ -0,0 +1,89 @@
+import { readdir } from "node:fs/promises";
+import path from "node:path";
+import { NextResponse } from "next/server";
+import { getProjectRoot, normalizePath } from "../../../lib/project-root";
+
+export const runtime = "nodejs";
+
+type DocScope = "arch-domains" | "arch-model" | "architecture" | "roadmap";
+
+function titleCase(value: string): string {
+  return value
+    .split(/\s+/)
+    .filter(Boolean)
+    .map((part) => part[0]?.toUpperCase() + part.slice(1).toLowerCase())
+    .join(" ");
+}
+
+function humanizeFileName(fileName: string): string {
+  const base = fileName.replace(/\.[a-z0-9]+$/i, "");
+  return titleCase(base.replace(/[_-]+/g, " "));
+}
+
+async function collectDocs(
+  root: string,
+  relativeDir: DocScope,
+  allowedExtensions: Set<string>,
+  maxDepth = 4,
+): Promise<
+  Array<{
+    id: string;
+    scope: DocScope;
+    file: string;
+    path: string;
+    title: string;
+  }>
+> {
+  const output: Array<{
+    id: string;
+    scope: DocScope;
+    file: string;
+    path: string;
+    title: string;
+  }> = [];
+  const baseDir = path.join(root, relativeDir);
+
+  async function walk(currentDir: string, depth: number): Promise<void> {
+    if (depth > maxDepth) return;
+    const entries = await readdir(currentDir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(fullPath, depth + 1);
+        continue;
+      }
+      const ext = path.extname(entry.name).toLowerCase();
+      if (!allowedExtensions.has(ext)) continue;
+      const relativePath = normalizePath(path.relative(root, fullPath));
+      output.push({
+        id: relativePath,
+        scope: relativeDir,
+        file: entry.name,
+        path: relativePath,
+        title: humanizeFileName(entry.name),
+      });
+    }
+  }
+
+  try {
+    await walk(baseDir, 0);
+  } catch {
+    return [];
+  }
+
+  return output.sort((a, b) => a.path.localeCompare(b.path));
+}
+
+export async function GET() {
+  const root = getProjectRoot();
+  const [domainDocs, modelDocs, architectureDocs, roadmapDocs] = await Promise.all([
+    collectDocs(root, "arch-domains", new Set([".md", ".json"]), 2),
+    collectDocs(root, "arch-model", new Set([".md", ".json"]), 2),
+    collectDocs(root, "architecture", new Set([".md", ".json"]), 6),
+    collectDocs(root, "roadmap", new Set([".md", ".json"]), 8),
+  ]);
+
+  return NextResponse.json({
+    docs: [...domainDocs, ...modelDocs, ...architectureDocs, ...roadmapDocs],
+  });
+}

package/templates/arch-ui/app/api/domains/route.ts

@@ -0,0 +1,10 @@
+import { NextResponse } from "next/server";
+import { readDomains } from "../../../lib/arch-model";
+import { getProjectRoot } from "../../../lib/project-root";
+
+export const runtime = "nodejs";
+
+export async function GET() {
+  const root = getProjectRoot();
+  return NextResponse.json(await readDomains(root));
+}

package/templates/arch-ui/app/api/graph/route.ts

@@ -0,0 +1,16 @@
+import { NextResponse } from "next/server";
+import { graph } from "project-arch";
+import { getProjectRoot } from "../../../lib/project-root";
+import { readArchitectureMap } from "../../../lib/arch-model";
+import { buildValidatedGraphDataset } from "../../../lib/graph-dataset";
+
+export const runtime = "nodejs";
+
+export async function GET() {
+  const root = getProjectRoot();
+  process.env.PROJECT_ROOT = root;
+  await graph.graphBuild();
+  const architectureMap = await readArchitectureMap(root);
+  const result = await buildValidatedGraphDataset(root, architectureMap);
+  return NextResponse.json(result);
+}

package/templates/arch-ui/app/api/health/route.ts

@@ -0,0 +1,44 @@
+import { NextResponse } from "next/server";
+import { check } from "project-arch";
+import { getProjectRoot } from "../../../lib/project-root";
+import { readArchitectureMap } from "../../../lib/arch-model";
+import { buildValidatedGraphDataset } from "../../../lib/graph-dataset";
+
+export const runtime = "nodejs";
+
+export async function GET() {
+  const root = getProjectRoot();
+  process.env.PROJECT_ROOT = root;
+  const [checkResult, architectureMap] = await Promise.all([check.checkRun(), readArchitectureMap(root)]);
+  const { validation } = await buildValidatedGraphDataset(root, architectureMap);
+
+  const graphErrors = validation.errors.map(
+    (issue) => `[graph:${issue.ruleId}] ${issue.message}`,
+  );
+  const graphWarnings = validation.warnings.map(
+    (issue) => `[graph:${issue.ruleId}] ${issue.message}`,
+  );
+
+  const maybeWrapped = checkResult as {
+    success?: boolean;
+    data?: { ok: boolean; errors: string[]; warnings: string[] };
+    errors?: string[];
+  };
+  const base =
+    maybeWrapped.data ??
+    ({
+      ok: true,
+      errors: maybeWrapped.errors ?? [],
+      warnings: [],
+    } as { ok: boolean; errors: string[]; warnings: string[] });
+
+  return NextResponse.json({
+    success: maybeWrapped.success ?? true,
+    data: {
+      ...base,
+      ok: base.ok && graphErrors.length === 0,
+      errors: [...base.errors, ...graphErrors],
+      warnings: [...base.warnings, ...graphWarnings],
+    },
+  });
+}