mirror-mind 0.33.0 → 0.33.2

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

@@ -11,29 +11,53 @@
 // the pipeline's decisions are testable without a registry.
 
 import { execFileSync } from "node:child_process";
+import { basename, join } from "node:path";
 import { type ApplyStrategy, KNOWN_CHANNELS } from "#runtime/updatePipeline.ts";
 import { compareSemver, isPlainSemver } from "#util/semver.ts";
 
-/** `cwd` matters to the one npm command that reads a tree, `publish`; the rest ignore it. */
+/**
+ * Where and how long one npm command runs.
+ *
+ * `cwd` is a trust decision, not a convenience (CR135). npm reads the project
+ * config of the directory it runs in -- the `.npmrc` beside the nearest
+ * `package.json` -- so a command started in the person's project takes its
+ * `registry=` and `prefix=` from whatever that project ships. Every call the
+ * product makes names its directory: the install's own root for the package's
+ * commands, the release's repository for `publish`.
+ */
+export interface NpmCall {
+  cwd?: string;
+  /** Kill npm after this long. Absent, npm runs until it answers. */
+  timeoutMs?: number;
+}
+
 export type NpmRunner = (
   args: readonly string[],
-  cwd?: string,
+  call?: NpmCall,
 ) => {
   code: number;
   stdout: string;
   stderr: string;
 };
 
-export const defaultNpmRunner: NpmRunner = (args, cwd) => {
+export const defaultNpmRunner: NpmRunner = (args, call = {}) => {
   try {
     const stdout = execFileSync("npm", [...args], {
       encoding: "utf8",
       stdio: ["ignore", "pipe", "pipe"],
-      ...(cwd === undefined ? {} : { cwd }),
+      ...(call.cwd === undefined ? {} : { cwd: call.cwd }),
+      ...(call.timeoutMs === undefined ? {} : { timeout: call.timeoutMs }),
     });
     return { code: 0, stdout, stderr: "" };
   } catch (error) {
-    const shaped = error as { status?: number; stdout?: string; stderr?: string };
+    const shaped = error as { status?: number; stdout?: string; stderr?: string; code?: string };
+    if (shaped.code === "ETIMEDOUT") {
+      return {
+        code: -1,
+        stdout: shaped.stdout ?? "",
+        stderr: `npm ${args[0] ?? ""} timed out after ${call.timeoutMs} ms`,
+      };
+    }
     return {
       code: shaped.status ?? -1,
       stdout: shaped.stdout ?? "",
@@ -42,9 +66,14 @@ export const defaultNpmRunner: NpmRunner = (args, cwd) => {
   }
 };
 
-/** `npm root -g`, or null when npm is not usable. Resolved once per run. */
-export function npmRootGlobal(npm: NpmRunner = defaultNpmRunner): string | null {
-  const result = npm(["root", "-g"]);
+/**
+ * `npm root -g`, or null when npm is not usable. Resolved once per run.
+ *
+ * It runs before the install is known, so its directory is the caller's: the
+ * tree the front door runs from, which for a package is the install's root.
+ */
+export function npmRootGlobal(cwd: string, npm: NpmRunner = defaultNpmRunner): string | null {
+  const result = npm(["root", "-g"], { cwd });
   const value = result.stdout.trim();
   return result.code === 0 && value ? value : null;
 }
@@ -54,9 +83,25 @@ export function npmRootGlobal(npm: NpmRunner = defaultNpmRunner): string | null
 
 export type DistTags = { ok: true; tags: Record<string, string> } | { ok: false; detail: string };
 
+/**
+ * How to read the dist-tags. `cwd` is the install's root. The welcome card
+ * bounds the read and drops npm's retries, which cost over a minute when the
+ * registry cannot be reached (CR135); `runtime update` asks for neither.
+ */
+export interface DistTagRead {
+  cwd: string;
+  timeoutMs?: number;
+  fetchRetries?: number;
+}
+
 /** `npm view <name> dist-tags --json`, read once per run. */
-export function readDistTags(name: string, npm: NpmRunner = defaultNpmRunner): DistTags {
-  const result = npm(["view", name, "dist-tags", "--json"]);
+export function readDistTags(name: string, npm: NpmRunner, read: DistTagRead): DistTags {
+  const args = ["view", name, "dist-tags", "--json"];
+  if (read.fetchRetries !== undefined) args.push(`--fetch-retries=${read.fetchRetries}`);
+  const result = npm(
+    args,
+    read.timeoutMs === undefined ? { cwd: read.cwd } : { cwd: read.cwd, timeoutMs: read.timeoutMs },
+  );
   if (result.code !== 0)
     return { ok: false, detail: firstLine(result.stderr) || "npm view failed" };
   let parsed: unknown;
@@ -117,12 +162,24 @@ export type ChannelDirection =
   | { kind: "behind"; version: string; detail: string; carriedBy: string | null }
   | { kind: "unresolved"; detail: string };
 
+/** What the package's npm commands need to know about the install. */
+export interface PackageInstall {
+  name: string;
+  version: string;
+  /** Where the package lives; its npm commands run here. */
+  root: string;
+}
+
+/** The bound and retries of one dist-tag read; where it runs is the install's. */
+export type DistTagLimits = Omit<DistTagRead, "cwd">;
+
 export function channelDirection(
-  install: { name: string; version: string },
+  install: PackageInstall,
   channel: string,
   npm: NpmRunner = defaultNpmRunner,
+  limits: DistTagLimits = {},
 ): ChannelDirection {
-  const read = readDistTags(install.name, npm);
+  const read = readDistTags(install.name, npm, { cwd: install.root, ...limits });
   if (!read.ok) return { kind: "unresolved", detail: read.detail };
   const resolved = resolveFrom(read.tags, install.name, channel);
   if (!resolved.ok) return { kind: "unresolved", detail: resolved.detail };
@@ -165,12 +222,13 @@ export interface PackageUpdateAvailability {
 }
 
 export function checkPackageUpdateAvailability(
-  install: { name: string; version: string },
+  install: PackageInstall,
   channel: { value: string; note: string | null },
   npm: NpmRunner = defaultNpmRunner,
+  limits: DistTagLimits = {},
 ): PackageUpdateAvailability {
   const base = { name: install.name, installed: install.version, channel, carriedBy: null };
-  const direction = channelDirection(install, channel.value, npm);
+  const direction = channelDirection(install, channel.value, npm, limits);
   switch (direction.kind) {
     case "current":
       return { ...base, resolved: direction.version, status: "up_to_date", note: null };
@@ -220,18 +278,53 @@ export function renderPackageUpdateAvailability(report: PackageUpdateAvailabilit
   return `${lines.join("\n")}\n`;
 }
 
-/** Install one exact version globally. Never a bare tag. */
+/** Install one exact version globally, from the install's own root. Never a bare tag. */
 export function installGlobal(
   name: string,
   version: string,
+  cwd: string,
   npm: NpmRunner = defaultNpmRunner,
 ): { ok: boolean; detail: string } {
-  const result = npm(["install", "-g", `${name}@${version}`]);
+  const result = npm(["install", "-g", `${name}@${version}`], { cwd });
   return result.code === 0
     ? { ok: true, detail: `${name}@${version}` }
     : { ok: false, detail: firstLine(result.stderr) || "npm install failed" };
 }
 
+/**
+ * `npm pack <name>@<version>` into `destination`: the exact tarball `runtime
+ * update` would install, fetched -- never unpacked here -- so `release-notes
+ * pending` can read what that version brings (CR134). It runs in the install's
+ * own root, as every npm call does (CR135). `--ignore-scripts`: a registry
+ * tarball runs no scripts when packed, and at a trust boundary that is said
+ * rather than assumed.
+ */
+export function packTarball(
+  name: string,
+  version: string,
+  cwd: string,
+  destination: string,
+  npm: NpmRunner = defaultNpmRunner,
+): { ok: true; path: string } | { ok: false; detail: string } {
+  const result = npm(
+    ["pack", `${name}@${version}`, "--pack-destination", destination, "--ignore-scripts", "--json"],
+    { cwd },
+  );
+  if (result.code !== 0)
+    return { ok: false, detail: firstLine(result.stderr) || "npm pack failed" };
+  let filename: unknown;
+  try {
+    filename = (JSON.parse(result.stdout) as Array<{ filename?: unknown }>)[0]?.filename;
+  } catch {
+    return { ok: false, detail: "npm pack returned unreadable JSON" };
+  }
+  // A bare file name, or nothing: the path is ours to build.
+  if (typeof filename !== "string" || filename === "" || basename(filename) !== filename) {
+    return { ok: false, detail: "npm pack named no tarball" };
+  }
+  return { ok: true, path: join(destination, filename) };
+}
+
 /** The pasteable route back, with the captured version in it. */
 export function packageRecoveryCommand(name: string, previousVersion: string | null): string {
   return previousVersion === null
@@ -249,7 +342,7 @@ export function packageRecoveryCommand(name: string, previousVersion: string | n
  * asked once, at plan.
  */
 export function packageStrategy(
-  install: { name: string; version: string },
+  install: PackageInstall,
   channel: string,
   npm: NpmRunner,
 ): ApplyStrategy {
@@ -268,11 +361,7 @@ export function packageStrategy(
     }),
 
     plan: (previousRef) => {
-      const direction = channelDirection(
-        { name: install.name, version: previousRef },
-        channel,
-        npm,
-      );
+      const direction = channelDirection({ ...install, version: previousRef }, channel, npm);
       switch (direction.kind) {
         case "unresolved":
           return {
@@ -308,7 +397,7 @@ export function packageStrategy(
     },
 
     apply: (_previousRef, target) => {
-      const applied = installGlobal(install.name, target, npm);
+      const applied = installGlobal(install.name, target, install.root, npm);
       return applied.ok
         ? { ok: true, newRef: target, detail: applied.detail, changes: [] }
         : {

package/ts/src/util/tarEntries.ts

@@ -0,0 +1,128 @@
+// Named entries out of a gzipped tar archive, in memory. (CR134)
+//
+// A package's pending release notes are read from the channel version's
+// tarball, which `npm pack` fetched across a trust boundary: the registry is
+// whatever the npm config names, and a project's `.npmrc` can name it (CR135).
+// So nothing here writes a file, and no entry name becomes a path or an
+// argument -- the caller asks for names and gets bytes. That is also why `tar`
+// is not spawned: it would take archive-chosen member names as arguments.
+// Inflation stops at a bound, because a small gzip can inflate to gigabytes.
+//
+// What is read is what tar writers produce: ustar headers with the POSIX
+// `prefix` field, pax extended headers (`x`, whose `path` names the next
+// entry), and GNU long names (`L`). Every header's checksum is checked, and an
+// archive that stops before its end-of-archive block is refused rather than
+// half-read: a tarball cut between two entries would otherwise lose the later
+// ones -- the newest note among them -- without a word.
+
+import { gunzipSync } from "node:zlib";
+
+const BLOCK = 512;
+const USTAR_MAGIC = Buffer.from("ustar\0", "latin1");
+
+/** The bound on inflated bytes. A release tarball inflates to a few MB. */
+export const MAX_INFLATED_BYTES = 64 * 1024 * 1024;
+
+export type TarEntries = { ok: true; entries: Map<string, Buffer> } | { ok: false; detail: string };
+
+/** A NUL-terminated header field. */
+function field(bytes: Buffer): string {
+  const end = bytes.indexOf(0);
+  return bytes.subarray(0, end === -1 ? bytes.length : end).toString("utf8");
+}
+
+/** An octal header number, or null when the field holds anything else. */
+function octal(bytes: Buffer): number | null {
+  const value = field(bytes).trim();
+  return /^[0-7]+$/.test(value) ? Number.parseInt(value, 8) : null;
+}
+
+/** The checksum counts the header with its own field read as spaces. */
+function checksumHolds(header: Buffer): boolean {
+  const recorded = octal(header.subarray(148, 156));
+  if (recorded === null) return false;
+  let sum = 0;
+  for (let index = 0; index < BLOCK; index += 1) {
+    sum += index >= 148 && index < 156 ? 0x20 : (header[index] as number);
+  }
+  return sum === recorded;
+}
+
+/** The `path` record of a pax extended header: records are `<len> <key>=<value>\n`. */
+function paxPath(data: Buffer): string | null {
+  let path: string | null = null;
+  let offset = 0;
+  while (offset < data.length) {
+    const space = data.indexOf(0x20, offset);
+    if (space === -1) break;
+    const length = Number.parseInt(data.subarray(offset, space).toString("latin1"), 10);
+    if (!Number.isInteger(length) || length <= 0 || offset + length > data.length) break;
+    const record = data.subarray(space + 1, offset + length - 1).toString("utf8");
+    const equals = record.indexOf("=");
+    if (equals !== -1 && record.slice(0, equals) === "path") path = record.slice(equals + 1);
+    offset += length;
+  }
+  return path;
+}
+
+/**
+ * The regular-file entries of a gzipped tar whose names `wanted` accepts.
+ * Refuses, with a reason, an archive that inflates past the bound, is not
+ * gzip, fails a header checksum, or ends inside an entry.
+ */
+export function readTarGzEntries(
+  gz: Buffer,
+  wanted: (name: string) => boolean,
+  maxInflatedBytes: number = MAX_INFLATED_BYTES,
+): TarEntries {
+  let tar: Buffer;
+  try {
+    tar = gunzipSync(gz, { maxOutputLength: maxInflatedBytes });
+  } catch (error) {
+    if ((error as { code?: string }).code === "ERR_BUFFER_TOO_LARGE") {
+      return { ok: false, detail: `the archive inflates to more than ${maxInflatedBytes} bytes` };
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return { ok: false, detail: `unreadable gzip: ${message}` };
+  }
+
+  const entries = new Map<string, Buffer>();
+  let nextName: string | null = null;
+  let offset = 0;
+  while (offset + BLOCK <= tar.length) {
+    const header = tar.subarray(offset, offset + BLOCK);
+    if (header.every((byte) => byte === 0)) return { ok: true, entries };
+    if (!checksumHolds(header)) {
+      return { ok: false, detail: `the tar header at byte ${offset} fails its checksum` };
+    }
+    const size = octal(header.subarray(124, 136));
+    if (size === null) {
+      return { ok: false, detail: `the tar header at byte ${offset} has an unreadable size` };
+    }
+    const start = offset + BLOCK;
+    const end = start + size;
+    if (end > tar.length) return { ok: false, detail: "the archive is truncated" };
+    const data = tar.subarray(start, end);
+    const type = String.fromCharCode(header[156] as number);
+
+    if (type === "x") {
+      nextName = paxPath(data) ?? nextName;
+    } else if (type === "L") {
+      nextName = field(data);
+    } else if (type !== "g") {
+      const prefix = header.subarray(257, 263).equals(USTAR_MAGIC)
+        ? field(header.subarray(345, 500))
+        : "";
+      const base = field(header.subarray(0, 100));
+      const name = nextName ?? (prefix ? `${prefix}/${base}` : base);
+      nextName = null;
+      if ((type === "0" || type === "\0") && wanted(name)) entries.set(name, Buffer.from(data));
+    }
+    offset = start + Math.ceil(size / BLOCK) * BLOCK;
+  }
+  // The archive stopped before its end-of-archive block: inside an entry's
+  // padding, or cleanly between two entries. Entries after the last whole one
+  // may be missing, so nothing read here is presented as the whole (CI at
+  // 565b7b97 met the first; the second is the general case).
+  return { ok: false, detail: "the archive is truncated" };
+}