plures 1.9.1 → 1.11.0

package/README.md

@@ -48,7 +48,9 @@ if (event.type === "task.completed" && event.data.result?.agreement === 1) {
 - `plures.tasks.retrieve(id)`, `plures.tasks.list({ status?, limit?, starting_after?, app? })`, `plures.tasks.cancel(id)`
 - `new Plures(key, { app: "support-agent" })` or `PLURES_APP`: send everything to one of your apps. `plures.apps.list()`, `.create({ name, id? })`, `.retrieve(id)`, `.update(id, { name?, id?, default? })`, `.del(id)`. Each app keeps its own tasks, ledger view, map and quality.
 - `plures.maps.guide()`, `.retrieve(app)`, `.upload(app, map)`, `.setCheckpoint(app, id, status)`: the agent map, where your agent needs a person. Or run `npx plures map` in your repo: your own coding agent reads the code and only the map is sent.
-- `plures.maps.createKey(app, { label? })`, `.keys(app)`, `.revokeKey(app, id)`: map keys for CI, which can only read and upload that app's map. `.workflow(app, branch?)` returns the GitHub Action that maps on every push; `npx plures map workflow` writes it to `.github/workflows/plures-map.yml`. Or use **Map with GitHub** on the app's map page and Plures opens the pull request for you. `plures.maps.startRun(app)` and `.runs(app)`: in CI with no Claude key, `npx plures map` starts a run where Plures runs Claude (first map free, then Claude's cost plus 30%, at most $5).
+- `plures.maps.createKey(app, { label? })`, `.keys(app)`, `.revokeKey(app, id)`: map keys for CI, which can only read and upload that app's map. `.workflow(app, branch?)` returns the GitHub Action that maps on every push; `npx plures map workflow` writes it to `.github/workflows/plures-map.yml`. Or use **Map with GitHub** on the app's map page and Plures opens the pull request for you, then **Turn on mapping** merges it. `plures.maps.startRun(app)` and `.runs(app)`: in CI with no Claude key, `npx plures map` starts a run where Plures runs Claude (first map free, then Claude's cost plus 30%, at most $5).
+- `npx plures map` shows each file as Claude Code reads it and sends the file names (never their contents) to Plures, so the map page shows the reading live and the map builds itself when it lands. `plures.maps.progress(app, { session, phase, events })` is the call behind it.
+- `plures.github.repos()`, `.connect(app, "owner/repo")`, `.turnOn(app)`, `.status(app)`, `.disconnect(app)`: Map with GitHub from code. Plures sets the repo's map key secret and opens a pull request adding the workflow; `turnOn` merges it. Installing the Plures GitHub App needs a browser once (`install_url`). From a terminal: `npx plures map github connect`, then `npx plures map github on`.
 - `plures.quality.sample({ rubric, output, input? })`: send every output; a share is graded by people against the rubric, with personal details taken out first. `plures.quality.rubrics.create({ name, question, options, sample_rate })`, `.retrieve(name)` (score by day, this week against the four before, drift), `.list()`, `.update()`, `.del()`. `plures.quality.compare({ release, input, a, b })` and `plures.quality.release(name)` for blind release checks. `plures.quality.export(rubric)` returns graded samples for evals or fine tuning.
 - `plures.testMix.set({ unanimous: 70, split: 20, tie: 5, expired: 5 })`, `.get()`, `.clear()`: with a test key, makes a share of test tasks split, tie or expire at random so you can test routing to your team without changing your agent. A task can override it with `metadata.test_mix`, and `metadata.test_outcome` beats both.
 - `plures.routing.get()`, `plures.routing.set({ groups, rules, team })`: named teams of your own people and rules by category, like `{ groups: [{ name: "Finance", emails: ["ap@acme.com"] }], rules: [{ category: "refunds", route: "team", group: "Finance" }] }`. What you send replaces what's there; the rest stays.

package/dist/{chunk-23ZYPCPM.js → chunk-WPSUIAVZ.js}

@@ -1,5 +1,5 @@
 // src/index.ts
-var VERSION = "1.9.1";
+var VERSION = "1.11.0";
 var PluresError = class extends Error {
   constructor(message, status, type) {
     super(message);
@@ -109,12 +109,31 @@ var Plures = class {
     /** Starts a map run where Plures runs Claude (CI with no Anthropic key). npx plures map does this. */
     startRun: (app) => this.req("POST", `/api/v1/apps/${encodeURIComponent(app)}/map_runs`, {}),
     runs: (app) => this.req("GET", `/api/v1/apps/${encodeURIComponent(app)}/map_runs`),
+    /** While mapping, which files the coding agent is reading, shown live on the map page. File names only. npx plures map does this. */
+    progress: (app, p) => this.req("POST", `/api/v1/apps/${encodeURIComponent(app)}/map/progress`, p),
     /** The GitHub Actions workflow that maps a repo on every push to its main branch. */
     workflow: async (app, branch = "main") => {
       const r = await fetch(`${this.base}/api/v1/map_workflow?app=${encodeURIComponent(app)}&branch=${encodeURIComponent(branch)}`);
       return r.text();
     }
   };
+  /**
+   * Map with GitHub: Plures adds a workflow to your repo by pull request and keeps the app's map
+   * current on every push. Installing the Plures GitHub App needs a browser once (installUrl);
+   * everything after that works here.
+   */
+  github = {
+    /** Repos the Plures GitHub App can reach. installed is false until you install it at install_url. */
+    repos: () => this.req("GET", "/api/v1/github/repos"),
+    /** Where an app's GitHub link stands: repo, pull request, mapping on, latest run, last map. */
+    status: (app) => this.req("GET", `/api/v1/apps/${encodeURIComponent(app)}/github`),
+    /** Connects a repo ("owner/name"): sets its map key secret and opens the pull request. */
+    connect: (app, repo) => this.req("POST", `/api/v1/apps/${encodeURIComponent(app)}/github`, { repo }),
+    /** Turns mapping on by merging the pull request. The repo's own rules (reviews, checks) still apply. */
+    turnOn: (app) => this.req("POST", `/api/v1/apps/${encodeURIComponent(app)}/github/merge`, {}),
+    /** Revokes the repo's map key. Delete the workflow file in the repo to stop runs. */
+    disconnect: (app) => this.req("DELETE", `/api/v1/apps/${encodeURIComponent(app)}/github`)
+  };
   /**
    * Quality: people grade a sample of your agent's outputs against a rubric, so you see drift
    * early, and compare two versions blind before you ship. Personal details are taken out first.

package/dist/cli.cjs

@@ -3,10 +3,12 @@
 
 // src/cli.ts
 var import_node_child_process = require("child_process");
+var import_node_crypto = require("crypto");
+var import_node_path = require("path");
 var import_node_fs = require("fs");
 
 // src/index.ts
-var VERSION = "1.9.1";
+var VERSION = "1.11.0";
 var PluresError = class extends Error {
   constructor(message, status, type) {
     super(message);
@@ -116,12 +118,31 @@ var Plures = class {
     /** Starts a map run where Plures runs Claude (CI with no Anthropic key). npx plures map does this. */
     startRun: (app2) => this.req("POST", `/api/v1/apps/${encodeURIComponent(app2)}/map_runs`, {}),
     runs: (app2) => this.req("GET", `/api/v1/apps/${encodeURIComponent(app2)}/map_runs`),
+    /** While mapping, which files the coding agent is reading, shown live on the map page. File names only. npx plures map does this. */
+    progress: (app2, p) => this.req("POST", `/api/v1/apps/${encodeURIComponent(app2)}/map/progress`, p),
     /** The GitHub Actions workflow that maps a repo on every push to its main branch. */
     workflow: async (app2, branch2 = "main") => {
       const r = await fetch(`${this.base}/api/v1/map_workflow?app=${encodeURIComponent(app2)}&branch=${encodeURIComponent(branch2)}`);
       return r.text();
     }
   };
+  /**
+   * Map with GitHub: Plures adds a workflow to your repo by pull request and keeps the app's map
+   * current on every push. Installing the Plures GitHub App needs a browser once (installUrl);
+   * everything after that works here.
+   */
+  github = {
+    /** Repos the Plures GitHub App can reach. installed is false until you install it at install_url. */
+    repos: () => this.req("GET", "/api/v1/github/repos"),
+    /** Where an app's GitHub link stands: repo, pull request, mapping on, latest run, last map. */
+    status: (app2) => this.req("GET", `/api/v1/apps/${encodeURIComponent(app2)}/github`),
+    /** Connects a repo ("owner/name"): sets its map key secret and opens the pull request. */
+    connect: (app2, repo) => this.req("POST", `/api/v1/apps/${encodeURIComponent(app2)}/github`, { repo }),
+    /** Turns mapping on by merging the pull request. The repo's own rules (reviews, checks) still apply. */
+    turnOn: (app2) => this.req("POST", `/api/v1/apps/${encodeURIComponent(app2)}/github/merge`, {}),
+    /** Revokes the repo's map key. Delete the workflow file in the repo to stop runs. */
+    disconnect: (app2) => this.req("DELETE", `/api/v1/apps/${encodeURIComponent(app2)}/github`)
+  };
   /**
    * Quality: people grade a sample of your agent's outputs against a rubric, so you see drift
    * early, and compare two versions blind before you ship. Personal details are taken out first.
@@ -283,11 +304,73 @@ With plures-mcp connected, just ask: ${cyan("Map this app for Plures")}`);
   const prompt = `${guide}
 
 Write the map to ${FILE} in the current directory now. Read the code; don't run it or change anything else.`;
+  const live = key ? client() : null;
+  const session = (0, import_node_crypto.randomBytes)(12).toString("base64url");
+  const source = process.env.GITHUB_ACTIONS ? "github" : "cli";
+  let queue = [], phase = "reading", sent = "", reads = 0;
+  const flush = async () => {
+    if (!live) return;
+    const events = queue;
+    queue = [];
+    if (!events.length && sent === phase) return;
+    sent = phase;
+    await live.maps.progress(app, { session, phase, source, events }).catch(() => {
+    });
+  };
+  const tick = setInterval(() => {
+    void flush();
+  }, 900);
+  void flush();
+  const rel = (p) => {
+    if (typeof p !== "string" || !p) return null;
+    const r = (0, import_node_path.isAbsolute)(p) ? (0, import_node_path.relative)(process.cwd(), p) : p;
+    return r.startsWith("..") ? null : r.replace(/\\/g, "/");
+  };
+  let result = "";
   const code = await new Promise((resolve) => {
-    const p = (0, import_node_child_process.spawn)("claude", ["-p", prompt, "--allowedTools", "Read,Grep,Glob,Write,Bash(git rev-parse:*),Bash(git remote:*)"], { stdio: ["ignore", "inherit", "inherit"], env: childEnv });
+    const p = (0, import_node_child_process.spawn)("claude", ["-p", prompt, "--output-format", "stream-json", "--verbose", "--allowedTools", "Read,Grep,Glob,Write,Bash(git rev-parse:*),Bash(git remote:*)"], { stdio: ["ignore", "pipe", "inherit"], env: childEnv });
+    let buf = "";
+    p.stdout.on("data", (chunk) => {
+      buf += chunk.toString();
+      let i;
+      while ((i = buf.indexOf("\n")) >= 0) {
+        const line = buf.slice(0, i);
+        buf = buf.slice(i + 1);
+        let ev;
+        try {
+          ev = JSON.parse(line);
+        } catch {
+          continue;
+        }
+        if (ev.type === "result" && typeof ev.result === "string") result = ev.result;
+        for (const b of ev.type === "assistant" ? ev.message?.content ?? [] : []) {
+          if (b.type !== "tool_use") continue;
+          if (b.name === "Read") {
+            const f = rel(b.input?.file_path);
+            if (!f) continue;
+            reads++;
+            queue.push({ path: f, tool: "Read" });
+            console.log(`  ${dim(String(reads).padStart(3))}  ${dim("reading")} ${f}`);
+          } else if (b.name === "Write" && String(b.input?.file_path ?? "").endsWith(FILE)) {
+            phase = "drawing";
+            console.log(`
+  ${violet("drawing")}  the map`);
+          }
+        }
+      }
+    });
     p.on("close", (n) => resolve(n ?? 1));
     p.on("error", () => resolve(1));
   });
+  clearInterval(tick);
+  if (result) console.log(`
+${result.trim()}
+`);
+  const ok = code === 0 && (0, import_node_fs.existsSync)(FILE) && (0, import_node_fs.statSync)(FILE).mtimeMs !== before;
+  if (!ok) {
+    phase = "failed";
+    await flush();
+  } else await flush();
   if (code !== 0 || !(0, import_node_fs.existsSync)(FILE) || (0, import_node_fs.statSync)(FILE).mtimeMs === before) die(`Claude Code didn't write ${FILE}. Ask it directly, then run npx plures map upload.`);
   await upload(FILE);
 }
@@ -301,11 +384,58 @@ async function workflow() {
   (0, import_node_fs.writeFileSync)(path, await r.text());
   console.log(`${bold("Wrote " + path)}: maps this repo on every push to ${b}.
 
-Then add two repository secrets (Settings, Secrets and variables, Actions):
+Then add a repository secret (Settings, Secrets and variables, Actions):
   ${cyan("PLURES_MAP_KEY")}      a map key: ${dim(`${base}/dashboard/apps/${app}/map`)} or ${dim("POST /api/v1/apps/" + app + "/map_keys")}
-  ${cyan("ANTHROPIC_API_KEY")}   or ${cyan("CLAUDE_CODE_OAUTH_TOKEN")} from ${dim("claude setup-token")}
+Optional: ${cyan("ANTHROPIC_API_KEY")}, or ${cyan("CLAUDE_CODE_OAUTH_TOKEN")} from ${dim("claude setup-token")}, to map on your own key for free.
+Without it Plures maps it: the first map is free.
 
-Or let Plures do all of this: ${bold("Map with GitHub")} on the app's map page.`);
+Or let Plures do all of this: ${bold("npx plures map github connect")}.`);
+}
+function originRepo() {
+  const u = (0, import_node_child_process.spawnSync)("git", ["remote", "get-url", "origin"], { encoding: "utf8" }).stdout?.trim() ?? "";
+  return /github\.com[:/]([\w.-]+\/[\w.-]+?)(?:\.git)?$/.exec(u)?.[1];
+}
+async function github(action, arg) {
+  const p = client();
+  const show = (g) => {
+    if (!g.connected) return console.log(`${bold(app)} has no repo connected. Run ${cyan("npx plures map github connect")} in the repo, or pass ${cyan("owner/repo")}.`);
+    const on = g.mapping_on ? cyan("on") : coral("off until the pull request is merged");
+    console.log(`${bold(app)} maps from ${bold(g.repo)}: mapping ${on}.
+  Pull request  ${g.pull_request?.state} ${dim(g.pull_request?.url ?? "")}
+  Mapped by     ${g.mapped_by === "your_anthropic_key" ? "your Anthropic key, free" : g.mapped_by === "plures" ? `Plures${g.first_map_free ? ", first map free" : ""}` : coral("needs ANTHROPIC_API_KEY in the repo's secrets")}
+  Latest run    ${g.latest_run ? `${g.latest_run.conclusion ?? g.latest_run.status} ${dim(g.latest_run.url)}` : dim("none yet")}
+  Map           ${g.mapped_at ? `uploaded ${g.mapped_at}` : dim("arrives a few minutes after the first run")}`);
+    if (g.pull_request?.state === "open") console.log(`
+Turn it on: ${cyan("npx plures map github on")}${app !== "default" ? ` --app ${app}` : ""}`);
+  };
+  try {
+    if (!action || action === "status") return show(await p.github.status(app));
+    if (action === "on") {
+      const r = await p.github.turnOn(app);
+      console.log(r.already_merged ? "Mapping was already on." : `${bold("Mapping is on.")} The first run is starting on GitHub.`);
+      return show(await p.github.status(app));
+    }
+    if (action === "off") {
+      await p.github.disconnect(app);
+      return console.log(`Disconnected. The repo's map key is revoked. Delete ${cyan(".github/workflows/plures-map.yml")} in the repo to stop runs.`);
+    }
+    if (action === "connect") {
+      const repo = arg ?? originRepo();
+      if (!repo) die("Pass the repo as owner/name, or run this inside a clone of it.");
+      const list = await p.github.repos();
+      if (!list.installed || !list.data.some((r) => r.repo.toLowerCase() === repo.toLowerCase()))
+        die(`The Plures GitHub App can't reach ${repo} yet. Open this once, pick the repo, then run this again:
+  ${list.install_url}?app=${app}`);
+      const g = await p.github.connect(app, repo);
+      console.log(`${bold("Pull request opened")} in ${repo}: ${g.pull_request?.url}
+It adds one workflow file. Review it, then turn mapping on with ${cyan("npx plures map github on")}${app !== "default" ? ` --app ${app}` : ""}, or merge it on GitHub.`);
+      return;
+    }
+    die("npx plures map github [connect [owner/repo] | on | off]");
+  } catch (e) {
+    if (e instanceof PluresError) die(e.message);
+    throw e;
+  }
 }
 async function main() {
   const [cmd, sub, arg] = argv;
@@ -316,6 +446,8 @@ async function main() {
   npx plures map upload [file]         upload ${FILE}
   npx plures map guide                 print the steps for any coding agent
   npx plures map workflow              add a GitHub Action that maps on every push
+  npx plures map github connect        let Plures add that Action by pull request
+  npx plures map github on             merge it, which turns mapping on
 
 Docs: https://plures.si/docs`);
     return;
@@ -323,6 +455,7 @@ Docs: https://plures.si/docs`);
   if (sub === "upload") return upload(arg ?? FILE);
   if (sub === "guide") return void console.log(await (await fetch(`${base}/api/v1/map_guide`)).text());
   if (sub === "workflow") return workflow();
+  if (sub === "github") return github(arg, argv[3]);
   return map();
 }
 main().catch((e) => die(String(e?.message ?? e)));

package/dist/cli.js

@@ -3,10 +3,12 @@ import {
   Plures,
   PluresError,
   VERSION
-} from "./chunk-23ZYPCPM.js";
+} from "./chunk-WPSUIAVZ.js";
 
 // src/cli.ts
 import { spawnSync, spawn } from "child_process";
+import { randomBytes } from "crypto";
+import { relative, isAbsolute } from "path";
 import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "fs";
 var argv = process.argv.slice(2);
 var flag = (name) => {
@@ -106,11 +108,73 @@ With plures-mcp connected, just ask: ${cyan("Map this app for Plures")}`);
   const prompt = `${guide}
 
 Write the map to ${FILE} in the current directory now. Read the code; don't run it or change anything else.`;
+  const live = key ? client() : null;
+  const session = randomBytes(12).toString("base64url");
+  const source = process.env.GITHUB_ACTIONS ? "github" : "cli";
+  let queue = [], phase = "reading", sent = "", reads = 0;
+  const flush = async () => {
+    if (!live) return;
+    const events = queue;
+    queue = [];
+    if (!events.length && sent === phase) return;
+    sent = phase;
+    await live.maps.progress(app, { session, phase, source, events }).catch(() => {
+    });
+  };
+  const tick = setInterval(() => {
+    void flush();
+  }, 900);
+  void flush();
+  const rel = (p) => {
+    if (typeof p !== "string" || !p) return null;
+    const r = isAbsolute(p) ? relative(process.cwd(), p) : p;
+    return r.startsWith("..") ? null : r.replace(/\\/g, "/");
+  };
+  let result = "";
   const code = await new Promise((resolve) => {
-    const p = spawn("claude", ["-p", prompt, "--allowedTools", "Read,Grep,Glob,Write,Bash(git rev-parse:*),Bash(git remote:*)"], { stdio: ["ignore", "inherit", "inherit"], env: childEnv });
+    const p = spawn("claude", ["-p", prompt, "--output-format", "stream-json", "--verbose", "--allowedTools", "Read,Grep,Glob,Write,Bash(git rev-parse:*),Bash(git remote:*)"], { stdio: ["ignore", "pipe", "inherit"], env: childEnv });
+    let buf = "";
+    p.stdout.on("data", (chunk) => {
+      buf += chunk.toString();
+      let i;
+      while ((i = buf.indexOf("\n")) >= 0) {
+        const line = buf.slice(0, i);
+        buf = buf.slice(i + 1);
+        let ev;
+        try {
+          ev = JSON.parse(line);
+        } catch {
+          continue;
+        }
+        if (ev.type === "result" && typeof ev.result === "string") result = ev.result;
+        for (const b of ev.type === "assistant" ? ev.message?.content ?? [] : []) {
+          if (b.type !== "tool_use") continue;
+          if (b.name === "Read") {
+            const f = rel(b.input?.file_path);
+            if (!f) continue;
+            reads++;
+            queue.push({ path: f, tool: "Read" });
+            console.log(`  ${dim(String(reads).padStart(3))}  ${dim("reading")} ${f}`);
+          } else if (b.name === "Write" && String(b.input?.file_path ?? "").endsWith(FILE)) {
+            phase = "drawing";
+            console.log(`
+  ${violet("drawing")}  the map`);
+          }
+        }
+      }
+    });
     p.on("close", (n) => resolve(n ?? 1));
     p.on("error", () => resolve(1));
   });
+  clearInterval(tick);
+  if (result) console.log(`
+${result.trim()}
+`);
+  const ok = code === 0 && existsSync(FILE) && statSync(FILE).mtimeMs !== before;
+  if (!ok) {
+    phase = "failed";
+    await flush();
+  } else await flush();
   if (code !== 0 || !existsSync(FILE) || statSync(FILE).mtimeMs === before) die(`Claude Code didn't write ${FILE}. Ask it directly, then run npx plures map upload.`);
   await upload(FILE);
 }
@@ -124,11 +188,58 @@ async function workflow() {
   writeFileSync(path, await r.text());
   console.log(`${bold("Wrote " + path)}: maps this repo on every push to ${b}.
 
-Then add two repository secrets (Settings, Secrets and variables, Actions):
+Then add a repository secret (Settings, Secrets and variables, Actions):
   ${cyan("PLURES_MAP_KEY")}      a map key: ${dim(`${base}/dashboard/apps/${app}/map`)} or ${dim("POST /api/v1/apps/" + app + "/map_keys")}
-  ${cyan("ANTHROPIC_API_KEY")}   or ${cyan("CLAUDE_CODE_OAUTH_TOKEN")} from ${dim("claude setup-token")}
+Optional: ${cyan("ANTHROPIC_API_KEY")}, or ${cyan("CLAUDE_CODE_OAUTH_TOKEN")} from ${dim("claude setup-token")}, to map on your own key for free.
+Without it Plures maps it: the first map is free.
 
-Or let Plures do all of this: ${bold("Map with GitHub")} on the app's map page.`);
+Or let Plures do all of this: ${bold("npx plures map github connect")}.`);
+}
+function originRepo() {
+  const u = spawnSync("git", ["remote", "get-url", "origin"], { encoding: "utf8" }).stdout?.trim() ?? "";
+  return /github\.com[:/]([\w.-]+\/[\w.-]+?)(?:\.git)?$/.exec(u)?.[1];
+}
+async function github(action, arg) {
+  const p = client();
+  const show = (g) => {
+    if (!g.connected) return console.log(`${bold(app)} has no repo connected. Run ${cyan("npx plures map github connect")} in the repo, or pass ${cyan("owner/repo")}.`);
+    const on = g.mapping_on ? cyan("on") : coral("off until the pull request is merged");
+    console.log(`${bold(app)} maps from ${bold(g.repo)}: mapping ${on}.
+  Pull request  ${g.pull_request?.state} ${dim(g.pull_request?.url ?? "")}
+  Mapped by     ${g.mapped_by === "your_anthropic_key" ? "your Anthropic key, free" : g.mapped_by === "plures" ? `Plures${g.first_map_free ? ", first map free" : ""}` : coral("needs ANTHROPIC_API_KEY in the repo's secrets")}
+  Latest run    ${g.latest_run ? `${g.latest_run.conclusion ?? g.latest_run.status} ${dim(g.latest_run.url)}` : dim("none yet")}
+  Map           ${g.mapped_at ? `uploaded ${g.mapped_at}` : dim("arrives a few minutes after the first run")}`);
+    if (g.pull_request?.state === "open") console.log(`
+Turn it on: ${cyan("npx plures map github on")}${app !== "default" ? ` --app ${app}` : ""}`);
+  };
+  try {
+    if (!action || action === "status") return show(await p.github.status(app));
+    if (action === "on") {
+      const r = await p.github.turnOn(app);
+      console.log(r.already_merged ? "Mapping was already on." : `${bold("Mapping is on.")} The first run is starting on GitHub.`);
+      return show(await p.github.status(app));
+    }
+    if (action === "off") {
+      await p.github.disconnect(app);
+      return console.log(`Disconnected. The repo's map key is revoked. Delete ${cyan(".github/workflows/plures-map.yml")} in the repo to stop runs.`);
+    }
+    if (action === "connect") {
+      const repo = arg ?? originRepo();
+      if (!repo) die("Pass the repo as owner/name, or run this inside a clone of it.");
+      const list = await p.github.repos();
+      if (!list.installed || !list.data.some((r) => r.repo.toLowerCase() === repo.toLowerCase()))
+        die(`The Plures GitHub App can't reach ${repo} yet. Open this once, pick the repo, then run this again:
+  ${list.install_url}?app=${app}`);
+      const g = await p.github.connect(app, repo);
+      console.log(`${bold("Pull request opened")} in ${repo}: ${g.pull_request?.url}
+It adds one workflow file. Review it, then turn mapping on with ${cyan("npx plures map github on")}${app !== "default" ? ` --app ${app}` : ""}, or merge it on GitHub.`);
+      return;
+    }
+    die("npx plures map github [connect [owner/repo] | on | off]");
+  } catch (e) {
+    if (e instanceof PluresError) die(e.message);
+    throw e;
+  }
 }
 async function main() {
   const [cmd, sub, arg] = argv;
@@ -139,6 +250,8 @@ async function main() {
   npx plures map upload [file]         upload ${FILE}
   npx plures map guide                 print the steps for any coding agent
   npx plures map workflow              add a GitHub Action that maps on every push
+  npx plures map github connect        let Plures add that Action by pull request
+  npx plures map github on             merge it, which turns mapping on
 
 Docs: https://plures.si/docs`);
     return;
@@ -146,6 +259,7 @@ Docs: https://plures.si/docs`);
   if (sub === "upload") return upload(arg ?? FILE);
   if (sub === "guide") return void console.log(await (await fetch(`${base}/api/v1/map_guide`)).text());
   if (sub === "workflow") return workflow();
+  if (sub === "github") return github(arg, argv[3]);
   return map();
 }
 main().catch((e) => die(String(e?.message ?? e)));

package/dist/index.cjs

@@ -26,7 +26,7 @@ __export(index_exports, {
   default: () => index_default
 });
 module.exports = __toCommonJS(index_exports);
-var VERSION = "1.9.1";
+var VERSION = "1.11.0";
 var PluresError = class extends Error {
   constructor(message, status, type) {
     super(message);
@@ -136,12 +136,31 @@ var Plures = class {
     /** Starts a map run where Plures runs Claude (CI with no Anthropic key). npx plures map does this. */
     startRun: (app) => this.req("POST", `/api/v1/apps/${encodeURIComponent(app)}/map_runs`, {}),
     runs: (app) => this.req("GET", `/api/v1/apps/${encodeURIComponent(app)}/map_runs`),
+    /** While mapping, which files the coding agent is reading, shown live on the map page. File names only. npx plures map does this. */
+    progress: (app, p) => this.req("POST", `/api/v1/apps/${encodeURIComponent(app)}/map/progress`, p),
     /** The GitHub Actions workflow that maps a repo on every push to its main branch. */
     workflow: async (app, branch = "main") => {
       const r = await fetch(`${this.base}/api/v1/map_workflow?app=${encodeURIComponent(app)}&branch=${encodeURIComponent(branch)}`);
       return r.text();
     }
   };
+  /**
+   * Map with GitHub: Plures adds a workflow to your repo by pull request and keeps the app's map
+   * current on every push. Installing the Plures GitHub App needs a browser once (installUrl);
+   * everything after that works here.
+   */
+  github = {
+    /** Repos the Plures GitHub App can reach. installed is false until you install it at install_url. */
+    repos: () => this.req("GET", "/api/v1/github/repos"),
+    /** Where an app's GitHub link stands: repo, pull request, mapping on, latest run, last map. */
+    status: (app) => this.req("GET", `/api/v1/apps/${encodeURIComponent(app)}/github`),
+    /** Connects a repo ("owner/name"): sets its map key secret and opens the pull request. */
+    connect: (app, repo) => this.req("POST", `/api/v1/apps/${encodeURIComponent(app)}/github`, { repo }),
+    /** Turns mapping on by merging the pull request. The repo's own rules (reviews, checks) still apply. */
+    turnOn: (app) => this.req("POST", `/api/v1/apps/${encodeURIComponent(app)}/github/merge`, {}),
+    /** Revokes the repo's map key. Delete the workflow file in the repo to stop runs. */
+    disconnect: (app) => this.req("DELETE", `/api/v1/apps/${encodeURIComponent(app)}/github`)
+  };
   /**
    * Quality: people grade a sample of your agent's outputs against a rubric, so you see drift
    * early, and compare two versions blind before you ship. Personal details are taken out first.

package/dist/index.d.cts

@@ -350,7 +350,30 @@ type WebhookEvent = {
     created_at: string;
     data: Task;
 };
-declare const VERSION = "1.9.1";
+declare const VERSION = "1.11.0";
+type GitHubLink = {
+    object: "github_link";
+    app: string;
+    installed: boolean;
+    install_url: string;
+    connected: boolean;
+    repo?: string;
+    pull_request?: {
+        url: string | null;
+        state: "open" | "merged" | "closed" | "unknown";
+    };
+    mapping_on?: boolean;
+    mapped_by?: "plures" | "your_anthropic_key" | "needs_key";
+    first_map_free?: boolean;
+    latest_run?: {
+        status: string;
+        conclusion: string | null;
+        url: string;
+        created_at: string;
+    } | null;
+    mapped_at?: string | null;
+    connected_at?: string;
+};
 declare class PluresError extends Error {
     readonly status: number;
     readonly type: string;
@@ -484,9 +507,64 @@ declare class Plures {
                 created_at: string;
             }[];
         }>;
+        /** While mapping, which files the coding agent is reading, shown live on the map page. File names only. npx plures map does this. */
+        progress: (app: string, p: {
+            session: string;
+            phase?: "reading" | "drawing" | "done" | "failed";
+            source?: "cli" | "github";
+            events?: {
+                path: string;
+                tool?: string;
+            }[];
+        }) => Promise<{
+            object: "map_progress";
+            app: string;
+            session: string;
+            phase: string;
+            received: number;
+        }>;
         /** The GitHub Actions workflow that maps a repo on every push to its main branch. */
         workflow: (app: string, branch?: string) => Promise<string>;
     };
+    /**
+     * Map with GitHub: Plures adds a workflow to your repo by pull request and keeps the app's map
+     * current on every push. Installing the Plures GitHub App needs a browser once (installUrl);
+     * everything after that works here.
+     */
+    github: {
+        /** Repos the Plures GitHub App can reach. installed is false until you install it at install_url. */
+        repos: () => Promise<{
+            object: "list";
+            installed: boolean;
+            install_url: string;
+            data: {
+                object: "github_repo";
+                repo: string;
+                private: boolean;
+                account: string;
+                default_branch: string;
+            }[];
+        }>;
+        /** Where an app's GitHub link stands: repo, pull request, mapping on, latest run, last map. */
+        status: (app: string) => Promise<GitHubLink>;
+        /** Connects a repo ("owner/name"): sets its map key secret and opens the pull request. */
+        connect: (app: string, repo: string) => Promise<GitHubLink>;
+        /** Turns mapping on by merging the pull request. The repo's own rules (reviews, checks) still apply. */
+        turnOn: (app: string) => Promise<{
+            object: "github_merge";
+            app: string;
+            merged: true;
+            already_merged: boolean;
+            sha: string | null;
+        }>;
+        /** Revokes the repo's map key. Delete the workflow file in the repo to stop runs. */
+        disconnect: (app: string) => Promise<{
+            object: "github_link";
+            app: string;
+            connected: false;
+            deleted: true;
+        }>;
+    };
     /**
      * Quality: people grade a sample of your agent's outputs against a rubric, so you see drift
      * early, and compare two versions blind before you ship. Personal details are taken out first.
@@ -578,4 +656,4 @@ declare class Plures {
     static verifyWebhook(rawBody: string, signatureHeader: string | null, secret: string, toleranceSec?: number): Promise<WebhookEvent>;
 }
 
-export { type AgentMap, type App, type Balance, type Consensus, type CreateTask, type Escalation, type MapCheckpoint, type MapDraft, type MapKey, type MapNode, type Mix, type Option, Plures, PluresError, type Release, type Result, type Route, type Routing, type RoutingRule, type RoutingUpdate, type Rubric, type RubricParams, type Sample, type StoredAgentMap, type Task, type TaskStatus, type TeamTally, type TeamVote, type TestMix, VERSION, type WebhookEvent, Plures as default };
+export { type AgentMap, type App, type Balance, type Consensus, type CreateTask, type Escalation, type GitHubLink, type MapCheckpoint, type MapDraft, type MapKey, type MapNode, type Mix, type Option, Plures, PluresError, type Release, type Result, type Route, type Routing, type RoutingRule, type RoutingUpdate, type Rubric, type RubricParams, type Sample, type StoredAgentMap, type Task, type TaskStatus, type TeamTally, type TeamVote, type TestMix, VERSION, type WebhookEvent, Plures as default };

package/dist/index.d.ts

@@ -350,7 +350,30 @@ type WebhookEvent = {
     created_at: string;
     data: Task;
 };
-declare const VERSION = "1.9.1";
+declare const VERSION = "1.11.0";
+type GitHubLink = {
+    object: "github_link";
+    app: string;
+    installed: boolean;
+    install_url: string;
+    connected: boolean;
+    repo?: string;
+    pull_request?: {
+        url: string | null;
+        state: "open" | "merged" | "closed" | "unknown";
+    };
+    mapping_on?: boolean;
+    mapped_by?: "plures" | "your_anthropic_key" | "needs_key";
+    first_map_free?: boolean;
+    latest_run?: {
+        status: string;
+        conclusion: string | null;
+        url: string;
+        created_at: string;
+    } | null;
+    mapped_at?: string | null;
+    connected_at?: string;
+};
 declare class PluresError extends Error {
     readonly status: number;
     readonly type: string;
@@ -484,9 +507,64 @@ declare class Plures {
                 created_at: string;
             }[];
         }>;
+        /** While mapping, which files the coding agent is reading, shown live on the map page. File names only. npx plures map does this. */
+        progress: (app: string, p: {
+            session: string;
+            phase?: "reading" | "drawing" | "done" | "failed";
+            source?: "cli" | "github";
+            events?: {
+                path: string;
+                tool?: string;
+            }[];
+        }) => Promise<{
+            object: "map_progress";
+            app: string;
+            session: string;
+            phase: string;
+            received: number;
+        }>;
         /** The GitHub Actions workflow that maps a repo on every push to its main branch. */
         workflow: (app: string, branch?: string) => Promise<string>;
     };
+    /**
+     * Map with GitHub: Plures adds a workflow to your repo by pull request and keeps the app's map
+     * current on every push. Installing the Plures GitHub App needs a browser once (installUrl);
+     * everything after that works here.
+     */
+    github: {
+        /** Repos the Plures GitHub App can reach. installed is false until you install it at install_url. */
+        repos: () => Promise<{
+            object: "list";
+            installed: boolean;
+            install_url: string;
+            data: {
+                object: "github_repo";
+                repo: string;
+                private: boolean;
+                account: string;
+                default_branch: string;
+            }[];
+        }>;
+        /** Where an app's GitHub link stands: repo, pull request, mapping on, latest run, last map. */
+        status: (app: string) => Promise<GitHubLink>;
+        /** Connects a repo ("owner/name"): sets its map key secret and opens the pull request. */
+        connect: (app: string, repo: string) => Promise<GitHubLink>;
+        /** Turns mapping on by merging the pull request. The repo's own rules (reviews, checks) still apply. */
+        turnOn: (app: string) => Promise<{
+            object: "github_merge";
+            app: string;
+            merged: true;
+            already_merged: boolean;
+            sha: string | null;
+        }>;
+        /** Revokes the repo's map key. Delete the workflow file in the repo to stop runs. */
+        disconnect: (app: string) => Promise<{
+            object: "github_link";
+            app: string;
+            connected: false;
+            deleted: true;
+        }>;
+    };
     /**
      * Quality: people grade a sample of your agent's outputs against a rubric, so you see drift
      * early, and compare two versions blind before you ship. Personal details are taken out first.
@@ -578,4 +656,4 @@ declare class Plures {
     static verifyWebhook(rawBody: string, signatureHeader: string | null, secret: string, toleranceSec?: number): Promise<WebhookEvent>;
 }
 
-export { type AgentMap, type App, type Balance, type Consensus, type CreateTask, type Escalation, type MapCheckpoint, type MapDraft, type MapKey, type MapNode, type Mix, type Option, Plures, PluresError, type Release, type Result, type Route, type Routing, type RoutingRule, type RoutingUpdate, type Rubric, type RubricParams, type Sample, type StoredAgentMap, type Task, type TaskStatus, type TeamTally, type TeamVote, type TestMix, VERSION, type WebhookEvent, Plures as default };
+export { type AgentMap, type App, type Balance, type Consensus, type CreateTask, type Escalation, type GitHubLink, type MapCheckpoint, type MapDraft, type MapKey, type MapNode, type Mix, type Option, Plures, PluresError, type Release, type Result, type Route, type Routing, type RoutingRule, type RoutingUpdate, type Rubric, type RubricParams, type Sample, type StoredAgentMap, type Task, type TaskStatus, type TeamTally, type TeamVote, type TestMix, VERSION, type WebhookEvent, Plures as default };

package/dist/index.js

@@ -3,7 +3,7 @@ import {
   PluresError,
   VERSION,
   index_default
-} from "./chunk-23ZYPCPM.js";
+} from "./chunk-WPSUIAVZ.js";
 export {
   Plures,
   PluresError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plures",
-  "version": "1.9.1",
+  "version": "1.11.0",
   "description": "Human judgment as an API for AI agents. Send a decision to ID verified people and get their consensus back.",
   "keywords": [
     "human-in-the-loop",