@nanocollective/roster 0.1.0-alpha.20 → 0.1.0-alpha.22

package/README.md

@@ -33,6 +33,11 @@ first finished run, most of it writing what the business is and the staff member
 Everything the portal does is also a command, on the same files. Nothing changes anything
 without `--apply`.
 
+**`roster` here means either of these.** With nothing installed, run commands through npx:
+`npx @nanocollective/roster@latest upgrade`. Or install it once with
+`npm install -g @nanocollective/roster` and type `roster upgrade`. When you run through npx,
+the commands roster suggests are printed the npx way, so they can be pasted as they are.
+
 ```bash
 roster init --org acme          # ops repo, org layer, merge base
 roster hire cto                 # scaffold a staff member: repo, workflows, labels, peers

package/dist/cli.js

@@ -5401,6 +5401,30 @@ function short3(e) {
   return line.length > 200 ? `${line.slice(0, 199)}\u2026` : line;
 }
 
+// src/lib/bin.ts
+var NPX = "npx @nanocollective/roster@latest";
+function bin(env = process.env, argv1 = process.argv[1] ?? "") {
+  if (env.ROSTER_BIN) return env.ROSTER_BIN;
+  if (env.npm_command === "exec" || /[\\/]_npx[\\/]/.test(argv1)) return NPX;
+  return "roster";
+}
+var COMMAND = /\broster(?= (?:init|hire|app|credential|run|doctor|fix|portal|prompt|upgrade|retire|lint|brief|export|help)\b)/g;
+function withBin(text, name = bin()) {
+  return name === "roster" ? text : text.replace(COMMAND, name);
+}
+function rewriteOutput(name = bin()) {
+  const raw = process.stdout.write.bind(process.stdout);
+  if (name === "roster") return (text) => void raw(text);
+  for (const stream of [process.stdout, process.stderr]) {
+    const write = stream.write.bind(stream);
+    stream.write = ((chunk, ...rest) => write(
+      typeof chunk === "string" ? withBin(chunk, name) : chunk,
+      ...rest
+    ));
+  }
+  return (text) => void raw(text);
+}
+
 // src/lib/browser.ts
 import { spawn } from "child_process";
 function shouldOpen(env, isTTY, noOpen) {
@@ -6415,7 +6439,7 @@ async function portalCommand(argv) {
   const handleSetup = async (url, req, res) => {
     const route = url.pathname.slice("/api/setup/".length);
     if (route === "status") {
-      json(res, { ...await setupStatus(startedIn), startedIn });
+      json(res, { ...await setupStatus(startedIn), startedIn }, true);
       return;
     }
     if (route === "app") {
@@ -6796,7 +6820,7 @@ async function portalCommand(argv) {
         return;
       }
       if (url.pathname === "/api/doctor") {
-        collect({ ops: ws?.opsDir, offline: url.searchParams.get("offline") === "1" }).then((report3) => json(res, report3 ?? { findings: [], online: false, empty: true })).catch((err) => {
+        collect({ ops: ws?.opsDir, offline: url.searchParams.get("offline") === "1" }).then((report3) => json(res, report3 ?? { findings: [], online: false, empty: true }, true)).catch((err) => {
           res.writeHead(200, { "content-type": "application/json" });
           res.end(JSON.stringify({ findings: [], error: String(err?.message ?? err) }));
         });
@@ -6877,7 +6901,7 @@ async function portalCommand(argv) {
               throw new Error(`"${handle}" is not in org.yaml`);
             }
             const plan3 = buildRetirePlan(w, org, handle, parseYaml);
-            json(res, { action, plan: plan3 });
+            json(res, { action, plan: plan3 }, true);
             return;
           }
           if (!/^[a-z][a-z0-9-]{1,20}$/.test(handle)) {
@@ -6889,10 +6913,11 @@ async function portalCommand(argv) {
           const flags = hireFlags(url.searchParams);
           const plan2 = buildPlan(w, org, handle, flags, parseYaml);
           void readOrgSecret(org.org, plan2.staff.agentSecret).then(
-            (orgSecret) => json(res, {
-              action,
-              plan: { ...plan2, orgSecret, files: [...plan2.files.keys()].sort() }
-            })
+            (orgSecret) => json(
+              res,
+              { action, plan: { ...plan2, orgSecret, files: [...plan2.files.keys()].sort() } },
+              true
+            )
           );
         } catch (err) {
           res.writeHead(400, { "content-type": "application/json" });
@@ -6966,7 +6991,7 @@ async function portalCommand(argv) {
         return;
       }
       if (url.pathname === "/api/fix") {
-        gather(w, url.searchParams.get("offline") === "1").then((items) => json(res, { items, text: fixBrief(w, items) })).catch((err) => {
+        gather(w, url.searchParams.get("offline") === "1").then((items) => json(res, { items, text: fixBrief(w, items) }, true)).catch((err) => {
           res.writeHead(200, { "content-type": "application/json" });
           res.end(JSON.stringify({ items: [], error: String(err?.message ?? err) }));
         });
@@ -7491,12 +7516,13 @@ function refuseWrite(res) {
   res.writeHead(403, { "content-type": "application/json" });
   res.end(JSON.stringify({ error: "write actions need a local POST from the portal" }));
 }
-function json(res, data) {
+function json(res, data, advice = false) {
   res.writeHead(200, {
     "content-type": "application/json; charset=utf-8",
     "cache-control": "no-store"
   });
-  res.end(JSON.stringify(data));
+  const text = JSON.stringify(data);
+  res.end(advice ? withBin(text) : text);
 }
 function hireFlags(params) {
   const num = (k) => params.get(k) ? Number(params.get(k)) : void 0;
@@ -7900,11 +7926,24 @@ var HELPS = {
   export: exportHelp
 };
 async function main(argv) {
+  const raw = rewriteOutput();
   const [command, ...rest] = argv;
   if (!command) return portalCommand([]);
   if (command === "help" || command === "--help" || command === "-h") {
     const topic = rest[0];
-    process.stdout.write(topic && HELPS[topic] ? HELPS[topic] : HELP);
+    if (!topic || !HELPS[topic]) {
+      const name = bin();
+      if (name !== "roster") {
+        raw(
+          `
+  Run these as ${name} <command>, or install it: npm install -g @nanocollective/roster
+`
+        );
+      }
+      raw(HELP);
+      return 0;
+    }
+    process.stdout.write(HELPS[topic]);
     return 0;
   }
   const run6 = COMMANDS[command];

package/docs/commands.md

@@ -6,6 +6,11 @@ sidebar_order: 8
 
 # Commands
 
+**`roster` here means either of these.** With nothing installed, run commands through npx:
+`npx @nanocollective/roster@latest upgrade`. Or install it once with
+`npm install -g @nanocollective/roster` and type `roster upgrade`. When you run through npx,
+the commands roster suggests are printed the npx way, so they can be pasted as they are.
+
 Every command that changes anything prints a plan and changes nothing unless you pass
 `--apply`. `lint`, `prompt`, `export`, `brief`, `doctor` and `fix` never change anything.
 `portal` is the exception: it is interactive, and each change there is a button you press after

package/docs/getting-started.md

@@ -144,6 +144,9 @@ member on their next run.
 
 The same road, command by command. Each prints its plan and changes nothing without `--apply`.
 
+`roster` below means `npx @nanocollective/roster@latest`, unless you have installed it with
+`npm install -g @nanocollective/roster`.
+
 ```bash
 roster init --org acme --apply        # the ops repo, and its Actions access
 roster brief discover                 # a brief for org/business.md; write priorities.md too

package/docs/upgrading.md

@@ -10,9 +10,9 @@ The framework writes templates out. A tenant runs its own copies. So the two dri
 `roster upgrade` is what reconciles them without eating your edits.
 
 ```bash
-roster upgrade                 # what would change
-roster upgrade --apply         # do it
-roster upgrade --check         # exit non-zero if anything is pending (for CI)
+npx @nanocollective/roster@latest upgrade           # what would change
+npx @nanocollective/roster@latest upgrade --apply   # do it
+npx @nanocollective/roster@latest upgrade --check   # exit non-zero if anything is pending (for CI)
 ```
 
 ## How it decides

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanocollective/roster",
-  "version": "0.1.0-alpha.20",
+  "version": "0.1.0-alpha.22",
   "description": "An agent-run org, powered by GitHub. Scaffold AI staff members whose brain is a repo.",
   "type": "module",
   "bin": {

package/templates/portal/css/setup.css

@@ -148,3 +148,13 @@
 .mode:hover{color:var(--ink)}
 .mode.on{background:var(--bg-elev);color:var(--ink);box-shadow:var(--shadow-sm)}
 .modes + div > .paste{border-top:0;margin-top:0;padding-top:0}
+
+/* ---------- a checked paste ---------- */
+.verdict{margin:0 0 10px;font:600 13.5px var(--sans)}
+.verdict.ok{color:var(--accent)}
+.verdict.bad{color:var(--err)}
+.pastepreview{border:1px solid var(--line);border-radius:var(--r);padding:14px 16px;margin-bottom:12px;background:var(--bg)}
+.pastenotes{margin:0 0 12px}
+.pastenotes summary{cursor:pointer;font:600 12.5px var(--sans);color:var(--ink-dim);margin-bottom:6px}
+.pastenotes .md{border-left:3px solid var(--line);padding-left:12px}
+.pastefile .diff{white-space:pre-wrap;overflow-wrap:anywhere}

package/templates/portal/js/views/orgedit.js

@@ -17,6 +17,10 @@ const BUSINESS_QUESTIONS = [
 
 const val = (input) => String(input.value ?? "").trim();
 
+/* A file still in the shape it shipped in holds the questions, not answers, and pre-filling the
+   fields with "Not a segment. The person…" reads as if somebody had already answered them. */
+const isStub = (text) => /This file is a stub|Or answer these by hand/.test(text);
+
 /**
  * org/business.md as five questions. With `text`, the answers already in the file fill the
  * fields, so changing one answer does not mean retyping the other four.
@@ -25,7 +29,7 @@ const val = (input) => String(input.value ?? "").trim();
  */
 export function businessForm(o) {
   const form = el("div");
-  const known = sections(o.text ?? "");
+  const known = isStub(o.text ?? "") ? new Map() : sections(o.text ?? "");
   const fields = BUSINESS_QUESTIONS.map(([id, label, heading, required]) => {
     const input = id === "line" ? el("input", { type: "text" }) : el("textarea", { className: "pastebox", rows: 3 });
     const had = known.get(heading.toLowerCase());
@@ -64,7 +68,7 @@ export function businessForm(o) {
 /** org/priorities.md as three lines and an out-of-scope list, filled from the file if it has them. */
 export function prioritiesForm(o) {
   const form = el("div");
-  const { items, outs } = parsePriorities(o.text ?? "");
+  const { items, outs } = isStub(o.text ?? "") ? { items: [], outs: [] } : parsePriorities(o.text ?? "");
   const ranks = [1, 2, 3].map((i) => {
     const input = el("input", { type: "text", placeholder: i === 1 ? "e.g. Tasks can be ticked off and removed" : "" });
     if (items[i - 1]) input.value = items[i - 1];

package/templates/portal/js/views/paste.js

@@ -7,6 +7,7 @@
  * Nothing here writes. The panel parses, shows a diff, and waits for a second click. */
 
 import { getBrief, parsePaste, saveFile } from "../api.js";
+import { mdlite } from "../md.js";
 import { el, toClipboard } from "../dom.js";
 import { unifiedDiff, diffStat } from "../textdiff.js";
 
@@ -123,23 +124,47 @@ export function paste(opts) {
       result.append(note);
     }
 
+    // What the AI said around the file: its caveats and "check these" are worth reading first.
+    const notes = String(answer.value ?? "")
+      .replace(/<<<ROSTER FILE [^>]+>>>[\s\S]*?<<<ROSTER END>>>/g, "")
+      .trim();
+
     for (const file of data.files ?? []) {
-      if (file.unchanged) continue;
       const card = el("div", { className: "pastefile" });
-      const stat = diffStat(file.before, file.text);
+      const name = file.path.split("/").slice(-2).join("/");
+      if (file.unchanged) {
+        card.append(el("p", { className: "verdict", textContent: "✓ Same as what's already in " + name + ". Nothing to save." }));
+        result.append(card);
+        continue;
+      }
       card.append(
-        el("b", { textContent: file.path }),
-        el("span", {
-          className: "meta",
-          textContent: `+${stat.added} −${stat.removed}` + (file.writable ? "" : " · not writable"),
+        el("p", {
+          className: "verdict" + (file.writable ? " ok" : " bad"),
+          textContent: file.writable
+            ? "✓ Looks good. Saving replaces " + name + " with this:"
+            : "✗ " + file.path + " can't be written from here.",
         }),
       );
-      const diff = el("pre", { className: "diff" });
+      card.append(el("div", { className: "md doc pastepreview", innerHTML: mdlite(file.text) }));
+
+      if (notes) {
+        const said = el("details", { className: "pastenotes", open: true });
+        said.append(el("summary", { textContent: "Your AI also said" }), el("div", { className: "md doc", innerHTML: mdlite(notes) }));
+        card.append(said);
+      }
+
+      const diff = el("pre", { className: "diff", hidden: true });
       diff.textContent = unifiedDiff(file.before, file.text, file.path);
-      card.append(diff);
+      const stat = diffStat(file.before, file.text);
+      const toggle = el("button", { className: "ghbtn", textContent: `Show changes (+${stat.added} −${stat.removed})` });
+      toggle.onclick = () => {
+        diff.hidden = !diff.hidden;
+        toggle.textContent = (diff.hidden ? "Show changes" : "Hide changes") + ` (+${stat.added} −${stat.removed})`;
+      };
 
+      const row = el("div", { className: "row" });
       if (file.writable) {
-        const save = el("button", { className: "btn primary", textContent: "Save and commit" });
+        const save = el("button", { className: "btn primary", textContent: "Save" });
         save.onclick = async () => {
           save.disabled = true;
           save.textContent = "Saving…";
@@ -150,17 +175,19 @@ export function paste(opts) {
             opts.onSaved?.();
           } catch (err) {
             save.disabled = false;
-            save.textContent = "Save and commit";
+            save.textContent = "Save";
             card.append(el("p", { className: "err", textContent: String(err.message || err) }));
           }
         };
-        card.append(save);
+        row.append(save);
       }
+      row.append(toggle);
+      card.append(row, diff);
       result.append(card);
     }
 
     if (!(data.problems ?? []).length && !(data.files ?? []).length) {
-      result.append(el("p", { className: "sub", textContent: "Nothing to do." }));
+      result.append(el("p", { className: "verdict bad", textContent: "✗ No file found in that reply." }));
     }
   };
 

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

@@ -219,13 +219,9 @@ export function viewStaff(m) {
 
     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", "Create their GitHub App, then install it on the repos it opens with ticked"),
       line("todo", "Write the charter"),
-      line("todo", "Run once now, or roster run " + s.handle + " --apply: the run that proves the wiring"),
+      line("todo", "Run once now, to check everything works"),
     );
     for (const w of plan.warnings ?? []) box.append(line("warn", S.data.staff.length ? w : portalWords(w)));