mirror-mind 0.33.0 → 0.33.2

package/ts/src/runtime/releaseNotes.ts

@@ -1,20 +1,36 @@
 // Release-note reading for the runtime surface (CV22.DS7.TS3, plateau 2).
 // Port of the release-note half of `src/memory/cli/runtime.py`.
 //
-// Two sources, one document shape. The working tree answers "what does this
-// checkout contain"; a git ref answers "what does the channel contain that I
-// have not merged", which is the question `release-notes pending` exists for
-// and the reason this path shells out to `ls-tree`/`show` instead of reading
-// files. Ordering is by semantic version everywhere: `v0.10.0` follows
-// `v0.9.0`, which a lexical sort gets backwards.
+// Three sources, one document shape. A tree answers "what does this tree
+// contain": `docs/releases` under the root the caller names, read as files
+// with no git call -- the caller passes the running tree, which for a package
+// may sit inside a git work tree it does not own, such as Homebrew's prefix
+// (CR133). The other two answer `release-notes pending`, "what does my channel
+// hold that I do not", for the install that is running and never for the cwd
+// (CR134): a clone's git ref, read in the clone's own repository -- the only
+// path here that shells out to git -- and a package's channel version,
+// resolved by the registry and read from that version's tarball in memory.
+// Ordering is by semantic version everywhere: `v0.10.0` follows `v0.9.0`,
+// which a lexical sort gets backwards.
 //
-// `fetch` is the one command here that writes anything — remote-tracking refs,
-// never the worktree — and only when `release-notes pending` is allowed to
-// refresh. Everything else reads.
+// When no source answers, the bundle says so -- `unknown`, with a reason --
+// rather than `none`, which means a source answered and held nothing newer.
+//
+// `fetch` writes remote-tracking refs in the clone, never its worktree, and
+// `npm pack` one tarball into a private directory removed after the read.
+// Everything else reads.
 
-import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { basename, join, resolve } from "node:path";
+import {
+  channelDirection,
+  type NpmRunner,
+  type PackageInstall,
+  packTarball,
+} from "#runtime/strategies/package.ts";
 import { compareSemver } from "#util/semver.ts";
+import { MAX_INFLATED_BYTES, readTarGzEntries } from "#util/tarEntries.ts";
 import { GIT_NETWORK_TIMEOUT_MS, runGit } from "./git.ts";
 
 export interface ReleaseNote {
@@ -29,6 +45,8 @@ export interface ReleaseNotesBundle {
   notes: ReleaseNote[];
   current_version: string | null;
   source: string | null;
+  /** Why no source answered; null when one did, with notes or with none (CR134). */
+  unknown_reason: string | null;
 }
 
 const NOTE_NAME = /^v\d+\.\d+\.\d+\.md$/;
@@ -99,15 +117,13 @@ export function releaseNoteFromText(path: string, text: string): ReleaseNote {
   };
 }
 
-function repositoryFor(start: string): string {
-  const startPath = resolve(start);
-  const top = runGit(["rev-parse", "--show-toplevel"], startPath);
-  return top.code === 0 && top.stdout ? top.stdout : startPath;
-}
-
-/** Notes in the working tree, ordered by semantic version. */
-export function readReleaseNotes(start: string): ReleaseNote[] {
-  const dir = join(repositoryFor(start), "docs", "releases");
+/**
+ * Notes under `<root>/docs/releases`, ordered by semantic version. The root is
+ * read as given: asking git for its repository would climb out of a package
+ * installed under a prefix that is itself a work tree (CR133).
+ */
+export function readReleaseNotes(root: string): ReleaseNote[] {
+  const dir = join(resolve(root), "docs", "releases");
   if (!existsSync(dir)) return [];
   return readdirSync(dir)
     .filter((name) => NOTE_NAME.test(name))
@@ -118,58 +134,104 @@ export function readReleaseNotes(start: string): ReleaseNote[] {
     });
 }
 
-export function readReleaseNote(version: string, start: string): ReleaseNote | null {
-  const notes = readReleaseNotes(start);
+export function readReleaseNote(version: string, root: string): ReleaseNote | null {
+  const notes = readReleaseNotes(root);
   if (version === "latest")
     return notes.length > 0 ? (notes[notes.length - 1] as ReleaseNote) : null;
   const wanted = version.startsWith("v") ? version : `v${version}`;
   return notes.find((note) => note.version === wanted) ?? null;
 }
 
-function refNoteNames(ref: string, repository: string): string[] {
-  const listed = runGit(["ls-tree", "-r", "--name-only", ref, "docs/releases"], repository);
-  if (listed.code !== 0 || !listed.stdout) return [];
-  return listed.stdout
+/**
+ * A ref is user-supplied (`--ref`), and git takes an argument that begins with
+ * `-` as an option, `--upload-pack=<command>` among them (CR134). Such a ref is
+ * refused before git runs, and every verb below also puts `--end-of-options`
+ * before its operands, which covers the half of a ref after its first slash.
+ */
+function refusedRef(ref: string): string | null {
+  if (ref === "") return "no ref was named";
+  if (ref.startsWith("-")) return `ref ${JSON.stringify(ref)} begins with '-' and is refused`;
+  return null;
+}
+
+function firstLine(text: string): string {
+  return (
+    text
+      .split("\n")
+      .find((line) => line.trim() !== "")
+      ?.trim() ?? ""
+  );
+}
+
+type RefNames = { ok: true; names: string[] } | { ok: false; detail: string };
+
+/** The note paths at `ref`. A ref that does not resolve is said, not read as empty. */
+function refNoteNames(ref: string, repository: string): RefNames {
+  const refused = refusedRef(ref);
+  if (refused !== null) return { ok: false, detail: refused };
+  const listed = runGit(
+    ["ls-tree", "-r", "--name-only", "--end-of-options", ref, "docs/releases"],
+    repository,
+  );
+  if (listed.code !== 0) return { ok: false, detail: `ref ${ref} does not resolve` };
+  const names = listed.stdout
     .split("\n")
     .map((line) => line.trim())
     .filter((line) => REF_NOTE_PATH.test(line));
+  return { ok: true, names };
+}
+
+function showAtRef(ref: string, path: string, repository: string): string | null {
+  const shown = runGit(["show", "--end-of-options", `${ref}:${path}`], repository);
+  return shown.code === 0 && shown.stdout ? shown.stdout : null;
 }
 
-/** Notes as the ref has them — what a channel contains, merged or not. */
-export function readReleaseNotesFromRef(ref: string, start: string): ReleaseNote[] {
-  const repository = repositoryFor(start);
-  const names = refNoteNames(ref, repository).sort((a, b) =>
+type RefNotes = { ok: true; notes: ReleaseNote[] } | { ok: false; detail: string };
+
+function readRefNotes(ref: string, repository: string): RefNotes {
+  const listed = refNoteNames(ref, repository);
+  if (!listed.ok) return listed;
+  const names = listed.names.sort((a, b) =>
     compareSemver(basename(a).replace(/\.md$/, ""), basename(b).replace(/\.md$/, "")),
   );
   const notes: ReleaseNote[] = [];
   for (const selected of names) {
-    const shown = runGit(["show", `${ref}:${selected}`], repository);
-    if (shown.code !== 0 || !shown.stdout) continue;
-    notes.push(releaseNoteFromText(selected, shown.stdout));
+    const text = showAtRef(ref, selected, repository);
+    if (text !== null) notes.push(releaseNoteFromText(selected, text));
   }
-  return notes;
+  return { ok: true, notes };
+}
+
+/**
+ * Notes as the ref has them — what a channel contains, merged or not — in the
+ * repository given, never one discovered from a cwd (CR134). A ref that does
+ * not resolve yields none here; `buildPendingReleaseNotes` says why.
+ */
+export function readReleaseNotesFromRef(ref: string, repository: string): ReleaseNote[] {
+  const read = readRefNotes(ref, resolve(repository));
+  return read.ok ? read.notes : [];
 }
 
 export function readReleaseNoteFromRef(
   ref: string,
   version: string,
-  start: string,
+  repository: string,
 ): ReleaseNote | null {
-  const repository = repositoryFor(start);
+  const root = resolve(repository);
   let selected: string;
   if (version === "latest") {
-    const names = refNoteNames(ref, repository);
-    if (names.length === 0) return null;
-    selected = names.sort((a, b) =>
+    const listed = refNoteNames(ref, root);
+    if (!listed.ok || listed.names.length === 0) return null;
+    selected = listed.names.sort((a, b) =>
       compareSemver(basename(b).replace(/\.md$/, ""), basename(a).replace(/\.md$/, "")),
     )[0] as string;
   } else {
+    if (refusedRef(ref) !== null) return null;
     const wanted = version.startsWith("v") ? version : `v${version}`;
     selected = `docs/releases/${wanted}.md`;
   }
-  const shown = runGit(["show", `${ref}:${selected}`], repository);
-  if (shown.code !== 0 || !shown.stdout) return null;
-  return releaseNoteFromText(selected, shown.stdout);
+  const text = showAtRef(ref, selected, root);
+  return text === null ? null : releaseNoteFromText(selected, text);
 }
 
 /** Port of `_normalize_version`: drop a leading `v`, keep the rest. */
@@ -178,30 +240,141 @@ export function normalizeVersion(version: string): string {
   return trimmed.startsWith("v") ? trimmed.slice(1) : trimmed;
 }
 
-/** Refresh the channel ref before reading it. The only write in this module. */
-export function fetchReleaseNotesRef(ref: string, repository: string): void {
+export type RefFetch =
+  | { kind: "skipped" }
+  | { kind: "fetched" }
+  | { kind: "failed"; detail: string };
+
+/**
+ * Refresh the channel ref before reading it: `git fetch <remote> <branch>` for
+ * a ref shaped `<remote>/<branch>`, in the clone's own repository. A ref with
+ * no remote part, such as `HEAD`, has nothing to fetch, and a refused ref never
+ * reaches git.
+ */
+export function fetchReleaseNotesRef(ref: string, repository: string): RefFetch {
+  if (refusedRef(ref) !== null) return { kind: "skipped" };
   const slash = ref.indexOf("/");
-  if (slash <= 0 || slash === ref.length - 1) return;
+  if (slash <= 0 || slash === ref.length - 1) return { kind: "skipped" };
   const remote = ref.slice(0, slash);
   const branch = ref.slice(slash + 1);
-  runGit(["fetch", remote, branch], repository, GIT_NETWORK_TIMEOUT_MS);
+  const fetched = runGit(
+    ["fetch", "--end-of-options", remote, branch],
+    repository,
+    GIT_NETWORK_TIMEOUT_MS,
+  );
+  if (fetched.code === 0) return { kind: "fetched" };
+  return {
+    kind: "failed",
+    detail: firstLine(fetched.stderr) || `git fetch exited ${fetched.code}`,
+  };
+}
+
+/** A bundle no source answered: `Pending releases: unknown`, and why. */
+export function unknownReleaseNotes(
+  currentVersion: string,
+  source: string | null,
+  reason: string,
+): ReleaseNotesBundle {
+  return {
+    notes: [],
+    current_version: `v${normalizeVersion(currentVersion)}`,
+    source,
+    unknown_reason: reason,
+  };
 }
 
 export interface PendingOptions {
   currentVersion: string;
   ref: string;
-  start: string;
+  /** The install's own checkout, used as given: never discovered from a cwd (CR134). */
+  repository: string;
   fetch: boolean;
 }
 
+/**
+ * A clone's pending notes: the releases at `ref` newer than the installed
+ * version. A fetch that fails is `unknown`, not a quiet read of a stale ref;
+ * `--no-fetch` is how to ask for the ref as last fetched (CR134, decision 2).
+ */
 export function buildPendingReleaseNotes(options: PendingOptions): ReleaseNotesBundle {
-  const repository = repositoryFor(options.start);
+  const repository = resolve(options.repository);
   const current = normalizeVersion(options.currentVersion);
-  if (options.fetch) fetchReleaseNotesRef(options.ref, repository);
-  const notes = readReleaseNotesFromRef(options.ref, repository).filter((note) =>
-    isNewer(note.version, current),
-  );
-  return { notes, current_version: `v${current}`, source: options.ref };
+  const unknown = (reason: string) => unknownReleaseNotes(current, options.ref, reason);
+  const refused = refusedRef(options.ref);
+  if (refused !== null) return unknown(refused);
+  if (options.fetch) {
+    const fetched = fetchReleaseNotesRef(options.ref, repository);
+    if (fetched.kind === "failed") return unknown(`fetch failed: ${fetched.detail}`);
+  }
+  const read = readRefNotes(options.ref, repository);
+  if (!read.ok) return unknown(read.detail);
+  return {
+    notes: read.notes.filter((note) => isNewer(note.version, current)),
+    current_version: `v${current}`,
+    source: options.ref,
+    unknown_reason: null,
+  };
+}
+
+export interface RegistryPendingOptions {
+  currentVersion: string;
+  install: PackageInstall;
+  channel: string;
+  npm: NpmRunner;
+}
+
+const TARBALL_NOTE = /^package\/docs\/releases\/v\d+\.\d+\.\d+\.md$/;
+
+/**
+ * A package's pending notes (CR134). The registry resolves the channel's
+ * dist-tag to a version, as `runtime update` does at plan. When that version is
+ * ahead, its exact tarball is fetched into a private directory and the notes
+ * are read in memory, within the reader's bound; when it is current or behind,
+ * nothing is downloaded. Every npm call runs in the install's root (CR135).
+ */
+export function buildPendingReleaseNotesFromRegistry(
+  options: RegistryPendingOptions,
+): ReleaseNotesBundle {
+  const { install, channel, npm } = options;
+  const current = normalizeVersion(options.currentVersion);
+  const tag = `npm ${install.name}@${channel}`;
+  const direction = channelDirection({ ...install, version: current }, channel, npm);
+  if (direction.kind === "unresolved") return unknownReleaseNotes(current, tag, direction.detail);
+  const target = direction.version;
+  const source = `${tag} (${target})`;
+  if (direction.kind !== "ahead") {
+    return { notes: [], current_version: `v${current}`, source, unknown_reason: null };
+  }
+
+  const destination = mkdtempSync(join(tmpdir(), "mirror-release-notes-"));
+  try {
+    const packed = packTarball(install.name, target, install.root, destination, npm);
+    if (!packed.ok) return unknownReleaseNotes(current, source, packed.detail);
+    // The compressed file is read whole before it is inflated, so it is bounded too.
+    if (statSync(packed.path).size > MAX_INFLATED_BYTES) {
+      return unknownReleaseNotes(
+        current,
+        source,
+        `the tarball is larger than ${MAX_INFLATED_BYTES} bytes`,
+      );
+    }
+    const read = readTarGzEntries(readFileSync(packed.path), (name) => TARBALL_NOTE.test(name));
+    if (!read.ok) return unknownReleaseNotes(current, source, read.detail);
+    const notes = [...read.entries]
+      .sort(([a], [b]) =>
+        compareSemver(basename(a).replace(/\.md$/, ""), basename(b).replace(/\.md$/, "")),
+      )
+      .map(([name, bytes]) =>
+        releaseNoteFromText(
+          `${install.name}@${target}:${name.slice("package/".length)}`,
+          bytes.toString("utf8"),
+        ),
+      )
+      .filter((note) => isNewer(note.version, current));
+    return { notes, current_version: `v${current}`, source, unknown_reason: null };
+  } finally {
+    rmSync(destination, { recursive: true, force: true });
+  }
 }
 
 export function renderReleaseNote(note: ReleaseNote | null): string {
@@ -226,6 +399,11 @@ export function renderReleaseNotesBundle(bundle: ReleaseNotesBundle): string {
   const lines = ["Mirror runtime release notes", ""];
   if (bundle.current_version) lines.push(`Current version: ${bundle.current_version}`);
   if (bundle.source) lines.push(`Source: ${bundle.source}`);
+  if (bundle.unknown_reason !== null) {
+    lines.push("Pending releases: unknown");
+    lines.push(`Reason: ${bundle.unknown_reason}`);
+    return `${lines.join("\n")}\n`;
+  }
   if (bundle.notes.length === 0) {
     lines.push("Pending releases: none");
     return `${lines.join("\n")}\n`;

package/ts/src/runtime/status.ts

@@ -26,16 +26,21 @@ import { inspectMigrationFiles } from "#extensions/migrations.ts";
 import { type DbPathEnv, dbNameForEnv, resolveMirrorHome } from "#frontDoor/dbPath.ts";
 import { DEFAULT_EMBEDDING_MODEL, DEFAULT_EXTRACTION_MODEL } from "#providers/config.ts";
 import { sortByCodePoint } from "#util/pythonText.ts";
-import { channelFor } from "./channel.ts";
+import { channelForReport } from "./channel.ts";
 import type { MarkerValue } from "./git.ts";
 import {
+  cloneRoleFor,
   type GitStatus,
-  inspectCloneRole,
   inspectGitFor,
-  inspectUpdateChannel,
+  renderCloneRoleLines,
   renderRepositoryLines,
 } from "./git.ts";
-import { detectInstallKind, type InstallKind, renderInstallLines } from "./installKind.ts";
+import {
+  detectInstallKind,
+  type InstallKind,
+  inspectionRootFor,
+  renderInstallLines,
+} from "./installKind.ts";
 
 export interface CoreMigrationHealth {
   ready: boolean;
@@ -339,6 +344,11 @@ export function detectNodeVersion(): string | null {
 }
 
 export interface BuildStatusOptions {
+  /**
+   * An explicit repository to inspect. Absent, the install's own: a clone's
+   * checkout, and for anything else none (CR138). It used to default to the
+   * cwd, which for a skill is the person's project.
+   */
   start?: string;
   mirrorHome?: string | null;
   channel?: string | null;
@@ -354,21 +364,6 @@ export interface BuildStatusOptions {
   install?: InstallKind;
 }
 
-/**
- * The channel the report shows. A clone is inspected at `start`, as the
- * oracle did and `version --start PATH` still means; a package has no tree at
- * `start` and keeps its channel in the user's config file (US3 D9).
- */
-function channelForStatus(
-  install: InstallKind,
-  startPath: string,
-  override: string | null,
-  env: NodeJS.ProcessEnv,
-): MarkerValue {
-  if (install.kind === "package") return channelFor(install, env, undefined, override);
-  return inspectUpdateChannel(startPath, override);
-}
-
 /**
  * Python's `resolve_mirror_home` raises `ValueError`, and
  * `build_runtime_status` prints `str(exc)` as `Mirror home note:`. The front
@@ -394,16 +389,17 @@ function mirrorHomeForStatus(env: DbPathEnv): { home: string | null; error: stri
 
 /** Port of `build_runtime_status`. */
 export function buildRuntimeStatus(options: BuildStatusOptions = {}): RuntimeStatusReport {
-  const startPath = resolve(options.start ?? process.cwd());
   const env = options.env ?? process.env;
   const install =
     options.install ??
     detectInstallKind({ frontDoorPath: new URL("../frontDoor/cli.ts", import.meta.url).pathname });
-  // The git facts are a clone's. A package has no repository, and grading the
-  // cwd as one read "not a git repository" as a git error, said `attention
-  // needed`, and so refused every package update at the gate (CV22.DS10.US3
-  // plateau 4, found by the package lane of the update smoke).
-  const git = inspectGitFor(install, startPath);
+  // The repository rows are the install's own, or the one `start` names; never
+  // the cwd's (CR138). The git facts are a clone's: a package has no
+  // repository, and grading the cwd as one read "not a git repository" as a git
+  // error, said `attention needed`, and so refused every package update at the
+  // gate (CV22.DS10.US3 plateau 4, found by the package lane of the update smoke).
+  const root = inspectionRootFor(install, options.start);
+  const git = inspectGitFor(install, root);
 
   let mirrorHome: string | null;
   let mirrorHomeError: string | null;
@@ -430,9 +426,9 @@ export function buildRuntimeStatus(options: BuildStatusOptions = {}): RuntimeSta
     core_migrations: inspectCoreMigrations(dbPath, dbExists),
     extensions: listInstalledExtensions(mirrorHome),
     extension_health: inspectExtensionHealth(mirrorHome, dbPath, dbExists),
-    clone_role: inspectCloneRole(startPath),
+    clone_role: cloneRoleFor(install, root),
     memory_env: memoryEnv,
-    update_channel: channelForStatus(install, startPath, options.channel ?? null, env),
+    update_channel: channelForReport(install, root, env, undefined, options.channel ?? null),
     node_version: options.nodeVersion === undefined ? detectNodeVersion() : options.nodeVersion,
   };
 }
@@ -533,8 +529,7 @@ export function renderRuntimeStatus(
     lines.push("Installed extensions: 0");
   }
   lines.push(...renderExtensionHealth(report.extension_health));
-  lines.push(`Clone role: ${report.clone_role.value}`);
-  if (report.clone_role.note) lines.push(`Clone role note: ${report.clone_role.note}`);
+  lines.push(...renderCloneRoleLines(report.install, report.clone_role));
   lines.push(`Update channel: ${report.update_channel.value}`);
   if (report.update_channel.note) lines.push(`Update channel note: ${report.update_channel.note}`);
   lines.push(`Node: ${report.node_version || "not found (TS front door requires Node >= 24)"}`);

package/ts/src/runtime/strategies/clone.ts

@@ -9,15 +9,18 @@
 // decisions can be driven in tests without a remote, and so this module can be
 // read as "what we ask git for" rather than "how we spawn it".
 
-import { runGit } from "#runtime/git.ts";
+import { GIT_NETWORK_TIMEOUT_MS, runGit } from "#runtime/git.ts";
 import type { ApplyStrategy } from "#runtime/updatePipeline.ts";
 
+/** Without a timeout, a command gets `runGit`'s local budget. */
 export type GitRunner = (
   args: readonly string[],
   cwd: string,
+  timeoutMs?: number,
 ) => { code: number; stdout: string; stderr: string };
 
-export const defaultGitRunner: GitRunner = (args, cwd) => runGit([...args], cwd);
+export const defaultGitRunner: GitRunner = (args, cwd, timeoutMs) =>
+  runGit([...args], cwd, timeoutMs);
 
 /** `origin/main` -> `["origin", "main"]`; anything else is refused. */
 export function splitUpstream(upstream: string): [string, string] | null {
@@ -44,7 +47,11 @@ export function fetchUpstream(
   const split = splitUpstream(upstream);
   if (split === null) return { ok: false, detail: "unexpected upstream name" };
   const [remote, branch] = split;
-  const result = git(["fetch", remote, branch], repository);
+  // The one command here that crosses the network, so it gets the network
+  // budget (CR132). On the 2-second local budget a fetch still in flight was
+  // killed and reported failed. The oracle's `_git_fetch` had this since
+  // 521177f8, and the port lost it. Both update lanes run this fetch.
+  const result = git(["fetch", remote, branch], repository, GIT_NETWORK_TIMEOUT_MS);
   return result.code === 0
     ? { ok: true, detail: `${remote} ${branch}` }
     : { ok: false, detail: result.stderr.trim() || "fetch failed" };