viewable-one 0.0.0-stage → 0.12.1

package/lib/uninstall.mjs

@@ -0,0 +1,457 @@
+// `glytch uninstall` - the ruling, 2026-09-12: removing glytch, its OAuth
+// grants and everything it wrote must be one straightforward command for any
+// user. Before this, undoing `glytch init` was four separate half-measures
+// (`forget`, `stop`, `logout`, and a person deleting `~/.glytch` by hand) and
+// none of them touched the board's own record of the grant - a machine that
+// "uninstalled" glytch was still a machine the board would accept a bearer
+// token from.
+//
+// THE SHAPE: a project step (every registered folder, or just `--project`'s
+// cwd) delegates to `uninstallProject` (bridge/lib/uninstall-project.mjs,
+// built on its own branch - see the stub note below), then three
+// machine-wide steps run unless `--project` was passed: stop and remove the
+// login daemon, revoke this machine's board grant and sign out, delete
+// `~/.glytch` outright. `--dry-run` reports "would ..." everywhere and
+// changes nothing; `--keep-login` leaves the machine signed in and its
+// credential on disk.
+//
+// EVERY SEAM IS INJECTED, the logindaemon.mjs rule that runs through this
+// whole package: `exec`, `fetchImpl`, `daemon` and `uninstallProject` itself
+// are parameters with real defaults, so a test drives the whole command with
+// fakes and nothing here ever calls launchctl/schtasks/systemctl, opens a
+// socket, or touches a real ~/.glytch.
+//
+// THE STUB. `uninstallProject` is being written on a separate branch
+// (`bridge/lib/uninstall-project.mjs`, doctor-shaped rows: agent logouts,
+// config entry removal, `.glytch/agents.json`, the registry entry for one
+// folder). Until that lands here, a stub of the same path and signature
+// (returning `[]`) lets this module and its tests import and run; the stub
+// is not part of this branch's commit, and the merge brings the real file in
+// over it.
+
+import { createInterface } from "node:readline";
+import { rm } from "node:fs/promises";
+import { join } from "node:path";
+
+import { bold, bullets, colorEnabled, heading, hint, renderRow, row, step, summary, warn, warnRow } from "./cli-output.mjs";
+import { appUrlFrom, logout as hostedLogout, readAuthFile } from "./auth.mjs";
+import { detectAgents, execProbe } from "./detect.mjs";
+import { glytchHome, readRegistry } from "./registry.mjs";
+import { loginDaemon } from "./logindaemon.mjs";
+import { uninstallProject } from "./uninstall-project.mjs";
+
+/** `--project`, `--keep-login`, `--dry-run`, `--yes` - the same "throw on
+ * anything else" shape `initOptions` uses (agent-selection.mjs), so a typo in
+ * a flag is refused rather than silently ignored. */
+export function uninstallOptions(args) {
+  let project = false;
+  let keepLogin = false;
+  let dryRun = false;
+  let yes = false;
+  for (const arg of args) {
+    if (arg === "--project") project = true;
+    else if (arg === "--keep-login") keepLogin = true;
+    else if (arg === "--dry-run") dryRun = true;
+    else if (arg === "--yes" || arg === "-y") yes = true;
+    else throw new Error(`Unknown uninstall option: ${arg}`);
+  }
+  return { project, keepLogin, dryRun, yes };
+}
+
+// `row`/`warnRow`, imported from cli-output.mjs (brief 31 review, U6/reuse,
+// 2026-09-12 - this used to be a local copy, byte-identical to doctor.mjs's
+// own and lib/uninstall-project.mjs's own): the exact doctor-shaped contract
+// `uninstallProject` answers in too, {key, label, ok, state, detail,
+// action?}, so every row this command prints - its own and the other
+// worker's - paints the same way.
+
+/** A readline `ask`, matching the shape `chooseAgents`' own fallback prompt
+ * takes (agent-selection.mjs: `ask(question) => Promise<string>`, injected
+ * there for the exact same reason - a test drives it with a canned answer,
+ * and nothing here ever has to touch a real terminal to be exercised). This
+ * is the "type an answer" half of that same pattern, spelled out with
+ * `node:readline` because uninstall has one yes/no question and no rows to
+ * pick from - there is nothing here for the arrow-key picker to do. */
+export function readlineAsk(input = process.stdin, output = process.stdout) {
+  return (question) =>
+    new Promise((resolvePromise) => {
+      const rl = createInterface({ input, output });
+      let answered = false;
+      rl.question(question, (answer) => {
+        answered = true;
+        rl.close();
+        resolvePromise(answer);
+      });
+      // FIXED 2026-09-12 (brief 31 review, U5): with no `close` handler,
+      // Ctrl-D (or any input stream that ends before an answer) left
+      // `rl.question`'s callback never called and this promise hung
+      // forever - `confirmUninstall` above never got an answer to compare
+      // against "yes", so the whole command just sat there. `close` fires
+      // either way (readline calls it itself once `question`'s callback
+      // resolves), so this only resolves a SECOND time when the input
+      // ended without ever answering - treated as "" here, the same "not
+      // yes" `confirmUninstall` already refuses on.
+      rl.on("close", () => {
+        if (!answered) resolvePromise("");
+      });
+    });
+}
+
+/** The bulleted plan printed before the question is ever asked - "print what
+ * will happen" first, so "Type yes to continue" means something. */
+export function uninstallPlan(options, { folderCount = 0 } = {}) {
+  const lines = [];
+  if (options.project) {
+    lines.push(
+      "Disconnect this project folder only: agent sign-outs, its config entries, .glytch/agents.json, and its registry entry.",
+    );
+  } else {
+    lines.push(
+      folderCount > 0
+        ? `Disconnect ${folderCount} registered project folder${folderCount === 1 ? "" : "s"}: agent sign-outs, config entries, .glytch/agents.json, and each registry entry.`
+        : "No project folders are registered: nothing to disconnect there.",
+    );
+    lines.push("Stop watching folders and remove the watcher's file.");
+    lines.push(
+      options.keepLogin
+        ? "Keep your computer signed in to the board (--keep-login)."
+        : "Revoke your computer's board sign-in at the board and forget the credential.",
+    );
+    lines.push(
+      options.keepLogin
+        ? "Leave ~/.glytch in place: the sign-in credential lives there (--keep-login)."
+        : "Delete ~/.glytch entirely.",
+    );
+  }
+  lines.push("Print the two steps left to finish by hand: uninstalling the npm package, and unlinking the folder in the app.");
+  return lines;
+}
+
+/** Print the plan and get a yes. `--yes` skips the question outright; a
+ * non-TTY without it prints the plan and refuses rather than opening a
+ * prompt nothing can answer - the same call chooseAgents already makes for
+ * its own picker (agent-selection.mjs). */
+export async function confirmUninstall({ options, plan, isTTY, ask, log, color }) {
+  const paint = { color };
+  log(heading("Viewable · Uninstall", paint));
+  log(bold("This will:", paint));
+  for (const line of bullets(plan, paint)) log(line);
+  log("");
+  if (options.yes) return true;
+  if (!isTTY) {
+    log(warn("No terminal here, nothing was changed.", paint));
+    log("Run again with --yes to uninstall without a prompt.");
+    return false;
+  }
+  const answer = await ask("Type yes to continue: ");
+  if (String(answer ?? "").trim().toLowerCase() !== "yes") {
+    log("");
+    log(warn("Not confirmed, nothing was changed.", paint));
+    return false;
+  }
+  return true;
+}
+
+/** One row per doctor-shaped row, painted exactly the way `checkSections`
+ * paints each of its own - same status column, same wrap, same indent - but
+ * with no grouping into Project/Runner/Coding agents/System and no derived
+ * "Next steps" (doctor's defaults there, "run viewable init", are the wrong
+ * advice for a command that is in the middle of removing glytch).
+ *
+ * Built on `renderRow` (cli-output.mjs), the single-row painter
+ * `checkSections` itself uses - the two used to be separate, byte-identical
+ * implementations (brief 31 review, U6/reuse, 2026-09-12). */
+export function printedRows(rows, options = {}) {
+  const lines = [];
+  for (const r of rows ?? []) lines.push(...renderRow(r, options));
+  return lines;
+}
+
+/** Step 2, row 1: stop the daemon AND remove its file (`removeFile: true`
+ * already deletes the Windows launcher and task XML together with the
+ * launcher path itself - see schtasks.stop in logindaemon.mjs - so there is
+ * nothing platform-specific to add here).
+ *
+ * NO `exec` PARAMETER, ON PURPOSE (bug found 2026-09-12 by a real, non-dry
+ * run): this used to accept `exec` and hand it straight to `daemon.stop()`,
+ * which meant whatever `runUninstall` was given for AGENT probing -
+ * `execProbe`, shaped `exec(bin, args, options)` - silently replaced
+ * `daemon.stop()`'s own correct default (`execLaunchctl` / `execSchtasks` /
+ * `execSystemctl`, shaped `exec(argsArray, env)`). The two shapes are not
+ * compatible: `execFile`'s own argument-shifting (a non-array second
+ * argument is treated as `options`, and the real `options` shifts into the
+ * callback slot) turned into "The 'callback' argument must be of type
+ * function. Received an instance of Object" the moment step 2 tried to stop
+ * a real daemon. `daemon.stop()` already knows how to reach launchctl,
+ * schtasks or systemctl for the machine it is actually running on - exactly
+ * the way `viewable stop` above calls it with no `exec` of its own - so this
+ * function has no business choosing one for it.
+ *
+ * THE ROW READS THE FILE, NOT JUST `result.unloaded` (Bug 2, found the same
+ * day, same real run): the daemon implementations already delete the file
+ * unconditionally once `removeFile: true` is asked for and the file exists,
+ * whether or not the unload itself succeeded - a plist written under
+ * GLYTCH_NO_DAEMON_INSTALL (never loaded in the first place), or a scheduled
+ * task already gone, both hit this. Before Bug 1 was fixed the file simply
+ * never got deleted, because the crash aborted `stop()` before it reached
+ * that line - so this looked like it was Bug 1's fault too, until fixing
+ * Bug 1 alone left the row still calling a successful deletion a "failed"
+ * uninstall, because the row only ever looked at `result.unloaded`.
+ * Re-reading the file after `stop()` returns is what tells "the unload
+ * failed but the file is gone" (ok - uninstalling was the goal, not
+ * unloading) from "the file could not be removed" (the one real failure). */
+export async function daemonUninstallRow({ daemon, env, dryRun }) {
+  const label = daemon.rowLabel;
+  const file = daemon.filePath(env);
+  const installed = (await daemon.read(env)) !== null;
+  if (!installed) {
+    return row("daemon", `Stop the ${label}`, true, "not installed", `nothing at ${file}`);
+  }
+  if (dryRun) {
+    return row("daemon", `Stop the ${label}`, true, "would stop", `would unload and delete ${file}`);
+  }
+  const result = await daemon.stop({ env, removeFile: true });
+  const stillThere = (await daemon.read(env)) !== null;
+  if (stillThere) {
+    return row("daemon", `Stop the ${label}`, false, "failed", result.why || "the file could not be removed");
+  }
+  return result.unloaded
+    ? row("daemon", `Stop the ${label}`, true, "stopped", `${file} removed`)
+    : row(
+        "daemon",
+        `Stop the ${label}`,
+        true,
+        "removed (was not loaded)",
+        result.why ? `${file} removed; ${result.why}` : `${file} removed, it was not loaded`,
+      );
+}
+
+/** Step 2, row 2: revoke this machine's grant server-side, then forget the
+ * credential locally. `stored` is read once by the caller and passed in
+ * (rather than re-read here) so dry-run and the real run agree on exactly
+ * what they saw. */
+export async function revokeRow({ stored, env, fetchImpl, dryRun, keepLogin, logout = hostedLogout }) {
+  if (keepLogin) {
+    return warnRow("revoke", "Board sign-in", "kept", "your computer stays signed in (--keep-login)");
+  }
+  if (!stored) {
+    return row("revoke", "Board sign-in", true, "not signed in", "no stored credential to revoke");
+  }
+  const appUrl = stored.appUrl || appUrlFrom(undefined, env);
+  const revokeUrl = `${appUrl}/oauth/revoke`;
+  if (dryRun) {
+    return row("revoke", "Board sign-in", true, "would revoke", `would revoke at ${revokeUrl} and delete the local credential`);
+  }
+  // Either half of the pair kills the whole family server-side (oauth.mjs's
+  // own revokeToken), so presenting both is belt and suspenders against
+  // whichever one the server happens to still recognise - never a second
+  // grant to clean up.
+  const tokens = [stored.refreshToken, stored.accessToken].filter((t) => typeof t === "string" && t !== "");
+  let networkFailed = false;
+  let badStatus = null;
+  for (const token of tokens) {
+    try {
+      const response = await fetchImpl(revokeUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({ token }),
+      });
+      // FIXED 2026-09-12 (brief 31 review, U2): the response status was
+      // never read. A 404/500 from `/oauth/revoke` does not throw - only a
+      // network-level failure does - so this used to call the row "revoked"
+      // and delete the credential even when the board plainly said the
+      // revoke did not happen.
+      if (response && response.ok === false && badStatus === null) badStatus = response.status;
+    } catch {
+      networkFailed = true;
+    }
+  }
+  // A STATUS THE BOARD ACTUALLY SENT BACK IS A DEFINITE "NO", unlike a
+  // network failure (below) where nothing is known either way. The
+  // credential is KEPT rather than deleted here, and the caller
+  // (runUninstall) skips deleting ~/.glytch too - the returned
+  // `keptCredential` flag is how it knows - so a re-run of `glytch
+  // uninstall` still has a token on disk to retry the revoke with. Deleting
+  // it now would strand the grant at the board with nothing left on this
+  // machine that could ever ask it to revoke again.
+  if (badStatus !== null) {
+    return {
+      ...warnRow(
+        "revoke",
+        "Board sign-in",
+        "could not revoke",
+        `could not revoke at ${revokeUrl} (HTTP ${badStatus}); the credential is kept locally so a retry can revoke it - or revoke it in Settings`,
+      ),
+      keptCredential: true,
+    };
+  }
+  // Deleted locally either way: a laptop with no network right now should
+  // still end up signed out on its own side, same rule as `logout()`'s own
+  // header comment.
+  await logout(env);
+  return networkFailed
+    ? warnRow(
+        "revoke",
+        "Board sign-in",
+        "could not reach the board",
+        "could not reach the board to revoke; the credential is deleted locally, revoke it in Settings",
+      )
+    : row("revoke", "Board sign-in", true, "revoked", `revoked at ${revokeUrl} and removed the local credential`);
+}
+
+/** Step 2, row 3: delete `~/.glytch` outright - folders.json, auth.json,
+ * logs/, the cloudflared cache, and everything else this package ever wrote
+ * under it. Never anything outside glytchHome(). */
+export async function deleteHomeRow({ env, dryRun, keepLogin }) {
+  const home = glytchHome(env);
+  if (keepLogin) {
+    return warnRow("home", "Delete ~/.glytch", "kept", `kept - the sign-in credential lives at ${join(home, "auth.json")} (--keep-login)`);
+  }
+  if (dryRun) {
+    return row("home", "Delete ~/.glytch", true, "would delete", home);
+  }
+  await rm(home, { recursive: true, force: true });
+  return row("home", "Delete ~/.glytch", true, "deleted", home);
+}
+
+/** The two steps this command cannot do for you, as hints under step 3.
+ * "Is this a checkout" is asked of the RUNNING script's own path - a global
+ * install's is a symlink through some `node_modules/.bin`, and a checkout's
+ * is not - the same distinguishing fact logindaemon.mjs's own daemon-version
+ * check reads a package.json beside a script path for. */
+export function uninstallGuideLines(scriptPath = process.argv[1]) {
+  const globalInstall = /node_modules[\\/]/.test(String(scriptPath ?? ""));
+  return [
+    globalInstall
+      ? "npm uninstall -g viewable-one glytch"
+      : "This is a checkout: run `npm unlink -g viewable-one` from bridge/.",
+    "Unlink the folder in the app's Project panel.",
+  ];
+}
+
+/** The whole command. Returns the exit code; the caller (glytch.mjs) is the
+ * one that calls `process.exit`, same as every other one-shot command here. */
+export async function runUninstall({
+  root,
+  args = [],
+  options = uninstallOptions(args),
+  env = process.env,
+  exec = execProbe,
+  fetchImpl = fetch,
+  daemon = loginDaemon({ env }),
+  uninstallProjectFn = uninstallProject,
+  detect = detectAgents,
+  isTTY = Boolean(process.stdin.isTTY && process.stdout.isTTY),
+  ask = readlineAsk(),
+  log = () => {},
+  color = colorEnabled(),
+} = {}) {
+  const paint = { color };
+  const roots = options.project ? [root] : await readRegistry(env);
+  const plan = uninstallPlan(options, { folderCount: roots.length });
+  const proceed = await confirmUninstall({ options, plan, isTTY, ask, log, color });
+  if (!proceed) return 1;
+
+  const titles = options.project ? ["Projects", "What is left for you"] : ["Projects", "Your computer", "What is left for you"];
+  const allRows = [];
+  let n = 1;
+
+  log("");
+  log(step(n, titles.length, "Projects", paint));
+  n += 1;
+  if (roots.length === 0) {
+    log(warn("No project folders are registered.", paint));
+  } else {
+    const agents = await detect({ exec, env });
+    for (const projectRoot of roots) {
+      log("");
+      log(bold(projectRoot, paint));
+      // BUG 3, found 2026-09-12 by a real, non-dry run: `uninstallProject`'s
+      // `log` calls back with the ROW ITSELF, once per row, in the same
+      // order the returned array carries them (its own test: "a `log`
+      // callback sees every row as it is produced") - a live-progress hook,
+      // not a string logger. This used to forward each row straight into
+      // `hint()`, which stringifies whatever it is given
+      // (`String(aPlainObject)` is "[object Object]") and printed eight of
+      // those above the real rows on a real project. Painting each row here,
+      // as it lands, is also the ONLY place these rows get printed - nothing
+      // re-walks the returned array below, so a row is painted once, not
+      // twice.
+      let rows;
+      try {
+        rows = await uninstallProjectFn(projectRoot, {
+          agents,
+          exec,
+          env,
+          dryRun: options.dryRun,
+          log: (r) => { for (const line of printedRows([r], paint)) log(line); },
+        });
+      } catch (error) {
+        // U4: uninstallProjectFn is documented to never throw, but one bad
+        // folder (a config path that turned out to be a directory, a
+        // permission error) must not abort every folder after it and the
+        // machine steps that follow. This mirrors the per-step wrapping in
+        // lib/uninstall-project.mjs itself.
+        const failed = row("project", projectRoot, false, "error", `${error?.code ? `${error.code}: ` : ""}${error?.message ?? String(error)}`);
+        for (const line of printedRows([failed], paint)) log(line);
+        rows = [failed];
+      }
+      allRows.push(...(rows ?? []));
+    }
+  }
+
+  if (!options.project) {
+    log("");
+    log(step(n, titles.length, "Your computer", paint));
+    n += 1;
+
+    // U3: `allRows` at this point is exactly the project rows (nothing
+    // machine-level has been pushed yet). A project step that failed means
+    // this run did not fully undo what `init` did to that folder - deleting
+    // ~/.glytch now would remove the only thing a retry has to compare
+    // against, and would take the registry with it before registryRow's own
+    // U3 gate ever got a chance to leave the folder registered.
+    const projectsOk = allRows.every((r) => r.ok);
+
+    const daemonRow = await daemonUninstallRow({ daemon, env, dryRun: options.dryRun });
+    for (const line of printedRows([daemonRow], paint)) log(line);
+    allRows.push(daemonRow);
+
+    const stored = await readAuthFile(env);
+    const revoke = await revokeRow({ stored, env, fetchImpl, dryRun: options.dryRun, keepLogin: options.keepLogin });
+    for (const line of printedRows([revoke], paint)) log(line);
+    allRows.push(revoke);
+
+    // U2: a revoke the board definitely refused (a real HTTP status, not a
+    // network failure) kept the credential on disk on purpose - deleting
+    // ~/.glytch now would take that credential with it and strand the grant
+    // with nothing left able to retry the revoke. U3: a failed project step
+    // (checked above, before this section pushed any machine rows) means a
+    // retry needs ~/.glytch left in place too.
+    const home = !projectsOk
+      ? warnRow(
+          "home",
+          "Delete ~/.glytch",
+          "left in place",
+          "a project step failed - ~/.glytch was left in place so `viewable uninstall` can retry",
+        )
+      : revoke.keptCredential
+        ? warnRow(
+            "home",
+            "Delete ~/.glytch",
+            "kept",
+            "the board sign-in could not be revoked and its credential was kept so a retry can revoke it; ~/.glytch was not deleted",
+          )
+        : await deleteHomeRow({ env, dryRun: options.dryRun, keepLogin: options.keepLogin });
+    for (const line of printedRows([home], paint)) log(line);
+    allRows.push(home);
+  }
+
+  log("");
+  log(step(n, titles.length, "What is left for you", paint));
+  for (const line of uninstallGuideLines()) log(hint(line, paint));
+
+  log("");
+  log(summary(allRows, paint));
+  return allRows.every((r) => r.ok) ? 0 : 1;
+}