mirror-mind 0.33.0 → 0.33.2

package/ts/src/frontDoor/runtimeRoute.ts

@@ -21,7 +21,7 @@ import {
   renderRuntimeBackupCreated,
   verifyBackupArchive,
 } from "#runtime/backup.ts";
-import { channelFor, renderChannel, setChannel } from "#runtime/channel.ts";
+import { channelFor, channelForReport, renderChannel, setChannel } from "#runtime/channel.ts";
 import {
   diagnoseRuntime,
   hookFailureFindings,
@@ -33,26 +33,31 @@ import {
 } from "#runtime/diagnose.ts";
 import {
   checkUpdateAvailability,
-  inspectCloneRole,
+  cloneRoleFor,
   inspectGitFor,
   inspectGitWorktree,
-  inspectUpdateChannel,
   packageVersion,
   renderRuntimeUpdateAvailability,
   renderRuntimeVersion,
+  unavailableUpdateCheck,
   upstreamFor,
 } from "#runtime/git.ts";
-import { detectInstallKind, type InstallKind } from "#runtime/installKind.ts";
+import { detectInstallKind, type InstallKind, inspectionRootFor } from "#runtime/installKind.ts";
 import { MIGRATE_DECLINED_EXIT, renderMigrate, runMigrate } from "#runtime/migrate.ts";
 import {
   buildPendingReleaseNotes,
+  buildPendingReleaseNotesFromRegistry,
+  type ReleaseNotesBundle,
   readReleaseNote,
   renderReleaseNote,
   renderReleaseNotesBundle,
+  unknownReleaseNotes,
 } from "#runtime/releaseNotes.ts";
 import { buildRuntimeStatus, renderRuntimeStatus, statusVerdict } from "#runtime/status.ts";
 import {
   checkPackageUpdateAvailability,
+  defaultNpmRunner,
+  type NpmRunner,
   npmRootGlobal,
   renderPackageUpdateAvailability,
 } from "#runtime/strategies/package.ts";
@@ -61,8 +66,9 @@ import { frontDoorSpawner, postUpdateHints, runUpdate, type UpdateSpawn } from "
 import { statusAllowsUpdatePreflight } from "#runtime/updateGate.ts";
 import { renderUpdateResult, updateLogDetail } from "#runtime/updatePipeline.ts";
 import { expandHome } from "#util/paths.ts";
-import { composeWelcome, welcomeDisabled } from "#welcome/card.ts";
+import { composeWelcome, type RemoteCheck, welcomeDisabled } from "#welcome/card.ts";
 import { composeStatusLine } from "#welcome/statusLine.ts";
+import { isoNow, recordUpToDate } from "#welcome/updateCache.ts";
 
 /** The `runtime` subcommands this story ports. */
 export const TS_RUNTIME_READ_SUBCOMMANDS = new Set([
@@ -150,6 +156,11 @@ function resolveWelcomeHome(explicit: string | null, env: NodeJS.ProcessEnv): st
 }
 
 export interface RuntimeRouteIo {
+  /**
+   * Where the command was run. No `runtime` read route consults it: since
+   * CR134 and CR138 they answer for the install, wherever they run. Tests pass
+   * it to show that it does not matter.
+   */
   cwd?: string;
   env?: NodeJS.ProcessEnv;
   stdout?: (text: string) => void;
@@ -165,18 +176,39 @@ function writeErr(io: RuntimeRouteIo, text: string): void {
   (io.stderr ?? ((value: string) => process.stderr.write(value)))(text);
 }
 
-/** Port of `welcome.main`. Always exits 0, like the oracle. */
-export function runWelcomeRoute(argv: readonly string[], io: RuntimeRouteIo = {}): number {
+/**
+ * The seams of the routes that answer for the running install, beyond the
+ * route's own: the install and its npm, for tests. The welcome (CR135) and
+ * `release-notes pending` (CR134) take them.
+ */
+export interface InstallRouteIo extends RuntimeRouteIo {
+  install?: InstallKind;
+  npm?: NpmRunner;
+  /** The OS home whose config directory holds a package's channel file. */
+  osHome?: string;
+}
+
+export type WelcomeRouteIo = InstallRouteIo;
+
+/**
+ * Port of `welcome.main`. Always exits 0, like the oracle.
+ *
+ * The card and the status line answer for the install that is running, never
+ * for the cwd (CR135): Pi renders both in the person's project.
+ */
+export function runWelcomeRoute(argv: readonly string[], io: WelcomeRouteIo = {}): number {
   const env = io.env ?? process.env;
-  const cwd = io.cwd ?? process.cwd();
   const args = argv.slice(1);
   if (welcomeDisabled(env)) return 0;
 
   const home = resolveWelcomeHome(optionValue(args, "--mirror-home"), env);
+  // The running tree's manifest: a file read, so the status line still spawns nothing.
+  const version = packageVersion(runningTreeRoot()) ?? "unknown";
 
   if (args.includes("--status-line")) {
     const line = composeStatusLine({
       mirrorHome: home,
+      installedVersion: version,
       sessionId: optionValue(args, "--session-id"),
       env,
     });
@@ -184,26 +216,39 @@ export function runWelcomeRoute(argv: readonly string[], io: RuntimeRouteIo = {}
     return 0;
   }
 
-  const version = packageVersion(runningTreeRoot()) ?? "unknown";
-  const card = composeWelcome({
+  const { card, check } = composeWelcome({
     mirrorHome: home,
-    cwd,
-    treeRoot: runningTreeRoot(),
+    install: io.install ?? detectThisInstall(),
     env,
     version,
-    updateChannel: inspectUpdateChannel(cwd, null),
+    ...(io.npm === undefined ? {} : { npm: io.npm }),
+    ...(io.osHome === undefined ? {} : { osHome: io.osHome }),
   });
   if (card) writeOut(io, `${card}\n`);
+  if (home !== null && check !== null) logWelcomeCheck(home, env, check);
   return 0;
 }
 
+/**
+ * One front-door line per remote check, so a slow session start can be
+ * explained later: what was asked, how it answered, how long it took. Never a
+ * path or a version.
+ */
+function logWelcomeCheck(home: string, env: NodeJS.ProcessEnv, check: RemoteCheck): void {
+  logFrontDoor(frontDoorLogPath(join(home, dbNameForEnv(env.MEMORY_ENV || "production"))), {
+    command: "welcome",
+    route: "ts",
+    exitCode: 0,
+    detail: `update-check source=${check.source} verdict=${check.verdict} ms=${check.ms}`,
+  });
+}
+
 /** Port of the read half of `cmd_runtime`. */
 export async function runRuntimeReadRoute(
   argv: readonly string[],
-  io: RuntimeRouteIo = {},
+  io: InstallRouteIo = {},
 ): Promise<number> {
   const env = io.env ?? process.env;
-  const cwd = io.cwd ?? process.cwd();
   const args = argv.slice(1);
   const subcommand = args[0] ?? "";
   // The version is the running tree's, never the cwd's: for a skill the cwd
@@ -213,19 +258,24 @@ export async function runRuntimeReadRoute(
 
   if (subcommand === "version") {
     const startArg = optionValue(args, "--start");
-    const start = startArg ? expandHome(startArg) : cwd;
-    const install = detectThisInstall();
+    const install = io.install ?? detectThisInstall();
+    // The install's own repository, or the one `--start` names: the one
+    // explicit way these commands run git outside the install (CR138).
+    const root = inspectionRootFor(install, startArg ? expandHome(startArg) : null);
     writeOut(
       io,
       renderRuntimeVersion({
         version,
         install,
-        git: inspectGitFor(install, start),
-        cloneRole: inspectCloneRole(start),
-        updateChannel:
-          install.kind === "package"
-            ? channelFor(install, env, homedir(), optionValue(args, "--channel"))
-            : inspectUpdateChannel(start, optionValue(args, "--channel")),
+        git: inspectGitFor(install, root),
+        cloneRole: cloneRoleFor(install, root),
+        updateChannel: channelForReport(
+          install,
+          root,
+          env,
+          io.osHome ?? homedir(),
+          optionValue(args, "--channel"),
+        ),
       }),
     );
     return 0;
@@ -233,24 +283,24 @@ export async function runRuntimeReadRoute(
 
   if (subcommand === "status") {
     const report = buildRuntimeStatus({
-      start: cwd,
       mirrorHome: optionValue(args, "--mirror-home"),
       channel: optionValue(args, "--channel"),
       env,
       version,
-      install: detectThisInstall(),
+      install: io.install ?? detectThisInstall(),
     });
     writeOut(io, renderRuntimeStatus(report, env));
     return statusVerdict(report) === "ready" ? 0 : 1;
   }
 
   if (subcommand === "diagnose") {
+    // The install's own tree, so its worktree findings are Mirror's and never
+    // the cwd project's (CR138).
     const report = buildRuntimeStatus({
-      start: cwd,
       mirrorHome: optionValue(args, "--mirror-home"),
       env,
       version,
-      install: detectThisInstall(),
+      install: io.install ?? detectThisInstall(),
     });
     const findings = [
       ...diagnoseRuntime(report, inspectGitWorktree(report.git.repository)),
@@ -280,19 +330,14 @@ export async function runRuntimeReadRoute(
   if (subcommand === "release-notes") {
     const target = firstPositional(args.slice(1)) ?? "latest";
     if (target === "pending") {
-      writeOut(
-        io,
-        renderReleaseNotesBundle(
-          buildPendingReleaseNotes({
-            // `--from` omitted falls back to the checkout's own version,
-            // exactly as the oracle does before normalizing.
-            currentVersion: optionValue(args, "--from") ?? version,
-            ref: optionValue(args, "--ref") ?? "origin/stable",
-            fetch: !args.includes("--no-fetch"),
-            start: cwd,
-          }),
-        ),
-      );
+      const pending = pendingReleaseNotes(args, io, env, version);
+      if ("usage" in pending) {
+        writeErr(io, pending.usage);
+        return 2;
+      }
+      writeOut(io, renderReleaseNotesBundle(pending.bundle));
+      // `unknown` exits 1, as `update --check` does on `unresolved` (CR134, decision 3).
+      return pending.bundle.unknown_reason === null ? 0 : 1;
     } else {
       // The notes ship in the package at the same path as in the checkout
       // (US3 D8), read from the tree that holds the running front door --
@@ -304,7 +349,7 @@ export async function runRuntimeReadRoute(
 
   if (subcommand === "backup") return runRuntimeBackup(args.slice(1), io, env);
   if (subcommand === "migrate") return runRuntimeMigrate(args.slice(1), io, env);
-  if (subcommand === "update") return runRuntimeUpdate(args.slice(1), io, env, cwd);
+  if (subcommand === "update") return runRuntimeUpdate(args.slice(1), io, env);
   if (subcommand === "channel") return runRuntimeChannel(args.slice(1), io, env);
 
   // Routing answers every name it does not recognize before dispatch (the
@@ -450,20 +495,28 @@ function runRuntimeChannel(
  */
 function runRuntimeUpdate(
   args: readonly string[],
-  io: RuntimeRouteIo,
+  io: InstallRouteIo,
   env: NodeJS.ProcessEnv,
-  cwd: string,
 ): number {
   const version = packageVersion(runningTreeRoot()) ?? "unknown";
   const channelOverride = optionValue(args, "--channel");
   // The update lane asks npm, once, whether `-g` addresses this install: a
   // package outside npm's own global root is not the one `npm install -g`
   // would replace. The read routes do not pay for the probe.
-  const install = detectInstallKind({
-    frontDoorPath: frontDoorSelfPath(),
-    npmRootGlobal: npmRootGlobal(),
-  });
-  const start = install.kind === "clone" ? install.repository : cwd;
+  //
+  // npm runs in the tree the front door runs from -- for a package, the
+  // install's own root -- and never in the cwd, whose `.npmrc` could name
+  // another registry or prefix (CR135). The strategy's own calls do the same.
+  //
+  // Git runs in the clone's own checkout and nowhere else: the gate's report
+  // and `--check` name no cwd (CR138), whose `.git/config` could name a
+  // command for git to run.
+  const install =
+    io.install ??
+    detectInstallKind({
+      frontDoorPath: frontDoorSelfPath(),
+      npmRootGlobal: npmRootGlobal(runningTreeRoot()),
+    });
   const channel = channelFor(install, env, homedir(), channelOverride);
 
   if (args.includes("--check")) {
@@ -477,7 +530,12 @@ function runRuntimeUpdate(
         ? 0
         : 1;
     }
-    const availability = checkUpdateAvailability(start, channelOverride, version);
+    // An install that cannot be identified has no checkout to ask, and the
+    // cwd is not one (CR138, decision 2). `runtime update` refuses it too.
+    const availability =
+      install.kind === "clone"
+        ? checkUpdateAvailability(install.repository, channelOverride, version)
+        : unavailableUpdateCheck(version, channel, `install kind unknown: ${install.reason}`);
     writeOut(io, renderRuntimeUpdateAvailability(availability));
     return availability.status === "up_to_date" || availability.status === "update_available"
       ? 0
@@ -501,7 +559,6 @@ function runRuntimeUpdate(
 
   const gate = (): { ready: boolean; allowed: boolean; detail: string } => {
     const report = buildRuntimeStatus({
-      start,
       mirrorHome,
       channel: channelOverride,
       env,
@@ -548,6 +605,16 @@ function runRuntimeUpdate(
   });
 
   writeOut(io, renderUpdateResult(result));
+  // The install now holds its channel's version: say so where the welcome card
+  // and the status line read it, or they keep announcing what was just
+  // installed (CR135).
+  if (result.success && !args.includes("--dry-run")) {
+    recordUpToDate(mirrorHome, {
+      channel: channel.value,
+      commit: install.kind === "clone" ? result.newRef : null,
+      checkedAt: isoNow(),
+    });
+  }
   if (repair && result.success) {
     // After the stages, not before them: the instruction is what to do NEXT,
     // and it reads as a caption on a result the operator has already seen.
@@ -596,6 +663,74 @@ function detectThisInstall(): InstallKind {
   return detectInstallKind({ frontDoorPath: frontDoorSelfPath() });
 }
 
+/**
+ * `release-notes pending` for the install that is running, never for the cwd
+ * (CR134), which for a skill is the person's project. A clone reads its own
+ * channel's ref -- or `--ref` -- in its own repository; a package asks the
+ * registry what its channel holds; an install that cannot be identified has no
+ * source, and says so.
+ */
+function pendingReleaseNotes(
+  args: readonly string[],
+  io: InstallRouteIo,
+  env: NodeJS.ProcessEnv,
+  version: string,
+): { bundle: ReleaseNotesBundle } | { usage: string } {
+  const install = io.install ?? detectThisInstall();
+  const osHome = io.osHome ?? homedir();
+  const ref = optionValue(args, "--ref");
+  const fetch = !args.includes("--no-fetch");
+
+  if (install.kind === "clone") {
+    return {
+      bundle: buildPendingReleaseNotes({
+        // `--from` omitted falls back to the running tree's own version.
+        currentVersion: optionValue(args, "--from") ?? version,
+        ref: ref ?? upstreamFor(channelFor(install, env, osHome)),
+        repository: install.repository,
+        fetch,
+      }),
+    };
+  }
+
+  if (install.kind === "package") {
+    if (ref !== null) {
+      return {
+        usage:
+          `release-notes pending: --ref names a git ref, and this install is a package ` +
+          `(${install.name}@${install.version}), which reads its channel from the npm registry\n`,
+      };
+    }
+    const currentVersion = optionValue(args, "--from") ?? install.version;
+    const channel = channelFor(install, env, osHome).value;
+    if (!fetch) {
+      return {
+        bundle: unknownReleaseNotes(
+          currentVersion,
+          `npm ${install.name}@${channel}`,
+          "a package keeps no copy of its channel to read offline; run without --no-fetch",
+        ),
+      };
+    }
+    return {
+      bundle: buildPendingReleaseNotesFromRegistry({
+        currentVersion,
+        install,
+        channel,
+        npm: io.npm ?? defaultNpmRunner,
+      }),
+    };
+  }
+
+  return {
+    bundle: unknownReleaseNotes(
+      optionValue(args, "--from") ?? version,
+      null,
+      `install kind unknown (${install.reason})`,
+    ),
+  };
+}
+
 /**
  * argparse's positional for `release-notes`: the first bare token that is not
  * consumed as the VALUE of `--from` or `--ref`. Walking the list is the only

package/ts/src/runtime/channel.ts

@@ -82,6 +82,24 @@ export function channelFor(
   return { value: DEFAULT_CHANNEL, source: null, note: "install kind unknown" };
 }
 
+/**
+ * The channel row of `status` and `version` (CR138). A package's is its
+ * config file's. A clone's is the marker in the repository the rows come from
+ * (`inspectionRootFor`): its own checkout, or `version --start PATH`, the
+ * flag's documented meaning. With no root, the install's own answer, which for
+ * a clone without `--start` is the same marker, read the same way.
+ */
+export function channelForReport(
+  install: InstallKind,
+  root: string | null,
+  env: ConfigEnv = process.env,
+  home: string = homedir(),
+  override: string | null = null,
+): MarkerValue {
+  if (install.kind === "package" || root === null) return channelFor(install, env, home, override);
+  return inspectUpdateChannel(root, override);
+}
+
 export type ChannelWrite =
   | { ok: true; path: string; value: string; previous: string }
   | { ok: false; reason: string; exitCode: 1 | 2 };

package/ts/src/runtime/git.ts

@@ -13,7 +13,9 @@
 // Timeouts follow the oracle's two budgets, and for the reason recorded there:
 // local inspections are near-instant, while a single shared 2 s budget once
 // made a network operation report failure after it had already succeeded
-// (the v0.30.1 release incident). Network reads get 120 s.
+// (the v0.30.1 release incident). Network reads get 120 s, except where a
+// caller holds a tighter budget of its own: the welcome card's update check
+// runs inside the session start and passes what is left of its 5 s (CR135).
 
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync, realpathSync } from "node:fs";
@@ -260,11 +262,15 @@ function availability(
  * Is the channel's remote branch ahead of HEAD? The remote query is the only
  * authority: remote-tracking refs are only as fresh as the last fetch, and
  * trusting them is how a clone two releases behind gets told it is ahead.
+ *
+ * `networkTimeoutMs` bounds that query; `runtime update --check` keeps the
+ * network budget, and the welcome card passes what is left of its own.
  */
 export function checkUpdateAvailability(
   start: string,
   channel: string | null,
   version: string,
+  networkTimeoutMs: number = GIT_NETWORK_TIMEOUT_MS,
 ): UpdateAvailability {
   const startPath = resolve(start);
   const git = inspectGit(startPath);
@@ -303,7 +309,7 @@ export function checkUpdateAvailability(
   const lsRemote = runGit(
     ["ls-remote", remote, `refs/heads/${branch}`],
     git.repository,
-    GIT_NETWORK_TIMEOUT_MS,
+    networkTimeoutMs,
   );
   if (lsRemote.code !== 0 || !lsRemote.stdout) {
     return availability(version, updateChannel, {
@@ -430,12 +436,52 @@ export const NO_REPOSITORY: GitStatus = {
 };
 
 /**
- * The git facts of `start`, for the install's kind: a clone's are inspected,
- * a package's are `NO_REPOSITORY` (CV22.DS10.US3 plateau 4). Grading the cwd
- * of a package install as a tree read "not a git repository" as a git error.
+ * The git facts of the install's `root` (`inspectionRootFor`): a package's
+ * are `NO_REPOSITORY` (CV22.DS10.US3 plateau 4), since grading the cwd of a
+ * package install as a tree read "not a git repository" as a git error. With
+ * no root -- an install that cannot be identified, and no `--start` -- no
+ * repository is inspected at all, and the rows say why (CR138, decision 2).
+ */
+export function inspectGitFor(install: InstallKind, root: string | null): GitStatus {
+  if (install.kind === "package") return NO_REPOSITORY;
+  if (root === null) {
+    const reason =
+      install.kind === "unknown" ? `install kind unknown: ${install.reason}` : "no repository";
+    return { ...NO_REPOSITORY, error: reason };
+  }
+  return inspectGit(root);
+}
+
+/**
+ * The clone role the install's checkout declares (CR138). A package has none
+ * to declare. With no root, nothing is read, and the oracle's answer for no
+ * repository stands: the default, with the note that says why.
+ */
+export function cloneRoleFor(install: InstallKind, root: string | null): MarkerValue {
+  if (install.kind === "package") return { value: "none", source: null, note: "package install" };
+  if (root === null) return { value: DEFAULT_CLONE_ROLE, source: null, note: "no repository" };
+  return inspectCloneRole(root);
+}
+
+/** The clone-role rows of `status` and `version`, one renderer for both (CR138). */
+export function renderCloneRoleLines(install: InstallKind, role: MarkerValue): string[] {
+  if (install.kind === "package") return ["Clone role: none (package install)"];
+  const lines = [`Clone role: ${role.value}`];
+  if (role.note) lines.push(`Clone role note: ${role.note}`);
+  return lines;
+}
+
+/**
+ * `update --check` for an install whose repository is not asked: the same
+ * shape as the check's own `unknown`, with the reason (CR138). An install that
+ * cannot be identified has no checkout to ask, and the cwd is not one.
  */
-export function inspectGitFor(install: InstallKind, start: string): GitStatus {
-  return install.kind === "package" ? NO_REPOSITORY : inspectGit(start);
+export function unavailableUpdateCheck(
+  version: string,
+  updateChannel: MarkerValue,
+  note: string,
+): UpdateAvailability {
+  return availability(version, updateChannel, { note });
 }
 
 /**
@@ -464,8 +510,7 @@ export function renderRuntimeVersion(report: RuntimeVersionReport): string {
   lines.push(`Version: ${report.version}`);
   lines.push(...renderInstallLines(report.install));
   lines.push(...renderRepositoryLines(report.install, report.git, false));
-  lines.push(`Clone role: ${report.cloneRole.value}`);
-  if (report.cloneRole.note) lines.push(`Clone role note: ${report.cloneRole.note}`);
+  lines.push(...renderCloneRoleLines(report.install, report.cloneRole));
   lines.push(`Update channel: ${report.updateChannel.value}`);
   if (report.updateChannel.note) lines.push(`Update channel note: ${report.updateChannel.note}`);
   return `${lines.join("\n")}\n`;

package/ts/src/runtime/installKind.ts

@@ -201,6 +201,21 @@ export function detectInstallKind(probe: InstallKindProbe): InstallKind {
   };
 }
 
+/**
+ * Where the repository rows of `status`, `version`, and `diagnose` come from
+ * (CR138): `start` when one is given -- `version --start PATH`, or a test --
+ * else a clone's own checkout, else nowhere. Never the cwd. For a skill the
+ * cwd is the person's project, and git run there reads that project's config,
+ * where `core.fsmonitor` names a command git runs on `status`.
+ */
+export function inspectionRootFor(
+  install: InstallKind,
+  start: string | null | undefined,
+): string | null {
+  if (start !== null && start !== undefined) return resolve(start);
+  return install.kind === "clone" ? install.repository : null;
+}
+
 /** One line for a render or a log entry. */
 export function describeInstallKind(install: InstallKind): string {
   if (install.kind === "clone") return `clone (${install.repository})`;