@acta-dev/web 1.0.0

package/src/lib/project.test.ts

@@ -0,0 +1,24 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { findActaRoot, getActaConfigPath } from "./project.js";
+
+describe("web project utilities", () => {
+  it("finds the nearest parent directory containing acta.config.ts", async () => {
+    const root = join(tmpdir(), `acta-web-${crypto.randomUUID()}`);
+    const nested = join(root, "apps", "web", "src");
+    await mkdir(nested, { recursive: true });
+    await writeFile(join(root, "acta.config.ts"), "export default {};\n", "utf8");
+
+    await expect(findActaRoot(nested)).resolves.toBe(root);
+    await expect(getActaConfigPath(nested)).resolves.toBe(join(root, "acta.config.ts"));
+  });
+
+  it("throws a clear error when no Acta config exists in parent directories", async () => {
+    const root = join(tmpdir(), `acta-web-${crypto.randomUUID()}`);
+    await mkdir(root, { recursive: true });
+
+    await expect(findActaRoot(root)).rejects.toThrow("Could not find acta.config.ts");
+  });
+});

package/src/lib/project.ts

@@ -0,0 +1,120 @@
+import { access, readFile } from "node:fs/promises";
+import { dirname, join, parse, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import type {
+  ActaDocument,
+  DocumentGraph,
+  DocumentOrdering,
+  ValidationResult,
+} from "@acta-dev/core";
+import { sortDocumentsByNewest } from "./documents.js";
+
+export interface ActaWebProject {
+  documents: ActaDocument[];
+  graph: DocumentGraph;
+  ordering: DocumentOrdering;
+}
+
+export interface ActaWebData {
+  project: ActaWebProject;
+  validation: ValidationResult;
+}
+
+let cachedData: Promise<ActaWebData> | undefined;
+
+export async function loadActaWebData(distDir?: string): Promise<ActaWebData> {
+  cachedData ??= loadUncachedActaWebData(distDir);
+  return cachedData;
+}
+
+/**
+ * Resolve the directory holding the `acta build` artifacts.
+ *
+ * Precedence:
+ *  1. explicit argument (used by tests),
+ *  2. `ACTA_DIST_DIR` env (set by `acta site` when building outside the monorepo),
+ *  3. `<ACTA_PROJECT_ROOT|findActaRoot()>/.acta/dist` (monorepo dev fallback).
+ */
+export async function resolveDistDir(distDir?: string): Promise<string> {
+  if (distDir) {
+    return resolve(distDir);
+  }
+
+  if (process.env.ACTA_DIST_DIR) {
+    return resolve(process.env.ACTA_DIST_DIR);
+  }
+
+  const root = process.env.ACTA_PROJECT_ROOT
+    ? resolve(process.env.ACTA_PROJECT_ROOT)
+    : await findActaRoot();
+
+  return join(root, ".acta", "dist");
+}
+
+export async function findActaRoot(startDir = defaultStartDir()): Promise<string> {
+  let current = resolve(startDir);
+  const root = parse(current).root;
+
+  while (true) {
+    const configPath = join(current, "acta.config.ts");
+    if (await exists(configPath)) {
+      return current;
+    }
+
+    if (current === root) {
+      throw new Error(`Could not find acta.config.ts from ${startDir}`);
+    }
+
+    current = dirname(current);
+  }
+}
+
+export async function getActaConfigPath(startDir = defaultStartDir()): Promise<string> {
+  return join(await findActaRoot(startDir), "acta.config.ts");
+}
+
+async function loadUncachedActaWebData(distDir?: string): Promise<ActaWebData> {
+  const dir = await resolveDistDir(distDir);
+
+  const [documents, graph, ordering, validation] = await Promise.all([
+    readArtifact<ActaDocument[]>(dir, "documents.json"),
+    readArtifact<DocumentGraph>(dir, "graph.json"),
+    readArtifact<DocumentOrdering>(dir, "ordering.json"),
+    readArtifact<ValidationResult>(dir, "validation.json"),
+  ]);
+
+  return {
+    project: {
+      documents: sortDocumentsByNewest(documents),
+      graph,
+      ordering,
+    },
+    validation,
+  };
+}
+
+async function readArtifact<T>(dir: string, file: string): Promise<T> {
+  const path = join(dir, file);
+
+  try {
+    return JSON.parse(await readFile(path, "utf8")) as T;
+  } catch (cause) {
+    throw new Error(
+      `Could not read Acta artifact ${path}. Run \`acta build\` before building the site.`,
+      { cause },
+    );
+  }
+}
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function defaultStartDir(): string {
+  return dirname(fileURLToPath(import.meta.url));
+}

package/src/lib/search-client.ts

@@ -0,0 +1,192 @@
+import {
+  buildSearchUrl,
+  getQueryFromUrl,
+  searchDocuments,
+  updateQueryInUrl,
+  type WebSearchFilters,
+  type WebSearchIndexArtifact,
+} from "./search.js";
+
+let searchIndexPromise: Promise<WebSearchIndexArtifact> | undefined;
+let fullSearchIndexPromise: Promise<WebSearchIndexArtifact> | undefined;
+
+export function initDocumentSearch(root: HTMLElement): void {
+  const searchInput = root.querySelector<HTMLInputElement>("[data-search-query]");
+  const kindSelect = root.querySelector<HTMLSelectElement>("[data-filter-kind]");
+  const statusSelect = root.querySelector<HTMLSelectElement>("[data-filter-status]");
+  const tagSelect = root.querySelector<HTMLSelectElement>("[data-filter-tag]");
+  const componentSelect = root.querySelector<HTMLSelectElement>("[data-filter-component]");
+  const sortInputs = Array.from(root.querySelectorAll<HTMLInputElement>("[data-sort-order]"));
+  const contentSearchInput = root.querySelector<HTMLInputElement>("[data-search-content]");
+  const contentLoading = root.querySelector<HTMLElement>("[data-search-content-loading]");
+  const documentList = root.querySelector<HTMLElement>("[data-document-list]");
+  const showMoreButton = root.querySelector<HTMLButtonElement>("[data-show-more]");
+  const rows = Array.from(root.querySelectorAll<HTMLElement>("[data-document-row]"));
+  const emptyState = root.querySelector<HTMLElement>("[data-empty-state]");
+  const searchLink = root.querySelector<HTMLAnchorElement>("[data-search-link]");
+
+  if (
+    !searchInput ||
+    !kindSelect ||
+    !statusSelect ||
+    !tagSelect ||
+    !componentSelect ||
+    !contentSearchInput ||
+    sortInputs.length === 0 ||
+    !documentList ||
+    !showMoreButton ||
+    !emptyState
+  ) {
+    throw new Error("Document search controls failed to initialize.");
+  }
+
+  const search = searchInput;
+  const kindFilter = kindSelect;
+  const statusFilter = statusSelect;
+  const tagFilter = tagSelect;
+  const componentFilter = componentSelect;
+  const contentSearch = contentSearchInput;
+  const loading = contentLoading;
+  const list = documentList;
+  const showMore = showMoreButton;
+  const empty = emptyState;
+  const rowsById = new Map(rows.map((row) => [row.dataset.documentId ?? "", row]));
+  const pageSize = Number.parseInt(list.dataset.pageSize ?? "20", 10);
+  const increment = Number.isFinite(pageSize) && pageSize > 0 ? pageSize : 20;
+  let visibleLimit = increment;
+  let currentMatchingCount = rows.length;
+  let updateSequence = 0;
+
+  search.value = getQueryFromUrl(window.location.href);
+
+  function filters(): WebSearchFilters {
+    return {
+      kind: kindFilter.value,
+      status: statusFilter.value,
+      tag: tagFilter.value,
+      component: componentFilter.value,
+    };
+  }
+
+  function selectedSortOrder(): "newest" | "dependency" {
+    return sortInputs.find((input) => input.checked)?.value === "dependency"
+      ? "dependency"
+      : "newest";
+  }
+
+  function syncQueryUrl() {
+    const nextUrl = updateQueryInUrl(window.location.href, search.value);
+    history.replaceState(history.state, "", `${nextUrl.pathname}${nextUrl.search}${nextUrl.hash}`);
+    if (searchLink) {
+      searchLink.href = buildSearchUrl(search.value);
+    }
+  }
+
+  async function matchingRows(): Promise<HTMLElement[]> {
+    const query = search.value.trim();
+
+    if (query.length > 0) {
+      const includeContent = contentSearch.checked || query.length > 2;
+      if (loading) {
+        loading.hidden = !includeContent || fullSearchIndexPromise !== undefined;
+      }
+      const ids = await searchDocuments(await loadSearchIndex(includeContent), query, filters());
+      if (loading) {
+        loading.hidden = true;
+      }
+      return ids.map((id) => rowsById.get(id)).filter((row) => row !== undefined);
+    }
+
+    const orderKey = selectedSortOrder() === "dependency" ? "dependencyOrder" : "newestOrder";
+    return rows
+      .filter((row) => rowMatchesFilters(row, filters()))
+      .sort((left, right) => {
+        const leftOrder = Number.parseInt(left.dataset[orderKey] ?? "0", 10);
+        const rightOrder = Number.parseInt(right.dataset[orderKey] ?? "0", 10);
+        return leftOrder - rightOrder;
+      });
+  }
+
+  async function updateResults() {
+    updateSequence += 1;
+    const sequence = updateSequence;
+    syncQueryUrl();
+    const matches = await matchingRows();
+
+    if (sequence !== updateSequence) {
+      return;
+    }
+
+    for (const row of rows) {
+      row.hidden = true;
+    }
+
+    matches.forEach((row, index) => {
+      list.append(row);
+      row.hidden = index >= visibleLimit;
+    });
+
+    list.append(empty);
+    currentMatchingCount = matches.length;
+    empty.hidden = matches.length > 0;
+    showMore.hidden = matches.length <= visibleLimit;
+  }
+
+  const resetAndUpdateResults = () => {
+    visibleLimit = increment;
+    void updateResults();
+  };
+
+  for (const control of [
+    search,
+    kindFilter,
+    statusFilter,
+    tagFilter,
+    componentFilter,
+    contentSearch,
+    ...sortInputs,
+  ]) {
+    control.addEventListener("input", resetAndUpdateResults);
+    control.addEventListener("change", resetAndUpdateResults);
+  }
+
+  showMore.addEventListener("click", () => {
+    visibleLimit = Math.min(visibleLimit + increment, currentMatchingCount);
+    void updateResults();
+  });
+
+  void updateResults();
+}
+
+function rowMatchesFilters(row: HTMLElement, filters: WebSearchFilters): boolean {
+  return (
+    (!filters.kind || row.dataset.kind === filters.kind) &&
+    (!filters.status || row.dataset.status === filters.status) &&
+    (!filters.tag || (row.dataset.tags ?? "").split(" ").includes(filters.tag)) &&
+    (!filters.component || (row.dataset.components ?? "").split(" ").includes(filters.component))
+  );
+}
+
+async function loadSearchIndex(includeContent: boolean): Promise<WebSearchIndexArtifact> {
+  if (includeContent) {
+    fullSearchIndexPromise ??= fetch("/search-index-full.json").then((response) => {
+      if (!response.ok) {
+        throw new Error(`Failed to load full search index: ${response.status}`);
+      }
+
+      return response.json() as Promise<WebSearchIndexArtifact>;
+    });
+
+    return fullSearchIndexPromise;
+  }
+
+  searchIndexPromise ??= fetch("/search-index.json").then((response) => {
+    if (!response.ok) {
+      throw new Error(`Failed to load search index: ${response.status}`);
+    }
+
+    return response.json() as Promise<WebSearchIndexArtifact>;
+  });
+
+  return searchIndexPromise;
+}

package/src/lib/search.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildSearchUrl,
+  getQueryFromUrl,
+  removeQueryFromUrl,
+  searchDocuments,
+  updateQueryInUrl,
+  type WebSearchIndexArtifact,
+} from "./search.js";
+
+const index: WebSearchIndexArtifact = {
+  schemaVersion: "1.0.0",
+  documents: [
+    {
+      id: "ADR-0001",
+      href: "/documents/ADR-0001/",
+      kind: "adr",
+      status: "accepted",
+      date: "2026-05-01",
+      title: "Use Markdown as source of truth",
+      summary: "Markdown remains canonical.",
+      tags: ["source"],
+      components: ["acta-core"],
+      owners: ["Boris"],
+    },
+    {
+      id: "SPEC-0004",
+      href: "/documents/SPEC-0004/",
+      kind: "spec",
+      status: "active",
+      date: "2026-05-02",
+      title: "Acta web viewer",
+      summary: "Static document viewer.",
+      tags: ["web"],
+      components: ["acta-web"],
+      owners: ["Boris"],
+    },
+  ],
+};
+
+const fullIndex: WebSearchIndexArtifact = {
+  schemaVersion: "1.0.0",
+  documents: [
+    {
+      ...index.documents[0],
+      sectionsText: "Context Decision Consequences",
+      bodyText: "Markdown files stay in Git.",
+    },
+    {
+      ...index.documents[1],
+      sectionsText: "Requirements Client-side search",
+      bodyText: "Astro interface with Orama search.",
+    },
+  ],
+};
+
+describe("web search utilities", () => {
+  it("reads and normalizes q from URLs", () => {
+    expect(getQueryFromUrl("https://acta.test/search?q=%20Astro%20")).toBe("Astro");
+    expect(getQueryFromUrl("https://acta.test/search?q=%20%20")).toBe("");
+    expect(getQueryFromUrl("https://acta.test/search")).toBe("");
+  });
+
+  it("updates q in URLs and removes empty queries", () => {
+    expect(updateQueryInUrl("https://acta.test/search?kind=spec", "Astro").toString()).toBe(
+      "https://acta.test/search?kind=spec&q=Astro",
+    );
+    expect(removeQueryFromUrl("https://acta.test/search?q=Astro&kind=spec").toString()).toBe(
+      "https://acta.test/search?kind=spec",
+    );
+    expect(buildSearchUrl("Astro docs")).toBe("/search?q=Astro+docs");
+    expect(buildSearchUrl("")).toBe("/search");
+  });
+
+  it("ranks exact ID and title matches before body matches", async () => {
+    await expect(searchDocuments(index, "SPEC-0004")).resolves.toEqual(["SPEC-0004"]);
+    await expect(searchDocuments(index, "markdown")).resolves.toEqual(["ADR-0001"]);
+  });
+
+  it("searches body content only when full index fields are present", async () => {
+    await expect(searchDocuments(index, "orama")).resolves.toEqual([]);
+    await expect(searchDocuments(fullIndex, "orama")).resolves.toEqual(["SPEC-0004"]);
+  });
+
+  it("applies metadata filters after Orama ranking", async () => {
+    await expect(searchDocuments(index, "viewer", { kind: "adr" })).resolves.toEqual([]);
+    await expect(searchDocuments(index, "viewer", { kind: "spec" })).resolves.toEqual([
+      "SPEC-0004",
+    ]);
+    await expect(searchDocuments(index, "source", { component: "acta-core" })).resolves.toEqual([
+      "ADR-0001",
+    ]);
+  });
+});

package/src/lib/search.ts

@@ -0,0 +1,153 @@
+import { create, insertMultiple, search } from "@orama/orama";
+
+export interface WebSearchIndexArtifact {
+  schemaVersion: string;
+  documents: WebSearchIndexDocument[];
+}
+
+export interface WebSearchIndexDocument {
+  id: string;
+  href: string;
+  kind: "adr" | "spec";
+  status: string;
+  date: string;
+  title: string;
+  summary: string;
+  tags: string[];
+  components: string[];
+  owners: string[];
+  sectionsText?: string;
+  bodyText?: string;
+}
+
+export interface WebSearchFilters {
+  kind?: string;
+  status?: string;
+  tag?: string;
+  component?: string;
+}
+
+const searchSchema = {
+  id: "string",
+  href: "string",
+  kind: "string",
+  status: "string",
+  date: "string",
+  title: "string",
+  summary: "string",
+  tags: "string[]",
+  components: "string[]",
+  owners: "string[]",
+} as const;
+
+const fullSearchSchema = {
+  ...searchSchema,
+  sectionsText: "string",
+  bodyText: "string",
+} as const;
+
+export function getQueryFromUrl(url: string | URL): string {
+  return new URL(url).searchParams.get("q")?.trim() ?? "";
+}
+
+export function updateQueryInUrl(url: string | URL, query: string): URL {
+  const nextUrl = new URL(url);
+  const normalizedQuery = query.trim();
+
+  if (normalizedQuery.length > 0) {
+    nextUrl.searchParams.set("q", normalizedQuery);
+  } else {
+    nextUrl.searchParams.delete("q");
+  }
+
+  return nextUrl;
+}
+
+export function removeQueryFromUrl(url: string | URL): URL {
+  return updateQueryInUrl(url, "");
+}
+
+export function buildSearchUrl(query: string): string {
+  const url = updateQueryInUrl("https://acta.local/search", query);
+  return `${url.pathname}${url.search}`;
+}
+
+export async function searchDocuments(
+  index: WebSearchIndexArtifact,
+  query: string,
+  filters: WebSearchFilters = {},
+): Promise<string[]> {
+  const normalizedQuery = query.trim();
+  const filteredDocuments = normalizedQuery
+    ? await rankedDocuments(index, normalizedQuery)
+    : index.documents;
+
+  return filteredDocuments
+    .filter((document) => matchesFilters(document, filters))
+    .map((document) => document.id);
+}
+
+function matchesFilters(document: WebSearchIndexDocument, filters: WebSearchFilters): boolean {
+  return (
+    (!filters.kind || document.kind === filters.kind) &&
+    (!filters.status || document.status === filters.status) &&
+    (!filters.tag || document.tags.includes(filters.tag)) &&
+    (!filters.component || document.components.includes(filters.component))
+  );
+}
+
+async function rankedDocuments(
+  index: WebSearchIndexArtifact,
+  query: string,
+): Promise<WebSearchIndexDocument[]> {
+  const searchesBody = index.documents.some(
+    (document) => document.sectionsText !== undefined || document.bodyText !== undefined,
+  );
+
+  if (searchesBody) {
+    const db = create({ schema: fullSearchSchema });
+    await insertMultiple(db, index.documents);
+    const result = await search<typeof db, WebSearchIndexDocument>(db, {
+      term: query,
+      properties: [
+        "id",
+        "title",
+        "summary",
+        "tags",
+        "components",
+        "owners",
+        "sectionsText",
+        "bodyText",
+      ],
+      boost: {
+        id: 16,
+        title: 10,
+        tags: 6,
+        components: 6,
+        summary: 4,
+        sectionsText: 2,
+        bodyText: 1,
+      },
+      limit: index.documents.length,
+    });
+
+    return result.hits.map((hit) => hit.document);
+  }
+
+  const db = create({ schema: searchSchema });
+  await insertMultiple(db, index.documents);
+  const result = await search<typeof db, WebSearchIndexDocument>(db, {
+    term: query,
+    properties: ["id", "title", "summary", "tags", "components", "owners"],
+    boost: {
+      id: 16,
+      title: 10,
+      tags: 6,
+      components: 6,
+      summary: 4,
+    },
+    limit: index.documents.length,
+  });
+
+  return result.hits.map((hit) => hit.document);
+}

package/src/locales/en/common.json

@@ -0,0 +1,6 @@
+{
+  "all": "All",
+  "none": "None",
+  "valid": "Valid",
+  "needsAttention": "Needs attention"
+}

package/src/locales/en/dashboard.json

@@ -0,0 +1,8 @@
+{
+  "tab": "Acta documents",
+  "meta": "Browse Acta ADR and spec documents",
+  "eyebrow": "Repository viewer",
+  "header": "Documents",
+  "counts": "{{count}} documents, {{adrs}} ADRs, {{specs}} specs",
+  "issuesPill": "{{errors}} errors · {{warnings}} warnings"
+}

package/src/locales/en/documents.json

@@ -0,0 +1,63 @@
+{
+  "filters": {
+    "legend": "Document filters",
+    "search": "Search",
+    "searchPlaceholder": "Title, tag, owner, section...",
+    "kind": "Kind",
+    "status": "Status",
+    "tag": "Tag",
+    "component": "Component",
+    "sort": "Sort",
+    "sortNewest": "Newest first",
+    "sortDependency": "Dependency order",
+    "searchContent": "Search in content",
+    "searchingContent": "Searching content..."
+  },
+  "empty": "No matching documents.",
+  "showMore": "Show more",
+  "detail": {
+    "file": "File",
+    "owners": "Owners",
+    "tags": "Tags",
+    "components": "Components",
+    "validation": "Validation",
+    "links": "Links",
+    "backlinks": "Backlinks",
+    "externalReferences": "External references",
+    "noOutgoing": "No outgoing internal links.",
+    "noBacklinks": "No backlinks.",
+    "back": "Back to documents"
+  },
+  "linkTypes": {
+    "tooltipOutgoing": "What is \"{{key}}\"?",
+    "tooltipIncoming": "What is \"{{key}}\" (incoming)?",
+    "related": {
+      "outgoing": "Loose semantic connection — context shared, no dependency.",
+      "incoming": "Other documents that mark this one as related context."
+    },
+    "supersedes": {
+      "outgoing": "This document replaces the linked documents.",
+      "incoming": "Documents that replace this one (this one is superseded)."
+    },
+    "replacedBy": {
+      "outgoing": "The linked documents replace this one.",
+      "incoming": "Documents that this one replaces."
+    },
+    "decidedBy": {
+      "outgoing": "Decisions (ADRs) that drive this document.",
+      "incoming": "Documents driven by the decision recorded here."
+    },
+    "dependsOn": {
+      "outgoing": "Documents this one depends on.",
+      "incoming": "Documents that depend on this one."
+    },
+    "validates": {
+      "outgoing": "Documents this one validates (e.g. tests/specs verify decisions).",
+      "incoming": "Documents that validate this one."
+    },
+    "references": {
+      "outgoing": "External URLs cited from this document.",
+      "incoming": "External references pointing here."
+    }
+  }
+}

package/src/locales/en/graph.json

@@ -0,0 +1,19 @@
+{
+  "tab": "Acta graph",
+  "meta": "Explore Acta document relationships",
+  "eyebrow": "Repository viewer",
+  "header": "Graph",
+  "counts": "{{nodes}} nodes, {{edges}} relationships",
+  "filters": {
+    "legend": "Graph filters",
+    "kind": "Kind",
+    "status": "Status"
+  },
+  "areaLabel": "Document relationship graph",
+  "legend": {
+    "label": "Graph legend",
+    "dependency": "Dependency",
+    "related": "Related",
+    "supersession": "Supersession"
+  }
+}

package/src/locales/en/search.json

@@ -0,0 +1,7 @@
+{
+  "tab": "Acta search",
+  "meta": "Search Acta ADR and spec documents",
+  "eyebrow": "Repository search",
+  "header": "Search",
+  "counts": "{{count}} searchable documents"
+}