plures 1.3.1 → 1.7.0

package/README.md

@@ -44,8 +44,13 @@ if (event.type === "task.completed" && event.data.result?.agreement === 1) {
 
 ## API
 
-- `plures.tasks.create(params, { idempotencyKey? })`: send a task. Params: `question`, `options` (2 to 8, strings or `{ id, label }`), `context`, `image_url`, `audio_url` or `video_url` with `media_seconds` (a clip up to 180 seconds that people play through before answering), `sensitive`, `instructions`, `verifiers` (1, 3, 5, 7 or 9), `max_verifiers`, `presence_check` (default true), `webhook_url`, `metadata`, `expires_in`.
-- `plures.tasks.retrieve(id)`, `plures.tasks.list({ status?, limit?, starting_after? })`, `plures.tasks.cancel(id)`
+- `plures.tasks.create(params, { idempotencyKey? })`: send a task. Params: `question`, `options` (2 to 8, strings or `{ id, label }`), `context`, `image_url`, `audio_url` or `video_url` with `media_seconds` (a clip up to 180 seconds that people play through before answering), `sensitive`, `instructions`, `verifiers` (1, 3, 5, 7 or 9), `max_verifiers`, `presence_check` (default true), `webhook_url`, `metadata`, `expires_in`, `route` (`"team"` sends it straight to your own people, $0.05 per internal vote live), `category` (matches your routing rules) and `team` (one of your named teams), `team_votes` and `team_unanimous` (internal consensus: how many of your team vote, and whether they must all agree; a split goes to the team's lead).
+- `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.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.
 - `plures.balance()`: your prepaid credit for live tasks, in cents. Live tasks cost $0.20 per answer (more for clips); a task that could cost more than your available credit throws a `PluresError` with `type` `insufficient_credits` (status 402).
 - `plures.tasks.waitFor(id, { timeoutMs?, intervalMs? })`: poll until settled
 - `plures.verify(params, { timeoutMs?, idempotencyKey? })`: create and wait

package/dist/chunk-XOB4CPDP.js

@@ -0,0 +1,174 @@
+// src/index.ts
+var VERSION = "1.7.0";
+var PluresError = class extends Error {
+  constructor(message, status, type) {
+    super(message);
+    this.status = status;
+    this.type = type;
+  }
+  status;
+  type;
+};
+var Plures = class {
+  base;
+  apiKey;
+  /** The app tasks go to when they don't name one. From opts.app or PLURES_APP. */
+  app;
+  ua;
+  constructor(apiKey, opts = {}) {
+    const key = apiKey ?? (typeof process !== "undefined" ? process.env?.PLURES_API_KEY : void 0);
+    if (!key) throw new Error("Pass your Plures API key, or set PLURES_API_KEY. Get a free test key at https://plures.si/?for=developers#join");
+    this.apiKey = key;
+    this.ua = opts.userAgent ?? `plures-js/${VERSION}`;
+    this.app = opts.app ?? (typeof process !== "undefined" ? process.env?.PLURES_APP : void 0) ?? null;
+    this.base = (opts.baseUrl ?? (typeof process !== "undefined" ? process.env?.PLURES_BASE_URL : void 0) ?? "https://plures.si").replace(/\/$/, "");
+  }
+  async req(method, path, body, headers = {}) {
+    for (let attempt = 0; ; attempt++) {
+      const r = await fetch(this.base + path, {
+        method,
+        headers: { authorization: `Bearer ${this.apiKey}`, "user-agent": this.ua, ...body ? { "content-type": "application/json" } : {}, ...this.app ? { "plures-app": this.app } : {}, ...headers },
+        body: body ? JSON.stringify(body) : void 0
+      });
+      if (r.status >= 500 && attempt < 2) {
+        await sleep(500 * 2 ** attempt);
+        continue;
+      }
+      const data = await r.json().catch(() => ({}));
+      if (!r.ok) throw new PluresError(data?.error?.message ?? `HTTP ${r.status}`, r.status, data?.error?.type ?? "api_error");
+      return data;
+    }
+  }
+  tasks = {
+    /** Sends a question to verified people. Pass an idempotency key to make retries safe. */
+    create: (params, opts = {}) => this.req("POST", "/api/v1/tasks", params, opts.idempotencyKey ? { "idempotency-key": opts.idempotencyKey } : {}),
+    retrieve: (id) => this.req("GET", `/api/v1/tasks/${encodeURIComponent(id)}`),
+    list: (params = {}) => {
+      const q = new URLSearchParams(Object.entries(params).filter(([, v]) => v != null).map(([k, v]) => [k, String(v)]));
+      return this.req("GET", `/api/v1/tasks${q.size ? `?${q}` : ""}`);
+    },
+    cancel: (id) => this.req("POST", `/api/v1/tasks/${encodeURIComponent(id)}/cancel`),
+    /** Polls until the task is settled. Prefer webhooks in production. */
+    waitFor: async (id, opts = {}) => {
+      const end = Date.now() + (opts.timeoutMs ?? 10 * 6e4);
+      for (; ; ) {
+        const t = await this.tasks.retrieve(id);
+        if (t.status !== "pending") return t;
+        if (Date.now() > end) return t;
+        await sleep(opts.intervalMs ?? 3e3);
+      }
+    }
+  };
+  /**
+   * Test keys only. How test tasks behave when they don't set metadata.test_outcome,
+   * so an agent running unchanged sends a share of decisions to your team.
+   * A single task can override it with metadata.test_mix.
+   */
+  testMix = {
+    get: () => this.req("GET", "/api/v1/test_mix"),
+    /** For example { unanimous: 70, split: 20, tie: 5, expired: 5 }. Pass null to turn it off. */
+    set: (mix) => this.req("PUT", "/api/v1/test_mix", { mix }),
+    clear: () => this.req("DELETE", "/api/v1/test_mix")
+  };
+  /**
+   * Where tasks go. set() replaces what you send (team, groups or rules) and keeps the rest.
+   * For example { groups: [{ name: "Finance", emails: ["ap@acme.com"] }], rules: [{ category: "refunds", route: "team", group: "Finance" }] }.
+   */
+  routing = {
+    get: () => this.req("GET", "/api/v1/routing"),
+    set: (update) => this.req("PUT", "/api/v1/routing", update)
+  };
+  /** Your apps. Each agent you run can be its own app, with its own tasks, ledger view and map. */
+  apps = {
+    list: () => this.req("GET", "/api/v1/apps"),
+    /** { name: "Support agent" }, with an optional id like "support-agent". */
+    create: (params) => this.req("POST", "/api/v1/apps", params),
+    retrieve: (id) => this.req("GET", `/api/v1/apps/${encodeURIComponent(id)}`),
+    /** Rename it, change its id (its tasks move with it), or make it the default. */
+    update: (id, params) => this.req("PATCH", `/api/v1/apps/${encodeURIComponent(id)}`, params),
+    /** Only an app with no tasks can be deleted. */
+    del: (id) => this.req("DELETE", `/api/v1/apps/${encodeURIComponent(id)}`)
+  };
+  /**
+   * Agent maps: where each app's agent needs a person. Your coding agent reads your code and
+   * writes the map; Plures gets only the map. guide() returns the steps it follows.
+   */
+  maps = {
+    guide: async () => {
+      const r = await fetch(`${this.base}/api/v1/map_guide`);
+      return r.text();
+    },
+    retrieve: (app) => this.req("GET", `/api/v1/apps/${encodeURIComponent(app)}/map`),
+    /** Uploads a new version. Checks you already added or dismissed keep that. */
+    upload: (app, map) => this.req("PUT", `/api/v1/apps/${encodeURIComponent(app)}/map`, map),
+    setCheckpoint: (app, id, status) => this.req("PATCH", `/api/v1/apps/${encodeURIComponent(app)}/map/checkpoints/${encodeURIComponent(id)}`, { status })
+  };
+  /**
+   * 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.
+   */
+  quality = {
+    /** Send every output; the rubric's sample rate decides which ones people grade. */
+    sample: (p) => this.req("POST", "/api/v1/samples", p),
+    /** A blind release check: a is the current version's output, b the new one's, for the same input. */
+    compare: (p) => this.req("POST", "/api/v1/comparisons", p),
+    /** How often people preferred the new version, with a 95% range and a verdict. */
+    release: (name, opts = {}) => this.req("GET", `/api/v1/releases/${encodeURIComponent(name)}${opts.app ? `?app=${encodeURIComponent(opts.app)}` : ""}`),
+    rubrics: {
+      list: (opts = {}) => this.req("GET", `/api/v1/rubrics${opts.app ? `?app=${encodeURIComponent(opts.app)}` : ""}`),
+      /** { name: "reply_quality", question: "Is this reply correct and kind?", options: ["Good", "Okay", "Bad"], sample_rate: 0.05 } */
+      create: (p) => this.req("POST", "/api/v1/rubrics", p),
+      retrieve: (name, opts = {}) => this.req("GET", `/api/v1/rubrics/${encodeURIComponent(name)}${opts.app ? `?app=${encodeURIComponent(opts.app)}` : ""}`),
+      update: (name, p) => this.req("PATCH", `/api/v1/rubrics/${encodeURIComponent(name)}${p.app ? `?app=${encodeURIComponent(p.app)}` : ""}`, p),
+      del: (name, opts = {}) => this.req("DELETE", `/api/v1/rubrics/${encodeURIComponent(name)}${opts.app ? `?app=${encodeURIComponent(opts.app)}` : ""}`)
+    },
+    /** Graded samples as JSON lines (input, output, grade, score, agreement), for fine tuning or an eval set. */
+    export: async (rubric, opts = {}) => {
+      const q = new URLSearchParams(Object.entries({ app: opts.app ?? this.app ?? void 0, since: opts.since }).filter(([, v]) => v));
+      const r = await fetch(`${this.base}/api/v1/rubrics/${encodeURIComponent(rubric)}/export${q.size ? `?${q}` : ""}`, { headers: { authorization: `Bearer ${this.apiKey}`, "user-agent": this.ua } });
+      if (!r.ok) {
+        const d = await r.json().catch(() => ({}));
+        throw new PluresError(d?.error?.message ?? `HTTP ${r.status}`, r.status, d?.error?.type ?? "api_error");
+      }
+      return (await r.text()).split("\n").filter(Boolean).map((l) => JSON.parse(l));
+    }
+  };
+  /** Your prepaid credit. A live task that could cost more than available_cents is refused with a 402 insufficient_credits error. */
+  balance = () => this.req("GET", "/api/v1/balance");
+  /** Creates a task and waits for people to answer it. */
+  async verify(params, opts = {}) {
+    const t = await this.tasks.create(params, { idempotencyKey: opts.idempotencyKey });
+    return t.status === "pending" ? this.tasks.waitFor(t.id, { timeoutMs: opts.timeoutMs }) : t;
+  }
+  /**
+   * Checks the Plures-Signature header on a webhook and returns the parsed event.
+   * Pass the raw request body exactly as received. Throws if the signature is wrong
+   * or older than toleranceSec.
+   */
+  static async verifyWebhook(rawBody, signatureHeader, secret, toleranceSec = 300) {
+    const parts = Object.fromEntries((signatureHeader ?? "").split(",").map((p) => p.split("=", 2)));
+    const t = Number(parts.t);
+    if (!t || !parts.v1) throw new Error("Missing Plures-Signature header");
+    if (Math.abs(Date.now() / 1e3 - t) > toleranceSec) throw new Error("Webhook timestamp is too old");
+    const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    const mac = new Uint8Array(await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(`${t}.${rawBody}`)));
+    const expected = Array.from(mac, (b) => b.toString(16).padStart(2, "0")).join("");
+    if (!timingSafeEqual(expected, parts.v1)) throw new Error("Webhook signature does not match");
+    return JSON.parse(rawBody);
+  }
+};
+function timingSafeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+var index_default = Plures;
+
+export {
+  VERSION,
+  PluresError,
+  Plures,
+  index_default
+};

package/dist/cli.cjs

@@ -0,0 +1,284 @@
+#!/usr/bin/env node
+"use strict";
+
+// src/cli.ts
+var import_node_child_process = require("child_process");
+var import_node_fs = require("fs");
+
+// src/index.ts
+var VERSION = "1.7.0";
+var PluresError = class extends Error {
+  constructor(message, status, type) {
+    super(message);
+    this.status = status;
+    this.type = type;
+  }
+  status;
+  type;
+};
+var Plures = class {
+  base;
+  apiKey;
+  /** The app tasks go to when they don't name one. From opts.app or PLURES_APP. */
+  app;
+  ua;
+  constructor(apiKey, opts = {}) {
+    const key2 = apiKey ?? (typeof process !== "undefined" ? process.env?.PLURES_API_KEY : void 0);
+    if (!key2) throw new Error("Pass your Plures API key, or set PLURES_API_KEY. Get a free test key at https://plures.si/?for=developers#join");
+    this.apiKey = key2;
+    this.ua = opts.userAgent ?? `plures-js/${VERSION}`;
+    this.app = opts.app ?? (typeof process !== "undefined" ? process.env?.PLURES_APP : void 0) ?? null;
+    this.base = (opts.baseUrl ?? (typeof process !== "undefined" ? process.env?.PLURES_BASE_URL : void 0) ?? "https://plures.si").replace(/\/$/, "");
+  }
+  async req(method, path, body, headers = {}) {
+    for (let attempt = 0; ; attempt++) {
+      const r = await fetch(this.base + path, {
+        method,
+        headers: { authorization: `Bearer ${this.apiKey}`, "user-agent": this.ua, ...body ? { "content-type": "application/json" } : {}, ...this.app ? { "plures-app": this.app } : {}, ...headers },
+        body: body ? JSON.stringify(body) : void 0
+      });
+      if (r.status >= 500 && attempt < 2) {
+        await sleep(500 * 2 ** attempt);
+        continue;
+      }
+      const data = await r.json().catch(() => ({}));
+      if (!r.ok) throw new PluresError(data?.error?.message ?? `HTTP ${r.status}`, r.status, data?.error?.type ?? "api_error");
+      return data;
+    }
+  }
+  tasks = {
+    /** Sends a question to verified people. Pass an idempotency key to make retries safe. */
+    create: (params, opts = {}) => this.req("POST", "/api/v1/tasks", params, opts.idempotencyKey ? { "idempotency-key": opts.idempotencyKey } : {}),
+    retrieve: (id) => this.req("GET", `/api/v1/tasks/${encodeURIComponent(id)}`),
+    list: (params = {}) => {
+      const q = new URLSearchParams(Object.entries(params).filter(([, v]) => v != null).map(([k, v]) => [k, String(v)]));
+      return this.req("GET", `/api/v1/tasks${q.size ? `?${q}` : ""}`);
+    },
+    cancel: (id) => this.req("POST", `/api/v1/tasks/${encodeURIComponent(id)}/cancel`),
+    /** Polls until the task is settled. Prefer webhooks in production. */
+    waitFor: async (id, opts = {}) => {
+      const end = Date.now() + (opts.timeoutMs ?? 10 * 6e4);
+      for (; ; ) {
+        const t = await this.tasks.retrieve(id);
+        if (t.status !== "pending") return t;
+        if (Date.now() > end) return t;
+        await sleep(opts.intervalMs ?? 3e3);
+      }
+    }
+  };
+  /**
+   * Test keys only. How test tasks behave when they don't set metadata.test_outcome,
+   * so an agent running unchanged sends a share of decisions to your team.
+   * A single task can override it with metadata.test_mix.
+   */
+  testMix = {
+    get: () => this.req("GET", "/api/v1/test_mix"),
+    /** For example { unanimous: 70, split: 20, tie: 5, expired: 5 }. Pass null to turn it off. */
+    set: (mix) => this.req("PUT", "/api/v1/test_mix", { mix }),
+    clear: () => this.req("DELETE", "/api/v1/test_mix")
+  };
+  /**
+   * Where tasks go. set() replaces what you send (team, groups or rules) and keeps the rest.
+   * For example { groups: [{ name: "Finance", emails: ["ap@acme.com"] }], rules: [{ category: "refunds", route: "team", group: "Finance" }] }.
+   */
+  routing = {
+    get: () => this.req("GET", "/api/v1/routing"),
+    set: (update) => this.req("PUT", "/api/v1/routing", update)
+  };
+  /** Your apps. Each agent you run can be its own app, with its own tasks, ledger view and map. */
+  apps = {
+    list: () => this.req("GET", "/api/v1/apps"),
+    /** { name: "Support agent" }, with an optional id like "support-agent". */
+    create: (params) => this.req("POST", "/api/v1/apps", params),
+    retrieve: (id) => this.req("GET", `/api/v1/apps/${encodeURIComponent(id)}`),
+    /** Rename it, change its id (its tasks move with it), or make it the default. */
+    update: (id, params) => this.req("PATCH", `/api/v1/apps/${encodeURIComponent(id)}`, params),
+    /** Only an app with no tasks can be deleted. */
+    del: (id) => this.req("DELETE", `/api/v1/apps/${encodeURIComponent(id)}`)
+  };
+  /**
+   * Agent maps: where each app's agent needs a person. Your coding agent reads your code and
+   * writes the map; Plures gets only the map. guide() returns the steps it follows.
+   */
+  maps = {
+    guide: async () => {
+      const r = await fetch(`${this.base}/api/v1/map_guide`);
+      return r.text();
+    },
+    retrieve: (app2) => this.req("GET", `/api/v1/apps/${encodeURIComponent(app2)}/map`),
+    /** Uploads a new version. Checks you already added or dismissed keep that. */
+    upload: (app2, map2) => this.req("PUT", `/api/v1/apps/${encodeURIComponent(app2)}/map`, map2),
+    setCheckpoint: (app2, id, status) => this.req("PATCH", `/api/v1/apps/${encodeURIComponent(app2)}/map/checkpoints/${encodeURIComponent(id)}`, { status })
+  };
+  /**
+   * 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.
+   */
+  quality = {
+    /** Send every output; the rubric's sample rate decides which ones people grade. */
+    sample: (p) => this.req("POST", "/api/v1/samples", p),
+    /** A blind release check: a is the current version's output, b the new one's, for the same input. */
+    compare: (p) => this.req("POST", "/api/v1/comparisons", p),
+    /** How often people preferred the new version, with a 95% range and a verdict. */
+    release: (name, opts = {}) => this.req("GET", `/api/v1/releases/${encodeURIComponent(name)}${opts.app ? `?app=${encodeURIComponent(opts.app)}` : ""}`),
+    rubrics: {
+      list: (opts = {}) => this.req("GET", `/api/v1/rubrics${opts.app ? `?app=${encodeURIComponent(opts.app)}` : ""}`),
+      /** { name: "reply_quality", question: "Is this reply correct and kind?", options: ["Good", "Okay", "Bad"], sample_rate: 0.05 } */
+      create: (p) => this.req("POST", "/api/v1/rubrics", p),
+      retrieve: (name, opts = {}) => this.req("GET", `/api/v1/rubrics/${encodeURIComponent(name)}${opts.app ? `?app=${encodeURIComponent(opts.app)}` : ""}`),
+      update: (name, p) => this.req("PATCH", `/api/v1/rubrics/${encodeURIComponent(name)}${p.app ? `?app=${encodeURIComponent(p.app)}` : ""}`, p),
+      del: (name, opts = {}) => this.req("DELETE", `/api/v1/rubrics/${encodeURIComponent(name)}${opts.app ? `?app=${encodeURIComponent(opts.app)}` : ""}`)
+    },
+    /** Graded samples as JSON lines (input, output, grade, score, agreement), for fine tuning or an eval set. */
+    export: async (rubric, opts = {}) => {
+      const q = new URLSearchParams(Object.entries({ app: opts.app ?? this.app ?? void 0, since: opts.since }).filter(([, v]) => v));
+      const r = await fetch(`${this.base}/api/v1/rubrics/${encodeURIComponent(rubric)}/export${q.size ? `?${q}` : ""}`, { headers: { authorization: `Bearer ${this.apiKey}`, "user-agent": this.ua } });
+      if (!r.ok) {
+        const d = await r.json().catch(() => ({}));
+        throw new PluresError(d?.error?.message ?? `HTTP ${r.status}`, r.status, d?.error?.type ?? "api_error");
+      }
+      return (await r.text()).split("\n").filter(Boolean).map((l) => JSON.parse(l));
+    }
+  };
+  /** Your prepaid credit. A live task that could cost more than available_cents is refused with a 402 insufficient_credits error. */
+  balance = () => this.req("GET", "/api/v1/balance");
+  /** Creates a task and waits for people to answer it. */
+  async verify(params, opts = {}) {
+    const t = await this.tasks.create(params, { idempotencyKey: opts.idempotencyKey });
+    return t.status === "pending" ? this.tasks.waitFor(t.id, { timeoutMs: opts.timeoutMs }) : t;
+  }
+  /**
+   * Checks the Plures-Signature header on a webhook and returns the parsed event.
+   * Pass the raw request body exactly as received. Throws if the signature is wrong
+   * or older than toleranceSec.
+   */
+  static async verifyWebhook(rawBody, signatureHeader, secret, toleranceSec = 300) {
+    const parts = Object.fromEntries((signatureHeader ?? "").split(",").map((p) => p.split("=", 2)));
+    const t = Number(parts.t);
+    if (!t || !parts.v1) throw new Error("Missing Plures-Signature header");
+    if (Math.abs(Date.now() / 1e3 - t) > toleranceSec) throw new Error("Webhook timestamp is too old");
+    const key2 = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    const mac = new Uint8Array(await crypto.subtle.sign("HMAC", key2, new TextEncoder().encode(`${t}.${rawBody}`)));
+    const expected = Array.from(mac, (b) => b.toString(16).padStart(2, "0")).join("");
+    if (!timingSafeEqual(expected, parts.v1)) throw new Error("Webhook signature does not match");
+    return JSON.parse(rawBody);
+  }
+};
+function timingSafeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// src/cli.ts
+var argv = process.argv.slice(2);
+var flag = (name) => {
+  const i = argv.indexOf(`--${name}`);
+  if (i < 0) return void 0;
+  const v = argv[i + 1];
+  argv.splice(i, 2);
+  return v;
+};
+var app = flag("app") ?? process.env.PLURES_APP ?? "default";
+var key = flag("key") ?? process.env.PLURES_API_KEY;
+var base = flag("base-url") ?? process.env.PLURES_BASE_URL ?? "https://plures.si";
+var tty = process.stdout.isTTY && !process.env.NO_COLOR;
+var c = (code) => (s) => tty ? `\x1B[${code}m${s}\x1B[0m` : s;
+var dim = c("2");
+var bold = c("1");
+var cyan = c("36");
+var coral = c("38;5;209");
+var violet = c("38;5;147");
+var FILE = "plures.map.json";
+function die(msg) {
+  console.error(coral(msg));
+  process.exit(1);
+}
+function client() {
+  if (!key) die("Set PLURES_API_KEY (a free pk_test_ key works), or pass --key. Get one at https://plures.si/?for=developers#join");
+  return new Plures(key, { baseUrl: base, app, userAgent: `plures-cli/${VERSION}` });
+}
+async function upload(file) {
+  if (!(0, import_node_fs.existsSync)(file)) die(`No ${file} here. Run npx plures map to make one, or pass the file's path.`);
+  let map2;
+  try {
+    map2 = JSON.parse((0, import_node_fs.readFileSync)(file, "utf8"));
+  } catch {
+    die(`${file} isn't valid JSON.`);
+  }
+  console.log(dim(`Sending the map to Plures. No source code is sent.`));
+  let m;
+  try {
+    m = await client().maps.upload(app, map2);
+  } catch (e) {
+    die(e instanceof PluresError ? `Plures said: ${e.message}` : String(e));
+  }
+  report(m);
+}
+function report(m) {
+  const nodes = new Map(m.nodes.map((n) => [n.id, n]));
+  const actions = m.nodes.filter((n) => n.kind === "action");
+  console.log(`
+${bold(m.name ?? m.app)}: ${m.nodes.length} steps, ${actions.length} ${actions.length === 1 ? "action" : "actions"} with consequences
+`);
+  const at = new Map(m.checkpoints.map((cp) => [cp.at, cp]));
+  for (const a of actions) {
+    const cp = at.get(a.id);
+    const loc = a.file ? dim(`${a.file}${a.line ? `:${a.line}` : ""}`) : "";
+    if (cp?.status === "added") console.log(`  ${cyan("checked ")}   ${a.label.padEnd(26)} ${loc}`);
+    else if (cp?.status === "suggested") console.log(`  ${violet("suggested")}  ${a.label.padEnd(26)} ${dim(cp.why)}`);
+    else console.log(`  ${a.risk === "high" ? coral("no check ") : dim("no check ")}  ${a.label.padEnd(26)} ${loc}`);
+  }
+  for (const cp of m.checkpoints.filter((x) => nodes.get(x.at)?.kind !== "action" && x.status !== "dismissed"))
+    console.log(`  ${violet("suggested")}  ${(nodes.get(cp.at)?.label ?? cp.at).padEnd(26)} ${dim(cp.why)}`);
+  console.log(`
+Version ${m.version}. Open ${bold(m.url ?? `${base}/dashboard/apps/${m.app}/map`)}`);
+}
+function hasClaude() {
+  return (0, import_node_child_process.spawnSync)(process.platform === "win32" ? "where" : "which", ["claude"], { stdio: "ignore" }).status === 0;
+}
+async function map() {
+  const guide = await (await fetch(`${base}/api/v1/map_guide`)).text().catch(() => "");
+  if (!guide) die("Couldn't reach Plures for the mapping guide. Check your connection.");
+  if (!hasClaude()) {
+    console.log(`${bold("Map this app with your coding agent")}
+
+Ask it: ${cyan(`Read ${base}/api/v1/map_guide and follow it to write ${FILE} for this repo.`)}
+Then run: ${cyan(`npx plures map upload${app !== "default" ? ` --app ${app}` : ""}`)}
+
+With plures-mcp connected, just ask: ${cyan("Map this app for Plures")}`);
+    return;
+  }
+  const before = (0, import_node_fs.existsSync)(FILE) ? (0, import_node_fs.statSync)(FILE).mtimeMs : 0;
+  console.log(`Reading this repo on your machine with Claude Code. ${dim("Only the map leaves it.")}
+`);
+  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 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"] });
+    p.on("close", (n) => resolve(n ?? 1));
+    p.on("error", () => resolve(1));
+  });
+  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);
+}
+async function main() {
+  const [cmd, sub, arg] = argv;
+  if (cmd !== "map") {
+    console.log(`Plures
+
+  npx plures map [--app <id>]          map this repo's agent and upload it
+  npx plures map upload [file]         upload ${FILE}
+  npx plures map guide                 print the steps for any coding agent
+
+Docs: https://plures.si/docs`);
+    return;
+  }
+  if (sub === "upload") return upload(arg ?? FILE);
+  if (sub === "guide") return void console.log(await (await fetch(`${base}/api/v1/map_guide`)).text());
+  return map();
+}
+main().catch((e) => die(String(e?.message ?? e)));

package/dist/cli.d.cts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+import {
+  Plures,
+  PluresError,
+  VERSION
+} from "./chunk-XOB4CPDP.js";
+
+// src/cli.ts
+import { spawnSync, spawn } from "child_process";
+import { existsSync, readFileSync, statSync } from "fs";
+var argv = process.argv.slice(2);
+var flag = (name) => {
+  const i = argv.indexOf(`--${name}`);
+  if (i < 0) return void 0;
+  const v = argv[i + 1];
+  argv.splice(i, 2);
+  return v;
+};
+var app = flag("app") ?? process.env.PLURES_APP ?? "default";
+var key = flag("key") ?? process.env.PLURES_API_KEY;
+var base = flag("base-url") ?? process.env.PLURES_BASE_URL ?? "https://plures.si";
+var tty = process.stdout.isTTY && !process.env.NO_COLOR;
+var c = (code) => (s) => tty ? `\x1B[${code}m${s}\x1B[0m` : s;
+var dim = c("2");
+var bold = c("1");
+var cyan = c("36");
+var coral = c("38;5;209");
+var violet = c("38;5;147");
+var FILE = "plures.map.json";
+function die(msg) {
+  console.error(coral(msg));
+  process.exit(1);
+}
+function client() {
+  if (!key) die("Set PLURES_API_KEY (a free pk_test_ key works), or pass --key. Get one at https://plures.si/?for=developers#join");
+  return new Plures(key, { baseUrl: base, app, userAgent: `plures-cli/${VERSION}` });
+}
+async function upload(file) {
+  if (!existsSync(file)) die(`No ${file} here. Run npx plures map to make one, or pass the file's path.`);
+  let map2;
+  try {
+    map2 = JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    die(`${file} isn't valid JSON.`);
+  }
+  console.log(dim(`Sending the map to Plures. No source code is sent.`));
+  let m;
+  try {
+    m = await client().maps.upload(app, map2);
+  } catch (e) {
+    die(e instanceof PluresError ? `Plures said: ${e.message}` : String(e));
+  }
+  report(m);
+}
+function report(m) {
+  const nodes = new Map(m.nodes.map((n) => [n.id, n]));
+  const actions = m.nodes.filter((n) => n.kind === "action");
+  console.log(`
+${bold(m.name ?? m.app)}: ${m.nodes.length} steps, ${actions.length} ${actions.length === 1 ? "action" : "actions"} with consequences
+`);
+  const at = new Map(m.checkpoints.map((cp) => [cp.at, cp]));
+  for (const a of actions) {
+    const cp = at.get(a.id);
+    const loc = a.file ? dim(`${a.file}${a.line ? `:${a.line}` : ""}`) : "";
+    if (cp?.status === "added") console.log(`  ${cyan("checked ")}   ${a.label.padEnd(26)} ${loc}`);
+    else if (cp?.status === "suggested") console.log(`  ${violet("suggested")}  ${a.label.padEnd(26)} ${dim(cp.why)}`);
+    else console.log(`  ${a.risk === "high" ? coral("no check ") : dim("no check ")}  ${a.label.padEnd(26)} ${loc}`);
+  }
+  for (const cp of m.checkpoints.filter((x) => nodes.get(x.at)?.kind !== "action" && x.status !== "dismissed"))
+    console.log(`  ${violet("suggested")}  ${(nodes.get(cp.at)?.label ?? cp.at).padEnd(26)} ${dim(cp.why)}`);
+  console.log(`
+Version ${m.version}. Open ${bold(m.url ?? `${base}/dashboard/apps/${m.app}/map`)}`);
+}
+function hasClaude() {
+  return spawnSync(process.platform === "win32" ? "where" : "which", ["claude"], { stdio: "ignore" }).status === 0;
+}
+async function map() {
+  const guide = await (await fetch(`${base}/api/v1/map_guide`)).text().catch(() => "");
+  if (!guide) die("Couldn't reach Plures for the mapping guide. Check your connection.");
+  if (!hasClaude()) {
+    console.log(`${bold("Map this app with your coding agent")}
+
+Ask it: ${cyan(`Read ${base}/api/v1/map_guide and follow it to write ${FILE} for this repo.`)}
+Then run: ${cyan(`npx plures map upload${app !== "default" ? ` --app ${app}` : ""}`)}
+
+With plures-mcp connected, just ask: ${cyan("Map this app for Plures")}`);
+    return;
+  }
+  const before = existsSync(FILE) ? statSync(FILE).mtimeMs : 0;
+  console.log(`Reading this repo on your machine with Claude Code. ${dim("Only the map leaves it.")}
+`);
+  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 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"] });
+    p.on("close", (n) => resolve(n ?? 1));
+    p.on("error", () => resolve(1));
+  });
+  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);
+}
+async function main() {
+  const [cmd, sub, arg] = argv;
+  if (cmd !== "map") {
+    console.log(`Plures
+
+  npx plures map [--app <id>]          map this repo's agent and upload it
+  npx plures map upload [file]         upload ${FILE}
+  npx plures map guide                 print the steps for any coding agent
+
+Docs: https://plures.si/docs`);
+    return;
+  }
+  if (sub === "upload") return upload(arg ?? FILE);
+  if (sub === "guide") return void console.log(await (await fetch(`${base}/api/v1/map_guide`)).text());
+  return map();
+}
+main().catch((e) => die(String(e?.message ?? e)));