pi-weave 0.1.1

package/src/core/graph/build.ts

@@ -0,0 +1,258 @@
+/**
+ * Pure graph builder: knowledge workspace inputs → GraphModel.
+ *
+ * No I/O, no clock access, no harness imports (design §21,
+ * docs/weave-view.md §3). Stability contract: identical inputs produce
+ * byte-identical JSON (ids derive from slugs/paths only; `generatedAt` is
+ * derived from input timestamps, never from the wall clock) — that is what
+ * makes the page's refresh-polling cheap.
+ */
+
+import type { Note, RepoIndex, StalenessReport, VaultStatus } from "../types";
+import type { SummaryRecord } from "../summaries";
+import type { EdgeKind, GraphEdge, GraphModel, GraphNode } from "./model";
+import { extractWikilinks } from "./wikilinks";
+
+/** Hard cap on note nodes (docs/weave-view.md M3 guard). */
+export const DEFAULT_MAX_NOTES = 500;
+
+export interface BuildGraphInput {
+  vault: VaultStatus;
+  /** Full notes including bodies (for wiki-link extraction). */
+  notes: Note[];
+  /** Repository half; null when cwd is not an indexed git repository. */
+  repository: { index: RepoIndex; staleness: StalenessReport } | null;
+  /** Deep-scan summaries keyed by repo-relative path (docs/scan-modes.md). */
+  summaries?: ReadonlyMap<string, SummaryRecord>;
+}
+
+const SHORT_SHA_LEN = 7;
+const PREVIEW_LEN = 240;
+
+function moduleDetail(
+  path: string,
+  fileCount: number,
+  summaries: ReadonlyMap<string, SummaryRecord> | undefined,
+): Record<string, string> {
+  const detail: Record<string, string> = { path, files: String(fileCount) };
+  if (summaries) {
+    const prefix = path === "." ? "" : `${path}/`;
+    let count = 0;
+    for (const target of summaries.keys()) {
+      if (target.startsWith(prefix)) count += 1;
+    }
+    if (count > 0) detail["summarized files"] = String(count);
+  }
+  return detail;
+}
+
+function preview(body: string): string {
+  const flat = body.trim().replace(/\s+/g, " ");
+  return flat.length > PREVIEW_LEN ? `${flat.slice(0, PREVIEW_LEN)}…` : flat;
+}
+
+/** Data-as-of marker: newest timestamp present in the inputs (ISO strings compare lexicographically). */
+export function dataTimestamp(input: BuildGraphInput): string {
+  let max = "";
+  for (const note of input.notes) {
+    if (note.updated > max) max = note.updated;
+  }
+  const repoStamp = input.repository?.index.updated ?? "";
+  if (repoStamp > max) max = repoStamp;
+  if (input.summaries) {
+    for (const rec of input.summaries.values()) {
+      if (rec.at > max) max = rec.at;
+    }
+  }
+  return max;
+}
+
+/**
+ * Parse a remote into display label + canonical url. Core `remotes()` emits
+ * bare deduped URLs, but hand-written fixtures (or future sources) may use
+ * "name url"; both are accepted. Bare URLs get their label from the last
+ * path segment (works for scp-style `git@host:org/repo.git` too).
+ */
+function parseRemote(raw: string): { label: string; url: string } {
+  const s = raw.trim();
+  const named = /^\s*(\S+)\s+(\S.*)$/.exec(s);
+  if (named && named[1] !== undefined && named[2] !== undefined && !named[1].includes("://") && !named[1].includes("@")) {
+    return { label: named[1], url: named[2].trim() };
+  }
+  const noTrail = s.replace(/\/+$/, "");
+  const afterColon = noTrail.split(":").pop() ?? noTrail;
+  const tail = afterColon.split("/").pop() ?? afterColon;
+  return { label: tail.replace(/\.git$/, ""), url: s };
+}
+
+function buildVaultSide(input: BuildGraphInput, maxNotes: number, nodes: GraphNode[], edges: GraphEdge[]): string[] {
+  const truncated = input.notes.length > maxNotes;
+  const kept = input.notes.slice(0, maxNotes);
+
+  const vaultDetail: Record<string, string> = {
+    root: input.vault.root,
+    notes: String(input.vault.noteCount),
+  };
+  if (truncated) {
+    vaultDetail.warning = `Graph shows the ${maxNotes} most recent notes — the vault holds ${input.vault.noteCount}. Wiki-links to older notes are omitted.`;
+  }
+  nodes.push({ id: "vault", kind: "vault", label: "Vault", provenance: null, detail: vaultDetail });
+
+  const keptSlugs = new Set(kept.map((n) => n.slug));
+  for (const note of kept) {
+    const links = extractWikilinks(note.body);
+    const resolved = links.filter((slug) => keptSlugs.has(slug));
+    const detail: Record<string, string> = {
+      slug: note.slug,
+      source: note.source,
+      updated: note.updated,
+    };
+    if (note.tags.length > 0) detail.tags = note.tags.join(", ");
+    const dangling = links.length - resolved.length;
+    if (dangling > 0) detail["dangling links"] = String(dangling);
+    detail.preview = preview(note.body);
+
+    nodes.push({ id: `note:${note.slug}`, kind: "note", label: note.title, provenance: note.source, detail });
+    edges.push({ source: "vault", target: `note:${note.slug}`, kind: "contains" });
+    for (const target of resolved) {
+      edges.push({ source: `note:${note.slug}`, target: `note:${target}`, kind: "links-to" });
+    }
+  }
+  return [...keptSlugs];
+}
+
+function buildRepositorySide(
+  repository: NonNullable<BuildGraphInput["repository"]>,
+  summaries: ReadonlyMap<string, SummaryRecord> | undefined,
+  nodes: GraphNode[],
+  edges: GraphEdge[],
+): void {
+  const { index, staleness } = repository;
+  const { identity, git, structure } = index;
+
+  const repoDetail: Record<string, string> = {
+    root: identity.root,
+    files: String(structure.fileCount),
+    state: staleness.state,
+  };
+  const languages = Object.entries(structure.languages)
+    .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+    .slice(0, 3)
+    .map(([name, count]) => `${name} (${count})`)
+    .join(", ");
+  if (languages.length > 0) repoDetail.languages = languages;
+  if (staleness.reasons.length > 0) repoDetail.stale = staleness.reasons[0] ?? "";
+  nodes.push({ id: "repository", kind: "repository", label: identity.name, provenance: null, detail: repoDetail });
+
+  const branch = git.branch.length > 0 ? git.branch : "(detached)";
+  nodes.push({
+    id: "gitState",
+    kind: "gitState",
+    label: `${branch} @ ${git.headSha.slice(0, SHORT_SHA_LEN)}`,
+    provenance: null,
+    detail: {
+      branch,
+      commit: git.headSha,
+      "uncommitted changes": String(git.changedFiles.length),
+      captured: git.capturedAt,
+    },
+  });
+  edges.push({ source: "repository", target: "gitState", kind: "anchored-at" });
+
+  for (const remote of identity.remotes) {
+    const { label, url } = parseRemote(remote);
+    // Id keys off the URL (the actual identity — two names can collide).
+    nodes.push({ id: `external:${url}`, kind: "external", label, provenance: null, detail: { url } });
+    edges.push({ source: "repository", target: `external:${url}`, kind: "contains" });
+  }
+
+  for (const pkg of structure.packages) {
+    nodes.push({
+      id: `package:${pkg.manifestPath}`,
+      kind: "package",
+      label: pkg.name,
+      provenance: null,
+      detail: { manifest: pkg.manifestPath, kind: pkg.kind },
+    });
+    edges.push({ source: "repository", target: `package:${pkg.manifestPath}`, kind: "contains" });
+  }
+
+  for (const mod of structure.modules) {
+    const label = mod.path === "(root)" ? "./ (root files)" : mod.path;
+    nodes.push({
+      id: `module:${mod.path}`,
+      kind: "module",
+      label,
+      provenance: null,
+      detail: moduleDetail(mod.path, mod.fileCount, summaries),
+    });
+    edges.push({ source: "repository", target: `module:${mod.path}`, kind: "contains" });
+  }
+
+  for (const entry of structure.entryPoints) {
+    const detail: Record<string, string> = { path: entry };
+    const sum = summaries?.get(entry);
+    if (sum) {
+      detail.summary = sum.summary;
+      detail["summarized at"] = sum.at;
+      if (sum.model !== null) detail["summarized by"] = sum.model;
+    }
+    nodes.push({ id: `entryPoint:${entry}`, kind: "entryPoint", label: entry, provenance: null, detail });
+    edges.push({ source: "repository", target: `entryPoint:${entry}`, kind: "contains" });
+  }
+
+  // Render the derived .okf index as an expandable subtree under its module.
+  // Files nest by directory: okf.json at the root, repository/*.json under a
+  // "repository" folder, and summary files under a "summaries" folder so a
+  // large summary set never explodes the tree. Ids are path-derived (stable).
+  if (structure.okFiles && structure.okFiles.length > 0) {
+    const okRoot = "module:.okf";
+    const repoDir = "module:.okf/repository";
+    const sumDir = "module:.okf/repository/summaries";
+    const okChildren: string[] = [];
+    const repoChildren: string[] = [];
+    const sumChildren: string[] = [];
+    for (const f of structure.okFiles) {
+      const rel = f.replace(/^\.okf\//, "");
+      const id = `okf:${rel}`;
+      const label = rel.split("/").pop() ?? rel;
+      nodes.push({ id, kind: "file", label, provenance: null, detail: { path: rel } });
+      if (rel.startsWith("repository/summaries/")) sumChildren.push(id);
+      else if (rel.startsWith("repository/")) repoChildren.push(id);
+      else okChildren.push(id);
+    }
+    okChildren.forEach((c) => edges.push({ source: okRoot, target: c, kind: "contains" }));
+    if (repoChildren.length > 0 || sumChildren.length > 0) {
+      nodes.push({ id: repoDir, kind: "module", label: "repository", provenance: null, detail: { path: ".okf/repository" } });
+      edges.push({ source: okRoot, target: repoDir, kind: "contains" });
+      repoChildren.forEach((c) => edges.push({ source: repoDir, target: c, kind: "contains" }));
+      if (sumChildren.length > 0) {
+        nodes.push({ id: sumDir, kind: "module", label: "summaries", provenance: null, detail: { path: ".okf/repository/summaries" } });
+        edges.push({ source: repoDir, target: sumDir, kind: "contains" });
+        sumChildren.forEach((c) => edges.push({ source: sumDir, target: c, kind: "contains" }));
+      }
+    }
+  }
+}
+
+/**
+ * Build the graph model for the viewer. Notes are capped at `maxNotes`
+ * (docs/weave-view.md M3); the vault node carries a warning when truncated.
+ */
+export function buildGraph(input: BuildGraphInput, options: { maxNotes?: number } = {}): GraphModel {
+  const maxNotes = options.maxNotes ?? DEFAULT_MAX_NOTES;
+  const nodes: GraphNode[] = [];
+  const edges: GraphEdge[] = [];
+  buildVaultSide(input, maxNotes, nodes, edges);
+  if (input.repository !== null) {
+    buildRepositorySide(input.repository, input.summaries, nodes, edges);
+  }
+  return {
+    generatedAt: dataTimestamp(input),
+    staleness: input.repository?.staleness ?? null,
+    nodes,
+    edges,
+  };
+}
+
+export type { EdgeKind, GraphEdge, GraphModel, GraphNode, NodeKind } from "./model";

package/src/core/graph/current.ts

@@ -0,0 +1,107 @@
+/**
+ * Workspace assembly readers for the viewers (docs/weave-view.md §2,
+ * weave-view-tui-design §3.1).
+ *
+ * These functions are *workspace assembly*, symmetric to `getWorkspaceStatus`
+ * (already in core): pure fan-out over `core/vault`, `core/repoIndex`,
+ * `core/summaries`, `core/git`, then the pure `buildGraph`. They import only
+ * core + node builtins, so a future Claude Code / opencode adapter can
+ * assemble the same graph without importing pi's viewer directory.
+ */
+
+import { readFile } from "node:fs/promises";
+import { join, resolve, sep } from "node:path";
+import {
+  assessStaleness,
+  buildGraph,
+  DEFAULT_MAX_NOTES,
+  findGitRoot,
+  getNote,
+  listNotes,
+  noteCount,
+  readRepoIndex,
+  readSummaryMap,
+  resolveNotePath,
+  resolveVaultRoot,
+  type BuildGraphInput,
+  type GraphModel,
+  type Note,
+} from "../index";
+
+/** A note read for the viewers (read-only; never cached). Mirrors the vault `Note` shape. */
+export interface ViewNote {
+  slug: string;
+  title: string;
+  body: string;
+  created: string;
+  updated: string;
+  tags: string[];
+  source: Note["source"];
+}
+
+/**
+ * Live-read one note for the viewer's side panel / TUI detail (read-only;
+ * never caches). Traversal-safe: an unsafe slug returns null without
+ * touching disk.
+ */
+export async function readNoteForView(vaultRoot: string, slug: string): Promise<ViewNote | null> {
+  if (resolveNotePath(vaultRoot, slug) === null) return null; // traversal-safe
+  const note = await getNote(vaultRoot, slug);
+  if (note === null) return null;
+  return {
+    slug: note.slug,
+    title: note.title,
+    body: note.body,
+    created: note.created,
+    updated: note.updated,
+    tags: note.tags,
+    source: note.source,
+  };
+}
+
+/**
+ * Read one derived index file under <cwd>/.okf for the viewers
+ * (traversal-safe). The `rel` path is anchored to <cwd>/.okf, so
+ * summary/identity/structure bodies can be shown instead of "(no body)".
+ */
+export async function readOkfFileForView(cwd: string, rel: string): Promise<{ path: string; body: string } | null> {
+  const okfRoot = join(cwd, ".okf");
+  const resolved = resolve(okfRoot, rel);
+  if (resolved !== okfRoot && !resolved.startsWith(okfRoot + sep)) return null; // traversal-safe
+  try {
+    const body = await readFile(resolved, "utf8");
+    return { path: rel, body };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Assemble the fresh graph from disk. Called on every viewer fetch
+ * (no caching — docs/weave-view.md §2). Reads the vault (capped at
+ * DEFAULT_MAX_NOTES) and, when cwd is an indexed git repository, the repo
+ * index + deep-scan summary sidecars. Degrades to a vault-only graph when
+ * the repo has no index or the index is corrupt.
+ */
+export async function buildCurrentGraph(cwd: string, vaultRoot: string = resolveVaultRoot()): Promise<GraphModel> {
+  const noteSummaries = (await listNotes(vaultRoot)).slice(0, DEFAULT_MAX_NOTES);
+  const loaded = await Promise.all(noteSummaries.map((s) => getNote(vaultRoot, s.slug)));
+  const notes = loaded.filter((n): n is Note => n !== null);
+
+  const input: BuildGraphInput = {
+    vault: { root: vaultRoot, exists: true, noteCount: await noteCount(vaultRoot) },
+    notes,
+    repository: null,
+  };
+
+  const repoRoot = await findGitRoot(cwd);
+  if (repoRoot !== null) {
+    const index = await readRepoIndex(repoRoot);
+    if (index !== null) {
+      input.repository = { index, staleness: await assessStaleness(repoRoot) };
+      input.summaries = await readSummaryMap(repoRoot); // deep-scan sidecars, read live
+    }
+  }
+  return buildGraph(input);
+}
+

package/src/core/graph/model.ts

@@ -0,0 +1,63 @@
+/**
+ * Graph model shared between the builder (core) and the viewer (adapter).
+ * Pure data — no harness imports (design §21). See docs/weave-view.md §3.
+ */
+
+import type { NoteSource, StalenessReport } from "../types";
+
+export type NodeKind =
+  | "vault"
+  | "note"
+  | "repository"
+  | "module"
+  | "package"
+  | "entryPoint"
+  | "gitState"
+  | "external"
+  | "file";
+
+export type EdgeKind = "contains" | "anchored-at" | "links-to" | "mentions";
+
+/** All node kinds — the viewer legend and tests iterate this list. */
+export const NODE_KINDS: readonly NodeKind[] = [
+  "vault",
+  "note",
+  "repository",
+  "module",
+  "package",
+  "entryPoint",
+  "gitState",
+  "external",
+  "file",
+];
+
+/** All edge kinds — the viewer legend and tests iterate this list. */
+export const EDGE_KINDS: readonly EdgeKind[] = ["contains", "anchored-at", "links-to", "mentions"];
+
+/** A single graph node. `id` is stable: derived from slugs/paths only. */
+export interface GraphNode {
+  id: string;
+  kind: NodeKind;
+  label: string;
+  /** Trust provenance for knowledge nodes; null for structural nodes. */
+  provenance: NoteSource | null;
+  /** Pre-formatted side-panel payload. */
+  detail: Record<string, string>;
+}
+
+export interface GraphEdge {
+  source: string;
+  target: string;
+  kind: EdgeKind;
+}
+
+export interface GraphModel {
+  /**
+   * Data-as-of marker derived from inputs (max note updated / index stamp),
+   * so two builds of unchanged inputs produce byte-identical JSON.
+   */
+  generatedAt: string;
+  staleness: StalenessReport | null;
+  nodes: GraphNode[];
+  edges: GraphEdge[];
+}

package/src/core/graph/wikilinks.ts

@@ -0,0 +1,28 @@
+/**
+ * Obsidian-compatible [[wiki-link]] extraction from note bodies.
+ * Pure module — see docs/weave-view.md §3.
+ */
+
+import { slugify } from "../slug";
+
+const WIKILINK_RE = /\[\[([^\][|]+)(?:\|[^\]]*)?\]\]/g;
+
+/**
+ * Extract wiki-link targets from a note body as slugs. Handles
+ * `[[some-note]]` and aliased `[[Some Note|alias]]` (alias ignored for
+ * linking). Targets are slugified so `[[Release Plan]]` matches the note
+ * `release-plan`. Duplicates are removed, order of first appearance kept.
+ */
+export function extractWikilinks(body: string): string[] {
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const match of body.matchAll(WIKILINK_RE)) {
+    const raw = (match[1] ?? "").trim();
+    if (raw.length === 0) continue;
+    const slug = slugify(raw);
+    if (seen.has(slug)) continue;
+    seen.add(slug);
+    out.push(slug);
+  }
+  return out;
+}

package/src/core/index.ts

@@ -0,0 +1,25 @@
+/**
+ * pi-weave core — the portable knowledge engine.
+ *
+ * NO harness imports allowed in this tree (see docs/design.md §21).
+ */
+export * from "./types";
+export * from "./slug";
+export * from "./frontmatter";
+export * from "./languages";
+export * from "./mutex";
+export * from "./paths";
+export * from "./git";
+export * from "./vault";
+export * from "./repoIndex";
+export * from "./summaries";
+export * from "./workspace";
+export * from "./graph/model";
+export * from "./graph/wikilinks";
+export { buildGraph, dataTimestamp, DEFAULT_MAX_NOTES, type BuildGraphInput } from "./graph/build";
+export {
+  buildCurrentGraph,
+  readNoteForView,
+  readOkfFileForView,
+  type ViewNote,
+} from "./graph/current";

package/src/core/languages.ts

@@ -0,0 +1,76 @@
+/** File-extension -> language name used for the Level 0 language histogram. */
+
+const EXTENSION_TO_LANGUAGE: Record<string, string> = {
+  ".ts": "TypeScript",
+  ".tsx": "TypeScript",
+  ".mts": "TypeScript",
+  ".cts": "TypeScript",
+  ".js": "JavaScript",
+  ".jsx": "JavaScript",
+  ".mjs": "JavaScript",
+  ".cjs": "JavaScript",
+  ".py": "Python",
+  ".pyi": "Python",
+  ".go": "Go",
+  ".rs": "Rust",
+  ".rb": "Ruby",
+  ".java": "Java",
+  ".kt": "Kotlin",
+  ".kts": "Kotlin",
+  ".swift": "Swift",
+  ".c": "C",
+  ".h": "C",
+  ".cpp": "C++",
+  ".cc": "C++",
+  ".cxx": "C++",
+  ".hpp": "C++",
+  ".cs": "C#",
+  ".fs": "F#",
+  ".php": "PHP",
+  ".lua": "Lua",
+  ".zig": "Zig",
+  ".ex": "Elixir",
+  ".exs": "Elixir",
+  ".erl": "Erlang",
+  ".hrl": "Erlang",
+  ".clj": "Clojure",
+  ".cljs": "Clojure",
+  ".scala": "Scala",
+  ".hs": "Haskell",
+  ".ml": "OCaml",
+  ".sh": "Shell",
+  ".bash": "Shell",
+  ".zsh": "Shell",
+  ".fish": "Shell",
+  ".ps1": "PowerShell",
+  ".sql": "SQL",
+  ".html": "HTML",
+  ".htm": "HTML",
+  ".css": "CSS",
+  ".scss": "SCSS",
+  ".less": "Less",
+  ".md": "Markdown",
+  ".mdx": "Markdown",
+  ".json": "JSON",
+  ".jsonc": "JSON",
+  ".yaml": "YAML",
+  ".yml": "YAML",
+  ".toml": "TOML",
+  ".xml": "XML",
+  ".vue": "Vue",
+  ".svelte": "Svelte",
+  ".tf": "Terraform",
+  ".proto": "Protobuf",
+  ".graphql": "GraphQL",
+  ".gql": "GraphQL",
+  ".r": "R",
+  ".jl": "Julia",
+  ".dart": "Dart",
+  ".dockerfile": "Dockerfile",
+};
+
+/** Look up a language by file extension (with or without leading dot). */
+export function languageForExtension(ext: string): string | undefined {
+  const key = ext.startsWith(".") ? ext.toLowerCase() : `.${ext.toLowerCase()}`;
+  return EXTENSION_TO_LANGUAGE[key];
+}

package/src/core/mutex.ts

@@ -0,0 +1,34 @@
+/**
+ * Keyed async mutation queue (core-owned; no harness dependencies).
+ *
+ * Serializes async mutators that touch the same resource key (e.g. a note
+ * file path) so concurrent callers — parallel tool calls, multiple tools
+ * writing at once — can't interleave writes. Replaces the pi harness's
+ * `withFileMutationQueue` with a portable equivalent, per AGENTS.md rule 3
+ * (logic lives in core; adapters stay thin).
+ *
+ * Properties:
+ * - Tasks sharing a key run strictly one-after-another, in call order.
+ * - Tasks with different keys run concurrently.
+ * - A rejected task does NOT wedge the queue: its error propagates to its
+ *   own caller, and later tasks for the same key still run.
+ * - The value each task resolves with is passed through untouched.
+ */
+
+const queues = new Map<string, Promise<unknown>>();
+
+export function withMutationQueue<T>(key: string, task: () => Promise<T>): Promise<T> {
+  const prior = queues.get(key) ?? Promise.resolve();
+  // `prior` (as stored below) never rejects; the dual callbacks are
+  // belt-and-braces so even a foreign promise in the map can't wedge us.
+  const result = prior.then(() => task(), () => task());
+  // Store a non-rejecting tail so a failure can't poison later tasks.
+  queues.set(
+    key,
+    result.then(
+      () => undefined,
+      () => undefined,
+    ),
+  );
+  return result;
+}

package/src/core/paths.ts

@@ -0,0 +1,37 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * Canonical locations for pi-weave knowledge (design Appendix A).
+ *
+ *  - Vault:            ~/.okf/            (human/agent persistent knowledge)
+ *  - Repository index: <git root>/.okf/   (derived machine knowledge)
+ *
+ * The vault location can be overridden with PI_WEAVE_VAULT, primarily for
+ * tests and for users who keep their vault somewhere unusual.
+ */
+
+export const OKF_DIR = ".okf";
+export const OKF_MANIFEST = "okf.json";
+export const NOTES_DIR = "notes";
+export const REPOSITORY_DIR = "repository";
+export const VAULT_ENV_VAR = "PI_WEAVE_VAULT";
+
+/** Resolve the vault root. `env` is injectable for tests. */
+export function resolveVaultRoot(env: NodeJS.ProcessEnv = process.env): string {
+  const override = env[VAULT_ENV_VAR];
+  if (override && override.trim().length > 0) {
+    return override;
+  }
+  return join(homedir(), OKF_DIR);
+}
+
+/** The repository index directory for a given repo root. */
+export function repoIndexDir(repoRoot: string): string {
+  return join(repoRoot, OKF_DIR);
+}
+
+/** Subdirectory of an .okf index holding repository knowledge. */
+export function repoKnowledgeDir(repoRoot: string): string {
+  return join(repoRoot, OKF_DIR, REPOSITORY_DIR);
+}