create-project-arch 1.0.0

package/templates/arch-ui/app/api/node-files/route.ts

@@ -0,0 +1,173 @@
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { NextRequest, NextResponse } from "next/server";
+import { getProjectRoot, normalizePath } from "../../../lib/project-root";
+
+export const runtime = "nodejs";
+
+type NodeType = "phase" | "milestone" | "task" | "domain" | "file";
+
+function isSafeSegment(value: string): boolean {
+  return /^[a-zA-Z0-9-]+$/.test(value);
+}
+
+async function collectFiles(
+  baseDir: string,
+  root: string,
+  skipDirs: Set<string>,
+  maxDepth = 2,
+): Promise<string[]> {
+  const output: string[] = [];
+
+  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()) {
+        if (skipDirs.has(entry.name)) continue;
+        await walk(fullPath, depth + 1);
+        continue;
+      }
+      output.push(normalizePath(path.relative(root, fullPath)));
+    }
+  }
+
+  try {
+    await walk(baseDir, 0);
+  } catch (error) {
+    if (
+      error &&
+      typeof error === "object" &&
+      "code" in error &&
+      (error as { code?: string }).code === "ENOENT"
+    ) {
+      return [];
+    }
+    throw error;
+  }
+  return output.sort((a, b) => a.localeCompare(b));
+}
+
+async function findTaskFile(root: string, taskId: string): Promise<string | null> {
+  const [phase, milestone, taskNumber] = taskId.split("/");
+  if (!phase || !milestone || !taskNumber) return null;
+  if (!isSafeSegment(phase) || !isSafeSegment(milestone) || !isSafeSegment(taskNumber)) return null;
+
+  const tasksDir = path.join(root, "roadmap", "phases", phase, "milestones", milestone, "tasks");
+  const lanes = ["planned", "discovered", "backlog", "complete"] as const;
+  for (const lane of lanes) {
+    const laneDir = path.join(tasksDir, lane);
+    try {
+      const files = await readdir(laneDir);
+      const candidate = files.find(
+        (file) => file.startsWith(`${taskNumber}-`) && file.endsWith(".md"),
+      );
+      if (candidate)
+        return normalizePath(
+          path.join("roadmap", "phases", phase, "milestones", milestone, "tasks", lane, candidate),
+        );
+    } catch {
+      // Continue.
+    }
+  }
+  return null;
+}
+
+async function resolveFilesForNode(root: string, type: NodeType, id: string): Promise<string[]> {
+  if (type === "task") {
+    const found = await findTaskFile(root, id);
+    return found ? [found] : [];
+  }
+
+  if (type === "file") {
+    const normalized = normalizePath(id).replace(/^\/+/, "");
+    const allowedRoots = ["arch-domains/", "arch-model/", "architecture/", "roadmap/"];
+    if (!allowedRoots.some((prefix) => normalized.startsWith(prefix))) {
+      return [];
+    }
+    const absolutePath = path.join(root, normalized);
+    const relativeRoundTrip = normalizePath(path.relative(root, absolutePath));
+    if (relativeRoundTrip !== normalized) {
+      return [];
+    }
+    try {
+      await readFile(absolutePath, "utf8");
+      return [normalized];
+    } catch {
+      return [];
+    }
+  }
+
+  if (type === "domain") {
+    const domainsDir = path.join(root, "arch-domains");
+    try {
+      const files = await readdir(domainsDir);
+      const markdownFiles = files.filter((file) => file.toLowerCase().endsWith(".md"));
+      if (markdownFiles.length === 0) return [];
+
+      const normalizedId = id.trim().toLowerCase();
+      const normalizedDashId = normalizedId.replace(/\//g, "-");
+      const slug = normalizedId
+        .replace(/[^a-z0-9/ -]/g, "")
+        .replace(/[ /]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+
+      const exactMatches = markdownFiles.filter((file) => {
+        const base = file.slice(0, -3).toLowerCase();
+        return base === normalizedId || base === normalizedDashId || base === slug;
+      });
+
+      const selected = exactMatches.length > 0 ? exactMatches : markdownFiles;
+      return selected
+        .map((file) => normalizePath(path.join("arch-domains", file)))
+        .sort((a, b) => a.localeCompare(b));
+    } catch {
+      return [];
+    }
+  }
+
+  if (type === "phase") {
+    const [phase] = id.split("/");
+    if (!phase || !isSafeSegment(phase)) return [];
+    const phaseDir = path.join(root, "roadmap", "phases", phase);
+    return collectFiles(phaseDir, root, new Set(["milestones", "tasks", "node_modules", ".git"]), 2);
+  }
+
+  const [phase, milestone] = id.split("/");
+  if (!phase || !milestone || !isSafeSegment(phase) || !isSafeSegment(milestone)) return [];
+  const milestoneDir = path.join(root, "roadmap", "phases", phase, "milestones", milestone);
+  return collectFiles(milestoneDir, root, new Set(["tasks", "node_modules", ".git"]), 3);
+}
+
+export async function GET(request: NextRequest) {
+  const root = getProjectRoot();
+  const type = request.nextUrl.searchParams.get("type") as NodeType | null;
+  const id = request.nextUrl.searchParams.get("id");
+
+  if (!type || !id) {
+    return NextResponse.json(
+      { success: false, errors: ["type and id query parameters are required"] },
+      { status: 400 },
+    );
+  }
+  if (!["phase", "milestone", "task", "domain", "file"].includes(type)) {
+    return NextResponse.json({ files: [] });
+  }
+
+  const files = await resolveFilesForNode(root, type, id);
+  const withContent = await Promise.all(
+    files.map(async (relativePath) => {
+      const absolutePath = path.join(root, relativePath);
+      const content = await readFile(absolutePath, "utf8");
+      return { path: relativePath, content };
+    }),
+  );
+
+  return NextResponse.json({
+    type,
+    id,
+    files: withContent,
+  });
+}

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

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

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

@@ -0,0 +1,22 @@
+import { NextResponse } from "next/server";
+
+export const runtime = "nodejs";
+
+export async function GET() {
+  return NextResponse.json({
+    service: "arch-api",
+    status: "ok",
+    endpoints: [
+      "GET /api/health",
+      "GET /api/graph",
+      "GET /api/architecture/map",
+      "GET /api/domains",
+      "GET /api/phases",
+      "GET /api/tasks",
+      "GET /api/trace/task/:taskId",
+      "GET /api/trace/file?path=<repoPath>",
+      "POST /api/tasks",
+      "POST /api/decisions",
+    ],
+  });
+}

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

@@ -0,0 +1,56 @@
+import { NextRequest, NextResponse } from "next/server";
+import { readArchitectureMap } from "../../../lib/arch-model";
+import { getProjectRoot } from "../../../lib/project-root";
+
+export const runtime = "nodejs";
+
+export async function GET(request: NextRequest) {
+  const root = getProjectRoot();
+  const query = (request.nextUrl.searchParams.get("q") ?? "").trim();
+  const lowerQuery = query.toLowerCase();
+  const map = await readArchitectureMap(root);
+
+  const results = [
+    ...map.nodes.tasks.map((task) => ({
+      id: `task:${task.id}`,
+      kind: "task" as const,
+      title: task.title,
+      subtitle: task.id,
+      route: "/work",
+    })),
+    ...map.nodes.decisions.map((decision) => ({
+      id: `decision:${decision.id}`,
+      kind: "decision" as const,
+      title: decision.title ?? decision.id,
+      subtitle: decision.id,
+      route: "/architecture?view=decisions",
+    })),
+    ...map.nodes.domains.map((domain) => ({
+      id: `domain:${domain.name}`,
+      kind: "domain" as const,
+      title: domain.name,
+      subtitle: domain.description,
+      route: "/architecture",
+    })),
+    ...map.nodes.modules.map((moduleRef) => ({
+      id: `module:${moduleRef.name}`,
+      kind: "module" as const,
+      title: moduleRef.name,
+      subtitle: moduleRef.type ?? "module",
+      route: "/architecture",
+    })),
+  ].filter((item) => {
+    if (!lowerQuery) return true;
+    return (
+      item.title.toLowerCase().includes(lowerQuery) ||
+      item.subtitle?.toLowerCase().includes(lowerQuery) ||
+      item.kind.toLowerCase().includes(lowerQuery)
+    );
+  });
+
+  return NextResponse.json({
+    query,
+    results: results.slice(0, 30),
+  });
+}
+

package/templates/arch-ui/app/api/task-doc/[taskId]/route.ts

@@ -0,0 +1,60 @@
+import { readdir, readFile } 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";
+
+const lanes = ["planned", "discovered", "backlog", "complete"] as const;
+
+function isSafeSegment(value: string): boolean {
+  return /^[a-zA-Z0-9-]+$/.test(value);
+}
+
+export async function GET(_: Request, context: { params: Promise<{ taskId: string }> }) {
+  const root = getProjectRoot();
+  const { taskId } = await context.params;
+  const decoded = decodeURIComponent(taskId);
+  const [phase, milestone, taskNumber] = decoded.split("/");
+
+  if (
+    !phase ||
+    !milestone ||
+    !taskNumber ||
+    !isSafeSegment(phase) ||
+    !isSafeSegment(milestone) ||
+    !isSafeSegment(taskNumber)
+  ) {
+    return NextResponse.json(
+      { success: false, errors: ["invalid task id; expected phase/milestone/task"] },
+      { status: 400 },
+    );
+  }
+
+  const tasksDir = path.join(root, "roadmap", "phases", phase, "milestones", milestone, "tasks");
+  for (const lane of lanes) {
+    const laneDir = path.join(tasksDir, lane);
+    try {
+      const files = await readdir(laneDir);
+      const candidate = files.find(
+        (file) => file.startsWith(`${taskNumber}-`) && file.endsWith(".md"),
+      );
+      if (!candidate) continue;
+      const fullPath = path.join(laneDir, candidate);
+      const markdown = await readFile(fullPath, "utf8");
+      return NextResponse.json({
+        id: decoded,
+        lane,
+        path: normalizePath(path.relative(root, fullPath)),
+        markdown,
+      });
+    } catch {
+      // Continue to other lanes.
+    }
+  }
+
+  return NextResponse.json(
+    { success: false, errors: [`task document not found for ${decoded}`] },
+    { status: 404 },
+  );
+}

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

@@ -0,0 +1,36 @@
+import { NextRequest, NextResponse } from "next/server";
+import { tasks } from "project-arch";
+import { readTasksNode } 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 readTasksNode(root));
+}
+
+export async function POST(request: NextRequest) {
+  const root = getProjectRoot();
+  const body = (await request.json()) as { phase?: string; milestone?: string; title?: string };
+  if (!body.phase || !body.milestone) {
+    return NextResponse.json(
+      { success: false, errors: ["phase and milestone are required"] },
+      { status: 400 },
+    );
+  }
+  if (body.title && typeof body.title !== "string") {
+    return NextResponse.json(
+      { success: false, errors: ["title must be a string"] },
+      { status: 400 },
+    );
+  }
+  return NextResponse.json(
+    await tasks.taskCreate({
+      phase: body.phase,
+      milestone: body.milestone,
+      title: body.title,
+      cwd: root,
+    }),
+  );
+}

package/templates/arch-ui/app/api/trace/file/route.ts

@@ -0,0 +1,40 @@
+import { NextRequest, NextResponse } from "next/server";
+import { graph } from "project-arch";
+import { readTaskToDecisionEdges, readTaskToModuleEdges } from "../../../../lib/arch-model";
+import { getProjectRoot, mapTargetToModule, normalizePath } from "../../../../lib/project-root";
+
+export const runtime = "nodejs";
+
+export async function GET(request: NextRequest) {
+  const root = getProjectRoot();
+  process.env.PROJECT_ROOT = root;
+  const filePath = request.nextUrl.searchParams.get("path");
+  if (!filePath) {
+    return NextResponse.json(
+      { success: false, errors: ["path query parameter is required"] },
+      { status: 400 },
+    );
+  }
+  await graph.graphBuild();
+  const moduleName = mapTargetToModule(filePath);
+  const taskEdges = await readTaskToModuleEdges(root);
+  const decisionEdges = await readTaskToDecisionEdges(root);
+  const tasksForModule = [
+    ...new Set(
+      taskEdges.edges.filter((edge) => edge.module === moduleName).map((edge) => edge.task),
+    ),
+  ];
+  const decisionsForModule = [
+    ...new Set(
+      decisionEdges.edges
+        .filter((edge) => tasksForModule.includes(edge.task))
+        .map((edge) => edge.decision),
+    ),
+  ];
+  return NextResponse.json({
+    file: normalizePath(filePath),
+    module: moduleName,
+    tasks: tasksForModule,
+    decisions: decisionsForModule,
+  });
+}

package/templates/arch-ui/app/api/trace/task/[taskId]/route.ts

@@ -0,0 +1,12 @@
+import { NextResponse } from "next/server";
+import { graph } from "project-arch";
+import { getProjectRoot } from "../../../../../lib/project-root";
+
+export const runtime = "nodejs";
+
+export async function GET(_: Request, context: { params: Promise<{ taskId: string }> }) {
+  const root = getProjectRoot();
+  process.env.PROJECT_ROOT = root;
+  const { taskId } = await context.params;
+  return NextResponse.json(await graph.graphTraceTask({ task: decodeURIComponent(taskId) }));
+}

package/templates/arch-ui/app/architecture/page.tsx

@@ -0,0 +1,5 @@
+import { redirect } from "next/navigation";
+
+export default function ArchitecturePage() {
+  redirect("/work?view=architecture");
+}

package/templates/arch-ui/app/globals.css

@@ -0,0 +1,240 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+:root {
+  color-scheme: dark;
+  --bg: #020617;
+  --panel: #0f172a;
+  --panel-2: #111827;
+  --border: #1e293b;
+  --border-strong: #334155;
+  --text: #e2e8f0;
+  --muted: #94a3b8;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+html,
+body {
+  margin: 0;
+  height: 100%;
+  background: radial-gradient(1300px 800px at 20% -10%, #0f172a, var(--bg));
+  color: var(--text);
+  font-family: 'IBM Plex Sans', 'Segoe UI', system-ui, sans-serif;
+}
+
+a {
+  color: inherit;
+  text-decoration: none;
+}
+
+.ui-card {
+  border-radius: 12px;
+  border: 1px solid var(--border-strong);
+  background: color-mix(in hsl, var(--panel) 90%, black);
+  box-shadow: 0 1px 0 #0005;
+  padding: 12px;
+}
+
+.ui-card-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  gap: 8px;
+  margin-bottom: 10px;
+}
+
+.ui-card-title {
+  margin: 0;
+  font-size: 15px;
+}
+
+.ui-card-description {
+  margin: 0;
+  color: var(--muted);
+}
+
+.ui-card-content {
+  display: grid;
+  gap: 10px;
+}
+
+.ui-btn {
+  border-radius: 10px;
+  border: 1px solid var(--border-strong);
+  padding: 8px 10px;
+  font-size: 13px;
+  cursor: pointer;
+  color: var(--text);
+}
+
+.ui-btn-default {
+  background: #1d4ed8;
+  border-color: #1d4ed8;
+}
+
+.ui-btn-secondary {
+  background: #374151;
+}
+
+.ui-btn-outline {
+  background: transparent;
+}
+
+.ui-btn-ghost {
+  background: transparent;
+  border-color: transparent;
+}
+
+.ui-badge {
+  border-radius: 999px;
+  padding: 3px 10px;
+  border: 1px solid var(--border-strong);
+  font-size: 12px;
+}
+
+.ui-badge-default {
+  background: #1e3a8a;
+}
+
+.ui-badge-secondary {
+  background: #5b21b6;
+}
+
+.ui-badge-success {
+  background: #14532d;
+}
+
+.ui-badge-warning {
+  background: #78350f;
+}
+
+.ui-badge-danger {
+  background: #7f1d1d;
+}
+
+.ui-input {
+  width: 100%;
+  border-radius: 10px;
+  border: 1px solid var(--border-strong);
+  background: #020617;
+  color: var(--text);
+  padding: 8px 10px;
+}
+
+.ui-table {
+  width: 100%;
+  border-collapse: collapse;
+}
+
+.ui-table-head,
+.ui-table-cell {
+  text-align: left;
+  padding: 8px;
+  border-bottom: 1px solid var(--border);
+}
+
+.ui-table-row:hover {
+  background: #111827;
+}
+
+.ui-code {
+  font-family: 'IBM Plex Mono', ui-monospace, Menlo, Monaco, monospace;
+  background: #020617;
+  border: 1px solid var(--border-strong);
+  border-radius: 6px;
+  padding: 2px 6px;
+  font-size: 12px;
+}
+
+.ui-command {
+  display: grid;
+  gap: 10px;
+}
+
+.ui-command-list {
+  max-height: 240px;
+  overflow: auto;
+  display: grid;
+  gap: 6px;
+}
+
+.ui-command-item {
+  text-align: left;
+  border: 1px solid var(--border-strong);
+  border-radius: 8px;
+  background: #020617;
+  color: var(--text);
+  padding: 8px 10px;
+  cursor: pointer;
+}
+
+.ui-command-item:hover {
+  background: #1f2937;
+}
+
+.ui-tabs-list,
+.ui-toggle-group {
+  display: flex;
+  gap: 8px;
+  flex-wrap: wrap;
+}
+
+.ui-tabs-trigger,
+.ui-toggle-item {
+  border: 1px solid var(--border-strong);
+  border-radius: 10px;
+  background: #020617;
+  color: var(--text);
+  padding: 7px 10px;
+  cursor: pointer;
+}
+
+.ui-separator {
+  border: 0;
+  border-top: 1px solid var(--border);
+}
+
+.ui-scroll-area {
+  overflow: auto;
+}
+
+.ui-skeleton {
+  border-radius: 8px;
+  background: linear-gradient(90deg, #111827 0, #1f2937 50%, #111827 100%);
+  background-size: 200% 100%;
+  animation: shimmer 1.4s infinite;
+  height: 20px;
+}
+
+@keyframes shimmer {
+  from {
+    background-position: 200% 0;
+  }
+
+  to {
+    background-position: -200% 0;
+  }
+}
+
+.ui-dropdown,
+.ui-accordion,
+.ui-nav-menu {
+  display: grid;
+  gap: 6px;
+}
+
+.ui-dropdown-item {
+  font-size: 12px;
+  color: var(--muted);
+}
+
+.ui-accordion-item {
+  border: 1px solid var(--border-strong);
+  border-radius: 10px;
+  padding: 8px;
+  background: #020617;
+}