viewable-one 0.0.0-stage → 0.12.2

package/lib/uninstall-project.mjs

@@ -0,0 +1,589 @@
+// THE PER-PROJECT HALF OF `glytch uninstall` (brief 31, 2026-09-12).
+//
+// `glytch init` writes four things into a project and one credential into
+// each selected agent: the `.mcp.json` / `.codex/config.toml` /
+// `opencode.json` entry (lib/project-mcp.mjs, lib/mcpjson.mjs), the saved
+// choice of which agents this project uses (`.glytch/agents.json`,
+// lib/agent-selection.mjs), the folder's row in ~/.glytch/folders.json
+// (lib/registry.mjs), and - since brief 31 Move 2 - each agent's own OAuth
+// token for the `glytch` MCP server (lib/init-connect.mjs). This file is the
+// reverse of all four, run from the project being disconnected. The
+// machine-level half (the daemon, the login agent, the signed-in machine
+// itself) is a different question and a different worker's file - this one
+// only undoes what `init` did TO THIS FOLDER.
+//
+// ORDER MATTERS. The OAuth sign-out (step 1) runs before the config files
+// are touched (step 2), because at least one agent's `logout`/`remove` verb
+// resolves the server by NAME against its own configured list, and until the
+// config file is edited, `.mcp.json`'s `glytch` entry is still how that name
+// resolves for Claude Code's project scope.
+//
+// NEVER THROWS. A missing file, a missing agent, a server nobody ever
+// connected - every one of those is a row, not an exception, the same
+// promise lib/doctor.mjs's rows keep. `dryRun` runs every read (a probe, a
+// file read, a registry lookup) so its rows are accurate, and skips every
+// write (no exec call, no file write, no delete, no registry edit).
+
+import { readdir, rm, stat } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { parse as parseToml } from "smol-toml";
+import { parse as parseJsonc, modify, applyEdits } from "jsonc-parser";
+
+import { boardEntryIsOurs as jsonBoardEntryIsOurs } from "./mcpjson.mjs";
+import { boardEntryIsOurs as codexBoardEntryIsOurs, opencodeBoardEntryIsOurs, projectMcpServerKeys, readOptional, withoutTomlTable } from "./project-mcp.mjs";
+import { detectAgents, execProbe } from "./detect.mjs";
+import { SERVER_KEY, lastStderrLine } from "./init-connect.mjs";
+import { writeFileAtomic } from "./atomic.mjs";
+import { readRegistry, removeFolder } from "./registry.mjs";
+import { row, warnRow } from "./cli-output.mjs";
+
+/** `code: message`, or just the message when there is no `.code` (a plain
+ *  `Error`, not a Node `fs` errno one). Used only by the per-step try/catch
+ *  wrapping below (U4, brief 31 review) to turn an exception into a FAIL row
+ *  someone can actually act on, rather than a stack trace that aborts the
+ *  whole `viewable uninstall` run over one bad folder. */
+const describeError = (error) => (error?.code ? `${error.code}: ${error.message ?? error}` : String(error?.message ?? error));
+
+// --------------------------------------------------------------- Step 1
+//
+// Each agent's own verb, run whenever the agent is INSTALLED - not whenever
+// this project selected it. A token is per machine, and the verb is cheap
+// and idempotent (every agent below answered instantly, with no browser, in
+// testing), so there is no reason to skip it for a project that happened to
+// pick only one or two agents: it costs nothing to also clear a token this
+// project never used, and it is the only chance `uninstall` gets to leave
+// the machine as if `init` had never touched it.
+//
+// `claude mcp remove glytch -s project` was considered and dropped
+// (`claude mcp remove --help`, 2026-09-12 on 2.1.269): its only scope
+// argument is "local, user, or project", and "project" scope IS the
+// `.mcp.json` file this module already edits directly in step 2 - Claude
+// Code has no separate bookkeeping for that scope beyond the file itself.
+// Running it would either no-op against a file step 2 already rewrote, or
+// (in the other order) delete the same entry step 2 was about to delete
+// anyway. Redundant either way, so it is skipped.
+export const LOGOUT_VERBS = {
+  claude: { label: "Claude Code", bin: "claude", verb: ["mcp", "logout", SERVER_KEY] },
+  codex: { label: "codex", bin: "codex", verb: ["mcp", "logout", SERVER_KEY] },
+  opencode: { label: "opencode", bin: "opencode", verb: ["mcp", "logout", SERVER_KEY] },
+};
+
+/** Logout is local-only - no browser, no person to wait on - so it gets a
+ *  short timeout rather than init-connect's LOGIN_TIMEOUT_MS (five minutes,
+ *  sized for a person finding their password manager). Every logout call
+ *  measured below returned in well under a second. */
+export const LOGOUT_TIMEOUT_MS = 15_000;
+
+/** THE WORDING EACH BINARY USES FOR "no credential was ever stored", MEASURED
+ *  2026-09-12 by adding a throwaway HTTP server (a name no real project
+ *  uses, pointed at a URL nobody has ever authenticated against) and running
+ *  each agent's own logout verb against it, then removing the fixture:
+ *
+ *    claude    2.1.269: `claude mcp logout <name>` prints
+ *              `Signed out of "<name>". Run \`claude mcp login <name>\` to
+ *              authenticate again.` with exit 0 - the SAME wording whether
+ *              or not a credential was ever issued. Claude Code has no
+ *              distinct "nothing was stored" message to key on, so every
+ *              exit-0 result is reported plainly as "signed out"; there is
+ *              no `claude` entry in the map below on purpose. (A name with
+ *              no configured server at all is a DIFFERENT, non-zero-exit
+ *              case: `No MCP server named "<name>". Configured servers:
+ *              ...` - that falls through to the generic failure branch.)
+ *    codex     0.153.4: `codex mcp logout <name>` prints
+ *              `No OAuth credentials stored for '<name>'.` with exit 0 -
+ *              for a configured-but-never-authenticated server AND for a
+ *              name with no configured server at all; codex's logout is a
+ *              credential-store lookup, not a config lookup.
+ *    opencode  1.18.23: `opencode mcp logout <name>` prints (through its
+ *              boxed CLI chrome) `No credentials found for: <name>` with
+ *              exit 0 - again for both a configured-but-unauthenticated
+ *              server and a name that was never configured at all.
+ */
+const NOTHING_STORED = {
+  codex: /No OAuth credentials stored for/i,
+  opencode: /No credentials found for/i,
+};
+
+/** A NON-ZERO EXIT THAT IS NOT A FAILURE - the agent is telling us there was
+ *  never a credential in reach for THIS project, not that the sign-out
+ *  attempt broke. Both were found by a real run of `viewable uninstall`
+ *  (2026-09-12) against a project whose `.mcp.json` had never been opened in
+ *  an interactive session:
+ *
+ *    claude  2.1.269, exit 1: Claude Code refuses to touch an MCP server it
+ *            has never had a person approve - a project-scope `.mcp.json`
+ *            entry needs a session opened in that directory and the
+ *            approval prompt clicked through once, and nobody had:
+ *              "glytch" is from .mcp.json and awaiting approval. Run
+ *              `claude` in this directory to review it first.
+ *            There is no credential to revoke, so this is `ok`, not `fail`.
+ *    codex   0.153.4, exit 1: Codex only reads a project's
+ *            `.codex/config.toml` at all when the project is TRUSTED
+ *            (`codex --help`'s own trust model) - an untrusted project, or
+ *            one whose entry is simply gone, is invisible to it rather than
+ *            "present but unauthenticated":
+ *              Error: No MCP server named 'glytch' found in configuration.
+ *            Same conclusion: nothing was ever configured here for codex to
+ *            hold a credential for, so this is `ok`, not `fail`.
+ *
+ *  opencode needs no entry here - its own logout (NOTHING_STORED above) is
+ *  already `ok` on exit 0 for a name that was never configured at all, the
+ *  same wording either way. */
+const NOT_A_FAILURE = {
+  claude: [
+    { pattern: /is from \.mcp\.json and awaiting approval/i, state: "not approved yet", detail: "nothing to sign out of" },
+    // A Codex-only project: Claude is installed but never had this server.
+    { pattern: /No MCP server named/i, state: "not configured", detail: "Claude Code has no Viewable server to sign out of" },
+  ],
+  codex: [{ pattern: /No MCP server named .* found in configuration/i, state: "not configured", detail: "codex has no glytch server to sign out of" }],
+};
+
+/** `cwd: root` (brief 31 review, U1): Claude Code resolves a project-scoped
+ *  MCP server by NAME against the project open in the CURRENT WORKING
+ *  DIRECTORY, not against `root` as a plain argument - `claude mcp logout
+ *  glytch` run from anywhere else cannot see this project's `.mcp.json`
+ *  entry at all, the exact "awaiting approval" / "no MCP server named"
+ *  outcomes NOT_A_FAILURE above exists to word correctly are also what a
+ *  correctly-configured project looks like from the wrong cwd. codex and
+ *  opencode read their own project config the same way. */
+async function logoutRows({ root, agents, exec, env, dryRun, log }) {
+  const rows = [];
+  for (const key of Object.keys(LOGOUT_VERBS)) {
+    if (!agents?.[key]?.found) continue;
+    const { label, bin } = LOGOUT_VERBS[key];
+    // Every name on disk gets signed out: its entry is deleted in step 2, and
+    // a credential left behind under a deleted name is never reached again.
+    const names = await projectMcpServerKeys(root, key);
+    for (const serverKey of names.length ? names : [SERVER_KEY]) {
+      const verb = [...LOGOUT_VERBS[key].verb.slice(0, -1), serverKey];
+      const command = `${bin} ${verb.join(" ")}`;
+      const rowKey = `${key}Logout`;
+      const rowLabel = names.length > 1 ? `${label} sign-out (${serverKey})` : `${label} sign-out`;
+      let r;
+      try {
+        if (dryRun) {
+          r = row(rowKey, rowLabel, true, "would sign out", `would run: ${command}`);
+        } else {
+          const result = await exec(bin, verb, { timeoutMs: LOGOUT_TIMEOUT_MS, env, cwd: root });
+          const text = `${result?.stdout ?? ""}${result?.stderr ?? ""}`;
+          if (result?.ok) {
+            const pattern = NOTHING_STORED[key];
+            r = pattern && pattern.test(text)
+              ? row(rowKey, rowLabel, true, "nothing stored", `ran: ${command}`)
+              : row(rowKey, rowLabel, true, "signed out", `ran: ${command}`);
+          } else {
+            const notAFailure = NOT_A_FAILURE[key]?.find((entry) => entry.pattern.test(text));
+            r = notAFailure
+              ? row(rowKey, rowLabel, true, notAFailure.state, notAFailure.detail)
+              : row(rowKey, rowLabel, false, "failed", lastStderrLine(result));
+          }
+        }
+      } catch (error) {
+        // U4: an `exec` that throws (rather than resolving `{ok:false, ...}`,
+        // its documented contract) must not abort every step after it for
+        // this folder - one agent's logout is not another's.
+        r = row(rowKey, rowLabel, false, "error", describeError(error));
+      }
+      log?.(r);
+      rows.push(r);
+    }
+  }
+  return rows;
+}
+
+// --------------------------------------------------------------- Step 2
+//
+// The removal side of lib/mcpjson.mjs and lib/project-mcp.mjs's merges.
+// Those two files only ever ADD; there is no un-merge in them to import. The
+// "is this entry ours" check for each format - `boardEntryIsOurs` (JSON,
+// lib/mcpjson.mjs), its Codex-TOML equivalent and `opencodeBoardEntryIsOurs`
+// (both lib/project-mcp.mjs) - is imported from the same file that WROTE the
+// entry in the first place (brief 31 review, U6/reuse, 2026-09-12: these
+// were three private, byte-identical copies here before), rather than
+// re-derived.
+//
+// PRESENCE IS THE KEY, NOT THE VALUE, for `glytch` itself - same rule
+// mergeBoardServer documents: any `glytch` entry, whatever its shape, is
+// ours to remove. A `board` entry is only removed when it is RECOGNISED as
+// ours (the retired command shape, or at our hosted URL, old or new);
+// a stranger's own server merely named "board" is left exactly alone.
+
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const render = (value) => `${JSON.stringify(value, null, 2)}\n`;
+
+/** `$schema` is not content - it is a JSON Schema pointer editors and some
+ *  agents' own CLIs attach automatically (opencode does this: any `opencode`
+ *  invocation with a project as its cwd, even a plain `--version` probe
+ *  during agent detection, was observed 2026-09-12 to stamp a bare
+ *  `opencode.json` with `{"$schema": "https://opencode.ai/config.json"}`
+ *  before this file's own writer ever touches it). A JSON config file whose
+ *  only OTHER top-level key besides the servers map is `$schema` is exactly
+ *  as empty as one with no other keys at all, and is deleted the same way -
+ *  otherwise every project that ever ran `opencode` once is left with a
+ *  schema pointer and nothing it points at. TOML has no such convention, so
+ *  `removeFromCodexToml` below does not use this. */
+const IGNORED_TOP_KEYS = new Set(["$schema"]);
+const meaningfulKeys = (keys) => keys.filter((k) => !IGNORED_TOP_KEYS.has(k));
+
+// `boardEntryIsOurs` (for `.mcp.json`, from lib/mcpjson.mjs, imported above
+// as `jsonBoardEntryIsOurs`), the Codex-TOML equivalent (from
+// lib/project-mcp.mjs as `codexBoardEntryIsOurs`) and the opencode
+// equivalent (`opencodeBoardEntryIsOurs`, same file) used to be
+// byte-identical private copies kept local to this file - EXPORTED from
+// their own modules and imported here instead (brief 31 review, U6/reuse,
+// 2026-09-12), since each one already has to agree with the merge logic
+// that WROTE the entry in the first place.
+
+function removeFromMcpJson(existing, env) {
+  if (existing === null) return { kind: "not-present" };
+  let parsed;
+  try {
+    parsed = JSON.parse(existing);
+  } catch {
+    return { kind: "unreadable" };
+  }
+  if (!isObject(parsed)) return { kind: "unreadable" };
+  const servers = parsed.mcpServers;
+  if (servers === undefined) return { kind: "not-present" };
+  if (!isObject(servers)) return { kind: "unreadable" };
+  const hasGlytch = Object.hasOwn(servers, "glytch");
+  const hasViewable = Object.hasOwn(servers, "viewable");
+  const hasOurBoard = Object.hasOwn(servers, "board") && jsonBoardEntryIsOurs(servers.board, env);
+  if (!hasGlytch && !hasViewable && !hasOurBoard) return { kind: "not-present" };
+
+  const nextServers = { ...servers };
+  delete nextServers.glytch;
+  delete nextServers.viewable;
+  if (hasOurBoard) delete nextServers.board;
+  const remaining = Object.keys(nextServers);
+  const otherTopKeys = meaningfulKeys(Object.keys(parsed).filter((k) => k !== "mcpServers"));
+  if (remaining.length === 0 && otherTopKeys.length === 0) return { kind: "removed", deleteFile: true };
+
+  const nextParsed = { ...parsed };
+  if (remaining.length === 0) delete nextParsed.mcpServers;
+  else nextParsed.mcpServers = nextServers;
+  return { kind: "removed", text: render(nextParsed) };
+}
+
+// `withoutTomlTable(text, header)` (the text splice that removes one TOML
+// table, stopping at the next top-level header so a hand-written comment
+// elsewhere survives) is imported from lib/project-mcp.mjs, which needs the
+// exact same splice for its own `[mcp_servers.board]` removal - see that
+// file for the full doc comment. Returns null when the header cannot be
+// found; this file's own callers report "unreadable" rather than guess.
+
+function removeFromCodexToml(existing, env) {
+  if (existing === null) return { kind: "not-present" };
+  let parsed;
+  try {
+    parsed = parseToml(existing);
+  } catch {
+    return { kind: "unreadable" };
+  }
+  if (parsed.mcp_servers !== undefined && !isObject(parsed.mcp_servers)) return { kind: "unreadable" };
+  const servers = parsed.mcp_servers ?? {};
+  const hasGlytch = Object.hasOwn(servers, "glytch");
+  const hasViewable = Object.hasOwn(servers, "viewable");
+  const hasOurBoard = Object.hasOwn(servers, "board") && codexBoardEntryIsOurs(servers.board, env);
+  if (!hasGlytch && !hasViewable && !hasOurBoard) return { kind: "not-present" };
+
+  let text = existing;
+  if (hasGlytch) {
+    const stripped = withoutTomlTable(text, "mcp_servers.glytch");
+    if (stripped === null) return { kind: "unreadable" };
+    text = stripped;
+  }
+  if (hasViewable) {
+    const stripped = withoutTomlTable(text, "mcp_servers.viewable");
+    if (stripped === null) return { kind: "unreadable" };
+    text = stripped;
+  }
+  if (hasOurBoard) {
+    const stripped = withoutTomlTable(text, "mcp_servers.board");
+    if (stripped === null) return { kind: "unreadable" };
+    text = stripped;
+  }
+
+  let check;
+  try {
+    check = parseToml(text);
+  } catch {
+    return { kind: "unreadable" };
+  }
+  const remaining = isObject(check.mcp_servers) ? Object.keys(check.mcp_servers) : [];
+  const otherTopKeys = Object.keys(check).filter((k) => k !== "mcp_servers");
+  if (remaining.length === 0 && otherTopKeys.length === 0) return { kind: "removed", deleteFile: true };
+  return { kind: "removed", text };
+}
+
+function removeFromOpencodeJsonc(existing, env) {
+  if (existing === null) return { kind: "not-present" };
+  const errors = [];
+  const parsed = parseJsonc(existing, errors, { allowTrailingComma: true });
+  if (errors.length || !isObject(parsed)) return { kind: "unreadable" };
+  if (parsed.mcp !== undefined && !isObject(parsed.mcp)) return { kind: "unreadable" };
+  const mcp = parsed.mcp ?? {};
+  const hasGlytch = Object.hasOwn(mcp, "glytch");
+  const hasViewable = Object.hasOwn(mcp, "viewable");
+  const hasOurBoard = Object.hasOwn(mcp, "board") && opencodeBoardEntryIsOurs(mcp.board, env);
+  if (!hasGlytch && !hasViewable && !hasOurBoard) return { kind: "not-present" };
+
+  const formattingOptions = { insertSpaces: true, tabSize: 2, eol: existing.includes("\r\n") ? "\r\n" : "\n" };
+  let text = existing;
+  if (hasViewable) text = applyEdits(text, modify(text, ["mcp", "viewable"], undefined, { formattingOptions }));
+  if (hasGlytch) text = applyEdits(text, modify(text, ["mcp", "glytch"], undefined, { formattingOptions }));
+  if (hasOurBoard) text = applyEdits(text, modify(text, ["mcp", "board"], undefined, { formattingOptions }));
+
+  const afterErrors = [];
+  const after = parseJsonc(text, afterErrors, { allowTrailingComma: true });
+  if (afterErrors.length || !isObject(after)) return { kind: "unreadable" };
+  const remaining = isObject(after.mcp) ? Object.keys(after.mcp) : [];
+  const otherTopKeys = meaningfulKeys(Object.keys(after).filter((k) => k !== "mcp"));
+  if (remaining.length === 0 && otherTopKeys.length === 0) return { kind: "removed", deleteFile: true };
+  if (remaining.length === 0) text = applyEdits(text, modify(text, ["mcp"], undefined, { formattingOptions }));
+  return { kind: "removed", text };
+}
+
+async function configRow({ key, label, path, decide, env, dryRun, log }) {
+  let r;
+  try {
+    const existing = await readOptional(path);
+    const decision = decide(existing, env);
+    if (decision.kind === "not-present") {
+      r = row(key, label, true, "not present", `no Viewable connection in ${label}`);
+    } else if (decision.kind === "unreadable") {
+      r = row(
+        key,
+        label,
+        false,
+        "unreadable",
+        `${path} could not be safely edited - it is someone's work, so nothing was touched. Remove the Viewable connection and any leftover board entry by hand.`,
+      );
+    } else if (dryRun) {
+      r = decision.deleteFile
+        ? row(key, label, true, "would delete", `${path} would have nothing left after removing the board connection; would delete the file`)
+        : row(key, label, true, "would remove", `would remove the board connection from ${path}, other servers kept`);
+    } else if (decision.deleteFile) {
+      await rm(path, { force: true });
+      r = row(key, label, true, "deleted", `${path} had nothing left after removing the board connection; deleted`);
+    } else {
+      const mode = (await stat(path).catch(() => null))?.mode;
+      await writeFileAtomic(path, decision.text, "utf8", mode ? { mode: mode & 0o777 } : {});
+      r = row(key, label, true, "removed", `glytch entry removed from ${path}, other servers kept`);
+    }
+  } catch (error) {
+    // U4: `readOptional` rethrows anything but ENOENT (EISDIR - the config
+    // path is actually a directory, EACCES - unreadable permissions, ...).
+    // One such folder must not abort the whole `glytch uninstall` run; it
+    // becomes a FAIL row naming the real error instead.
+    r = row(key, label, false, "error", `${path}: ${describeError(error)}`);
+  }
+  log?.(r);
+  return r;
+}
+
+/** `.codex/` itself, left empty once `config.toml` is the last thing removed
+ *  from it (real-run leftover found 2026-09-12, U7): `viewable init` creates
+ *  the directory only to hold that one file, so an empty `.codex/` after
+ *  uninstall is debris nobody asked to keep. Mirrors `glytchDirRow`'s own
+ *  "only remove when nothing else is in it" rule - anything else Codex or a
+ *  person put there (a `log/`, a hand-written `AGENTS.md`) leaves the
+ *  directory in place untouched. */
+async function removeCodexDirIfEmpty(root) {
+  const dir = join(root, ".codex");
+  let entries;
+  try {
+    entries = await readdir(dir);
+  } catch {
+    return; // not present, or not a directory - nothing to do
+  }
+  if (entries.length === 0) await rm(dir, { recursive: true, force: true }).catch(() => {});
+}
+
+/** `skip`: agent keys whose sign-out failed. Their config stays, so a retry
+ *  still finds the name that reaches the credential; the other agents' configs
+ *  are cleaned regardless. */
+async function projectMcpRows(root, { env, dryRun, log, skip = new Set() }) {
+  const rows = [];
+  if (!skip.has("claude")) {
+    rows.push(
+      await configRow({
+        key: "mcpJson",
+        label: ".mcp.json",
+        path: join(root, ".mcp.json"),
+        decide: removeFromMcpJson,
+        env,
+        dryRun,
+        log,
+      }),
+    );
+  }
+  if (!skip.has("codex")) {
+    const codexConfig = await configRow({
+      key: "codexConfig",
+      label: ".codex/config.toml",
+      path: join(root, ".codex", "config.toml"),
+      decide: removeFromCodexToml,
+      env,
+      dryRun,
+      log,
+    });
+    rows.push(codexConfig);
+    if (!dryRun && codexConfig.ok && codexConfig.state === "deleted") await removeCodexDirIfEmpty(root);
+  }
+  if (!skip.has("opencode")) {
+    // OpenCode gives JSONC precedence - the same rule syncProjectMcp applies
+    // when it WRITES the entry, applied here when removing it.
+    const useJsonc = (await readOptional(join(root, "opencode.jsonc"))) !== null;
+    rows.push(
+      await configRow({
+        key: "opencodeConfig",
+        label: useJsonc ? "opencode.jsonc" : "opencode.json",
+        path: join(root, useJsonc ? "opencode.jsonc" : "opencode.json"),
+        decide: removeFromOpencodeJsonc,
+        env,
+        dryRun,
+        log,
+      }),
+    );
+  }
+  return rows;
+}
+
+// --------------------------------------------------------------- Step 3
+//
+// `.glytch/agents.json` is this project's own file (lib/agent-selection.mjs)
+// and is always safe to delete outright - unlike the config files above, it
+// carries nothing anyone hand-edited that is worth preserving. `.glytch/`
+// itself is only removed when NOTHING else is left in it: images staging and
+// the repomap cache are not this function's business, and a folder that
+// still holds either is left in place and named in the row detail (there is
+// only one row for this whole step, since both actions describe one fact:
+// what happened to .glytch/agents.json, and what became of the directory).
+async function projectDirRow(root, { dryRun, log }, directory = ".glytch") {
+  const dir = join(root, directory);
+  const agentsPath = join(dir, "agents.json");
+  let r;
+  try {
+    const hadAgents = (await readOptional(agentsPath)) !== null;
+
+    let entries;
+    try {
+      entries = await readdir(dir);
+    } catch {
+      entries = null;
+    }
+
+    if (entries === null) {
+      r = row(directory === ".glytch" ? "glytchDir" : "viewableDir", `${directory}/`, true, "not present", `no ${directory}/ folder to remove`);
+    } else {
+      const others = entries.filter((name) => name !== "agents.json");
+      const wouldBeEmpty = others.length === 0;
+      const othersNote = others.length ? `; ${directory}/ kept (${others.join(", ")} remain)` : "";
+      if (!hadAgents) {
+        r = row(directory === ".glytch" ? "glytchDir" : "viewableDir", `${directory}/`, true, "not present", `no ${directory}/agents.json to remove${othersNote}`);
+      } else if (dryRun) {
+        r = wouldBeEmpty
+          ? row(directory === ".glytch" ? "glytchDir" : "viewableDir", `${directory}/`, true, "would delete", `would delete ${directory}/agents.json, then ${directory}/ (empty afterward)`)
+          : row(directory === ".glytch" ? "glytchDir" : "viewableDir", `${directory}/`, true, "would delete", `would delete ${directory}/agents.json${othersNote}`);
+      } else {
+        await rm(agentsPath, { force: true });
+        if (wouldBeEmpty) {
+          await rm(dir, { recursive: true, force: true });
+          r = row(directory === ".glytch" ? "glytchDir" : "viewableDir", `${directory}/`, true, "deleted", `deleted ${directory}/agents.json, then ${directory}/ (was empty)`);
+        } else {
+          r = row(directory === ".glytch" ? "glytchDir" : "viewableDir", `${directory}/`, true, "deleted", `deleted ${directory}/agents.json${othersNote}`);
+        }
+      }
+    }
+  } catch (error) {
+    // U4: `readOptional(agentsPath)` rethrows anything but ENOENT (EISDIR,
+    // EACCES, ...) - one bad folder must not abort the whole run.
+    r = row(directory === ".glytch" ? "glytchDir" : "viewableDir", `${directory}/`, false, "error", `${agentsPath}: ${describeError(error)}`);
+  }
+  log?.(r);
+  return r;
+}
+
+// --------------------------------------------------------------- Step 4
+
+/** `allOk` (brief 31 review, U3): unregistering a folder whose earlier steps
+ *  did not all succeed loses the only record that this project ever needed
+ *  cleaning up - a retry of `viewable uninstall` reads ~/.glytch/folders.json
+ *  to know which folders to visit at all, so a folder dropped from it here
+ *  is a folder a retry will never look at again, even though its `.mcp.json`
+ *  (say) is still sitting there unreadable. Left registered instead, with a
+ *  warn row saying why, so the next run finds it. */
+async function registryRow(root, { env, dryRun, log, allOk = true }) {
+  const target = resolve(root);
+  let r;
+  try {
+    if (!allOk) {
+      const folders = await readRegistry(env);
+      r = folders.includes(target)
+        ? warnRow(
+            "registry",
+            "folder registered",
+            "left registered",
+            "an earlier step in this project failed - left registered so `viewable uninstall` can retry",
+          )
+        : row("registry", "folder registered", true, "not present", "this folder is not in ~/.glytch/folders.json");
+    } else if (dryRun) {
+      const folders = await readRegistry(env);
+      r = folders.includes(target)
+        ? row("registry", "folder registered", true, "would unregister", "would remove this folder from ~/.glytch/folders.json")
+        : row("registry", "folder registered", true, "not present", "this folder is not in ~/.glytch/folders.json");
+    } else {
+      const result = await removeFolder(root, env);
+      r = result.removed
+        ? row("registry", "folder registered", true, "unregistered", "removed from ~/.glytch/folders.json")
+        : row("registry", "folder registered", true, "not present", "this folder was not in ~/.glytch/folders.json");
+    }
+  } catch (error) {
+    // U4: this should be rare (the registry file is JSON we control), but a
+    // bad folder must not abort the whole run here either.
+    r = row("registry", "folder registered", false, "error", describeError(error));
+  }
+  log?.(r);
+  return r;
+}
+
+// --------------------------------------------------------------- Entry point
+
+/**
+ * Undo, in this one project folder, everything `viewable init` did: each
+ * installed agent's own OAuth token for the `glytch` server (step 1), the
+ * `glytch` (and recognised leftover `board`) entry in `.mcp.json`,
+ * `.codex/config.toml` and `opencode.json`/`opencode.jsonc` (step 2), this
+ * project's saved agent selection (step 3), and this folder's row in
+ * ~/.glytch/folders.json (step 4).
+ *
+ * NEVER THROWS for a missing file or an absent agent - both are rows. `agents`
+ * is a `detectAgents()` result; when omitted, this calls `detectAgents`
+ * itself (through the same `exec`, so a test's injected exec sees every call
+ * this function makes and nothing it does not). `dryRun` performs no exec
+ * call, no file write, no delete and no registry edit - every row it
+ * produces is read from what is already on disk, worded "would ...".
+ *
+ * `log`, WHEN GIVEN, IS CALLED WITH THE ROW ITSELF, once per row, in the
+ * order the returned array carries them - a live-progress hook, not a string
+ * logger. FIXED 2026-09-12 (brief 31 review, bug found integrating with
+ * lib/uninstall.mjs): this used to call `log?.(\`${r.label} — ${r.state}\`)`
+ * at all four sites below, while the caller (`runUninstall`) already treats
+ * `log` as receiving the row object and paints it through
+ * `cli-output.mjs`'s `renderRow` - the mismatch printed "FAIL undefined"
+ * eight times on a real run, once per row, because `renderRow` read
+ * `.warn`/`.ok`/`.label`/`.state` off a plain string.
+ */
+export async function uninstallProject(root, { agents, exec = execProbe, env = process.env, dryRun = false, log } = {}) {
+  const found = agents ?? (await detectAgents({ exec, env }));
+  const rows = [];
+  rows.push(...(await logoutRows({ root, agents: found, exec, env, dryRun, log })));
+  // Keep an agent's saved server names until its own logout succeeds, so retries reach the same credential.
+  const skip = new Set(Object.keys(LOGOUT_VERBS).filter((key) => rows.some((r) => r.key === `${key}Logout` && !r.ok)));
+  rows.push(...(await projectMcpRows(root, { env, dryRun, log, skip })));
+  rows.push(await projectDirRow(root, { dryRun, log }));
+  rows.push(await projectDirRow(root, { dryRun, log }, ".viewable"));
+  rows.push(await registryRow(root, { env, dryRun, log, allOk: rows.every((r) => r.ok) }));
+  return rows;
+}