pi-copy 0.0.0-stage → 0.1.2

package/README.md

@@ -1,3 +1,43 @@
-# Temporary Holding Version
+# pi-copy
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A pi extension that copies **one part** of the last answer so it pastes cleanly: a code block exactly as written (a long command continued with `\` pastes into a terminal and runs), or the prose as plain text (one line per paragraph, ready for an email).
+
+Pi's own `/copy` (Ctrl+X) copies the whole last answer as markdown source, fences and marks included; drag-selecting copies the rendered screen, wraps and borders included. pi-copy reads the answer's source text from the session instead, never the screen.
+
+## Use
+
+- `/copy-part` opens a picker of the answer's parts. Enter copies the chosen part; Escape copies nothing.
+- **alt+c** does the same, except that when the answer has exactly one code block it copies that block at once.
+- After a copy, a one-line notice names what was copied and its size, such as `Copied code block (1 line, 148 chars)`. With no answer yet it says `No answer to copy yet.`
+
+## The parts
+
+- **Each code block**, in order, labelled with its language and its first line. Copied as its exact text: no fences, no indent, no trailing newline. A block inside a list item counts too.
+- **The prose**: everything outside the code blocks, as plain text. Paragraphs are one line each, separated by a blank line; bold, italic, inline code and strike marks are removed; a link becomes `text (url)`, or just the address when the two are the same; headings are their text on a line of their own; list items keep `- ` or `1. ` with two spaces per nesting level; a blockquote loses its `>`; a table is copied as its markdown source rows.
+- **All**: the whole answer, the prose as above with each code block's text in place.
+
+An answer with no code blocks has only the prose part; one with no prose has only its code blocks.
+
+Only the last answer is read. An earlier answer can still be copied whole from `/tree` with Ctrl+X.
+
+## Design
+
+- Parsing uses `marked`'s lexer, the parser pi draws messages with, carried as this package's own dependency (pinned to the version pi uses) because pi doesn't provide it to extensions.
+- The copy goes through pi's `copyToClipboard`, which also reaches the local clipboard from tmux and over SSH through OSC 52.
+- `src/parts.ts` is the pure splitting and plain-text rendering; `src/index.ts` is the thin pi wiring.
+
+## Tests
+
+`node --test src/*.test.ts`: the parts and each part's copied text (continued commands, a block in a list, paragraphs, inline marks, links, headings, nested lists, blockquotes, tables, the notice), and the wiring against a fake pi (alt+c's one-block shortcut, the picker, Escape, no answer, an aborted answer skipped).
+
+## Install
+
+```sh
+pi install npm:pi-copy
+```
+
+Or try it against a live session without installing:
+
+```sh
+pi -e ./packages/pi-copy/src/index.ts
+```

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "pi-copy",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.2",
+  "description": "Copy one part of the last pi answer from its source text: a code block exactly as written, or the prose as plain text, through /copy-part and alt+c.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/subaud-tools/pi-extensions.git",
+    "directory": "packages/pi-copy"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi-coding-agent",
+    "copy",
+    "clipboard",
+    "markdown"
+  ],
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "node --test src/*.test.ts"
+  },
+  "dependencies": {
+    "marked": "18.0.11"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.84.3",
+    "typescript": "^5.6.0"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,112 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { createCopy } from "./index.ts";
+
+const assistant = (text: string) => ({
+  type: "message",
+  message: { role: "assistant", content: [{ type: "text", text }], stopReason: "stop" },
+});
+const user = (text: string) => ({ type: "message", message: { role: "user", content: text } });
+
+// A fake pi capturing the command and shortcut, and a fake ctx whose branch,
+// select answer, notices and clipboard are all observable.
+function makeFixture(branch: any[], choose: (labels: string[]) => string | undefined = () => undefined) {
+  const commands = new Map<string, { handler: (args: string, ctx: any) => Promise<void> }>();
+  const shortcuts = new Map<string, { handler: (ctx: any) => Promise<void> }>();
+  const copied: string[] = [];
+  const notices: string[] = [];
+  const selects: string[][] = [];
+
+  const pi = {
+    registerCommand(name: string, options: any) {
+      commands.set(name, options);
+    },
+    registerShortcut(key: string, options: any) {
+      shortcuts.set(key, options);
+    },
+  };
+  createCopy(pi, {
+    copy: async (text: string) => {
+      copied.push(text);
+    },
+  });
+
+  const ctx = {
+    sessionManager: { getBranch: () => branch },
+    ui: {
+      async select(_title: string, labels: string[]) {
+        selects.push(labels);
+        return choose(labels);
+      },
+      notify(message: string) {
+        notices.push(message);
+      },
+    },
+  };
+
+  return {
+    copied,
+    notices,
+    selects,
+    altC: () => shortcuts.get("alt+c")!.handler(ctx),
+    copyPart: () => commands.get("copy-part")!.handler("", ctx),
+  };
+}
+
+const oneBlock = "Cut the release:\n\n```bash\ngit tag pi-copy-v0.1.0 && git push --tags\n```";
+const twoBlocks = "Build:\n\n```sh\nnpm pack --workspace packages/pi-copy\n```\n\nThen:\n\n```sh\nnpm publish pi-copy-0.1.0.tgz\n```";
+
+test("alt+c with one code block copies it without the picker", async () => {
+  const f = makeFixture([user("how do I tag it?"), assistant(oneBlock)]);
+
+  await f.altC();
+
+  assert.equal(f.selects.length, 0);
+  assert.deepEqual(f.copied, ["git tag pi-copy-v0.1.0 && git push --tags"]);
+  assert.deepEqual(f.notices, ["Copied code block (1 line, 41 chars)"]);
+});
+
+test("alt+c with two code blocks opens the picker and copies the choice", async () => {
+  const f = makeFixture([assistant(twoBlocks)], (labels) => labels[1]);
+
+  await f.altC();
+
+  assert.equal(f.selects.length, 1);
+  assert.deepEqual(f.copied, ["npm publish pi-copy-0.1.0.tgz"]);
+});
+
+test("/copy-part opens the picker even with one code block", async () => {
+  const f = makeFixture([assistant(oneBlock)], (labels) => labels.find((l) => l.startsWith("Prose")));
+
+  await f.copyPart();
+
+  assert.equal(f.selects.length, 1);
+  assert.deepEqual(f.copied, ["Cut the release:"]);
+});
+
+test("Escape in the picker copies nothing", async () => {
+  const f = makeFixture([assistant(twoBlocks)], () => undefined);
+
+  await f.copyPart();
+
+  assert.deepEqual(f.copied, []);
+  assert.deepEqual(f.notices, []);
+});
+
+test("no answer yet notifies and copies nothing", async () => {
+  const f = makeFixture([user("hello")]);
+
+  await f.altC();
+
+  assert.deepEqual(f.copied, []);
+  assert.deepEqual(f.notices, ["No answer to copy yet."]);
+});
+
+test("an aborted empty answer is skipped for the one before it", async () => {
+  const aborted = { type: "message", message: { role: "assistant", content: [], stopReason: "aborted" } };
+  const f = makeFixture([assistant(oneBlock), user("again"), aborted]);
+
+  await f.altC();
+
+  assert.deepEqual(f.copied, ["git tag pi-copy-v0.1.0 && git push --tags"]);
+});

package/src/index.ts

@@ -0,0 +1,89 @@
+// pi-copy — copy one part of the last answer: a code block exactly as
+// written, or the prose as plain text.
+//
+// The answer is read from the session (the same message pi's /copy uses),
+// never from the screen, so nothing copied carries pi's wrapping or borders.
+// `/copy-part` always opens a picker of the parts; alt+c copies the one code
+// block at once when there is exactly one, and opens the picker otherwise.
+// The copy goes through pi's own copyToClipboard, which also reaches the
+// local clipboard from tmux and over SSH (OSC 52).
+//
+// The pure splitting lives in parts.ts; this file is the thin pi wiring.
+
+import { notice, splitParts, type Part } from "./parts.ts";
+
+export type Deps = {
+  // Injectable so the wiring is testable without pi's real clipboard.
+  copy?: (text: string) => Promise<void>;
+};
+
+// Lazy: a top-level import of the pi package pulls its entire runtime, which
+// only resolves inside a live pi process (and breaks node --test).
+async function defaultCopy(text: string): Promise<void> {
+  const mod: any = await import("@earendil-works/pi-coding-agent");
+  await mod.copyToClipboard(text);
+}
+
+// The last assistant answer's text, as pi's getLastAssistantText reads it:
+// an aborted message with no content is skipped.
+export function lastAnswerText(branch: any[]): string | undefined {
+  const entry = branch
+    .slice()
+    .reverse()
+    .find((e) => {
+      const m = e?.type === "message" ? e.message : undefined;
+      if (m?.role !== "assistant") return false;
+      return !(m.stopReason === "aborted" && (m.content ?? []).length === 0);
+    });
+  if (!entry) return undefined;
+  let text = "";
+  for (const content of entry.message.content ?? []) {
+    if (content?.type === "text") text += content.text;
+  }
+  return text.trim() || undefined;
+}
+
+export function createCopy(pi: any, deps: Deps = {}): void {
+  const copy = deps.copy ?? defaultCopy;
+
+  async function run(ctx: any, alwaysPick: boolean): Promise<void> {
+    const text = lastAnswerText(ctx.sessionManager.getBranch());
+    if (!text) {
+      ctx.ui.notify("No answer to copy yet.", "info");
+      return;
+    }
+    const parts = splitParts(text);
+    const code = parts.filter((p) => p.kind === "code");
+    let part: Part | undefined;
+    if (!alwaysPick && code.length === 1) {
+      part = code[0];
+    } else {
+      const label = await ctx.ui.select(
+        "Copy which part?",
+        parts.map((p) => p.label),
+      );
+      part = parts.find((p) => p.label === label);
+    }
+    if (!part) return;
+    try {
+      await copy(part.text);
+      ctx.ui.notify(notice(part), "info");
+    } catch (error) {
+      ctx.ui.notify(`pi-copy: could not copy: ${String(error)}`, "error");
+    }
+  }
+
+  pi.registerCommand("copy-part", {
+    description: "Copy one part of the last answer: a code block as written, or the prose as plain text",
+    handler: async (_args: string, ctx: any) => run(ctx, true),
+  });
+
+  pi.registerShortcut("alt+c", {
+    description: "Copy a part of the last answer (the one code block at once)",
+    handler: async (ctx: any) => run(ctx, false),
+  });
+}
+
+export default function (pi: any) {
+  createCopy(pi);
+}

package/src/parts.test.ts

@@ -0,0 +1,158 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { notice, splitParts } from "./parts.ts";
+
+const prose = (md: string) => splitParts(md).find((p) => p.kind === "prose")!.text;
+
+test("a multi-line command with \\ continuations copies byte for byte", () => {
+  const command = [
+    "gh release create pi-copy-v0.1.0 \\",
+    '  --repo subaud-tools/pi-extensions \\',
+    '  --title "pi-copy 0.1.0" \\',
+    "  --notes-file CHANGELOG.md --verify-tag",
+  ].join("\n");
+  const answer = `Run this to cut the release:\n\n\`\`\`bash\n${command}\n\`\`\`\n\nThen watch the workflow.`;
+
+  const parts = splitParts(answer);
+
+  assert.equal(parts[0]!.kind, "code");
+  assert.equal(parts[0]!.text, command);
+  assert.match(parts[0]!.label, /bash/);
+  assert.match(parts[0]!.label, /gh release create pi-copy-v0\.1\.0/);
+});
+
+test("a code block inside a list item is a part copied without the list indent", () => {
+  const answer = [
+    "Two steps:",
+    "",
+    "1. Build the tarball:",
+    "",
+    "   ```sh",
+    "   npm pack --workspace packages/pi-copy",
+    "   ls *.tgz",
+    "   ```",
+    "",
+    "2. Publish it.",
+  ].join("\n");
+
+  const code = splitParts(answer).filter((p) => p.kind === "code");
+
+  assert.equal(code.length, 1);
+  assert.equal(code[0]!.text, "npm pack --workspace packages/pi-copy\nls *.tgz");
+});
+
+test("a paragraph written across several source lines becomes one line", () => {
+  const answer = [
+    "Hi Dana,",
+    "",
+    "Thanks for sending the deck over. I went through it",
+    "last night and the pricing section reads well,",
+    "though slide 7 could lose a bullet.",
+    "",
+    "Can we talk Thursday?",
+  ].join("\n");
+
+  assert.equal(
+    prose(answer),
+    "Hi Dana,\n\nThanks for sending the deck over. I went through it last night and the pricing section reads well, though slide 7 could lose a bullet.\n\nCan we talk Thursday?",
+  );
+});
+
+test("bold, italic, inline code and strike marks are removed", () => {
+  const answer = "The **release** is _ready_: run `npm pack` ~~twice~~ once.";
+
+  assert.equal(prose(answer), "The release is ready: run npm pack twice once.");
+});
+
+test("a link becomes its text and address, a bare URL just the address", () => {
+  const answer = "See [the deck](https://x.io/d) or https://x.io/notes for detail.";
+
+  assert.equal(prose(answer), "See the deck (https://x.io/d) or https://x.io/notes for detail.");
+});
+
+test("a heading becomes its text on a line of its own", () => {
+  const answer = "## Next steps\n\nShip it on Friday.";
+
+  assert.equal(prose(answer), "Next steps\n\nShip it on Friday.");
+});
+
+test("nested ordered and unordered lists keep markers, two spaces per level", () => {
+  const answer = [
+    "1. Prepare the release",
+    "   - bump the **version**",
+    "   - update the changelog",
+    "2. Tag it",
+  ].join("\n");
+
+  assert.equal(
+    prose(answer),
+    "1. Prepare the release\n  - bump the version\n  - update the changelog\n2. Tag it",
+  );
+});
+
+test("a blockquote becomes its text without the > mark", () => {
+  const answer = "> Ship the smallest correct change.\n> Then stop.";
+
+  assert.equal(prose(answer), "Ship the smallest correct change. Then stop.");
+});
+
+test("a table keeps its markdown source rows", () => {
+  const table = "| Package | Status |\n|---|---|\n| pi-copy | new |";
+  const answer = `Where things stand:\n\n${table}`;
+
+  assert.equal(prose(answer), `Where things stand:\n\n${table}`);
+});
+
+test("an answer with only prose has the prose part alone", () => {
+  const parts = splitParts("Hi Dana,\n\nThe deck looks good.\n\nCourt");
+
+  assert.deepEqual(
+    parts.map((p) => p.kind),
+    ["prose"],
+  );
+});
+
+test("an answer with only a code block has only the block", () => {
+  const parts = splitParts("```bash\nnpm publish --access public\n```");
+
+  assert.deepEqual(
+    parts.map((p) => p.kind),
+    ["code"],
+  );
+  assert.equal(parts[0]!.text, "npm publish --access public");
+});
+
+test("a blank line before the closing fence leaves no trailing newline", () => {
+  const answer = "Run:\n\n```sh\necho ready\n\n```";
+
+  const parts = splitParts(answer);
+
+  assert.equal(parts[0]!.text, "echo ready");
+  assert.equal(parts[2]!.text, "Run:\n\necho ready");
+});
+
+test("parts come in order: each code block, then prose, then all with code in place", () => {
+  const answer = "First:\n\n```sh\nnpm ci\n```\n\nThen **test**:\n\n```sh\nnpm test\n```";
+
+  const parts = splitParts(answer);
+
+  assert.deepEqual(
+    parts.map((p) => p.kind),
+    ["code", "code", "prose", "all"],
+  );
+  assert.equal(parts[2]!.text, "First:\n\nThen test:");
+  assert.equal(parts[3]!.text, "First:\n\nnpm ci\n\nThen test:\n\nnpm test");
+});
+
+test("notice names a one-line part and its size", () => {
+  const text = "x".repeat(148);
+  const [part] = splitParts("```\n" + text + "\n```");
+
+  assert.equal(notice(part!), "Copied code block (1 line, 148 chars)");
+});
+
+test("notice counts lines of a multi-line part", () => {
+  const parts = splitParts("Hello there.\n\nSecond paragraph.");
+
+  assert.equal(notice(parts[0]!), "Copied prose (3 lines, 31 chars)");
+});

package/src/parts.ts

@@ -0,0 +1,147 @@
+// pi-copy parts — split an answer's markdown source into the parts the picker
+// offers, and turn each into the text it copies.
+//
+// Parsing uses marked's lexer (the parser pi draws messages with), so a code
+// block is found wherever pi would draw one, inside a list item included, and
+// its text is marked's: fences and indent removed, no trailing newline.
+// Prose is rendered to plain text here: one line per paragraph, inline marks
+// dropped, links as `text (url)`, list markers kept, tables as source rows.
+
+import { Lexer, type Token, type Tokens } from "marked";
+
+export type Part = { kind: "code" | "prose" | "all"; label: string; text: string };
+
+const PREVIEW = 60;
+
+function preview(text: string): string {
+  const first = text.split("\n").find((line) => line.trim() !== "") ?? "";
+  const line = first.trim();
+  return line.length > PREVIEW ? `${line.slice(0, PREVIEW - 1)}…` : line;
+}
+
+// Every code block, in source order, wherever it sits (lists, blockquotes).
+function codeBlocks(tokens: Token[], out: Tokens.Code[] = []): Tokens.Code[] {
+  for (const token of tokens) {
+    if (token.type === "code") out.push(token as Tokens.Code);
+    else if (token.type === "list") for (const item of (token as Tokens.List).items) codeBlocks(item.tokens, out);
+    else if ("tokens" in token && Array.isArray(token.tokens)) codeBlocks(token.tokens, out);
+  }
+  return out;
+}
+
+// A code block's exact text, without the trailing newlines a blank line before the fence leaves.
+function codeText(code: Tokens.Code): string {
+  return code.text.replace(/\n+$/, "");
+}
+
+function inline(tokens: Token[] | undefined): string {
+  if (!tokens) return "";
+  return tokens.map(inlineToken).join("");
+}
+
+function inlineToken(token: Token): string {
+  switch (token.type) {
+    case "strong":
+    case "em":
+    case "del":
+      return inline((token as Tokens.Strong).tokens);
+    case "codespan":
+      return (token as Tokens.Codespan).text;
+    case "link":
+    case "image": {
+      const link = token as Tokens.Link;
+      const text = link.tokens ? inline(link.tokens) : link.text;
+      return text === link.href || text === "" ? link.href : `${text} (${link.href})`;
+    }
+    case "br":
+      return "\n";
+    case "text": {
+      const text = token as Tokens.Text;
+      return text.tokens ? inline(text.tokens) : text.text;
+    }
+    default:
+      return "text" in token && typeof token.text === "string" ? token.text : token.raw;
+  }
+}
+
+// A paragraph's soft and hard line breaks become spaces: one line each.
+function oneLine(text: string): string {
+  return text.replace(/[ \t]*\n[ \t]*/g, " ").trim();
+}
+
+// Blocks to plain text; withCode puts each code block's text in place.
+function blocks(tokens: Token[], withCode: boolean): string[] {
+  const out: string[] = [];
+  for (const token of tokens) {
+    switch (token.type) {
+      case "paragraph":
+      case "heading":
+      case "text":
+        out.push(oneLine(inline((token as Tokens.Paragraph).tokens)));
+        break;
+      case "code":
+        if (withCode) out.push(codeText(token as Tokens.Code));
+        break;
+      case "list":
+        out.push(list(token as Tokens.List, 0, withCode).join("\n"));
+        break;
+      case "blockquote":
+        out.push(...blocks((token as Tokens.Blockquote).tokens, withCode));
+        break;
+      case "table":
+        out.push(token.raw.trimEnd());
+        break;
+      case "html":
+        out.push(token.raw.trim());
+        break;
+      default:
+        // space, hr, def: nothing to copy
+        break;
+    }
+  }
+  return out.filter((block) => block !== "");
+}
+
+function list(token: Tokens.List, depth: number, withCode: boolean): string[] {
+  const indent = "  ".repeat(depth);
+  const start = typeof token.start === "number" ? token.start : 1;
+  const lines: string[] = [];
+  token.items.forEach((item, index) => {
+    const marker = token.ordered ? `${start + index}. ` : "- ";
+    let first = true;
+    for (const child of item.tokens) {
+      if (child.type === "list") {
+        lines.push(...list(child as Tokens.List, depth + 1, withCode));
+        continue;
+      }
+      for (const block of blocks([child], withCode)) {
+        // A code block keeps its own text: no marker, no indent.
+        if (child.type === "code") lines.push(block);
+        else lines.push(first ? `${indent}${marker}${block}` : `${indent}  ${block}`);
+        if (child.type !== "code") first = false;
+      }
+    }
+  });
+  return lines;
+}
+
+export function splitParts(markdown: string): Part[] {
+  const tokens = new Lexer().lex(markdown);
+  const parts: Part[] = codeBlocks(tokens).map((code, index) => ({
+    kind: "code",
+    label: `Code block ${index + 1}${code.lang ? ` (${code.lang})` : ""}: ${preview(code.text)}`,
+    text: codeText(code),
+  }));
+  const prose = blocks(tokens, false).join("\n\n");
+  if (prose === "") return parts;
+  parts.push({ kind: "prose", label: `Prose: ${preview(prose)}`, text: prose });
+  if (parts.length > 1) parts.push({ kind: "all", label: "All of the answer", text: blocks(tokens, true).join("\n\n") });
+  return parts;
+}
+
+const NOUN: Record<Part["kind"], string> = { code: "code block", prose: "prose", all: "the whole answer" };
+
+export function notice(part: Part): string {
+  const lines = part.text.split("\n").length;
+  return `Copied ${NOUN[part.kind]} (${lines} ${lines === 1 ? "line" : "lines"}, ${part.text.length} chars)`;
+}