muse-crew 0.7.20 → 0.8.0

package/lib/update-watch.js

@@ -0,0 +1,633 @@
+#!/usr/bin/env node
+// lib/update-watch.js — the automatic update watcher (deterministic, no LLM
+// judgment). Run daily by the crew-update-watch cron. Watches two things:
+//
+//   1. Crew: public npm registry (npm view muse-crew version) vs the live
+//      release (crew-release.sh current). If newer and policy/channel allow,
+//      file a workflow="upgrade" task with source: npm@<version>.
+//   2. Dashboard: git ls-remote origin HEAD on the first deploy_type=artifact
+//      project vs the recorded sha in $CREW_HOME/.update-watch.json. If
+//      newer and policy allows, read the .crew-version compatibility anchor
+//      declared at the new ref (git fetch origin + git show <sha>:.crew-version)
+//      and file a workflow="chore" task carrying the dashboard-upgrade journey
+//      (old -> new commits). When the anchor declares a newer crew than the
+//      running release, the crew upgrade task is filed FIRST and the dashboard
+//      task notes that it follows the crew upgrade (dashboard-led ordering).
+//
+// Safety invariants (hard):
+//   - The watcher only FILES tasks. It never deploys, never touches the
+//     artifact, never mutates config, never touches the scheduler.
+//   - The npm source is the pinned public registry URL only.
+//   - Every check failure is logged and reported — never thrown. Exit 0 on
+//     every path except a missing --crew-home (exit 2).
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { execFileSync } = require("child_process");
+
+const STATE_FILE = ".update-watch.json";
+const LOG_FILE = "update-watch.log";
+const NPM_REGISTRY = "https://registry.npmjs.org/";
+const SHA40 = /^[0-9a-f]{40}$/;
+
+// ── Pure functions (no IO — exported for tests) ──────────────────────
+
+function parseSemver(v) {
+  if (typeof v !== "string") return null;
+  const m = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/.exec(v.trim());
+  if (!m) return null;
+  return {
+    major: parseInt(m[1], 10),
+    minor: parseInt(m[2], 10),
+    patch: parseInt(m[3], 10),
+    prerelease: m[4] || null,
+    raw: v.trim()
+  };
+}
+
+function compareSemver(a, b) {
+  const keys = ["major", "minor", "patch"];
+  for (let i = 0; i < keys.length; i++) {
+    if (a[keys[i]] !== b[keys[i]]) return a[keys[i]] < b[keys[i]] ? -1 : 1;
+  }
+  if (a.prerelease === b.prerelease) return 0;
+  if (a.prerelease === null) return 1; // a plain release outranks a prerelease
+  if (b.prerelease === null) return -1;
+  if (a.prerelease === b.prerelease) return 0;
+  return a.prerelease < b.prerelease ? -1 : 1;
+}
+
+function channelAllows(channel, current, latest) {
+  if (compareSemver(latest, current) <= 0) return false;
+  if (channel === "patch") {
+    return current.major === latest.major && current.minor === latest.minor;
+  }
+  return true; // "latest"; unknown values are normalized to latest at policy read
+}
+
+// { autoUpdate, current, latest, channel, lastFiled } -> { action, reason }
+// current/latest are parseSemver results (or null when unobtainable),
+// lastFiled is state.crew.last_filed_version (or undefined).
+function crewDecision(opts) {
+  if (!opts.autoUpdate) return { action: "skip", reason: "policy-off" };
+  if (opts.current === null) return { action: "skip", reason: "not-an-npm-release" };
+  if (opts.latest === null) return { action: "skip", reason: "npm-check-failed" };
+  if (compareSemver(opts.latest, opts.current) <= 0) return { action: "skip", reason: "current" };
+  if (!channelAllows(opts.channel, opts.current, opts.latest)) return { action: "skip", reason: "channel" };
+  if (opts.lastFiled === opts.latest.raw) return { action: "skip", reason: "already-filed" };
+  return { action: "file", reason: "newer" };
+}
+
+// { autoUpdate, recordedSha, remoteSha } -> { action, reason }
+function dashboardDecision(opts) {
+  if (!opts.autoUpdate) return { action: "skip", reason: "policy-off" };
+  if (!opts.remoteSha) return { action: "skip", reason: "ls-remote-failed" };
+  if (opts.recordedSha === opts.remoteSha) return { action: "skip", reason: "already-filed" };
+  return { action: "file", reason: "newer" };
+}
+
+// { autoUpdate, current, declared, lastFiledCrew } ->
+// { action: "file-first" | "dashboard-only" | "skip", reason }
+// current/declared are parseSemver results (or null when unobtainable);
+// lastFiledCrew is state.crew.last_filed_version (or undefined).
+//
+// The compatibility-anchor decision: a dashboard release declares the crew
+// version it needs via .crew-version; the watcher treats (dashboard ref,
+// crew version) as one unit and orders upgrades dashboard-led.
+//
+// A declared requirement bypasses update_channel (requirement, not
+// preference) but not the auto_update_crew=false policy opt-out (a hard
+// human decision — the dashboard task then notes the required version for
+// a human). A declared older crew is a downgrade: a human decision, never
+// filed automatically.
+function crewVersionOrdering(opts) {
+  if (opts.declared === null) return { action: "dashboard-only", reason: "anchor-unavailable" };
+  if (opts.current === null) return { action: "dashboard-only", reason: "not-an-npm-release" };
+  const cmp = compareSemver(opts.declared, opts.current);
+  if (cmp < 0) return { action: "skip", reason: "downgrade" };
+  if (cmp === 0) return { action: "dashboard-only", reason: "current" };
+  if (!opts.autoUpdate) return { action: "dashboard-only", reason: "policy-off" };
+  if (opts.lastFiledCrew === opts.declared.raw) return { action: "dashboard-only", reason: "already-filed" };
+  return { action: "file-first", reason: "newer" };
+}
+
+// ── IO helpers (take crewHome so tests use a tmp dir) ────────────────
+
+function stateFilePath(crewHome) { return path.join(crewHome, STATE_FILE); }
+function logFilePath(crewHome) { return path.join(crewHome, LOG_FILE); }
+
+function appendLog(crewHome, level, message) {
+  const line = new Date().toISOString() + " " + level + " " + String(message) + "\n";
+  try {
+    fs.appendFileSync(logFilePath(crewHome), line, "utf8");
+  } catch (e) {
+    // The log is observability, never a gate: a read-only crew home must not
+    // stop the check. stdout still carries the summary.
+  }
+}
+
+function readState(crewHome) {
+  let raw;
+  try {
+    raw = fs.readFileSync(stateFilePath(crewHome), "utf8");
+  } catch (e) {
+    return {}; // missing file: first run
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object") return parsed;
+  } catch (e) {
+    // fall through to the corrupt path below
+  }
+  appendLog(crewHome, "error", "state file corrupt — starting fresh");
+  return {};
+}
+
+function writeState(crewHome, state) {
+  const p = stateFilePath(crewHome);
+  const tmp = p + ".tmp." + process.pid;
+  fs.writeFileSync(tmp, JSON.stringify(state, null, 2) + "\n", "utf8");
+  fs.renameSync(tmp, p); // atomic swap
+}
+
+function firstLine(e) {
+  const s = String((e && e.message) || e || "");
+  return s.split("\n")[0].slice(0, 200);
+}
+
+// Reads the .crew-version compatibility anchor at the filed remote ref.
+// The declaration belongs to the release being evaluated, so it is read from
+// the fetched remote object (git show <sha>:.crew-version), never from the
+// local working tree — the checkout still sits at the recorded sha while the
+// watcher evaluates a newer remote ref, so a working-tree read would answer
+// the old release's declaration (exactly the staleness the anchor exists to
+// fix).
+//
+// Returns the parseSemver result, or null when the anchor is missing,
+// unreadable, or invalid: the dashboard leg then proceeds as today (fail open
+// on the dashboard leg — never block updates on a missing declaration).
+async function readCrewAnchor(deps, crewHome, repoPath, sha) {
+  try {
+    await deps.gitFetch(repoPath);
+  } catch (e) {
+    appendLog(crewHome, "info", "dashboard: git fetch origin failed (" + firstLine(e) + ") — .crew-version unreadable, proceeding as today");
+    return null;
+  }
+  let raw;
+  try {
+    raw = String(await deps.gitShow(repoPath, sha, ".crew-version")).trim();
+  } catch (e) {
+    appendLog(crewHome, "info", "dashboard: no .crew-version at " + sha.slice(0, 7) + " (" + firstLine(e) + ") — proceeding as today");
+    return null;
+  }
+  const parsed = parseSemver(raw);
+  if (!parsed) {
+    appendLog(crewHome, "info", 'dashboard: .crew-version at ' + sha.slice(0, 7) + ' is not strict semver ("' + raw.slice(0, 80) + '") — proceeding as today');
+    return null;
+  }
+  appendLog(crewHome, "info", "dashboard: .crew-version at " + sha.slice(0, 7) + " declares crew " + parsed.raw);
+  return parsed;
+}
+
+// ── Crew upgrade filing (shared by both legs) ────────────────────────
+
+// Files one crew upgrade task and records it in state (idempotency marker
+// last_filed_version, written at file time). Shared by the crew leg (its own
+// npm-vs-current check) and the dashboard leg (dashboard-led ordering).
+// opts: { current, latest (parseSemver), body } — body is the leg-specific
+// description text that follows the pinned "source: npm@<v>" first line.
+// Returns the filed task id, or null when nothing was filed.
+async function fileCrewUpgrade(deps, ctx, summary, opts) {
+  const crewHome = ctx.crewHome;
+  const state = ctx.state;
+
+  let proj;
+  try {
+    proj = await deps.getProject("muse-crew");
+  } catch (e) {
+    proj = null;
+  }
+  if (!proj) {
+    const msg = "crew: no muse-crew project registered — skipping";
+    appendLog(crewHome, "skip", msg);
+    summary.push("update-watch: " + msg);
+    return null;
+  }
+
+  const description =
+    "source: npm@" + opts.latest.raw + "\n" +
+    "\n" +
+    opts.body;
+  try {
+    const task = await deps.createTask({
+      project: "muse-crew",
+      workflow: "upgrade",
+      filed_by: "update-watch",
+      priority: "normal",
+      title: "Upgrade crew to pkg-" + opts.latest.raw,
+      description: description
+    });
+    state.crew = { last_filed_version: opts.latest.raw };
+    writeState(crewHome, state);
+    const taskId = task && task.id ? task.id : "(id unknown)";
+    const msg = "filed crew upgrade task " + taskId + " (pkg-" + opts.current.raw + " -> pkg-" + opts.latest.raw + ")";
+    appendLog(crewHome, "filed", msg);
+    summary.push("update-watch: " + msg);
+    return taskId;
+  } catch (e) {
+    const msg = "crew: create-task failed (" + firstLine(e) + ")";
+    appendLog(crewHome, "error", msg);
+    summary.push("update-watch: " + msg);
+    return null;
+  }
+}
+
+// ── Crew check ────────────────────────────────────────────────────────
+
+async function crewCheck(deps, ctx, summary) {
+  const crewHome = ctx.crewHome;
+  const state = ctx.state;
+  const channel = ctx.channel;
+
+  let currentRaw;
+  try {
+    currentRaw = String(await deps.readCurrent()).trim();
+  } catch (e) {
+    const msg = "crew: could not read current release (" + firstLine(e) + ")";
+    appendLog(crewHome, "error", msg);
+    summary.push("update-watch: " + msg);
+    return;
+  }
+  const current = parseSemver(currentRaw.replace(/^pkg-/, ""));
+  if (!current) {
+    const msg = 'crew: current release "' + currentRaw + '" is not an npm release — skipping crew check';
+    appendLog(crewHome, "skip", msg);
+    summary.push("update-watch: " + msg);
+    return;
+  }
+
+  let latestRaw;
+  try {
+    latestRaw = String(await deps.npmView()).trim();
+  } catch (e) {
+    const msg = "crew: npm check failed (" + firstLine(e) + ")";
+    appendLog(crewHome, "error", msg);
+    summary.push("update-watch: " + msg);
+    return;
+  }
+  const latest = parseSemver(latestRaw);
+  if (!latest) {
+    const msg = 'crew: npm check failed (unparseable version "' + latestRaw + '")';
+    appendLog(crewHome, "error", msg);
+    summary.push("update-watch: " + msg);
+    return;
+  }
+
+  const lastFiled = state.crew && state.crew.last_filed_version;
+  const decision = crewDecision({ autoUpdate: true, current: current, latest: latest, channel: channel, lastFiled: lastFiled });
+  if (decision.action === "skip") {
+    const msg = "crew pkg-" + current.raw + " -> npm " + latest.raw + " (no-op: " + decision.reason + ")";
+    appendLog(crewHome, "skip", msg);
+    summary.push("update-watch: " + msg);
+    return;
+  }
+
+  await fileCrewUpgrade(deps, { crewHome: crewHome, state: state }, summary, {
+    current: current,
+    latest: latest,
+    body:
+      "Automatic crew update: pkg-" + current.raw + " -> pkg-" + latest.raw + ".\n" +
+      "Filed by the update watcher (policy auto_update_crew, channel " + channel + ").\n" +
+      "The upgrade workflow deploys and verifies; this task is the trigger only."
+  });
+}
+
+// ── Dashboard check ──────────────────────────────────────────────────
+
+async function dashboardCheck(deps, ctx, summary) {
+  const crewHome = ctx.crewHome;
+  const state = ctx.state;
+
+  let projects;
+  try {
+    projects = await deps.listProjects();
+  } catch (e) {
+    const msg = "dashboard: list-projects failed (" + firstLine(e) + ")";
+    appendLog(crewHome, "error", msg);
+    summary.push("update-watch: " + msg);
+    return;
+  }
+  const proj = (projects || []).find(function (p) {
+    return p && p.deploy_type === "artifact" && p.repo_path;
+  });
+  if (!proj) {
+    const msg = "dashboard: no artifact project — skipping";
+    appendLog(crewHome, "skip", msg);
+    summary.push("update-watch: " + msg);
+    return;
+  }
+  const projectId = proj.id || proj.project_id;
+
+  let remote;
+  try {
+    remote = String(await deps.gitConfigGet(proj.repo_path, "remote.origin.url")).trim();
+  } catch (e) {
+    remote = "";
+  }
+  if (!remote) {
+    const msg = "dashboard: no origin remote on " + proj.repo_path + " — skipping";
+    appendLog(crewHome, "skip", msg);
+    summary.push("update-watch: " + msg);
+    return;
+  }
+
+  let sha = "";
+  let lsErr = null;
+  try {
+    sha = String(await deps.lsRemote(remote)).trim().split(/\s+/)[0] || "";
+  } catch (e) {
+    lsErr = firstLine(e);
+  }
+  if (!SHA40.test(sha)) {
+    const msg = "dashboard: ls-remote failed (" + (lsErr || "unparseable output") + ")";
+    appendLog(crewHome, "error", msg);
+    summary.push("update-watch: " + msg);
+    return;
+  }
+
+  const recorded = (state.dashboard && state.dashboard[projectId] && state.dashboard[projectId].last_filed_sha) || null;
+  const decision = dashboardDecision({ autoUpdate: true, recordedSha: recorded, remoteSha: sha });
+  if (decision.action === "skip") {
+    const msg = "dashboard " + projectId + " " + sha.slice(0, 7) + " -> " + sha.slice(0, 7) + " (no-op: " + decision.reason + ")";
+    appendLog(crewHome, "skip", msg);
+    summary.push("update-watch: " + msg);
+    return;
+  }
+
+  const oldSha = recorded || "unknown";
+  const oldSha7 = recorded ? recorded.slice(0, 7) : "unknown";
+
+  // Compatibility anchor (.crew-version): the release at `sha` declares the
+  // crew version it needs. Read at the filed ref, never the working tree.
+  const declared = await readCrewAnchor(deps, crewHome, proj.repo_path, sha);
+
+  let current = null;
+  if (declared) {
+    let currentRaw;
+    try {
+      currentRaw = String(await deps.readCurrent()).trim();
+    } catch (e) {
+      appendLog(crewHome, "info", "dashboard: could not read current release (" + firstLine(e) + ") — anchor unevaluable, proceeding as today");
+    }
+    if (currentRaw !== undefined) {
+      current = parseSemver(currentRaw.replace(/^pkg-/, ""));
+      if (!current) {
+        appendLog(crewHome, "info", 'dashboard: running crew "' + currentRaw.slice(0, 40) + '" is not an npm release — anchor unevaluable, proceeding as today');
+      }
+    }
+  }
+
+  const ordering = crewVersionOrdering({
+    autoUpdate: ctx.autoUpdateCrew,
+    current: current,
+    declared: declared,
+    lastFiledCrew: state.crew && state.crew.last_filed_version
+  });
+
+  if (ordering.action === "skip") {
+    const msg = "dashboard " + projectId + " " + oldSha7 + " -> " + sha.slice(0, 7) +
+      " skipped: .crew-version declares crew " + declared.raw +
+      " older than running pkg-" + current.raw + " (a downgrade is a human decision)";
+    appendLog(crewHome, "skip", msg);
+    summary.push("update-watch: " + msg);
+    return; // state untouched — a downgrade is never filed automatically
+  }
+
+  // Dashboard-led ordering: file the required crew upgrade first, so the
+  // dashboard task can note that it follows the crew upgrade.
+  let crewTaskId = null;
+  if (ordering.action === "file-first") {
+    crewTaskId = await fileCrewUpgrade(deps, { crewHome: crewHome, state: state }, summary, {
+      current: current,
+      latest: declared,
+      body:
+        "Dashboard-led crew update: pkg-" + current.raw + " -> pkg-" + declared.raw + ".\n" +
+        "Required by dashboard " + projectId + " release " + sha.slice(0, 7) + " (.crew-version).\n" +
+        "Filed by the update watcher (policy auto_update_crew; a declared requirement, not an update_channel preference).\n" +
+        "The upgrade workflow deploys and verifies; this task is the trigger only.\n" +
+        "The dashboard upgrade to " + sha.slice(0, 7) + " is filed as its own task and must follow this one."
+    });
+    if (!crewTaskId) {
+      // The crew upgrade could not be filed (logged inside fileCrewUpgrade).
+      // The (dashboard ref, crew version) unit cannot be ordered — hold the
+      // dashboard leg rather than filing an upgrade the crew cannot run.
+      const msg = "dashboard " + projectId + " " + sha.slice(0, 7) +
+        " held: crew upgrade to pkg-" + declared.raw + " could not be filed — dashboard task not filed";
+      appendLog(crewHome, "error", msg);
+      summary.push("update-watch: " + msg);
+      return;
+    }
+  }
+
+  // Ordering note for the dashboard task, inserted right after the pinned
+  // "source: dashboard@<sha>" first line.
+  let orderingNote = "";
+  if (ordering.action === "file-first") {
+    orderingNote =
+      "Ordering: this dashboard release declares crew " + declared.raw + " (.crew-version).\n" +
+      "The crew upgrade (task " + crewTaskId + ") was filed first and must land before this dashboard upgrade proceeds.";
+  } else if (ordering.reason === "already-filed") {
+    orderingNote =
+      "Ordering: this dashboard release declares crew " + declared.raw + " (.crew-version).\n" +
+      "The crew upgrade task was already filed and must land before this dashboard upgrade proceeds.";
+  } else if (ordering.reason === "policy-off") {
+    orderingNote =
+      "Note: this dashboard release declares crew " + declared.raw + " (.crew-version),\n" +
+      "but auto_update_crew=false — a human must upgrade the crew to pkg-" + declared.raw + " first.";
+  }
+
+  const description =
+    "source: dashboard@" + sha + "\n" +
+    (orderingNote === "" ? "" : "\n" + orderingNote + "\n") +
+    "\n" +
+    "Automatic dashboard upgrade: " + oldSha7 + " -> " + sha.slice(0, 7) + ".\n" +
+    "Filed by the update watcher (policy auto_update_dashboard).\n" +
+    "\n" +
+    "Journey (execute mechanically, no judgment):\n" +
+    "1. In " + proj.repo_path + ": git fetch origin && git rev-parse origin/HEAD — must\n" +
+    "   match " + sha + ". Mismatch → park the task and say so.\n" +
+    "2. Ancestor check: git merge-base --is-ancestor " + oldSha + " " + sha + ". If " + oldSha + "\n" +
+    "   is unknown or not an ancestor (force-push / history rewrite) → park\n" +
+    "   the task and say so. Never upgrade across a rewritten history blind.\n" +
+    "3. Review: git log " + oldSha + ".." + sha + " --oneline and git diff --stat\n" +
+    "   " + oldSha + " " + sha + ". Anything unrelated or suspicious → park and say so.\n" +
+    "4. Check out " + sha + " in the working copy and let this chore's Publish phase\n" +
+    "   carry the artifact update (the normal publish path — no side channels).";
+  try {
+    const task = await deps.createTask({
+      project: projectId,
+      workflow: "chore",
+      filed_by: "update-watch",
+      priority: "normal",
+      title: "Dashboard upgrade to " + sha.slice(0, 7),
+      description: description
+    });
+    state.dashboard = state.dashboard || {};
+    state.dashboard[projectId] = { last_filed_sha: sha };
+    writeState(crewHome, state);
+    const taskId = task && task.id ? task.id : "(id unknown)";
+    const msg = "filed dashboard upgrade task " + taskId + " (" + oldSha7 + " -> " + sha.slice(0, 7) + ")";
+    appendLog(crewHome, "filed", msg);
+    summary.push("update-watch: " + msg);
+  } catch (e) {
+    const msg = "dashboard: create-task failed (" + firstLine(e) + ")";
+    appendLog(crewHome, "error", msg);
+    summary.push("update-watch: " + msg);
+  }
+}
+
+// ── Pipeline ─────────────────────────────────────────────────────────
+
+async function run(deps) {
+  const crewHome = deps.crewHome;
+  const summary = [];
+  const state = readState(crewHome);
+  appendLog(crewHome, "info", "watch run started");
+
+  let config = {};
+  try {
+    config = (await deps.getConfig()) || {};
+  } catch (e) {
+    const msg = "config read failed (" + firstLine(e) + ") — checks skipped";
+    appendLog(crewHome, "error", msg);
+    summary.push("update-watch: " + msg);
+    appendLog(crewHome, "info", "watch run finished");
+    return { summary: summary };
+  }
+  const autoUpdateCrew = config.auto_update_crew !== "false";
+  const autoUpdateDashboard = config.auto_update_dashboard !== "false";
+  let channel = config.update_channel || "latest";
+  if (channel !== "latest" && channel !== "patch") {
+    appendLog(crewHome, "info", 'unknown update_channel "' + channel + '", treating as latest');
+    channel = "latest";
+  }
+
+  if (!autoUpdateCrew) {
+    const msg = "crew check skipped (auto_update_crew=false)";
+    appendLog(crewHome, "skip", "crew: policy off (auto_update_crew=false)");
+    summary.push("update-watch: " + msg);
+  } else {
+    await crewCheck(deps, { crewHome: crewHome, state: state, channel: channel }, summary);
+  }
+
+  if (!autoUpdateDashboard) {
+    const msg = "dashboard check skipped (auto_update_dashboard=false)";
+    appendLog(crewHome, "skip", "dashboard: policy off (auto_update_dashboard=false)");
+    summary.push("update-watch: " + msg);
+  } else {
+    await dashboardCheck(deps, { crewHome: crewHome, state: state, autoUpdateCrew: autoUpdateCrew }, summary);
+  }
+
+  appendLog(crewHome, "info", "watch run finished");
+  return { summary: summary };
+}
+
+// ── Real deps (shell out; built once in main) ────────────────────────
+
+function shOut(cmd, args, timeoutMs) {
+  return execFileSync(cmd, args, { encoding: "utf8", timeout: timeoutMs || 30000 }).toString();
+}
+
+function apiCall(crewHome, command, jsonArgs) {
+  const args = [
+    path.join(crewHome, "current", "lib", "crew-api.js"),
+    "--crew-home", crewHome,
+    command
+  ];
+  if (jsonArgs !== undefined) args.push("--json", JSON.stringify(jsonArgs));
+  const out = shOut(process.execPath, args);
+  return JSON.parse(out);
+}
+
+function buildRealDeps(crewHome) {
+  return {
+    crewHome: crewHome,
+    getConfig: function () { return apiCall(crewHome, "get-config").config || {}; },
+    readCurrent: function () {
+      return shOut("/bin/bash", [path.join(crewHome, "crew-release.sh"), "current", crewHome]).trim();
+    },
+    npmView: function () {
+      // Pinned to the public registry — never a local path, never a git URL.
+      return shOut("npm", ["view", "muse-crew", "version", "--registry", NPM_REGISTRY]).trim();
+    },
+    getProject: function (id) { return apiCall(crewHome, "get-project", { id: id }).project; },
+    listProjects: function () { return apiCall(crewHome, "list-projects").projects; },
+    gitConfigGet: function (repoPath, key) {
+      return shOut("git", ["-C", repoPath, "config", "--get", key]).trim();
+    },
+    lsRemote: function (remote) {
+      try {
+        const out = shOut("git", ["ls-remote", remote, "HEAD"]);
+        return (out.trim().split(/\s+/)[0] || "");
+      } catch (e) {
+        const first = String((e && e.stderr) || (e && e.message) || e || "").split("\n")[0].slice(0, 200);
+        throw new Error("ls-remote failed (" + first + ")");
+      }
+    },
+    gitFetch: function (repoPath) {
+      // Throws on failure; the caller fails open.
+      return shOut("git", ["-C", repoPath, "fetch", "origin"]).trim();
+    },
+    gitShow: function (repoPath, sha, filePath) {
+      // Throws when the ref or file is missing; the caller fails open.
+      // sha is SHA40-validated before it reaches here; filePath is the
+      // constant ".crew-version".
+      return shOut("git", ["-C", repoPath, "show", sha + ":" + filePath]).trim();
+    },
+    createTask: function (args) { return apiCall(crewHome, "create-task", args).task; }
+  };
+}
+
+// ── CLI ──────────────────────────────────────────────────────────────
+
+function main() {
+  const args = process.argv.slice(2);
+  let crewHome = null;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--crew-home" && i + 1 < args.length) crewHome = args[i + 1];
+  }
+  if (!crewHome) {
+    process.stderr.write("usage: node update-watch.js --crew-home <path>\n");
+    process.exit(2);
+  }
+  run(buildRealDeps(crewHome)).then(
+    function (res) {
+      res.summary.forEach(function (line) { process.stdout.write(line + "\n"); });
+      process.exit(0);
+    },
+    function (e) {
+      // Defensive last resort: run() is built to never throw, but if it does
+      // the loop must still survive.
+      appendLog(crewHome, "error", "unexpected failure (" + firstLine(e) + ")");
+      process.stdout.write("update-watch: unexpected failure (logged)\n");
+      process.exit(0);
+    }
+  );
+}
+
+module.exports = {
+  parseSemver: parseSemver,
+  compareSemver: compareSemver,
+  channelAllows: channelAllows,
+  crewDecision: crewDecision,
+  dashboardDecision: dashboardDecision,
+  crewVersionOrdering: crewVersionOrdering,
+  fileCrewUpgrade: fileCrewUpgrade,
+  readState: readState,
+  writeState: writeState,
+  appendLog: appendLog,
+  run: run
+};
+
+if (require.main === module) main();