pi-weave 0.1.7 → 0.1.8

package/src/web/client/workspace.ts

@@ -0,0 +1,214 @@
+/**
+ * The controller: fetches, signals, and the SSE loop joined up
+ * (weave-workspace §1.3, §6).
+ *
+ * Three modules already exist and none of them knows about the others —
+ * `api.ts` fetches, `live.ts` listens, `state.ts` holds. This is the seam
+ * that connects them, and it is a plain `.ts` with every dependency injected
+ * so it is covered by ordinary tests: `fetch` comes in as a {@link FetchLike}
+ * and the socket as an {@link EventSourceFactory}, exactly as those modules
+ * were designed to allow.
+ *
+ * Keeping it out of a component is what makes the shell's `useEffect` a
+ * two-liner (`start`, return `stop`). A `.tsx` cannot be tested here, so any
+ * decision that lands in one is a decision that ships uncovered.
+ *
+ * ## Refetch is ordered and conditional
+ *
+ * A plan can ask for both endpoints; the graph is fetched first because it
+ * carries the stamp that `seen()` records and therefore the dedupe key for
+ * every subsequent frame. Both requests are conditional in the sense that
+ * matters: the graph sends `If-None-Match` and a `304` costs an empty body,
+ * so "refetch everything on reconnect" (§6) is genuinely cheap rather than
+ * merely correct.
+ *
+ * ## Failures are absorbed, not thrown
+ *
+ * `api.ts` returns a discriminated result precisely so this layer never
+ * catches. A failed refetch leaves the previous signal value in place — a
+ * stale graph is strictly better than a blank workspace, and the next frame
+ * or the `⟳` button retries. The connection indicator, driven separately by
+ * the socket, is what tells the user something is wrong.
+ */
+
+import type { NotePayload } from "../shared/wire";
+import type { ApiResult, FetchLike } from "./api";
+import { fetchGraph, fetchNote } from "./api";
+import type { EventSourceFactory, LiveHandle } from "./live";
+import { startLive } from "./live";
+import type { RefetchPlan } from "./live.model";
+import { connection, graph, noteBody, selectedId } from "./state";
+
+/** What {@link startWorkspace} needs. Everything injectable is injected. */
+export interface WorkspaceOptions {
+  fetch: FetchLike;
+  /** Socket constructor. `domEventSource` at the real call site. */
+  open: EventSourceFactory;
+  /** Overrides the SSE path. Tests use it; the shell does not. */
+  path?: string;
+}
+
+/**
+ * Told about every note that arrives, so the editor can decide (§6, P5).
+ *
+ * A module-level hook rather than a parameter threaded through five call
+ * sites, because a note reaches the column from three unrelated directions —
+ * the mount fetch, a selection, and an SSE refetch — and the editor's
+ * decision ("is this the note I am editing, at a revision I do not hold?")
+ * has to be made on all three or it is made on none. The alternative was
+ * `loadNote` taking a callback that every caller had to remember to pass.
+ *
+ * Set by the shell at mount and cleared on unmount, exactly like
+ * `Shell.tsx`'s `fit` ref. `null` — the shape every test that does not care
+ * about editing sees — means the load simply publishes and nothing else
+ * happens.
+ */
+let onNoteLoaded: ((payload: NotePayload) => void) | null = null;
+
+/** Register the editor's load hook. Returns an unsubscribe. */
+export function observeNotes(hook: (payload: NotePayload) => void): () => void {
+  onNoteLoaded = hook;
+  return () => {
+    // Only clear our own registration: two shells in one test process
+    // unmounting out of order must not blank a live hook.
+    if (onNoteLoaded === hook) onNoteLoaded = null;
+  };
+}
+
+/** A running workspace. */
+export interface WorkspaceHandle {
+  /** Force a full refetch — the header's `⟳`. */
+  refresh(): void;
+  /** Fetch the body for the current selection, or clear it. */
+  syncNote(): Promise<void>;
+  /** Close the socket. Idempotent. */
+  stop(): void;
+}
+
+/**
+ * Fetch the graph and publish it.
+ *
+ * The stamp is handed to {@link LiveHandle.seen} only on success, which is
+ * the invariant `live.model.ts` documents: a stamp recorded for a fetch that
+ * failed would dedupe away the very frame that would have retried it.
+ *
+ * A `304` arrives as `cached: true` with the caller's own payload, so
+ * re-assigning the signal would be a no-op write that still wakes every
+ * subscriber. Skipping it is the difference between an idle workspace doing
+ * nothing and one re-rendering three columns every time the watcher twitches.
+ */
+async function loadGraph(fetchImpl: FetchLike, live: LiveHandle | null): Promise<ApiResult<unknown>> {
+  const result = await fetchGraph(fetchImpl, graph.value);
+  if (!result.ok) return result;
+  if (!result.cached) graph.value = result.data;
+  live?.seen(result.data.stamp);
+  return result;
+}
+
+/**
+ * Fetch the selected note's body, or clear it.
+ *
+ * The selection is a graph node id, and only *note* nodes have a body — the
+ * repository, git-state and file nodes do not. `note:` is the prefix core's
+ * graph builder gives them; anything else clears the column rather than
+ * issuing a request the server would answer `404`.
+ */
+async function loadNote(fetchImpl: FetchLike): Promise<void> {
+  const slug = noteSlug(selectedId.value);
+  if (slug === null) {
+    noteBody.value = null;
+    return;
+  }
+  const result = await fetchNote(fetchImpl, slug);
+  // A failed note fetch leaves the previous body on screen. The alternative —
+  // blanking the column on a transient error — throws away readable content
+  // to display nothing, and the note is usually still there.
+  if (!result.ok) return;
+  noteBody.value = result.data;
+  // After the signal, not before: the editor's decision may leave the draft
+  // in place *while* the column's read-mode rendering shows the new version,
+  // and the two are independent. Publishing second would let the editor see
+  // a payload the rest of the workspace does not yet hold.
+  onNoteLoaded?.(result.data);
+}
+
+/**
+ * The slug inside a `note:<slug>` node id, or `null` for any other node.
+ *
+ * Exported because it is the one piece of id-shape knowledge in this file and
+ * it deserves a test of its own rather than being reached only through a
+ * fetch. An empty slug (`"note:"`) is rejected: it would produce a request
+ * for `/api/note/` and a 404 that means nothing to anyone.
+ */
+export function noteSlug(id: string | null): string | null {
+  if (id === null || !id.startsWith("note:")) return null;
+  const slug = id.slice("note:".length);
+  return slug === "" ? null : slug;
+}
+
+/**
+ * Boot the workspace: first graph fetch, then the event stream.
+ *
+ * In that order, deliberately. The mount fetch seeds the stamp via `seen()`,
+ * so the hello frame `sse.ts` sends every newly attached client is recognised
+ * as already-held and deduped away. Opening the socket first would make the
+ * first frame arrive before there is a stamp to compare it to, and the
+ * workspace would fetch the same graph twice on every single load.
+ */
+export function startWorkspace(opts: WorkspaceOptions): WorkspaceHandle {
+  let live: LiveHandle | null = null;
+
+  const runPlan = (plan: RefetchPlan): void => {
+    // Fire-and-forget: this is called from a socket callback, which cannot
+    // await. Failures are values (`api.ts`), so there is nothing to reject —
+    // `void` documents that rather than hiding a floating promise.
+    void (async () => {
+      if (plan.graph) await loadGraph(opts.fetch, live);
+      if (plan.note) await loadNote(opts.fetch);
+    })();
+  };
+
+  live = startLive({
+    open: opts.open,
+    refetch: runPlan,
+    hasSelection: () => noteSlug(selectedId.value) !== null,
+    ...(opts.path === undefined ? {} : { path: opts.path }),
+  });
+
+  void loadGraph(opts.fetch, live);
+
+  return {
+    refresh() {
+      live?.refresh();
+    },
+    syncNote() {
+      return loadNote(opts.fetch);
+    },
+    stop() {
+      live?.stop();
+      live = null;
+    },
+  };
+}
+
+/**
+ * Select a node — the §1.3 context bus, in one function.
+ *
+ * Writing `selectedId` is the whole mechanism; the note fetch that follows is
+ * a *consequence* of the write, not part of it, which is why the signal is
+ * set before the fetch is issued. Every column that derives from the
+ * selection updates on the synchronous write, so the UI responds immediately
+ * and the body arrives when it arrives.
+ */
+export function select(fetchImpl: FetchLike, id: string | null): Promise<void> {
+  selectedId.value = id;
+  return loadNote(fetchImpl);
+}
+
+/** Reset every signal. The shell's unmount path, and every test's cleanup. */
+export function resetWorkspace(): void {
+  selectedId.value = null;
+  graph.value = null;
+  noteBody.value = null;
+  connection.value = "live";
+}

package/src/web/server/page.ts

@@ -0,0 +1,256 @@
+/**
+ * The HTML shell (weave-workspace §5.2, §5.3, §9).
+ *
+ * Four elements and nothing else: a nonce'd `<style>` carrying the CSS
+ * variable theme, `<div id="app">`, a nonce'd JSON bootstrap block, and
+ * `<script nonce src="/app.js">`. All behaviour lives in the committed
+ * bundle; this file exists to deliver a nonce, a CSP header and three
+ * strings of context.
+ *
+ * ## Why the no-backtick guard survived the rewrite
+ *
+ * §9 retired the *source* guard for `dist/app.js` in favour of a stronger
+ * invariant — `build:web:check` byte-compares the committed bundle against a
+ * fresh build, so the shipped artifact provably matches its source. That
+ * argument does not transfer here, because this file is not generated: it is
+ * a template literal into which `cwd`, `vaultRoot` and a session id are
+ * interpolated, and it is therefore still an injection surface. A vault path
+ * containing `</script>` is not a hypothetical — it is one `mkdir` away.
+ *
+ * So the guard stays, in two forms, both in `tests/web/page.test.ts`:
+ *
+ *  1. **Output**: the rendered page contains no `` ` `` and no `${`. Every
+ *     escaper below emits those as numeric entities or `\u` escapes, so a
+ *     hit means an interpolation reached the output raw.
+ *  2. **Source**: every `${…}` in this file's template is a call to one of
+ *     {@link escapeHtml}, {@link escapeAttr} or {@link jsonScriptBody}. This
+ *     is the stronger half — the output guard can only catch a leak that a
+ *     *test fixture* happens to trigger, while the source guard catches the
+ *     unescaped interpolation itself, on the commit that adds it.
+ *
+ * ## CSP
+ *
+ * `default-src 'none'` and a per-response nonce. Nothing loads that we did
+ * not name: no `'unsafe-inline'`, no `'unsafe-eval'`, no `blob:`, no remote
+ * origin. `connect-src 'self'` is what permits `/api/*` and the `/events`
+ * stream; `frame-ancestors 'none'` means no page can embed us, which
+ * matters because a framed workspace plus a stolen click is a way to reach
+ * `POST /api/open`.
+ *
+ * The nonce is fresh per response (16 bytes). Reuse across responses would
+ * make it a static secret that any successful injection could simply read
+ * from the previous page and replay.
+ */
+
+import { randomBytes } from "node:crypto";
+import type { Bootstrap } from "../shared/wire";
+import { BOOTSTRAP_ELEMENT_ID } from "../shared/wire";
+
+/** Nonce entropy, in bytes. 128 bits — CSP requires ≥ 128. */
+export const NONCE_BYTES = 16;
+
+/** A fresh per-response CSP nonce. */
+export function generateNonce(): string {
+  return randomBytes(NONCE_BYTES).toString("base64");
+}
+
+/**
+ * A nonce, validated for use inside a CSP header.
+ *
+ * The third escaper, and the odd one out: HTML escaping is *wrong* here,
+ * because a `&quot;` in a header value is a literal `&quot;`, not a quote.
+ * What a header needs is a character-set check — a nonce containing `;`,
+ * `'`, CR or LF would either terminate the directive early (turning
+ * `script-src` into something permissive) or split the header outright.
+ *
+ * Base64 is a strict subset of what CSP's `base64-value` grammar allows, so
+ * requiring it costs nothing and makes the failure loud. It throws rather
+ * than sanitising: a nonce that is not base64 did not come from
+ * {@link generateNonce}, and quietly repairing it would hide the bug that
+ * produced it.
+ */
+export function cspNonce(nonce: string): string {
+  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(nonce)) throw new Error("pi-weave: CSP nonce must be base64");
+  return nonce;
+}
+
+/**
+ * The §5.2 policy, bound to one nonce.
+ *
+ * Emitted as a single line with `; ` separators. `tests/web/routes.test.ts`
+ * asserts the exact string — a policy that drifts silently is a policy that
+ * has already stopped protecting anything.
+ */
+export function contentSecurityPolicy(nonce: string): string {
+  return [
+    "default-src 'none'",
+    `script-src 'nonce-${cspNonce(nonce)}'`,
+    `style-src 'nonce-${cspNonce(nonce)}'`,
+    "img-src 'self' data:",
+    "connect-src 'self'",
+    "font-src 'self'",
+    "base-uri 'none'",
+    "form-action 'none'",
+    "frame-ancestors 'none'",
+  ].join("; ");
+}
+
+// --- escaping ----------------------------------------------------------------
+
+/**
+ * The five HTML-significant characters, plus `` ` `` and `$`.
+ *
+ * The last two are not HTML-significant and are escaped anyway, to keep the
+ * output guard above meaningful: if `` ` `` can never appear in rendered
+ * output, then finding one is unambiguous evidence of a raw interpolation
+ * rather than a false positive from a note title that happened to contain a
+ * code span. `&#96;` and `&#36;` render identically to the user.
+ */
+const HTML_ESCAPES: Readonly<Record<string, string>> = {
+  "&": "&amp;",
+  "<": "&lt;",
+  ">": "&gt;",
+  '"': "&quot;",
+  "'": "&#39;",
+  "`": "&#96;",
+  $: "&#36;",
+};
+
+/**
+ * The character class matching exactly {@link HTML_ESCAPES}' keys.
+ *
+ * Derived from the map rather than written twice, so the two cannot drift —
+ * a key added to the map without a matching regex edit would be a character
+ * that silently stops being escaped, which is the quietest possible way to
+ * introduce an XSS.
+ */
+const HTML_ESCAPE_PATTERN = new RegExp(
+  // Built by concatenation rather than a template literal so the source
+  // guard in `tests/web/page.test.ts` stays absolute: *every* `${…}` in this
+  // file is an escaper call, with no exemptions to remember.
+  "[" + Object.keys(HTML_ESCAPES).map((ch) => "\\" + ch).join("") + "]",
+  "g",
+);
+
+/** Escape a value for HTML text content. */
+export function escapeHtml(value: string): string {
+  // The regex is built from the map's keys, so every match has an entry.
+  // Asserted rather than left as a `?? ch` fallback, which would be a dead
+  // branch dressed up as safety — and one that fails *open*, emitting the
+  // raw character it was supposed to escape.
+  return value.replace(HTML_ESCAPE_PATTERN, (ch) => HTML_ESCAPES[ch] as string);
+}
+
+/**
+ * Escape a value for a double-quoted attribute.
+ *
+ * Identical to {@link escapeHtml} today — the set of characters that can
+ * break out of a quoted attribute is a subset of the set that can break out
+ * of text. Kept as a distinct name because the *call site* documents intent,
+ * and because an attribute-specific rule (escaping whitespace, for unquoted
+ * attributes) is the obvious future divergence.
+ */
+export function escapeAttr(value: string): string {
+  return escapeHtml(value);
+}
+
+/**
+ * Serialize a value for embedding inside `<script type="application/json">`.
+ *
+ * `JSON.stringify` alone is **not** safe here. The HTML parser looks for
+ * `</script` inside a script element before the JSON parser ever sees the
+ * bytes, so a string containing it terminates the element early and
+ * everything after is parsed as markup. `<!--` opens an HTML comment with
+ * the same effect. Escaping `<` and `>` to `\u003c` / `\u003e` closes both,
+ * and is transparent to `JSON.parse`.
+ *
+ * `&`, `` ` `` and `$` follow for the same reason as in {@link HTML_ESCAPES}:
+ * so the output guard has no legitimate exceptions to carve out.
+ *
+ * U+2028 and U+2029 are escaped because they are valid in JSON strings but
+ * are line terminators in JavaScript source — a hazard if this block is ever
+ * read with `eval`-adjacent machinery rather than `JSON.parse`.
+ */
+export function jsonScriptBody(value: unknown): string {
+  return JSON.stringify(value).replace(
+    /[<>&`$\u2028\u2029]/g,
+    (ch) => "\\u" + ch.charCodeAt(0).toString(16).padStart(4, "0"),
+  );
+}
+
+// --- rendering ---------------------------------------------------------------
+
+export interface RenderPageOptions {
+  bootstrap: Bootstrap;
+  /** Defaults to a fresh {@link generateNonce}. Injectable for tests. */
+  nonce?: string;
+}
+
+export interface RenderedPage {
+  html: string;
+  nonce: string;
+  /** The exact `Content-Security-Policy` header value for this response. */
+  csp: string;
+}
+
+/**
+ * The theme, as CSS custom properties.
+ *
+ * A constant, never interpolated, so it cannot carry user input. It stays in
+ * the shell rather than the bundle so the first paint has a background
+ * colour before `app.js` parses — a dark-mode user should not get a white
+ * flash while 21 KB of JavaScript loads.
+ */
+const THEME_CSS = [
+  ":root{color-scheme:light dark;",
+  "--weave-bg:#faf9f7;--weave-fg:#1c1b19;--weave-dim:#6f6b66;",
+  "--weave-line:#e3e0dc;--weave-accent:#7a5cff;--weave-warn:#c2410c;",
+  "--weave-mono:ui-monospace,SFMono-Regular,Menlo,monospace;",
+  "--weave-sans:ui-sans-serif,system-ui,-apple-system,Segoe UI,sans-serif}",
+  "@media(prefers-color-scheme:dark){:root{",
+  "--weave-bg:#16151a;--weave-fg:#eceaf0;--weave-dim:#9a95a3;",
+  "--weave-line:#2c2a33;--weave-accent:#a48cff;--weave-warn:#fb923c}}",
+  "*{box-sizing:border-box}",
+  "html,body{height:100%}",
+  "body{margin:0;background:var(--weave-bg);color:var(--weave-fg);",
+  "font-family:var(--weave-sans);font-size:14px;line-height:1.5}",
+  "#app{height:100%;display:flex;flex-direction:column}",
+].join("");
+
+/**
+ * Render the shell.
+ *
+ * Returns the nonce and the CSP alongside the HTML rather than setting a
+ * header itself: the caller owns the response, and coupling a renderer to
+ * `ServerResponse` would make it untestable without a socket. The invariant
+ * that the header and the document agree on the nonce is held by
+ * `routes.ts`, which receives both from this one call.
+ */
+export function renderPage(opts: RenderPageOptions): RenderedPage {
+  const nonce = opts.nonce ?? generateNonce();
+  const html = [
+    "<!doctype html>",
+    '<html lang="en">',
+    "<head>",
+    '<meta charset="utf-8">',
+    '<meta name="viewport" content="width=device-width,initial-scale=1">',
+    '<meta name="referrer" content="no-referrer">',
+    "<title>pi-weave workspace</title>",
+    `<style nonce="${escapeAttr(nonce)}">`,
+    THEME_CSS,
+    "</style>",
+    "</head>",
+    "<body>",
+    `<div id="app" data-cwd="${escapeAttr(opts.bootstrap.cwd)}">`,
+    "<noscript>pi-weave needs JavaScript. Use <code>/weave-view tui</code> instead.</noscript>",
+    "</div>",
+    `<script type="application/json" id="${escapeAttr(BOOTSTRAP_ELEMENT_ID)}" nonce="${escapeAttr(nonce)}">`,
+    jsonScriptBody(opts.bootstrap),
+    "</script>",
+    `<script nonce="${escapeAttr(nonce)}" src="/app.js"></script>`,
+    "</body>",
+    "</html>",
+  ].join("\n");
+
+  return { html, nonce, csp: contentSecurityPolicy(nonce) };
+}