@nanocollective/roster 0.1.0-alpha.3 → 0.1.0-alpha.31

package/templates/portal/js/readiness.js

@@ -0,0 +1,35 @@
+/* Whether each staff member can actually run yet.
+ *
+ * A hire that had its App created but not installed, and no credential, looked finished: the
+ * card said so and Getting started went away. This is the one answer every screen asks. */
+
+import { getStaffProgress } from "./api.js";
+import { S } from "./state.js";
+
+/** What is left for one staff member, as short instructions. Empty when they are ready. */
+export async function whatsLeft(s, fresh = false) {
+  const left = [];
+  if (s.rig?.charterStub) left.push("write the charter");
+  const p = await getStaffProgress(s.handle, fresh).catch(() => ({}));
+  if (p.installed === false) left.push(p.app ? "install the GitHub App" : "create the GitHub App");
+  if (p.credential === false) left.push("add the agent credential");
+  if (p.ran === false) left.push("run once");
+  S.readiness = { ...(S.readiness ?? {}), [s.handle]: left };
+  return left;
+}
+
+/** Every staff member's, then `then` once all have answered. */
+export function checkAll(then) {
+  return Promise.all((S.data?.staff ?? []).map((s) => whatsLeft(s))).then(() => then?.());
+}
+
+/** The staff with anything left, from what has been checked so far. */
+export function notReady() {
+  return (S.data?.staff ?? []).filter((s) => (S.readiness?.[s.handle] ?? []).length);
+}
+
+/** "install the GitHub App, add the agent credential and run once" */
+export function sentence(left) {
+  if (left.length < 2) return left.join("");
+  return left.slice(0, -1).join(", ") + " and " + left.at(-1);
+}

package/templates/portal/js/refresh.js

@@ -7,10 +7,75 @@
  * Its own module because both the shell and the inbox need it, and importing the shell from
  * a view would make the module graph a ring. */
 
-import { getOrg, getSync } from "./api.js";
+import { getInbox, getOrg, getSync } from "./api.js";
 import { $, ago, el, esc } from "./dom.js";
 import { render } from "./router.js";
-import { S } from "./state.js";
+import { openCount, openPrCount, S } from "./state.js";
+
+/**
+ * The inbox, fetched at most once at a time.
+ *
+ * Two things want it the moment the page opens: the sidebar, which counts what is waiting on
+ * you, and the Inbox screen, if that is where the URL landed. Both used to ask separately, and
+ * the second one paid a second round trip through every repo on GitHub to learn what the first
+ * was already finding out.
+ *
+ * So the request is shared. `force` always goes to GitHub — it is the refresh button — and
+ * everything else takes whatever is in flight or already loaded.
+ */
+let inflight = null;
+
+export function ensureInbox(force) {
+  if (!force && S.inbox) return Promise.resolve(S.inbox);
+  if (!force && inflight) return inflight;
+  const asked = getInbox(force)
+    .then((data) => {
+      S.inbox = data;
+      if (inflight === asked) inflight = null;
+      return data;
+    })
+    .catch((err) => {
+      if (inflight === asked) inflight = null;
+      throw err;
+    });
+  inflight = asked;
+  return asked;
+}
+
+/**
+ * The two sidebar counts, wherever they are asked for.
+ *
+ * They live here rather than on the Inbox screen because they are the shell's, and because the
+ * whole point of this pass is that they are right before anybody has opened that screen. While
+ * the first fetch is out they show a placeholder rather than nothing: an empty badge reads as
+ * "zero", and zero is a different claim from "still counting".
+ */
+export function stampCounts() {
+  const waiting = !S.inbox;
+  for (const [sel, n] of [
+    ["#inboxcount", openCount],
+    ["#prcount", openPrCount],
+  ]) {
+    const slot = document.querySelector(sel);
+    if (!slot) continue;
+    slot.textContent = waiting ? "" : String(n());
+    slot.classList.toggle("wait", waiting);
+  }
+}
+
+/**
+ * Count what is waiting on you without opening the screen that lists it.
+ *
+ * The badges used to fill in only once something else caused a render with an inbox loaded,
+ * which in practice meant "after you visit the Inbox". A sidebar that says nothing until you
+ * look at it is not a sidebar.
+ */
+export function countInBackground() {
+  stampCounts();
+  return ensureInbox(false)
+    .then(stampCounts)
+    .catch(() => stampCounts());
+}
 
 export async function refreshAll(soft) {
   const bar = $("#refreshall");
@@ -21,14 +86,54 @@ export async function refreshAll(soft) {
     S.sync = await getSync();
     S.data = await getOrg();
     S.inbox = null; // the inbox re-fetches itself on next paint
+    inflight = null;
     S.loadedAt = new Date();
     if (!soft) render();
     stampLoaded();
+    // The badges are now claiming a count from before the sync. Re-ask, and say so meanwhile.
+    countInBackground();
+  } finally {
+    bar?.classList.remove("spin");
+  }
+}
+
+/**
+ * The same thing, for coming back to the tab.
+ *
+ * Asked for by a focus event rather than by a person, so it has to earn every visible effect.
+ * A full refresh drops the inbox, which sends the next paint to GitHub for four seconds and
+ * throws away whatever was on screen — including a half-written issue. Almost every focus
+ * finds nothing new, so this one syncs, looks, and only then does any of that.
+ */
+export async function refreshQuietly() {
+  const bar = $("#refreshall");
+  bar?.classList.add("spin");
+  try {
+    S.sync = await getSync();
+    const data = await getOrg();
+    const changed = shape(data) !== shape(S.data);
+    S.data = data;
+    S.loadedAt = new Date();
+    stampLoaded();
+    // Something landed in a checkout: the inbox is stale too, and the screen should say so.
+    if (changed || (S.sync?.results ?? []).some((r) => r.pulled)) {
+      S.inbox = null;
+      inflight = null;
+      render();
+      countInBackground();
+    }
   } finally {
     bar?.classList.remove("spin");
   }
 }
 
+/** The export minus its timestamp, which is stamped per request and always differs. */
+function shape(data) {
+  if (!data) return "";
+  const { generatedAt, ...rest } = data;
+  return JSON.stringify(rest);
+}
+
 export function stampLoaded() {
   const s = $("#loaded");
   if (s && S.loadedAt) s.textContent = "data " + ago(S.loadedAt.toISOString());
@@ -40,20 +145,45 @@ export function syncNotice() {
   const stuck = (S.sync?.results ?? []).filter((r) => r.skipped || r.error || r.behind > 0);
   if (!stuck.length) return null;
   const d = el("div", { className: "notice" });
-  d.innerHTML = stuck
+  const lines = el("div");
+  lines.innerHTML = stuck
     .map(
       (r) =>
         "<b>" + esc(r.dir) + "</b> " +
         (r.error
           ? "could not sync: " + esc(r.error)
           : r.skipped === "dirty"
-            ? "is " + r.behind + " behind and has uncommitted changes, so it was not pulled"
+            ? "is " + r.behind + " behind and has uncommitted changes, so it was not pulled. " +
+              "Commit or stash them, then pull."
             : r.skipped === "diverged"
-              ? "has diverged (" + r.ahead + " ahead, " + r.behind + " behind)"
+              ? "has diverged (" + r.ahead + " ahead, " + r.behind + " behind). " +
+                "Push or rebase it by hand: a merge is not this button's to make."
               : r.skipped === "no-remote"
                 ? "has no remote"
-                : "is still " + r.behind + " behind"),
+                : "is " + r.behind + " behind"),
     )
     .join("<br>");
+  d.append(lines);
+
+  /* The same conservative pull `roster portal` runs on a refresh, on demand: fetch, and pull
+     only what is clean and fast-forward. It is here because the answer to "commit those and
+     pull" should not be to reload the page and hope. */
+  const status = el("span", { className: "meta" });
+  const pull = el("button", { className: "ghbtn", textContent: "Pull now" });
+  pull.onclick = async () => {
+    pull.disabled = true;
+    status.textContent = "pulling…";
+    status.className = "meta";
+    S.sync = await getSync();
+    const pulled = (S.sync?.results ?? []).filter((r) => r.pulled);
+    // Anything that landed is on disk now, so the export and the inbox are both behind it.
+    if (pulled.length) await refreshAll(false);
+    else {
+      pull.disabled = false;
+      status.textContent = "nothing could be pulled";
+      render();
+    }
+  };
+  d.append(el("div", { className: "row", style: "margin-top:10px" }, [pull, status]));
   return d;
 }

package/templates/portal/js/state.js

@@ -22,18 +22,29 @@ export const VIEWS = [
 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 ORG_WIDE = new Set(["setup", "inbox", "prs", "runs", "org", "staff", "docs"]);
+
+/** The two screens that read the inbox, and so share its filters and its `?t=` thread. */
+const INBOXY = new Set(["inbox", "prs"]);
 
 export const S = {
   /** The org export from /api/org. Everything the brain screens read comes off this. */
   data: null,
   docs: null,
   inbox: null,
+  /** /api/runs. Kept once read: it is minutes of downloads on a cold cache. */
+  runs: null,
   sync: null,
   loadedAt: null,
+  /** The role whose hire list is open on the Staff screen, kept across a refresh. */
+  staffOpen: null,
+  /** Per staff member, what is left before they can run. See readiness.js. */
+  readiness: null,
 
   staffHandle: null,
-  view: "brain",
+  /* What is waiting on you, not whose brain you read last. The org-wide screens are where a
+     session starts, which is also why the Staff list below them opens folded. */
+  view: "inbox",
   /** The inbox filter box. Brain and "what changed" keep their own, below. */
   query: "",
 
@@ -48,13 +59,16 @@ export const S = {
   changedFilter: "",
 
   openDoc: null,
+  /** The docs search box. Its own field: the Docs screen keeps it while you read a page. */
+  docQuery: "",
 
   /** 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. */
+  /** Which org-layer file the Org screen is showing, and what it found on disk. */
   orgOpen: null,
+  orgFiles: [],
 
   inboxFilter: "",
   inboxStaff: "",
@@ -67,12 +81,40 @@ export const S = {
 
 /* 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. */
+   need you is worse than no badge. Pull requests are excluded for the same reason: they are
+   Pending work's, and counting them here would bill you twice for the same pile. */
 export const openCount = () =>
-  (S.inbox?.items ?? []).filter((i) => i.state === "OPEN").length;
+  (S.inbox?.items ?? []).filter((i) => i.state === "OPEN" && i.kind !== "pr").length;
+
+/** The same, for the screen that is only pull requests. */
+export const openPrCount = () =>
+  (S.inbox?.items ?? []).filter((i) => i.state === "OPEN" && i.kind === "pr").length;
 
 export const staff = () => S.data.staff.find((s) => s.handle === S.staffHandle) ?? S.data.staff[0];
 
+/**
+ * Everyone the staff answer to.
+ *
+ * An org can have more than one. `humans` is the list the export sends now; `human` is what a
+ * portal whose server predates the list sends, and falling back to it is what keeps the page
+ * working across the upgrade rather than showing an org with nobody in it.
+ */
+export const humansOf = () =>
+  S.data?.humans?.length ? S.data.humans : S.data?.human?.github ? [S.data.human] : [];
+
+/** Whether a login is one of them. Assignment to any of them is assignment to "us". */
+export const isHuman = (login) =>
+  !!login &&
+  humansOf().some((h) => String(h.github ?? "").toLowerCase() === String(login).toLowerCase());
+
+/** What to call them collectively, for a filter label or a count. */
+export const humanLabel = () => {
+  const humans = humansOf();
+  if (!humans.length) return "you";
+  if (humans.length === 1) return humans[0].name ?? humans[0].github ?? "you";
+  return humans.map((h) => h.name ?? h.github).join(" or ");
+};
+
 export function readHash() {
   const raw = (location.hash || "").replace(/^#\/?/, "");
   if (!raw) return null;
@@ -97,7 +139,14 @@ 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;
+  const q =
+    S.view === "brain"
+      ? S.fileQuery
+      : S.view === "changed"
+        ? S.changedQuery
+        : S.view === "docs"
+          ? S.docQuery
+          : 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);
@@ -106,7 +155,7 @@ export function writeHash(push) {
     if (S.promptKind !== "daily") params.set("k", S.promptKind);
     if (S.promptOpen) params.set("f", S.promptOpen);
   }
-  if (S.view === "inbox") {
+  if (INBOXY.has(S.view)) {
     if (S.inboxFilter) params.set("s", S.inboxFilter);
     if (S.inboxStaff) params.set("w", S.inboxStaff);
     if (S.inboxState) params.set("x", S.inboxState);
@@ -134,6 +183,8 @@ export function applyHash() {
     S.openFile = h.f;
   } else if (S.view === "changed") {
     S.changedQuery = h.q;
+  } else if (S.view === "docs") {
+    S.docQuery = h.q;
   } else {
     S.query = h.q;
   }
@@ -146,7 +197,7 @@ export function applyHash() {
     S.promptOpen = h.f;
   }
 
-  if (S.view === "inbox") {
+  if (INBOXY.has(S.view)) {
     S.inboxFilter = h.s;
     S.inboxStaff = h.w;
     S.inboxState = h.x;

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

@@ -6,8 +6,8 @@
  * 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. */
+ * repositories and GitHub asks a human to confirm them, which is correct behaviour and should not
+ * be worked around. The link it hands back has the right repos already selected. */
 
 import { appResult, startApp } from "../api.js";
 import { el } from "../dom.js";
@@ -27,8 +27,7 @@ export function appPanel(opts) {
     }),
     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.",
+        "A GitHub tab opens. Confirm there, then come back here to install it.",
     }),
   );
 
@@ -48,6 +47,11 @@ export function appPanel(opts) {
          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) }));
+      if (err.data?.install) {
+        note.append(
+          el("a", { className: "btn", href: err.data.install, target: "_blank", textContent: "Install it" }),
+        );
+      }
       out.replaceChildren(note);
       return;
     }
@@ -102,9 +106,21 @@ export function appPanel(opts) {
         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.",
+            "The link opens GitHub's install page with the org and the repos already selected: " +
+            "this staff member's brain, every peer tracker it writes to, and the product repos. " +
+            "Check the list and confirm.",
         }),
+        ...((result.preselected ?? []).length
+          ? [el("p", { className: "sub", textContent: "Selected: " + result.preselected.join(", ") })]
+          : []),
+        ...((result.missing ?? []).length
+          ? [
+              el("p", {
+                className: "err",
+                textContent: "Tick these yourself, their ids could not be read: " + result.missing.join(", "),
+              }),
+            ]
+          : []),
         el("a", {
           className: "btn primary",
           href: result.install,
@@ -115,7 +131,8 @@ export function appPanel(opts) {
           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.",
+            "from what an installation was granted. Only a run that finished proves the chain, " +
+            "which is what Run once now on the staff card is for.",
         }),
       );
       out.replaceChildren(done);

package/templates/portal/js/views/checklist.js

@@ -9,8 +9,19 @@ import { el, toClipboard } from "../dom.js";
 
 const LEVEL_ORDER = { fail: 0, warn: 1, ok: 2 };
 
+/**
+ * @param opts.skip  finding ids the caller already shows as a step of its own, so they are not
+ *   reported twice. With `opts.hideWhenClean`, a list left empty draws nothing at all.
+ * @param opts.shell  when Health draws this, the section it lives in: `{actions, say}`. The
+ *   setup screen passes nothing and gets the layout it has always had. Its own screen is a
+ *   wizard, where a chunky button and a paragraph under it are right; on Health it is one
+ *   section of four, and has to look like the other three.
+ */
 export async function checklist(host, opts = {}) {
-  host.replaceChildren(el("p", { className: "sub", textContent: "Checking…" }));
+  const inSection = Boolean(opts.shell);
+  const btnClass = inSection ? "ghbtn" : "btn";
+  const noteClass = inSection ? "hnote" : "sub";
+  host.replaceChildren(el("p", { className: noteClass, textContent: "Checking…" }));
 
   let report;
   try {
@@ -23,12 +34,18 @@ export async function checklist(host, opts = {}) {
   const findings = (report.findings ?? []).slice().sort(
     (a, b) => (LEVEL_ORDER[a.level] ?? 3) - (LEVEL_ORDER[b.level] ?? 3),
   );
-  const bad = findings.filter((f) => f.level !== "ok");
+  const skip = new Set(opts.skip ?? []);
+  const bad = findings.filter((f) => f.level !== "ok" && !skip.has(f.id));
 
   host.replaceChildren();
+  if (!bad.length && opts.hideWhenClean) {
+    opts.onEmpty?.();
+    return;
+  }
+  opts.shell?.say(bad.length ? String(bad.length) : "clean");
   host.append(
     el("p", {
-      className: "sub",
+      className: noteClass,
       textContent: bad.length
         ? `${bad.filter((f) => f.level === "fail").length} failing, ${bad.filter((f) => f.level === "warn").length} to look at.` +
           (report.online ? "" : " Local checks only.")
@@ -51,7 +68,7 @@ export async function checklist(host, opts = {}) {
 
   /* The isitagentready move: the findings as instructions, for the agent you already have
      pointed at this workspace. What only a person can do is deliberately not in that text. */
-  const copy = el("button", { className: "btn primary", textContent: "Copy all instructions" });
+  const copy = el("button", { className: btnClass + " primary", textContent: "Copy all instructions" });
   const note = el("span", { className: "meta" });
   copy.onclick = async () => {
     copy.disabled = true;
@@ -70,17 +87,19 @@ export async function checklist(host, opts = {}) {
     }
   };
 
-  const again = el("button", { className: "btn", textContent: "Check again" });
+  const again = el("button", { className: btnClass, textContent: "Check again" });
   again.onclick = () => checklist(host, opts);
 
-  host.append(el("div", { className: "row" }, [copy, again, note]));
+  const feet = opts.shell?.actions ?? host.appendChild(el("div", { className: "row" }));
+  if (opts.shell) feet.replaceChildren();
+  feet.append(copy, again, note);
   if (bad.length) {
-    host.append(
+    feet.append(
       el("p", {
-        className: "sub",
+        className: noteClass,
+        style: "flex-basis:100%",
         textContent:
-          "Paste it into Cursor, Claude Code or anything else that can edit files here, then " +
-          "check again. The ids above should be gone.",
+          "Paste them into your coding agent, then check again.",
       }),
     );
   }

package/templates/portal/js/views/credential.js

@@ -0,0 +1,84 @@
+/* The agent's credential, stored once for the org.
+ *
+ * The value goes from this box to the local server in a POST, and from there to gh on its
+ * standard input. It is not kept in the page after it is sent, and nothing echoes it back. */
+
+import { getCredential, storeCredential } from "../api.js";
+import { el } from "../dom.js";
+
+/** @param opts.bare  drawn inside a step that already has a title. `onStatus(done)` hears whether one is stored. */
+export function credentialPanel(opts = {}) {
+  const box = el("div", { className: opts.bare ? "" : "manual" });
+  if (!opts.bare) box.append(el("b", { textContent: "Agent credential" }));
+  const body = el("div");
+  box.append(body);
+  body.append(el("p", { className: "sub", textContent: "Checking…" }));
+
+  getCredential()
+    .then((c) => {
+      opts.onStatus?.(Boolean(c.stored ?? c.orgSecret));
+      draw(body, c, opts);
+    })
+    .catch((err) => body.replaceChildren(el("p", { className: "err", textContent: String(err.message || err) })));
+  return box;
+}
+
+function draw(body, c, opts = {}) {
+  body.replaceChildren();
+
+  if (!(c.brains ?? []).length) {
+    // Inside a step, the step's own hint already says when this opens.
+    if (!opts.bare) body.append(el("p", { className: "sub", textContent: "Available after your first hire. You only add it once." }));
+    return;
+  }
+
+  const form = el("div", { className: "credform" });
+  const input = el("input", { type: "password", placeholder: "Paste it here", autocomplete: "off", className: "textfield" });
+  const go = el("button", { className: "btn primary", textContent: "Save" });
+  const out = el("div");
+  form.append(
+    ...(c.howTo ? [el("p", { className: "sub", textContent: "To get one, " + c.howTo })] : []),
+    input,
+    el("div", { className: "row" }, [go]),
+    out,
+  );
+
+  // Stored already, on the org or on every brain repo: say so, and keep replacing it one click away.
+  if (c.stored ?? c.orgSecret) {
+    const replace = el("button", { className: "ghbtn", textContent: "Replace it" });
+    replace.onclick = () => {
+      replace.remove();
+      form.hidden = false;
+      input.focus?.();
+    };
+    form.hidden = true;
+    body.append(el("p", { className: "okline", textContent: "✓ Stored as " + c.name + "." }), replace, form);
+  } else {
+    body.append(form);
+  }
+
+  go.onclick = async () => {
+    const value = String(input.value ?? "").trim();
+    if (!value) {
+      input.focus?.();
+      return;
+    }
+    go.disabled = true;
+    go.textContent = "Saving…";
+    try {
+      const r = await storeCredential(value, false);
+      input.value = "";
+      if (!r.ok) throw new Error(r.error);
+      opts.onStatus?.(true);
+      out.replaceChildren(
+        ...(r.fellBack ? [el("p", { className: "sub", textContent: "Saved on each repo instead: " + r.fellBack })] : []),
+        el("p", { className: "okline", textContent: "✓ Saved." }),
+      );
+    } catch (err) {
+      out.replaceChildren(el("p", { className: "err", textContent: String(err.message || err) }));
+    } finally {
+      go.disabled = false;
+      go.textContent = "Save";
+    }
+  };
+}