pi-weave 0.1.7 → 0.1.9

package/src/web/shared/view.ts

@@ -0,0 +1,200 @@
+/**
+ * The browser's legal door onto the core view-models (weave-workspace §3, §2.1).
+ *
+ * ## What this is
+ *
+ * `src/core/view/` holds the one implementation of the tree, detail and focus
+ * projections — the whole point of §3 being that the TUI and the browser
+ * workspace *cannot drift*, because there is nothing to drift from. The tier
+ * table (§2) forbids `src/web/client/**` from reaching `src/core`, transitively
+ * included, so without a door the client's only options were to re-implement
+ * those projections or to have the server pre-render them. Both defeat §3.
+ *
+ * This module is the door. It contains **no logic**: every line below is an
+ * `export … from`, so the client and the TUI call the same function object
+ * defined in the same file. A wrapper would be a second implementation with a
+ * second set of edge cases, which is the failure mode §3 exists to prevent.
+ *
+ * ## Why this is allowed to import `src/core` when `wire.ts` is not
+ *
+ * §2.1 records a hard-won rule: *nothing under `src/web/shared/` imports
+ * `src/core`, not even as a type*. That rule was written after
+ * `import type { GraphModel }` in `wire.ts` broke `tsc -p tsconfig.web.json`
+ * with 24 `Cannot find module 'node:fs'` errors — because type erasure happens
+ * in the bundler and not in the typechecker, so the compiler still walked the
+ * whole Node-flavoured core type graph.
+ *
+ * The reasoning was correct about *that* closure. `src/core/graph/model.ts` was
+ * reached from a barrel whose neighbours read the filesystem. It was not a
+ * claim about core in general, and it is not true of this closure:
+ *
+ * ```text
+ * shared/view.ts
+ *   → core/view/{tree,detail,focus,links,time,types}.ts
+ *     → core/graph/model.ts → core/types.ts
+ * ```
+ *
+ * Eleven modules, zero `node:*` imports, zero Node globals, zero npm
+ * dependencies, all pure functions over plain data. They are genuinely
+ * browser-portable; only the blanket tier rule stood in the way.
+ *
+ * Two guards keep that a fact rather than an assumption, and they are what
+ * makes the exception sound rather than merely convenient:
+ *
+ * 1. `tests/web/view.purity.test.ts` walks the transitive closure reachable
+ *    from this file and fails if any module in it acquires a `node:*` import,
+ *    a Node global, or an npm dependency. Add `node:fs` to
+ *    `src/core/view/tree.ts` and the suite goes red immediately — not silently
+ *    at runtime in someone's browser.
+ * 2. `tsconfig.web.json` includes `src/web/shared/**`, so the same closure is
+ *    typechecked with `"types": []` and a `lib` with no Node types. That is
+ *    the check that caught the original 24 errors, now aimed here on purpose.
+ *
+ * The narrow, precise version of the §2.1 rule is therefore: *`src/web/shared/`
+ * may import the modules of `src/core` that are proven node-free, and nothing
+ * else.* `tests/web/tiers.test.ts` encodes that as a **module allowlist**, not
+ * a directory one — `core/vault.ts`, `core/git.ts`, `core/repoIndex.ts`,
+ * `core/summaries.ts`, `core/paths.ts`, `core/cache/` and
+ * `core/graph/current.ts` all remain forbidden here, because reopening the
+ * door as "shared may import core" would reopen the exact hole §2.1 closed.
+ *
+ * ## Why this is a small list
+ *
+ * Deliberately not `export * from "../../core/view"`. The barrel pulls in
+ * `health.ts` (a TUI surface) and `links.ts`'s tag index (derived server-side
+ * into `GraphPayload.tags`), neither of which any browser column consumes
+ * today — and each one it pulled in would be a module the purity guard then
+ * has to defend forever.
+ *
+ * So this is an allowlist, on the same principle as the `npm` column in
+ * `tests/web/tiers.test.ts`: the surface the columns actually use, and nothing
+ * more. **P3 added `focusNeighborhood`, `degreeOf` and `clusterAggregate`**,
+ * in the commit that first calls them, exactly as this paragraph promised —
+ * along with `src/core/view/cluster.ts` in `NODE_FREE_CORE_MODULES`, which is
+ * the reviewed edit that grants the permission. `cluster.ts`'s closure adds
+ * nothing new (it reaches only `graph/model.ts`, `types.ts` and `view/tree.ts`,
+ * all already permitted), so the node-free proof `view.purity.test.ts` runs is
+ * unchanged in kind.
+ *
+ * ## Wire types vs. view types
+ *
+ * The view-models were written against core's `GraphModel`, and the client
+ * holds `GraphPayload` from `./wire`. The two disagree by exactly one field:
+ * `WireGraphModel` is `Omit<GraphModel, "danglingLinks">`, because the payload
+ * hoists that map to its own top-level `dangling` rather than shipping it
+ * twice (§4.2). A caller therefore reassembles
+ * `{ ...payload.model, danglingLinks: payload.dangling }` before calling
+ * {@link treeRows} or {@link detailModel}. That reassembly is not done here on
+ * purpose: it is a wire concern with exactly one correct spelling, and putting
+ * it in this file would make the door carry a transformation instead of just
+ * being a door.
+ *
+ * The node and edge types need no such care. `WireGraphNode` / `WireGraphEdge`
+ * are asserted mutually assignable with their core counterparts by
+ * `tests/web/wire.contract.test.ts`, so a `WireGraphNode` may be passed to
+ * {@link listLabel} and a `WireGraphEdge[]` to {@link deriveBacklinks} with no
+ * cast. Likewise `WireNodeKind` / `WireNoteSource` are the same unions as
+ * core's `NodeKind` / `NoteSource`, which is why this module does not
+ * re-export a second name for either.
+ */
+
+// --- tree column (§1.2, P2) ---------------------------------------------------
+
+/**
+ * The tree column *is* `treeRows` with a different renderer (§3).
+ *
+ * `listLabel` is exported alongside it because the browser has places that
+ * hold a node but not a row — a graph tooltip, a dangling-link ghost — and a
+ * second label rule for those is precisely the drift §3 forbids.
+ * `treeEmptyHint` is the tree's honest empty state, for the same reason.
+ */
+export { listLabel, treeEmptyHint, treeRows } from "../../core/view/tree";
+
+/**
+ * `TreeState` here is **core's**, not the placeholder in
+ * `src/web/client/state.ts`: it carries the filter, the provenance cycle and
+ * the internals toggle that `treeRows` actually reads, where the client's
+ * P1 stand-in carries only an expanded-id list. P2 replaces the latter with
+ * this.
+ */
+export type { TreeRow, TreeState } from "../../core/view/tree";
+
+// --- note column (§1.2, P2) ---------------------------------------------------
+
+/**
+ * `relTime` renders the note header's "updated 12m ago"; `formatTreeMeta`
+ * renders a `TreeMeta` as plain text.
+ *
+ * A richer renderer is expected to switch on the {@link TreeMeta} union itself
+ * (a `<time>` element wants the ISO string, not a pre-formatted one), which is
+ * why the structured type comes across too and not only the formatter.
+ */
+export { formatTreeMeta, relTime } from "../../core/view/time";
+
+// --- context rail (§1.2, P2) --------------------------------------------------
+
+/** Links, backlinks and the ordered meta block for the selected node. */
+export { detailModel } from "../../core/view/detail";
+export type { DetailLinkRow, DetailMetaRow, DetailModel } from "../../core/view/detail";
+
+/** "Related": the 1-hop neighborhood, grouped by relationship. */
+export { focusModel } from "../../core/view/focus";
+export type { FocusGroup, FocusModel, FocusRow } from "../../core/view/focus";
+
+// --- graph column (§1.2, §7, P3) ------------------------------------------------
+
+/**
+ * The graph's neighborhood highlight (§7.4) and its node sizing.
+ *
+ * `focusNeighborhood` is the set sigma's `nodeReducer` dims *outside* of, and
+ * it must be the same set the context rail's "Related" is built from — a graph
+ * that highlights one neighbourhood while the rail lists another is two
+ * answers to one question, which is the drift §3 exists to prevent.
+ *
+ * `degreeOf` comes across alongside it because the graph column needs a
+ * *single* node's degree in one place (a tooltip, a collapsed cluster's
+ * badge). The bulk case — a degree for every node at once — is `degrees` in
+ * `client/graph/graph.model.ts`, which is O(edges) rather than
+ * O(nodes × edges); that is a different algorithm for a different question,
+ * not a second implementation of this one.
+ */
+export { degreeOf, focusNeighborhood } from "../../core/view/focus";
+
+/**
+ * Cluster collapse/expand, as **graph reduction** rather than masking (§7.4).
+ *
+ * Built in P0 and deliberately not a port of the retired viewer's function of
+ * the same name: that one computed a visibility mask, left every node in the
+ * graph, and never rewrote an edge — so a link from a hidden file to a visible
+ * note simply vanished. This returns reduced node and edge arrays with
+ * boundary-crossing edges retargeted onto the standing-in cluster, which is
+ * what sigma wants (§7.1: a graph it can consume verbatim) and what keeps the
+ * TUI tree and the web graph answering "what is visible?" identically.
+ */
+export { clusterAggregate } from "../../core/view/cluster";
+export type { ClusterAggregate, ClusterInfo, ProvenanceSplit } from "../../core/view/cluster";
+
+/**
+ * Backlinks for the whole graph in one pass — the rail renders one node's, but
+ * the tree wants "does this note have any?" without an O(nodes × edges) scan.
+ */
+export { deriveBacklinks } from "../../core/view/links";
+
+// --- shared row/meta types ----------------------------------------------------
+
+/**
+ * `SelectableRow` is the base of `TreeRow`, `DetailLinkRow` and `FocusRow`, so
+ * a single "render a selectable row" component can be typed against it rather
+ * than against a union of three.
+ */
+export type { SelectableRow, TreeMeta } from "../../core/view/types";
+
+/**
+ * The input type every function above takes.
+ *
+ * Renamed rather than re-exported as `GraphModel`, because `./wire` already
+ * exports that name for the *wire* model and the two are one field apart (see
+ * the module header). Two different `GraphModel`s in one tier is a trap; a
+ * name that says which side of the boundary it belongs to is not.
+ */
+export type { GraphModel as ViewGraphModel } from "../../core/graph/model";

package/src/web/shared/wire.ts

@@ -0,0 +1,358 @@
+/**
+ * The wire contract between the loopback server and the browser client
+ * (weave-workspace §5.3).
+ *
+ * ## Why this file exists at all
+ *
+ * The client cannot import `src/core` (§2 tier table): core is
+ * Node-flavoured TypeScript and a value import would drag `node:fs` into the
+ * bundle. So everything both sides need is either a **type** here or a pure
+ * function in `src/web/shared/`. This module is the type half — it is the
+ * single place where the shape of an HTTP response or an SSE frame is
+ * written down, and both the server that produces it and the client that
+ * consumes it are typed from it.
+ *
+ * ## Tier rules
+ *
+ * `src/web/shared/**`: itself only. No `node:*`, no DOM globals, no
+ * `src/pi`, and — as of the tier fix — **no `src/core`, not even as a type**.
+ *
+ * That last clause is stricter than the §2 table as originally written, and
+ * it exists because "core types only" turned out not to be a real boundary.
+ * `import type` erases from the *bundle*, but the compiler still has to
+ * resolve it: pulling `GraphModel` in here made `tsc -p tsconfig.web.json`
+ * load the entire core type graph, `node:fs` and all, and fail with 24
+ * errors under a project that deliberately has no node lib. The type-only
+ * distinction is one the bundler makes and the typechecker does not.
+ *
+ * The DTOs now live in `./graph`, declared structurally, with
+ * `tests/web/wire.contract.test.ts` asserting they stay assignable to and
+ * from their core counterparts. Drift is a compile error; the client is free
+ * of core in every sense.
+ *
+ * ## The graph payload is not the core `GraphModel`
+ *
+ * The core model is lossy on purpose: tags are flattened into a comma-joined
+ * display string and dangling link targets are counted then discarded
+ * (weave-view handoff findings). {@link GraphPayload} therefore carries the
+ * model *plus* the two structured indexes the model dropped, rather than
+ * growing structure inside `WireGraphNode.detail`, which is display-only by
+ * contract.
+ */
+
+import type { WireGraphModel, WireNoteSearchHit, WireNoteSource, WireViewNote } from "./graph";
+import type { Point } from "./metrics";
+
+/**
+ * The wire DTOs, re-exported under the names the client and server already
+ * use. Aliases rather than a second declaration, so there is exactly one
+ * definition of each shape and `./graph` remains the place drift is caught.
+ */
+export type GraphModel = WireGraphModel;
+export type ViewNote = WireViewNote;
+export type NoteSearchHit = WireNoteSearchHit;
+export type { Point };
+
+export type {
+  WireEdgeKind,
+  WireGraphEdge,
+  WireGraphModel,
+  WireGraphNode,
+  WireNodeKind,
+  WireNoteMeta,
+  WireNoteSearchHit,
+  WireNoteSource,
+  WireNoteSummary,
+  WireStalenessReport,
+  WireStalenessState,
+  WireViewNote,
+} from "./graph";
+export { WIRE_EDGE_KINDS, WIRE_MODEL_OMITTED_KEYS, WIRE_NODE_KINDS } from "./graph";
+
+// --- liveness ----------------------------------------------------------------
+
+/**
+ * Which half of the workspace an SSE frame is about.
+ *
+ * Deliberately coarser than the paths that produced it: macOS `fs.watch`
+ * coalesces and can miss rapid bursts, so a frame means "something in this
+ * scope changed, re-read it", never "here is the delta" (§6). A client that
+ * treated frames as deltas would silently diverge the first time the OS
+ * dropped one.
+ */
+export type ChangeScope = "vault" | "repo" | "git";
+
+/** Every {@link ChangeScope}, for exhaustiveness checks and table tests. */
+export const CHANGE_SCOPES: readonly ChangeScope[] = ["vault", "repo", "git"];
+
+/**
+ * One SSE frame.
+ *
+ * `stamp` is the graph's content digest at the moment the change was observed
+ * — the same value `GET /api/graph` serves as its ETag (§5.3). It is the
+ * dedupe key: a client that already holds this stamp has nothing to refetch,
+ * which matters because the watcher's debounce window can still emit two
+ * frames for one logical edit.
+ *
+ * Sharing one key with the ETag is load-bearing rather than tidy. While this
+ * was `generatedAt`, an edit that did not advance the timestamp maximum
+ * produced a frame the client deduped away against the stamp of the graph it
+ * already held, so the refetch never happened (§15.6).
+ */
+export interface ChangeEvent {
+  scope: ChangeScope;
+  stamp: string;
+}
+
+/** The `event:` name carried by every {@link ChangeEvent} frame. */
+export const CHANGE_EVENT_NAME = "change";
+
+/**
+ * Structural guard for a decoded SSE `data:` payload.
+ *
+ * The client parses frames off a socket that survives server restarts and
+ * proxy interference, so "it is JSON" is not the same as "it is ours".
+ * Narrow rather than validate-and-throw: a malformed frame should cost a
+ * skipped refetch, not an unhandled rejection inside `EventSource`'s
+ * callback.
+ */
+export function isChangeEvent(value: unknown): value is ChangeEvent {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value as { scope?: unknown; stamp?: unknown };
+  if (typeof candidate.stamp !== "string") return false;
+  return CHANGE_SCOPES.includes(candidate.scope as ChangeScope);
+}
+
+// --- responses ---------------------------------------------------------------
+
+/**
+ * `GET /api/graph`.
+ *
+ * @see GraphModel for the authoritative node/edge data.
+ */
+export interface GraphPayload {
+  /** Nodes, edges, staleness, `generatedAt`. The authoritative model. */
+  model: GraphModel;
+  /**
+   * tag → slugs (§4.3).
+   *
+   * Built by core's `deriveTagIndex` from the notes the graph was built from
+   * — *not* by re-parsing `WireGraphNode.detail.tags`, which is a
+   * comma-joined display string and must never be turned back into
+   * structure.
+   *
+   * Key order is meaningful and load-bearing: `deriveTagIndex` returns count
+   * descending, then tag ascending, and `Object.fromEntries` preserves that
+   * as JSON key insertion order. A client that wants the ranking can either
+   * trust the order or re-derive it from the array lengths. A tag with no
+   * notes cannot occur.
+   *
+   * Slugs, not node ids — `note:` is a graph-internal prefix.
+   */
+  tags: Record<string, string[]>;
+  /**
+   * slug → unresolved wikilink targets (§4.2).
+   *
+   * The ghost-node affordance: a `[[target]]` that matches no note is an
+   * offer to create one. Populated from core's `GraphModel.danglingLinks`,
+   * which the builder now retains instead of counting and discarding.
+   *
+   * Lives at the payload's top level rather than inside {@link GraphModel},
+   * which is why `WireGraphModel` is declared one field narrower than its
+   * core counterpart — the same map crossing the wire twice would give the
+   * client two places to read one fact from. A note with nothing unresolved
+   * is absent from the record, not present with an empty array.
+   */
+  dangling: Record<string, string[]>;
+  /**
+   * Server-precomputed layout, so the graph appears already laid out with no
+   * visible settling (§7.3). `null` when the server did not compute one —
+   * which is the default, because the layout module imports `d3-force` and
+   * the published package has zero runtime dependencies. The client then
+   * runs the identical `src/web/shared/layout` code itself.
+   */
+  positions: Record<string, Point> | null;
+  /**
+   * A **content digest** of this payload. The ETag body and the SSE dedupe
+   * key (§5.3, §6).
+   *
+   * Opaque: a truncated SHA-256 of the serialized payload, and nothing may
+   * parse it or derive meaning from its value. The only defined operation is
+   * equality, and it has exactly one guarantee — two payloads share a stamp
+   * if and only if they serialize to the same bytes.
+   *
+   * This was `model.generatedAt` until §15.6. A max of input timestamps is
+   * blind to any change that does not advance the maximum (a body edit, a
+   * front-matter edit, deleting a note that is not the newest), so a
+   * conditional GET answered `304` with stale content and the SSE dedupe
+   * dropped the frame that would have corrected it.
+   *
+   * For a human-readable "data as of" marker, read {@link GraphModel.generatedAt},
+   * which still carries it — the status bar does exactly that.
+   */
+  stamp: string;
+}
+
+/**
+ * `GET /api/note/:slug`, and the note half of every write response.
+ *
+ * The route used to serve a bare {@link ViewNote}. It carries a `revision`
+ * as of P5 because the editor cannot save safely without one: a save that
+ * does not say *which* state it was editing is a last-write-wins save, and
+ * the two writers a vault actually has — `$EDITOR` and an agent's
+ * `weave_note` call — are both fast enough to lose a paragraph to it.
+ *
+ * Carried in the **body** rather than as an `ETag`, deliberately. `api.ts`'s
+ * {@link HttpResponse} port exposes `ok`, `status` and `json()` and nothing
+ * else, because it exists so a two-line fake can stand in for `fetch` in a
+ * repository with no DOM (§10). Reading a header would mean widening that
+ * port for one field, and the field is a *property of the note*, not of the
+ * HTTP representation — unlike `/api/graph`'s stamp, which really is a cache
+ * validator and really does belong in an `ETag`.
+ */
+export interface NotePayload {
+  note: ViewNote;
+  /**
+   * Opaque version stamp for the file the note was read from.
+   *
+   * **Compare it, do not interpret it.** Core currently derives it from
+   * `mtimeMs:size` and says in the same breath that the shape is not part of
+   * the contract; a client that parsed a timestamp out of it would break the
+   * day core upgrades it to a digest. The only defined operation is equality
+   * against a later read of the same note.
+   */
+  revision: string;
+}
+
+/**
+ * `POST /api/note/:slug` request body.
+ *
+ * Every field optional, and that is not laziness — it mirrors core's
+ * `UpdateNoteInput`, where a metadata-only edit (retagging) and a body-only
+ * edit (the textarea) are both first-class. A body of `{}` is a legal
+ * request that bumps `updated` and nothing else.
+ */
+export interface SaveNoteRequest {
+  /** Replacement Markdown body. Omit to change only metadata. */
+  body?: string;
+  /**
+   * Metadata to merge over the note's current values.
+   *
+   * `created` is absent by construction: it records when the note came into
+   * existence and an edit is not a re-creation. `updated` is absent because
+   * the server owns it — a client that could set it could make an edit look
+   * older than the state it overwrote.
+   */
+  meta?: {
+    title?: string;
+    tags?: string[];
+    source?: WireNoteSource;
+  };
+  /**
+   * The {@link NotePayload.revision} the client last read.
+   *
+   * Supply it and a stale save is refused with `409` and a
+   * {@link ConflictPayload} carrying the note as it now is. Omit it and the
+   * save is last-write-wins — which is a legitimate thing for the *user* to
+   * choose after seeing a conflict, and is exactly how "overwrite" is
+   * expressed: the same request, resent without this field.
+   */
+  expectedRevision?: string;
+}
+
+/** `POST /api/note/:slug/rename` request body. */
+export interface RenameNoteRequest {
+  /**
+   * The destination. Passed through core's `slugify`, so a human title is
+   * as acceptable as a slug and both land on the same file name.
+   */
+  slug: string;
+}
+
+/** `DELETE /api/note/:slug` response. Hard delete — there is no trash. */
+export interface DeleteNoteResult {
+  deleted: true;
+}
+
+/**
+ * The `409` body for both write routes.
+ *
+ * A discriminated union rather than one shape with optional halves, because
+ * the two cases carry genuinely different payloads and a client that has to
+ * check `current !== undefined` before it can tell them apart is a client
+ * that will one day forget to.
+ *
+ * The `conflict` arm carries the **whole current note**, not just its
+ * revision. That is the difference between a UI that can offer
+ * reload-or-overwrite immediately and one that has to issue a second request
+ * before it can say anything useful — and the second request is one more
+ * window in which the file moves again. Core hands the server this note as
+ * part of the failure, so shipping it costs nothing.
+ */
+export type ConflictPayload =
+  | {
+      error: string;
+      reason: "conflict";
+      /** The note as it is on disk right now, with its current revision. */
+      current: NotePayload;
+    }
+  | {
+      error: string;
+      reason: "collision";
+      /** The destination slug that is already taken. */
+      slug: string;
+    };
+
+/** `GET /api/okf/:rel`. */
+export interface OkfFilePayload {
+  /** The requested path, relative to `<cwd>/.okf`. Echoed, never resolved. */
+  path: string;
+  body: string;
+}
+
+/** `GET /api/search?q=`. */
+export interface SearchPayload {
+  query: string;
+  hits: NoteSearchHit[];
+}
+
+/** `POST /api/open` request body. */
+export interface OpenRequest {
+  slug: string;
+}
+
+/** `POST /api/open` response. `false` for an unsafe slug or a missing note. */
+export interface OpenResult {
+  opened: boolean;
+}
+
+/**
+ * Every non-2xx JSON response. One shape for all of them so the client has
+ * exactly one error path.
+ */
+export interface ErrorPayload {
+  error: string;
+}
+
+// --- page bootstrap ----------------------------------------------------------
+
+/** `id` of the `<script type="application/json">` block in the HTML shell. */
+export const BOOTSTRAP_ELEMENT_ID = "weave-bootstrap";
+
+/**
+ * The JSON block embedded in the shell, so the first paint knows where it is
+ * without a round trip.
+ */
+export interface Bootstrap {
+  /** Absolute path the workspace was started in. */
+  cwd: string;
+  /** Absolute path of the vault root. */
+  vaultRoot: string;
+  /**
+   * Random per-boot id. `EventSource` reconnects transparently across a
+   * server restart, so without this a client cannot distinguish two cases it
+   * must handle differently: "I missed some frames" (refetch) and "this is a
+   * different server" (full reload).
+   */
+  session: string;
+}