clearotron 0.3.0-beta.1 → 0.3.0-beta.2

package/shared/store-in-repo.mjs

@@ -362,3 +362,150 @@ export function resolveStoreRepoRoot({ names, fallback = null, env = process.env
   if (fallback) return { root: fallback, from: "module-relative fallback", tried };
   return { root: null, from: null, tried };
 }
+
+// ── WHERE A SAVE GOES AFTER IT IS COMMITTED ──────────────────────────────────────────────────────────
+//
+// Everything above ends at a commit. Nothing in this file pushes, and nothing should: what happens to a
+// commit next is a property of the repository the store sits in, not of the save. When that repository's
+// branch tracks a remote one, the next person who syncs or pushes the checkout publishes every save made
+// there, and that person is usually not the one who made them.
+//
+// Measured on a test instance, 2026-09-10: its store sat inside a checkout that people also synced for
+// unrelated work. A company created in the portal was committed there as designed, waited eleven hours
+// as a local commit, and went out with an ordinary pull-then-push. It had happened the evening before,
+// and the only thing that stopped that one was somebody noticing.
+//
+// THIS IS A REPORT, NEVER A REFUSAL. Keeping a store in a repository you push on purpose is a
+// reasonable deployment, and the harm needs a second person doing ordinary git work in the same checkout,
+// which no service can see. So the answer is for whoever reads it (doctor), and no save waits on it.
+//
+// READ FROM THE BRANCH'S TRACKING CONFIGURATION, NOT FROM `@{u}`. The clone of an empty remote has its
+// tracking configured and nothing to resolve `@{u}` to until the first commit, so `@{u}` answers with a
+// usage error for a store whose first save a bare push WOULD publish. The configuration answers the
+// question actually being asked: will a push or pull with no arguments carry this branch anywhere?
+//
+// NO FETCH. A doctor that reaches the network hangs on a box without a route, and the count of commits
+// waiting is measured against the last fetch, which is enough: a commit made here is ahead of any
+// version of the remote branch until somebody pushes it.
+
+/**
+ * Where does a save committed in `dir`'s repository go next? Read-only.
+ *
+ * @param {string} dir  the store directory — any directory inside the repository; git finds the root
+ * @param {{ env?: object, gitVersion?: string }} [opts]  the environment git runs in — a caller can bound the
+ *   search upwards — and, for a test, the `git version` answer to reason from instead of asking git
+ * @returns one of:
+ *   `{ state: "publishes", root, branch, upstream, ahead, via }` — a push with no arguments carries the store's
+ *     commits out: the branch tracks a remote branch (`via: "tracking"`), or it tracks none and git's push
+ *     settings send it anyway (`via` names the setting). `ahead` counts the commits waiting, or is null when
+ *     git cannot count them (nothing to count against yet).
+ *   `{ state: "stays-here", root, branch, remotes }` — no tracking branch (or no branch at all), and no push
+ *     setting that sends it anyway: nothing leaves unless someone pushes it by name. `remotes` lists the remotes such a push could name.
+ *   `{ state: "not-a-repository", why }` — a save through a door is refused until the store is in one.
+ *   `{ state: "could-not-look", why }` — git would not answer: a missing directory, a repository owned
+ *     by another account, no git on the path. Never read as either answer above.
+ */
+export function whereSavesGo(dir, { env = process.env, gitVersion = null } = {}) {
+  const ask = (...args) => {
+    try {
+      return { ok: true, out: execFileSync("git", ["-C", String(dir ?? ""), ...args],
+        { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], env }).trim() };
+    } catch (e) {
+      return { ok: false, status: e?.status ?? null,
+        why: String(e?.stderr || e?.message || e).trim().split("\n")[0].slice(0, 200) };
+    }
+  };
+  const top = ask("rev-parse", "--show-toplevel");
+  if (!top.ok) {
+    return /not a git repository/i.test(top.why)
+      ? { state: "not-a-repository", why: top.why }
+      : { state: "could-not-look", why: top.why };
+  }
+  const root = top.out;
+  const listed = ask("remote");
+  if (!listed.ok) return { state: "could-not-look", why: listed.why };
+  const remotes = listed.out.split("\n").filter(Boolean);
+  // `-q` makes a detached HEAD a quiet exit 1, which is an answer (no branch, so nothing tracks). Any
+  // other failure is git refusing to say, and is reported as that.
+  const head = ask("symbolic-ref", "--short", "-q", "HEAD");
+  if (!head.ok) return head.status === 1 ? { state: "stays-here", root, branch: null, remotes } : { state: "could-not-look", why: head.why };
+  const branch = head.out;
+  // `config --get` exits 1 for a key that is not set, which is again an answer; anything else is not.
+  const setting = (key) => {
+    const r = ask("config", "--get", key);
+    if (r.ok) return { value: r.out };
+    return r.status === 1 ? { value: null } : { why: r.why };
+  };
+  const remote = setting(`branch.${branch}.remote`);
+  if (remote.why) return { state: "could-not-look", why: remote.why };
+  // A branch tracking another LOCAL branch names the remote `.`: a pull merges within this repository,
+  // and unless a push remote is named below, a push goes nowhere else.
+  if (!remote.value || remote.value === ".") {
+    // ── NO TRACKING IS NOT THE SAME AS NOTHING LEAVES ────────────────────────────────────────────────
+    //
+    // A bare `git push` on a branch with no tracking still publishes it in three configurations. Measured
+    // with git 2.43 against real remotes, 2026-09-10, after a review drove the first one:
+    // `push.autoSetupRemote=true` (the push sets up tracking as it goes), `push.default=current`, and
+    // `push.default=matching` once the remote has a branch of the same name. `upstream` and `nothing` refuse
+    // with no upstream. Git's default, `simple`, refuses too, UNLESS the push is triangular: a push remote
+    // (the branch's `pushRemote`, or `remote.pushDefault`) that is not the remote the branch fetches from.
+    // Then `simple` pushes as `current` does. A review drove that case with git 2.43 after this comment had
+    // said `simple` refuses whenever only those keys are set; that is true only while they name the fetch
+    // remote. Where a push goes is git's order: the branch's push remote, then `remote.pushDefault`, then
+    // `origin`, then the only remote there is. The remote a branch with no upstream fetches from is found
+    // the same way without the first two. The test beside this pushes for real in each configuration and
+    // holds this function to what git did.
+    const pushRemote = setting(`branch.${branch}.pushRemote`), pushDefault = setting("remote.pushDefault"), mode = setting("push.default");
+    for (const x of [pushRemote, pushDefault, mode]) if (x.why) return { state: "could-not-look", why: x.why };
+    const auto = ask("config", "--type=bool", "--get", "push.autoSetupRemote");
+    if (!auto.ok && auto.status !== 1) return { state: "could-not-look", why: auto.why };
+    // ── WHICH GIT IS ANSWERING ─────────────────────────────────────────────────────────────────────────
+    //
+    // Two of these rules arrived in git 2.37.0: `push.autoSetupRemote`, and the fallback that makes the only
+    // remote the default when it is not named `origin`. Before 2.37 the default remote is `origin` whether
+    // or not one exists, so a lone remote with another name is never the default. A push remote naming it
+    // is then triangular against a missing `origin`, and `simple` pushes. A review found that for the git on
+    // Ubuntu 22.04 (2.34), where the 2.37 reading here said the store stayed: a missed publish, the one
+    // direction this must not err in. A version git will not state is read both ways, below.
+    const ver = /(\d+)\.(\d+)/.exec(String(gitVersion ?? ask("version").out ?? ""));
+    const pushing = mode.value || "simple";
+    const reading = (modern) => {
+      const fallback = remotes.includes("origin") ? "origin" : modern && remotes.length === 1 ? remotes[0] : null;
+      const fetchesFrom = remote.value || (modern ? fallback : "origin");
+      const dest = pushRemote.value || pushDefault.value || (remote.value === "." ? null : fallback);
+      const triangular = dest !== fetchesFrom;
+      const autoOn = modern && auto.ok && auto.out === "true";
+      const via = !dest || !remotes.includes(dest) ? null
+        : pushing === "current" ? "push.default is current"
+        // `upstream` refuses a push to a remote the branch does not fetch from, tracking set up or not:
+        // "You are pushing to remote 'x', which is not the upstream of your current branch".
+        : autoOn && (pushing === "simple" || (pushing === "upstream" && !triangular)) ? "push.autoSetupRemote is on"
+        : pushing === "simple" && triangular ? `push.default is simple, and it pushes to ${dest}, not the remote this branch fetches from`
+        : pushing === "matching" && ask("rev-parse", "--verify", "-q", `refs/remotes/${dest}/${branch}`).ok
+          ? "push.default is matching, and the remote has this branch"
+        : null;
+      return { via, dest };
+    };
+    // A GIT THAT WILL NOT STATE ITS VERSION IS READ BOTH WAYS, and publishing wins. Reading it as current
+    // was the exception to "never err toward staying": in the lone-remote case the older reading is the one
+    // that publishes. A review of that exception named it; every real git states its version, so this
+    // costs nothing today and removes the one case where the promise above did not hold.
+    const modernNow = ver && (Number(ver[1]) > 2 || (Number(ver[1]) === 2 && Number(ver[2]) >= 37));
+    const now = ver ? reading(modernNow) : reading(true);
+    const older = ver ? null : reading(false);
+    const r = now.via ? now
+      : older?.via ? { ...older, via: `${older.via}, as a git older than 2.37 would push it; this git did not state its version` }
+      : now;
+    const { via, dest } = r;
+    if (!via) return { state: "stays-here", root, branch, remotes };
+    const known = ask("rev-list", "--count", `refs/remotes/${dest}/${branch}..HEAD`);
+    return { state: "publishes", root, branch, upstream: `${dest}/${branch}`, via,
+      ahead: known.ok && /^\d+$/.test(known.out) ? Number(known.out) : null };
+  }
+  const merge = setting(`branch.${branch}.merge`);
+  if (merge.why) return { state: "could-not-look", why: merge.why };
+  const upstream = `${remote.value}/${String(merge.value ?? branch).replace(/^refs\/heads\//, "")}`;
+  const count = ask("rev-list", "--count", "@{u}..HEAD");
+  const ahead = count.ok && /^\d+$/.test(count.out) ? Number(count.out) : null;
+  return { state: "publishes", root, branch, upstream, ahead, via: "tracking" };
+}

package/shared/withheld-paths-access.mjs

@@ -48,17 +48,17 @@
 // present, and cannot see whether it ought to be. So it states the mode and what that means for the
 // three readers, and leaves the judgement to a reader who knows which tree they are looking at.
 //
-// NOTHING PINS THIS ANNOUNCEMENT, and this block used to claim something did. Measured 2026-09-09: no
-// test in either repository imports `announceWithheldMode` or asserts its line, so the wording above is
-// held by nothing and a silent removal of it would pass. That gap is filed rather than fixed here,
-// because closing it adds a test file and this change is comment text only.
+// WHAT HOLDS THE ANNOUNCEMENT: `driver/test/the-public-residue-is-a-floor.test.mjs`, in a throwaway tree
+// in both modes. Each mode says so, the two say different things, the present one counts its entries, the
+// line is said once and returned on every call, and the stricter mode does not call itself an alarm. Those
+// arms hold the property rather than the sentence, so the wording can be corrected without re-pointing them.
 
 let record = null;
 try {
   record = await import("./withheld-paths.mjs");
 } catch {
-  // Absent is the PUBLIC tree's normal state and our tree's alarm. Which one it is, is the caller's to
-  // decide from `CUT_RECORD_PRESENT`; this module only refuses to guess.
+  // Absent is the state of every tree today, as the header says. Whether that is right is the caller's
+  // to judge from `CUT_RECORD_PRESENT`; this module only refuses to guess.
   record = null;
 }
 

package/shared/yes-no-echo.mjs

@@ -0,0 +1,35 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026 Cordillera Sàrl. Additional terms under section 7 of the AGPL-3.0 apply — see ADDITIONAL-TERMS.md
+//
+// A YES/NO QUESTION ECHOES ONLY A YES/NO ANSWER.
+//
+// Setup asks "Enter a Perplexity API key now? [Y/n]", and a person who already holds the key pastes it
+// there. The wizard answered "Please answer y or n" and asked again, which is right, but the key had
+// already been echoed to the terminal, into its scrollback and into whatever gets pasted into a bug
+// report. Reported from a real install, 2026-09-10.
+//
+// THE ECHO IS DECIDED CHARACTER BY CHARACTER, because that is how it happens. In terminal mode readline
+// writes each keypress as it arrives, a paste included, so by the time the line is submitted every
+// character has already been shown. Waiting for the answer and then deciding is too late. So the echo is
+// allowed only while the line typed so far can still become `y`, `yes`, `n` or `no`, and a key never is.
+
+/** Whether the line typed so far can still become a yes/no answer. The empty line can: it takes the default. */
+export const couldBeYesNo = (line) => /^(y|ye|yes|n|no)?$/i.test(String(line ?? ""));
+
+/**
+ * Whether an answer is plainly a credential rather than a yes/no: sixteen or more characters with no space
+ * in them. No yes/no answer is that long, and every key this product asks for is longer.
+ */
+export const looksLikeAKey = (answer) => /^\S{16,}$/.test(String(answer ?? "").trim());
+
+/**
+ * What a yes/no question lets readline write, given the chunk it is about to write, the line typed so far
+ * and the question's prompt. Cursor movement and the newline always pass, so the terminal stays in step.
+ * Readline redraws the prompt and the whole line as one write after an edit, so a redraw keeps the prompt
+ * and drops the line.
+ */
+export function yesNoEchoOf(chunk, { line = "", prompt = "" } = {}) {
+  const s = String(chunk ?? "");
+  if (!s || s.charCodeAt(0) === 0x1b || /^[\r\n]+$/.test(s) || couldBeYesNo(line)) return s;
+  return prompt && s.startsWith(prompt) ? prompt : "";
+}