@signalridge/pi-welcome 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## Unreleased
+
+- Moved the Pi startup card into the independently publishable Signalridge package.
+- Keep Pi's native resource listing enabled; the card no longer attempts to rebuild the private resource loader.
+- Refined the card with original Signalridge Ridgeline branding and a width-safe compact layout.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 signalridge
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,17 @@
+# 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.
+
+## Install
+
+```bash
+pi install npm:@signalridge/pi-welcome
+```
+
+## Use from this checkout
+
+From the repository root:
+
+```bash
+pi -e ./packages/pi-welcome
+```

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@signalridge/pi-welcome",
+  "version": "0.1.0",
+  "description": "Startup resource and repository summary card for Pi.",
+  "type": "module",
+  "license": "MIT",
+  "private": false,
+  "piExtension": {
+    "lifecycle": "stable"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/signalridge/pi-extensions",
+    "directory": "packages/pi-welcome"
+  },
+  "homepage": "https://github.com/signalridge/pi-extensions/tree/main/packages/pi-welcome",
+  "bugs": {
+    "url": "https://github.com/signalridge/pi-extensions/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "src"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "test": "bun test test",
+    "check": "bun run lint && bun run typecheck && bun run test",
+    "format": "biome check --write ."
+  }
+}

package/src/index.ts

@@ -0,0 +1,286 @@
+/**
+ * Signalridge startup card for Pi.
+ *
+ * The card is a compact, rounded summary of the current workspace. It uses the
+ * 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.
+ *
+ * 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
+ * session_start and stored in the entry, so a resumed session redraws the card
+ * as it was when that session began.
+ */
+
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import {
+  type ExtensionAPI,
+  type ExtensionContext,
+  getAgentDir,
+  type Theme,
+  VERSION,
+} from "@earendil-works/pi-coding-agent";
+import { type Component, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+
+const ENTRY_TYPE = "welcome-card";
+
+/** A small original ridgeline mark; no private-use or font-specific glyphs. */
+const LOGO = ["╭─╮", "╰─╯"] as const;
+const BRAND = "SIGNALRIDGE / PI";
+const SUBTITLE = "A focused coding workspace";
+
+/** Columns of padding inside the card. */
+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. */
+const GAP: [string, string] = ["", ""];
+
+interface WelcomeData {
+  rows: [string, string][];
+}
+
+// ─── Fact Collection ───────────────────────────────────────────────────────────
+
+function tildify(path: string): string {
+  const home = homedir();
+  return path === home || path.startsWith(`${home}/`) ? `~${path.slice(home.length)}` : path;
+}
+
+/** `main [+392 -202]`, or undefined outside a repo. Best-effort and never throws. */
+function gitSummary(cwd: string): string | undefined {
+  const git = (args: string[]): string | undefined => {
+    try {
+      return execFileSync("git", args, {
+        cwd,
+        encoding: "utf8",
+        timeout: 1000,
+        stdio: ["ignore", "pipe", "ignore"],
+      }).trim();
+    } catch {
+      return undefined;
+    }
+  };
+
+  const branch = git(["rev-parse", "--abbrev-ref", "HEAD"]);
+  if (!branch) return undefined;
+
+  // --numstat over HEAD covers staged + unstaged; untracked files are excluded
+  // on purpose, matching what `git diff` itself reports.
+  const numstat = git(["diff", "HEAD", "--numstat"]);
+  if (!numstat) return branch;
+
+  let added = 0;
+  let removed = 0;
+  for (const line of numstat.split("\n")) {
+    const [a, r] = line.split("\t");
+    // Binary files report "-" for both counts.
+    added += Number.parseInt(a ?? "", 10) || 0;
+    removed += Number.parseInt(r ?? "", 10) || 0;
+  }
+  return added || removed ? `${branch} [+${added} -${removed}]` : branch;
+}
+
+/**
+ * `compaction.reserveTokens` from settings.json. ExtensionContext does not carry
+ * settings, so this reads the same file pi does — the trigger point is worth the
+ * one stat() because it, not the raw window, is what a long session runs into.
+ */
+function readReserveTokens(): number | undefined {
+  try {
+    const raw = readFileSync(join(getAgentDir(), "settings.json"), "utf8");
+    const value = JSON.parse(raw)?.compaction?.reserveTokens;
+    return typeof value === "number" ? value : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function formatTokens(n: number): string {
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(n % 1_000_000 === 0 ? 0 : 1)}M`;
+  if (n >= 1_000) return `${Math.round(n / 1_000)}K`;
+  return String(n);
+}
+
+function collect(pi: ExtensionAPI, ctx: ExtensionContext): WelcomeData {
+  const rows: [string, string][] = [];
+  const push = (label: string, value: string | undefined) => {
+    if (value) rows.push([label, value]);
+  };
+
+  const trusted = (() => {
+    try {
+      return ctx.isProjectTrusted() ? "" : "  (untrusted)";
+    } catch {
+      return "";
+    }
+  })();
+  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.
+  push("Session", pi.getSessionName?.() || "(new)");
+
+  const model = ctx.model;
+  if (model) {
+    const id = model.id;
+    const provider = model.provider;
+    const thinking = ctx.thinkingLevel ? ` · thinking ${ctx.thinkingLevel}` : "";
+    push("Model", `${provider ? `${provider} / ` : ""}${id}${thinking}`);
+
+    const window = model.contextWindow;
+    if (typeof window === "number" && window > 0) {
+      // Pi compacts at contextWindow - reserveTokens; surfacing the trigger up
+      // front is the one number that actually governs a long session.
+      const reserve = readReserveTokens();
+      const trigger =
+        typeof reserve === "number" && reserve > 0 && reserve < window
+          ? ` · compacts at ${formatTokens(window - reserve)}`
+          : "";
+      push("Budget", `${formatTokens(window)}${trigger}`);
+    }
+  }
+
+  try {
+    const all = pi.getAllTools?.() ?? [];
+    const active = pi.getActiveTools?.() ?? [];
+    if (all.length) {
+      push("Tools", `${active.length} active of ${all.length}`);
+    }
+  } catch {}
+
+  push("Version", VERSION);
+  return { rows };
+}
+
+/**
+ * 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.
+ */
+export function collectResources(_cwd: string): Promise<[string, string][]> {
+  return Promise.resolve([]);
+}
+// ─── Card Component ────────────────────────────────────────────────────────────
+
+export class WelcomeCard implements Component {
+  constructor(
+    private readonly data: WelcomeData,
+    private readonly theme: Theme,
+  ) {}
+
+  /** Pad or truncate a (possibly styled) string to exactly `width` columns. */
+  private fit(text: string, width: number): string {
+    const safeWidth = Math.max(0, width);
+    const renderedWidth = visibleWidth(text);
+    if (renderedWidth > safeWidth) return truncateToWidth(text, safeWidth, "");
+    return text + " ".repeat(safeWidth - renderedWidth);
+  }
+
+  private renderCompact(width: number): string[] {
+    const t = this.theme;
+    const lines = [
+      t.bold(t.fg("accent", "sr / pi")),
+      t.fg("muted", "ready"),
+      ...this.data.rows.map(([label, value]) =>
+        label === GAP[0] && value === GAP[1] ? "" : `${t.fg("dim", `${label}:`)} ${t.fg("text", value)}`,
+      ),
+    ];
+    return lines.map((line) => truncateToWidth(line, Math.max(1, width), ""));
+  }
+
+  render(width: number): string[] {
+    const safeWidth = Math.max(1, width);
+    if (safeWidth < MIN_WIDTH) return this.renderCompact(safeWidth);
+
+    const t = this.theme;
+    const border = (text: string) => t.fg("border", text);
+    const inner = safeWidth - 2;
+    const line = (content: string) => border("│") + this.fit(content, inner) + border("│");
+    const blank = () => line("");
+    const pad = " ".repeat(PAD);
+    const body: string[] = [blank()];
+    const logoWidth = Math.max(...LOGO.map(visibleWidth));
+
+    body.push(
+      line(pad + t.fg("accent", LOGO[0].padEnd(logoWidth)) + pad + t.bold(t.fg("text", BRAND))),
+      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) {
+      if (label === GAP[0] && value === GAP[1]) {
+        body.push(blank());
+        continue;
+      }
+
+      const gutter = pad + `${label}:`.padEnd(labelWidth);
+      const room = Math.max(1, inner - visibleWidth(gutter) - PAD);
+      const [head, ...tail] = wrapTextWithAnsi(value, room);
+      body.push(line(t.fg("dim", gutter) + t.fg("text", head ?? "")));
+      for (const continuation of tail) {
+        body.push(line(" ".repeat(visibleWidth(gutter)) + t.fg("text", continuation)));
+      }
+    }
+
+    body.push(blank());
+    const rule = (left: string, right: string) => border(left + "─".repeat(inner) + right);
+    return [rule("╭", "╮"), ...body, rule("╰", "╯")];
+  }
+
+  invalidate(): void {}
+}
+
+// ─── Extension Entry ───────────────────────────────────────────────────────────
+
+export default function (pi: ExtensionAPI) {
+  pi.registerEntryRenderer<WelcomeData>(ENTRY_TYPE, (entry, _options, theme) => {
+    const data = entry.data;
+    if (!data?.rows?.length) return undefined;
+    return new WelcomeCard(data, theme);
+  });
+
+  pi.on("session_start", async (_event, ctx) => {
+    if (ctx.mode !== "tui") return;
+
+    // A resumed session already carries its card; appending on every
+    // session_start would stack a fresh one on top at each reload.
+    try {
+      for (const entry of ctx.sessionManager.getEntries()) {
+        if (entry.type === "custom" && entry.customType === ENTRY_TYPE) {
+          return;
+        }
+      }
+    } 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);
+    } catch {
+      // A missing card is not worth failing a session start over.
+    }
+  });
+}