pipeup 0.8.1 → 0.9.0

package/README.md

@@ -2,7 +2,7 @@
 
 Comments and feedback right on any HTML page: documents, slide decks and whole sites.
 
-> **Alpha (0.8.1).** The API and the stored comment format may change before 1.0; pin an exact version.
+> **Alpha (0.9.0).** 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,
@@ -16,14 +16,20 @@ colour on a tint of it) at the top right of their comments; once they add a name
 identity row at the top of the menu) the avatar shows their initial in the same colours. Copy for AI names unnamed reviewers by
 their colour and animal.
 
-As a classic script (also works from `file://`), it mounts itself on pages that carry a document id:
+As a classic script (also works from `file://`), it mounts itself (`data-pipeup-auto="off"` stops that). The script
+line alone is enough; a document id on `<html>` keeps comments with the page wherever it is opened, instead of with
+its address:
 
 ```html
 <html data-pipeup-doc="<id>:<key>">
   ...
-  <script src="https://cdn.jsdelivr.net/npm/pipeup@0.8.1/dist/pipeup.min.js" integrity="sha384-…" crossorigin="anonymous" defer></script>
+  <script src="https://cdn.jsdelivr.net/npm/pipeup@0.9.0/dist/pipeup.min.js" integrity="sha384-…" crossorigin="anonymous" defer></script>
 ```
 
+On a host that writes its own `<html>` (claude.ai Artifacts, for example), put the same settings on the script
+line instead: `<script src="…/pipeup.min.js" data-pipeup-doc="<id>:<key>" …>`. Every `data-pipeup-*` setting works
+there, for add-ons too.
+
 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.
@@ -39,11 +45,21 @@ Install with `npm i pipeup`. From a bundler (no side effects; call `mount` yours
 
 ```js
 import { mount } from "pipeup";
-const pipeup = await mount({ name: "Sam" }); // options: root, name (optional), store, slides
+const pipeup = await mount({ name: "Sam" }); // options: root, name, store, slides, doc, layout, theme, select
 await pipeup.flush(); // write any unsaved changes now (this also happens when the page is hidden)
 pipeup.unmount(); // remove Pipeup from the page; the comments stay saved
 ```
 
+A page with its own review controls (a Comment button in its header, a name field) drives Pipeup without reaching
+inside it:
+
+```js
+await pipeup.setCommentMode(true); // resolves once comment mode is on; pipeup.commentMode reads it
+await pipeup.setName("Ada"); // kept as if the reviewer had typed it; pipeup.name reads it
+const stop = pipeup.on("change", ({ commentMode, name }) => label(commentMode, name)); // however it changed
+mount().catch((e) => show(e.code, e.message)); // "another-copy" or "failed", with words for people
+```
+
 Pages designed for review can reserve a comment gutter: add `data-pipeup-reserve` to `<html>` and lay the
 page out with `var(--pipeup-gutter, 0px)`. While All comments is open the page is moved over for it and its
 width is published as `--pipeup-panel`, so fixed bars can use `right: var(--pipeup-panel, 0px)` — see [examples/review-document.html](https://github.com/pipeup-ai/pipeup/blob/main/libs/ts/pipeup/examples/review-document.html).
@@ -64,14 +80,17 @@ Examples in the source repository, one per kind of page, each following the agen
 - [examples/review-site.html](https://github.com/pipeup-ai/pipeup/blob/main/libs/ts/pipeup/examples/review-site.html) — a site: clear blocks with stable ids for comment mode and pins; navigation ignored.
 - [examples/review-deck.html](https://github.com/pipeup-ai/pipeup/blob/main/libs/ts/pipeup/examples/review-deck.html) — a deck: one marked element per slide; slide controls ignored so they keep working, and one line so Pipeup can go to a comment's slide.
 
+Selecting words offers a comment icon beside them, in comment mode or out of it; outside it, the comment leaves
+comment mode off and the page keeps working (`data-pipeup-select="comment-mode"` keeps it to comment mode).
 Comments show whether comment mode is on or off: highlights, bubbles and the column can be read and opened, and
 outside comment mode the rest of the page works as normal. **Hide comments** in the control's menu puts them out
 of sight on that page (remembered in the browser); the control still counts the open threads, and comment mode,
 All comments or a comment being written show them again while they last.
 
 The comment control is a small square of frosted glass tucked into the bottom-right corner: the comment icon, or
-the number of open threads inside a comment bubble. Pointed at, it reaches left to show its shortcut; clicking (or tapping) it opens its menu of
-one-line rows, each explained by a tooltip on hover or focus. From the top: who you are (avatar and name, with
+the number of open threads inside a comment bubble. One click (or tap) starts comment mode and another stops it.
+Pointed at, it reaches left to show its shortcut and **⋯**, which opens its menu (by touch, press and hold the
+control; from the keyboard, ↑ on it): one-line rows, each explained by a tooltip on hover or focus. From the top: who you are (avatar and name, with
 Add name, edited in place in that row), Copy comments (as Markdown for AI, or as text), Theme, All comments, a Hide comments switch, and nearest the button **Start commenting** with its shortcut and a switch, which leaves the menu open so you see it move. The menu closes on Esc, a click outside, or 3 seconds after the pointer leaves it.
 **All comments** is a panel on the right that moves the page over to make room: every thread in page order as a
 card, threads whose content is gone under "No longer on the page", and two icon toggles in its header, **@** (mentions
@@ -86,7 +105,7 @@ comment goes away; deleting a thread's first comment removes the thread. The com
 reply boxes have Cancel and Comment (Reply) buttons; Enter also sends. Elements the page
 fixes to the window don't move over with the page.
 
-Comment mode (press **Shift+Alt+C**, or **⇧⌥C** on a Mac, or switch on Start commenting in the control's menu) lets reviewers comment on blocks and drop pins
+Comment mode (click the comment control, press **Shift+Alt+C**, or **⇧⌥C** on a Mac) lets reviewers comment on blocks and drop pins
 (Option-click, Alt-click, or the naming bar's Pin) on any page. While it is on, clicks and submits on the page do
 nothing, and selecting text offers a comment icon, clicking a highlight opens its thread, and
 clicking a block opens its comment box at once (a bar names the block; Around it and Inside it move the box to the

package/cli/asks.d.mts

@@ -0,0 +1,33 @@
+import type { Thread } from "../src/model/types";
+
+export interface PageAsk {
+  id: string;
+  question: string;
+  kind: "open" | "agree" | "choice";
+  options: string[];
+  other: boolean;
+  needed: boolean;
+}
+export interface ReadAnswer {
+  thread: string;
+  name: string;
+  author: string;
+  choice: string;
+  words: string;
+  text: string;
+  at: string;
+  edited: boolean;
+  replies: number;
+  askedAs?: string;
+}
+export function asksIn(html: string): PageAsk[];
+export function parseAnswer(ask: PageAsk, text: string): { choice: string; words: string } | null;
+export function asksWithAnswers(
+  html: string,
+  threads: readonly Thread[],
+  agents?: readonly string[],
+): (PageAsk & { answers: ReadAnswer[] })[];
+export function asksMarkdown(
+  asks: (PageAsk & { answers: ReadAnswer[] })[],
+  nameOf: (key: string) => string,
+): string;

package/cli/asks.mjs

@@ -0,0 +1,131 @@
+// The asks a page puts in its content (spec §11b, the inline add-on), with each reviewer's latest answer, for
+// `pipeup read`. Read from the page's markup and the comments, as the add-on reads them: an answer is a comment on the
+// ask's block, kept with the question it answered ("Asked: …"), whose words fit the ask's kind.
+
+const ASKED = "Asked: ";
+const AGREE = "Agree";
+const CHANGE = "Needs change";
+const OTHER = "Other";
+
+const unescape = (s) =>
+  s
+    .replace(/"/g, '"')
+    .replace(/'|'/g, "'")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&amp;/g, "&");
+
+/** A tag's attributes, by name (lower case); a bare attribute is "". */
+function attrs(tag) {
+  const out = {};
+  for (const m of tag.matchAll(/\s([^\s"'<>/=]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+)))?/g))
+    out[m[1].toLowerCase()] = unescape(m[2] ?? m[3] ?? m[4] ?? "");
+  return out;
+}
+
+/** The page's asks, in page order: { id, question, kind, options, other, needed }. */
+export function asksIn(html) {
+  const asks = [];
+  for (const m of html.matchAll(/<[a-z][a-z0-9-]*\b(?:[^>"']|"[^"]*"|'[^']*')*>/gi)) {
+    const a = attrs(m[0]);
+    if (!("data-pipeup-ask" in a)) continue;
+    const id = a["data-pipeup-id"] ?? "";
+    const question = a["data-pipeup-ask"].replace(/\s+/g, " ").trim();
+    if (!id || !question) continue;
+    const given = a["data-pipeup-ask-kind"];
+    const kind = given === "agree" || given === "choice" ? given : "open";
+    const options =
+      kind === "agree"
+        ? [AGREE, CHANGE]
+        : kind === "choice"
+          ? [
+              ...new Set(
+                (a["data-pipeup-ask-options"] ?? "")
+                  .split("|")
+                  .map((o) => o.trim())
+                  .filter(Boolean),
+              ),
+            ]
+          : [];
+    if (kind === "choice" && (options.length < 2 || options.length > 6)) continue;
+    asks.push({
+      id,
+      question,
+      kind,
+      options,
+      other: kind === "choice" && "data-pipeup-ask-other" in a,
+      needed: "data-pipeup-ask-needed" in a,
+    });
+  }
+  return asks;
+}
+
+/** A comment's words as an answer to `ask` ({ choice, words }), or null. */
+export function parseAnswer(ask, text) {
+  const t = text.trim();
+  if (!t) return null;
+  if (ask.kind === "open") return { choice: "", words: t };
+  for (const choice of [...ask.options, ...(ask.other ? [OTHER] : [])]) {
+    if (t === choice && choice !== CHANGE && choice !== OTHER) return { choice, words: "" };
+    if ((ask.kind === "agree" || choice === OTHER) && t.startsWith(`${choice}:`)) {
+      const words = t.slice(choice.length + 1).trim();
+      if (words || choice === AGREE) return { choice, words };
+    }
+  }
+  return null;
+}
+
+/** Pipeup's name for AI writers: "AI assistant", or that and more words. */
+const AI_NAME = "AI assistant";
+
+/**
+ * Each ask with every reviewer's latest answer (and the question it answered, when the words have changed since).
+ * Agents never answer asks: a thread there by an agent the page lists (`agents`), or under an AI name, isn't counted.
+ */
+export function asksWithAnswers(html, threads, agents = []) {
+  return asksIn(html).map((ask) => {
+    const latest = new Map();
+    for (const t of [...threads].sort((a, b) => a.root.at - b.root.at)) {
+      if (t.anchor.id !== ask.id || t.root.deleted || !t.anchor.snapshot?.startsWith(ASKED)) continue;
+      const name = t.root.name ?? "";
+      if (agents.includes(t.root.author) || name === AI_NAME || name.startsWith(`${AI_NAME} `)) continue;
+      const answer = parseAnswer(ask, t.root.text);
+      if (!answer) continue;
+      const was = t.anchor.snapshot.slice(ASKED.length);
+      latest.set(t.root.author, {
+        thread: t.id,
+        name: t.root.name,
+        author: t.root.author,
+        ...answer,
+        text: t.root.text,
+        at: new Date(t.root.at).toISOString(),
+        edited: t.root.edited,
+        replies: t.root.replies.length,
+        ...(was && was !== ask.question.slice(0, was.length) ? { askedAs: was } : {}),
+      });
+    }
+    return { ...ask, answers: [...latest.values()] };
+  });
+}
+
+/** The asks as Markdown, after the comments: each question, its kind, and who answered what. */
+export function asksMarkdown(asks, nameOf) {
+  if (!asks.length) return "";
+  const lines = ["", "## Asks", ""];
+  for (const a of asks) {
+    const kind =
+      a.kind === "choice"
+        ? `choice: ${[...a.options, ...(a.other ? [OTHER] : [])].join(", ")}`
+        : a.kind === "agree"
+          ? "agree or needs change"
+          : "open";
+    lines.push(`### "${a.question}"`, "", `- Name: \`${a.id}\` · ${kind}${a.needed ? " · needed" : ""}`);
+    if (!a.answers.length) lines.push("- No answers yet.");
+    for (const r of a.answers)
+      lines.push(
+        `- ${r.name || nameOf(r.author)}: ${r.text.split("\n")[0]}${r.edited ? " (changed)" : ""}${r.askedAs ? ` (asked as: "${r.askedAs}")` : ""} — thread ${r.thread}`,
+      );
+    lines.push("");
+  }
+  return lines.join("\n");
+}

package/cli/init.mjs

@@ -67,7 +67,7 @@ function attrSpan(tag, name) {
 const attrEnd = (tag) => tag.length - (/\s*\/?>$/.exec(tag)?.[0].length ?? 1);
 
 /** What the page already has: its <html> tag, Pipeup's script, add-ons. */
-function survey(html) {
+export function survey(html) {
   const h = HTML_TAG.exec(html);
   if (!h) throw new InitError("the page has no <html> element; add one around the page and run this again");
   const found = { html: { at: h.index, tag: h[0] }, core: null, addons: new Map(), lastScriptEnd: -1 };
@@ -298,7 +298,7 @@ export function candidates(html) {
 }
 
 /** Applies edits (each { at, del, text }) from the end of the file back, so earlier offsets stay right. */
-function apply(html, edits) {
+export function apply(html, edits) {
   let out = html;
   for (const e of [...edits].sort((a, b) => b.at - a.at || b.order - a.order))
     out = out.slice(0, e.at) + e.text + out.slice(e.at + (e.del ?? 0));
@@ -306,7 +306,7 @@ function apply(html, edits) {
 }
 
 /** Sets (or appends to) an attribute on the <html> start tag: returns the edit, or null when nothing changes. */
-function htmlAttr(found, name, value, { append = false } = {}) {
+export function htmlAttr(found, name, value, { append = false } = {}) {
   const { at, tag } = found.html;
   const span = attrSpan(tag, name);
   if (!span) return { at: at + attrEnd(tag), text: ` ${name}="${escapeAttr(value)}"` };

package/cli/pipeup.mjs

@@ -1,11 +1,12 @@
 #!/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 { chmod, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { basename, dirname, join, resolve } from "node:path";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
 import { check, table } from "./check.mjs";
-import { init, InitError } from "./init.mjs";
+import { apply, htmlAttr, init, InitError, survey } from "./init.mjs";
 import { read, ReadError } from "./read.mjs";
 import { comments, watch } from "./link.mjs";
 import * as skills from "./skills.mjs";
@@ -30,6 +31,7 @@ pipeup read <page.html> [--from <file or folder>]… [--deep] [--all] [--json] [
   feedback files and folders of them (--deep looks in folders inside), the page's shared copy (with @pipeup/share
   installed; --no-share reads nothing from the network) and its replies file. Every comment is checked as the page
   checks it; what was read, skipped or left out is said on standard error. --out writes one merged feedback file.
+  Asks the page puts in its content (the inline add-on) follow, each with its question, kind and answers.
   Exit codes: 0 done, 1 a source couldn't be read, 2 the command needs something first.
 
 pipeup skills install|remove|list [--project] [--agent claude|codex|all] [--yes] [--replace] [--dry-run]
@@ -41,9 +43,10 @@ pipeup check <page.html> [--json]
   Loads the page with and without Pipeup at 375, 768 and 1440 px (with Playwright, which you install) and says what
   Pipeup changes or covers, and what the page could do better: pass, WARN or FAIL for each. Exits 1 on any FAIL.
 
-pipeup agent [--name <name>]
+pipeup agent [--name <name>] [--page <page.html>] [--yes]
   Makes this computer's agent key (once) and prints the public key to list on the page:
-  <html data-pipeup-agents="<key>">
+  <html data-pipeup-agents="<key>">. With --page it lists the agent on that page itself: it shows the one change and
+  asks first (--yes to go ahead without asking; where it can't ask, it changes nothing and exits 2).
 
 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"
@@ -55,8 +58,66 @@ 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.`;
+  Writes a signed reply (and, with --addressed, an addressed note) where the page reads replies: <file>.replies.js
+  next to the page, or the file the page names. The page is the HTML file that runs Pipeup, never a file it shows.
+  It never resolves, reopens, edits or deletes anything: the author closes threads.
+
+pipeup reply --print (--doc <document id> | --page <file.html>) --thread <id> "<words>" [--addressed "<short note>"]
+  Prints the same signed reply as a replies block for the person to paste into the page (Paste my agent's replies),
+  for an agent that can't write next to the page. Copy for my agent gives the document id. Nothing is written.
+
+Agents run these as \`npx --yes pipeup@0 …\`: any release from 0.6 answers agent, reply and comments the same way.`;
+
+/** How agents are told to run this command line: never stopping to ask, and any release npm will give. */
+const RUN = "npx --yes pipeup@0";
+/** A path as the person typed it, or relative to where they are. */
+const shown = (file) => relative(process.cwd(), resolve(file)) || file;
+const DOC = /<html\b[^>]*\sdata-pipeup-doc\s*=\s*["']([^"']+)["']/i;
+
+/**
+ * The options each agent command knows: one this release doesn't know is said, and the rest carry on (a newer
+ * agent's command still works with an older release).
+ */
+const KNOWN = {
+  agent: ["name", "page", "yes"],
+  reply: ["page", "thread", "addressed", "print", "doc"],
+  comments: ["all", "json"],
+  watch: ["agent", "port"],
+};
+function unknown(command, args) {
+  for (const k of Object.keys(args))
+    if (k !== "_" && KNOWN[command] && !KNOWN[command].includes(k))
+      console.warn(`pipeup: this release doesn't know --${k}; carrying on without it`);
+}
+
+/** The HTML file nearest to `file` (its folder, then the folders above) that runs Pipeup, or null. */
+async function nearbyPage(file) {
+  const self = resolve(file);
+  let dir = dirname(self);
+  for (let i = 0; i < 4; i++) {
+    const names = await readdir(dir).catch(() => []);
+    for (const n of names.filter((n) => /\.html?$/i.test(n)).sort()) {
+      const p = join(dir, n);
+      if (p !== self && DOC.test(await readFile(p, "utf8").catch(() => ""))) return p;
+    }
+    const up = dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  return null;
+}
+
+/** `file` doesn't run Pipeup (a note a viewer shows, say): nothing is written, and the page nearby is named. */
+async function notPipeup(file, what) {
+  const near = await nearbyPage(file);
+  console.error(`pipeup: ${shown(file)} doesn't run Pipeup, so ${what}.`);
+  console.error(
+    near
+      ? `The page that shows it is probably ${shown(near)}:\n  --page ${shown(near)}`
+      : "Pass the HTML page the comments were left on: --page <page.html>",
+  );
+  process.exit(1);
+}
 
 function fail(message) {
   console.error(`pipeup: ${message}`);
@@ -109,13 +170,26 @@ async function loadAgent(name) {
 /** A name that shows it is an agent: "AI assistant · Claude". */
 const signedName = (name) => (name && name !== AI ? `${AI} · ${name}`.slice(0, 80) : AI);
 
+/** Reads a page: its text, or a plain failure when it can't be read. */
+const readPage = (file) => readFile(file, "utf8").catch((e) => fail(`can't read ${file}: ${e.message}`));
+
 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 html = await readPage(file);
+  const m = DOC.exec(html);
+  if (!m) await notPipeup(file, "nothing was written");
   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) };
+  // Where the page reads replies: the file it names (a path beside it), else <page>.replies.js.
+  const given = /<html\b[^>]*\sdata-pipeup-replies\s*=\s*["']([^"']+)["']/i.exec(html)?.[1];
+  const local = given && !/^[a-z][\w+.-]*:|^\/\//i.test(given);
+  if (given && !local)
+    console.warn(
+      `pipeup: the page reads replies from ${given}, which isn't a file here; writing next to the page`,
+    );
+  const replies = local
+    ? resolve(dirname(file), given.split(/[?#]/)[0])
+    : resolve(file.replace(/\.[^./\\]*$/, "") + ".replies.js");
+  return { id, listed: listed.split(/[\s,]+/).filter(Boolean), replies };
 }
 
 const headerOf = (file) =>
@@ -132,24 +206,71 @@ async function readReplies(path, doc) {
   }
 }
 
+/** One entry of a replies block, signed: the person pastes it into the page, which checks it against the listed keys. */
+function printBlock(name, thread, words, note, ops) {
+  const field = (key, text) =>
+    text
+      .split("\n")
+      .map((line, i) => (i ? `  ${line}` : `${key}: ${line}`))
+      .join("\n");
+  return [
+    "```pipeup-replies",
+    `agent: ${name}`,
+    `thread: ${thread}`,
+    field("reply", words),
+    ...(note ? [field("addressed", note)] : []),
+    `signed: ${b64u(new TextEncoder().encode(JSON.stringify(ops)))}`,
+    "```",
+  ].join("\n");
+}
+
 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 print = args.print === true;
+  const given = typeof args.doc === "string" && print ? args.doc.trim() : "";
+  if ((typeof page !== "string" && !given) || typeof thread !== "string" || !words)
+    fail(`missing words, ${print ? "--doc" : "--page"} or --thread\n\n${USAGE}`);
+  if (given && given.length > 64) fail("that isn't a document id");
   const note = typeof args.addressed === "string" ? args.addressed.trim() : "";
-  const { id: doc, listed } = await pageDoc(page);
+  const {
+    id: doc,
+    listed,
+    replies: out,
+  } = given ? { id: given, listed: null, replies: "" } : await pageDoc(page);
   const { identity, name } = await loadAgent();
+  if (print) {
+    let clock = Math.floor(Date.now() / 1000);
+    let at = Date.now();
+    const { computeOpId, signOp } = await core();
+    const make = async (fields) => {
+      const body = {
+        v: 1,
+        ...fields,
+        id: "",
+        doc,
+        author: identity.publicKey,
+        name: signedName(name),
+        clock: clock++,
+        at: at++,
+      };
+      body.id = await computeOpId(body);
+      return signOp(body, identity);
+    };
+    const ops = [await make({ kind: "reply", thread, target: thread, text: words })];
+    if (note) ops.push(await make({ kind: "addressed", thread, text: note }));
+    if (listed && !listed.includes(identity.publicKey))
+      console.error(
+        `pipeup: this page doesn't list your key, so these replies will show as pasted by the person.\n  To be listed: <html data-pipeup-agents="${identity.publicKey}">`,
+      );
+    console.log(printBlock(name, thread, words, note, ops));
+    return;
+  }
   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));
@@ -173,16 +294,57 @@ async function reply(args) {
   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}`);
+  console.log(`Wrote ${added.length} ${added.length === 1 ? "entry" : "entries"} to ${shown(out)}.`);
+  // Written either way, so nothing is lost: the page shows them once it lists the agent.
+  if (!listed.includes(identity.publicKey) && !linked)
+    console.warn(
+      `The page will ignore them until it lists ${name || "your agent"}. Ask the page's author. After their yes, run:\n  ${RUN} agent --page ${shown(page)} --yes`,
+    );
+  else console.log("The page reads this file: the reply shows in its thread within a few seconds.");
+}
+
+/**
+ * Lists the agent on a page: the one change (its key in data-pipeup-agents on <html>) is shown and asked about first;
+ * --yes goes ahead. Where it can't ask (an agent's shell, with nobody to answer), nothing changes and it exits 2.
+ */
+async function listOn(page, identity, name, yes) {
+  const html = await readPage(page);
+  if (!DOC.test(html)) await notPipeup(page, "nothing was changed");
+  const found = survey(html);
+  const edit = htmlAttr(found, "data-pipeup-agents", identity.publicKey, { append: true });
+  if (!edit) return console.log(`${name} is already listed on ${shown(page)}; nothing was changed.`);
+  const next = apply(html, [{ ...edit, order: 0 }]);
+  console.log(
+    `\nThis ${edit.del ? `adds ${name}'s key to the page's agents` : "adds one attribute"} on ${shown(page)}, and changes nothing else:\n  ${survey(next).html.tag}\n`,
+  );
+  if (!yes) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+      console.log(
+        "This shell can't ask, so nothing was changed.\nAsk the page's author. After their yes, run it again with --yes.",
+      );
+      process.exitCode = 2;
+      return;
+    }
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await rl.question("Add it? (y/N) ");
+    rl.close();
+    if (!/^y(es)?$/i.test(answer.trim())) return console.log("Nothing was changed.");
+  }
+  await writeFile(page, next);
+  console.log(`Listed ${name} on ${shown(page)}. Reload the page, and it shows ${name}'s replies.`);
 }
 
 const [command, ...rest] = process.argv.slice(2);
 const args = flags(rest);
+unknown(command, args);
 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}">`,
-  );
+  console.log(`${name} (${KEYFILE})`);
+  if (typeof args.page === "string") await listOn(args.page, identity, name, args.yes === true);
+  else
+    console.log(
+      `\nList this key on the page:\n  <html data-pipeup-agents="${identity.publicKey}">\nOr list it in one step: ${RUN} agent --page <page.html>`,
+    );
 } else if (command === "reply") await reply(args);
 else if (command === "skills") {
   const sub = args._[0];
@@ -299,7 +461,7 @@ else if (command === "skills") {
   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)})`,
+    `Read:  ${RUN} comments ${page}\nReply: ${RUN} 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);

package/cli/read.mjs

@@ -3,6 +3,7 @@
 import { readdir, readFile, stat, writeFile } from "node:fs/promises";
 import { basename, dirname, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
+import { asksMarkdown, asksWithAnswers } from "./asks.mjs";
 
 const core = () => import("../dist/pipeup.core.js");
 const MAX_MERGE = 5000;
@@ -52,7 +53,7 @@ async function filesIn(dir, deep) {
 
 /**
  * The share add-on's headless reader, if it is installed: beside this package, or in the project the command runs in
- * (as with `npx pipeup read` in a folder where `@pipeup/share` is installed). It is never a dependency of `pipeup`.
+ * (as with `npx --yes pipeup@0 read` in a folder where `@pipeup/share` is installed). It is never a dependency of `pipeup`.
  */
 async function shareReader() {
   try {
@@ -118,6 +119,7 @@ export async function read(o) {
     parseDocumentAttribute,
     readFeedbackFile,
     agentComments,
+    animalName,
   } = await core();
   let id;
   let key;
@@ -286,6 +288,16 @@ export async function read(o) {
     all: o.all,
   });
 
+  // The asks the page puts in its content (§11b), each with every reviewer's latest answer, so an agent can work through them.
+  const asks = asksWithAnswers(
+    html,
+    threads,
+    (attrOf(html, "data-pipeup-agents") ?? "").split(/[\s,]+/).filter(Boolean),
+  );
+  if (asks.length) {
+    out.asks = asks;
+    out.markdown = `${out.markdown.trimEnd()}\n${asksMarkdown(asks, animalName)}`;
+  }
   if (o.out) {
     try {
       await writeFile(o.out, await doc.exportFile());