harnery 0.46.1 → 0.47.0

package/src/core/autoupdate/fingerprint.ts

@@ -0,0 +1,89 @@
+/**
+ * Fingerprint of the watched paths outside Git. A change in any watched
+ * file's mtime or size, or in a watched directory's direct children, changes
+ * the fingerprint and forces an update run (`drift`).
+ */
+
+import { createHash } from "node:crypto";
+import { readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+
+/**
+ * Expand `~/` (or a bare `~`) and `$VAR` / `${VAR}`. Returns null when a
+ * referenced variable is unset, so the entry fingerprints as missing instead
+ * of resolving somewhere unintended.
+ */
+export function expandWatchPath(
+  entry: string,
+  projectRoot: string,
+  env: NodeJS.ProcessEnv = process.env,
+): string | null {
+  let unset = false;
+  let out = entry.replace(
+    /\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g,
+    (_m, a, b) => {
+      const value = env[(a ?? b) as string];
+      if (value === undefined || value === "") {
+        unset = true;
+        return "";
+      }
+      return value;
+    },
+  );
+  if (unset) return null;
+  if (out === "~" || out.startsWith("~/") || out.startsWith("~\\")) {
+    const home = env.HOME || env.USERPROFILE || homedir();
+    out = join(home, out.slice(1));
+  }
+  return isAbsolute(out) ? resolve(out) : resolve(projectRoot, out);
+}
+
+function statLine(path: string): string | null {
+  try {
+    const st = statSync(path);
+    return `${st.isDirectory() ? "dir" : "file"}\t${Math.trunc(st.mtimeMs)}\t${st.isDirectory() ? 0 : st.size}`;
+  } catch {
+    return null;
+  }
+}
+
+/** The raw lines behind the fingerprint (sorted), for diagnostics and tests. */
+export function fingerprintLines(
+  watch: readonly string[],
+  projectRoot: string,
+  env: NodeJS.ProcessEnv = process.env,
+): string[] {
+  const lines: string[] = [];
+  for (const entry of watch) {
+    const path = expandWatchPath(entry, projectRoot, env);
+    const self = path ? statLine(path) : null;
+    if (!path || !self) {
+      lines.push(`${entry}\tmissing`);
+      continue;
+    }
+    lines.push(`${entry}\t${self}`);
+    if (!self.startsWith("dir\t")) continue;
+    let children: string[] = [];
+    try {
+      children = readdirSync(path);
+    } catch {
+      children = [];
+    }
+    for (const child of children) {
+      lines.push(`${entry}/${child}\t${statLine(join(path, child)) ?? "missing"}`);
+    }
+  }
+  return lines.sort();
+}
+
+/** sha1 hex of the sorted fingerprint lines. */
+export function fingerprint(
+  watch: readonly string[],
+  projectRoot: string,
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  return createHash("sha1")
+    .update(fingerprintLines(watch, projectRoot, env).join("\n"))
+    .digest("hex");
+}

package/src/core/autoupdate/git.ts

@@ -0,0 +1,120 @@
+/**
+ * The few Git reads self-update needs. Every call is synchronous, bounded by a
+ * timeout, and goes through an injectable runner so tests never touch a
+ * network remote.
+ */
+
+import { spawnSync } from "node:child_process";
+
+export interface GitResult {
+  status: number | null;
+  stdout: string;
+  stderr: string;
+}
+
+export type GitRunner = (args: string[], opts: { cwd: string; timeoutMs: number }) => GitResult;
+
+const LOCAL_TIMEOUT_MS = 10_000;
+const REMOTE_TIMEOUT_MS = 15_000;
+
+export const defaultGitRunner: GitRunner = (args, opts) => {
+  const result = spawnSync("git", args, {
+    cwd: opts.cwd,
+    encoding: "utf8",
+    timeout: opts.timeoutMs,
+    windowsHide: true,
+    // Never block a background run on a credential prompt.
+    env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+  });
+  return {
+    status: result.error ? null : result.status,
+    stdout: typeof result.stdout === "string" ? result.stdout : "",
+    stderr: typeof result.stderr === "string" ? result.stderr : "",
+  };
+};
+
+function read(
+  run: GitRunner,
+  root: string,
+  args: string[],
+  timeoutMs = LOCAL_TIMEOUT_MS,
+): string | null {
+  const result = run(args, { cwd: root, timeoutMs });
+  if (result.status !== 0) return null;
+  const out = result.stdout.trim();
+  return out || null;
+}
+
+export function head(root: string, run: GitRunner = defaultGitRunner): string | null {
+  return read(run, root, ["rev-parse", "HEAD"]);
+}
+
+export interface Upstream {
+  remote: string;
+  branch: string;
+  /** e.g. `origin/main`. */
+  display: string;
+}
+
+/** The current branch's upstream, or null when detached or untracked. */
+export function upstream(root: string, run: GitRunner = defaultGitRunner): Upstream | null {
+  const display = read(run, root, ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"]);
+  if (!display) return null;
+  const current = read(run, root, ["symbolic-ref", "--quiet", "--short", "HEAD"]);
+  if (current) {
+    const remote = read(run, root, ["config", "--get", `branch.${current}.remote`]);
+    const merge = read(run, root, ["config", "--get", `branch.${current}.merge`]);
+    if (remote && merge) {
+      return { remote, branch: merge.replace(/^refs\/heads\//, ""), display };
+    }
+  }
+  const slash = display.indexOf("/");
+  if (slash <= 0) return null;
+  return { remote: display.slice(0, slash), branch: display.slice(slash + 1), display };
+}
+
+/** The remote branch's sha, or null when the remote cannot be reached or lacks the branch. */
+export function lsRemote(
+  root: string,
+  remote: string,
+  branch: string,
+  run: GitRunner = defaultGitRunner,
+): string | null {
+  const out = read(
+    run,
+    root,
+    ["ls-remote", "--exit-code", remote, `refs/heads/${branch}`],
+    REMOTE_TIMEOUT_MS,
+  );
+  if (!out) return null;
+  const sha = out.split(/\s+/)[0] ?? "";
+  return /^[0-9a-f]{40,64}$/.test(sha) ? sha : null;
+}
+
+/** True when `sha` exists locally and is an ancestor of HEAD. */
+export function contains(root: string, sha: string, run: GitRunner = defaultGitRunner): boolean {
+  const exists = run(["cat-file", "-e", `${sha}^{commit}`], {
+    cwd: root,
+    timeoutMs: LOCAL_TIMEOUT_MS,
+  });
+  if (exists.status !== 0) return false;
+  const ancestor = run(["merge-base", "--is-ancestor", sha, "HEAD"], {
+    cwd: root,
+    timeoutMs: LOCAL_TIMEOUT_MS,
+  });
+  return ancestor.status === 0;
+}
+
+export function changedFiles(
+  root: string,
+  from: string,
+  to: string,
+  run: GitRunner = defaultGitRunner,
+): string[] {
+  const out = read(run, root, ["diff", "--name-only", from, to]);
+  if (!out) return [];
+  return out
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+}

package/src/core/autoupdate/index.ts

@@ -0,0 +1,29 @@
+export {
+  AUTOUPDATE_CHILD_ENV,
+  type AutoUpdateDeps,
+  type AutoUpdateStatus,
+  autoUpdateStatus,
+  autoUpdateTick,
+  checkForUpdate,
+  harnCliEntry,
+  isHookConfigPath,
+  isInstructionPath,
+  parseNoticeLines,
+  type RunAutoUpdateOptions,
+  type RunAutoUpdateResult,
+  runAutoUpdate,
+  type StepRunner,
+  type StepRunResult,
+} from "./engine.ts";
+export { expandWatchPath, fingerprint, fingerprintLines } from "./fingerprint.ts";
+export type { GitResult, GitRunner, Upstream } from "./git.ts";
+export {
+  addNotice,
+  autoUpdateLogPath,
+  autoUpdateStatePath,
+  type LockInspection,
+  type LockOwner,
+  pendingNotices,
+  readAutoUpdateState,
+} from "./state.ts";
+export * from "./types.ts";

package/src/core/autoupdate/state.ts

@@ -0,0 +1,269 @@
+/**
+ * Persistent state for project self-update: `state.json` (last run, converged
+ * point, notices, per-session delivery) and the `run.lock` directory that keeps
+ * one runner per checkout.
+ *
+ * Writers re-read the file immediately before writing (`mutateAutoUpdateState`)
+ * because a long run and the prompt hooks that deliver notices both update it.
+ */
+
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { hostname } from "node:os";
+import { join, resolve } from "node:path";
+import {
+  AUTOUPDATE_FILES,
+  type AutoUpdateConfig,
+  type AutoUpdateNotice,
+  type AutoUpdateState,
+  type NoticeKind,
+} from "./types.ts";
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const NOTICE_DEDUPE_MS = DAY_MS;
+const NOTICE_KEEP = 20;
+const NEW_SESSION_WINDOW_MS = DAY_MS;
+const DELIVERED_PRUNE_MS = 7 * DAY_MS;
+
+export function autoUpdateDir(coordRoot: string): string {
+  return join(resolve(coordRoot), AUTOUPDATE_FILES.dir);
+}
+
+export function autoUpdateStatePath(coordRoot: string): string {
+  return join(autoUpdateDir(coordRoot), AUTOUPDATE_FILES.state);
+}
+
+export function autoUpdateStampPath(coordRoot: string): string {
+  return join(autoUpdateDir(coordRoot), AUTOUPDATE_FILES.stamp);
+}
+
+export function autoUpdateLockPath(coordRoot: string): string {
+  return join(autoUpdateDir(coordRoot), AUTOUPDATE_FILES.lock);
+}
+
+/** The run log lives with the other Harnery logs, not in private state. */
+export function autoUpdateLogPath(coordRoot: string): string {
+  return join(resolve(coordRoot), ".harnery", "logs", AUTOUPDATE_FILES.log);
+}
+
+export function freshAutoUpdateState(): AutoUpdateState {
+  return { schema: 1, notices: [], delivered: {} };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isNotice(value: unknown): value is AutoUpdateNotice {
+  return (
+    isRecord(value) &&
+    typeof value.id === "string" &&
+    typeof value.at === "string" &&
+    typeof value.kind === "string" &&
+    typeof value.text === "string"
+  );
+}
+
+/** Read state; a missing or corrupt file yields fresh state. */
+export function readAutoUpdateState(coordRoot: string): AutoUpdateState {
+  let raw: string;
+  try {
+    raw = readFileSync(autoUpdateStatePath(coordRoot), "utf8");
+  } catch {
+    return freshAutoUpdateState();
+  }
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    if (!isRecord(parsed) || parsed.schema !== 1) return freshAutoUpdateState();
+    const state = parsed as unknown as AutoUpdateState;
+    const notices = Array.isArray(parsed.notices) ? parsed.notices.filter(isNotice) : [];
+    const delivered: Record<string, string> = {};
+    if (isRecord(parsed.delivered)) {
+      for (const [key, at] of Object.entries(parsed.delivered)) {
+        if (typeof at === "string") delivered[key] = at;
+      }
+    }
+    return { ...state, schema: 1, notices, delivered };
+  } catch {
+    return freshAutoUpdateState();
+  }
+}
+
+/** Write state atomically (temp file + rename). */
+export function writeAutoUpdateState(coordRoot: string, state: AutoUpdateState): void {
+  const dir = autoUpdateDir(coordRoot);
+  mkdirSync(dir, { recursive: true });
+  const target = autoUpdateStatePath(coordRoot);
+  const tmp = `${target}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`);
+  try {
+    renameSync(tmp, target);
+  } catch (err) {
+    rmSync(tmp, { force: true });
+    throw err;
+  }
+}
+
+/** Re-read, apply `mutate`, write. Returns the written state. */
+export function mutateAutoUpdateState(
+  coordRoot: string,
+  mutate: (state: AutoUpdateState) => void,
+): AutoUpdateState {
+  const state = readAutoUpdateState(coordRoot);
+  mutate(state);
+  writeAutoUpdateState(coordRoot, state);
+  return state;
+}
+
+function noticeId(kind: NoticeKind, text: string, at: string): string {
+  return createHash("sha1").update(`${kind}\n${text}\n${at}`).digest("hex").slice(0, 12);
+}
+
+/**
+ * Append a notice to `state` in place. The same kind and text within 24 hours
+ * is not repeated; only the newest 20 notices are kept. Returns the notice now
+ * on record (the earlier one when deduplicated).
+ */
+export function addNotice(
+  state: AutoUpdateState,
+  kind: NoticeKind,
+  text: string,
+  now: number = Date.now(),
+): AutoUpdateNotice {
+  const existing = state.notices.find(
+    (n) => n.kind === kind && n.text === text && now - Date.parse(n.at) < NOTICE_DEDUPE_MS,
+  );
+  if (existing) return existing;
+  const at = new Date(now).toISOString();
+  const notice: AutoUpdateNotice = { id: noticeId(kind, text, at), at, kind, text };
+  state.notices.push(notice);
+  if (state.notices.length > NOTICE_KEEP) {
+    state.notices = state.notices.slice(state.notices.length - NOTICE_KEEP);
+  }
+  return notice;
+}
+
+/**
+ * Notices this session has not seen yet, marked delivered. A session key with
+ * no record sees only the last 24 hours. Cheap when there is nothing to say:
+ * no write happens unless a notice is returned.
+ */
+export function pendingNotices(
+  coordRoot: string,
+  sessionKey: string,
+  now: number = Date.now(),
+): AutoUpdateNotice[] {
+  const state = readAutoUpdateState(coordRoot);
+  if (state.notices.length === 0) return [];
+  const since = state.delivered[sessionKey];
+  const cutoff = since ?? new Date(now - NEW_SESSION_WINDOW_MS).toISOString();
+  const fresh = state.notices.filter((n) => (since ? n.at > cutoff : n.at >= cutoff));
+  if (fresh.length === 0) return [];
+  const newest = fresh.reduce((max, n) => (n.at > max ? n.at : max), fresh[0]?.at ?? "");
+  mutateAutoUpdateState(coordRoot, (s) => {
+    const prior = s.delivered[sessionKey];
+    if (!prior || newest > prior) s.delivered[sessionKey] = newest;
+    for (const [key, at] of Object.entries(s.delivered)) {
+      const ms = Date.parse(at);
+      if (key !== sessionKey && (!Number.isFinite(ms) || now - ms > DELIVERED_PRUNE_MS)) {
+        delete s.delivered[key];
+      }
+    }
+  });
+  return fresh;
+}
+
+// ---------------------------------------------------------------- run lock
+
+export interface LockOwner {
+  pid: number;
+  at: string;
+  host?: string;
+}
+
+/** Minutes after which a held lock counts as abandoned. */
+export function lockStaleMinutes(
+  cfg: Pick<AutoUpdateConfig, "timeoutMinutes" | "steps" | "dailySteps">,
+): number {
+  return cfg.timeoutMinutes * Math.max(1, cfg.steps.length + cfg.dailySteps.length) + 5;
+}
+
+export interface LockInspection {
+  held: boolean;
+  stale: boolean;
+  owner: LockOwner | null;
+  ageMs: number | null;
+}
+
+/** Inspect the lock without taking it. One stat when free. */
+export function inspectLock(
+  coordRoot: string,
+  cfg: Pick<AutoUpdateConfig, "timeoutMinutes" | "steps" | "dailySteps">,
+  now: number = Date.now(),
+): LockInspection {
+  const lockDir = autoUpdateLockPath(coordRoot);
+  let dirMtime: number;
+  try {
+    dirMtime = statSync(lockDir).mtimeMs;
+  } catch {
+    return { held: false, stale: false, owner: null, ageMs: null };
+  }
+  let owner: LockOwner | null = null;
+  try {
+    const parsed = JSON.parse(readFileSync(join(lockDir, "owner.json"), "utf8")) as unknown;
+    if (isRecord(parsed) && typeof parsed.pid === "number" && typeof parsed.at === "string") {
+      owner = {
+        pid: parsed.pid,
+        at: parsed.at,
+        ...(typeof parsed.host === "string" ? { host: parsed.host } : {}),
+      };
+    }
+  } catch {
+    owner = null;
+  }
+  const since = owner ? Date.parse(owner.at) : dirMtime;
+  const ageMs = now - (Number.isFinite(since) ? since : dirMtime);
+  const stale = ageMs > lockStaleMinutes(cfg) * 60_000;
+  return { held: true, stale, owner, ageMs };
+}
+
+export type LockAttempt =
+  | { acquired: true; release: () => void }
+  | { acquired: false; owner: LockOwner | null };
+
+/** Take the run lock, breaking it once when it is stale. */
+export function acquireRunLock(
+  coordRoot: string,
+  cfg: Pick<AutoUpdateConfig, "timeoutMinutes" | "steps" | "dailySteps">,
+  now: number = Date.now(),
+): LockAttempt {
+  mkdirSync(autoUpdateDir(coordRoot), { recursive: true });
+  const lockDir = autoUpdateLockPath(coordRoot);
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      mkdirSync(lockDir);
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
+      const inspection = inspectLock(coordRoot, cfg, now);
+      if (!inspection.stale || attempt > 0) return { acquired: false, owner: inspection.owner };
+      rmSync(lockDir, { recursive: true, force: true });
+      continue;
+    }
+    const owner: LockOwner = {
+      pid: process.pid,
+      at: new Date(now).toISOString(),
+      host: hostname(),
+    };
+    writeFileSync(join(lockDir, "owner.json"), `${JSON.stringify(owner)}\n`);
+    let released = false;
+    return {
+      acquired: true,
+      release: () => {
+        if (released) return;
+        released = true;
+        rmSync(lockDir, { recursive: true, force: true });
+      },
+    };
+  }
+  return { acquired: false, owner: inspectLock(coordRoot, cfg, now).owner };
+}

package/src/core/autoupdate/types.ts

@@ -0,0 +1,135 @@
+/**
+ * Shared contracts for project self-update (ADR 0229).
+ *
+ * Activity fires it: every prompt, session start, and host CLI command calls
+ * `autoUpdateTick`, whose hot path is one stat of a throttle stamp. When the
+ * stamp is stale, the tick launches a detached `<harn> autoupdate run
+ * --background`, which exits early unless the upstream branch moved, a
+ * watched path outside Git changed, the daily check is due, or the last run
+ * failed. Only then does it run the host's configured steps.
+ */
+
+/** `.harnery/config.jsonc` `autoUpdate` section, after lenient parsing. */
+export interface AutoUpdateConfig {
+  enabled: boolean;
+  /** Minimum minutes between remote checks. Default 15, range 1..1440. */
+  checkMinutes: number;
+  /** Argv arrays run in order from the project root when an update is needed; first failure stops. */
+  steps: string[][];
+  /** Argv arrays run at most once per 24h even when current (e.g. a doctor). */
+  dailySteps: string[][];
+  /**
+   * Paths outside Git whose change forces a run (managed tools, generated
+   * hook configs). `~/` and `$VAR` expand; relative paths resolve from the
+   * project root. A directory is fingerprinted shallowly (its own mtime plus
+   * each direct child's mtime and size).
+   */
+  watch: string[];
+  /** Per-step timeout in minutes. Default 20. */
+  timeoutMinutes: number;
+  /** Run `artifacts clean --yes` (expired only) at most once per day after a successful run. Default true. */
+  cleanup: boolean;
+}
+
+export const AUTOUPDATE_DEFAULTS = {
+  checkMinutes: 15,
+  timeoutMinutes: 20,
+  /** After a failed run, wait at least this long before the next attempt. */
+  failureBackoffMinutes: 60,
+  dailyHours: 24,
+} as const;
+
+/**
+ * Step output protocol. A line `harnery-notice: <text>` (stdout or stderr)
+ * becomes a notice for the agents in this checkout. Exit code 75 means the
+ * step finished what it could but needs a person (outcome `blocked`), which
+ * is not retried as a failure.
+ */
+export const NOTICE_PREFIX = "harnery-notice:";
+export const EXIT_NEEDS_PERSON = 75;
+
+export type CheckReason =
+  | "disabled"
+  | "behind" // upstream has a commit HEAD does not contain
+  | "drift" // a watched path changed since the last converged run
+  | "daily" // daily steps are due
+  | "retry" // last run failed and the backoff elapsed
+  | "forced"
+  | "current" // nothing to do
+  | "no-upstream" // detached or untracked branch and no drift
+  | "offline"; // ls-remote failed
+
+export interface CheckDecision {
+  needed: boolean;
+  reason: CheckReason;
+  head: string | null;
+  upstream: string | null; // e.g. "origin/main"
+  remoteSha: string | null;
+  fingerprint: string;
+  /** True when only daily steps should run (repo already current). */
+  dailyOnly: boolean;
+  detail?: string;
+}
+
+export type NoticeKind = "instructions" | "hooks" | "person" | "failure" | "info";
+
+export interface AutoUpdateNotice {
+  id: string;
+  at: string;
+  kind: NoticeKind;
+  text: string;
+}
+
+export interface StepRecord {
+  argv: string[];
+  exitCode: number | null;
+  ms: number;
+  timedOut?: boolean;
+}
+
+export type RunOutcome =
+  | "current"
+  | "updated"
+  | "blocked"
+  | "failed"
+  | "skipped-locked"
+  | "offline";
+
+export interface RunRecord {
+  startedAt: string;
+  finishedAt: string;
+  outcome: RunOutcome;
+  reason: CheckReason;
+  fromHead: string | null;
+  toHead: string | null;
+  steps: StepRecord[];
+  error?: string;
+}
+
+/** `.harnery/private/autoupdate/state.json`. */
+export interface AutoUpdateState {
+  schema: 1;
+  converged?: { head: string; remoteSha: string | null; fingerprint: string; at: string };
+  lastRun?: RunRecord;
+  dailyAt?: string;
+  cleanupAt?: string;
+  notices: AutoUpdateNotice[];
+  /** Per session key (agent instance id), the `at` of the newest notice already delivered. */
+  delivered: Record<string, string>;
+}
+
+export interface TickResult {
+  action: "disabled" | "throttled" | "locked" | "launched" | "error";
+  detail?: string;
+}
+
+/** Files under `.harnery/private/autoupdate/` (except `log`, see below). */
+export const AUTOUPDATE_FILES = {
+  dir: ".harnery/private/autoupdate",
+  /** Throttle stamp; only its mtime matters. */
+  stamp: "checked-at",
+  state: "state.json",
+  lock: "run.lock",
+  /** Run log lives at .harnery/logs/autoupdate.log (not in this dir). */
+  log: "autoupdate.log",
+} as const;