pipeup 0.5.4 → 0.7.0-beta.1

package/README.md

@@ -2,7 +2,7 @@
 
 Comments and feedback right on any HTML page: documents, slide decks and whole sites.
 
-> **Alpha (0.5.4).** The API and the stored comment format may change before 1.0; pin an exact version.
+> **Alpha (0.7.0-beta.1).** The API and the stored comment format may change before 1.0; pin an exact version.
 > Website and Try pages: https://pipeup-ai.github.io/pipeup/ · Source: https://github.com/pipeup-ai/pipeup
 
 Pipeup: signed comment operations, threads with one-level replies, anchors that survive page changes,
@@ -21,14 +21,14 @@ As a classic script (also works from `file://`), it mounts itself on pages that
 ```html
 <html data-pipeup-doc="<id>:<key>">
   ...
-  <script src="https://cdn.jsdelivr.net/npm/pipeup@0.5.4/dist/pipeup.min.js" integrity="sha384-…" crossorigin="anonymous" defer></script>
+  <script src="https://cdn.jsdelivr.net/npm/pipeup@0.7.0-beta.1/dist/pipeup.min.js" integrity="sha384-…" crossorigin="anonymous" defer></script>
 ```
 
 Each release's notes on GitHub give the `integrity` value
 (`node scripts/sri.mjs` prints it for a local build). Make a document key with
 `await Pipeup.newDocumentAttribute()` and keep it once people have commented.
 
-**Add-ons.** Optional extra scripts add features (`@pipeup/share`, `voice`, `live`, `assist`), and anyone can write their own
+**Add-ons.** Optional extra scripts add features (`@pipeup/share`, `voice`, `live`, `assist`, `agents`, `emoji`, `github`, `updates`, `inbox`), and anyone can write their own
 (a company's, for example) without the Pipeup project's permission: see the
 [guide](https://pipeup-ai.github.io/pipeup/addons-guide.html). Add-ons run with the page's full power, so keep them
 intentional (best effort): pin each script with its `integrity` hash, name the add-ons that may run with

package/cli/link.d.mts

@@ -0,0 +1,17 @@
+export type Support = "old" | "builtin" | "addon" | "unknown";
+export function served(
+  html: string,
+  o: { base: string; agent: string; key: string; file: string; addon?: boolean },
+): string;
+export function pageSupport(
+  html: string,
+  dir: string,
+): Promise<{ support: Support; version: string; loaded: boolean }>;
+export function watch(o: {
+  page: string;
+  agent: string;
+  key: string;
+  port?: number;
+  log?: (line: string) => void;
+}): Promise<{ url: string; sidecar: string; support: Support; addon: boolean; close(): Promise<void> }>;
+export function comments(o: { page: string; all?: boolean; json?: boolean }): Promise<string>;

package/cli/link.mjs

@@ -0,0 +1,207 @@
+// pipeup watch / pipeup comments: the live link between a page shown from this computer and an agent on it.
+// Everything stays on this computer: the server listens on 127.0.0.1 only, and answers only the page it serves.
+import { randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+import { readFile, rename, writeFile } from "node:fs/promises";
+import { basename, dirname, extname, join, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** The agents add-on that ships with this install; `watch` serves it to the pages that need it. */
+const ADDON_FILE = fileURLToPath(new URL("../dist/pipeup.agents.js", import.meta.url));
+
+const TYPES = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".ico": "image/x-icon",
+  ".woff2": "font/woff2",
+  ".txt": "text/plain; charset=utf-8",
+  ".md": "text/markdown; charset=utf-8",
+};
+const MAX_BODY = 8 * 1024 * 1024;
+const attr = (v) => v.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
+
+/** The page for the browser: its own html tag, plus the link's address and the agent it lists, and the agents add-on when it needs one. */
+export function served(html, { base, agent, key, file, addon = false }) {
+  const out = html.replace(/<html\b([^>]*)>/i, (_, rest) => {
+    let tag = rest;
+    const listed = /\sdata-pipeup-agents\s*=\s*"([^"]*)"/i.exec(tag);
+    if (listed) tag = tag.replace(listed[0], ` data-pipeup-agents="${attr(`${listed[1]} ${key}`.trim())}"`);
+    else tag += ` data-pipeup-agents="${key}"`;
+    tag += ` data-pipeup-link="${base}" data-pipeup-link-agent="${attr(agent)}" data-pipeup-link-file="${attr(file)}"`;
+    return `<html${tag}>`;
+  });
+  if (!addon) return out;
+  // After the page's own scripts: an add-on registers in any order. The page's file on disk is not touched.
+  const tag = `<script src="${base}/agents.js"></script>`;
+  return /<\/body>/i.test(out) ? out.replace(/<\/body>/i, () => `${tag}</body>`) : out + tag;
+}
+
+/** Which of Pipeup's agent support a version has: before 0.6 none, 0.6.x built in, 0.7 and later in the agents add-on. */
+function byVersion(v) {
+  const m = /^(\d+)\.(\d+)\.\d+/.exec(v);
+  if (!m) return null;
+  const [major, minor] = [Number(m[1]), Number(m[2])];
+  return major > 0 || minor >= 7 ? "addon" : minor === 6 ? "builtin" : "old";
+}
+
+/** The same, read from a Pipeup script's own text: it carries the names of what it supports. */
+function bySignature(text) {
+  if (!text.includes("pipeup-root")) return null;
+  if (text.includes("pipeupReplies")) return "builtin";
+  return text.includes("listnote") ? "addon" : "old";
+}
+
+/**
+ * What the page's Pipeup can do for an agent, found without running the page: "old" (before 0.6, can't take an
+ * agent), "builtin" (0.6.x, agent support is part of it), "addon" (0.7 or later: the agents add-on serves an agent),
+ * or "unknown" (a floating address, or no Pipeup script to read). `loaded` says the page already includes the add-on.
+ */
+export async function pageSupport(html, dir) {
+  const result = { support: "unknown", version: "", loaded: false };
+  for (const [, src] of html.matchAll(/<script\b[^>]*\bsrc\s*=\s*["']([^"']+)["']/gi)) {
+    if (/agents(\.min)?\.js|@pipeup\/agents/i.test(src)) result.loaded = true;
+    const named = /pipeup(?:@|-)(\d+\.\d+\.\d+(?:-[\w.]+)?)\b/.exec(src);
+    if (named && result.support === "unknown") {
+      result.support = byVersion(named[1]) ?? "unknown";
+      result.version = named[1];
+      continue;
+    }
+    if (result.support !== "unknown" || /^(https?:)?\/\//i.test(src)) continue;
+    try {
+      const path = /^file:/i.test(src)
+        ? fileURLToPath(src.split(/[?#]/)[0])
+        : resolve(dir, decodeURIComponent(src.split(/[?#]/)[0]));
+      result.support = bySignature(await readFile(path, "utf8")) ?? "unknown";
+    } catch {
+      // a script that can't be read says nothing about Pipeup
+    }
+  }
+  // A Pipeup carried inside the page itself.
+  if (result.support === "unknown") result.support = bySignature(html) ?? "unknown";
+  return result;
+}
+
+/** Starts the link for a page file. Resolves to { url, close }. */
+export async function watch({ page, agent, key, port = 0, log = console.log }) {
+  const file = resolve(page);
+  const dir = dirname(file);
+  const name = basename(file);
+  const base = `/__pipeup/${randomBytes(18).toString("base64url")}`;
+  const sidecar = file.replace(/\.[^./\\]*$/, "") + ".comments.json";
+  let origin = "";
+  let host = "";
+
+  // Which Pipeup the page uses decides whether the agents add-on is added to what it shows.
+  const found = await pageSupport(await readFile(file, "utf8"), dir);
+  if (found.support === "old")
+    throw new Error(
+      `this page uses ${found.version ? `Pipeup ${found.version}` : "a Pipeup older than 0.6"}, which can't take an agent. Use Pipeup 0.6 or later (pin an exact version) and run this again`,
+    );
+  const addon = found.support !== "builtin" && !found.loaded;
+  let addonCode = "";
+  if (addon) {
+    try {
+      addonCode = await readFile(ADDON_FILE, "utf8");
+    } catch {
+      throw new Error("the agents add-on isn't in this install of pipeup (dist/pipeup.agents.js is missing)");
+    }
+  }
+
+  const send = (res, status, body = "", type = "text/plain; charset=utf-8") => {
+    res.writeHead(status, {
+      "content-type": type,
+      "cache-control": "no-store",
+      "x-content-type-options": "nosniff",
+    });
+    res.end(body);
+  };
+
+  const server = createServer(async (req, res) => {
+    try {
+      // Only this computer's own address: a name that points here from another site is refused.
+      if (req.headers.host !== host) return send(res, 403, "wrong host");
+      const url = new URL(req.url, origin);
+      if (url.pathname.startsWith("/__pipeup/")) {
+        if (addon && url.pathname === `${base}/agents.js` && req.method === "GET")
+          return send(res, 200, addonCode, TYPES[".js"]);
+        if (url.pathname !== `${base}/comments` || req.method !== "POST") return send(res, 404, "not found");
+        if (req.headers.origin !== origin) return send(res, 403, "wrong origin");
+        const chunks = [];
+        let size = 0;
+        for await (const c of req) {
+          size += c.length;
+          if (size > MAX_BODY) return send(res, 413, "too big");
+          chunks.push(c);
+        }
+        let body;
+        try {
+          body = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+        } catch {
+          return send(res, 400, "not json");
+        }
+        if (body?.v !== 1 || !body.open || !body.all) return send(res, 400, "not a comments snapshot");
+        const tmp = `${sidecar}.${process.pid}.tmp`;
+        await writeFile(tmp, JSON.stringify(body));
+        await rename(tmp, sidecar);
+        log(`Shared ${body.open.threads.length} open comment${body.open.threads.length === 1 ? "" : "s"}.`);
+        return send(res, 204);
+      }
+      if (req.method !== "GET" && req.method !== "HEAD") return send(res, 405, "method not allowed");
+      let path = decodeURIComponent(url.pathname);
+      if (path === "/") path = `/${name}`;
+      const target = resolve(join(dir, path));
+      if (target !== dir && !target.startsWith(dir + sep)) return send(res, 404, "not found");
+      let bytes;
+      try {
+        bytes = await readFile(target);
+      } catch {
+        return send(res, 404, "not found");
+      }
+      if (target === file)
+        bytes = Buffer.from(served(bytes.toString("utf8"), { base, agent, key, file, addon }));
+      send(
+        res,
+        200,
+        req.method === "HEAD" ? "" : bytes,
+        TYPES[extname(target).toLowerCase()] ?? "application/octet-stream",
+      );
+    } catch {
+      send(res, 500, "error");
+    }
+  });
+  await new Promise((ok) => server.listen(port, "127.0.0.1", ok));
+  const { port: bound } = server.address();
+  origin = `http://127.0.0.1:${bound}`;
+  host = `127.0.0.1:${bound}`;
+  return {
+    url: `${origin}/${encodeURIComponent(name)}`,
+    sidecar,
+    support: found.support,
+    addon,
+    close: () => new Promise((ok) => server.close(ok)),
+  };
+}
+
+/** What `pipeup comments` prints: the shared comments, as Markdown or as data. */
+export async function comments({ page, all = false, json = false }) {
+  const sidecar = resolve(page).replace(/\.[^./\\]*$/, "") + ".comments.json";
+  let shared;
+  try {
+    shared = JSON.parse(await readFile(sidecar, "utf8"));
+  } catch {
+    throw new Error(
+      `nothing is shared for ${page} yet. Start the link (pipeup watch ${page}), open the page it prints, and switch on Share with my agent`,
+    );
+  }
+  const view = all ? shared.all : shared.open;
+  return json ? JSON.stringify({ at: shared.at, ...view }, null, 2) : view.markdown;
+}

package/cli/pipeup.mjs

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+// pipeup agent / pipeup reply: how an AI agent answers comments on a Pipeup page.
+// The agent's key stays in ~/.pipeup/agent.json (owner-only) and never goes in the page or its folder.
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+import { comments, watch } from "./link.mjs";
+import * as skills from "./skills.mjs";
+
+// The page library, loaded only by the commands that sign or read a page: `skills` and `comments` need nothing built.
+const core = () => import("../dist/pipeup.core.js");
+
+const KEYFILE = process.env.PIPEUP_AGENT_FILE || join(homedir(), ".pipeup", "agent.json");
+const AI = "AI assistant";
+
+const USAGE = `pipeup skills install|remove|list [--project] [--agent claude|codex|all] [--yes] [--replace] [--dry-run]
+  Puts Pipeup's agent skills where Claude Code (.claude/skills) and Codex (.agents/skills) look: for you, in every
+  project, or with --project for this folder only. It says what it will write, asks first (--yes to go ahead without
+  asking), and never replaces a skill you changed unless you say --replace.
+
+pipeup agent [--name <name>]
+  Makes this computer's agent key (once) and prints the public key to list on the page:
+  <html data-pipeup-agents="<key>">
+
+pipeup watch <page.html> [--agent <name>] [--port <number>]
+  Shows the page from this computer, with a live link to the agent: the page offers "Share with my agent"
+  (off until the person switches it on), and the agent is listed for this page while the link runs. It adds the
+  agents add-on to the page it shows (the file is not changed), unless the page's Pipeup already has agent support
+  (0.6.x), and refuses a page whose Pipeup is older than 0.6.
+
+pipeup comments <page.html> [--all] [--json]
+  Prints the comments the page has shared (open threads, or all with --all), as Markdown or, with --json, as data.
+
+pipeup reply --page <file.html> --thread <id> "<words>" [--addressed "<short note>"]
+  Writes a signed reply (and, with --addressed, an addressed note) to <file>.replies.js next to the page.
+  It never resolves, reopens, edits or deletes anything: the author closes threads.`;
+
+function fail(message) {
+  console.error(`pipeup: ${message}`);
+  process.exit(1);
+}
+
+function flags(argv) {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith("--")) out[a.slice(2)] = true;
+      else ((out[a.slice(2)] = next), i++);
+    } else out._.push(a);
+  }
+  return out;
+}
+
+const b64u = (bytes) => Buffer.from(bytes).toString("base64url");
+
+async function loadAgent(name) {
+  let saved = null;
+  try {
+    saved = JSON.parse(await readFile(KEYFILE, "utf8"));
+  } catch {
+    // none yet
+  }
+  if (!saved) {
+    const pair = await crypto.subtle.generateKey({ name: "Ed25519" }, true, ["sign", "verify"]);
+    const raw = new Uint8Array(await crypto.subtle.exportKey("raw", pair.publicKey));
+    saved = {
+      name: typeof name === "string" ? name : "Agent",
+      publicKey: b64u(raw),
+      privateKey: await crypto.subtle.exportKey("jwk", pair.privateKey),
+    };
+    await mkdir(dirname(KEYFILE), { recursive: true, mode: 0o700 });
+    await writeFile(KEYFILE, JSON.stringify(saved), { mode: 0o600 });
+    await chmod(KEYFILE, 0o600);
+  } else if (typeof name === "string" && name !== saved.name) {
+    saved.name = name;
+    await writeFile(KEYFILE, JSON.stringify(saved), { mode: 0o600 });
+  }
+  const privateKey = await crypto.subtle.importKey("jwk", saved.privateKey, { name: "Ed25519" }, false, [
+    "sign",
+  ]);
+  return { identity: { publicKey: saved.publicKey, privateKey }, name: saved.name };
+}
+
+/** A name that shows it is an agent: "AI assistant · Claude". */
+const signedName = (name) => (name && name !== AI ? `${AI} · ${name}`.slice(0, 80) : AI);
+
+async function pageDoc(file) {
+  const html = await readFile(file, "utf8");
+  const m = /<html\b[^>]*\sdata-pipeup-doc\s*=\s*["']([^"']+)["']/i.exec(html);
+  if (!m) fail(`${file} has no data-pipeup-doc attribute; add Pipeup to the page first`);
+  const { id } = await (await core()).parseDocumentAttribute(m[1]);
+  const listed = /<html\b[^>]*\sdata-pipeup-agents\s*=\s*["']([^"']*)["']/i.exec(html)?.[1] ?? "";
+  return { id, listed: listed.split(/[\s,]+/).filter(Boolean) };
+}
+
+const headerOf = (file) =>
+  `// Replies to the comments on ${basename(file)}. Written by \`pipeup reply\`; safe to keep with the page.\n`;
+
+async function readReplies(path, doc) {
+  try {
+    const text = await readFile(path, "utf8");
+    const m = /push\((\{.*\})\);\s*$/m.exec(text);
+    const file = m && JSON.parse(m[1]);
+    return file && file.doc === doc && Array.isArray(file.ops) ? file.ops : [];
+  } catch {
+    return [];
+  }
+}
+
+async function reply(args) {
+  const page = args.page;
+  const thread = args.thread;
+  const words = args._[0]?.trim();
+  if (typeof page !== "string" || typeof thread !== "string" || !words)
+    fail(`missing words, --page or --thread\n\n${USAGE}`);
+  const note = typeof args.addressed === "string" ? args.addressed.trim() : "";
+  const { id: doc, listed } = await pageDoc(page);
+  const { identity, name } = await loadAgent();
+  const linked = await readFile(page.replace(/\.[^./\\]*$/, "") + ".comments.json", "utf8").then(
+    () => true,
+    () => false,
+  );
+  if (!listed.includes(identity.publicKey) && !linked)
+    console.warn(
+      `pipeup: this page doesn't list your key yet, so it will ignore these replies.\n  Add: <html data-pipeup-agents="${identity.publicKey}">`,
+    );
+  const out = resolve(page.replace(/\.[^./\\]*$/, "") + ".replies.js");
+  const ops = await readReplies(out, doc);
+  // Seconds since 1970: later than any counter a browser has kept, so these follow the thread they answer.
+  let clock = Math.max(Math.floor(Date.now() / 1000), ...ops.map((o) => o.body.clock + 1));
+  let at = Date.now();
+  const make = async (fields) => {
+    const body = {
+      v: 1,
+      ...fields,
+      id: "",
+      doc,
+      author: identity.publicKey,
+      name: signedName(name),
+      clock: clock++,
+      at: at++,
+    };
+    const { computeOpId, signOp } = await core();
+    body.id = await computeOpId(body);
+    return signOp(body, identity);
+  };
+  const added = [await make({ kind: "reply", thread, target: thread, text: words })];
+  if (note) added.push(await make({ kind: "addressed", thread, text: note }));
+  const file = { format: "pipeup-replies", v: 1, doc, ops: [...ops, ...added] };
+  await writeFile(out, `${headerOf(page)}(globalThis.pipeupReplies ||= []).push(${JSON.stringify(file)});\n`);
+  console.log(`Wrote ${added.length} ${added.length === 1 ? "entry" : "entries"} to ${out}`);
+}
+
+const [command, ...rest] = process.argv.slice(2);
+const args = flags(rest);
+if (command === "agent") {
+  const { identity, name } = await loadAgent(args.name);
+  console.log(
+    `${name} (${KEYFILE})\n\nList this key on the page:\n  <html data-pipeup-agents="${identity.publicKey}">`,
+  );
+} else if (command === "reply") await reply(args);
+else if (command === "skills") {
+  const sub = args._[0];
+  const opts = {
+    agent: typeof args.agent === "string" ? args.agent : "all",
+    project: args.project === true,
+    yes: args.yes === true,
+    replace: args.replace === true,
+    dryRun: args["dry-run"] === true,
+  };
+  try {
+    if (sub === "install" || sub === "update") await skills.install(opts);
+    else if (sub === "remove") await skills.remove(opts);
+    else if (sub === "list") await skills.list(opts);
+    else fail(`skills: say install, remove or list\n\n${USAGE}`);
+  } catch (e) {
+    fail(e.message);
+  }
+} else if (command === "comments") {
+  const page = args._[0];
+  if (!page) fail(`missing the page\n\n${USAGE}`);
+  try {
+    console.log(await comments({ page, all: args.all === true, json: args.json === true }));
+  } catch (e) {
+    fail(e.message);
+  }
+} else if (command === "watch") {
+  const page = args._[0];
+  if (!page) fail(`missing the page\n\n${USAGE}`);
+  await pageDoc(page);
+  const { identity, name } = await loadAgent(typeof args.agent === "string" ? args.agent : undefined);
+  let link;
+  try {
+    link = await watch({
+      page,
+      agent: name,
+      key: identity.publicKey,
+      port: typeof args.port === "string" ? Number(args.port) : 0,
+    });
+  } catch (e) {
+    fail(e.message);
+  }
+  console.log(`Open this page: ${link.url}\n`);
+  console.log(
+    `While this runs, ${name} is listed for the page and the page offers "Share with my agent" (off until you switch it on).`,
+  );
+  if (link.addon)
+    console.log(
+      link.support === "unknown"
+        ? "It couldn't tell which Pipeup the page uses, so it adds the agents add-on to the page it shows (the add-on stays off on a Pipeup that already has agent support). The page's file is not changed."
+        : "It adds the agents add-on to the page it shows. The page's file is not changed.",
+    );
+  else if (link.support === "builtin")
+    console.log("This page's Pipeup (0.6) has agent support built in, so nothing is added to it.");
+  console.log(
+    `Read:  npx pipeup comments ${page}\nReply: npx pipeup reply --page ${page} --thread <id> "words" --addressed "note"\nStop:  Ctrl-C (comments stay in ${basename(link.sidecar)})`,
+  );
+  const stop = () => link.close().then(() => process.exit(0));
+  process.on("SIGINT", stop);
+  process.on("SIGTERM", stop);
+} else {
+  console.log(USAGE);
+  process.exit(command ? 1 : 0);
+}

package/cli/skills.mjs

@@ -0,0 +1,154 @@
+// pipeup skills install | remove | list: puts Pipeup's agent skills where Claude Code and Codex look for them.
+// It writes only SKILL.md files and a small marker beside each (so it can tell its own from yours), asks before
+// replacing one you changed, and makes no network request: the skills ship inside this package.
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { createInterface } from "node:readline/promises";
+
+const MARKER = ".pipeup-installed";
+const sha = (text) => createHash("sha256").update(text).digest("hex");
+
+/** Where the skills come from: inside this package, or (running from the repository) the one source. */
+function sourceDir() {
+  for (const rel of ["../skills", "../../../../apps/agent-skills"]) {
+    const dir = new URL(`${rel}/`, import.meta.url).pathname;
+    if (existsSync(dir)) return dir;
+  }
+  throw new Error("this copy of pipeup doesn't carry the skills");
+}
+
+function loadSkills() {
+  const dir = sourceDir();
+  return readdirSync(dir)
+    .filter((n) => n.startsWith("pipeup-") && existsSync(join(dir, n, "SKILL.md")))
+    .sort()
+    .map((name) => ({ name, text: readFileSync(join(dir, name, "SKILL.md"), "utf8") }));
+}
+
+const version = () => JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+
+/** The places to write: each agent's skills folder, for the person (every project) or for this project only. */
+export function targets({
+  agent = "all",
+  project = false,
+  home = process.env.PIPEUP_SKILLS_HOME || homedir(),
+  cwd = process.cwd(),
+}) {
+  const base = project ? cwd : home;
+  const out = [];
+  if (agent === "all" || agent === "claude")
+    out.push({ agent: "Claude Code", dir: join(base, ".claude", "skills") });
+  if (agent === "all" || agent === "codex")
+    out.push({ agent: "Codex", dir: join(base, ".agents", "skills") });
+  if (!out.length) throw new Error(`unknown agent "${agent}": use claude, codex or all`);
+  return out;
+}
+
+/** What is there now for one skill: nothing, ours and unchanged, or changed by you (or not ours). */
+async function stateOf(dir, name) {
+  const file = join(dir, name, "SKILL.md");
+  if (!existsSync(file)) return "new";
+  const text = await readFile(file, "utf8");
+  try {
+    const marker = JSON.parse(await readFile(join(dir, name, MARKER), "utf8"));
+    return marker.sha256 === sha(text) ? "ours" : "changed";
+  } catch {
+    return "changed";
+  }
+}
+
+async function ask(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return /^y(es)?$/i.test((await rl.question(`${question} [y/N] `)).trim());
+  } finally {
+    rl.close();
+  }
+}
+
+export async function install(o) {
+  const skills = loadSkills();
+  const where = targets(o);
+  const plan = [];
+  for (const t of where)
+    for (const s of skills)
+      plan.push({ ...t, ...s, state: await stateOf(t.dir, s.name), path: join(t.dir, s.name, "SKILL.md") });
+  const say = o.log ?? console.log;
+  say(`Pipeup skills ${version()} (${skills.length}) will be written to:`);
+  for (const t of where) say(`  ${t.agent}: ${t.dir}`);
+  const mine = (st) => plan.filter((p) => p.state === st).length;
+  say(
+    `  ${mine("new")} new, ${mine("ours")} already from Pipeup (updated if different), ${mine("changed")} you have changed or didn't come from here`,
+  );
+  if (mine("changed")) say("  Skills you have changed are left alone unless you choose to replace them.");
+  if (o.dryRun) return { written: 0, skipped: 0, dry: true };
+  if (!o.yes) {
+    if (!process.stdin.isTTY) {
+      say(
+        "Nothing written. Run it again with --yes to go ahead (--replace also replaces skills you changed).",
+      );
+      return { written: 0, skipped: plan.length };
+    }
+    if (!(await ask("Go ahead?"))) return { written: 0, skipped: plan.length };
+  }
+  let written = 0;
+  let skipped = 0;
+  for (const p of plan) {
+    if (p.state === "changed") {
+      const replace =
+        o.replace ||
+        (process.stdin.isTTY && !o.yes ? await ask(`${p.path} has been changed. Replace it?`) : false);
+      if (!replace) {
+        say(`  kept yours: ${p.path}`);
+        skipped++;
+        continue;
+      }
+    }
+    await mkdir(join(p.dir, p.name), { recursive: true });
+    await writeFile(p.path, p.text);
+    await writeFile(
+      join(p.dir, p.name, MARKER),
+      JSON.stringify({ version: version(), sha256: sha(p.text) }) + "\n",
+    );
+    written++;
+  }
+  say(
+    `Wrote ${written} skill${written === 1 ? "" : "s"}${skipped ? `, kept ${skipped} of yours` : ""}. Restart the agent if it was open.`,
+  );
+  return { written, skipped };
+}
+
+export async function remove(o) {
+  const say = o.log ?? console.log;
+  const skills = loadSkills();
+  let removed = 0;
+  for (const t of targets(o))
+    for (const s of skills) {
+      const state = await stateOf(t.dir, s.name);
+      if (state === "new") continue;
+      if (state === "changed" && !o.replace) {
+        say(`  kept (not from Pipeup, or changed by you): ${join(t.dir, s.name)}`);
+        continue;
+      }
+      if (o.dryRun) say(`  would remove ${join(t.dir, s.name)}`);
+      else await rm(join(t.dir, s.name), { recursive: true, force: true });
+      removed++;
+    }
+  say(`${o.dryRun ? "Would remove" : "Removed"} ${removed} skill${removed === 1 ? "" : "s"}.`);
+  return { removed };
+}
+
+export async function list(o) {
+  const say = o.log ?? console.log;
+  const skills = loadSkills();
+  for (const t of targets(o)) {
+    say(`${t.agent}: ${t.dir}`);
+    for (const s of skills)
+      say(
+        `  ${s.name}: ${{ new: "not installed", ours: "installed", changed: "there, but not from Pipeup or changed" }[await stateOf(t.dir, s.name)]}`,
+      );
+  }
+}

package/dist/pipeup.agents.js

@@ -0,0 +1,2 @@
+"use strict";(()=>{function b(e){let t=globalThis;(t.pipeupAddons||=[]).push(e),typeof addEventListener=="function"&&addEventListener("load",()=>{t.Pipeup||console.error(`pipeup: the "${e.id}" add-on needs Pipeup on the page too; load pipeup.min.js.`)},{once:!0})}var re=2n**256n-2n**32n-977n;var L=/^\/__pipeup\/[A-Za-z0-9_-]{16,}$/;function P(e){let t=document.documentElement,n=t.getAttribute("data-pipeup-link")??"",s=L.test(n),o=!1,c=0,y=()=>{};async function r(){let d=!1;try{d=(await fetch(`${n}/comments`,{method:"POST",headers:{"content-type":"application/json"},body:JSON.stringify(await e.snapshot())})).ok}catch{}if(!d)throw new Error("pipeup: the link to your agent isn't reachable; your comments are safe here")}let u=()=>{window.clearTimeout(c),y(),y=()=>{},o=!1};return{enabled:s,agent:t.getAttribute("data-pipeup-link-agent")??"",file:t.getAttribute("data-pipeup-link-file")??"",on:()=>o,set:async d=>{if(s){if(!d){u(),e.refresh();return}await r(),o=!0,y=e.changes(()=>{window.clearTimeout(c),c=window.setTimeout(()=>{r().catch(h=>{u(),e.refresh(),globalThis.reportError?.(h)})},300)}),e.refresh()}},destroy:u}}function T(e){let t=n=>n.replace(/\s+/g," ").trim();return[`Act on the review comments on this page, which uses Pipeup: ${t(e.title)} (${t(e.url)}).`,"",e.file?`1. Read the comments: \`npx pipeup comments ${e.file}\` (add --all for resolved ones). If it says nothing is shared, ask me to switch on Share with my agent.`:"1. Read the comments. Open the page in a browser and run `await Pipeup.comments()`, then read `.markdown`. If you can't run the page, ask me to paste its Copy as Markdown.","2. Work through the open threads in order. For each, make the change I approved, or say why you didn't. Ask me before changing anything I haven't approved, and answer a question with an answer.",e.replies?`3. Answer in each thread: \`npx pipeup reply --page ${e.file||"<the page's file>"} --thread <Thread id> "what you changed and where" --addressed "short note"\`. That writes ${t(e.replies)}.`+(e.listed?"":" The page doesn't list your key yet: run `npx pipeup agent --name <your name>` and tell me the attribute to add."):"3. Tell me what you would reply in each thread, in words I can paste.","4. Only mark a thread addressed. Never resolve, reopen, edit or delete: I close threads. Keep your key out of the page and its folder, and never answer as me.","","Guide: https://pipeup-ai.github.io/pipeup/skills/pipeup-apply/SKILL.md"].join(`
+`)}var C=/^[A-Za-z0-9_-]{43}$/,_="pipeupReplies";var D=/^AI assistant\s*·?\s*/;function x(e=document.documentElement){let t=e.getAttribute("data-pipeup-agents")??"";return[...new Set(t.split(/[\s,]+/).filter(n=>C.test(n)))]}function k(e=location,t=document.documentElement){let n=t.getAttribute("data-pipeup-replies");try{let s=e.href.split(/[?#]/)[0],o=new URL(n??(/\/$/.test(s)?`${s}index.replies.js`:s.replace(/\.[^./]*$/,"")+".replies.js"),e.href),c=o.protocol==="file:"?e.protocol==="file:":o.origin===e.origin;return c||console.warn("pipeup: the replies file must be on this site or this computer; ignoring it"),c?o.href:null}catch{return null}}function E(e){let t=x(),n=0,s="",o=null;async function c(){let l=globalThis[_];if(!Array.isArray(l))return 0;let p=l.splice(0),g=[];for(let f of p){let m=f;if(!(m?.format!=="pipeup-replies"||m.doc!==e.document.id||!Array.isArray(m.ops)))for(let i of m.ops){let a=i?.body;a&&t.includes(a.author)&&(a.kind==="reply"||a.kind==="addressed"||a.kind==="react"||a.kind==="unreact")?(g.push(i),(a.name==="AI assistant"||a.name.startsWith("AI assistant "))&&(s=a.name.replace(D,""))):n++}}return g.length?e.merge(g):0}function y(){let l=k();return l?(o?.remove(),new Promise((p,g)=>{let f=document.createElement("script");o=f,f.src=`${l}?${Date.now()}`;let m=a=>{window.clearTimeout(i),f.remove(),o===f&&(o=null),a?g(new Error(`pipeup: ${a}`)):p()},i=window.setTimeout(()=>m("the replies file didn't answer"),4e3);f.addEventListener("load",()=>m()),f.addEventListener("error",()=>m("there is no replies file yet")),e.overlay().append(f)})):Promise.reject(new Error("pipeup: the replies file can't be read from here"))}async function r(){if(!t.length)return 0;let l=await c();return await y(),l+await c()}let u=!1,d=()=>{u||document.hidden||(u=!0,r().catch(()=>{}).finally(()=>u=!1))},h=0;return t.length?(d(),h=window.setInterval(d,4e3),document.addEventListener("visibilitychange",d)):c(),{enabled:t.length>0,ignored:()=>n,who:()=>s,check:r,tally:l=>{let p=l.filter(i=>!i.resolved),g=i=>i.root.replies.some(a=>t.includes(a.author)),f=new Set(l.map(i=>i.id));return{stray:new Set(e.document.ops().filter(i=>t.includes(i.body.author)&&!f.has(i.body.thread)).map(i=>i.body.thread)).size,open:p.length,answered:p.filter(g).length,addressed:p.filter(i=>i.addressed).length}},destroy:()=>{window.clearInterval(h),document.removeEventListener("visibilitychange",d),o?.remove()}}}var R=()=>globalThis.Pipeup??{},H=["M10 8h8a2 2 0 0 1 2 2v8a2 2 0 0 1-2 2h-8a2 2 0 0 1-2-2v-8a2 2 0 0 1 2-2z","M16 8V6a2 2 0 0 0-2-2H6a2 2 0 0 0-2 2v8a2 2 0 0 0 2 2h2"],N=["M21 12L3.5 4.5 6.2 12l-2.7 7.5zM6.2 12H13"],z="Reads a replies file next to this page. When the page is shown through pipeup watch, and only after you switch it on, it sends this page's comments to the program running on this computer. Nothing leaves this computer.",S=e=>e instanceof Error?e.message.replace(/^pipeup: /,""):"Something went wrong";async function K(e,t){try{await navigator.clipboard.writeText(e);return}catch{}let n=document.createElement("textarea");n.value=e,n.setAttribute("readonly",""),n.style.cssText="position:fixed;opacity:0;pointer-events:none",t.append(n),n.select();let s=document.execCommand("copy");if(n.remove(),!s)throw new Error("pipeup: your browser blocked copying")}function U(){return{id:"agents",api:1,version:"0.6.0",needs:["menu","status","notify","listnote"],network:{when:"page-configured",to:["page"],says:z},setup(e){let t=E(e),n=P({snapshot:async()=>{let r=R();if(!r.comments)throw new Error("pipeup: this page has no Pipeup to read comments from");let[u,d]=await Promise.all([r.comments(),r.comments({all:!0})]);return{v:1,at:new Date().toISOString(),title:document.title,open:u,all:d}},changes:r=>e.document.onChange(r),refresh:()=>o()}),s=()=>t.who()||n.agent,o=()=>{if(e.setStatus(t.enabled||n.enabled?{text:n.on()?`Sharing comments with ${s()||"your agent"}`:`${s()||"An AI agent"} can answer comments here`}:null),!t.enabled)return e.setListNote(null);let r=t.tally(e.document.threads()),u=s()||"An agent",d=r.answered?`${u} has answered ${r.answered} of ${r.open} open comments${r.addressed?`; ${r.addressed} ${r.addressed===1?"is":"are"} marked addressed`:""}`:"No replies from an agent yet",h=t.ignored(),l=(n.on()?`Sharing with ${n.agent||"your agent"} \xB7 `:"")+d+(h?` \xB7 ${h} from other writers ignored`:"")+(r.stray?` \xB7 replies for ${r.stray} comment${r.stray===1?"":"s"} this page doesn't have`:"");e.setListNote({text:l,action:{label:"Check for replies",run:async()=>{try{let p=await t.check();e.notify(p?`${p} new ${p===1?"reply":"replies"}`:"No new replies")}catch(p){e.notify(S(p))}finally{o()}}}})},c=[e.addMenuItem({id:"prompt",icon:H,label:()=>"Copy a prompt for my agent",hint:()=>"Tells an AI agent where the comments are and how to answer them",select:async()=>{try{await K(T({title:document.title,url:location.href,replies:k(),file:n.enabled?n.file:"",listed:x().length>0}),e.overlay()),e.notify("Copied a prompt for your agent")}catch(r){e.notify(S(r))}}})];n.enabled&&c.push(e.addMenuItem({id:"link",icon:N,label:()=>"Share with my agent",hint:()=>"Sends this page's comments to the program running on this computer, and nothing else",checked:()=>n.on(),select:async()=>{try{await n.set(!n.on())}catch(r){e.notify(S(r))}o()}}));let y=e.document.onChange(o);return o(),()=>{y(),t.destroy(),n.destroy()}}}}b(U());})();