@nanocollective/roster 0.1.0-alpha.1

package/templates/portal/js/state.js

@@ -0,0 +1,160 @@
+/* Every screen's state in one object, and the URL that mirrors it.
+ *
+ * The URL is the state, so a refresh lands where you were and a link is shareable. Changing
+ * staff or view pushes; typing in a filter replaces, so a search does not bury the back
+ * button under one entry per keystroke.
+ *
+ * This used to be a wall of top-level `var`s in a classic script, kept as `var` on purpose
+ * because a top-level `let` is not reachable as a global and the state was otherwise
+ * untestable. As a module it is exported, so it is neither global nor hidden. */
+
+export const VIEWS = [
+  ["brain", "Brain"],
+  ["prompt", "Prompt"],
+  ["graph", "Graph"],
+  ["changed", "What changed"],
+  ["health", "Health"],
+];
+
+/* Memory used to be its own view. It is a surface of the brain — both manifests already
+   declare `memory/` with `render: memory` — so it is now the brain's first stop, and the
+   old links still land somewhere sensible. */
+export const VIEW_ALIAS = { memory: "brain" };
+
+/** Screens that belong to the org rather than to one staff member. */
+export const ORG_WIDE = new Set(["inbox", "org", "staff", "docs"]);
+
+export const S = {
+  /** The org export from /api/org. Everything the brain screens read comes off this. */
+  data: null,
+  docs: null,
+  inbox: null,
+  sync: null,
+  loadedAt: null,
+
+  staffHandle: null,
+  view: "brain",
+  /** The inbox filter box. Brain and "what changed" keep their own, below. */
+  query: "",
+
+  /* What the brain's right pane is showing: a file path, or one of the memory pseudo-paths
+     `mem:*`, `mem:<section>`, `fact:<slug>`. One key, so the URL carries either. */
+  openFile: null,
+  fileQuery: "",
+  /** Which surfaces are unfolded in the brain navigator. Not in the URL: it is furniture. */
+  openSurfaces: null,
+
+  changedQuery: "",
+  changedFilter: "",
+
+  openDoc: null,
+
+  /** Which kind of run the Prompt screen is showing, and which layer of it is open. */
+  promptKind: "daily",
+  promptOpen: null,
+
+  /** Which org-layer file the Org screen is showing. */
+  orgOpen: null,
+
+  inboxFilter: "",
+  inboxStaff: "",
+  /** "" is open only, which is what an inbox is for. `closed` and `all` widen it. */
+  inboxState: "",
+  inboxOpen: null,
+
+  applyingHash: false,
+};
+
+/* The sidebar badge counts open items, not everything loaded. Once the inbox could show
+   closed work the two stopped being the same number, and a badge that says 135 when 34 things
+   need you is worse than no badge. */
+export const openCount = () =>
+  (S.inbox?.items ?? []).filter((i) => i.state === "OPEN").length;
+
+export const staff = () => S.data.staff.find((s) => s.handle === S.staffHandle) ?? S.data.staff[0];
+
+export function readHash() {
+  const raw = (location.hash || "").replace(/^#\/?/, "");
+  if (!raw) return null;
+  const [path, qs] = raw.split("?");
+  const [handle, view] = path.split("/");
+  const p = new URLSearchParams(qs || "");
+  return {
+    handle,
+    view,
+    q: p.get("q") || "",
+    f: p.get("f") || null,
+    k: p.get("k") || "",
+    x: p.get("x") || "",
+    s: p.get("s") || "",
+    w: p.get("w") || "",
+    t: p.get("t") || null,
+    p: p.get("p") || null,
+  };
+}
+
+export function writeHash(push) {
+  if (S.applyingHash) return;
+  if (!S.staffHandle && !ORG_WIDE.has(S.view)) return;
+  const params = new URLSearchParams();
+  const q = S.view === "brain" ? S.fileQuery : S.view === "changed" ? S.changedQuery : S.query;
+  if (q) params.set("q", q);
+  if (S.view === "brain" && S.openFile) params.set("f", S.openFile);
+  if (S.view === "docs" && S.openDoc) params.set("p", S.openDoc);
+  if (S.view === "org" && S.orgOpen) params.set("f", S.orgOpen);
+  if (S.view === "prompt") {
+    if (S.promptKind !== "daily") params.set("k", S.promptKind);
+    if (S.promptOpen) params.set("f", S.promptOpen);
+  }
+  if (S.view === "inbox") {
+    if (S.inboxFilter) params.set("s", S.inboxFilter);
+    if (S.inboxStaff) params.set("w", S.inboxStaff);
+    if (S.inboxState) params.set("x", S.inboxState);
+    if (S.inboxOpen) {
+      params.set("t", S.inboxOpen.repo + "#" + S.inboxOpen.number + ":" + S.inboxOpen.kind);
+    }
+  }
+  const qs = params.toString();
+  const next = "#/" + (S.staffHandle ?? "-") + "/" + S.view + (qs ? "?" + qs : "");
+  if (location.hash === next) return;
+  if (history.pushState) history[push ? "pushState" : "replaceState"](null, "", next);
+  else location.hash = next;
+}
+
+export function applyHash() {
+  const h = readHash();
+  if (!h) return false;
+  const known = S.data.staff.some((s) => s.handle === h.handle);
+  if (known) S.staffHandle = h.handle;
+  const asked = VIEW_ALIAS[h.view] ?? h.view;
+  if (ORG_WIDE.has(asked) || VIEWS.some(([id]) => id === asked)) S.view = asked;
+
+  if (S.view === "brain") {
+    S.fileQuery = h.q;
+    S.openFile = h.f;
+  } else if (S.view === "changed") {
+    S.changedQuery = h.q;
+  } else {
+    S.query = h.q;
+  }
+
+  if (S.view === "docs") S.openDoc = h.p;
+  if (S.view === "org") S.orgOpen = h.f;
+
+  if (S.view === "prompt") {
+    S.promptKind = h.k || "daily";
+    S.promptOpen = h.f;
+  }
+
+  if (S.view === "inbox") {
+    S.inboxFilter = h.s;
+    S.inboxStaff = h.w;
+    S.inboxState = h.x;
+    if (h.t) {
+      const [repoNum, kind] = h.t.split(":");
+      const [repo, number] = repoNum.split("#");
+      S.inboxOpen = { repo, number: Number(number), kind: kind === "pr" ? "pr" : "issue" };
+    }
+  }
+  return known;
+}

package/templates/portal/js/textdiff.js

@@ -0,0 +1,96 @@
+/* A unified diff between two strings, in the format `renderDiff` already parses.
+ *
+ * Editing a layer changes a file, but what you meant to change is the composed prompt, and
+ * those are not the same thing: a line added to one fragment can land three times or not at
+ * all. Showing the file diff would answer a question nobody asked.
+ *
+ * There is no git here, so the diff is computed in the page. Plain LCS: these are a few
+ * hundred lines of prose, and anything cleverer would be solving a problem this does not have.
+ */
+
+export function unifiedDiff(before, after, name, context = 3) {
+  const a = String(before).split("\n");
+  const b = String(after).split("\n");
+  const ops = lcsOps(a, b);
+  if (!ops.some((o) => o.op !== " ")) return "";
+
+  /* Only the neighbourhood of a change is worth printing. A whole 400-line prompt with six
+     lines highlighted is not a diff, it is the prompt again. */
+  const keep = new Set();
+  ops.forEach((o, i) => {
+    if (o.op === " ") return;
+    for (let j = Math.max(0, i - context); j <= Math.min(ops.length - 1, i + context); j++) {
+      keep.add(j);
+    }
+  });
+
+  const out = ["diff --git a/" + name + " b/" + name];
+  let i = 0;
+  let oldNo = 1;
+  let newNo = 1;
+  // Walk once, emitting a hunk each time the kept region starts again.
+  const lineNos = ops.map((o) => {
+    const at = { old: oldNo, new: newNo };
+    if (o.op !== "+") oldNo++;
+    if (o.op !== "-") newNo++;
+    return at;
+  });
+
+  while (i < ops.length) {
+    if (!keep.has(i)) {
+      i++;
+      continue;
+    }
+    let end = i;
+    while (end + 1 < ops.length && keep.has(end + 1)) end++;
+    const rows = ops.slice(i, end + 1);
+    const oldCount = rows.filter((o) => o.op !== "+").length;
+    const newCount = rows.filter((o) => o.op !== "-").length;
+    out.push(`@@ -${lineNos[i].old},${oldCount} +${lineNos[i].new},${newCount} @@`);
+    for (const row of rows) out.push(row.op + row.text);
+    i = end + 1;
+  }
+  return out.join("\n");
+}
+
+/** Longest common subsequence, as a flat list of ` `, `-` and `+` rows. */
+function lcsOps(a, b) {
+  const n = a.length;
+  const m = b.length;
+  const grid = new Uint32Array((n + 1) * (m + 1));
+  const at = (i, j) => i * (m + 1) + j;
+  for (let i = n - 1; i >= 0; i--) {
+    for (let j = m - 1; j >= 0; j--) {
+      grid[at(i, j)] =
+        a[i] === b[j]
+          ? grid[at(i + 1, j + 1)] + 1
+          : Math.max(grid[at(i + 1, j)], grid[at(i, j + 1)]);
+    }
+  }
+  const ops = [];
+  let i = 0;
+  let j = 0;
+  while (i < n && j < m) {
+    if (a[i] === b[j]) {
+      ops.push({ op: " ", text: a[i] });
+      i++;
+      j++;
+    } else if (grid[at(i + 1, j)] >= grid[at(i, j + 1)]) {
+      ops.push({ op: "-", text: a[i++] });
+    } else {
+      ops.push({ op: "+", text: b[j++] });
+    }
+  }
+  while (i < n) ops.push({ op: "-", text: a[i++] });
+  while (j < m) ops.push({ op: "+", text: b[j++] });
+  return ops;
+}
+
+/** How much moved, for a one-line summary beside the commit. */
+export function diffStat(before, after) {
+  const ops = lcsOps(String(before).split("\n"), String(after).split("\n"));
+  return {
+    added: ops.filter((o) => o.op === "+").length,
+    removed: ops.filter((o) => o.op === "-").length,
+  };
+}

package/templates/portal/js/views/app.js

@@ -0,0 +1,128 @@
+/* Creating a staff member's GitHub App, from the page you are already on.
+ *
+ * There is no API that creates a GitHub App. The only route is the manifest flow: post a
+ * manifest to a settings page, a human confirms, GitHub hands back a one-time code. `roster app`
+ * does that by standing up a second server on 4310; here it runs on the portal's own port, so
+ * it is one browser, one origin, and nothing extra to explain.
+ *
+ * What it still cannot do is install the App. Installing is a grant of access to specific
+ * repositories and GitHub asks a human to choose them, which is correct behaviour and should not
+ * be worked around. */
+
+import { appResult, startApp } from "../api.js";
+import { el } from "../dom.js";
+
+/**
+ * @param {{staff: string, name: string, scope?: "private"|"public", onDone?: () => void}} opts
+ */
+export function appPanel(opts) {
+  const scope = opts.scope ?? "private";
+  const box = el("div", { className: "manual" });
+  box.append(
+    el("b", {
+      textContent:
+        scope === "public"
+          ? "Create the shared public identity"
+          : `Create ${opts.name}'s GitHub App`,
+    }),
+    el("p", {
+      textContent:
+        "A tab opens, GitHub asks you to confirm, and the App's id and private key go straight " +
+        "into the repo's secrets. The key is held in memory and never written to disk.",
+    }),
+  );
+
+  const go = el("button", { className: "btn primary", textContent: "Create the App" });
+  const out = el("div", { style: "margin-top:9px" });
+  box.append(el("div", { className: "row" }, [go]), out);
+
+  go.onclick = async () => {
+    go.disabled = true;
+    out.replaceChildren(el("p", { className: "sub", textContent: "Preparing the hand-off…" }));
+    let started;
+    try {
+      started = await startApp(opts.staff, scope);
+    } catch (err) {
+      go.disabled = false;
+      /* The common failure is a name already taken, and the server sends the install URL with
+         it: an App that exists is not a problem, it is a step you have already done. */
+      const note = el("div");
+      note.append(el("p", { className: "err", textContent: String(err.message || err) }));
+      out.replaceChildren(note);
+      return;
+    }
+
+    window.open(started.start, "_blank");
+    out.replaceChildren(
+      el("p", {
+        className: "sub",
+        textContent: "Confirm it in the tab that just opened. This will update when it lands.",
+      }),
+    );
+
+    /* GitHub redirects the *other* tab back to this server, so there is no callback to await
+       here. Polling for the result the callback recorded is the only thing this tab can do. */
+    const started_at = Date.now();
+    const tick = async () => {
+      let result;
+      try {
+        result = await appResult(started.state);
+      } catch {
+        result = { pending: true };
+      }
+      if (result.pending) {
+        if (Date.now() - started_at > 5 * 60 * 1000) {
+          out.replaceChildren(
+            el("p", {
+              className: "sub",
+              textContent:
+                "Still waiting. If you finished in the other tab and nothing happened here, " +
+                "reload — the App may well have been created.",
+            }),
+          );
+          go.disabled = false;
+          return;
+        }
+        setTimeout(tick, 2000);
+        return;
+      }
+
+      go.disabled = false;
+      if (!result.ok) {
+        out.replaceChildren(el("p", { className: "err", textContent: String(result.error) }));
+        return;
+      }
+
+      /* The install is the step that most often looks done and is not, so it is the loudest
+         thing on the page once the App exists. */
+      const done = el("div");
+      done.append(
+        el("p", { textContent: `${result.slug} created, and its secrets are set.` }),
+        el("b", { textContent: "It still has to be installed." }),
+        el("p", {
+          className: "sub",
+          textContent:
+            "Grant it every tracker this staff member writes to, not just their own: the token " +
+            "is minted organisation-wide and a peer's board is where a brief lands.",
+        }),
+        el("a", {
+          className: "btn primary",
+          href: result.install,
+          target: "_blank",
+          textContent: "Install it",
+        }),
+        el("p", {
+          className: "sub",
+          textContent:
+            "Do not verify this by reading the API. It reports what an App declares separately " +
+            "from what an installation was granted. Only a run that finished proves the chain.",
+        }),
+      );
+      out.replaceChildren(done);
+      opts.onDone?.();
+    };
+    setTimeout(tick, 2000);
+  };
+
+  return box;
+}

package/templates/portal/js/views/brain.js

@@ -0,0 +1,260 @@
+/* The brain screen.
+ *
+ * Memory and the file tree were two screens showing one thing, and both manifests already
+ * declare `memory/` as a surface with `render: memory`. So it is one screen — but one screen
+ * is not one list. The navigator is two boxes, because a parsed memory section and a file on
+ * disk are different kinds of thing and the old flat list told them apart only by typeface.
+ *
+ * The `memory/` surface's own files are folded into Memory rather than repeated under Files:
+ * `INDEX.md` is literally what "All facts" renders, and `notes/x.md` is the argument behind a
+ * fact. Listing them twice was most of what made this hard to read.
+ */
+
+import { el, kb } from "../dom.js";
+import { icon } from "../icons.js";
+import { S, staff, writeHash } from "../state.js";
+import { showFile, showGallery } from "./files.js";
+import { showMemory } from "./memory.js";
+
+/** Files a brain browser should not offer: placeholders that hold a directory open. */
+const NOISE = new Set([".gitkeep", ".keep", ".DS_Store"]);
+
+const isIndex = (path) => path === "memory/INDEX.md";
+const isNote = (path) => path.startsWith("memory/notes/");
+
+export function viewBrain(m) {
+  const s = staff();
+  if (!S.openSurfaces) S.openSurfaces = new Map();
+
+  const allFiles = s.surfaces.flatMap((x) => x.files).filter((f) => !NOISE.has(base(f.path)));
+  const notes = allFiles.filter((f) => isNote(f.path));
+  /* What Files is actually for: everything that is not the memory index or a note behind a
+     fact, both of which Memory already renders properly. */
+  const plain = allFiles.filter((f) => !isIndex(f.path) && !isNote(f.path));
+
+  m.append(el("h1", { textContent: s.name + " · brain" }));
+  m.append(
+    el("p", {
+      className: "sub",
+      textContent:
+        s.facts.length + " facts in " + s.sections.length + " sections, " + notes.length +
+        " notes · " + plain.length + " other files across " + s.surfaces.length + " surfaces.",
+    }),
+  );
+
+  const filter = el("input", {
+    type: "search",
+    placeholder: "Search facts and files…",
+    value: S.fileQuery,
+  });
+  const count = el("span", { className: "meta" });
+  m.append(el("div", { className: "row", style: "margin-bottom:16px" }, [filter, count]));
+
+  const split = el("div", { className: "split" });
+  const tree = el("div", { className: "tree" });
+  const viewer = el("div", { className: "viewer" });
+  split.append(tree, viewer);
+  m.append(split);
+
+  filter.oninput = () => {
+    S.fileQuery = filter.value;
+    writeHash(false);
+    paintTree();
+  };
+
+  // Memory is where a brain starts, so it is what you land on.
+  if (!S.openFile) S.openFile = "mem:*";
+  paintTree();
+  openBrain(S.openFile);
+
+  /* ------------------------------ selection ----------------------------- */
+
+  function pick(key) {
+    S.openFile = key;
+    writeHash(false);
+    markTree();
+    openBrain(key);
+  }
+
+  /** Which row is open, and — when a single fact is focused — which section holds it, so
+      opening one fact never loses your place in the list above it. */
+  function withinKey() {
+    if (!S.openFile?.startsWith("fact:")) return null;
+    const f = s.facts.find((x) => x.slug === S.openFile.slice(5));
+    return f ? "mem:" + f.section : null;
+  }
+
+  /** Applied as a row is built and again when the selection moves without a repaint, so
+      picking a fact does not rebuild the tree and throw away its scroll position. */
+  function mark(b, within) {
+    b.setAttribute("aria-current", String(b.dataset.key === S.openFile));
+    if (within && b.dataset.key === within) b.dataset.within = "true";
+    else delete b.dataset.within;
+  }
+
+  function markTree() {
+    const within = withinKey();
+    for (const o of tree.querySelectorAll(".tfile")) mark(o, within);
+  }
+
+  /* -------------------------------- rows -------------------------------- */
+
+  function row(key, label, right, cls) {
+    const b = el("button", { className: "tfile" + (cls ? " " + cls : ""), title: label });
+    b.dataset.key = key;
+    b.append(el("span", { className: "t", textContent: label }));
+    if (right) b.append(el("i", { textContent: right }));
+    mark(b, withinKey());
+    b.onclick = () => pick(key);
+    return b;
+  }
+
+  /** A titled box in the navigator. Two of them: what the agent knows, and what it holds. */
+  function group(title, right) {
+    const g = el("div", { className: "navgroup" });
+    const h = el("div", { className: "ghead", textContent: title });
+    if (right) h.append(el("i", { textContent: right }));
+    g.append(h);
+    return g;
+  }
+
+  /** A folder that unfolds. Big surfaces start closed; a handful of files does not need it. */
+  function folder(g, key, label, kids, right) {
+    const open = S.openSurfaces.get(key) ?? kids.length <= 12;
+    const head = el("button", { className: "tsurface", title: label });
+    head.setAttribute("aria-expanded", String(open));
+    head.append(
+      icon("chevron", "caret"),
+      el("span", { className: "t", textContent: label }),
+      el("i", { textContent: right ?? String(kids.length) }),
+    );
+    const box = el("div", { className: "tsfiles" }, kids);
+    box.hidden = !open;
+    head.onclick = () => {
+      const now = !(S.openSurfaces.get(key) ?? kids.length <= 12);
+      S.openSurfaces.set(key, now);
+      head.setAttribute("aria-expanded", String(now));
+      box.hidden = !now;
+    };
+    g.append(head, box);
+  }
+
+  /* ------------------------------ the tree ------------------------------ */
+
+  function paintTree() {
+    const q = S.fileQuery.trim().toLowerCase();
+    tree.replaceChildren();
+
+    const hits = s.facts.filter((f) => matchesFact(f, q));
+    const noteHits = notes.filter((f) => !q || f.path.toLowerCase().includes(q));
+    const fileHits = plain.filter((f) => !q || f.path.toLowerCase().includes(q));
+
+    /* ---- memory ---- */
+    const mem = group("Memory", s.facts.length + " facts");
+    if (q) {
+      for (const f of hits.slice(0, 200)) mem.append(row("fact:" + f.slug, f.slug, "", "tmem"));
+      if (!hits.length) {
+        mem.append(el("div", { className: "tfile", textContent: "no facts match" }));
+      }
+    } else {
+      mem.append(row("mem:*", "All facts", String(s.facts.length), "tmem"));
+      for (const sec of s.sections) {
+        const n = s.facts.filter((f) => f.section === sec).length;
+        mem.append(row("mem:" + sec, sec, String(n), "tmem"));
+      }
+    }
+    if (noteHits.length) {
+      /* Labelled, because "notes" beside a list of memory sections reads as a mystery
+         drawer. A note is the argument behind one fact, read only when that fact is in
+         play, which is what keeps the index cheap enough to read at every boot. */
+      folder(
+        mem,
+        "notes",
+        "notes/ — why a fact holds",
+        noteHits.map((f) => row(f.path, base(f.path), kb(f.bytes))),
+        String(noteHits.length),
+      );
+    }
+    if (!q && allFiles.some((f) => isIndex(f.path))) {
+      mem.append(row("memory/INDEX.md", "INDEX.md — the raw index", "", "tmem"));
+    }
+    tree.append(mem);
+
+    /* ---- who they are ----
+       CHARTER.md and staff.yaml sit at the brain root and are in no declared surface, so
+       the portal could not show either of them. They are the two files that decide what
+       this staff member is, which made that a strange gap. */
+    if (!q) {
+      const id = group("Identity", "");
+      id.append(row("CHARTER.md", "CHARTER.md — the personality", "", "tmem"));
+      id.append(row("staff.yaml", "staff.yaml — the manifest", "", "tmem"));
+      tree.append(id);
+    }
+
+    /* ---- files ---- */
+    if (fileHits.length) {
+      const fg = group("Files", plain.length + " files");
+      for (const surface of s.surfaces) {
+        const fs = fileHits.filter((f) => surface.files.some((x) => x.path === f.path));
+        if (!fs.length) continue;
+        const kids = fs
+          .slice(0, 400)
+          .map((f) => row(f.path, f.path.replace(surface.path, "") || f.path, kb(f.bytes)));
+        // A gallery surface earns one extra row, in words rather than the manifest's jargon.
+        if (surface.render === "gallery" && !q) {
+          kids.unshift(row("gallery:" + surface.path, "View all as a gallery", ""));
+        }
+        folder(fg, surface.path, surface.path, kids);
+      }
+      tree.append(fg);
+    }
+
+    // Counted the same way the subtitle counts, so the two never disagree.
+    count.textContent = q
+      ? hits.length + " facts, " + noteHits.length + " notes, " + fileHits.length + " files"
+      : s.facts.length + " facts, " + notes.length + " notes, " + plain.length + " files";
+    if (q && !hits.length && !fileHits.length && !noteHits.length) {
+      tree.replaceChildren(el("p", { className: "empty", textContent: "Nothing matches." }));
+    }
+    markTree();
+  }
+
+  /* ------------------------------ the pane ------------------------------ */
+
+  function openBrain(key) {
+    if (key?.startsWith("gallery:")) {
+      const surface = s.surfaces.find((x) => x.path === key.slice(8));
+      if (surface) showGallery(viewer, s, surface);
+      return;
+    }
+    if (!key || key.startsWith("mem:") || key.startsWith("fact:")) {
+      showMemory(viewer, s, key || "mem:*", pick);
+      return;
+    }
+    const f = allFiles.find((x) => x.path === key) ?? rootFile(key);
+    if (!f) {
+      viewer.replaceChildren(
+        el("p", { className: "empty", textContent: "That file is not in this brain." }),
+      );
+      return;
+    }
+    showFile(viewer, s, f, pick);
+  }
+}
+
+const base = (path) => path.split("/").pop();
+
+/* A file at the brain root, which no surface declares. `bytes` and `modified` are only used
+   for the header line, and the renderer reads the file itself. */
+const ROOT_FILES = new Set(["CHARTER.md", "staff.yaml", "README.md"]);
+function rootFile(key) {
+  if (!ROOT_FILES.has(key)) return null;
+  return { path: key, ext: key.split(".").pop().toLowerCase(), bytes: 0, modified: new Date().toISOString() };
+}
+
+export function matchesFact(f, q) {
+  if (!q) return true;
+  return (f.slug + " " + f.statement + " " + (f.consequence ?? "") + " " + (f.section ?? ""))
+    .toLowerCase()
+    .includes(q);
+}