@pi-unipi/updater 0.1.1

package/src/index.ts

@@ -0,0 +1,178 @@
+/**
+ * @pi-unipi/updater — Extension entry point
+ *
+ * Auto-updater, changelog browser, and readme browser for Unipi.
+ *
+ * On session start: loads config, checks npm registry for updates,
+ * shows update overlay if available. Registers commands for
+ * /unipi:readme, /unipi:changelog, /unipi:updater-settings.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import {
+  UNIPI_EVENTS,
+  MODULES,
+  UPDATER_COMMANDS,
+  UNIPI_PREFIX,
+  emitEvent,
+  getPackageVersion,
+} from "@pi-unipi/core";
+import { registerCommands } from "./commands.js";
+import { loadConfig } from "./settings.js";
+import { checkForUpdates } from "./checker.js";
+import { isVersionSkipped } from "./cache.js";
+import { renderUpdateOverlay } from "./tui/update-overlay.js";
+
+/** Package version */
+const VERSION = getPackageVersion(new URL("..", import.meta.url).pathname);
+
+export default function updaterExtension(pi: ExtensionAPI): void {
+  // Register skills directory
+  const skillsDir = new URL("../skills", import.meta.url).pathname;
+  pi.on("resources_discover", async () => {
+    return {
+      skillPaths: [skillsDir],
+    };
+  });
+
+  // Register commands
+  registerCommands(pi);
+
+  // Session lifecycle — check for updates and announce module
+  pi.on("session_start", async (_event, ctx) => {
+    // Emit MODULE_READY
+    emitEvent(pi as any, UNIPI_EVENTS.MODULE_READY, {
+      name: MODULES.UPDATER,
+      version: VERSION,
+      commands: [
+        `${UNIPI_PREFIX}${UPDATER_COMMANDS.README}`,
+        `${UNIPI_PREFIX}${UPDATER_COMMANDS.CHANGELOG}`,
+        `${UNIPI_PREFIX}${UPDATER_COMMANDS.UPDATER_SETTINGS}`,
+      ],
+      tools: [],
+    });
+
+    // Register info-screen group
+    const infoRegistry = (globalThis as any).__unipi_info_registry;
+    if (infoRegistry) {
+      let cachedResult: { currentVersion: string; latestVersion: string; updateAvailable: boolean; lastCheck: string } | null = null;
+
+      infoRegistry.registerGroup({
+        id: "updater",
+        name: "Updater",
+        icon: "📦",
+        priority: 20,
+        config: {
+          showByDefault: true,
+          stats: [
+            { id: "current", label: "Installed", show: true },
+            { id: "latest", label: "Latest", show: true },
+            { id: "status", label: "Status", show: true },
+            { id: "lastCheck", label: "Last check", show: true },
+          ],
+        },
+        dataProvider: async () => {
+          if (!cachedResult) {
+            return {
+              current: VERSION,
+              latest: "checking...",
+              status: "⏳ Checking",
+              lastCheck: "never",
+            };
+          }
+          return {
+            current: cachedResult.currentVersion,
+            latest: cachedResult.latestVersion,
+            status: cachedResult.updateAvailable ? "↑ Update available" : "✓ Up to date",
+            lastCheck: cachedResult.lastCheck || "never",
+          };
+        },
+      });
+
+      // Subscribe to events to update cached data
+      pi.events.on(UNIPI_EVENTS.UPDATE_CHECK, (payload: any) => {
+        cachedResult = {
+          currentVersion: payload.currentVersion,
+          latestVersion: payload.latestVersion,
+          updateAvailable: payload.updateAvailable,
+          lastCheck: new Date().toLocaleTimeString(),
+        };
+        emitEvent(pi as any, UNIPI_EVENTS.INFO_DATA_UPDATED, {
+          groupId: "updater",
+          keys: ["current", "latest", "status", "lastCheck"],
+        });
+      });
+
+      pi.events.on(UNIPI_EVENTS.UPDATE_AVAILABLE, (_payload: any) => {
+        if (cachedResult) {
+          cachedResult.updateAvailable = true;
+        }
+        emitEvent(pi as any, UNIPI_EVENTS.INFO_DATA_UPDATED, {
+          groupId: "updater",
+          keys: ["status"],
+        });
+      });
+
+      pi.events.on(UNIPI_EVENTS.UPDATE_APPLIED, (_payload: any) => {
+        if (cachedResult) {
+          cachedResult.updateAvailable = false;
+        }
+        emitEvent(pi as any, UNIPI_EVENTS.INFO_DATA_UPDATED, {
+          groupId: "updater",
+          keys: ["status"],
+        });
+      });
+    }
+
+    // Check for updates in background
+    const config = loadConfig();
+    if (config.autoUpdate === "disabled") return;
+
+    try {
+      const result = await checkForUpdates();
+
+      // Emit check event
+      emitEvent(pi as any, UNIPI_EVENTS.UPDATE_CHECK, result);
+
+      if (!result.updateAvailable || result.error) return;
+
+      // Check if user skipped this version
+      if (isVersionSkipped(result.latestVersion)) return;
+
+      // Emit available event
+      emitEvent(pi as any, UNIPI_EVENTS.UPDATE_AVAILABLE, {
+        currentVersion: result.currentVersion,
+        latestVersion: result.latestVersion,
+      });
+
+      // Show update overlay if UI is available
+      if (ctx.hasUI) {
+        const updateResult = await ctx.ui.custom(
+          renderUpdateOverlay(result),
+          {
+            overlay: true,
+            overlayOptions: {
+              width: "80%",
+              minWidth: 60,
+              anchor: "center",
+              margin: 2,
+            },
+          },
+        );
+        if (updateResult?.updated) {
+          ctx.ui.notify(
+            `Updated to ${result.latestVersion}. Restart pi to apply.`,
+            "info",
+          );
+        }
+      }
+    } catch (_err) {
+      // Update check failure — silent, non-critical
+    }
+  });
+
+  // Cleanup on session shutdown
+  pi.on("session_shutdown", async () => {
+    // No cleanup needed
+  });
+}

package/src/installer.ts

@@ -0,0 +1,74 @@
+/**
+ * @pi-unipi/updater — Update installer
+ *
+ * Wraps child_process.exec for installing updates via pi CLI.
+ * Emits UPDATE_APPLIED or UPDATE_ERROR events.
+ */
+
+import { exec } from "child_process";
+import { promisify } from "util";
+import { getPackageVersion, emitEvent, UNIPI_EVENTS } from "@pi-unipi/core";
+import type { InstallResult } from "../types.js";
+
+const execAsync = promisify(exec);
+
+/** Timeout for the install command (60 seconds) */
+const INSTALL_TIMEOUT_MS = 60000;
+
+/**
+ * Install the latest version of @pi-unipi/unipi.
+ * Uses pi CLI: `pi install npm:@pi-unipi/unipi`
+ * Returns structured result with success/failure info.
+ */
+export async function installUpdate(
+  pi?: { events: { emit: (name: string, payload: unknown) => void } },
+): Promise<InstallResult> {
+  const installedBefore = getPackageVersion(
+    new URL("../../..", import.meta.url).pathname,
+  );
+
+  try {
+    const { stdout, stderr } = await execAsync(
+      "pi install npm:@pi-unipi/unipi",
+      {
+        timeout: INSTALL_TIMEOUT_MS,
+        env: { ...process.env },
+      },
+    );
+
+    // Get new version after install
+    const installedAfter = getPackageVersion(
+      new URL("../../..", import.meta.url).pathname,
+    );
+
+    const result: InstallResult = {
+      success: true,
+      version: installedAfter,
+    };
+
+    // Emit success event
+    if (pi) {
+      emitEvent(pi, UNIPI_EVENTS.UPDATE_APPLIED, {
+        previousVersion: installedBefore,
+        newVersion: installedAfter,
+      });
+    }
+
+    return result;
+  } catch (err: any) {
+    const errorMessage = err.stderr || err.message || "Unknown install error";
+
+    // Emit error event
+    if (pi) {
+      emitEvent(pi, UNIPI_EVENTS.UPDATE_ERROR, {
+        error: errorMessage,
+        phase: "install",
+      });
+    }
+
+    return {
+      success: false,
+      error: errorMessage,
+    };
+  }
+}

package/src/markdown.ts

@@ -0,0 +1,173 @@
+/**
+ * @pi-unipi/updater — Markdown terminal renderer
+ *
+ * Renders markdown to terminal-formatted strings.
+ * When a Theme is provided, uses the full Markdown component from pi-tui
+ * with theme-aware styling. Falls back to simple ANSI rendering otherwise.
+ */
+
+import { Markdown } from "@mariozechner/pi-tui";
+import type { MarkdownTheme } from "@mariozechner/pi-tui";
+import { getMarkdownTheme } from "@mariozechner/pi-coding-agent";
+import type { Theme } from "@mariozechner/pi-coding-agent";
+
+/**
+ * Render markdown text to terminal-formatted lines.
+ *
+ * When a Theme is provided, uses the full Markdown component from pi-tui
+ * with syntax highlighting, proper list nesting, tables, etc.
+ *
+ * @param text - Markdown text to render
+ * @param width - Available width for rendering
+ * @param theme - Optional Theme for styled rendering
+ * @returns Array of rendered terminal lines
+ */
+export function renderMarkdown(text: string, width: number, theme?: Theme): string[] {
+  if (theme) {
+    return renderWithTheme(text, width, theme);
+  }
+  return renderSimple(text, width);
+}
+
+/**
+ * Render using the full Markdown component with theme support.
+ */
+function renderWithTheme(text: string, width: number, theme: Theme): string[] {
+  const mdTheme = getMarkdownTheme();
+  const md = new Markdown(text, 1, 0, mdTheme);
+  return md.render(width);
+}
+
+/**
+ * Simple fallback renderer using basic ANSI codes.
+ * Used when no Theme is available.
+ */
+
+/** ANSI escape codes */
+const ESC = "\x1b";
+const BOLD = `${ESC}[1m`;
+const DIM = `${ESC}[2m`;
+const UNDERLINE = `${ESC}[4m`;
+const RESET = `${ESC}[0m`;
+
+/** Wrap text in ANSI formatting */
+function fmt(code: string, text: string): string {
+  return `${code}${text}${RESET}`;
+}
+
+/** Word-wrap a line to fit within width */
+function wordWrap(line: string, width: number): string[] {
+  // Strip ANSI for length calculation but preserve in output
+  const stripped = line.replace(/\x1b\[[0-9;]*m/g, "");
+  if (stripped.length <= width) return [line];
+
+  const words = line.split(/(\s+)/);
+  const result: string[] = [];
+  let currentLine = "";
+  let currentWidth = 0;
+
+  for (const word of words) {
+    const wordWidth = word.replace(/\x1b\[[0-9;]*m/g, "").length;
+    if (currentWidth + wordWidth > width && currentLine) {
+      result.push(currentLine);
+      currentLine = word.trimStart();
+      currentWidth = currentLine.replace(/\x1b\[[0-9;]*m/g, "").length;
+    } else {
+      currentLine += word;
+      currentWidth += wordWidth;
+    }
+  }
+  if (currentLine) result.push(currentLine);
+  return result.length > 0 ? result : [""];
+}
+
+/** Apply inline formatting: bold, italic, code, links */
+function formatInline(text: string): string {
+  // Inline code: `code`
+  text = text.replace(/`([^`]+)`/g, (_, code) => fmt(DIM, code));
+
+  // Bold: **text**
+  text = text.replace(/\*\*([^*]+)\*\*/g, (_, bold) => fmt(BOLD, bold));
+
+  // Italic: *text*
+  text = text.replace(/(?<!\*)\*([^*]+)\*(?!\*)/g, (_, italic) => fmt(UNDERLINE, italic));
+
+  // Links: [text](url) → underlined text
+  text = text.replace(/\[([^\]]+)\]\([^)]+\)/g, (_, linkText) => fmt(UNDERLINE, linkText));
+
+  return text;
+}
+
+/**
+ * Simple markdown renderer (fallback).
+ */
+function renderSimple(text: string, width: number): string[] {
+  const lines = text.split("\n");
+  const result: string[] = [];
+  let inCodeBlock = false;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    // Code fence toggle
+    if (trimmed.startsWith("```")) {
+      inCodeBlock = !inCodeBlock;
+      continue;
+    }
+
+    // Inside code block — dim, no formatting
+    if (inCodeBlock) {
+      const formatted = fmt(DIM, line);
+      result.push(...wordWrap(formatted, width));
+      continue;
+    }
+
+    // Heading: #, ##, ###
+    if (trimmed.startsWith("### ")) {
+      const heading = trimmed.slice(4);
+      const formatted = fmt(BOLD + UNDERLINE, heading);
+      result.push(...wordWrap(formatted, width));
+      continue;
+    }
+    if (trimmed.startsWith("## ")) {
+      const heading = trimmed.slice(3);
+      const formatted = fmt(BOLD, heading);
+      result.push(...wordWrap(formatted, width));
+      continue;
+    }
+    if (trimmed.startsWith("# ")) {
+      const heading = trimmed.slice(2);
+      const formatted = fmt(BOLD, heading);
+      result.push(...wordWrap(formatted, width));
+      continue;
+    }
+
+    // Bullet list: - or *
+    if (trimmed.startsWith("- ") || trimmed.startsWith("* ")) {
+      const content = trimmed.slice(2);
+      const formatted = "  • " + formatInline(content);
+      result.push(...wordWrap(formatted, width));
+      continue;
+    }
+
+    // Numbered list: 1. 2. etc.
+    const numberMatch = trimmed.match(/^(\d+)\.\s+(.+)$/);
+    if (numberMatch) {
+      const formatted = `  ${numberMatch[1]}. ${formatInline(numberMatch[2])}`;
+      result.push(...wordWrap(formatted, width));
+      continue;
+    }
+
+    // Empty line — preserve spacing
+    if (!trimmed) {
+      result.push("");
+      continue;
+    }
+
+    // Regular paragraph — apply inline formatting
+    const formatted = formatInline(trimmed);
+    result.push(...wordWrap(formatted, width));
+  }
+
+  return result;
+}

package/src/readme.ts

@@ -0,0 +1,139 @@
+/**
+ * @pi-unipi/updater — Readme discovery
+ *
+ * Discovers package README.md paths from the unipi monorepo.
+ * Root README from the unipi package root, package READMEs from
+ * node_modules/@pi-unipi/{name}/README.md.
+ */
+
+import { existsSync, readFileSync } from "fs";
+import { join, resolve } from "path";
+import { MODULES } from "@pi-unipi/core";
+import type { ReadmeEntry } from "../types.js";
+
+/** Short name → full package name mapping from MODULES constant */
+const PACKAGE_MAP: Record<string, string> = {
+  core: MODULES.CORE,
+  workflow: MODULES.WORKFLOW,
+  ralph: MODULES.RALPH,
+  memory: MODULES.MEMORY,
+  "info-screen": MODULES.INFO_SCREEN,
+  registry: MODULES.REGISTRY,
+  mcp: MODULES.MCP,
+  task: MODULES.TASK,
+  "web-api": MODULES.WEB_API,
+  impeccable: MODULES.IMPECCABLE,
+  settings: MODULES.SETTINGS,
+  utility: MODULES.UTILITY,
+  "ask-user": MODULES.ASK_USER,
+  compactor: MODULES.COMPACTOR,
+  notify: MODULES.NOTIFY,
+  btw: MODULES.BTW,
+  milestone: MODULES.MILESTONE,
+  kanboard: MODULES.KANBOARD,
+  footer: MODULES.FOOTER,
+  updater: MODULES.UPDATER,
+};
+
+/** Resolve the unipi monorepo root directory */
+function resolveUnipiRoot(): string {
+  // Walk up from this file to find the monorepo root (has package.json with @pi-unipi/unipi)
+  let dir = new URL(".", import.meta.url).pathname;
+  // From src/updater/src/ → go up 4 levels to reach monorepo root
+  // Actually: packages/updater/src/readme.ts → ../../.. = monorepo root
+  dir = resolve(dir, "../../..");
+  return dir;
+}
+
+/** Get version from a package.json at the given directory */
+function getPackageVersion(dir: string): string {
+  try {
+    const pkgPath = join(dir, "package.json");
+    if (existsSync(pkgPath)) {
+      const raw = readFileSync(pkgPath, "utf-8");
+      const pkg = JSON.parse(raw);
+      return pkg.version ?? "0.0.0";
+    }
+  } catch (_err) {
+    // Ignore parse errors
+  }
+  return "0.0.0";
+}
+
+/**
+ * Discover all available README.md files.
+ * Returns entries for the root README and all package READMEs that exist.
+ */
+export function discoverReadmes(): ReadmeEntry[] {
+  const root = resolveUnipiRoot();
+  const entries: ReadmeEntry[] = [];
+
+  // Root README
+  const rootReadme = join(root, "README.md");
+  if (existsSync(rootReadme)) {
+    entries.push({
+      name: "unipi",
+      packageName: "@pi-unipi/unipi",
+      version: getPackageVersion(root),
+      path: rootReadme,
+    });
+  }
+
+  // Package READMEs — check both workspace layout and node_modules layout
+  for (const [shortName, fullName] of Object.entries(PACKAGE_MAP)) {
+    // Workspace layout: packages/{shortName}/README.md
+    const workspacePath = join(root, "packages", shortName, "README.md");
+    // node_modules layout: node_modules/{fullName}/README.md
+    const nodeModulesPath = join(root, "node_modules", fullName, "README.md");
+
+    let readmePath: string | null = null;
+    let versionDir: string | null = null;
+
+    if (existsSync(workspacePath)) {
+      readmePath = workspacePath;
+      versionDir = join(root, "packages", shortName);
+    } else if (existsSync(nodeModulesPath)) {
+      readmePath = nodeModulesPath;
+      versionDir = join(root, "node_modules", fullName);
+    }
+
+    if (readmePath && versionDir) {
+      entries.push({
+        name: shortName,
+        packageName: fullName,
+        version: getPackageVersion(versionDir),
+        path: readmePath,
+      });
+    }
+  }
+
+  return entries;
+}
+
+/**
+ * Resolve the README path for a specific package.
+ * If packageName is undefined or empty, returns the root README.
+ * Returns null if the README doesn't exist.
+ */
+export function resolveReadmePath(packageName?: string): string | null {
+  const root = resolveUnipiRoot();
+
+  if (!packageName || packageName === "unipi") {
+    const rootReadme = join(root, "README.md");
+    return existsSync(rootReadme) ? rootReadme : null;
+  }
+
+  // Look up the short name in the package map
+  const fullName = PACKAGE_MAP[packageName];
+  if (!fullName) return null;
+
+  // Check workspace layout first
+  const workspacePath = join(root, "packages", packageName, "README.md");
+  if (existsSync(workspacePath)) return workspacePath;
+
+  // Then node_modules
+  const nodeModulesPath = join(root, "node_modules", fullName, "README.md");
+  if (existsSync(nodeModulesPath)) return nodeModulesPath;
+
+  return null;
+}

package/src/settings.ts

@@ -0,0 +1,98 @@
+/**
+ * @pi-unipi/updater — Configuration management
+ *
+ * Loads, saves, and validates updater config from ~/.unipi/config/updater/config.json
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
+import { dirname, join } from "path";
+import { homedir } from "os";
+import { UPDATER_DIRS } from "@pi-unipi/core";
+import type { UpdaterConfig } from "../types.js";
+
+/** Default configuration — 1 hour check interval, notify mode */
+export const DEFAULT_CONFIG: UpdaterConfig = {
+  checkIntervalMs: 3600000, // 1 hour
+  autoUpdate: "notify",
+};
+
+/** Valid check intervals in milliseconds */
+const VALID_INTERVALS: Record<string, number> = {
+  "30min": 1800000,
+  "1h": 3600000,
+  "6h": 21600000,
+  "1d": 86400000,
+};
+
+/** Valid auto-update modes */
+const VALID_MODES: UpdaterConfig["autoUpdate"][] = ["disabled", "notify", "auto"];
+
+/** Resolve config path */
+function resolveConfigPath(): string {
+  const base = UPDATER_DIRS.CONFIG.replace("~", homedir());
+  return join(base, "config.json");
+}
+
+/** Load config from disk, returning defaults if missing or invalid */
+export function loadConfig(): UpdaterConfig {
+  const configPath = resolveConfigPath();
+  try {
+    if (existsSync(configPath)) {
+      const raw = readFileSync(configPath, "utf-8");
+      const parsed = JSON.parse(raw) as Partial<UpdaterConfig>;
+      return mergeWithDefaults(parsed);
+    }
+  } catch (_err) {
+    // Config load failure — using defaults silently.
+  }
+  return { ...DEFAULT_CONFIG };
+}
+
+/** Save config to disk, creating directory if needed */
+export function saveConfig(config: UpdaterConfig): void {
+  const configPath = resolveConfigPath();
+  const dir = dirname(configPath);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
+}
+
+/** Validate config, returning list of error messages */
+export function validateConfig(config: UpdaterConfig): string[] {
+  const errors: string[] = [];
+
+  if (!VALID_MODES.includes(config.autoUpdate)) {
+    errors.push(`autoUpdate must be one of: ${VALID_MODES.join(", ")}`);
+  }
+
+  if (config.checkIntervalMs < 60000) {
+    errors.push("checkIntervalMs must be at least 60000 (1 minute)");
+  }
+
+  return errors;
+}
+
+/** Get human-readable label for an interval */
+export function getIntervalLabel(ms: number): string {
+  for (const [label, value] of Object.entries(VALID_INTERVALS)) {
+    if (value === ms) return label;
+  }
+  return `${Math.round(ms / 60000)}min`;
+}
+
+/** Get all valid intervals as { label, ms } pairs */
+export function getIntervalOptions(): Array<{ label: string; ms: number }> {
+  return Object.entries(VALID_INTERVALS).map(([label, ms]) => ({ label, ms }));
+}
+
+/** Get all valid auto-update modes */
+export function getAutoUpdateOptions(): UpdaterConfig["autoUpdate"][] {
+  return [...VALID_MODES];
+}
+
+/** Merge loaded config with defaults to ensure all fields exist */
+function mergeWithDefaults(loaded: Partial<UpdaterConfig>): UpdaterConfig {
+  return {
+    checkIntervalMs: loaded.checkIntervalMs ?? DEFAULT_CONFIG.checkIntervalMs,
+    autoUpdate: loaded.autoUpdate ?? DEFAULT_CONFIG.autoUpdate,
+  };
+}