@nanocollective/roster 0.1.0-alpha.1 → 0.1.0-alpha.10

package/templates/portal/js/views/staff.js

@@ -10,12 +10,16 @@
  */
 
 import { post } from "../api.js";
+import { askYes } from "../dialog.js";
 import { ago, el, esc } from "../dom.js";
 import { icon } from "../icons.js";
 import { refreshAll } from "../refresh.js";
 import { S } from "../state.js";
 import { appPanel } from "./app.js";
+import { credentialPanel } from "./credential.js";
+import { cronText } from "./health.js";
 import { paste } from "./paste.js";
+import { runOnce } from "./runonce.js";
 
 export function viewStaff(m) {
   m.append(el("h1", { textContent: "Staff" }));
@@ -87,31 +91,66 @@ export function viewStaff(m) {
       pane.scrollIntoView?.({ behavior: "smooth", block: "start" });
     };
 
-    d.append(el("div", { className: "row", style: "margin-top:10px" }, [write, app, go, status]));
+    /* The credential is once for the org, but the moment somebody looks for it is while setting
+       up one staff member, so it is reachable from each card. */
+    const cred = el("button", { className: "ghbtn", textContent: "Agent credential" });
+    cred.onclick = () => {
+      pane.replaceChildren(el("div", { className: "card" }, [credentialPanel()]));
+      pane.scrollIntoView?.({ behavior: "smooth", block: "start" });
+    };
+
+    const run = el("button", { className: "ghbtn", textContent: "Run once now" });
+    run.onclick = () => {
+      pane.replaceChildren(
+        el("div", { className: "card" }, [
+          runOnce({ staff: s.handle, name: s.name, onDone: (ok) => ok && refreshAll(true) }),
+        ]),
+      );
+      pane.scrollIntoView?.({ behavior: "smooth", block: "start" });
+    };
+
+    d.append(
+      el("div", { className: "row", style: "margin-top:10px" }, [write, app, cred, run, go, status]),
+    );
     return d;
   }
 
   /* ------------------------------- hiring -------------------------------- */
 
   function hireForm(host) {
+    /* App names are copied from whoever is already here. The first hire has nobody to copy
+       from, and the CLI asks for --app and --public-app at that point; these are those two. */
+    const first = !S.data.staff.length;
     const box = el("div", { className: "card" });
     box.append(
       el("h3", { textContent: "Hire someone" }),
       el("p", {
         className: "sub",
         style: "margin-bottom:14px",
-        textContent:
-          "Only the handle is required. Everything else is copied from whoever is already " +
-          "here, because app slugs carry a house naming scheme and the public identity is " +
-          "genuinely shared.",
+        textContent: first
+          ? "Only the handle is required. This is the first hire, so there is nobody to copy " +
+            "App names from: name them here, and later hires follow the pattern."
+          : "Only the handle is required. Everything else is copied from whoever is already " +
+            "here, because app slugs carry a house naming scheme and the public identity is " +
+            "genuinely shared.",
       }),
     );
 
     const handle = field("handle", "cfo", "lowercase, digits and dashes");
     const name = field("name", "Chief Financial Officer", "defaults to the handle, uppercased");
     const dir = field("dir", "finance", "directory and repo name; defaults to the handle");
-    const schedule = field("schedule", "0 9 * * 1-5", "defaults to a slot clear of everyone else");
-    for (const f of [handle, name, dir, schedule]) box.append(f.row);
+    const schedule = scheduleField();
+    const fields = [handle, name, dir, schedule];
+    const apps = [];
+    if (first) {
+      const org = S.data.org;
+      apps.push(
+        ["app", field("app", org + "-cfo", "this staff member's GitHub App. Names are unique across GitHub, so prefix it")],
+        ["publicApp", field("public app", org + "-robot", "the shared identity for public product repos. Optional when they are all private")],
+      );
+      fields.push(...apps.map(([, f]) => f));
+    }
+    for (const f of fields) box.append(f.row);
 
     const status = el("span", { className: "meta" });
     const plan = el("button", { className: "ghbtn primary", textContent: "Show the plan" });
@@ -133,8 +172,9 @@ export function viewStaff(m) {
       status.className = "meta";
       out.replaceChildren();
       const params = new URLSearchParams({ handle: handle.input.value.trim() });
-      for (const [key, f] of [["name", name], ["dir", dir], ["schedule", schedule]]) {
-        if (f.input.value.trim()) params.set(key, f.input.value.trim());
+      for (const [key, f] of [["name", name], ["dir", dir], ["schedule", schedule], ...apps]) {
+        const value = (f.value ? f.value() : f.input.value).trim();
+        if (value) params.set(key, value);
       }
       try {
         const data = await (await fetch("/api/staff/plan?" + params, { cache: "no-store" })).json();
@@ -161,18 +201,33 @@ export function viewStaff(m) {
       line("ok", "runs at " + s.schedule + ", on " + s.model),
     );
     for (const p of plan.peers) {
-      box.append(line("ok", p.dir + "/staff.yaml gains a peer entry and a " + p.label + " label"));
+      box.append(line("ok", p.brain + " gains a " + p.label + " label"));
     }
-    box.append(line("ok", "org.yaml gains a staff entry and a repo entry"));
+    /* Commits into repos that already exist, as you. Listed because they are writes to
+       somebody else's repo, and a plan that hid them would be the silent kind. */
+    box.append(el("div", { className: "planhead", textContent: "Commits and pushes, as you" }));
+    for (const c of plan.commits ?? []) box.append(line("ok", c.repo + ": " + c.file + ", " + c.why));
 
-    if (plan.secrets?.length) {
-      box.append(el("div", { className: "planhead", textContent: "You will still have to" }));
-      box.append(
-        line("todo", "create the GitHub App: roster app " + s.handle),
-        line("todo", "put " + plan.secrets.join(", ") + " on the new repo"),
-      );
-    }
-    for (const w of plan.warnings ?? []) box.append(line("warn", w));
+    const cred = s.agentSecret ?? "the agent credential";
+    box.append(
+      plan.orgSecret?.visibility === "selected"
+        ? line("ok", s.brain + " is added to the repos that can read the org secret " + cred)
+        : plan.orgSecret
+          ? line("ok", "the org secret " + cred + " already reaches " + plan.orgSecret.visibility + " repos")
+          : line("warn", "no org secret " + cred + " yet: store it once with Agent credential, after this"),
+    );
+
+    box.append(el("div", { className: "planhead", textContent: "Then, on the new card" }));
+    box.append(
+      line(
+        "todo",
+        "GitHub App, or roster app " + s.handle + " --apply: creates it, sets its secrets, and " +
+          "opens the install page with the repos already ticked",
+      ),
+      line("todo", "Write the charter"),
+      line("todo", "Run once now, or roster run " + s.handle + " --apply: the run that proves the wiring"),
+    );
+    for (const w of plan.warnings ?? []) box.append(line("warn", S.data.staff.length ? w : portalWords(w)));
 
     const status = el("span", { className: "meta" });
     const go = el("button", { className: "ghbtn primary", textContent: "Hire " + s.handle });
@@ -183,7 +238,7 @@ export function viewStaff(m) {
           handle: s.handle,
           flags: Object.fromEntries(params),
         },
-        "Create " + s.brain + " and wire it up?\n\nThis creates a repository on GitHub.",
+        { title: "Create " + s.brain + " and wire it up?", hint: "This creates a repository on GitHub.", confirm: "Hire " + s.handle },
         go,
         status,
         box,
@@ -238,7 +293,7 @@ export function viewStaff(m) {
     go.onclick = () =>
       apply(
         { action: "retire", handle: plan.handle },
-        "Retire " + plan.name + "?\n\n" + (plan.brain ?? plan.dir) + " is not touched.",
+        { title: "Retire " + plan.name + "?", hint: (plan.brain ?? plan.dir) + " is not touched.", confirm: "Retire " + plan.handle },
         go,
         status,
         box,
@@ -250,7 +305,7 @@ export function viewStaff(m) {
   /* -------------------------------- apply -------------------------------- */
 
   async function apply(payload, ask, btn, status, box) {
-    if (!confirm(ask)) return;
+    if (!(await askYes(ask))) return;
     btn.disabled = true;
     status.textContent = "working…";
     status.className = "meta";
@@ -269,6 +324,14 @@ export function viewStaff(m) {
   }
 }
 
+/* The plan's warnings are the CLI's, and name its flags. Here the same two options are fields
+   on the form above, and a flag the page has no box for reads as a dead end. */
+function portalWords(warning) {
+  return warning
+    .replace(/pass --public-app\b/, "fill in public app above")
+    .replace(/pass --app\b/, "fill in app above");
+}
+
 function field(label, placeholder, hint) {
   const input = el("input", { type: "search", placeholder, value: "", style: "width:100%" });
   input.dataset.field = label;
@@ -281,6 +344,64 @@ function field(label, placeholder, hint) {
   return { row, input };
 }
 
+/**
+ * When the daily run happens, as a time and a set of days rather than as cron.
+ *
+ * The value on the wire is still a cron expression, because that is what goes in the workflow
+ * and what `roster hire` takes. But nobody hiring their first staff member knows that
+ * `0 9 * * 1-5` is nine in the morning on weekdays, and a field that demands it is a field
+ * that gets a wrong answer or an empty one.
+ *
+ * UTC, said out loud, with the local equivalent beside it: GitHub schedules in UTC, and an
+ * agent that starts an hour off twice a year is worse than one you had to think about once.
+ */
+function scheduleField() {
+  const time = el("input", { type: "time", value: "", step: "60", style: "width:130px" });
+  const days = el("select");
+  days.append(
+    el("option", { value: "1-5", textContent: "Weekdays" }),
+    el("option", { value: "*", textContent: "Every day" }),
+    el("option", { value: "1", textContent: "Mondays" }),
+    el("option", { value: "1,3,5", textContent: "Mon, Wed, Fri" }),
+  );
+  // Said rather than relying on "the first option is selected", which is true of a rendered
+  // <select> and not of one that has only been built.
+  days.value = "1-5";
+
+  const said = el("small");
+  const value = () => {
+    if (!time.value) return "";
+    const [h, m] = time.value.split(":");
+    return `${Number(m)} ${Number(h)} * * ${days.value}`;
+  };
+  const say = () => {
+    const cron = value();
+    said.textContent = cron
+      ? cronText(cron) + local(time.value)
+      : "Leave it empty for a slot clear of everyone else.";
+  };
+  time.oninput = say;
+  days.onchange = say;
+  say();
+
+  const row = el("div", { className: "ffield" });
+  row.append(
+    el("label", { textContent: "schedule" }),
+    el("div", { className: "row" }, [time, days, el("span", { className: "meta", textContent: "UTC" })]),
+    said,
+  );
+  return { row, input: time, value };
+}
+
+/** What that UTC time is where the person reading it is, when the two differ. */
+function local(hhmm) {
+  if (!hhmm) return "";
+  const [h, m] = hhmm.split(":").map(Number);
+  const at = new Date(Date.UTC(2026, 0, 5, h, m));
+  const here = at.toLocaleTimeString(undefined, { hour: "2-digit", minute: "2-digit" });
+  return here === hhmm ? "" : " · " + here + " where you are";
+}
+
 const MARK = { ok: "check", stop: "closed", keep: "issue-open", todo: "dash", warn: "label" };
 
 function line(kind, text) {

package/templates/portal/js/yaml.js

@@ -0,0 +1,134 @@
+/* Colour for YAML.
+ *
+ * `org.yaml` and `staff.yaml` are the two files here a person actually reads closely, and they
+ * were served as one flat grey wall: the comments, the keys and the values all the same weight,
+ * so finding `mention_timeout_minutes` meant reading every line. Structure is the thing YAML has
+ * and prose does not, and showing it costs about eighty lines.
+ *
+ * Deliberately not a parser. It is a per-line tokeniser that knows comments, keys, quoted
+ * strings, numbers and the three keywords — enough to read by, and it cannot fail on a file it
+ * does not understand, because anything it does not recognise is left as plain text.
+ */
+
+import { el, esc } from "./dom.js";
+
+/** A `<pre>` holding the highlighted source. */
+export function yamlPre(text, className = "code yaml") {
+  const pre = el("pre", { className });
+  pre.innerHTML = yamlHTML(text);
+  return pre;
+}
+
+/** Escaped, highlighted HTML. Takes raw text: it does its own escaping. */
+export function yamlHTML(text) {
+  return String(text ?? "")
+    .split("\n")
+    .map(colourLine)
+    .join("\n");
+}
+
+/**
+ * The same, for text that is already HTML-escaped.
+ *
+ * The markdown renderer escapes a fenced block before it knows what language it is, and
+ * un-escaping four entities to escape them again is exact and cheaper than restructuring
+ * the renderer around one case.
+ */
+export function yamlHTMLFromEscaped(escaped) {
+  return yamlHTML(
+    String(escaped ?? "")
+      .replace(/&lt;/g, "<")
+      .replace(/&gt;/g, ">")
+      .replace(/&quot;/g, '"')
+      .replace(/&amp;/g, "&"),
+  );
+}
+
+const span = (cls, text) => '<span class="' + cls + '">' + esc(text) + "</span>";
+
+function colourLine(raw) {
+  const [code, comment] = splitComment(raw);
+  return (code ? colourCode(code) : "") + (comment ? span("yc", comment) : "");
+}
+
+/**
+ * Split a trailing comment off, without cutting a `#` that is inside a string.
+ *
+ * `marker: will   # the provenance tag` is a comment; `name: "a # b"` is not. YAML also only
+ * starts a comment at the beginning of a line or after whitespace, which is what keeps a
+ * `#hashtag` in a value intact.
+ */
+function splitComment(raw) {
+  let quote = null;
+  for (let i = 0; i < raw.length; i++) {
+    const c = raw[i];
+    if (quote) {
+      if (c === quote && raw[i - 1] !== "\\") quote = null;
+      continue;
+    }
+    if (c === '"' || c === "'") {
+      quote = c;
+      continue;
+    }
+    if (c === "#" && (i === 0 || /\s/.test(raw[i - 1]))) return [raw.slice(0, i), raw.slice(i)];
+  }
+  return [raw, ""];
+}
+
+const DOC = /^\s*(---|\.\.\.)\s*$/;
+/** Indent, then any run of list dashes: `  - - name: x` is two levels of list. */
+const LEAD = /^(\s*)((?:-\s+)*)/;
+/** A key is everything up to the first colon that is followed by a space or the end of line. */
+const KEY = /^([^\s"'#][^:]*?)(:)(\s|$)/;
+
+function colourCode(code) {
+  if (DOC.test(code)) return span("yp", code);
+
+  const lead = LEAD.exec(code);
+  const indent = lead[1];
+  const dashes = lead[2];
+  let rest = code.slice(indent.length + dashes.length);
+  let out = indent + (dashes ? span("yd", dashes) : "");
+
+  /* A line that opens a flow collection has no key of its own: `- { handle: cto }` is a list
+     item whose keys are all inside the braces, and taking "{ handle" for a key marked the
+     brace as part of the name. */
+  const key = /^[{[]/.test(rest) ? null : KEY.exec(rest);
+  if (key) {
+    out += span("yk", key[1]) + span("yp", key[2]) + key[3];
+    rest = rest.slice(key[1].length + 1 + key[3].length);
+  }
+  return out + colourValue(rest);
+}
+
+/* Strings, inline-map keys, the three keywords, numbers, and the punctuation that holds a flow
+   collection together. Ordered: a quoted string wins over everything inside it. */
+const TOKEN = new RegExp(
+  [
+    /("(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*')/, // 1 quoted string
+    /([A-Za-z_][\w.-]*)(\s*:)(?=\s|$)/, // 2,3 a key inside an inline map
+    /(\b(?:true|false|null|yes|no|on|off)\b|~)/, // 4 keywords
+    /(-?\d+(?:\.\d+)?\b)/, // 5 numbers
+    /([{}[\],])/, // 6 flow punctuation
+  ]
+    .map((r) => r.source)
+    .join("|"),
+  "g",
+);
+
+function colourValue(value) {
+  if (!value) return "";
+  let out = "";
+  let at = 0;
+  TOKEN.lastIndex = 0;
+  for (let m = TOKEN.exec(value); m; m = TOKEN.exec(value)) {
+    out += esc(value.slice(at, m.index));
+    if (m[1]) out += span("ys", m[1]);
+    else if (m[2]) out += span("yk", m[2]) + span("yp", m[3]);
+    else if (m[4]) out += span("yb", m[4]);
+    else if (m[5]) out += span("yn", m[5]);
+    else out += span("yp", m[6]);
+    at = m.index + m[0].length;
+  }
+  return out + esc(value.slice(at));
+}

package/templates/brain/.github/workflows/%%STAFF%%-pr-mention.yaml

@@ -1,50 +0,0 @@
-name: %%STAFF_UPPER%% on a product PR
-
-# Generated by roster. The body lives in %%OPS_REPO%%/.github/workflows/session.yaml.
-#
-# Amends an open PR on the product repo in response to a review comment, so the human can ask for
-# changes where they are already reading the diff instead of opening a ticket and cross-referencing.
-#
-# Not triggered directly. A forwarder in the PUBLIC product repo catches the mention and dispatches
-# here. The split exists because that repo is public: its Actions logs are world readable, so the
-# run that prints a charter and a chain of reasoning has to happen in a repo only we can see.
-#
-# NOTE: %%TOKENS%% are filled by `roster hire`. GitHub's own ${{ }} expressions are left alone.
-
-on:
-  repository_dispatch:
-    types: [pr-mention]
-
-  # Manual handle, for testing without leaving a comment on a public PR, and for re-running a
-  # request the dispatcher already consumed.
-  workflow_dispatch:
-    inputs:
-      pr:
-        description: "PR number on the product repo"
-        required: true
-      comment_id:
-        description: "id of the comment that triggered this"
-        required: true
-
-# Per PR. Several review comments in a row are the normal case; different PRs never contend.
-concurrency:
-  group: %%STAFF%%-pr-${{ github.event.inputs.pr || github.event.client_payload.pr }}
-  cancel-in-progress: false
-
-jobs:
-  amend:
-    uses: %%OPS_REPO%%/.github/workflows/session.yaml@main
-    with:
-      staff: %%STAFF%%
-      kind: pr-mention
-      ops_repo: %%OPS_REPO%%
-      model: %%MODEL%%
-      timeout_minutes: %%PR_MENTION_TIMEOUT%%
-      pr_number: ${{ github.event.inputs.pr || github.event.client_payload.pr }}
-      comment_id: ${{ github.event.inputs.comment_id || github.event.client_payload.comment_id }}
-    secrets:
-      APP_ID: ${{ secrets.%%SECRET_PREFIX%%_APP_ID }}
-      APP_PRIVATE_KEY: ${{ secrets.%%SECRET_PREFIX%%_APP_PRIVATE_KEY }}
-      PUBLIC_APP_ID: ${{ secrets.%%PUBLIC_SECRET_PREFIX%%_APP_ID }}
-      PUBLIC_APP_PRIVATE_KEY: ${{ secrets.%%PUBLIC_SECRET_PREFIX%%_APP_PRIVATE_KEY }}
-      AGENT_TOKEN: ${{ secrets.%%AGENT_SECRET%% }}

package/templates/ops/prompts/pr-mention.md

@@ -1,57 +0,0 @@
-You are **{{staff.name}}** at {{org.name}}. {{human.name}} has asked for a change to an open pull
-request, in a comment on the PR itself. They are not watching a terminal; **your reply on that PR is
-the only thing they will see.**
-
-**This is not a session.** No boot ritual, no handoff, no rewriting #{{staff.status_issue}}. Make the
-change asked for, push it, reply, stop.
-
-{{#if staff.public_bot}}
-## You are anonymous over there
-
-The PR is on a **public** repo. You post as `{{staff.public_bot}}`, an ordinary automation account.
-**Never sign as {{staff.name}}, never mention a charter, a tracker, a scheduled run, or that there is
-a role behind the account.** Write like a maintainer's bot: short, factual, no personality.
-
-Every `gh` call against that repo must carry the public identity: `GH_TOKEN=$PUBLIC_TOKEN gh ...`.
-The bare `GH_TOKEN` is your private-tracker identity and using it there would sign your name to a
-public repo.
-{{/if}}
-
-{{> prompts/_paths.md}}
-
-## The request
-
-**PR #{{event.pr_number}}, comment `{{event.comment_id}}`.** Read it before touching anything: an
-inline review comment carries `path`, `line` and `diff_hunk`, which say exactly which code is meant.
-Do not guess from the prose.
-
-## Do the work
-
-1. **You are already on the PR branch** - the runner checked it out. Do not start a new one.
-2. **If the PR is from a fork you cannot push to**, do not try. Reply with the exact diff to apply,
-   and say why you could not push it.
-3. **Make only the change asked for.** A review comment is a narrow request. Fixing something else
-   makes the diff unreviewable and costs a second review. If you spot something real and separate,
-   mention it in the reply and leave the code alone.
-4. **Run the full gate before pushing.** If it goes red on the requested change, push nothing and
-   reply with what broke.
-5. **Pull with rebase before pushing** - there may be several comments, and another run may be on
-   the same branch. If the push is still rejected, pull and retry rather than forcing: a force push
-   on a branch being reviewed throws away their place in the diff.
-6. **You cannot verify anything UI-shaped** - there is no browser and no device here. Say so plainly
-   rather than implying a green gate covered it.
-
-**Do not merge, and do not push to the default branch.**
-
-{{> org/guardrails.md}}
-
-## Reply where they asked
-
-Answer in the same place the request came from. **Do not @-mention them** - they are subscribed to
-their own PR.
-
-{{> org/voice.md}}
-
-**For this reply specifically:** what changed, the SHA, gate status, what it did not cover.
-**Nothing else.** No preamble, no restating the request, no headers, no sign-off, no narration of
-the steps you took. If nothing changed, one line saying so and why.