pi-note 0.5.1 → 0.6.0

package/README.md

@@ -100,17 +100,23 @@ user asks to switch. Reuse a saved tag name when it fits.
 
 Agents are guided to keep notes to three short bullets total: relevant outcome,
 blocker, and next action. Replace stale notes; omit narration, repeated task text,
-and routine test logs. Keep PR links in `PR`. This is guidance, not truncation or
-a storage limit.
+and routine test logs. Keep a GitHub pull request in `PR`. To show another footer
+field, set its Markdown value and append its label to `Bar`, one label per line.
+Do not list `PR` in `Bar`. Remove the field and its `Bar` line to drop it. This is
+guidance, not truncation or a storage limit.
 
-Values are Markdown strings; no fields are required. `PR` enables the watcher below:
+Values are Markdown strings; no fields are required. `PR` enables the watcher below.
+`Bar` chooses extra footer fields:
 
 ```markdown
 # Agent
 PR: [Task selection #42](https://github.com/org/repo/pull/42)
+Dashboard: [Metrics](http://127.0.0.1:3000/d/app)
+Next: Address review comments
+Bar: Dashboard
+Next
 Jira: [PROJ-123](https://example.atlassian.net/browse/PROJ-123)
 CWD: `/home/me/project`
-Next: Address review comments
 ```
 
 The GTK preview renders this section using its existing safe Markdown renderer.
@@ -119,12 +125,26 @@ sessions. Labels are case-sensitive (trimmed, Unicode-normalized), at most 64
 characters; values are at most 4096 characters. Maximum 64 fields / 32 KiB JSON
 per task. Use removal rather than empty values.
 
+### Footer links
+
+The selected active or in-progress task can show fields after its title.
+`PR` is always shown when it matches the watcher format below, as **PR #123**.
+`Bar` is a newline-separated list of other field labels. Each listed value is
+Markdown: the footer shows its text, and links in it are clickable for any scheme
+except `javascript:`, `data:`, and `vbscript:`. Credentials, control characters,
+and targets over 2048 characters after serialization are shown as text but not
+linked. Missing labels and the `PR` and `Bar` labels themselves are skipped.
+At most four extra fields are shown, each truncated to 60 columns. Removing a listed
+field hides it even if `Bar` still names it. Terminal OSC 8 support is required
+for clicking links. Pi joins footer statuses on one line, so a narrow terminal can
+ellipsize later fields. Other fields, such as `Jira` and `CWD` in the example, stay
+off the footer unless named in `Bar`.
+
 ### PR merge watcher
 
 Set `PR` with `pinote_update` to one `https://github.com/owner/repo/pull/123` URL
 or Markdown link. The footer adds a clickable, link-coloured **PR #123**, without
-status text. Other hosts, multiple links, and prose are not watched. Terminal
-OSC 8 support is required for clicking links.
+status text. Other hosts, multiple links, and prose are not watched.
 
 Interactive Pi checks only the selected task's PR using authenticated `gh`
 (`gh auth login`). Polling defaults to 60 seconds; launch Pi with
@@ -133,9 +153,12 @@ Allowed intervals are 10–86400 seconds. The selected task's link remains visib
 Network/authentication failures warn once until recovery and retry next interval.
 No polling runs in print/RPC mode or after Pi exits.
 
-On merge, Pi waits until idle and asks **Mark this task completed?** Confirmation
-uses the same guarded CLI Done operation as `/pi-note`; declining leaves the task
-unchanged. If it is already done, Pi says **PR #123 was merged and the task is
+On merge, Pi waits until idle and asks **Mark this task completed?** In Kitty,
+indeterminate progress animates the tab while the prompt awaits input (with Kitty's
+default progress-aware tab title or a working/ready renderer). Progress clears on
+response, cancellation, or shutdown; other terminals and redirected output are untouched.
+Confirmation uses the same guarded CLI Done operation as `/pi-note`; declining leaves
+the task unchanged. If it is already done, Pi says **PR #123 was merged and the task is
 already completed**, without completing it again. Completion clears the selection
 and hides the footer link, even with polling disabled. The background watch remains
 until another task is selected, the link is removed, or Pi exits. Removed/scheduled tasks are no longer watched.

package/footer-links.ts

@@ -0,0 +1,222 @@
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { stripVTControlCharacters } from "node:util";
+
+export const footerStatusKey = "pinote-links";
+export const legacyFooterStatusKey = "pinote-pr";
+const maxCustomChips = 4;
+const maxLabelWidth = 24;
+const maxChipWidth = 60;
+const maxUrlLength = 2048;
+const blockedProtocols = new Set(["javascript:", "data:", "vbscript:"]);
+const control = /[\u0000-\u001f\u007f-\u009f]/u;
+
+export type FooterSegment = { text: string; url?: string };
+export type FooterChip = { segments: FooterSegment[] };
+
+function display(value: string): string {
+  // Keep whitespace so newlines stay word boundaries. Drop other C0/C1 controls;
+  // U+009D survives stripVTControlCharacters and can start OSC.
+  return stripVTControlCharacters(value)
+    .replace(new RegExp(control, "gu"), (char) => /\s/u.test(char) ? " " : "")
+    .replace(/\s+/gu, " ");
+}
+
+function plain(value: string): string {
+  return display(value).trim();
+}
+
+function clip(value: string, width: number): string {
+  return stripVTControlCharacters(truncateToWidth(plain(value), width));
+}
+
+function ownText(notes: Record<string, string>, name: string): string | undefined {
+  if (!Object.hasOwn(notes, name)) return;
+  const value = notes[name];
+  return typeof value === "string" ? value : undefined;
+}
+
+// Any scheme except scriptable or credentialed targets. Reject terminal escapes and oversized serialization.
+function linkTarget(value: string): string | undefined {
+  // Do not trim or strip first: that can turn a dirty destination into a different URL.
+  if (!value || value.length > maxUrlLength || /[\s\\<>"`]/u.test(value) || control.test(value)) return;
+  const candidate = value;
+  let parsed: URL;
+  try {
+    parsed = new URL(candidate);
+  } catch {
+    return;
+  }
+  if (blockedProtocols.has(parsed.protocol) || parsed.username || parsed.password || !parsed.protocol) return;
+  if (parsed.href.length > maxUrlLength || /[\\<>"`]/u.test(parsed.href) || control.test(parsed.href)) return;
+  return parsed.href;
+}
+
+function pushText(segments: FooterSegment[], text: string) {
+  const cleaned = display(text).replace(/\*\*|__/gu, "");
+  if (!cleaned) return;
+  const last = segments.at(-1);
+  if (last && !last.url) last.text += cleaned;
+  else segments.push({ text: cleaned });
+}
+
+function readCode(source: string, index: number): { text: string; end: number } | undefined {
+  if (source[index] !== "`") return;
+  const end = source.indexOf("`", index + 1);
+  if (end < 0) return;
+  return { text: source.slice(index + 1, end), end: end + 1 };
+}
+
+function readDestination(source: string, start: number): { dest: string; end: number } | undefined {
+  if (source[start] === "<") {
+    const close = source.indexOf(">", start + 1);
+    if (close < 0) return;
+    return { dest: source.slice(start + 1, close), end: close + 1 };
+  }
+  let depth = 0;
+  let end = start;
+  for (; end < source.length; end++) {
+    const char = source[end];
+    if (char === "(") depth++;
+    else if (char === ")") {
+      if (depth === 0) break;
+      depth--;
+    }
+  }
+  if (end === start || depth !== 0) return;
+  return { dest: source.slice(start, end), end };
+}
+
+function readLink(source: string, index: number): { text: string; dest: string; end: number } | undefined {
+  let start = index;
+  if (source[start] === "!") start++;
+  if (source[start] !== "[") return;
+  const labelEnd = source.indexOf("]", start + 1);
+  if (labelEnd < 0 || source[labelEnd + 1] !== "(") return;
+  const dest = readDestination(source, labelEnd + 2);
+  if (!dest || source[dest.end] !== ")") return;
+  return { text: source.slice(start + 1, labelEnd), dest: dest.dest, end: dest.end + 1 };
+}
+
+function readAuto(source: string, index: number): { text: string; dest: string; end: number } | undefined {
+  if (source[index] !== "<") return;
+  const close = source.indexOf(">", index + 1);
+  if (close < 0) return;
+  const dest = source.slice(index + 1, close);
+  if (!/^[a-z][a-z0-9+.-]*:/iu.test(dest)) return;
+  return { text: dest, dest, end: close + 1 };
+}
+
+function readBare(source: string, index: number): { text: string; dest: string; end: number } | undefined {
+  if (index > 0 && /[A-Za-z0-9]/u.test(source[index - 1])) return;
+  const scheme = /^[a-z][a-z0-9+.-]*:\/\//iu.exec(source.slice(index));
+  if (!scheme) return;
+  let end = index + scheme[0].length;
+  let depth = 0;
+  for (; end < source.length; end++) {
+    const char = source[end];
+    if (/[\s<>\]*]/u.test(char) || control.test(char)) break;
+    if (char === "(") depth++;
+    else if (char === ")") {
+      if (depth === 0) break;
+      depth--;
+    }
+  }
+  const raw = source.slice(index, end).replace(/[.,;:!?]+$/u, "").replace(/__$/u, "");
+  if (!raw || depth !== 0) return;
+  return { text: raw, dest: raw, end: index + raw.length };
+}
+
+function emitLink(segments: FooterSegment[], label: string, dest: string) {
+  const text = plain(label).replace(/\*\*|__/gu, "") || plain(dest);
+  if (!text) return;
+  const url = linkTarget(dest);
+  segments.push(url ? { text, url } : { text });
+}
+
+export function renderMarkdown(value: string | undefined): FooterSegment[] {
+  const source = value ?? "";
+  if (!plain(source)) return [];
+  const segments: FooterSegment[] = [];
+  let text = "";
+  for (let index = 0; index < source.length;) {
+    const code = readCode(source, index);
+    const link = code ? undefined : readLink(source, index);
+    const auto = code || link ? undefined : readAuto(source, index);
+    const bare = code || link || auto ? undefined : readBare(source, index);
+    const token = link ?? auto ?? bare;
+    if (code) {
+      pushText(segments, text);
+      text = "";
+      pushText(segments, code.text);
+      index = code.end;
+    } else if (token) {
+      pushText(segments, text);
+      text = "";
+      emitLink(segments, token.text, token.dest);
+      index = token.end;
+    } else {
+      text += source[index];
+      index++;
+    }
+  }
+  pushText(segments, text);
+  if (segments[0] && !segments[0].url) segments[0].text = segments[0].text.trimStart();
+  const last = segments.at(-1);
+  if (last && !last.url) last.text = last.text.trimEnd();
+  return segments.filter((segment) => segment.text);
+}
+
+function truncateSegments(segments: readonly FooterSegment[], width: number): FooterSegment[] {
+  const kept: FooterSegment[] = [];
+  let used = 0;
+  for (const segment of segments) {
+    if (used >= width) break;
+    const room = width - used;
+    const text = visibleWidth(segment.text) <= room ? segment.text : clip(segment.text, room);
+    if (!text) break;
+    kept.push(segment.url ? { text, url: segment.url } : { text });
+    used += visibleWidth(text);
+  }
+  return kept;
+}
+
+export function customFooterChips(notes: Record<string, string> | undefined): FooterChip[] {
+  if (!notes) return [];
+  const chips: FooterChip[] = [];
+  const seen = new Set(["PR", "Bar"]);
+  for (const raw of (notes.Bar ?? "").split("\n")) {
+    if (chips.length >= maxCustomChips) break;
+    const name = raw.normalize("NFC").trim();
+    if (!name || seen.has(name)) continue;
+    seen.add(name);
+    const label = clip(name, maxLabelWidth);
+    const body = renderMarkdown(ownText(notes, name));
+    if (!label || !body.length) continue;
+    chips.push({ segments: truncateSegments([{ text: `${label}: ` }, ...body], maxChipWidth) });
+  }
+  return chips;
+}
+
+export function footerChips(
+  task: { state: string; agent_notes: Record<string, string> } | null,
+  pr: { url: string; number: string } | undefined,
+): FooterChip[] {
+  if (!task || !["active", "in_progress"].includes(task.state)) return [];
+  return [
+    ...(pr ? [{ segments: [{ text: `PR #${pr.number}`, url: pr.url }] }] : []),
+    ...customFooterChips(task.agent_notes),
+  ];
+}
+
+export function renderFooterLinks(
+  chips: readonly FooterChip[],
+  colorLink: (text: string) => string,
+): string | undefined {
+  const rendered = chips.flatMap((chip) => {
+    const text = chip.segments.map((segment) => segment.url
+      ? colorLink(`\x1b]8;;${segment.url}\x1b\\${segment.text}\x1b]8;;\x1b\\`)
+      : segment.text).join("");
+    return text.trim() ? [text] : [];
+  });
+  return rendered.length ? rendered.join(" · ") : undefined;
+}

package/index.ts

@@ -7,7 +7,7 @@ import { createPRWatcher } from "./pr-watch.ts";
 import { TaskPicker, taskState, taskTag } from "./task-picker.ts";
 import { bundledCLIVersion, cliMenu, detectCLI, setupCLI, setupHint, versionAtLeast, type CLIAction } from "./setup.ts";
 
-const handoffGuidance = "Keep agent notes to at most three short bullets total: outcome, blocker, next action, only when relevant. Replace stale notes; omit narration, repeated task text, and routine test logs. Keep PR links in the separate PR field.";
+const handoffGuidance = "Keep agent notes to at most three short bullets total: outcome, blocker, next action, only when relevant. Replace stale notes; omit narration, repeated task text, and routine test logs. Keep a GitHub pull request in the PR field. To show another footer field, set its Markdown value and append its label to Bar, one label per line. Links in that text are clickable. Do not list PR in Bar. Remove the field and its Bar line to drop it. Notes stay off the footer unless named in Bar.";
 const createGuidance = [
   "When the user gives work and no pinote task is selected, propose one note as `[tag] text` and ask before creating it. On no, continue without a note. On yes, call pinote_add with select true so it becomes this session's active task. Never add or select without a yes. If a task is already selected, do not replace it unless the user asks to switch.",
   "Reuse a pinote_tags name when it fits. One tag; case-sensitive, trimmed, at most 64 characters. pinote_tag changes an existing active or in-progress task after pinote_get; pass updated_at. Do not use pinote_update for tags or task text.",
@@ -378,7 +378,7 @@ export default function (pi: ExtensionAPI) {
     name: "pinote_update",
     label: "Pinote update",
     promptGuidelines: [handoffGuidance],
-    description: "Patch arbitrary agent handoff fields on an explicit pinote task. Read first with pinote_get; pass its updated_at as expected_updated_at. set merges label/value pairs without replacing other fields or task text; values are Markdown, e.g. PR: [Fix #42](https://github.com/org/repo/pull/42). Set PR to one GitHub pull-request URL or Markdown link to show it in the footer and watch for merge confirmation in interactive Pi. remove deletes named fields. A stale revision fails; read again before retrying. Does not complete the task or change its tag.",
+    description: "Patch arbitrary agent handoff fields on an explicit pinote task. Read first with pinote_get; pass its updated_at as expected_updated_at. set merges label/value pairs without replacing other fields or task text; values are Markdown, e.g. PR: [Fix #42](https://github.com/org/repo/pull/42). Set PR to one GitHub pull-request URL or Markdown link to show PR #N in the footer and watch for merge confirmation in interactive Pi. Set Bar to newline-separated field labels to show those Markdown fields in the footer; links in the text are clickable. remove deletes named fields. A stale revision fails; read again before retrying. Does not complete the task or change its tag.",
     parameters: Type.Object({
       id: idSchema,
       expected_updated_at: Type.String({ minLength: 1 }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-note",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Persistent pinote tasks, Markdown handoffs, and task status for Pi",
   "license": "MIT",
   "type": "module",
@@ -14,7 +14,7 @@
   "homepage": "https://github.com/kvidzibo/pinote/tree/main/pi#readme",
   "bugs": { "url": "https://github.com/kvidzibo/pinote/issues" },
   "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
-  "files": ["index.ts", "pr-watch.ts", "task-picker.ts", "setup.ts", "icons", "README.md", "LICENSE"],
+  "files": ["index.ts", "pr-watch.ts", "footer-links.ts", "task-picker.ts", "setup.ts", "icons", "README.md", "LICENSE"],
   "pi": { "extensions": ["./index.ts"] },
   "scripts": {
     "check": "tsc --noEmit",

package/pr-watch.ts

@@ -1,4 +1,5 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { footerChips, footerStatusKey, legacyFooterStatusKey, renderFooterLinks, type FooterChip } from "./footer-links.ts";
 
 export type WatchedTask = {
   id: number;
@@ -32,10 +33,35 @@ const watchKey = (task: WatchedTask | null) => {
   return task && pr ? keyFor(task, pr) : undefined;
 };
 
+async function confirmCompletion(ctx: ExtensionContext, pr: PR, signal: AbortSignal) {
+  let timer: ReturnType<typeof setInterval> | undefined;
+  const report = () => process.stdout.write("\x1b]9;4;3\x1b\\");
+  const stop = () => {
+    if (timer === undefined) return;
+    clearInterval(timer);
+    timer = undefined;
+    process.stdout.write("\x1b]9;4;0\x1b\\");
+  };
+  if (process.stdout.isTTY && process.env.KITTY_WINDOW_ID && !signal.aborted) {
+    report();
+    // Refresh Kitty's progress timeout and redraw the tab while input is pending.
+    timer = setInterval(report, 125);
+    timer.unref();
+    signal.addEventListener("abort", stop, { once: true });
+  }
+  try {
+    return await ctx.ui.confirm(`PR #${pr.number} was merged`, "Mark this task completed?", { signal });
+  } finally {
+    signal.removeEventListener("abort", stop);
+    stop();
+  }
+}
+
 export function createPRWatcher(pi: ExtensionAPI, deps: Dependencies) {
   let ctx: ExtensionContext | undefined;
   let watched: WatchedTask | null = null;
   let visiblePR: PR | undefined;
+  let visibleLinks: FooterChip[] = [];
   let timer: ReturnType<typeof setTimeout> | undefined;
   let controller = new AbortController();
   let generation = 0;
@@ -54,11 +80,13 @@ export function createPRWatcher(pi: ExtensionAPI, deps: Dependencies) {
     return changed;
   };
   const paint = () => {
-    if (!ctx) return;
-    const pr = visiblePR;
-    ctx.ui.setStatus("pinote-pr", pr
-      ? ctx.ui.theme.fg("mdLink", `\x1b]8;;${pr.url}\x1b\\PR #${pr.number}\x1b]8;;\x1b\\`)
-      : undefined);
+    const current = ctx;
+    if (!current) return;
+    // Clear the old key first so a reload cannot show PR twice.
+    current.ui.setStatus(legacyFooterStatusKey, undefined);
+    current.ui.setStatus(footerStatusKey, renderFooterLinks(
+      visibleLinks, (value) => current.ui.theme.fg("mdLink", value),
+    ));
   };
   const schedule = (delay = interval) => {
     if (!ctx || !interval || running) return;
@@ -71,6 +99,7 @@ export function createPRWatcher(pi: ExtensionAPI, deps: Dependencies) {
     revision++;
     // Display only the active selection, independently of the retained merge watch.
     visiblePR = current && ["active", "in_progress"].includes(current.state) ? taskPR(current) : undefined;
+    visibleLinks = footerChips(current, visiblePR);
     // Completion clears selection. Keep the last task until poll verifies its state.
     const changed = current ? remember(taskPR(current) ? current : null) : false;
     paint();
@@ -129,7 +158,7 @@ export function createPRWatcher(pi: ExtensionAPI, deps: Dependencies) {
         };
         if (current.state === "done") { alreadyDone(); return; }
         if (!["active", "in_progress"].includes(current.state)) return;
-        const confirmed = await context.ui.confirm(`PR #${pr.number} was merged`, "Mark this task completed?", { signal });
+        const confirmed = await confirmCompletion(context, pr, signal);
         if (!same() || !context.isIdle()) return;
         // Re-read selection, link, and revision after the dialog; never complete a changed task.
         const fresh = await latest(context, current);
@@ -192,10 +221,12 @@ export function createPRWatcher(pi: ExtensionAPI, deps: Dependencies) {
       controller.abort();
       controller = new AbortController();
       clearTimeout(timer);
-      ctx?.ui.setStatus("pinote-pr", undefined);
+      ctx?.ui.setStatus(legacyFooterStatusKey, undefined);
+      ctx?.ui.setStatus(footerStatusKey, undefined);
       ctx = undefined;
       watched = null;
       visiblePR = undefined;
+      visibleLinks = [];
       running = false;
       warned = false;
     },