pi-jscpd 0.1.1 → 0.2.1

package/CHANGELOG.md

@@ -7,6 +7,22 @@ published releases use [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-09-06
+
+### Added
+
+- Added a quiet, TUI-only update warning using one bounded, best-effort npm
+  metadata check, with offline and environment-variable opt-outs.
+
+## [0.2.0] - 2026-09-06
+
+### Added
+
+- Added Pi-native compact and expanded transcript rendering for `jscpd_run`,
+  covering scan targets, status, findings, expected fail-open outcomes, and
+  bounded public details without exposing overlay-only or analyzer internals.
+- Added a monthly npm downloads badge to the README.
+
 ## [0.1.1] - 2026-09-05
 
 ### Changed
@@ -107,6 +123,8 @@ published releases use [Semantic Versioning](https://semver.org/).
 - Project paths, child output, reports, temporary directories, cancellation,
   configuration trust, and lifecycle cleanup are bounded and fail open.
 
-[Unreleased]: https://github.com/revazi/pi-jscpd/compare/v0.1.1...HEAD
+[Unreleased]: https://github.com/revazi/pi-jscpd/compare/v0.2.1...HEAD
+[0.2.1]: https://github.com/revazi/pi-jscpd/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/revazi/pi-jscpd/compare/v0.1.1...v0.2.0
 [0.1.1]: https://github.com/revazi/pi-jscpd/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/revazi/pi-jscpd/releases/tag/v0.1.0

package/README.md

@@ -2,6 +2,7 @@
 
 [![CI](https://github.com/revazi/pi-jscpd/actions/workflows/ci.yml/badge.svg)](https://github.com/revazi/pi-jscpd/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/pi-jscpd.svg)](https://www.npmjs.com/package/pi-jscpd)
+[![npm downloads](https://img.shields.io/npm/dm/pi-jscpd.svg)](https://www.npmjs.com/package/pi-jscpd)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 [![GitHub issues](https://img.shields.io/github/issues/revazi/pi-jscpd.svg)](https://github.com/revazi/pi-jscpd/issues)
 
@@ -31,6 +32,12 @@ Start Pi in your project and verify the setup:
 If no compatible binary is available, the extension stays dormant and Pi
 continues normally.
 
+In TUI sessions, the extension performs one best-effort, metadata-only npm check
+and shows a warning only when a newer `pi-jscpd` release is available. The check
+is bounded to 1.5 seconds, never sends project data, and never downloads or
+installs package content. Set `PI_JSCPD_DISABLE_UPDATE_NOTICE=1` (or run Pi
+offline) to disable it.
+
 ## Usage
 
 Run `/jscpd` to open the interactive overview. Opening it shows status only; it
@@ -57,7 +64,13 @@ Pi can use the same operations through the `jscpd_run` tool:
 ```
 
 Supported tool commands are `scan`, `changed`, `status`, `off`, `on`, and
-`help`. In TUI mode, `/jscpd ` provides subcommand autocomplete with labels and
+`help`. In TUI mode, tool calls use a compact native transcript view for clean,
+findings, unavailable, timeout, cancellation, status, and session-control
+results. Expanding a result shows only its bounded public terminal presentation;
+it never reveals analyzer output, temporary paths, source fragments, or the
+overlay-only finding cache.
+
+In TUI mode, `/jscpd ` provides subcommand autocomplete with labels and
 descriptions; selecting `scan` leaves the editor ready for an optional target.
 
 The package also exposes `/skill:jscpd`. Pi advertises only the skill's concise

package/docs/overlay-interaction.md

@@ -6,6 +6,21 @@ Applies to: bare `/jscpd` only
 
 Does not change: `/jscpd scan`, `/jscpd changed`, `/jscpd status`, session controls, or `jscpd_run`
 
+## Relationship to the tool transcript
+
+The `jscpd_run` agent tool has a separate Pi-native transcript renderer. Its
+collapsed call shows the operation, at most three bounded scan targets, any
+additional-target count, and Pi's project working directory. Collapsed results
+summarize clean, findings, unavailable, timeout, cancellation, fail-open,
+status, help, and session-control states without synthetic exit codes or timing
+placeholders. Expanding a result renders only the configured-limit public
+terminal presentation.
+
+Transcript rendering is display-only. It never reads source fragments, raw
+analyzer output, temporary report paths, environment values, internal
+fingerprints, or the overlay-only finding cache, and it does not change tool
+content, scans, acknowledgements, persistence, or cancellation.
+
 Overlay actions route through the extension's single managed runtime while Pi TUI
 rendering and input remain the host adapter. The implementation preserves every
 interaction below.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-jscpd",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "A Pi-native, polyglot duplication guardrail powered by jscpd.",
   "type": "module",
   "license": "MIT",

package/src/extension.ts

@@ -68,7 +68,9 @@ import {
   type JscpdSessionModeService,
   type JscpdStatusService,
 } from "./status.js";
+import { renderJscpdToolCall, renderJscpdToolResult } from "./tool-render.js";
 import type { JscpdCommandExecutor, JscpdDispatchResult } from "./types.js";
+import { createJscpdUpdateNoticeService, type JscpdUpdateNoticeService } from "./update-notice.js";
 import { createJscpdVerificationService, type JscpdVerificationService } from "./verification.js";
 
 type JscpdToolDefinition = ToolDefinition<typeof jscpdRunParams, JscpdDispatchResult>;
@@ -90,6 +92,7 @@ export interface JscpdExtensionOptions {
   overlayLauncher?: JscpdOverlayLauncher;
   verificationService?: JscpdVerificationService;
   fallowCoexistenceService?: JscpdFallowCoexistenceService;
+  updateNoticeService?: JscpdUpdateNoticeService;
 }
 
 export function registerJscpdExtension(
@@ -116,6 +119,7 @@ export function registerJscpdExtension(
   const configService = options.configService ?? createJscpdConfigService();
   const fallowCoexistence =
     options.fallowCoexistenceService ?? createJscpdFallowCoexistenceService();
+  const updateNotice = options.updateNoticeService ?? createJscpdUpdateNoticeService();
   const startOwnedBaseline = (context: JscpdBaselineStartContext): void => {
     const started = startBaselineQuietly(runtime, baselineService, context);
     baselineSettlement = Promise.all([baselineSettlement, started]).then(() => undefined);
@@ -210,7 +214,10 @@ export function registerJscpdExtension(
   );
 
   pi.on("session_start", async (_event, ctx) => {
-    if (ctx.mode === "tui") installJscpdAutocompleteProvider(ctx.ui);
+    if (ctx.mode === "tui") {
+      installJscpdAutocompleteProvider(ctx.ui);
+      scheduleJscpdUpdateNotice(runtime, updateNotice, ctx);
+    }
     runtime.runSync(scheduler.resetEffect);
     fallowCoexistence.reset();
     verificationService?.reset();
@@ -368,6 +375,20 @@ export function registerJscpdExtension(
   });
 }
 
+function scheduleJscpdUpdateNotice(
+  runtime: JscpdEffectRuntime,
+  service: JscpdUpdateNoticeService,
+  context: ExtensionContext,
+): void {
+  void runtime.runPromiseExit(
+    service.noticeEffect.pipe(
+      Effect.flatMap((message) =>
+        message ? Effect.sync(() => context.ui.notify(message, "warning")) : Effect.void,
+      ),
+    ),
+  );
+}
+
 function requestAutomaticCheck(
   runtime: JscpdEffectRuntime,
   pi: ExtensionAPI,
@@ -585,6 +606,12 @@ export function createJscpdToolDefinition(
         details: withoutOverlayCache(result),
       };
     },
+    renderCall(args, theme, context) {
+      return renderJscpdToolCall(args, theme, context.cwd);
+    },
+    renderResult(result, options, theme) {
+      return renderJscpdToolResult(result, options, theme);
+    },
   };
 }
 

package/src/tool-render.ts

@@ -0,0 +1,385 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import type { JscpdDispatchResult } from "./types.js";
+
+const MAX_CALL_TARGETS = 3;
+const MAX_TARGET_CHARACTERS = 120;
+const MAX_CWD_CHARACTERS = 180;
+const MAX_EXPANDED_CHARACTERS = 100_000;
+const MAX_EXPANDED_LINES = 512;
+const CAPABILITY_LABELS: Readonly<Record<string, string>> = {
+  missing: "analyzer missing",
+  incompatible: "analyzer incompatible",
+  cancelled: "probe cancelled",
+  "timed-out": "probe timed out",
+  failed: "probe failed",
+};
+const PUBLIC_RESULT_STATUSES = new Set([
+  "completed",
+  "unavailable",
+  "failed",
+  "status",
+  "control",
+  "help",
+  "changed",
+  "changed-unavailable",
+  "invalid",
+  "error",
+]);
+
+type ToolCallArgs = {
+  readonly command?: unknown;
+  readonly args?: unknown;
+};
+
+type ToolRenderResult = {
+  readonly details?: unknown;
+};
+
+type Tone = "success" | "warning" | "error" | "muted";
+
+interface CompactResult {
+  readonly tone: Tone;
+  readonly headline: string;
+  readonly metadata?: string;
+}
+
+type CompactRenderer = (details: JscpdDispatchResult) => CompactResult;
+
+const COMPACT_RENDERERS: Readonly<Record<JscpdDispatchResult["status"], CompactRenderer>> = {
+  completed: (details) =>
+    completedCompact(details as Extract<JscpdDispatchResult, { status: "completed" }>),
+  changed: (details) =>
+    changedCompact(details as Extract<JscpdDispatchResult, { status: "changed" }>),
+  unavailable: (details) =>
+    unavailableCompact((details as Extract<JscpdDispatchResult, { status: "unavailable" }>).reason),
+  "changed-unavailable": (details) =>
+    changedUnavailableCompact(
+      (details as Extract<JscpdDispatchResult, { status: "changed-unavailable" }>).reason,
+    ),
+  failed: (details) =>
+    failedCompact((details as Extract<JscpdDispatchResult, { status: "failed" }>).reason),
+  status: (details) => statusCompact(details as Extract<JscpdDispatchResult, { status: "status" }>),
+  control: (details) =>
+    controlCompact(details as Extract<JscpdDispatchResult, { status: "control" }>),
+  help: () => ({ tone: "muted", headline: "jscpd help" }),
+  invalid: (details) => ({
+    tone: "error",
+    headline: "Invalid jscpd request",
+    metadata: reasonLabel((details as Extract<JscpdDispatchResult, { status: "invalid" }>).reason),
+  }),
+  error: (details) => ({
+    tone: "error",
+    headline: "jscpd could not run",
+    metadata: reasonLabel((details as Extract<JscpdDispatchResult, { status: "error" }>).reason),
+  }),
+};
+
+/** Render the bounded jscpd operation, scan targets, and Pi-provided working directory. */
+export function renderJscpdToolCall(args: ToolCallArgs, theme: Theme, cwd: string): Text {
+  const command = jscpdCommand(args.command);
+  const targets = command === "scan" ? scanTargetSummary(args.args) : undefined;
+  const location = boundedInline(displayToken(cwd || "."), MAX_CWD_CHARACTERS);
+  const content = [
+    theme.fg("toolTitle", theme.bold("jscpd ")),
+    theme.fg("accent", command),
+    targets ? theme.fg("muted", ` ${targets}`) : "",
+    theme.fg("dim", ` in ${location}`),
+  ].join("");
+  return new Text(content, 0, 0);
+}
+
+/** Render only normalized public details; model content and overlay-only caches are never read. */
+export function renderJscpdToolResult(
+  result: ToolRenderResult,
+  options: { readonly expanded?: boolean; readonly isPartial?: boolean },
+  theme: Theme,
+): Text {
+  if (options.isPartial) {
+    return new Text(theme.fg("warning", "Running jscpd…"), 0, 0);
+  }
+
+  const details = publicDetails(result.details);
+  if (!details) {
+    return new Text(theme.fg("dim", "No jscpd result details"), 0, 0);
+  }
+
+  const compact = compactResult(details);
+  let content = theme.fg(compact.tone, compact.headline);
+  if (compact.metadata) content += theme.fg("dim", ` · ${compact.metadata}`);
+
+  if (options.expanded) {
+    const expanded = expandedPublicMessage(details);
+    if (expanded) content += `\n${styleExpandedMessage(expanded, theme)}`;
+  }
+
+  return new Text(content, 0, 0);
+}
+
+function publicDetails(value: unknown): JscpdDispatchResult | undefined {
+  if (!isRecord(value) || typeof value.status !== "string") return undefined;
+  return PUBLIC_RESULT_STATUSES.has(value.status)
+    ? (value as unknown as JscpdDispatchResult)
+    : undefined;
+}
+
+function compactResult(details: JscpdDispatchResult): CompactResult {
+  return COMPACT_RENDERERS[details.status](details);
+}
+
+function statusCompact(details: Extract<JscpdDispatchResult, { status: "status" }>): CompactResult {
+  const mode = details.mode === "enabled" || details.mode === "disabled" ? details.mode : "status";
+  return {
+    tone: mode === "enabled" ? "success" : "warning",
+    headline: mode === "status" ? "jscpd status unavailable" : `jscpd ${mode}`,
+    metadata: [capabilityLabel(details.capability), lastCheckLabel(details.lastCheck)].join(" · "),
+  };
+}
+
+function controlCompact(
+  details: Extract<JscpdDispatchResult, { status: "control" }>,
+): CompactResult {
+  const action =
+    details.action === "enabled" || details.action === "disabled" ? details.action : undefined;
+  return {
+    tone: action === "enabled" ? "success" : "warning",
+    headline: action ? `jscpd ${action} for this session` : "jscpd session state updated",
+  };
+}
+
+function completedCompact(
+  details: Extract<JscpdDispatchResult, { status: "completed" }>,
+): CompactResult {
+  if (details.outcome === "clean") {
+    const sources = safeCount(details.summary?.sources);
+    return {
+      tone: "success",
+      headline: "No duplicate blocks found",
+      metadata: sources === undefined ? undefined : plural(sources, "source"),
+    };
+  }
+
+  const clones = safeCount(details.summary?.clones) ?? findingTotal(details);
+  const duplicatedLines = safeCount(details.summary?.duplicatedLines);
+  return {
+    tone: "warning",
+    headline: `${plural(clones, "duplicate block")} found`,
+    metadata:
+      duplicatedLines === undefined ? undefined : `${plural(duplicatedLines, "duplicated line")}`,
+  };
+}
+
+function changedCompact(
+  details: Extract<JscpdDispatchResult, { status: "changed" }>,
+): CompactResult {
+  if (details.outcome === "clean") {
+    return {
+      tone: "success",
+      headline: details.scanPerformed
+        ? "No new duplicate blocks found"
+        : "No session changes to scan",
+      metadata: ambiguityLabel(details.ambiguousFindings),
+    };
+  }
+
+  return {
+    tone: "warning",
+    headline: `${plural(findingTotal(details), "new duplicate block")} found`,
+    metadata: ambiguityLabel(details.ambiguousFindings),
+  };
+}
+
+function unavailableCompact(reason: string): CompactResult {
+  switch (reason) {
+    case "probe-cancelled":
+      return { tone: "muted", headline: "jscpd check cancelled" };
+    case "probe-timed-out":
+      return { tone: "warning", headline: "jscpd check timed out" };
+    case "disabled":
+      return { tone: "warning", headline: "jscpd is disabled for this session" };
+    case "missing-binary":
+      return { tone: "warning", headline: "jscpd unavailable", metadata: "analyzer missing" };
+    case "incompatible-version":
+      return { tone: "warning", headline: "jscpd unavailable", metadata: "incompatible analyzer" };
+    default:
+      return { tone: "warning", headline: "jscpd unavailable", metadata: reasonLabel(reason) };
+  }
+}
+
+function changedUnavailableCompact(reason: string): CompactResult {
+  if (reason === "baseline-cancelled") {
+    return { tone: "muted", headline: "Changed check cancelled" };
+  }
+  if (reason === "baseline-timed-out") {
+    return { tone: "warning", headline: "Changed check timed out" };
+  }
+  return { tone: "warning", headline: "Changed check unavailable", metadata: reasonLabel(reason) };
+}
+
+function failedCompact(reason: string): CompactResult {
+  if (reason === "scan-cancelled") return { tone: "muted", headline: "jscpd scan cancelled" };
+  if (reason === "scan-timed-out") return { tone: "warning", headline: "jscpd scan timed out" };
+  return { tone: "warning", headline: "jscpd scan failed open", metadata: reasonLabel(reason) };
+}
+
+function capabilityLabel(value: unknown): string {
+  if (!isRecord(value) || typeof value.status !== "string") return "analyzer state unavailable";
+  if (value.status !== "available") {
+    return CAPABILITY_LABELS[value.status] ?? "analyzer state unavailable";
+  }
+
+  const executable = safeInline(value.executable) ?? "jscpd";
+  const version = safeInline(value.version);
+  const source =
+    value.source === "bundled"
+      ? "bundled"
+      : value.source === "project-or-path"
+        ? "project/PATH"
+        : undefined;
+  return [executable, version, source].filter(Boolean).join(" ");
+}
+
+function lastCheckLabel(value: unknown): string {
+  if (!isRecord(value) || typeof value.state !== "string") return "last check unavailable";
+  switch (value.state) {
+    case "never":
+      return "not checked yet";
+    case "clean":
+      return "last check clean";
+    case "findings": {
+      const clones = safeCount(value.clones);
+      return clones === undefined
+        ? "last check found duplication"
+        : `last check ${plural(clones, "block")}`;
+    }
+    case "cancelled":
+      return "last check cancelled";
+    case "failed":
+      return "last check failed";
+    default:
+      return "last check unavailable";
+  }
+}
+
+function expandedPublicMessage(details: JscpdDispatchResult): string | undefined {
+  const candidate =
+    "terminalMessage" in details && typeof details.terminalMessage === "string"
+      ? details.terminalMessage
+      : typeof details.message === "string"
+        ? details.message
+        : undefined;
+  if (!candidate) return undefined;
+  return boundedMultiline(candidate);
+}
+
+function styleExpandedMessage(message: string, theme: Theme): string {
+  return message
+    .split("\n")
+    .map((line) => theme.fg("muted", line))
+    .join("\n");
+}
+
+function scanTargetSummary(value: unknown): string | undefined {
+  if (!Array.isArray(value) || value.length === 0) return undefined;
+  const targets = value.filter((item): item is string => typeof item === "string");
+  if (targets.length === 0) return undefined;
+  const visible = targets
+    .slice(0, MAX_CALL_TARGETS)
+    .map((target) => boundedInline(displayToken(target), MAX_TARGET_CHARACTERS));
+  if (targets.length > visible.length) visible.push(`… +${targets.length - visible.length}`);
+  return visible.join(" ");
+}
+
+function jscpdCommand(value: unknown): string {
+  switch (value) {
+    case "scan":
+    case "changed":
+    case "status":
+    case "off":
+    case "on":
+    case "help":
+      return value;
+    default:
+      return "run";
+  }
+}
+
+function findingTotal(details: {
+  readonly findings?: unknown;
+  readonly omittedFindings?: unknown;
+}): number {
+  const shown = Array.isArray(details.findings) ? details.findings.length : 0;
+  return shown + (safeCount(details.omittedFindings) ?? 0);
+}
+
+function ambiguityLabel(value: unknown): string | undefined {
+  const count = safeCount(value);
+  return count && count > 0 ? plural(count, "unclassified block") : undefined;
+}
+
+function safeCount(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
+
+function safeInline(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0
+    ? boundedInline(displayToken(value), MAX_TARGET_CHARACTERS)
+    : undefined;
+}
+
+function displayToken(value: string): string {
+  const safeValue = escapeControlCharacters(value, false);
+  return /^[\p{L}\p{N}_./@:+~-]+$/u.test(safeValue) ? safeValue : JSON.stringify(safeValue);
+}
+
+function boundedInline(value: string, maximum: number): string {
+  const characters = Array.from(value);
+  if (characters.length <= maximum) return value;
+  const retained = maximum - 1;
+  const beginning = Math.ceil(retained / 2);
+  const ending = Math.floor(retained / 2);
+  return `${characters.slice(0, beginning).join("")}…${characters.slice(-ending).join("")}`;
+}
+
+function boundedMultiline(value: string): string {
+  const sanitized = escapeControlCharacters(
+    value.replaceAll("\r\n", "\n").replaceAll("\r", "\n"),
+    true,
+  );
+  const sourceLines = sanitized.split("\n");
+  const lines = sourceLines.slice(0, MAX_EXPANDED_LINES);
+  let result = Array.from(lines.join("\n")).slice(0, MAX_EXPANDED_CHARACTERS).join("");
+  if (
+    sourceLines.length > lines.length ||
+    Array.from(lines.join("\n")).length > MAX_EXPANDED_CHARACTERS
+  ) {
+    result += "\n… transcript detail truncated";
+  }
+  return result;
+}
+
+function escapeControlCharacters(value: string, preserveNewlines: boolean): string {
+  return Array.from(value)
+    .map((character) => {
+      if (preserveNewlines && character === "\n") return character;
+      const codePoint = character.codePointAt(0) ?? 0;
+      return codePoint < 32 || (codePoint >= 127 && codePoint <= 159)
+        ? `\\u${codePoint.toString(16).padStart(4, "0")}`
+        : character;
+    })
+    .join("");
+}
+
+function reasonLabel(value: unknown): string {
+  return typeof value === "string" && value.length > 0
+    ? boundedInline(escapeControlCharacters(value.replaceAll("-", " "), false), 80)
+    : "details unavailable";
+}
+
+function plural(count: number, singular: string): string {
+  return `${count} ${singular}${count === 1 ? "" : "s"}`;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}

package/src/update-notice.ts

@@ -0,0 +1,194 @@
+import { readFile } from "node:fs/promises";
+import { get } from "node:https";
+import { Effect } from "effect";
+
+const PACKAGE_NAME = "pi-jscpd";
+const PACKAGE_JSON_URL = new URL("../package.json", import.meta.url);
+const NPM_LATEST_URL = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
+const UPDATE_COMMAND = `pi update npm:${PACKAGE_NAME}`;
+const DISABLE_UPDATE_ENV = "PI_JSCPD_DISABLE_UPDATE_NOTICE";
+const UPDATE_CHECK_ENV = "PI_JSCPD_UPDATE_CHECK";
+const UPDATE_CHECK_TIMEOUT_MS = 1_500;
+const MAX_RESPONSE_BYTES = 16 * 1_024;
+const VERSION_PATTERN =
+  /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+
+interface JscpdUpdateNoticeOptions {
+  readonly environment?: Readonly<Record<string, string | undefined>>;
+  readonly currentVersionEffect?: Effect.Effect<string | undefined, unknown>;
+  readonly latestVersionEffect?: Effect.Effect<string | undefined, unknown>;
+  readonly timeoutMs?: number;
+}
+
+export interface JscpdUpdateNoticeService {
+  /** Resolve at most one warning for this extension instance; failures stay silent. */
+  readonly noticeEffect: Effect.Effect<string | undefined>;
+}
+
+/** Best-effort npm metadata check. It never downloads or installs package content. */
+export function createJscpdUpdateNoticeService(
+  options: JscpdUpdateNoticeOptions = {},
+): JscpdUpdateNoticeService {
+  const environment = options.environment ?? process.env;
+  let shown = false;
+
+  return {
+    noticeEffect: Effect.suspend(() => {
+      if (shown || isUpdateCheckDisabled(environment)) return Effect.succeed(undefined);
+      shown = true;
+
+      const currentVersion = recoverLookup(
+        options.currentVersionEffect ?? readCurrentVersionEffect(),
+      );
+      const latestVersion = recoverLookup(
+        options.latestVersionEffect ?? fetchLatestVersionEffect(),
+      ).pipe(
+        Effect.timeoutTo({
+          duration: options.timeoutMs ?? UPDATE_CHECK_TIMEOUT_MS,
+          onSuccess: (version) => version,
+          onTimeout: () => undefined,
+        }),
+      );
+
+      return currentVersion.pipe(
+        Effect.flatMap((current) =>
+          current
+            ? latestVersion.pipe(Effect.map((latest) => buildUpdateNotice(current, latest)))
+            : Effect.succeed(undefined),
+        ),
+      );
+    }),
+  };
+}
+
+function readCurrentVersionEffect(): Effect.Effect<string | undefined, Error> {
+  return Effect.tryPromise({
+    try: () => readFile(PACKAGE_JSON_URL, "utf8"),
+    catch: () => new Error("Unable to read package metadata."),
+  }).pipe(Effect.map(parsePackageVersion));
+}
+
+function parsePackageVersion(source: string): string | undefined {
+  try {
+    const value = JSON.parse(source) as { version?: unknown };
+    return typeof value.version === "string" && VERSION_PATTERN.test(value.version)
+      ? value.version
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function fetchLatestVersionEffect(): Effect.Effect<string | undefined, Error> {
+  return Effect.async((resume) => {
+    let settled = false;
+    const settle = (effect: Effect.Effect<string | undefined, Error>): void => {
+      if (settled) return;
+      settled = true;
+      resume(effect);
+    };
+    const request = get(NPM_LATEST_URL, { headers: { accept: "application/json" } }, (response) => {
+      if (response.statusCode !== 200) {
+        response.resume();
+        settle(Effect.succeed(undefined));
+        return;
+      }
+
+      const declaredLength = Number(response.headers["content-length"]);
+      if (Number.isFinite(declaredLength) && declaredLength > MAX_RESPONSE_BYTES) {
+        response.destroy();
+        settle(Effect.succeed(undefined));
+        return;
+      }
+
+      const chunks: Uint8Array[] = [];
+      let total = 0;
+      response.on("data", (value: Buffer) => {
+        total += value.byteLength;
+        if (total > MAX_RESPONSE_BYTES) {
+          response.destroy();
+          settle(Effect.succeed(undefined));
+          return;
+        }
+        chunks.push(value);
+      });
+      response.once("end", () => {
+        settle(Effect.succeed(parseLatestVersionBytes(chunks, total)));
+      });
+      response.once("error", () => {
+        settle(Effect.fail(new Error("Unable to read npm package metadata.")));
+      });
+    });
+    request.once("error", () => {
+      settle(Effect.fail(new Error("Unable to check npm package metadata.")));
+    });
+
+    return Effect.sync(() => {
+      settled = true;
+      request.destroy();
+    });
+  });
+}
+
+function parseLatestVersionBytes(chunks: readonly Uint8Array[], total: number): string | undefined {
+  try {
+    const bytes = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+      bytes.set(chunk, offset);
+      offset += chunk.byteLength;
+    }
+    const source = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    const value = JSON.parse(source) as { version?: unknown };
+    return typeof value.version === "string" && VERSION_PATTERN.test(value.version)
+      ? value.version
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function recoverLookup(
+  effect: Effect.Effect<string | undefined, unknown>,
+): Effect.Effect<string | undefined> {
+  return effect.pipe(Effect.catchAll(() => Effect.succeed(undefined)));
+}
+
+function buildUpdateNotice(
+  currentVersion: string,
+  latestVersion: string | undefined,
+): string | undefined {
+  if (!latestVersion || compareVersions(latestVersion, currentVersion) <= 0) return undefined;
+  return `${PACKAGE_NAME} ${latestVersion} is available (you have ${currentVersion}). Update: ${UPDATE_COMMAND}`;
+}
+
+function compareVersions(left: string, right: string): number {
+  const leftMatch = VERSION_PATTERN.exec(left);
+  const rightMatch = VERSION_PATTERN.exec(right);
+  if (!leftMatch || !rightMatch) return 0;
+
+  for (let index = 1; index <= 3; index += 1) {
+    const difference = Number(leftMatch[index]) - Number(rightMatch[index]);
+    if (difference !== 0) return Math.sign(difference);
+  }
+
+  const leftPrerelease = left.includes("-");
+  const rightPrerelease = right.includes("-");
+  if (leftPrerelease === rightPrerelease) return 0;
+  return leftPrerelease ? -1 : 1;
+}
+
+function isUpdateCheckDisabled(environment: Readonly<Record<string, string | undefined>>): boolean {
+  const offline = environment.PI_OFFLINE;
+  if (offline !== undefined && !isFalseLike(offline)) return true;
+
+  const disabled = environment[DISABLE_UPDATE_ENV];
+  if (disabled !== undefined) return !isFalseLike(disabled);
+
+  const enabled = environment[UPDATE_CHECK_ENV];
+  return enabled !== undefined && isFalseLike(enabled);
+}
+
+function isFalseLike(value: string): boolean {
+  return ["0", "false", "off", "no"].includes(value.toLocaleLowerCase());
+}