@pi-unipi/updater 3.0.0-alpha.36 → 3.0.0-alpha.38

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/updater",
-  "version": "3.0.0-alpha.36",
+  "version": "3.0.0-alpha.38",
   "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",
   "main": "index.ts",
@@ -34,7 +34,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "3.0.0-alpha.36"
+    "@pi-unipi/core": "3.0.0-alpha.38"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.87.1",

package/src/channel.ts

@@ -0,0 +1,87 @@
+/**
+ * @pi-unipi/updater — release channel resolution (UNI-262)
+ *
+ * UniPi 3 ships on the npm `alpha` dist-tag while `latest` still points at the
+ * 2.x line. Comparing an alpha install against `latest` offered a downgrade.
+ * The channel to follow comes from, in order:
+ *   1. the pi settings package spec (`npm:@pi-unipi/unipi@alpha`) when its
+ *      version part is a dist-tag (not a pinned semver),
+ *   2. the installed version's prerelease id (`3.0.0-alpha.36` → `alpha`),
+ *   3. `latest`.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { compareVersions } from "@pi-unipi/core";
+
+export const UNIPI_PACKAGE = "@pi-unipi/unipi";
+
+/** `3.0.0-alpha.36` → `alpha`; stable → null. */
+export function prereleaseChannel(version: string): string | null {
+  const m = /^v?\d+\.\d+\.\d+-([0-9A-Za-z-]+)/.exec(version.trim());
+  if (!m) return null;
+  const id = m[1]!;
+  return /^\d+$/.test(id) ? null : id;
+}
+
+/** `npm:@pi-unipi/unipi@alpha` → `alpha`; pinned semver / no tag / other package → null. */
+export function channelFromSpec(spec: string): string | null {
+  const s = spec.trim().replace(/^npm:/, "");
+  if (!s.startsWith(`${UNIPI_PACKAGE}@`)) return null;
+  const tag = s.slice(UNIPI_PACKAGE.length + 1).trim();
+  if (!tag) return null;
+  // A pinned or ranged version is not a channel.
+  if (/^[\^~<>=v]?\d/.test(tag) || tag === "*") return null;
+  return tag;
+}
+
+/** pi's agent dir (honours PI_CODING_AGENT_DIR like pi itself). */
+export function piAgentDir(env: NodeJS.ProcessEnv = process.env): string {
+  const dir = env.PI_CODING_AGENT_DIR;
+  if (dir) return dir.startsWith("~") ? join(homedir(), dir.slice(1)) : dir;
+  return join(homedir(), ".pi", "agent");
+}
+
+/** The UniPi package spec from pi settings (project first, then global), if any. */
+export function readUnipiPackageSpec(cwd = process.cwd(), env: NodeJS.ProcessEnv = process.env): string | null {
+  const files = [join(cwd, ".pi", "settings.json"), join(piAgentDir(env), "settings.json")];
+  for (const file of files) {
+    try {
+      if (!existsSync(file)) continue;
+      const settings = JSON.parse(readFileSync(file, "utf8")) as { packages?: Array<string | { source?: string }> };
+      for (const pkg of settings.packages ?? []) {
+        const source = typeof pkg === "string" ? pkg : pkg?.source;
+        if (typeof source !== "string") continue;
+        const bare = source.trim().replace(/^npm:/, "");
+        if (bare === UNIPI_PACKAGE || bare.startsWith(`${UNIPI_PACKAGE}@`)) return source.trim();
+      }
+    } catch {
+      // Unreadable settings — try the next file.
+    }
+  }
+  return null;
+}
+
+/** The dist-tag this install follows. */
+export function resolveChannel(installedVersion: string, spec: string | null): string {
+  return (spec ? channelFromSpec(spec) : null) ?? prereleaseChannel(installedVersion) ?? "latest";
+}
+
+/**
+ * Pick the version to offer from a dist-tags map. A prerelease channel also
+ * considers `latest` so a graduation (3.0.0 stable) is still offered; a stable
+ * install never sees prerelease tags. Returns null if nothing usable.
+ */
+export function pickChannelVersion(distTags: Record<string, string> | undefined, channel: string): string | null {
+  if (!distTags) return null;
+  const candidates = [distTags[channel], channel !== "latest" ? distTags.latest : undefined]
+    .filter((v): v is string => typeof v === "string" && v.length > 0);
+  if (candidates.length === 0) return null;
+  return candidates.reduce((best, v) => (compareVersions(v, best) > 0 ? v : best));
+}
+
+/** The `pi install` source for this channel. */
+export function installSpec(channel: string): string {
+  return channel === "latest" ? `npm:${UNIPI_PACKAGE}` : `npm:${UNIPI_PACKAGE}@${channel}`;
+}

package/src/checker.ts

@@ -1,90 +1,115 @@
 /**
  * @pi-unipi/updater — NPM registry checker
  *
- * Fetches latest version from npm registry, compares with installed version,
- * respects check interval from config/cache.
+ * Fetches the dist-tag of the install's release channel (UNI-262: an alpha
+ * install follows `alpha`, never `latest`), compares with the installed
+ * version, never offers a lower version, and respects the check interval.
  */
 
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 import { getInstalledPackageVersion } from "@pi-unipi/core";
 import { loadConfig } from "./settings.js";
 import { readLastCheck, writeLastCheck, isCheckDue } from "./cache.js";
 import { compareVersions, isNewerVersion } from "./version.js";
+import { pickChannelVersion, readUnipiPackageSpec, resolveChannel, UNIPI_PACKAGE } from "./channel.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";
+/** npm registry base; `UNIPI_UPDATER_REGISTRY` overrides it (tests / mirrors). */
+export function registryUrl(env: NodeJS.ProcessEnv = process.env): string {
+  const base = (env.UNIPI_UPDATER_REGISTRY || "https://registry.npmjs.org").replace(/\/+$/, "");
+  return `${base}/-/package/${UNIPI_PACKAGE}/dist-tags`;
+}
 
 /** Resolve the installed version of @pi-unipi/unipi */
-function getInstalledVersion(): string {
-  // Walk up from this file to find the @pi-unipi/unipi package by name
-  const dir = new URL("..", import.meta.url).pathname;
-  return getInstalledPackageVersion(dir, "@pi-unipi/unipi");
+export function getInstalledVersion(): string {
+  // fileURLToPath, not URL.pathname: on Windows the latter is "/C:/…".
+  const dir = dirname(dirname(fileURLToPath(import.meta.url)));
+  return getInstalledPackageVersion(dir, UNIPI_PACKAGE);
 }
 
+/** The channel this install follows. */
+export function currentChannel(currentVersion = getInstalledVersion()): string {
+  return resolveChannel(currentVersion, readUnipiPackageSpec());
+}
 
 /** Build an update result without ever reporting downgrades as updates. */
-function toUpdateResult(latestVersion: string, currentVersion: string): UpdateCheckResult {
+function toUpdateResult(latestVersion: string, currentVersion: string, channel: string): UpdateCheckResult {
   return {
     updateAvailable: isNewerVersion(latestVersion, currentVersion),
     latestVersion,
     currentVersion,
+    channel,
   };
 }
 
+export interface CheckOptions {
+  fetchImpl?: typeof fetch;
+  currentVersion?: string;
+  channel?: string;
+  /** Ignore the interval cache. */
+  force?: boolean;
+}
+
 /**
- * Check for updates from npm registry.
+ * Check for updates on this install's channel.
  * Respects check interval — skips if last check was recent.
- * Returns update status and version info.
  */
-export async function checkForUpdates(): Promise<UpdateCheckResult> {
-  const currentVersion = getInstalledVersion();
+export async function checkForUpdates(opts: CheckOptions = {}): Promise<UpdateCheckResult> {
+  const currentVersion = opts.currentVersion ?? getInstalledVersion();
+  const channel = opts.channel ?? currentChannel(currentVersion);
 
   try {
     const config = loadConfig();
 
-    // Check if we need to fetch (interval not elapsed). If the cached npm
-    // version is older than the installed version, ignore the interval and
-    // refresh: this happens immediately after a local/source release before
-    // the updater cache has seen the new npm dist-tag.
+    // A cache is only reused for the same channel (an old cache written by
+    // the pre-UNI-262 checker holds `latest`). If the cached version is older
+    // than the installed one, refresh: right after a release the cache has
+    // not seen the new dist-tag yet.
     const cache = readLastCheck();
-    if (cache && !isCheckDue(config.checkIntervalMs)) {
+    if (!opts.force && cache && (cache.channel ?? "latest") === channel && !isCheckDue(config.checkIntervalMs)) {
       if (compareVersions(cache.latestVersion, currentVersion) >= 0) {
-        return toUpdateResult(cache.latestVersion, currentVersion);
+        return toUpdateResult(cache.latestVersion, currentVersion, channel);
       }
     }
 
-    // Fetch from npm registry
-    const response = await fetch(NPM_REGISTRY_URL, {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const response = await fetchImpl(registryUrl(), {
       headers: { Accept: "application/json" },
-      signal: AbortSignal.timeout(10000), // 10s timeout
+      signal: AbortSignal.timeout(10000),
     });
 
     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;
+    const body = await response.json() as Record<string, unknown>;
+    // The dist-tags endpoint returns the map itself; the full packument nests it.
+    const tags = (body["dist-tags"] ?? body) as Record<string, string>;
+    const latestVersion = pickChannelVersion(tags, channel);
 
     if (!latestVersion) {
-      throw new Error("No dist-tags.latest in npm response");
+      throw new Error(`No dist-tag "${channel}" in npm response`);
     }
 
-    // Write cache
     writeLastCheck({
       lastCheck: new Date().toISOString(),
       latestVersion,
+      channel,
+      skippedVersion: cache?.skippedVersion,
     });
 
-    return toUpdateResult(latestVersion, currentVersion);
+    return toUpdateResult(latestVersion, currentVersion, channel);
   } catch (err: unknown) {
-    // Network error — return cached info if available, but never suggest a
-    // downgrade from a stale cache.
+    // Network error — reuse cached info for this channel only, and never
+    // suggest a downgrade from a stale cache.
     const cache = readLastCheck();
+    const usable = cache && (cache.channel ?? "latest") === channel ? cache : null;
     return {
-      updateAvailable: cache ? isNewerVersion(cache.latestVersion, currentVersion) : false,
-      latestVersion: cache?.latestVersion ?? "",
+      updateAvailable: usable ? isNewerVersion(usable.latestVersion, currentVersion) : false,
+      latestVersion: usable?.latestVersion ?? "",
       currentVersion,
+      channel,
       error: err instanceof Error ? err.message : String(err) || "Unknown error",
     };
   }

package/src/index.ts

@@ -8,6 +8,7 @@
  * /unipi:readme and /unipi:changelog.
  */
 
+import { fileURLToPath } from "node:url";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import {
   bus,
@@ -25,7 +26,7 @@ import { renderUpdateOverlay } from "./tui/update-overlay.js";
 import { loadUpdateChangelog } from "./remote-changelog.js";
 
 /** Package version */
-const VERSION = getPackageVersion(new URL("..", import.meta.url).pathname);
+const VERSION = getPackageVersion(fileURLToPath(new URL("..", import.meta.url)));
 
 export default function updaterExtension(pi: ExtensionAPI): void {
 

package/src/installer.ts

@@ -6,7 +6,10 @@
 
 import { exec } from "child_process";
 import { promisify } from "util";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 import { getInstalledPackageVersion } from "@pi-unipi/core";
+import { installSpec } from "./channel.js";
 import type { InstallResult } from "../types.js";
 
 const execAsync = promisify(exec);
@@ -15,16 +18,18 @@ const execAsync = promisify(exec);
 const INSTALL_TIMEOUT_MS = 60000;
 
 /**
- * Install the latest version of @pi-unipi/unipi.
- * Uses pi CLI: `pi install npm:@pi-unipi/unipi`
+ * Install the newest @pi-unipi/unipi on `channel`.
+ * Uses pi CLI: `pi install npm:@pi-unipi/unipi[@<channel>]`
  * Returns structured result with success/failure info.
  */
-export async function installUpdate(): Promise<InstallResult> {
-  const thisDir = new URL("..", import.meta.url).pathname;
+export async function installUpdate(channel = "latest"): Promise<InstallResult> {
+  const thisDir = dirname(dirname(fileURLToPath(import.meta.url)));
 
   try {
+    // Install from the same channel the check used — a bare spec would pull
+    // `latest` and downgrade an alpha install (UNI-262).
     await execAsync(
-      "pi install npm:@pi-unipi/unipi",
+      `pi install ${installSpec(channel)}`,
       {
         timeout: INSTALL_TIMEOUT_MS,
         env: { ...process.env },

package/src/remote-changelog.ts

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { UPDATER_DIRS } from "@pi-unipi/core";
+import { UPDATER_DIRS, compareVersions } from "@pi-unipi/core";
 import type { ChangelogEntry } from "../types.js";
 import { getNewerVersions, parseChangelogContent, parseChangelog, resolveChangelogPath } from "./changelog.js";
 
@@ -17,6 +17,16 @@ function cacheDirectory(opts?: RemoteChangelogOptions): string {
   return (opts?.cacheDir ?? UPDATER_DIRS.CACHE).replace("~", homedir());
 }
 
+/**
+ * Branches to try when the release tag is missing. Prereleases are pushed to
+ * a channel branch (`3.0.0-alpha.36` → `v3.0.0-alpha`); `main` holds the
+ * stable line only, so it would show the wrong changelog to an alpha install.
+ */
+export function fallbackRefs(version: string): string[] {
+  const m = /^v?(\d+\.\d+\.\d+-[0-9A-Za-z-]+)\.[0-9A-Za-z.-]+$/.exec(version);
+  return m ? [`v${m[1]}`, "main"] : ["main"];
+}
+
 export async function fetchRemoteChangelog(version: string, opts: RemoteChangelogOptions = {}): Promise<string | null> {
   const cacheDir = cacheDirectory(opts);
   const cachePath = join(cacheDir, `changelog-${version}.md`);
@@ -31,10 +41,11 @@ export async function fetchRemoteChangelog(version: string, opts: RemoteChangelo
   try {
     let response = await fetchImpl(`${CHANGELOG_RAW_BASE}/v${version}/CHANGELOG.md`, { signal });
     // The release tag is immutable, so its changelog is safe to cache forever.
-    // The `main` fallback (tag not pushed yet) is not: never cache it.
+    // The branch fallbacks (tag not pushed yet) are not: never cache them.
     const cacheable = response.ok;
-    if (response.status === 404) {
-      response = await fetchImpl(`${CHANGELOG_RAW_BASE}/main/CHANGELOG.md`, { signal });
+    for (const ref of fallbackRefs(version)) {
+      if (response.status !== 404) break;
+      response = await fetchImpl(`${CHANGELOG_RAW_BASE}/${ref}/CHANGELOG.md`, { signal });
     }
     if (!response.ok) return null;
     const content = await response.text();
@@ -55,7 +66,9 @@ export async function loadUpdateChangelog(
 ): Promise<ChangelogEntry[]> {
   const remote = await fetchRemoteChangelog(latestVersion, opts);
   const entries = remote === null ? [] : parseChangelogContent(remote);
-  const newer = remote === null ? [] : getNewerVersions(entries, currentVersion);
+  const upTo = (list: ChangelogEntry[]) =>
+    list.filter((e) => e.version === "Unreleased" || compareVersions(e.version, latestVersion) <= 0);
+  const newer = remote === null ? [] : upTo(getNewerVersions(entries, currentVersion));
   if (newer.length > 0) return newer;
-  return getNewerVersions(parseChangelog(resolveChangelogPath()), currentVersion);
+  return upTo(getNewerVersions(parseChangelog(resolveChangelogPath()), currentVersion));
 }

package/src/tui/changelog-overlay.ts

@@ -5,10 +5,11 @@
  */
 
 import { existsSync } from "fs";
+import { fileURLToPath } from "node:url";
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { parseChangelog, resolveChangelogPath } from "../changelog.js";
 import { renderMarkdown } from "../markdown.js";
-import { getInstalledPackageVersion } from "@pi-unipi/core";
+import { getInstalledPackageVersion, compareVersions } from "@pi-unipi/core";
 import { createListDetailOverlay } from "./list-detail-overlay.js";
 import type { ChangelogEntry } from "../../types.js";
 
@@ -17,7 +18,7 @@ import type { ChangelogEntry } from "../../types.js";
  */
 export function renderChangelogOverlay() {
   const installedVersion = getInstalledPackageVersion(
-    new URL("..", import.meta.url).pathname,
+    fileURLToPath(new URL("..", import.meta.url)),
     "@pi-unipi/unipi",
   );
 
@@ -39,12 +40,7 @@ export function renderChangelogOverlay() {
       } else if (entry.version === installedVersion) {
         label = theme.fg("success", "✓ Current");
       } else {
-        const pa = entry.version.split(".").map(Number);
-        const pb = installedVersion.split(".").map(Number);
-        const isNewer =
-          pa[0]! > pb[0]! ||
-          (pa[0] === pb[0] && pa[1]! > pb[1]!) ||
-          (pa[0] === pb[0] && pa[1] === pb[1] && pa[2]! > pb[2]!);
+        const isNewer = compareVersions(entry.version, installedVersion) > 0;
         label = isNewer ? theme.fg("warning", "↑ New") : "";
       }
 

package/src/tui/update-overlay.ts

@@ -93,7 +93,7 @@ export function renderUpdateOverlay(checkResult: UpdateCheckResult, providedNewe
       state.installing = true;
       tui.requestRender();
 
-      const result = await installUpdate();
+      const result = await installUpdate(state.result.channel ?? "latest");
       if (result.success) {
         done({ updated: true });
       } else {

package/types.ts

@@ -20,6 +20,8 @@ export interface LastCheckCache {
   latestVersion: string;
   /** Version the user chose to skip */
   skippedVersion?: string;
+  /** npm dist-tag the check followed (absent in pre-UNI-262 caches = "latest") */
+  channel?: string;
 }
 
 /** A parsed changelog version entry */
@@ -54,6 +56,8 @@ export interface UpdateCheckResult {
   latestVersion: string;
   /** Currently installed version */
   currentVersion: string;
+  /** npm dist-tag this install follows ("alpha", "latest", …) */
+  channel?: string;
   /** Error message if check failed */
   error?: string;
 }