@signalridge/pi-welcome 0.1.0 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 1.0.0
+### Major Changes
+
+- Adopt a unified 1.0.0 across every published package.
+  
+  The version numbers no longer track their upstream forks individually; from this release each package
+  is versioned on its own merit against the Signalridge line, and 1.0.0 is the shared starting point.
+  Packages whose behavior changed in this release document that change in their own changeset entries;
+  the remainder are re-released unchanged so the whole set shares one baseline.
+
+### Patch Changes
+
+- Neutralize terminal control sequences and bidirectional overrides in the last three surfaces that rendered untrusted text raw: the recap the model writes from tool output, the workspace facts on the startup card, and the directory name written into the terminal title as an OSC escape sequence. The recap also sanitizes transcript text before it truncates it, so a cut can never hand the model half of an escape sequence.
+
 ## Unreleased
 
 - Moved the Pi startup card into the independently publishable Signalridge package.

package/README.md

@@ -1,6 +1,68 @@
 # pi-welcome
 
-TUI-only Signalridge startup card showing Pi's current repository, model, budget, and tools. It uses the active Pi theme, keeps the native resource listing intact, and persists a bounded custom entry. The rounded card collapses to a width-safe compact summary on narrow terminals.
+TUI-only Signalridge startup card: one rounded panel with the current
+repository, model, context budget, key hints, and a count of what Pi loaded. It
+uses the active Pi theme, persists a bounded custom entry so a resumed session
+redraws it, and collapses to a width-safe compact summary on narrow terminals.
+
+```
+╭──────────────────────────────────────────────────────────────────────╮
+│                                                                      │
+│  ╭─╮  SIGNALRIDGE / PI                                       v0.84.1 │
+│  ╰─╯  A focused coding workspace                                     │
+│                                                                      │
+│  Ctrl+C interrupt · / commands · ! bash · Ctrl+L clear               │
+│                                                                      │
+│  Directory: ~/ghq/github.com/signalridge/pi-extensions               │
+│  Branch:    main [+392 -202]                                         │
+│  Session:   (new)                                                    │
+│  Model:     openai-codex / gpt-5.6-luna · thinking max               │
+│  Budget:    400K · compacts at 270K                                  │
+│                                                                      │
+│  Context:   AGENTS.md · CLAUDE.md                                    │
+│  Loaded:    61 skills · 12 prompts · 9 commands from extensions      │
+│  Tools:     18 active of 42                                          │
+│                                                                      │
+╰──────────────────────────────────────────────────────────────────────╯
+```
+
+## Turn on `quietStartup`
+
+The card is designed to be the whole opening screen. Pi's own startup is a
+separate header, key-hint block, and one `[Section]` per resource kind with a
+blank line between each; leaving both on shows two unrelated designs and about
+forty-five lines of them. Set:
+
+```json
+{ "quietStartup": true }
+```
+
+in `~/.pi/agent/settings.json` (or `/settings` → Quiet startup). Pi then prints
+nothing at startup and this card stands alone. Diagnostics — resource
+collisions, extension load errors — are still shown when quiet, so nothing
+actionable is hidden.
+
+Leaving `quietStartup: false` is supported and changes nothing about the card;
+Pi simply prints its own block above it again.
+
+## What the counts come from
+
+`Context`, `Loaded`, and `Tools` are counted through Pi's public API only:
+`loadProjectContextFiles` and `loadSkills` are pure filesystem reads, and
+`getCommands()` / `getAllTools()` report what is actually registered. Pi renders
+its full `[Skills]` / `[Prompts]` / `[Extensions]` listing from a resource
+loader it does not expose read-only, and the only way to obtain a second one is
+to construct it — whose `reload()` re-executes every extension factory and would
+duplicate tools, listeners, timers, and child processes. So the card reports
+counts it can derive honestly and leaves out what it cannot.
+
+## Untrusted text
+
+A directory name, a git branch name, and a session name are all
+attacker-controlled in a cloned repository, and the card is a persisted entry
+replayed on every resume. Control characters and bidirectional overrides are
+neutralized at render time, so an entry stored before that landed is cleaned up
+on the way out too.
 
 ## Install
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signalridge/pi-welcome",
-  "version": "0.1.0",
+  "version": "1.2.0",
   "description": "Startup resource and repository summary card for Pi.",
   "type": "module",
   "license": "MIT",

package/src/index.ts

@@ -5,9 +5,13 @@
  * active Pi theme and semantic labels instead of a second palette or a bundled
  * font, so it stays legible in both dark and light terminals.
  *
- * It adds to Pi's native startup rather than replacing it. `quietStartup` must
- * stay false: Pi owns the key hints and loaded-resource listing, while this
- * card carries only workspace facts that are useful at a glance.
+ * It is meant to be the ONLY thing a session opens with. Pi's own startup is a
+ * header, a key-hint block, and one `[Section]` per resource kind with a blank
+ * line between each; stacking this card underneath produced two unrelated
+ * designs and about forty-five lines of them. So the card carries the pieces
+ * worth keeping — the key hints and a count of what loaded — and `quietStartup`
+ * is turned on in settings to silence the rest. With `quietStartup: false` Pi
+ * still prints its own block and the two appear together again.
  *
  * The card is a custom entry, not a widget: it lands in the transcript, scrolls
  * away as the conversation grows, and survives a reload. Facts are captured at
@@ -18,12 +22,15 @@
 import { execFileSync } from "node:child_process";
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 
 import {
   type ExtensionAPI,
   type ExtensionContext,
   getAgentDir,
+  keyText,
+  loadProjectContextFiles,
+  loadSkills,
   type Theme,
   VERSION,
 } from "@earendil-works/pi-coding-agent";
@@ -42,11 +49,21 @@ const PAD = 2;
 /** Below this width, use a compact no-border layout rather than overflow. */
 const MIN_WIDTH = 20;
 
-/** Sentinel row rendered as a blank line, separating the card's two groups. */
+/** Sentinel row rendered as a blank line, separating the card's groups. */
 const GAP: [string, string] = ["", ""];
 
+/** Most context-file names to spell out before collapsing the rest into a count. */
+const MAX_CONTEXT_NAMES = 3;
+
 interface WelcomeData {
   rows: [string, string][];
+  /**
+   * Key hints, most useful first. Kept as separate items rather than one joined
+   * string so a narrow card can drop the trailing ones instead of wrapping a
+   * separator onto a line of its own. Optional because an entry written before
+   * this field existed replays without any.
+   */
+  hints?: string[];
 }
 
 // ─── Fact Collection ───────────────────────────────────────────────────────────
@@ -111,6 +128,108 @@ function formatTokens(n: number): string {
   return String(n);
 }
 
+function plural(count: number, noun: string): string {
+  return `${count} ${noun}${count === 1 ? "" : "s"}`;
+}
+
+/**
+ * `ctrl+c` as `Ctrl+C`: key names read as proper nouns, the words after them
+ * stay lowercase. Pi capitalizes the same way internally but does not export
+ * the helper, so this repeats the one rule rather than reaching past the
+ * package's public surface.
+ */
+function capitalizeKey(key: string): string {
+  return key.replace(/[^+/]+/gu, (part) => part.charAt(0).toUpperCase() + part.slice(1));
+}
+
+/**
+ * The key hints Pi's own header would have shown, as plain text.
+ *
+ * Read from the live keybindings rather than hard-coded, so a rebound key is
+ * still described correctly. Deliberately not built with pi's `keyHint()`: that
+ * colors through pi's own theme singleton, while this card renders with the
+ * theme handed to its entry renderer, and the two would disagree after a theme
+ * change. The whole line is dimmed by the renderer instead of highlighting
+ * individual keys.
+ */
+export function collectHints(): string[] {
+  try {
+    // Ordered most useful first: a narrow card keeps the head of this list.
+    return [
+      [capitalizeKey(keyText("app.interrupt")), "interrupt"],
+      ["/", "commands"],
+      ["!", "bash"],
+      [capitalizeKey(keyText("app.clear")), "clear"],
+      [capitalizeKey(keyText("app.tools.expand")), "expand tools"],
+    ]
+      .filter(([key]) => key && key.length > 0)
+      .map(([key, description]) => `${key} ${description}`);
+  } catch {
+    // Keybindings are a TUI singleton; if it is not up yet, a card without a
+    // hint line is better than no card.
+    return [];
+  }
+}
+
+/**
+ * What pi loaded for this session, as counts rather than a listing.
+ *
+ * Pi renders the full `[Skills]`/`[Prompts]`/`[Extensions]` listing itself and
+ * exposes no read-only API for it — the loader that holds it can only be
+ * obtained by constructing a second one, whose `reload()` executes every
+ * extension factory again and would duplicate tools, listeners, timers, and
+ * child processes. So this counts through the public surfaces only:
+ * `loadSkills` and `loadProjectContextFiles` are pure filesystem reads that
+ * execute nothing, and `getCommands()` reports what is actually registered.
+ * Anything not derivable that way is left off rather than guessed at.
+ */
+export function collectResources(pi: ExtensionAPI, cwd: string): [string, string][] {
+  const rows: [string, string][] = [];
+
+  const contextNames = (() => {
+    try {
+      const files = loadProjectContextFiles({ cwd, agentDir: getAgentDir() });
+      // Several scopes can contribute the same filename (a project AGENTS.md
+      // and a global one); the card is naming kinds of context, not paths.
+      const names = [...new Set(files.map((file) => basename(file.path)))];
+      if (names.length === 0) return undefined;
+      const shown = names.slice(0, MAX_CONTEXT_NAMES).join(" · ");
+      const rest = names.length - MAX_CONTEXT_NAMES;
+      return rest > 0 ? `${shown} · +${rest}` : shown;
+    } catch {
+      return undefined;
+    }
+  })();
+  if (contextNames) rows.push(["Context", contextNames]);
+
+  const loaded: string[] = [];
+  try {
+    const { skills } = loadSkills({
+      cwd,
+      agentDir: getAgentDir(),
+      skillPaths: [],
+      includeDefaults: true,
+    });
+    if (skills.length > 0) loaded.push(plural(skills.length, "skill"));
+  } catch {}
+  try {
+    const commands = pi.getCommands?.() ?? [];
+    const prompts = commands.filter((command) => command.source === "prompt").length;
+    const extensionCommands = commands.filter((command) => command.source === "extension").length;
+    if (prompts > 0) loaded.push(plural(prompts, "prompt"));
+    if (extensionCommands > 0) loaded.push(`${plural(extensionCommands, "command")} from extensions`);
+  } catch {}
+  if (loaded.length > 0) rows.push(["Loaded", loaded.join(" · ")]);
+
+  try {
+    const all = pi.getAllTools?.() ?? [];
+    const active = pi.getActiveTools?.() ?? [];
+    if (all.length) rows.push(["Tools", `${active.length} active of ${all.length}`]);
+  } catch {}
+
+  return rows;
+}
+
 function collect(pi: ExtensionAPI, ctx: ExtensionContext): WelcomeData {
   const rows: [string, string][] = [];
   const push = (label: string, value: string | undefined) => {
@@ -127,9 +246,9 @@ function collect(pi: ExtensionAPI, ctx: ExtensionContext): WelcomeData {
   push("Directory", tildify(ctx.cwd) + trusted);
   push("Branch", gitSummary(ctx.cwd));
 
-  // Only a NAME is worth a row. The raw session id is a timestamp glued to a
-  // uuid; it is unreadable, identical in shape every time, and pushes the
-  // Keep the fresh-session label short; raw session ids add noise without helping orientation.
+  // Keep the fresh-session label short; raw session ids add noise without
+  // helping orientation — they are a timestamp glued to a uuid, identical in
+  // shape every time.
   push("Session", pi.getSessionName?.() || "(new)");
 
   const model = ctx.model;
@@ -152,36 +271,79 @@ function collect(pi: ExtensionAPI, ctx: ExtensionContext): WelcomeData {
     }
   }
 
-  try {
-    const all = pi.getAllTools?.() ?? [];
-    const active = pi.getActiveTools?.() ?? [];
-    if (all.length) {
-      push("Tools", `${active.length} active of ${all.length}`);
-    }
-  } catch {}
+  // GAP is the sentinel for a blank row: session facts above, what pi loaded
+  // below, so the card reads as two groups rather than one wall.
+  const resources = collectResources(pi, ctx.cwd);
+  if (resources.length > 0) rows.push(GAP, ...resources);
 
-  push("Version", VERSION);
-  return { rows };
+  const hints = collectHints();
+  return hints.length > 0 ? { rows, hints } : { rows };
 }
 
+// ─── Card Component ────────────────────────────────────────────────────────────
+
 /**
- * Pi 0.84.1 does not expose the already-active resource loader through the
- * public ExtensionContext/ExtensionAPI types. Do not construct a second
- * DefaultResourceLoader here: reload() executes arbitrary extension factories
- * and can duplicate tools, listeners, timers, and external processes. Pi owns
- * the startup resource listing, so this extension intentionally omits it until
- * a public non-executing API exists.
+ * Card facts come from a directory name, a git branch name and a session name.
+ * All three are attacker-controlled in a cloned repository, and the card is a
+ * persisted entry, so a poisoned fact is replayed on every resume. Neutralize
+ * C0/C1 controls and bidi overrides here, at the terminal boundary, so a stored
+ * entry written before this landed is cleaned up on the way out too.
+ *
+ * Duplicated rather than shared, per the package boundary rule; `pi-stamp`'s
+ * metadata sanitizer is the reference shape.
  */
-export function collectResources(_cwd: string): Promise<[string, string][]> {
-  return Promise.resolve([]);
+export function sanitizeCardText(value: string): string {
+  let safe = "";
+  for (const character of value) {
+    safe += isUnsafeTerminalCodePoint(character.codePointAt(0) ?? 0) ? " " : character;
+  }
+  return safe.replace(/\s+/gu, " ").trim();
+}
+
+function isUnsafeTerminalCodePoint(codePoint: number): boolean {
+  return (
+    codePoint <= 0x1f ||
+    (codePoint >= 0x7f && codePoint <= 0x9f) ||
+    codePoint === 0x061c ||
+    codePoint === 0x200e ||
+    codePoint === 0x200f ||
+    (codePoint >= 0x202a && codePoint <= 0x202e) ||
+    (codePoint >= 0x2066 && codePoint <= 0x2069)
+  );
+}
+
+/**
+ * Join as many hints as fit on one line, dropping from the end.
+ *
+ * Wrapping would put a leading `·` at the start of the continuation, which
+ * reads as a bullet for the line below it rather than a separator. Losing the
+ * last hint costs less than that, and the list is ordered so the ones worth
+ * keeping come first.
+ */
+export function fitHints(hints: readonly string[], width: number): string | undefined {
+  for (let count = hints.length; count > 0; count--) {
+    const line = hints.slice(0, count).join(" · ");
+    if (visibleWidth(line) <= width) return line;
+  }
+  return undefined;
 }
-// ─── Card Component ────────────────────────────────────────────────────────────
 
 export class WelcomeCard implements Component {
+  private readonly rows: [string, string][];
+  private readonly hints: string[];
+
   constructor(
-    private readonly data: WelcomeData,
+    data: WelcomeData,
     private readonly theme: Theme,
-  ) {}
+  ) {
+    this.rows = data.rows.map(([label, value]) => [sanitizeCardText(label), sanitizeCardText(value)]);
+    // The entry is replayed from a session file on disk, which an older build
+    // (or a hand edit) may have written with a different shape for this field.
+    this.hints = (Array.isArray(data.hints) ? data.hints : [])
+      .filter((hint): hint is string => typeof hint === "string")
+      .map(sanitizeCardText)
+      .filter((hint) => hint.length > 0);
+  }
 
   /** Pad or truncate a (possibly styled) string to exactly `width` columns. */
   private fit(text: string, width: number): string {
@@ -195,8 +357,8 @@ export class WelcomeCard implements Component {
     const t = this.theme;
     const lines = [
       t.bold(t.fg("accent", "sr / pi")),
-      t.fg("muted", "ready"),
-      ...this.data.rows.map(([label, value]) =>
+      t.fg("muted", this.hints.length > 0 ? (this.hints[0] ?? "ready") : "ready"),
+      ...this.rows.map(([label, value]) =>
         label === GAP[0] && value === GAP[1] ? "" : `${t.fg("dim", `${label}:`)} ${t.fg("text", value)}`,
       ),
     ];
@@ -216,16 +378,30 @@ export class WelcomeCard implements Component {
     const body: string[] = [blank()];
     const logoWidth = Math.max(...LOGO.map(visibleWidth));
 
+    // The version rides the brand line rather than taking a row of its own: it
+    // is the one fact nobody scans for, and the row it used to occupy sat at
+    // the bottom where the eye lands last.
+    const version = t.fg("dim", `v${VERSION}`);
+    const brandRoom = Math.max(0, inner - PAD - logoWidth - PAD - PAD - visibleWidth(version));
+    const brand = t.bold(t.fg("text", BRAND));
+    const brandLine = brand + " ".repeat(Math.max(1, brandRoom - visibleWidth(BRAND) + 1)) + version;
+
     body.push(
-      line(pad + t.fg("accent", LOGO[0].padEnd(logoWidth)) + pad + t.bold(t.fg("text", BRAND))),
+      line(pad + t.fg("accent", LOGO[0].padEnd(logoWidth)) + pad + brandLine),
       line(pad + t.fg("accent", LOGO[1].padEnd(logoWidth)) + pad + t.fg("muted", SUBTITLE)),
-      blank(),
     );
 
-    const labelWidth = this.data.rows.length
-      ? Math.max(...this.data.rows.map(([label]) => visibleWidth(label))) + 2
-      : 0;
-    for (const [label, value] of this.data.rows) {
+    const hintLine = fitHints(this.hints, Math.max(1, inner - PAD * 2));
+    if (hintLine) {
+      // The whole line is dimmed rather than highlighting each key: this is
+      // orientation, not a control the user is meant to look at.
+      body.push(blank(), line(pad + t.fg("dim", hintLine)));
+    }
+
+    body.push(blank());
+
+    const labelWidth = this.rows.length ? Math.max(...this.rows.map(([label]) => visibleWidth(label))) + 2 : 0;
+    for (const [label, value] of this.rows) {
       if (label === GAP[0] && value === GAP[1]) {
         body.push(blank());
         continue;
@@ -271,14 +447,7 @@ export default function (pi: ExtensionAPI) {
     } catch {}
 
     try {
-      const data = collect(pi, ctx);
-      const resources = await collectResources(ctx.cwd);
-      if (resources.length) {
-        // GAP is the sentinel for a blank row: session facts above, what pi
-        // loaded below, so the card reads as two groups rather than one wall.
-        data.rows.push(GAP, ...resources);
-      }
-      pi.appendEntry<WelcomeData>(ENTRY_TYPE, data);
+      pi.appendEntry<WelcomeData>(ENTRY_TYPE, collect(pi, ctx));
     } catch {
       // A missing card is not worth failing a session start over.
     }