create-project-arch 1.0.0

package/templates/arch-ui/components/topbar.tsx

@@ -0,0 +1,187 @@
+"use client";
+
+import { Badge } from "@repo/ui/badge";
+import { Button } from "@repo/ui/button";
+import { Command, CommandInput, CommandItem, CommandList } from "@repo/ui/command";
+import { Input } from "@repo/ui/input";
+import { usePathname, useRouter, useSearchParams } from "next/navigation";
+import { useEffect, useMemo, useState } from "react";
+import { getHealth, searchWorkspace } from "../lib/api";
+import { SearchResultItem } from "../lib/types";
+import { useInspector } from "./inspector-context";
+import { useWorkspace } from "./workspace-context";
+
+type HealthState = "OK" | "Warning" | "Drift";
+
+const staticCommands = [
+  { id: "architecture", label: "Open Architecture Map", route: "/work?view=architecture" },
+  { id: "work", label: "Open Tasks View", route: "/work?view=tasks" },
+  { id: "project", label: "Open Project View", route: "/work?view=project" },
+  { id: "health", label: "Open Health", route: "/health" },
+  { id: "search-task", label: "Open Tasks", route: "/work?view=tasks" },
+  { id: "trace-file", label: "Trace File", route: "/health?view=trace" },
+  { id: "open-domain", label: "Open Domain View", route: "/work?view=architecture" },
+] as const;
+
+export function Topbar({ projectName }: { projectName: string }) {
+  const [query, setQuery] = useState("");
+  const [paletteOpen, setPaletteOpen] = useState(false);
+  const [health, setHealth] = useState<HealthState>("OK");
+  const [searchResults, setSearchResults] = useState<SearchResultItem[]>([]);
+  const router = useRouter();
+  const pathname = usePathname();
+  const searchParams = useSearchParams();
+  const { selection } = useInspector();
+  const { splitPane, setSplitPane, rightCollapsed, setRightCollapsed, resetLayout } = useWorkspace();
+
+  useEffect(() => {
+    function onKeyDown(event: KeyboardEvent) {
+      if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === "k") {
+        event.preventDefault();
+        setPaletteOpen((prev) => !prev);
+      }
+    }
+
+    window.addEventListener("keydown", onKeyDown);
+    return () => window.removeEventListener("keydown", onKeyDown);
+  }, []);
+
+  useEffect(() => {
+    const timeout = window.setTimeout(() => {
+      void searchWorkspace(query)
+        .then((result) => setSearchResults(result.results))
+        .catch(() => setSearchResults([]));
+    }, 140);
+    return () => window.clearTimeout(timeout);
+  }, [query]);
+
+  useEffect(() => {
+    void getHealth()
+      .then((result) => {
+        if (!result.ok) {
+          setHealth("Drift");
+          return;
+        }
+        if (result.warnings.length > 0) {
+          setHealth("Warning");
+          return;
+        }
+        setHealth("OK");
+      })
+      .catch(() => setHealth("Drift"));
+  }, []);
+
+  const filteredCommands = useMemo(() => {
+    if (!query) return staticCommands;
+    const q = query.toLowerCase();
+    return staticCommands.filter((entry) => entry.label.toLowerCase().includes(q));
+  }, [query]);
+
+  const breadcrumbs = useMemo(() => {
+    const pathLabel =
+      pathname === "/work"
+          ? "Work Graph"
+          : pathname === "/health"
+            ? "Health"
+            : "Workspace";
+    const view = searchParams.get("view");
+    const secondary =
+      view === "docs"
+        ? "Repository Docs"
+        : view === "decisions"
+          ? "Decisions"
+          : view === "architecture"
+            ? "Architecture"
+          : view === "project"
+            ? "Project"
+          : view === "tasks"
+            ? "Tasks"
+            : "Map";
+
+    const parts = [pathLabel];
+    if (pathname === "/work") parts.push(secondary);
+    if (selection?.title) parts.push(selection.title);
+    return parts.join(" > ");
+  }, [pathname, searchParams, selection?.title]);
+
+  return (
+    <header className="grid items-center gap-3 border-b border-slate-800 px-4 py-2 xl:grid-cols-[auto_1fr_auto]">
+      <div>
+        <p className="m-0 text-[11px] uppercase tracking-[0.1em] text-slate-400">Project</p>
+        <p className="m-0 text-base font-semibold">{projectName}</p>
+        <p className="mt-0.5 text-xs leading-tight text-slate-400">{breadcrumbs}</p>
+      </div>
+
+      <div className="flex items-center gap-2">
+        <Input
+          placeholder="Search task, file, decision..."
+          value={query}
+          onChange={(event) => setQuery(event.target.value)}
+          onFocus={() => setPaletteOpen(true)}
+        />
+        <Button type="button" variant="outline" onClick={() => setPaletteOpen((prev) => !prev)}>
+          ⌘K
+        </Button>
+      </div>
+
+      <div className="flex flex-wrap gap-2">
+        <Button type="button" variant="outline" onClick={() => setSplitPane(!splitPane)}>
+          {splitPane ? "Single Pane" : "Split Pane"}
+        </Button>
+        <Button type="button" variant="outline" onClick={() => setRightCollapsed(!rightCollapsed)}>
+          {rightCollapsed ? "Show Inspector" : "Hide Inspector"}
+        </Button>
+        <Button type="button" variant="ghost" onClick={resetLayout}>
+          Reset Layout
+        </Button>
+        <Badge variant={health === "OK" ? "success" : health === "Warning" ? "warning" : "danger"}>
+          Health: {health}
+        </Badge>
+      </div>
+
+      {paletteOpen ? (
+        <div
+          className="fixed inset-0 z-50 grid place-items-start bg-black/60 pt-[14vh]"
+          role="presentation"
+          onClick={() => setPaletteOpen(false)}
+        >
+          <Command
+            className="w-[min(680px,90vw)] rounded-2xl border border-slate-600 bg-slate-950 p-3"
+            onClick={(event) => event.stopPropagation()}
+          >
+            <CommandInput
+              placeholder="Type a command"
+              value={query}
+              onChange={(event) => setQuery(event.target.value)}
+              autoFocus
+            />
+            <CommandList>
+              {searchResults.map((entry) => (
+                <CommandItem
+                  key={entry.id}
+                  onClick={() => {
+                    router.push(entry.route);
+                    setPaletteOpen(false);
+                  }}
+                >
+                  {entry.kind}: {entry.title}
+                </CommandItem>
+              ))}
+              {filteredCommands.map((entry) => (
+                <CommandItem
+                  key={entry.id}
+                  onClick={() => {
+                    router.push(entry.route);
+                    setPaletteOpen(false);
+                  }}
+                >
+                  {entry.label}
+                </CommandItem>
+              ))}
+            </CommandList>
+          </Command>
+        </div>
+      ) : null}
+    </header>
+  );
+}

package/templates/arch-ui/components/work-table.tsx

@@ -0,0 +1,57 @@
+"use client";
+
+import { Badge } from "@repo/ui/badge";
+import { Code } from "@repo/ui/code";
+import { DropdownMenu, DropdownMenuItem } from "@repo/ui/dropdown-menu";
+import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@repo/ui/table";
+import { TaskNode } from "../lib/types";
+
+function statusVariant(status: string): "default" | "secondary" | "success" {
+  if (status === "complete") return "success";
+  if (status === "discovered") return "secondary";
+  return "default";
+}
+
+type WorkTableProps = {
+  tasks: TaskNode[];
+  onSelectTask: (task: TaskNode) => void;
+};
+
+export function WorkTable({ tasks, onSelectTask }: WorkTableProps) {
+  return (
+    <Table>
+      <TableHeader>
+        <TableRow>
+          <TableHead>ID</TableHead>
+          <TableHead>Title</TableHead>
+          <TableHead>Status</TableHead>
+          <TableHead>Domain</TableHead>
+          <TableHead>Files</TableHead>
+        </TableRow>
+      </TableHeader>
+      <TableBody>
+        {tasks.map((task) => (
+          <TableRow
+            className="cursor-pointer"
+            key={task.id}
+            onClick={() => onSelectTask(task)}
+          >
+            <TableCell>
+              <Code>{task.id}</Code>
+            </TableCell>
+            <TableCell>{task.title}</TableCell>
+            <TableCell>
+              <Badge variant={statusVariant(task.lane)}>{task.lane}</Badge>
+            </TableCell>
+            <TableCell>{task.domain ?? "foundation"}</TableCell>
+            <TableCell>
+              <DropdownMenu>
+                <DropdownMenuItem>Open Trace</DropdownMenuItem>
+              </DropdownMenu>
+            </TableCell>
+          </TableRow>
+        ))}
+      </TableBody>
+    </Table>
+  );
+}

package/templates/arch-ui/components/workspace-context.tsx

@@ -0,0 +1,274 @@
+"use client";
+
+import { usePathname, useSearchParams } from "next/navigation";
+import { createContext, ReactNode, useContext, useEffect, useMemo, useState } from "react";
+import { GraphViewMode } from "../lib/graph-schema";
+
+export type WorkspaceView = "architecture-map" | "decisions" | "tasks-roadmap" | "project-map";
+export type GraphNodeFilter = "domains" | "modules" | "tasks" | "decisions";
+export type GraphEdgeFilter = "dependency" | "data-flow" | "blocking";
+export type GraphAuthorityFilter = "authoritative" | "manual" | "inferred";
+
+type WorkspaceFilters = {
+  nodeTypes: Record<GraphNodeFilter, boolean>;
+  edgeTypes: Record<GraphEdgeFilter, boolean>;
+  authorityTypes: Record<GraphAuthorityFilter, boolean>;
+  hideCompletedTasks: boolean;
+  showExternalDependencies: boolean;
+  hopDepth: number;
+};
+
+type WorkspacePersistedState = {
+  splitPane: boolean;
+  leftCollapsed: boolean;
+  rightCollapsed: boolean;
+  leftWidth: number;
+  rightWidth: number;
+  filtersByView: Record<GraphViewMode, WorkspaceFilters>;
+};
+
+type WorkspaceContextValue = {
+  splitPane: boolean;
+  leftCollapsed: boolean;
+  rightCollapsed: boolean;
+  leftWidth: number;
+  rightWidth: number;
+  filters: WorkspaceFilters;
+  setSplitPane: (next: boolean) => void;
+  setLeftCollapsed: (next: boolean) => void;
+  setRightCollapsed: (next: boolean) => void;
+  setLeftWidth: (next: number) => void;
+  setRightWidth: (next: number) => void;
+  toggleNodeType: (filter: GraphNodeFilter) => void;
+  toggleEdgeType: (filter: GraphEdgeFilter) => void;
+  toggleAuthorityType: (filter: GraphAuthorityFilter) => void;
+  setHideCompletedTasks: (next: boolean) => void;
+  setShowExternalDependencies: (next: boolean) => void;
+  setHopDepth: (next: number) => void;
+  resetLayout: () => void;
+};
+
+const DEFAULT_LEFT_WIDTH = 280;
+const DEFAULT_RIGHT_WIDTH = 420;
+const STORAGE_KEY = "arch:workspace:v1";
+
+const WorkspaceContext = createContext<WorkspaceContextValue | null>(null);
+
+function clamp(value: number, min: number, max: number) {
+  return Math.max(min, Math.min(max, value));
+}
+
+function defaultFilters(): WorkspaceFilters {
+  return {
+    nodeTypes: {
+      domains: true,
+      modules: true,
+      tasks: true,
+      decisions: true,
+    },
+    edgeTypes: {
+      dependency: true,
+      "data-flow": true,
+      blocking: true,
+    },
+    authorityTypes: {
+      authoritative: true,
+      manual: true,
+      inferred: true,
+    },
+    hideCompletedTasks: false,
+    showExternalDependencies: false,
+    hopDepth: 1,
+  };
+}
+
+function resolveActiveGraphView(pathname: string, searchParams: URLSearchParams): GraphViewMode {
+  if (pathname === "/work" && searchParams.get("view") === "project") return "project";
+  if (pathname === "/work" && searchParams.get("view") === "architecture") return "architecture-map";
+  if (pathname === "/work") return "tasks";
+  return "architecture-map";
+}
+
+export function WorkspaceProvider({ children }: { children: ReactNode }) {
+  const pathname = usePathname();
+  const searchParams = useSearchParams();
+  const activeGraphView = useMemo(
+    () => resolveActiveGraphView(pathname, searchParams),
+    [pathname, searchParams],
+  );
+  const [splitPane, setSplitPane] = useState(false);
+  const [leftCollapsed, setLeftCollapsed] = useState(false);
+  const [rightCollapsed, setRightCollapsed] = useState(false);
+  const [leftWidth, setLeftWidth] = useState(DEFAULT_LEFT_WIDTH);
+  const [rightWidth, setRightWidth] = useState(DEFAULT_RIGHT_WIDTH);
+  const [filtersByView, setFiltersByView] = useState<Record<GraphViewMode, WorkspaceFilters>>({
+    "architecture-map": defaultFilters(),
+    tasks: defaultFilters(),
+    project: defaultFilters(),
+  });
+
+  useEffect(() => {
+    try {
+      const raw = window.localStorage.getItem(STORAGE_KEY);
+      if (!raw) return;
+      const parsed = JSON.parse(raw) as Partial<{
+        splitPane: boolean;
+        leftCollapsed: boolean;
+        rightCollapsed: boolean;
+        leftWidth: number;
+        rightWidth: number;
+        filtersByView: Partial<Record<GraphViewMode, Partial<WorkspaceFilters>>>;
+      }>;
+      if (typeof parsed.splitPane === "boolean") setSplitPane(parsed.splitPane);
+      if (typeof parsed.leftCollapsed === "boolean") setLeftCollapsed(parsed.leftCollapsed);
+      if (typeof parsed.rightCollapsed === "boolean") setRightCollapsed(parsed.rightCollapsed);
+      if (typeof parsed.leftWidth === "number") setLeftWidth(clamp(parsed.leftWidth, 220, 520));
+      if (typeof parsed.rightWidth === "number") setRightWidth(clamp(parsed.rightWidth, 320, 720));
+      if (parsed.filtersByView) {
+        const views: GraphViewMode[] = ["architecture-map", "tasks", "project"];
+        const nextByView = { ...filtersByView };
+        for (const view of views) {
+          const incoming = parsed.filtersByView[view];
+          if (!incoming) continue;
+          const base = defaultFilters();
+          nextByView[view] = {
+            nodeTypes: {
+              domains: incoming.nodeTypes?.domains ?? base.nodeTypes.domains,
+              modules: incoming.nodeTypes?.modules ?? base.nodeTypes.modules,
+              tasks: incoming.nodeTypes?.tasks ?? base.nodeTypes.tasks,
+              decisions: incoming.nodeTypes?.decisions ?? base.nodeTypes.decisions,
+            },
+            edgeTypes: {
+              dependency: incoming.edgeTypes?.dependency ?? base.edgeTypes.dependency,
+              "data-flow": incoming.edgeTypes?.["data-flow"] ?? base.edgeTypes["data-flow"],
+              blocking: incoming.edgeTypes?.blocking ?? base.edgeTypes.blocking,
+            },
+            authorityTypes: {
+              authoritative:
+                incoming.authorityTypes?.authoritative ?? base.authorityTypes.authoritative,
+              manual: incoming.authorityTypes?.manual ?? base.authorityTypes.manual,
+              inferred: incoming.authorityTypes?.inferred ?? base.authorityTypes.inferred,
+            },
+            hideCompletedTasks: incoming.hideCompletedTasks ?? base.hideCompletedTasks,
+            showExternalDependencies:
+              incoming.showExternalDependencies ?? base.showExternalDependencies,
+            hopDepth: clamp(incoming.hopDepth ?? base.hopDepth, 0, 3),
+          };
+        }
+        setFiltersByView(nextByView);
+      }
+    } catch {
+      // Ignore invalid persisted state.
+    }
+  }, []);
+
+  useEffect(() => {
+    const payload = JSON.stringify({
+      splitPane,
+      leftCollapsed,
+      rightCollapsed,
+      leftWidth,
+      rightWidth,
+      filtersByView,
+    });
+    window.localStorage.setItem(STORAGE_KEY, payload);
+  }, [filtersByView, leftCollapsed, leftWidth, rightCollapsed, rightWidth, splitPane]);
+
+  const filters = filtersByView[activeGraphView] ?? defaultFilters();
+
+  const value = useMemo<WorkspaceContextValue>(
+    () => ({
+      splitPane,
+      leftCollapsed,
+      rightCollapsed,
+      leftWidth,
+      rightWidth,
+      filters,
+      setSplitPane,
+      setLeftCollapsed,
+      setRightCollapsed,
+      setLeftWidth: (next) => setLeftWidth(clamp(next, 220, 520)),
+      setRightWidth: (next) => setRightWidth(clamp(next, 320, 720)),
+      toggleNodeType: (filter) =>
+        setFiltersByView((prev) => ({
+          ...prev,
+          [activeGraphView]: {
+            ...prev[activeGraphView],
+            nodeTypes: {
+              ...prev[activeGraphView].nodeTypes,
+              [filter]: !prev[activeGraphView].nodeTypes[filter],
+            },
+          },
+        })),
+      toggleEdgeType: (filter) =>
+        setFiltersByView((prev) => ({
+          ...prev,
+          [activeGraphView]: {
+            ...prev[activeGraphView],
+            edgeTypes: {
+              ...prev[activeGraphView].edgeTypes,
+              [filter]: !prev[activeGraphView].edgeTypes[filter],
+            },
+          },
+        })),
+      toggleAuthorityType: (filter) =>
+        setFiltersByView((prev) => ({
+          ...prev,
+          [activeGraphView]: {
+            ...prev[activeGraphView],
+            authorityTypes: {
+              ...prev[activeGraphView].authorityTypes,
+              [filter]: !prev[activeGraphView].authorityTypes[filter],
+            },
+          },
+        })),
+      setHideCompletedTasks: (next) =>
+        setFiltersByView((prev) => ({
+          ...prev,
+          [activeGraphView]: {
+            ...prev[activeGraphView],
+            hideCompletedTasks: next,
+          },
+        })),
+      setShowExternalDependencies: (next) =>
+        setFiltersByView((prev) => ({
+          ...prev,
+          [activeGraphView]: {
+            ...prev[activeGraphView],
+            showExternalDependencies: next,
+          },
+        })),
+      setHopDepth: (next) =>
+        setFiltersByView((prev) => ({
+          ...prev,
+          [activeGraphView]: {
+            ...prev[activeGraphView],
+            hopDepth: clamp(next, 0, 3),
+          },
+        })),
+      resetLayout: () => {
+        setSplitPane(false);
+        setLeftCollapsed(false);
+        setRightCollapsed(false);
+        setLeftWidth(DEFAULT_LEFT_WIDTH);
+        setRightWidth(DEFAULT_RIGHT_WIDTH);
+        setFiltersByView({
+          "architecture-map": defaultFilters(),
+          tasks: defaultFilters(),
+          project: defaultFilters(),
+        });
+      },
+    }),
+    [activeGraphView, filters, leftCollapsed, leftWidth, rightCollapsed, rightWidth, splitPane],
+  );
+
+  return <WorkspaceContext.Provider value={value}>{children}</WorkspaceContext.Provider>;
+}
+
+export function useWorkspace() {
+  const value = useContext(WorkspaceContext);
+  if (!value) {
+    throw new Error("useWorkspace must be used within WorkspaceProvider");
+  }
+  return value;
+}

package/templates/arch-ui/eslint.config.js

@@ -0,0 +1,2 @@
+import { config } from '@repo/eslint-config/next-js';
+export default config;

package/templates/arch-ui/global.d.ts

@@ -0,0 +1 @@
+declare module "*.css";

package/templates/arch-ui/lib/api.ts

@@ -0,0 +1,93 @@
+import {
+  ApiResult,
+  ArchitectureMapData,
+  CheckData,
+  DomainDocsData,
+  FileTraceData,
+  GraphDatasetResponse,
+  NodeFilesData,
+  PhaseListData,
+  SearchResultData,
+  TaskDocumentData,
+  TaskNode,
+  TaskTraceData,
+} from "./types";
+
+async function readJson<T>(input: RequestInfo | URL, init?: RequestInit): Promise<T> {
+  const response = await fetch(input, init);
+  if (!response.ok) {
+    throw new Error(`${response.status} ${response.statusText}`);
+  }
+  return (await response.json()) as T;
+}
+
+function unwrap<T>(value: ApiResult<T> | T): T {
+  if (typeof value === "object" && value !== null && "success" in value) {
+    const result = value as ApiResult<T>;
+    if (result.success === false) {
+      throw new Error(result.errors?.join("; ") ?? "Request failed");
+    }
+    if (result.data === undefined) {
+      throw new Error("Missing data payload");
+    }
+    return result.data;
+  }
+  return value as T;
+}
+
+export async function getHealth(): Promise<CheckData> {
+  return unwrap(await readJson<ApiResult<CheckData>>("/api/health"));
+}
+
+export async function getArchitectureMap(): Promise<ArchitectureMapData> {
+  return await readJson<ArchitectureMapData>("/api/architecture/map");
+}
+
+export async function getDomains(): Promise<{
+  domains: Array<{ name: string; description?: string; ownedPackages?: string[] }>;
+}> {
+  return await readJson<{
+    domains: Array<{ name: string; description?: string; ownedPackages?: string[] }>;
+  }>("/api/domains");
+}
+
+export async function getPhases(): Promise<PhaseListData> {
+  return unwrap(await readJson<ApiResult<PhaseListData>>("/api/phases"));
+}
+
+export async function getTasks(): Promise<{ tasks: TaskNode[] }> {
+  return await readJson<{ tasks: TaskNode[] }>("/api/tasks");
+}
+
+export async function getTaskTrace(taskId: string): Promise<TaskTraceData> {
+  return await readJson<TaskTraceData>(`/api/trace/task/${encodeURIComponent(taskId)}`);
+}
+
+export async function getFileTrace(filePath: string): Promise<FileTraceData> {
+  return await readJson<FileTraceData>(`/api/trace/file?path=${encodeURIComponent(filePath)}`);
+}
+
+export async function getTaskDocument(taskId: string): Promise<TaskDocumentData> {
+  return await readJson<TaskDocumentData>(`/api/task-doc/${encodeURIComponent(taskId)}`);
+}
+
+export async function getNodeFiles(
+  type: "phase" | "milestone" | "task" | "domain" | "file",
+  id: string,
+): Promise<NodeFilesData> {
+  return await readJson<NodeFilesData>(
+    `/api/node-files?type=${encodeURIComponent(type)}&id=${encodeURIComponent(id)}`,
+  );
+}
+
+export async function searchWorkspace(query: string): Promise<SearchResultData> {
+  return await readJson<SearchResultData>(`/api/search?q=${encodeURIComponent(query)}`);
+}
+
+export async function getDomainDocs(): Promise<DomainDocsData> {
+  return await readJson<DomainDocsData>("/api/domain-docs");
+}
+
+export async function getGraphDataset(): Promise<GraphDatasetResponse> {
+  return await readJson<GraphDatasetResponse>("/api/graph");
+}