viewable-one 0.0.0-stage → 0.12.2

package/lib/admission.mjs

@@ -0,0 +1,105 @@
+import { mkdir, writeFile, unlink, link, open } from "node:fs/promises";
+import { join } from "node:path";
+import { hostname } from "node:os";
+import { randomUUID } from "node:crypto";
+import { SPAWN_DIR } from "./spawn.mjs";
+
+const deadLocalOwner = (owner) => {
+  if (owner?.host !== hostname() || !Number.isInteger(owner.pid) || owner.pid <= 0) return false;
+  try { process.kill(owner.pid, 0); return false; }
+  catch (error) { return error?.code === "ESRCH"; }
+};
+
+/** The bytes at `path` AND the identity of the file they came off, read
+ * through ONE handle so the two can never describe different files.
+ *
+ * WHY ONE HANDLE. This used to be a readFile followed by a stat of the same
+ * path, and the gap between them was a hole big enough to lose the whole
+ * guarantee through: a caller could read the torn bytes, lose the recovery
+ * race, and then stat the path again and get the INODE OF THE WINNER'S LIVE
+ * LOCK. The generation it filed a cleaner marker under was that winner's, so
+ * its marker was unclaimed, it unlinked a lock that was alive and healthy,
+ * and took the room for itself. Two holders, which is the one outcome this
+ * whole module exists to make impossible. Reading the size and the inode off
+ * an open descriptor makes the record and its identity the same observation.
+ *
+ * Null where there is nothing to read, which leaves the lock alone. */
+const readLock = async (path) => {
+  const handle = await open(path, "r");
+  try {
+    const info = await handle.stat();
+    return { raw: await handle.readFile("utf8"), generation: `inode-${info.ino}` };
+  } finally {
+    await handle.close().catch(() => {});
+  }
+};
+
+/** Serialize admission, not execution. Claims reserve budgets and rooms after
+ * release. Publish a complete owner via an exclusive hard link: a reader can
+ * never mistake an incomplete owner write for a dead process. The directory
+ * override lets registry restores reuse this protocol apart from run claims. */
+export async function acquireAdmission(root, { directory = join(root, SPAWN_DIR) } = {}) {
+  const dir = directory;
+  const path = join(dir, ".admission.lock");
+  const token = randomUUID();
+  const temporary = join(dir, `.admission-owner-${token}`);
+  await mkdir(dir, { recursive: true });
+  await writeFile(temporary, JSON.stringify({ pid: process.pid, host: hostname(), token }), { flag: "wx" });
+  try {
+    for (;;) {
+      try {
+        await link(temporary, path);
+        return { ok: true, release: () => unlink(path) };
+      } catch (error) {
+        if (error?.code !== "EEXIST") throw error;
+      }
+      let owner;
+      // A lock we could not read at all, kept apart from one we read and could
+      // not parse. The first may still be a live holder and is never stolen;
+      // the second cannot be, because a live holder publishes a COMPLETE owner
+      // by hard link and never a half of one.
+      let unreadable = null;
+      let corrupt = null;
+      try {
+        const { raw, generation: inode } = await readLock(path);
+        try { owner = JSON.parse(raw); }
+        catch { corrupt = inode; }
+      } catch (error) {
+        if (error?.code === "ENOENT") continue;
+        unreadable = error;
+      }
+      // The generation being recovered, and the key its one cleaner marker is
+      // filed under. A dead owner supplies its own token; a torn record cannot
+      // supply anything, so the inode it is written on IS its generation -
+      // unlinking frees it and the next holder is a different inode entirely.
+      const generation =
+        deadLocalOwner(owner) && /^[a-f0-9-]{36}$/.test(owner.token ?? "") ? owner.token : corrupt;
+      if (generation) {
+        // One cleaner for this exact dead generation. Keep its tiny marker:
+        // another delayed cleaner must never unlink a newer holder's lock.
+        // The marker is only worth that much while `generation` provably
+        // names the file the BYTES came off, which is what readLock's single
+        // handle buys and what a second stat of the path did not.
+        try {
+          await writeFile(join(dir, `.admission-recovered-${generation}`), "recovered\n", { flag: "wx" });
+          await unlink(path);
+          continue;
+        } catch (error) {
+          if (error?.code !== "EEXIST" && error?.code !== "ENOENT") throw error;
+        }
+      }
+      // WHY it is busy, in the answer itself. A refusal that names only the
+      // path leaves a caller guessing between a live holder and a lock this
+      // process cannot read, which is the difference between waiting and
+      // fixing something.
+      const because = unreadable
+        ? ` The lock could not be read (${unreadable.code ?? unreadable.message}).`
+        : owner
+          ? ` Held by pid ${owner.pid} on ${owner.host}.`
+          : "";
+      return { ok: false, detail: `Admission is busy (${path}).${because} Retry on the next poll. An owner on another host or an unreadable lock needs manual recovery after confirming it is stopped.` };
+    }
+  } finally {
+    await unlink(temporary).catch(() => {});
+  }
+}

package/lib/agent-selection.mjs

@@ -0,0 +1,124 @@
+// Project-owned MCP setup choices. A missing file means a legacy install;
+// malformed choices must never turn into permission to configure every agent.
+import { mkdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { PROBE_BINS } from "./detect.mjs";
+import { writeFileAtomic } from "./atomic.mjs";
+import { colorEnabled, dim } from "./cli-output.mjs";
+import { pickMany } from "./picker.mjs";
+
+export const SELECTION_FILE = ".viewable/agents.json";
+export const AGENT_KEYS = PROBE_BINS.map((b) => b.key);
+
+export function parseAgentSelection(value) {
+  const keys = Array.isArray(value) ? value : String(value).split(",").map((v) => v.trim());
+  if (!keys.length || keys.some((key) => !AGENT_KEYS.includes(key))) {
+    throw new Error(`Choose one or more agents: ${AGENT_KEYS.join(", ")}. Example: viewable init --agents claude,codex`);
+  }
+  return [...new Set(keys)];
+}
+
+export async function readAgentSelection(root) {
+  let text;
+  try {
+    text = await readFile(join(root, SELECTION_FILE), "utf8");
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+    try { text = await readFile(join(root, ".glytch/agents.json"), "utf8"); }
+    catch (legacyError) { if (legacyError.code === "ENOENT") return null; throw legacyError; }
+  }
+  try {
+    const saved = JSON.parse(text);
+    if (saved.version !== 1 || !Array.isArray(saved.agents)) throw new Error("Invalid shape");
+    return parseAgentSelection(saved.agents);
+  } catch {
+    throw new Error(`${SELECTION_FILE} is invalid. Fix it before running init or doctor; nothing was reconfigured.`);
+  }
+}
+
+export async function saveAgentSelection(root, agents) {
+  const selected = parseAgentSelection(agents);
+  await mkdir(join(root, ".viewable"), { recursive: true });
+  await writeFileAtomic(join(root, SELECTION_FILE), `${JSON.stringify({ version: 1, agents: selected }, null, 2)}\n`);
+}
+
+/** `--no-login` and `--no-agent-login` (brief 31, Moves 1 and 2, 2026-09-12)
+ *  are the two OFF switches for what `init` now does instead of printing:
+ *  signing this machine in, and running each agent's own OAuth verb. They are
+ *  for scripts, for CI, and for a machine that already reaches the board
+ *  through `VIEWABLE_BOARD_TOKEN`. Default is on, because the whole point of
+ *  the brief is that a new machine is one command. */
+export function initOptions(args) {
+  let agents;
+  let yes = false;
+  let login = true;
+  let agentLogin = true;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--yes" || arg === "-y") yes = true;
+    else if (arg === "--no-login") login = false;
+    else if (arg === "--no-agent-login") agentLogin = false;
+    else if (arg === "--agents" || arg.startsWith("--agents=")) {
+      const value = arg === "--agents" ? args[++i] : arg.slice("--agents=".length);
+      if (agents !== undefined || value === undefined) throw new Error("Pass --agents once, followed by a comma-separated list.");
+      agents = parseAgentSelection(value);
+    } else throw new Error(`Unknown init option: ${arg}`);
+  }
+  return { agents, yes, login, agentLogin };
+}
+
+// An arrow-key checkbox picker for a real terminal (brief 31, Move 8,
+// 2026-09-12: "when selecting a model I prefer not to type anything: go up
+// and down with arrows to select the right one or even multiple ones").
+// `ask` is kept as the injection point scripts and this file's own tests
+// used before the picker existed - a caller that supplies it gets the exact
+// numbered-list prompt this replaced, so nothing that already depends on
+// typing an answer breaks. Over SSH or a pipe (no TTY), or with `--yes`/
+// `--agents`, no prompt of either kind is ever opened - doctor and the
+// daemon never touch this function's interactive branches.
+export async function chooseAgents({
+  options, saved, found, input = process.stdin, output = process.stdout,
+  ask, picker = pickMany,
+}) {
+  if (options.agents) return options.agents;
+  const defaults = saved ?? AGENT_KEYS.filter((key) => found[key]?.found);
+  // `--yes` WITH NO AGENT BINARY ON PATH AND NO SAVED SELECTION used to reach
+  // `parseAgentSelection([])`, which throws "Choose one or more agents" -
+  // uncaught, this took the whole `init` down before the folder was
+  // registered or the runner was connected to the board, on a machine whose
+  // whole problem is that it has no agent yet (2026-09-19, persona walk).
+  // An empty defaults list under `--yes` is not a mistake to refuse; it is
+  // "nothing to select automatically", so it returns `[]` rather than
+  // throwing - `glytch.mjs`'s `init()` turns that into a warn row naming
+  // what to install, and every other step (registry, daemon) still runs.
+  if (options.yes) return defaults.length ? parseAgentSelection(defaults) : [];
+  if (!input.isTTY || !output.isTTY) {
+    if (saved) return saved;
+    throw new Error("Choose agents with viewable init --agents claude,codex (or --yes for detected agents) when running without a terminal.");
+  }
+  output.write("\nConnect coding agents to this project (choose one or more):\n");
+  if (ask) {
+    PROBE_BINS.forEach((b, i) => output.write(`  ${i + 1}. ${b.label} (${found[b.key]?.found ? "installed" : "not detected"})${defaults.includes(b.key) ? " [selected]" : ""}\n`));
+    while (true) {
+      const question = `Numbers or names, separated by commas${defaults.length ? ` [${defaults.join(",")}]` : ""}: `;
+      const answer = await ask(question);
+      try {
+        if (!answer.trim() && defaults.length) return defaults;
+        return parseAgentSelection(answer.split(",").map((s) => {
+          const value = s.trim();
+          return /^[1-3]$/.test(value) ? AGENT_KEYS[Number(value) - 1] : value;
+        }));
+      } catch (error) { output.write(`${error.message}\n`); }
+    }
+  }
+  const color = colorEnabled({ isTTY: output.isTTY });
+  const items = PROBE_BINS.map((b) => ({
+    key: b.key,
+    label: `${b.label} ${dim(found[b.key]?.found ? "(installed)" : "(not installed)", { color })}`,
+  }));
+  const chosen = await picker({ items, checked: defaults, input, output, color });
+  // Escape/Ctrl-C: the same exit the numbered prompt gave on Ctrl-C (an
+  // AbortError from `rl.question`, caught nowhere, dying with exit 1).
+  if (chosen === null) throw new Error("Cancelled - no agents connected.");
+  return parseAgentSelection(chosen);
+}