mirror-mind 0.0.1 → 0.33.0

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

@@ -0,0 +1,200 @@
+// The `clone` apply strategy: a git checkout following `origin/<channel>`.
+// (CV22.DS10.US2)
+//
+// This is how every Mirror installed today receives code, and it stays the
+// strategy for a checkout after npm distribution exists: the safety chain is
+// the product's promise, and the transport underneath it is two git commands.
+//
+// Every git invocation goes through an injectable runner so the pipeline's
+// 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 type { ApplyStrategy } from "#runtime/updatePipeline.ts";
+
+export type GitRunner = (
+  args: readonly string[],
+  cwd: string,
+) => { code: number; stdout: string; stderr: string };
+
+export const defaultGitRunner: GitRunner = (args, cwd) => runGit([...args], cwd);
+
+/** `origin/main` -> `["origin", "main"]`; anything else is refused. */
+export function splitUpstream(upstream: string): [string, string] | null {
+  const index = upstream.indexOf("/");
+  if (index <= 0 || index === upstream.length - 1) return null;
+  const remote = upstream.slice(0, index);
+  const branch = upstream.slice(index + 1);
+  if (remote.startsWith("-") || branch.startsWith("-")) return null;
+  return [remote, branch];
+}
+
+/** The commit this install is on, read BEFORE anything moves. */
+export function captureCommit(repository: string, git: GitRunner): string | null {
+  const result = git(["rev-parse", "--short", "HEAD"], repository);
+  const value = result.stdout.trim();
+  return result.code === 0 && value ? value : null;
+}
+
+export function fetchUpstream(
+  repository: string,
+  upstream: string,
+  git: GitRunner,
+): { ok: boolean; detail: string } {
+  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);
+  return result.code === 0
+    ? { ok: true, detail: `${remote} ${branch}` }
+    : { ok: false, detail: result.stderr.trim() || "fetch failed" };
+}
+
+/**
+ * Fast-forward only, never a merge. A clone that cannot fast-forward has local
+ * work or has diverged, and resolving that is a decision the updater must not
+ * take on someone's behalf.
+ */
+export function fastForward(
+  repository: string,
+  upstream: string,
+  git: GitRunner,
+): { ok: boolean; detail: string } {
+  const result = git(["merge", "--ff-only", upstream], repository);
+  return result.code === 0
+    ? { ok: true, detail: "" }
+    : { ok: false, detail: result.stderr.trim() || "fast-forward refused" };
+}
+
+/** One-line subjects installed by this update, for the render. */
+export function installedChanges(
+  repository: string,
+  previous: string | null,
+  next: string | null,
+  git: GitRunner,
+): string[] {
+  if (!previous || !next || previous === next) return [];
+  const result = git(["log", "--oneline", "--no-decorate", `${previous}..${next}`], repository);
+  if (result.code !== 0) return [];
+  return result.stdout
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .slice(0, 20);
+}
+
+/** The pasteable route back, with the captured value in it. */
+export function cloneRecoveryCommand(previous: string | null): string {
+  return previous === null ? "git reset --hard <previous commit>" : `git reset --hard ${previous}`;
+}
+
+function countCommits(repository: string, range: string, git: GitRunner): number | null {
+  const result = git(["rev-list", "--count", range], repository);
+  if (result.code !== 0) return null;
+  const value = Number.parseInt(result.stdout.trim(), 10);
+  return Number.isNaN(value) ? null : value;
+}
+
+/**
+ * The clone's answers to the pipeline's questions. A ref is a short commit;
+ * the channel is `origin/<channel>`; moving is a fast-forward and nothing
+ * else; the way back is a hard reset to the captured commit.
+ */
+export function cloneStrategy(repository: string, upstream: string, git: GitRunner): ApplyStrategy {
+  return {
+    kind: "clone",
+    applyStage: "fast-forward",
+
+    // The ordinary gate reads the status report; a tree too broken for that
+    // still has one thing the repair lane can check without it.
+    repairGate: () => {
+      const dirty = git(["status", "--porcelain"], repository);
+      if (dirty.code !== 0 || dirty.stdout.trim() !== "") {
+        return {
+          ok: false,
+          detail: "git tree is dirty",
+          recovery: ["Commit or stash local changes, then retry runtime update --repair-updater."],
+        };
+      }
+      return { ok: true };
+    },
+
+    capture: () => {
+      const ref = captureCommit(repository, git);
+      return ref === null
+        ? {
+            ok: false,
+            detail: "could not read the current commit",
+            recovery: ["Mirror must be a readable git checkout to update in place."],
+          }
+        : { ok: true, ref, detail: ref };
+    },
+
+    fetch: () => {
+      const fetched = fetchUpstream(repository, upstream, git);
+      return fetched.ok
+        ? { ok: true, detail: fetched.detail }
+        : {
+            ok: false,
+            detail: fetched.detail,
+            recovery: [
+              "Check network connectivity and remote access.",
+              "Retry runtime update, or use --no-fetch to plan from local refs only.",
+            ],
+          };
+    },
+
+    plan: (previousRef) => {
+      const ahead = countCommits(repository, `${upstream}..HEAD`, git);
+      const behind = countCommits(repository, `HEAD..${upstream}`, git);
+      if (ahead === null || behind === null) {
+        return {
+          kind: "blocked",
+          detail: `cannot compare against ${upstream}`,
+          recovery: [`Resolve upstream tracking for ${upstream}, then retry runtime update.`],
+        };
+      }
+      if (ahead === 0 && behind === 0) return { kind: "current", detail: "already up to date" };
+      if (ahead > 0) {
+        return {
+          kind: "blocked",
+          detail: behind > 0 ? "branch diverged" : "local commits present",
+          recovery: [
+            behind > 0
+              ? "Branch diverged; reconcile local and upstream commits manually."
+              : "Local branch is ahead of upstream; push or reset before updating.",
+            "The working tree and the database are unchanged.",
+            `Current commit: ${previousRef}`,
+          ],
+        };
+      }
+      return {
+        kind: "ahead",
+        target: upstream,
+        detail: `pull ${behind} remote commit(s)`,
+        dryRun: `would pull ${behind} commit(s) from ${upstream}`,
+      };
+    },
+
+    apply: (previousRef, target) => {
+      const applied = fastForward(repository, target, git);
+      if (!applied.ok) {
+        return {
+          ok: false,
+          detail: applied.detail,
+          recovery: ["Working tree is unchanged because fast-forward refused."],
+        };
+      }
+      const newRef = captureCommit(repository, git);
+      return {
+        ok: true,
+        newRef,
+        detail: `${previousRef} -> ${newRef ?? "unknown"}`,
+        changes: installedChanges(repository, previousRef, newRef, git),
+      };
+    },
+
+    recoveryCommand: cloneRecoveryCommand,
+    installedState: (newRef) => `Code is on ${newRef ?? "the new commit"}`,
+  };
+}

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

@@ -0,0 +1,328 @@
+// The `package` apply strategy: a global npm install following a dist-tag.
+// (CV22.DS10.US2)
+//
+// This is the mechanism npm distribution makes possible and the git updater
+// never could: the Frame's command registry says so in its own words --
+// `memory runtime update` "atualizaria só o clone, deixando o executável
+// instalado operando contra uma minor futura sem contrato de
+// compatibilidade". A versioned install is what that comment is waiting for.
+//
+// Every npm invocation goes through an injectable runner, like the git one, so
+// the pipeline's decisions are testable without a registry.
+
+import { execFileSync } from "node:child_process";
+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. */
+export type NpmRunner = (
+  args: readonly string[],
+  cwd?: string,
+) => {
+  code: number;
+  stdout: string;
+  stderr: string;
+};
+
+export const defaultNpmRunner: NpmRunner = (args, cwd) => {
+  try {
+    const stdout = execFileSync("npm", [...args], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      ...(cwd === undefined ? {} : { cwd }),
+    });
+    return { code: 0, stdout, stderr: "" };
+  } catch (error) {
+    const shaped = error as { status?: number; stdout?: string; stderr?: string };
+    return {
+      code: shaped.status ?? -1,
+      stdout: shaped.stdout ?? "",
+      stderr: shaped.stderr ?? String(error),
+    };
+  }
+};
+
+/** `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"]);
+  const value = result.stdout.trim();
+  return result.code === 0 && value ? value : null;
+}
+
+// The package channel's location and reader live in `#runtime/channel.ts`
+// with the clone's, since CV22.DS10.US3 plateau 4 gave both a writer.
+
+export type DistTags = { ok: true; tags: Record<string, string> } | { ok: false; detail: string };
+
+/** `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"]);
+  if (result.code !== 0)
+    return { ok: false, detail: firstLine(result.stderr) || "npm view failed" };
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(result.stdout);
+  } catch {
+    return { ok: false, detail: "npm view returned unreadable JSON" };
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    return { ok: false, detail: "npm view returned no dist-tags" };
+  }
+  const tags: Record<string, string> = {};
+  for (const [tag, value] of Object.entries(parsed as Record<string, unknown>)) {
+    if (typeof value === "string") tags[tag] = value;
+  }
+  return { ok: true, tags };
+}
+
+/**
+ * Resolve a dist-tag to a CONCRETE version before anything is installed.
+ *
+ * A bare `npm install -g name@stable` installs whatever the tag pointed at in
+ * that instant and reports nothing about it. Resolving first means the version
+ * is printed by `--check` and `--dry-run`, recorded in the stage detail and
+ * the log, and available as the value the recovery route needs. Following a
+ * mutable tag is the normal posture of `npm update -g`; being able to say what
+ * you got is the proportional control.
+ *
+ * The registry is a boundary. Its answer becomes the spec of
+ * `npm install -g <name>@<value>`, and npm's spec grammar admits tags, ranges,
+ * URLs, and paths beside versions, so a value that is not a plain version is
+ * refused here, before it is printed or installed (CV22.DS10.US3 plateau 4).
+ */
+function resolveFrom(
+  tags: Record<string, string>,
+  name: string,
+  channel: string,
+): { ok: true; version: string } | { ok: false; detail: string } {
+  const version = tags[channel];
+  if (version === undefined || version === "") {
+    return { ok: false, detail: `no dist-tag '${channel}' for ${name}` };
+  }
+  if (!isPlainSemver(version)) {
+    return { ok: false, detail: `dist-tag '${channel}' is not a version: ${version}` };
+  }
+  return { ok: true, version };
+}
+
+/**
+ * Which way the channel lies from the installed version. Migrations run one
+ * way, so a channel BEHIND the install is not an update to take: it is a
+ * downgrade, refused at plan, and the person is told which channel carries
+ * what they have.
+ */
+export type ChannelDirection =
+  | { kind: "current"; version: string }
+  | { kind: "ahead"; version: string }
+  | { kind: "behind"; version: string; detail: string; carriedBy: string | null }
+  | { kind: "unresolved"; detail: string };
+
+export function channelDirection(
+  install: { name: string; version: string },
+  channel: string,
+  npm: NpmRunner = defaultNpmRunner,
+): ChannelDirection {
+  const read = readDistTags(install.name, npm);
+  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 };
+  const order = compareSemver(resolved.version, install.version);
+  if (order === 0) return { kind: "current", version: resolved.version };
+  if (order > 0) return { kind: "ahead", version: resolved.version };
+  const carriedBy =
+    Object.entries(read.tags).find(
+      ([tag, version]) =>
+        tag !== channel &&
+        KNOWN_CHANNELS.has(tag) &&
+        isPlainSemver(version) &&
+        compareSemver(version, install.version) >= 0,
+    )?.[0] ?? null;
+  return {
+    kind: "behind",
+    version: resolved.version,
+    detail: `'${channel}' is behind the installed version (${resolved.version} < ${install.version})`,
+    carriedBy,
+  };
+}
+
+// --- `runtime update --check` for a package ----------------------------------
+
+export type PackageAvailabilityStatus =
+  | "up_to_date"
+  | "update_available"
+  | "channel_behind"
+  | "unresolved";
+
+export interface PackageUpdateAvailability {
+  name: string;
+  installed: string;
+  channel: { value: string; note: string | null };
+  resolved: string | null;
+  status: PackageAvailabilityStatus;
+  note: string | null;
+  /** The known channel at or past the installed version, when this one is behind. */
+  carriedBy: string | null;
+}
+
+export function checkPackageUpdateAvailability(
+  install: { name: string; version: string },
+  channel: { value: string; note: string | null },
+  npm: NpmRunner = defaultNpmRunner,
+): PackageUpdateAvailability {
+  const base = { name: install.name, installed: install.version, channel, carriedBy: null };
+  const direction = channelDirection(install, channel.value, npm);
+  switch (direction.kind) {
+    case "current":
+      return { ...base, resolved: direction.version, status: "up_to_date", note: null };
+    case "ahead":
+      return { ...base, resolved: direction.version, status: "update_available", note: null };
+    case "behind":
+      return {
+        ...base,
+        resolved: direction.version,
+        status: "channel_behind",
+        note: direction.detail,
+        carriedBy: direction.carriedBy,
+      };
+    case "unresolved":
+      return { ...base, resolved: null, status: "unresolved", note: direction.detail };
+  }
+}
+
+/** The package's counterpart of `renderRuntimeUpdateAvailability`, same shape. */
+export function renderPackageUpdateAvailability(report: PackageUpdateAvailability): string {
+  const lines = ["Mirror runtime update check", ""];
+  lines.push(`Version: ${report.installed}`);
+  lines.push(`Install: package (${report.name}@${report.installed})`);
+  lines.push(`Update channel: ${report.channel.value}`);
+  if (report.channel.note) lines.push(`Update channel note: ${report.channel.note}`);
+  lines.push(`Channel version: ${report.resolved ?? "unresolved"}`);
+  lines.push(`Availability: ${report.status}`);
+  if (report.note) lines.push(`Reason: ${report.note}`);
+  if (report.status === "update_available") {
+    lines.push("");
+    lines.push("Preview:");
+    lines.push("runtime update --dry-run");
+    lines.push("");
+    lines.push("Update:");
+    lines.push("runtime update");
+  } else if (report.status === "up_to_date") {
+    lines.push("");
+    lines.push("Next: no update needed");
+  } else if (report.status === "channel_behind") {
+    lines.push("");
+    lines.push(
+      report.carriedBy
+        ? `Next: runtime channel ${report.carriedBy}`
+        : `Next: stay on ${report.installed} until '${report.channel.value}' reaches it`,
+    );
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+/** Install one exact version globally. Never a bare tag. */
+export function installGlobal(
+  name: string,
+  version: string,
+  npm: NpmRunner = defaultNpmRunner,
+): { ok: boolean; detail: string } {
+  const result = npm(["install", "-g", `${name}@${version}`]);
+  return result.code === 0
+    ? { ok: true, detail: `${name}@${version}` }
+    : { ok: false, detail: firstLine(result.stderr) || "npm install failed" };
+}
+
+/** The pasteable route back, with the captured version in it. */
+export function packageRecoveryCommand(name: string, previousVersion: string | null): string {
+  return previousVersion === null
+    ? `npm install -g ${name}@<previous version>`
+    : `npm install -g ${name}@${previousVersion}`;
+}
+
+/**
+ * The package's answers to the pipeline's questions. A ref is an installed
+ * version, read from the manifest before anything is installed over it (npm's
+ * global install is not atomic, so a pinned reinstall is the only rollback
+ * there is); the channel is a dist-tag resolved to a concrete version at plan
+ * time; moving is one global install of exactly that version; the way back is
+ * the same install of the captured one. Nothing is fetched: the registry is
+ * asked once, at plan.
+ */
+export function packageStrategy(
+  install: { name: string; version: string },
+  channel: string,
+  npm: NpmRunner,
+): ApplyStrategy {
+  return {
+    kind: "package",
+    applyStage: "apply",
+
+    // A package has no tree to be dirty: the status gate is the only gate, and
+    // the repair lane simply forgoes it.
+    repairGate: () => ({ ok: true }),
+
+    capture: () => ({
+      ok: true,
+      ref: install.version,
+      detail: `${install.name}@${install.version}`,
+    }),
+
+    plan: (previousRef) => {
+      const direction = channelDirection(
+        { name: install.name, version: previousRef },
+        channel,
+        npm,
+      );
+      switch (direction.kind) {
+        case "unresolved":
+          return {
+            kind: "blocked",
+            detail: direction.detail,
+            recovery: [
+              `Could not resolve the '${channel}' dist-tag for ${install.name}.`,
+              "Check network access to the npm registry, then retry runtime update.",
+            ],
+          };
+        case "current":
+          return { kind: "current", detail: `already up to date (${direction.version})` };
+        case "behind":
+          return {
+            kind: "blocked",
+            detail: direction.detail,
+            recovery: [
+              "A downgrade is refused: migrations do not run backwards.",
+              direction.carriedBy
+                ? `Follow the channel that carries ${previousRef}: runtime channel ${direction.carriedBy}`
+                : `Stay on ${previousRef} until '${channel}' reaches it.`,
+              "Nothing was installed and the database is unchanged.",
+            ],
+          };
+        case "ahead":
+          return {
+            kind: "ahead",
+            target: direction.version,
+            detail: `${previousRef} -> ${direction.version}`,
+            dryRun: `would install ${install.name}@${direction.version}`,
+          };
+      }
+    },
+
+    apply: (_previousRef, target) => {
+      const applied = installGlobal(install.name, target, npm);
+      return applied.ok
+        ? { ok: true, newRef: target, detail: applied.detail, changes: [] }
+        : {
+            ok: false,
+            detail: applied.detail,
+            recovery: ["A global npm install is not atomic; this one did not complete."],
+          };
+    },
+
+    recoveryCommand: (previousRef) => packageRecoveryCommand(install.name, previousRef),
+    installedState: (newRef) => `${install.name}@${newRef ?? "<unknown>"} is installed`,
+  };
+}
+
+function firstLine(text: string): string {
+  return text.trim().split("\n")[0] ?? "";
+}

package/ts/src/runtime/treeRoot.ts

@@ -0,0 +1,30 @@
+// The tree that holds the running program. CV22.DS10.US3 plateau 1.
+//
+// Three readers used to locate the tree three ways: `init` walked up from its
+// own file for `templates/identity`; `runtime release-notes` asked
+// `git rev-parse --show-toplevel` and fell back to the cwd; the welcome card
+// read `<cwd>/docs/releases/<version>.md`. Only the first worked for an
+// installed package, and the third answered for whatever directory the person
+// happened to be in. Now there is one answer, from the same walk the version
+// and the checkout guard already use (`packageIdentity.ts`), anchored at this
+// file -- so it is the tree the code came from, in a checkout, through
+// `npm link`, or under `npm root -g` alike. Never the cwd, never git.
+
+import { findPackageIdentity } from "./packageIdentity.ts";
+
+export class TreeRootNotFoundError extends Error {}
+
+/**
+ * The root of the tree this module was loaded from: the directory holding the
+ * manifest and the front door. Throws when there is none, which means the
+ * program is running from a copy that is not a Mirror Mind tree at all.
+ */
+export function runningTreeRoot(): string {
+  const identity = findPackageIdentity(import.meta.dirname);
+  if (identity === null) {
+    throw new TreeRootNotFoundError(
+      `no Mirror Mind tree holds ${import.meta.filename}: package.json and ts/src/frontDoor/cli.ts not found above it`,
+    );
+  }
+  return identity.root;
+}