mirror-mind 0.0.1 → 0.32.1

package/ts/src/welcome/card.ts

@@ -0,0 +1,339 @@
+// The state-aware welcome card (CV22.DS7.TS3 plateau 4). Port of
+// `compose_welcome` from `src/memory/cli/welcome.py`.
+//
+// Unlike the status line, the card MAY reach the network: on the stable
+// channel it performs a bounded remote update check so a newly published
+// release becomes visible without manual cache repair. That check is
+// TTL-guarded, refresh-guarded, and switched off entirely by
+// `MIRROR_WELCOME_REMOTE_UPDATE_CHECK=off|0|false|no`.
+//
+// Date rendering is done by hand from `_MONTH_ABBR`, never through
+// `toLocaleDateString`: the oracle formats the month itself, so a locale-aware
+// TypeScript formatter would render "since ago. 2025" on a machine whose
+// locale is not English and call it parity.
+
+import { existsSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { type Database, openDatabaseReadOnly } from "#db/database.ts";
+import { dbNameForEnv } from "#frontDoor/dbPath.ts";
+import { listJourneysForListCommand } from "#identity/journeyListing.ts";
+import {
+  checkUpdateAvailability,
+  type GitStatus,
+  inspectGit,
+  inspectGitUpdatePlan,
+  type MarkerValue,
+  runGit,
+} from "#runtime/git.ts";
+import { compareSemver } from "#util/semver.ts";
+import { SEPARATOR } from "./statusLine.ts";
+import {
+  cacheIsStale,
+  cacheShouldRefresh,
+  readUpdateCache,
+  type UpdateAwareness,
+  writeUpdateCache,
+} from "./updateCache.ts";
+
+export const INVITATION = "→ Where shall we begin?";
+
+/** Port of `_MONTH_ABBR`. Hand-formatted, deliberately: see the module header. */
+const MONTH_ABBR = [
+  "Jan",
+  "Feb",
+  "Mar",
+  "Apr",
+  "May",
+  "Jun",
+  "Jul",
+  "Aug",
+  "Sep",
+  "Oct",
+  "Nov",
+  "Dec",
+] as const;
+
+export interface WelcomeStats {
+  journeys: number;
+  personas: number;
+  memories: number;
+  conversations: number;
+  since: string | null;
+}
+
+/** Port of `_fmt_count`: a thousands separator only from 1000 up. */
+function fmtCount(value: number): string {
+  return value >= 1000 ? value.toLocaleString("en-US") : String(value);
+}
+
+/** Port of `_since_label`. An unparseable or absent timestamp reads "today". */
+export function sinceLabel(firstStarted: string | null): string {
+  if (!firstStarted) return "since today";
+  const parsed = Date.parse(firstStarted.replace("Z", "+00:00"));
+  if (Number.isNaN(parsed)) return "since today";
+  // The oracle reads the naive/offset timestamp's OWN fields, so the month and
+  // year come from the stored local wall clock, not from a UTC conversion.
+  const match = firstStarted.match(/^(\d{4})-(\d{2})/);
+  if (match) return `since ${MONTH_ABBR[Number(match[2]) - 1]} ${Number(match[1])}`;
+  const date = new Date(parsed);
+  return `since ${MONTH_ABBR[date.getUTCMonth()]} ${date.getUTCFullYear()}`;
+}
+
+/** Port of `_format_stats`. */
+export function formatStats(stats: WelcomeStats): string {
+  return [
+    `${fmtCount(stats.journeys)} journeys`,
+    `${fmtCount(stats.personas)} personas`,
+    `${fmtCount(stats.memories)} memories`,
+    `${fmtCount(stats.conversations)} conversations`,
+    sinceLabel(stats.since),
+  ].join(SEPARATOR);
+}
+
+function scalar(db: Database, sql: string, ...params: string[]): number {
+  const row = db.prepare(sql).get(...params);
+  const value = row === undefined ? null : Object.values(row)[0];
+  if (value === null || value === undefined) return 0;
+  return typeof value === "number" ? value : Number(value);
+}
+
+/** Port of `_stats_line`: five numbers, one read-only connection. */
+export function readWelcomeStats(dbPath: string | null): WelcomeStats {
+  if (dbPath === null || !existsSync(dbPath)) {
+    return { journeys: 0, personas: 0, memories: 0, conversations: 0, since: null };
+  }
+  const db = openDatabaseReadOnly(dbPath);
+  try {
+    const activeJourneys = listJourneysForListCommand(db).filter(
+      (journey) => journey.status === "active",
+    ).length;
+    const startedRow = db.prepare("SELECT MIN(started_at) AS value FROM conversations").get();
+    const started = startedRow?.value;
+    return {
+      journeys: activeJourneys,
+      personas: scalar(db, "SELECT COUNT(*) AS value FROM identity WHERE layer = ?", "persona"),
+      memories: scalar(db, "SELECT COUNT(*) AS value FROM memories"),
+      conversations: scalar(db, "SELECT COUNT(*) AS value FROM conversations"),
+      since: typeof started === "string" && started ? started : null,
+    };
+  } finally {
+    db.close();
+  }
+}
+
+/** Port of `_render`. */
+export function renderWelcome(
+  user: string,
+  stats: string,
+  version: string,
+  update: string | null,
+): string {
+  const lines = [`◇ Mirror · ${user}`, `Version ${version}`, stats];
+  if (update) lines.push(update);
+  lines.push("", INVITATION);
+  return lines.join("\n");
+}
+
+/** Port of `_remote_update_check_disabled`. */
+export function remoteUpdateCheckDisabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  const value = (env.MIRROR_WELCOME_REMOTE_UPDATE_CHECK ?? "").trim().toLowerCase();
+  return value === "off" || value === "0" || value === "false" || value === "no";
+}
+
+/** Port of `_welcome_disabled`. */
+export function welcomeDisabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  const value = (env.MIRROR_WELCOME ?? "").trim().toLowerCase();
+  return value === "off" || value === "0" || value === "false" || value === "no";
+}
+
+/** Port of `_commits_match`: either id may be the abbreviated form. */
+function commitsMatch(candidate: string, target: string): boolean {
+  return candidate === target || candidate.startsWith(target) || target.startsWith(candidate);
+}
+
+// The oracle's `_semver_key` was `_parse_semver` under a second name; both
+// are `#util/semver.ts` now, and an unparseable tag still sorts below every
+// real one.
+
+/**
+ * Port of `_remote_tag_for_commit`: which published tag names the commit the
+ * remote is at. `^{}` refs are the dereferenced peel of an annotated tag and
+ * are skipped, so a tag is not counted twice.
+ */
+export function remoteTagForCommit(
+  upstream: string,
+  remoteCommit: string,
+  repository: string | null,
+): string | null {
+  if (!upstream.includes("/")) return null;
+  const remote = upstream.split("/", 1)[0] as string;
+  if (repository === null) return null;
+  const result = runGit(["ls-remote", "--tags", remote, "refs/tags/v*"], repository);
+  if (result.code !== 0 || !result.stdout) return null;
+
+  const matches: string[] = [];
+  for (const line of result.stdout.split("\n")) {
+    const parts = line.split(/\s+/).filter((part) => part.length > 0);
+    if (parts.length < 2) continue;
+    const [commit, ref] = parts as [string, string];
+    if (!commitsMatch(commit, remoteCommit) || ref.endsWith("^{}")) continue;
+    const tag = ref.split("/").pop() as string;
+    if (tag.startsWith("v")) matches.push(tag);
+  }
+  if (matches.length === 0) return null;
+  return matches.sort((a, b) => compareSemver(b, a))[0] as string;
+}
+
+/**
+ * Port of `_local_release_title`: the headline of a note already on disk,
+ * under `<treeRoot>/docs/releases`. The oracle read `<cwd>/docs/releases`;
+ * since CV22.DS10.US3 the caller passes the tree that holds the running front
+ * door, so the title is the installed package's own and not whatever
+ * directory the person is in.
+ */
+export function localReleaseTitle(version: string | null, treeRoot: string): string | null {
+  if (!version) return null;
+  let text: string;
+  try {
+    text = readFileSync(join(treeRoot, "docs", "releases", `${version}.md`), "utf8");
+  } catch {
+    return null;
+  }
+  const prefix = `# ${version} — `;
+  for (const line of text.split("\n")) {
+    if (line.startsWith(prefix)) return line.slice(prefix.length).trim();
+  }
+  return null;
+}
+
+export interface WelcomeOptions {
+  /** The resolved mirror home. Null renders "", as in the oracle. */
+  mirrorHome: string | null;
+  /** Where git is inspected for the update check (a clone's working tree). */
+  cwd?: string;
+  /** The tree holding the running program, where `docs/releases` is read. Defaults to `cwd`. */
+  treeRoot?: string;
+  env?: NodeJS.ProcessEnv;
+  version: string;
+  updateChannel: MarkerValue;
+  /** Injected only so the written cache is byte-comparable; production omits it. */
+  now?: () => string;
+}
+
+/** Port of `_iso_now`. */
+function isoNow(): string {
+  return new Date().toISOString().replace(/\.(\d{3})Z$/, ".$1000+00:00");
+}
+
+/** Port of `_refresh_update_cache`. Any failure leaves the cache untouched. */
+function refreshUpdateCache(
+  homePath: string,
+  channel: MarkerValue,
+  cwd: string,
+  treeRoot: string,
+  version: string,
+  now: () => string,
+): UpdateAwareness | null {
+  let report: ReturnType<typeof checkUpdateAvailability>;
+  try {
+    report = checkUpdateAvailability(cwd, channel.value, version);
+  } catch {
+    return null;
+  }
+  let tag: string | null = null;
+  let title: string | null = null;
+  if (report.status === "update_available" && report.remote_commit && report.upstream) {
+    tag = remoteTagForCommit(report.upstream, report.remote_commit, inspectGit(cwd).repository);
+    title = localReleaseTitle(tag, treeRoot);
+  }
+  const awareness: UpdateAwareness = {
+    availability: report.status,
+    checked_at: now(),
+    channel: channel.value,
+    current_commit: report.local_commit,
+    remote_commit: report.remote_commit,
+    version: tag,
+    title,
+    note: report.note,
+  };
+  if (report.status === "up_to_date" || report.status === "update_available") {
+    writeUpdateCache(homePath, awareness);
+  }
+  return awareness;
+}
+
+/** Port of `_update_awareness`: cache first, remote only when it must. */
+export function updateAwareness(
+  homePath: string,
+  channel: MarkerValue,
+  cwd: string,
+  version: string,
+  env: NodeJS.ProcessEnv,
+  now: () => string,
+  treeRoot: string = cwd,
+): UpdateAwareness | null {
+  const cached = readUpdateCache(homePath);
+  if (cached && !cacheIsStale(cached) && !cacheShouldRefresh(cached, channel)) return cached;
+  if (remoteUpdateCheckDisabled(env) || channel.value !== "stable") return cached;
+  return refreshUpdateCache(homePath, channel, cwd, treeRoot, version, now) ?? cached;
+}
+
+/** Port of `_update_line`. */
+export function updateLine(
+  channel: MarkerValue,
+  awareness: UpdateAwareness | null,
+  git: GitStatus,
+): string | null {
+  if (awareness && awareness.availability === "update_available") {
+    let label = "✨ New Version Available";
+    if (awareness.version && awareness.title) {
+      label = `${label}: ${awareness.version} — ${awareness.title}`;
+    } else if (awareness.version) {
+      label = `${label}: ${awareness.version}`;
+    } else {
+      label = `${label} on ${awareness.channel}`;
+    }
+    return `${label}\nAsk: "what's new in this update?" or "update my Mirror"`;
+  }
+
+  if (git.repository === null) return null;
+  const plan = inspectGitUpdatePlan(git, channel);
+  if (plan.ready && plan.action === "pull" && plan.behind) {
+    const plural = plan.behind !== 1 ? "s" : "";
+    const upstream = plan.upstream || "upstream";
+    return (
+      `New Version Available: ${plan.behind} commit${plural} behind ${upstream} · ` +
+      "run runtime update\n" +
+      'Ask Mirror: "What\'s new in the latest Mirror Mind release?"'
+    );
+  }
+  return null;
+}
+
+/**
+ * Port of `compose_welcome`. The ONLY path to empty output is an unresolvable
+ * mirror home: a fresh database with nothing in it still renders the full card
+ * with zeroes.
+ */
+export function composeWelcome(options: WelcomeOptions): string {
+  const homePath = options.mirrorHome;
+  if (homePath === null) return "";
+  const cwd = options.cwd ?? process.cwd();
+  const env = options.env ?? process.env;
+  const now = options.now ?? isoNow;
+
+  const dbPath = join(homePath, dbNameForEnv(env.MEMORY_ENV || "production"));
+  const stats = formatStats(readWelcomeStats(existsSync(dbPath) ? dbPath : null));
+  const versionLine = `${options.version} · channel ${options.updateChannel.value}`;
+  const awareness = updateAwareness(
+    homePath,
+    options.updateChannel,
+    cwd,
+    options.version,
+    env,
+    now,
+    options.treeRoot ?? cwd,
+  );
+  const update = updateLine(options.updateChannel, awareness, inspectGit(cwd));
+  return renderWelcome(basename(homePath), stats, versionLine, update);
+}

package/ts/src/welcome/statusLine.ts

@@ -0,0 +1,101 @@
+// The per-turn Mirror status line (CV22.DS7.TS3 plateau 4). Port of
+// `compose_status_line` from `src/memory/cli/welcome.py`.
+//
+// This is the most-executed surface in the product: it renders after every
+// turn, and CR059 made it a front-door call, so until it answers from
+// TypeScript every turn pays a Node start plus a Python start.
+//
+// THE HOT-PATH CONTRACT, enforced by a test that puts a recording `git` shim
+// first on PATH: this module spawns NOTHING. No git, no network, no provider.
+// It reads the update CACHE, never the remote -- refreshing the cache is the
+// full card's job, and the one time that budget was allowed to leak into the
+// per-turn path it cost a 120s network timeout on a status bar.
+
+import { existsSync } from "node:fs";
+import { basename, join } from "node:path";
+import { openDatabaseReadOnly } from "#db/database.ts";
+import { dbNameForEnv } from "#frontDoor/dbPath.ts";
+import { getIdentityContent } from "#identity/identityRead.ts";
+import { GLOBAL_STICKY_DEFAULTS_SESSION_ID, getRuntimeSession } from "#mirror/runtimeSession.ts";
+import { getActiveOperatingMode, modeLabel } from "#mode/operatingMode.ts";
+import { readUpdateCache } from "./updateCache.ts";
+
+export const SEPARATOR = " · ";
+
+export interface StatusLineOptions {
+  /** The resolved mirror home. Null renders nothing, as in the oracle. */
+  mirrorHome: string | null;
+  sessionId?: string | null;
+  env?: NodeJS.ProcessEnv;
+}
+
+/** Port of `_runtime_environment_segment`: production is unmarked. */
+export function runtimeEnvironmentSegment(env: NodeJS.ProcessEnv = process.env): string | null {
+  const memoryEnv = env.MEMORY_ENV || "production";
+  if (memoryEnv === "development") return "🛠 development";
+  if (memoryEnv === "test") return "🧪 test";
+  return null;
+}
+
+/** Port of `_journey_display_name`: the first line, stripped of its `# `. */
+export function journeyDisplayName(content: string | null): string | null {
+  if (content === null) return null;
+  let firstLine = (content.split("\n", 1)[0] ?? "").trim();
+  if (firstLine.startsWith("# ")) firstLine = firstLine.slice(2).trim();
+  return firstLine || null;
+}
+
+/**
+ * Port of `_mode_status_segment`. One read-only connection, opened only when
+ * the database actually exists.
+ */
+function modeStatusSegment(
+  homePath: string,
+  sessionId: string | null,
+  env: NodeJS.ProcessEnv,
+): string | null {
+  const dbPath = join(homePath, dbNameForEnv(env.MEMORY_ENV || "production"));
+  if (!existsSync(dbPath)) return null;
+
+  let db: ReturnType<typeof openDatabaseReadOnly>;
+  try {
+    db = openDatabaseReadOnly(dbPath);
+  } catch {
+    return null;
+  }
+  try {
+    let state = getActiveOperatingMode(db, sessionId ?? null);
+    if (state === null) {
+      // No active mode: fall back to Mirror Mode carrying the sticky journey,
+      // so the line still says WHERE the user is working.
+      const sticky = getRuntimeSession(db, GLOBAL_STICKY_DEFAULTS_SESSION_ID);
+      state = { mode: "Mirror Mode", journey: sticky?.journey ?? null };
+    }
+    if (!state.journey) return modeLabel(state);
+    const display = journeyDisplayName(getIdentityContent(db, "journey", state.journey));
+    return `${display ?? state.journey} on ${modeLabel(state)}`;
+  } finally {
+    db.close();
+  }
+}
+
+/** Port of `compose_status_line`. Returns "" when no home can be resolved. */
+export function composeStatusLine(options: StatusLineOptions): string {
+  const homePath = options.mirrorHome;
+  if (homePath === null) return "";
+  const env = options.env ?? process.env;
+
+  const parts = [`◇ ${basename(homePath)}`];
+  const environment = runtimeEnvironmentSegment(env);
+  if (environment) parts.push(environment);
+  const mode = modeStatusSegment(homePath, options.sessionId ?? null, env);
+  if (mode) parts.push(mode);
+
+  const awareness = readUpdateCache(homePath);
+  if (awareness && awareness.availability === "update_available") {
+    parts.push(`⬆${awareness.version ? ` ${awareness.version}` : ""}`);
+  } else {
+    parts.push("✓");
+  }
+  return parts.join(SEPARATOR);
+}

package/ts/src/welcome/updateCache.ts

@@ -0,0 +1,129 @@
+// The welcome's update-awareness cache (CV22.DS7.TS3 plateau 4). Port of the
+// cache half of `src/memory/cli/welcome.py`.
+//
+// `<mirror home>/runtime/update-check.json` is READ by the per-turn status line
+// and WRITTEN by the full card's refresh. During the transition both cores read
+// and write it, so byte compatibility is a hard requirement rather than a
+// nicety: two cores that serialize the same state differently would rewrite the
+// file on every alternating invocation and thrash the 6h TTL, turning a bounded
+// remote check into one on every turn.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { MarkerValue } from "#runtime/git.ts";
+import { pythonJsonDumpsIndented } from "#util/pyGenerators.ts";
+
+export const UPDATE_CHECK_CACHE = "runtime/update-check.json";
+export const UPDATE_CHECK_TTL_MS = 6 * 60 * 60 * 1000;
+
+export interface UpdateAwareness {
+  availability: string;
+  checked_at: string;
+  channel: string;
+  current_commit: string | null;
+  remote_commit: string | null;
+  version: string | null;
+  title: string | null;
+  note: string | null;
+}
+
+export function cachePath(homePath: string): string {
+  return join(homePath, UPDATE_CHECK_CACHE);
+}
+
+/** Port of `_optional_str`: a non-empty string, or null. */
+function optionalStr(value: unknown): string | null {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+/**
+ * Port of `_read_update_cache`. Every failure mode -- unreadable, malformed,
+ * not an object, or missing one of the three required fields -- yields null,
+ * because a cache that cannot be trusted is the same as no cache.
+ */
+export function readUpdateCache(homePath: string): UpdateAwareness | null {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(cachePath(homePath), "utf8"));
+  } catch {
+    return null;
+  }
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return null;
+  const record = raw as Record<string, unknown>;
+
+  const availability = optionalStr(record.availability);
+  const checkedAt = optionalStr(record.checked_at);
+  const channel = optionalStr(record.channel);
+  if (availability === null || checkedAt === null || channel === null) return null;
+
+  return {
+    availability,
+    checked_at: checkedAt,
+    channel,
+    current_commit: optionalStr(record.current_commit),
+    remote_commit: optionalStr(record.remote_commit),
+    version: optionalStr(record.version),
+    title: optionalStr(record.title),
+    note: optionalStr(record.note),
+  };
+}
+
+/**
+ * Port of `_write_update_cache`. Fail-quietly, like the oracle: a cache that
+ * cannot be written must never break the welcome it decorates.
+ */
+export function writeUpdateCache(homePath: string, awareness: UpdateAwareness): void {
+  const path = cachePath(homePath);
+  const payload = {
+    checked_at: awareness.checked_at,
+    channel: awareness.channel,
+    availability: awareness.availability,
+    current_commit: awareness.current_commit,
+    remote_commit: awareness.remote_commit,
+    version: awareness.version,
+    title: awareness.title,
+    note: awareness.note,
+  };
+  try {
+    if (!existsSync(dirname(path))) mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${pythonJsonDumpsIndented(payload)}\n`, "utf8");
+  } catch {
+    // Fail-quietly contract.
+  }
+}
+
+/** Port of `_parse_iso`, narrowed to the timestamps this cache carries. */
+export function parseIso(value: string | null): Date | null {
+  if (!value) return null;
+  const parsed = Date.parse(value.replace("Z", "+00:00"));
+  return Number.isNaN(parsed) ? null : new Date(parsed);
+}
+
+/**
+ * Port of `_cache_is_stale`. A timestamp that cannot be parsed is stale, not
+ * fresh -- the safe direction for a cache that gates a network call.
+ *
+ * A NAIVE timestamp (no offset) is read as UTC, matching the oracle's explicit
+ * `replace(tzinfo=timezone.utc)`. JavaScript would otherwise read it as local
+ * time and shift the TTL by the machine's offset.
+ */
+export function cacheIsStale(awareness: UpdateAwareness, now: Date = new Date()): boolean {
+  const hasOffset = /(?:Z|[+-]\d{2}:\d{2})$/.test(awareness.checked_at);
+  const checkedAt = parseIso(hasOffset ? awareness.checked_at : `${awareness.checked_at}Z`);
+  if (checkedAt === null) return true;
+  return now.getTime() - checkedAt.getTime() > UPDATE_CHECK_TTL_MS;
+}
+
+/**
+ * Port of `_cache_should_refresh`: stable-channel awareness is refreshed even
+ * inside the TTL. A cached notice may point at an intermediate release, and a
+ * cached up-to-date answer goes wrong the moment stable advances -- opening
+ * Mirror should show the newly published version without manually fetching
+ * refs or deleting this file.
+ */
+export function cacheShouldRefresh(awareness: UpdateAwareness, channel: MarkerValue): boolean {
+  return (
+    (awareness.availability === "up_to_date" || awareness.availability === "update_available") &&
+    channel.value === "stable"
+  );
+}