viewable-one 0.0.0-stage → 0.12.2

package/lib/sync.mjs

@@ -0,0 +1,484 @@
+// PUT BACK WHAT IS MISSING, TOUCH NOTHING THAT IS THERE.
+//
+// Ruling 5's second duty (2026-09-06). The four things a folder needs in
+// order for a session to run in it are each written by a different act, at a
+// different time, by a different tool - and each of them can go away on its
+// own. `.mcp.json` is lost to a `git clean`. The opencode registration lives
+// in opencode's own store and a reinstall drops it. The registry entry goes
+// when someone edits folders.json. The plist's captured PATH goes stale the
+// day Homebrew is installed. Nothing noticed any of that until a session
+// failed.
+//
+// So the daemon re-checks all four on every start, and `init` and `doctor`
+// call exactly the same function - one implementation, so the three cannot
+// drift into three different opinions about what a folder needs.
+//
+// THE RULE IS ONE-WAY. A missing thing is written; a thing that is there is
+// read and reported and left exactly as it is. The one place that is not
+// literal is the plist's PATH, and it is not an exception so much as the
+// same rule applied to the CONTENTS of the file: a PATH that has lost entries
+// the shell now has is missing those entries, and they are added back as a
+// union so nothing already captured is dropped. That trade is deliberate and
+// it is the launchd PATH trap; see lib/logindaemon.mjs.
+//
+// 2026-09-07, brief 21 session 4: the fourth row is no longer launchd. It
+// asks lib/logindaemon.mjs for THIS machine's implementation - a LaunchAgent
+// on macOS, a Task Scheduler onlogon task on Windows (ruling 1A), a systemd
+// user unit on WSL and Linux (ruling 6C) - and the logic below is the same
+// three questions on all three: is the file there, does its captured PATH
+// still cover this shell, and is the OS actually holding it. The row's KEY
+// stays "plist" because that is the contract doctor and the tests read; its
+// LABEL is what the platform calls the thing.
+
+import { readFile, realpath, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { detectAgents, execProbe } from "./detect.mjs";
+import {
+  DAEMON_LABEL,
+  RUNNER_BY_HAND,
+  daemonPackageVersion,
+  viewableScriptPath,
+  loginDaemon,
+  noDaemonInstall,
+} from "./logindaemon.mjs";
+import { BOARD_MCP_URL, DEFAULT_BOARD_MCP_URL, mergeBoardServer } from "./mcpjson.mjs";
+import { addFolder, readRegistry } from "./registry.mjs";
+import { readAgentSelection, parseAgentSelection } from "./agent-selection.mjs";
+import { syncProjectMcp } from "./project-mcp.mjs";
+import { packageVersion } from "./update.mjs";
+import { readRunnerHealth } from "./runner-health.mjs";
+
+export const MCP_FILE = ".mcp.json";
+/** What opencode's own CLI is told to register, for the legacy repair path
+ * (a folder with no saved agent selection - `syncOpencode` below, not the
+ * per-project `opencode.json` `syncProjectMcp` writes). The board is a
+ * hosted URL, so this registers it the way `opencode mcp add --help`
+ * documents a remote server (`--url`), with no process to spawn.
+ *
+ * RENAMED 2026-09-12 (brief 31, Move 3): the name is `glytch`, not `board`. */
+export const OPENCODE_ADD = ["mcp", "add", "glytch", "--url", BOARD_MCP_URL()];
+
+/** `action` is the one next step THIS row needs, when the generic "run
+ * viewable init" is wrong - a denied Task Scheduler registration being the case
+ * that named it (2026-09-11): init runs the same refused command, so the
+ * default advice was a loop. lib/cli-output.mjs prefers it over its own. */
+const row = (key, label, ok, state, detail = "", action) =>
+  action ? { key, label, ok, state, detail, action } : { key, label, ok, state, detail };
+
+/** `.mcp.json` in this folder, by the app's rules.
+ *
+ * 2026-09-11 (brief 30): the shape is one hosted URL on every platform now
+ * (lib/mcpjson.mjs), so `platform` stopped being the axis that mattered here
+ * - it is still accepted, unused, because every caller already threads one
+ * through for `syncLaunchAgent`'s sake and removing the parameter would
+ * touch every call site for no behavioural gain. `env` is the new axis
+ * (`GLYTCH_BOARD_URL`, for a dev pointing at another deployment), for the
+ * same reason `platform` used to be one: a test has to be able to say which,
+ * rather than inheriting whatever happens to be set in the runner's shell.
+ * A pre-existing `board` entry naming the retired local server is upgraded
+ * in place (`merge.kind === "legacy"`) rather than left to name a server
+ * that no longer runs; any other custom entry is still left exactly as it
+ * is, unchanged since before this ruling. */
+export async function syncMcpJson(root, { write = true, platform = process.platform, env = process.env } = {}) {
+  const path = join(root, MCP_FILE);
+  let existing = null;
+  try {
+    existing = await readFile(path, "utf8");
+  } catch {
+    existing = null;
+  }
+  const merge = mergeBoardServer(existing, env);
+  if (merge.kind === "present") return row("mcp", ".mcp.json", true, "present", "board connection already registered");
+  if (merge.kind === "unreadable") {
+    return row(
+      "mcp",
+      ".mcp.json",
+      false,
+      "unreadable",
+      `${path} exists and is not JSON we can extend. It is someone's work, so nothing was written - open it and add {"mcpServers":{"viewable":{"type":"http","url":"${DEFAULT_BOARD_MCP_URL}"}}} by hand.`,
+    );
+  }
+  if (!write) {
+    return merge.kind === "legacy"
+      ? row("mcp", ".mcp.json", false, "legacy-command", `${path} still names the retired ${merge.moved ? "board address - run viewable init to move it to app.viewable.one" : "local MCP server - run viewable init to switch it to the hosted board URL"}`)
+      : row("mcp", ".mcp.json", false, merge.kind, "missing the Viewable server");
+  }
+  await writeFile(path, merge.text, "utf8");
+  return merge.kind === "legacy"
+    ? row("mcp", ".mcp.json", true, "upgraded", `glytch entry ${merge.moved ? "moved to app.viewable.one" : "upgraded from the old command shape to the hosted URL"}`)
+    : row("mcp", ".mcp.json", true, merge.kind, merge.kind === "create" ? "written" : "viewable entry added beside what was there");
+}
+
+/** opencode's own MCP registry. It does not read .mcp.json, so this is the
+ * whole of its setup - and it is skipped, green, on a machine that has no
+ * opencode: a folder does not need a registration for a tool nobody has. */
+export async function syncOpencode(root, { exec = execProbe, found, write = true } = {}) {
+  if (!found) return row("opencode", "opencode glytch server", true, "absent", "opencode is not installed - nothing to register");
+  if (!exec) return row("opencode", "opencode glytch server", true, "unknown", "not checked");
+  const listed = await exec("opencode", ["mcp", "list"], { cwd: root });
+  // RENAMED 2026-09-12 (brief 31, Move 3): opencode registers the server as
+  // `glytch` now (OPENCODE_ADD above), so that is the name its own `mcp
+  // list` reports back when it is already there.
+  const already = listed?.ok === true && /\bglytch\b/.test(`${listed.stdout ?? ""}${listed.stderr ?? ""}`);
+  if (already) return row("opencode", "opencode glytch server", true, "present", "glytch entry registered with opencode");
+  if (!write) return row("opencode", "opencode glytch server", false, "missing", "glytch entry not registered with opencode");
+  const added = await exec("opencode", OPENCODE_ADD, { cwd: root });
+  return added?.ok === true
+    ? row("opencode", "opencode glytch server", true, "added", `ran: opencode ${OPENCODE_ADD.join(" ")}`)
+    : row("opencode", "opencode glytch server", false, "failed", (added?.stderr ?? "").trim() || "opencode mcp add failed");
+}
+
+/** This folder's entry in ~/.glytch/folders.json.
+ *
+ * `addFolder` can THROW - a Windows profile with a locked-down `%USERPROFILE%`
+ * (a managed machine, OneDrive redirecting the folder and briefly denying a
+ * write) refuses the file the same way `schtasks` refuses an unelevated
+ * registration - and until this pass that exception reached `doctor`/`init`
+ * uncaught: a stack trace instead of a row, and a project that silently never
+ * became "a runner project" because nothing here ever told the person why. A
+ * write failure is now the same shape every other row in this file uses -
+ * red, with the OS's own reason and something to try - never a crash. */
+export async function syncRegistry(root, { env = process.env, write = true } = {}) {
+  const folders = await readRegistry(env);
+  if (folders.includes(root)) return row("registry", "folder registered", true, "present", "your computer watches this folder");
+  if (!write) return row("registry", "folder registered", false, "missing", "this folder is not in ~/.glytch/folders.json");
+  try {
+    await addFolder(root, env);
+  } catch (error) {
+    const why = error instanceof Error ? error.message : String(error);
+    return row(
+      "registry",
+      "folder registered",
+      false,
+      "could not write",
+      `~/.glytch/folders.json could not be written: ${why}`,
+      "Check that ~/.glytch is writable by this account (on Windows, a locked-down or OneDrive-redirected profile can refuse it), then rerun viewable init.",
+    );
+  }
+  return row("registry", "folder registered", true, "added", "added to ~/.glytch/folders.json");
+}
+
+/** The entries of a PATH, in order, without the empties.
+ *
+ * 2026-09-07: the delimiter is an argument because a Windows PATH is `;`
+ * separated and its entries contain `C:`. It defaults to `:` rather than to
+ * `path.delimiter` on purpose - what these three functions are asked about is
+ * the PATH inside a plist, a launcher or a unit, which belongs to the
+ * IMPLEMENTATION being synced and not to the platform this process happens to
+ * be running on, so the caller passes impl.pathDelimiter. */
+export const pathEntries = (value, delimiter = ":") =>
+  String(value ?? "").split(delimiter).filter((e) => e !== "");
+
+/** What this shell has that the plist did not capture. ORDER IS NOT THE
+ * QUESTION: a plist capturing "/opt/homebrew/bin:/usr/bin" already covers a
+ * shell whose PATH is "/usr/bin:/opt/homebrew/bin", and rewriting it because
+ * the strings differ would rewrite the plist on every doctor run for ever. */
+export const missingPathEntries = (captured, current, delimiter = ":") => {
+  const have = new Set(pathEntries(captured, delimiter));
+  return pathEntries(current, delimiter).filter((entry) => !have.has(entry));
+};
+
+/** The union of two PATHs, the shell's order first, nothing dropped. */
+export function mergePaths(captured, current, delimiter = ":") {
+  const seen = new Set();
+  const out = [];
+  for (const entry of [...String(current ?? "").split(delimiter), ...String(captured ?? "").split(delimiter)]) {
+    if (entry === "" || seen.has(entry)) continue;
+    seen.add(entry);
+    out.push(entry);
+  }
+  return out.join(delimiter);
+}
+
+/** THE OTHER WAY A DAEMON FILE CAN BE WRONG - not a stale PATH but a stale
+ * SCRIPT (brief 31 repair, 2026-09-12). His Mac's plist named
+ * `~/.npm/_npx/<hash>/node_modules/glytch/glytch.mjs`, a 0.5.0 package, while
+ * `viewable init` ran from a 0.7.0 checkout - `doctor`'s daemonVersion row
+ * (lib/doctor.mjs) already noticed and said "run viewable init", but init's own
+ * sync only ever compared the captured PATH and reported "present" without
+ * looking at the script path at all. This is that missing look.
+ *
+ * Compared on the RESOLVED path - `realpath`, so an npm-linked symlink
+ * equals the checkout it points at (a plain string compare would rewrite a
+ * perfectly good `npm link` on every run) - with the package version beside
+ * each script as a second signal, for the same reason `daemonVersion` reads
+ * both: a path can survive a rename that a version catches, and a version
+ * can survive a path a symlink makes look different.
+ *
+ * NEVER RED FOR A FACT ABOUT THE WORLD (the rule doctor.mjs's own
+ * daemonVersion row already follows): when the INSTALLED script path does
+ * not resolve to a real file, there is nothing here to compare it against -
+ * `daemonPackageVersion` already calls that "unknown" rather than a mismatch,
+ * and so does this. Returns null for "leave it alone", or the two sides of
+ * the story for the row to print. */
+async function scriptMismatch({ installedScriptPath, currentScriptPath, currentVersion }) {
+  if (!installedScriptPath || installedScriptPath === currentScriptPath) return null;
+  let oldReal;
+  try {
+    oldReal = await realpath(installedScriptPath);
+  } catch {
+    return null;
+  }
+  const newReal = await realpath(currentScriptPath).catch(() => null);
+  const oldVersion = await daemonPackageVersion(installedScriptPath);
+  const pathDiffers = newReal === null || oldReal !== newReal;
+  const versionDiffers = oldVersion !== null && oldVersion !== currentVersion;
+  if (!pathDiffers && !versionDiffers) return null;
+  return { oldPath: installedScriptPath, newPath: currentScriptPath, oldVersion, newVersion: currentVersion };
+}
+
+/** The login daemon and the PATH it captured. Machine-wide rather than
+ * per-folder, but it is checked here because it is the fourth thing a folder
+ * needs and a person asking `doctor` in a folder wants one list.
+ *
+ * The name stayed `syncLaunchAgent` through brief 21 because every caller and
+ * every test says it; WHAT it syncs is whatever lib/logindaemon.mjs says this
+ * machine installs. */
+export async function syncLaunchAgent({
+  env = process.env,
+  // `launchctl` is what brief 19's callers and tests pass; `exec` is the same
+  // injected OS tool under the name the interface uses. Either works, and
+  // whichever is given is the only thing that ever reaches launchctl,
+  // schtasks or systemctl.
+  launchctl,
+  exec,
+  write = true,
+  path = env.PATH ?? "",
+  nodePath,
+  scriptPath,
+  // THE ONE CALLER THAT MUST NEVER LOAD ITSELF. multiwatch.mjs's own start
+  // (2026-09-06 finding) runs this same sync, and it IS the loaded daemon
+  // already - calling `launchctl load` from inside the process launchd is
+  // holding would unload the very process running this line, mid-sync. The
+  // same is true word for word of `schtasks /run` and of `systemctl --user
+  // enable --now` (2026-09-07), so the guard covers all three. That caller
+  // passes daemon:true and the present-but-unloaded branch below never
+  // reaches the OS tool at all when it is set. init and doctor leave it
+  // false, which is what lets THEM restart a stopped daemon.
+  daemon = false,
+  restart = false,
+  ensureVersion = false,
+  platform,
+  procVersion,
+  impl = loginDaemon({ env, platform: platform ?? process.platform, procVersion }),
+  // What THIS install would name the row's script-mismatch check against -
+  // the running package's own version, unless a test injects one so it
+  // never depends on which version this checkout happens to be at.
+  version = packageVersion(),
+} = {}) {
+  // GLYTCH_NO_DAEMON_INSTALL (GLYTCH_NO_LAUNCHCTL is its older name and still
+  // works): the file is written and nothing is registered, and the row says
+  // so in those words rather than failing. Ruling 7 of brief 19 - the real
+  // agent goes on his Mac after the build, by his word at that moment - and
+  // the tests, which must never touch launchd, Task Scheduler or systemd.
+  const escape = noDaemonInstall(env);
+  const skipped = Boolean(escape);
+  const tool = exec ?? launchctl;
+  const call = tool ? { exec: tool } : {};
+  const label = impl.rowLabel;
+  const file = impl.filePath(env);
+  const text = await impl.read(env);
+  if (text === null) {
+    if (!write) return row("plist", label, false, "missing", `no ${file}`);
+    const result = await impl.install({ env, ...call, path, nodePath, scriptPath });
+    if (skipped) {
+      return row("plist", label, true, "written, not loaded", `wrote ${result.file}; ${escape} is set, so ${impl.tool} was not run`);
+    }
+    // Ruling 6C: an older WSL with no `systemctl --user` is told the truth and
+    // given the fallback, rather than sent to `glytch init` for ever.
+    if (result.unavailable) {
+      return row("plist", label, true, "no systemd here", `wrote ${result.file}; systemctl --user is not available - run: ${RUNNER_BY_HAND}`);
+    }
+    return row(
+      "plist",
+      label,
+      result.loaded,
+      // Not "written, not loaded" - that state is the escape above, which is
+      // a green row on purpose. This one failed.
+      result.loaded ? "installed" : "written, not registered",
+      result.loaded ? `wrote and loaded ${result.file}` : `wrote ${result.file} but ${impl.tool} failed: ${result.why}`,
+      result.action,
+    );
+  }
+  const captured = impl.capturedPath(text);
+  const missing = missingPathEntries(captured, path, impl.pathDelimiter);
+  // Init must compare the loaded process with the installed CLI, not the
+  // package.json that npm may already have replaced at this same path.
+  // A legacy process has no version proof and needs one replacement. A
+  // process that has attested this version is left alone, even when its next
+  // beat is delayed: init waits for health rather than disrupting a busy run.
+  const loadedState = ensureVersion && !daemon && !skipped
+    ? await impl.loadedState({ env, ...call }) : null;
+  const health = loadedState?.loaded ? readRunnerHealth(env) : null;
+  const replaceLoadedVersion = loadedState?.loaded && (!health?.instance || health.version !== version);
+
+  // THE FILE NAMES A DIFFERENT SCRIPT THAN THIS INSTALL. Checked before the
+  // PATH branches below and gated on `daemon` the same way the present-but-
+  // unloaded branch is: the running daemon's own multiwatch loop must never
+  // unload itself mid-sync, so it leaves this repair to `init` and `doctor`,
+  // which both pass daemon:false.
+  if (!daemon) {
+    const currentScriptPath = scriptPath ?? viewableScriptPath();
+    const mismatch = await scriptMismatch({
+      installedScriptPath: impl.programScriptPath(text),
+      currentScriptPath,
+      currentVersion: version,
+    });
+    if (mismatch || restart || replaceLoadedVersion) {
+      const change = mismatch ?? { oldPath: impl.programScriptPath(text), newPath: currentScriptPath, oldVersion: health?.version ?? null, newVersion: version };
+      const oldVersionText = change.oldVersion ?? "unknown";
+      if (!write) {
+        return row(
+          "plist",
+          label,
+          false,
+          "different script",
+          `${file} runs ${change.oldPath} (${oldVersionText}); this install is ${change.newPath} (${change.newVersion})`,
+        );
+      }
+      const merged = mergePaths(captured, path, impl.pathDelimiter);
+      const result = await impl.install({ env, ...call, path: merged, nodePath, scriptPath: currentScriptPath, force: true });
+      if (skipped) {
+        return row(
+          "plist",
+          label,
+          true,
+          "rewritten, not loaded",
+          `rewrote ${result.file}; ${escape} is set, so ${impl.tool} was not run`,
+        );
+      }
+      if (result.unavailable) {
+        return row("plist", label, true, "no systemd here", `rewrote ${result.file}; systemctl --user is not available - run: ${RUNNER_BY_HAND}`);
+      }
+      return row(
+        "plist",
+        label,
+        result.loaded,
+        result.loaded ? "rewritten" : "rewritten, not restarted",
+        result.loaded
+          ? `was running ${change.oldPath} (${oldVersionText}); now ${change.newPath} (${change.newVersion})`
+          : `rewrote ${file} but ${impl.tool} failed: ${result.why}`,
+        result.action,
+      );
+    }
+  }
+  if (captured !== null && captured !== "" && missing.length === 0) {
+    // THE FILE IS UNCHANGED, BUT IS THE OS ACTUALLY HOLDING IT (2026-09-06
+    // end-to-end finding): `glytch stop` stops the daemon and leaves the file
+    // exactly as it was, and this branch used to stop right here and call that
+    // "present" even though nothing was watching - so `glytch init` after
+    // `glytch stop` printed ok and started nothing. Ask the OS.
+    if (skipped || daemon) {
+      return row("plist", label, true, "present", `${file}, PATH captured`);
+    }
+    const state = loadedState ?? await impl.loadedState({ env, ...call });
+    if (state.loaded) return row("plist", label, true, "present", `${file}, PATH captured`);
+    // REFUSED IS NOT MISSING (2026-09-11, his Windows machine). `schtasks
+    // /query` denied and `schtasks /query` on a task that is not there both
+    // exit non-zero, and treating the first as the second made init re-run a
+    // registration it was never allowed to make, then tell him to run init.
+    // The row says what happened and carries the step that actually helps.
+    if (state.denied) {
+      return row("plist", label, false, "present, cannot be checked", `${file} is on disk; ${impl.tool} refused: ${state.why}`, state.action);
+    }
+    if (state.unavailable) {
+      return row("plist", label, true, "no systemd here", `${file} is on disk; systemctl --user is not available - run: ${RUNNER_BY_HAND}`);
+    }
+    if (!write) {
+      return row(
+        "plist",
+        label,
+        false,
+        "present, not loaded",
+        `${file} is on disk but ${impl.holder} is not holding ${DAEMON_LABEL} - run: viewable init`,
+      );
+    }
+    const result = await impl.install({ env, ...call, path, nodePath, scriptPath, load: true });
+    return row(
+      "plist",
+      label,
+      result.loaded,
+      // The state told the truth only when the load worked: "loaded now" on a
+      // row already printing FAIL is the line that has to be read twice.
+      result.loaded ? "present, was not loaded, loaded now" : "present, not loaded",
+      result.loaded
+        ? `${file} was on disk but ${impl.holder} was not holding it; loaded now`
+        : `${label} present but ${impl.tool} failed: ${result.why}`,
+      result.action,
+    );
+  }
+  const merged = mergePaths(captured, path, impl.pathDelimiter);
+  if (!write) {
+    return row("plist", label, false, "stale PATH", "the captured PATH is missing entries this shell has");
+  }
+  const result = await impl.install({ env, ...call, path: merged, nodePath, scriptPath, force: true });
+  if (skipped) {
+    return row("plist", label, true, "PATH refreshed, not loaded", `rewrote ${result.file}; ${escape} is set, so ${impl.tool} was not run`);
+  }
+  if (result.unavailable) {
+    return row("plist", label, true, "no systemd here", `rewrote ${result.file}; systemctl --user is not available - run: ${RUNNER_BY_HAND}`);
+  }
+  return row(
+    "plist",
+    label,
+    result.loaded,
+    // "not loaded" is the escape's state a few lines up, and that row is green
+    // on purpose; this one failed, so it gets its own words.
+    result.loaded ? "PATH refreshed" : "PATH refreshed, not restarted",
+    result.loaded
+      ? `the captured PATH was missing ${missing.length} entry/entries this shell has; they were added and your computer restarted`
+      : `rewrote ${file} but ${impl.tool} failed: ${result.why}`,
+    result.action,
+  );
+}
+
+/** All four, for one folder. `write:false` turns the whole thing into a
+ * report, which is what a caller wants when it is only describing state. */
+export async function syncFolder(
+  root,
+  {
+    env = process.env,
+    exec,
+    launchctl,
+    agents,
+    selectedAgents,
+    write = true,
+    path = env.PATH ?? "",
+    nodePath,
+    scriptPath,
+    daemon = false,
+    ensureVersion = false,
+    deferRegistry = false,
+    platform,
+    procVersion,
+    impl,
+    version,
+  } = {},
+) {
+  // Missing choices retain legacy repairs. Once init saves a selection,
+  // every caller (including the background daemon) obeys that project choice.
+  // AN EXPLICIT EMPTY SELECTION (2026-09-19, `chooseAgents`' own `--yes`
+  // fallback when nothing was found) is a deliberate "no agent to connect
+  // yet", not the invalid input `parseAgentSelection` refuses - it is passed
+  // through as `[]` rather than validated, so the loop below simply writes
+  // no agent-specific config while the registry and daemon rows still run.
+  const selected = selectedAgents === undefined
+    ? await readAgentSelection(root)
+    : Array.isArray(selectedAgents) && selectedAgents.length === 0
+      ? []
+      : parseAgentSelection(selectedAgents);
+  const found = agents ?? (await detectAgents({ env }));
+  const rows = deferRegistry ? [] : [await syncRegistry(root, { env, write })];
+  if (selected === null) {
+    rows.push(await syncMcpJson(root, { write, platform, env }));
+    rows.push(await syncOpencode(root, { exec, found: found?.opencode?.found === true, write }));
+  } else {
+    for (const agent of selected) {
+      rows.push(agent === "claude"
+        ? await syncMcpJson(root, { write, platform, env })
+        : await syncProjectMcp(root, agent, { write, env }));
+    }
+  }
+  rows.push(await syncLaunchAgent({ env, launchctl, write, path, nodePath, scriptPath, daemon, ensureVersion, platform, procVersion, impl, version }));
+  return rows;
+}