@pi-unipi/updater 0.1.1

package/README.md

@@ -0,0 +1,71 @@
+# @pi-unipi/updater
+
+Auto-updater, changelog browser, and readme browser for the Unipi extension suite.
+
+## Features
+
+- **Auto-updater** — Periodically checks npm registry for new versions, shows update prompt with changelog diff
+- **Changelog browser** — TUI overlay listing all versions with dates and status labels (✓ Current, ↑ New)
+- **Readme browser** — TUI overlay listing all packages with versions, opens rendered README content
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/unipi:readme [package]` | Browse package README files. No arg opens list, with arg opens directly. |
+| `/unipi:changelog` | Browse CHANGELOG.md with version list and detail view |
+| `/unipi:updater-settings` | Configure check interval and auto-update mode |
+
+## Configuration
+
+Config stored at `~/.unipi/config/updater/config.json`:
+
+```json
+{
+  "checkIntervalMs": 3600000,
+  "autoUpdate": "notify"
+}
+```
+
+### Options
+
+| Option | Values | Default |
+|--------|--------|---------|
+| `checkIntervalMs` | `1800000` (30min), `3600000` (1h), `21600000` (6h), `86400000` (1d) | `3600000` (1h) |
+| `autoUpdate` | `disabled`, `notify`, `auto` | `notify` |
+
+### Auto-update modes
+
+- **disabled** — No update checks on session start
+- **notify** — Show update overlay with changelog diff, user chooses [Y] Update or [n] Skip
+- **auto** — Show countdown overlay, auto-install after 5 seconds unless cancelled
+
+## How it works
+
+1. On session start, checks npm registry for `@pi-unipi/unipi` latest version
+2. Compares with installed version from `package.json`
+3. If newer version found and not previously skipped, shows update overlay
+4. User can view changelog diff, update with `[Y]`, or skip with `[n]`
+5. Skipped versions are cached — only re-prompted when an even newer version appears
+6. Update installs via `pi install npm:@pi-unipi/unipi`
+
+## TUI Overlays
+
+All overlays use keyboard navigation:
+- `j`/`k` or ↑/↓ — navigate
+- `Enter` — select/open
+- `q`/`Esc` — back/close
+- `g`/`G` — jump to top/bottom
+- `Space` — cycle options (settings overlay)
+- `h`/`l` or ←/→ — cycle options (settings overlay)
+
+## Cache
+
+Last-check cache stored at `~/.unipi/cache/updater/last-check.json`:
+```json
+{
+  "lastCheck": "2026-05-01T12:00:00.000Z",
+  "latestVersion": "0.1.16",
+  "skippedVersion": "0.1.16"
+}
+```

package/index.ts

@@ -0,0 +1,6 @@
+/**
+ * @pi-unipi/updater — Re-export entry
+ */
+
+export { default } from "./src/index.js";
+export type * from "./types.js";

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@pi-unipi/updater",
+  "version": "0.1.1",
+  "description": "Auto-updater, changelog browser, and readme browser for Unipi — checks npm registry, renders CHANGELOG.md and README.md files in TUI overlays",
+  "type": "module",
+  "license": "MIT",
+  "author": "Neuron Mr White",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Neuron-Mr-White/unipi.git",
+    "directory": "packages/updater"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi-coding-agent",
+    "unipi",
+    "updater",
+    "changelog",
+    "readme"
+  ],
+  "files": [
+    "index.ts",
+    "src/**/*.ts",
+    "skills/**/*",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "src/index.ts"
+    ],
+    "skills": [
+      "skills"
+    ]
+  },
+  "scripts": {
+    "test": "node --experimental-strip-types --test tests/**/*.test.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@pi-unipi/core": "*"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "typescript": "^6.0.0"
+  }
+}

package/skills/configure-updater/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: configure-updater
+description: Guide for using and configuring the Unipi updater — auto-update, changelog browser, and readme browser.
+---
+
+# Configure Updater
+
+The `@pi-unipi/updater` package provides auto-update checking, a changelog browser, and a readme browser.
+
+## Commands
+
+### `/unipi:readme [package]`
+
+Browse README.md files for all unipi packages.
+
+- **No argument** — Opens a list of all packages with their versions. Select one to read its README.
+- **With argument** (e.g., `/unipi:readme workflow`) — Opens that package's README directly.
+
+### `/unipi:changelog`
+
+Browse the root CHANGELOG.md in a TUI overlay.
+
+- Shows version list with dates and status labels (✓ Current, ↑ New)
+- Select a version to view its changelog details (Added, Fixed, Changed sections)
+- Follows [Keep a Changelog](https://keepachangelog.com) format
+
+### `/unipi:updater-settings`
+
+Configure the updater module.
+
+**Settings:**
+- **Check Interval** — How often to check npm for updates (30min / 1h / 6h / 1d)
+- **Auto Update** — What happens when an update is found:
+  - `disabled` — No update checks on session start
+  - `notify` — Show update overlay, user chooses to update or skip
+  - `auto` — Auto-install after 5-second countdown (press `n` to cancel)
+
+## Config File
+
+Config stored at `~/.unipi/config/updater/config.json`:
+
+```json
+{
+  "checkIntervalMs": 3600000,
+  "autoUpdate": "notify"
+}
+```
+
+## Cache
+
+Last-check cache at `~/.unipi/cache/updater/last-check.json`:
+- Tracks when the last npm check was performed
+- Stores the latest version found
+- Remembers skipped versions (user pressed `n` to skip)
+- Re-prompts only when a newer version than the skipped one appears
+
+## Navigation
+
+All TUI overlays support:
+- `j`/`k` or ↑/↓ — Navigate
+- `Enter` — Select/open
+- `q`/`Esc` — Back/close
+- `g`/`G` — Jump to top/bottom
+- `Space` — Cycle options (settings)
+- `h`/`l` or ←/→ — Cycle options (settings)

package/src/cache.ts

@@ -0,0 +1,67 @@
+/**
+ * @pi-unipi/updater — Last-check cache
+ *
+ * Reads/writes last-check.json to ~/.unipi/cache/updater/last-check.json
+ * Tracks when the last npm check was performed and what version was found.
+ */
+
+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 { LastCheckCache } from "../types.js";
+
+/** Resolve cache path */
+function resolveCachePath(): string {
+  const base = UPDATER_DIRS.CACHE.replace("~", homedir());
+  return join(base, "last-check.json");
+}
+
+/** Read cache from disk, returning null if missing or invalid */
+export function readLastCheck(): LastCheckCache | null {
+  const cachePath = resolveCachePath();
+  try {
+    if (existsSync(cachePath)) {
+      const raw = readFileSync(cachePath, "utf-8");
+      const parsed = JSON.parse(raw) as LastCheckCache;
+      if (parsed.lastCheck && parsed.latestVersion) {
+        return parsed;
+      }
+    }
+  } catch (_err) {
+    // Cache read failure — treat as missing.
+  }
+  return null;
+}
+
+/** Write cache to disk, creating directory if needed */
+export function writeLastCheck(cache: LastCheckCache): void {
+  const cachePath = resolveCachePath();
+  const dir = dirname(cachePath);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(cachePath, JSON.stringify(cache, null, 2) + "\n", "utf-8");
+}
+
+/** Check if enough time has elapsed since last check */
+export function isCheckDue(intervalMs: number): boolean {
+  const cache = readLastCheck();
+  if (!cache) return true;
+
+  const lastCheckTime = new Date(cache.lastCheck).getTime();
+  const now = Date.now();
+  return now - lastCheckTime >= intervalMs;
+}
+
+/** Write skipped version to cache */
+export function writeSkippedVersion(version: string): void {
+  const cache = readLastCheck();
+  if (cache) {
+    writeLastCheck({ ...cache, skippedVersion: version });
+  }
+}
+
+/** Check if a version was skipped by the user */
+export function isVersionSkipped(version: string): boolean {
+  const cache = readLastCheck();
+  return cache?.skippedVersion === version;
+}

package/src/changelog.ts

@@ -0,0 +1,141 @@
+/**
+ * @pi-unipi/updater — Changelog parser
+ *
+ * Parses CHANGELOG.md (Keep a Changelog format) into structured ChangelogEntry[].
+ * Handles: ## [Unreleased], ## [x.y.z] — YYYY-MM-DD, ### Added/Fixed/etc.
+ */
+
+import { existsSync, readFileSync } from "fs";
+import type { ChangelogEntry } from "../types.js";
+
+/** Regex for version headers: ## [x.y.z] — YYYY-MM-DD or ## [Unreleased] */
+const VERSION_HEADER_RE = /^## \[(.+?)\](?:\s*[-—–]\s*(.+))?$/;
+
+/** Regex for section headers: ### Added, ### Fixed, etc. */
+const SECTION_HEADER_RE = /^### (.+)$/;
+
+/**
+ * Parse a CHANGELOG.md file into structured entries.
+ * Returns empty array if file doesn't exist or is empty.
+ */
+export function parseChangelog(filePath: string): ChangelogEntry[] {
+  if (!existsSync(filePath)) return [];
+
+  const content = readFileSync(filePath, "utf-8").trim();
+  if (!content) return [];
+
+  const lines = content.split("\n");
+  const entries: ChangelogEntry[] = [];
+
+  let currentEntry: ChangelogEntry | null = null;
+  let currentSection: string | null = null;
+  let currentItems: string[] = [];
+
+  for (const line of lines) {
+    const versionMatch = line.match(VERSION_HEADER_RE);
+    if (versionMatch) {
+      // Save previous entry
+      if (currentEntry) {
+        if (currentSection && currentItems.length > 0) {
+          currentEntry.sections[currentSection] = currentItems;
+        }
+        entries.push(currentEntry);
+      }
+
+      // Start new entry
+      const version = versionMatch[1].trim();
+      const date = (versionMatch[2] ?? "").trim();
+      currentEntry = {
+        version,
+        date,
+        sections: {},
+        body: "",
+      };
+      currentSection = null;
+      currentItems = [];
+      continue;
+    }
+
+    if (!currentEntry) continue;
+
+    const sectionMatch = line.match(SECTION_HEADER_RE);
+    if (sectionMatch) {
+      // Save previous section
+      if (currentSection && currentItems.length > 0) {
+        currentEntry.sections[currentSection] = currentItems;
+      }
+      currentSection = sectionMatch[1].trim();
+      currentItems = [];
+      continue;
+    }
+
+    // Collect section items (lines starting with - or *)
+    const trimmed = line.trim();
+    if (currentSection && (trimmed.startsWith("- ") || trimmed.startsWith("* "))) {
+      currentItems.push(trimmed.slice(2).trim());
+    } else if (trimmed && currentSection) {
+      // Continuation of previous item
+      if (currentItems.length > 0) {
+        currentItems[currentItems.length - 1] += " " + trimmed;
+      }
+    }
+  }
+
+  // Save last entry
+  if (currentEntry) {
+    if (currentSection && currentItems.length > 0) {
+      currentEntry.sections[currentSection] = currentItems;
+    }
+    entries.push(currentEntry);
+  }
+
+  // Build body text for each entry (for rendering)
+  for (const entry of entries) {
+    const lines: string[] = [];
+    for (const [section, items] of Object.entries(entry.sections)) {
+      lines.push(`### ${section}`);
+      for (const item of items) {
+        lines.push(`- ${item}`);
+      }
+      lines.push("");
+    }
+    entry.body = lines.join("\n").trim();
+  }
+
+  return entries;
+}
+
+/**
+ * Get changelog entries for versions newer than the given version.
+ * Returns entries in newest-first order, excluding the given version.
+ */
+export function getNewerVersions(
+  entries: ChangelogEntry[],
+  installedVersion: string,
+): ChangelogEntry[] {
+  const result: ChangelogEntry[] = [];
+  for (const entry of entries) {
+    if (entry.version === "Unreleased") {
+      result.push(entry);
+      continue;
+    }
+    if (entry.version === installedVersion) break;
+    result.push(entry);
+  }
+  return result;
+}
+
+/**
+ * Compare semver strings (simple lexicographic for x.y.z format).
+ * Returns positive if a > b, negative if a < b, 0 if equal.
+ */
+export function compareVersions(a: string, b: string): number {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const na = pa[i] ?? 0;
+    const nb = pb[i] ?? 0;
+    if (na !== nb) return na - nb;
+  }
+  return 0;
+}

package/src/checker.ts

@@ -0,0 +1,84 @@
+/**
+ * @pi-unipi/updater — NPM registry checker
+ *
+ * Fetches latest version from npm registry, compares with installed version,
+ * respects check interval from config/cache.
+ */
+
+import { getPackageVersion } from "@pi-unipi/core";
+import { loadConfig } from "./settings.js";
+import { readLastCheck, writeLastCheck, isCheckDue } from "./cache.js";
+import type { UpdateCheckResult } from "../types.js";
+
+/** NPM registry URL for the unipi umbrella package */
+const NPM_REGISTRY_URL = "https://registry.npmjs.org/@pi-unipi/unipi";
+
+/** Resolve the installed version of @pi-unipi/unipi */
+function getInstalledVersion(): string {
+  // Walk up from this file to find the monorepo root
+  const dir = new URL("../../..", import.meta.url).pathname;
+  return getPackageVersion(dir);
+}
+
+/**
+ * Check for updates from npm registry.
+ * Respects check interval — skips if last check was recent.
+ * Returns update status and version info.
+ */
+export async function checkForUpdates(): Promise<UpdateCheckResult> {
+  const currentVersion = getInstalledVersion();
+
+  try {
+    const config = loadConfig();
+
+    // Check if we need to fetch (interval not elapsed)
+    if (!isCheckDue(config.checkIntervalMs)) {
+      const cache = readLastCheck();
+      if (cache) {
+        return {
+          updateAvailable: cache.latestVersion !== currentVersion,
+          latestVersion: cache.latestVersion,
+          currentVersion,
+        };
+      }
+    }
+
+    // Fetch from npm registry
+    const response = await fetch(NPM_REGISTRY_URL, {
+      headers: { Accept: "application/json" },
+      signal: AbortSignal.timeout(10000), // 10s timeout
+    });
+
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+
+    const data = await response.json() as { "dist-tags": { latest: string } };
+    const latestVersion = data["dist-tags"]?.latest;
+
+    if (!latestVersion) {
+      throw new Error("No dist-tags.latest in npm response");
+    }
+
+    // Write cache
+    writeLastCheck({
+      lastCheck: new Date().toISOString(),
+      latestVersion,
+    });
+
+    return {
+      updateAvailable: latestVersion !== currentVersion,
+      latestVersion,
+      currentVersion,
+    };
+  } catch (err: any) {
+    // Network error — return cached info if available
+    const cache = readLastCheck();
+    return {
+      updateAvailable: false,
+      latestVersion: cache?.latestVersion ?? "",
+      currentVersion,
+      error: err.message ?? "Unknown error",
+    };
+  }
+}

package/src/commands.ts

@@ -0,0 +1,83 @@
+/**
+ * @pi-unipi/updater — Command Registration
+ *
+ * Registers /unipi:readme [package], /unipi:changelog, /unipi:updater-settings
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { UNIPI_PREFIX, UPDATER_COMMANDS } from "@pi-unipi/core";
+import { renderReadmeOverlay } from "./tui/readme-overlay.js";
+import { renderChangelogOverlay } from "./tui/changelog-overlay.js";
+import { renderSettingsOverlay } from "./tui/settings-overlay.js";
+
+/** Common overlay options for all updater overlays */
+const OVERLAY_OPTIONS = {
+  overlay: true,
+  overlayOptions: {
+    width: "80%",
+    minWidth: 60,
+    anchor: "center",
+    margin: 2,
+  },
+};
+
+/** Register updater commands */
+export function registerCommands(pi: ExtensionAPI): void {
+  // /unipi:readme [package] — Open readme browser
+  pi.registerCommand(
+    `${UNIPI_PREFIX}${UPDATER_COMMANDS.README}`,
+    {
+      description: "Browse package README files",
+      handler: async (args: string, ctx: any) => {
+        const packageName = args.trim() || undefined;
+        try {
+          await ctx.ui.custom(
+            renderReadmeOverlay({ openDirect: packageName }),
+            OVERLAY_OPTIONS,
+          );
+        } catch (err) {
+          ctx.ui.notify(`Readme overlay error: ${err}`, "error");
+        }
+      },
+    },
+  );
+
+  // /unipi:changelog — Open changelog browser
+  pi.registerCommand(
+    `${UNIPI_PREFIX}${UPDATER_COMMANDS.CHANGELOG}`,
+    {
+      description: "Browse changelog (Keep a Changelog format)",
+      handler: async (_args: string, ctx: any) => {
+        try {
+          await ctx.ui.custom(
+            renderChangelogOverlay(),
+            OVERLAY_OPTIONS,
+          );
+        } catch (err) {
+          ctx.ui.notify(`Changelog overlay error: ${err}`, "error");
+        }
+      },
+    },
+  );
+
+  // /unipi:updater-settings — Open updater settings
+  pi.registerCommand(
+    `${UNIPI_PREFIX}${UPDATER_COMMANDS.UPDATER_SETTINGS}`,
+    {
+      description: "Configure updater — check interval and auto-update mode",
+      handler: async (_args: string, ctx: any) => {
+        try {
+          const result = await ctx.ui.custom(
+            renderSettingsOverlay(),
+            OVERLAY_OPTIONS,
+          );
+          if (result?.saved) {
+            ctx.ui.notify("Updater settings saved.", "info");
+          }
+        } catch (err) {
+          ctx.ui.notify(`Settings overlay error: ${err}`, "error");
+        }
+      },
+    },
+  );
+}