clearotron 0.3.0-beta.8 → 0.3.0

package/shared/env-file-merge.mjs

@@ -34,6 +34,30 @@
  *                             like an engine fault. Names here must be values this code MINTS; putting
  *                             a credential a reader supplied in this list would delete their work.
  */
+// ── THE ONE `KEY=value` READER, AND IT LIVES IN A LEAF ────────────────────────────────────────────
+//
+// This reads the same file systemd's EnvironmentFile= reads, and systemd does no shell expansion there
+// either. Quotes are stripped because operators write them.
+//
+// IT USED TO LIVE IN `driver/systemd/render-units.mjs`, which is a COMMAND as well as a module, and its
+// `--apply` path awaits at the top level and imports `bin/start.mjs` from inside that await. So a reader
+// that took the parser from there put the command's own module in its import path: `start.mjs` importing
+// it closed a cycle, the CLI's top-level await never settled, and 21 install arms died at once with
+// "Detected unsettled top-level await" and nothing naming the cause (measured 2026-09-12). The parser has
+// no business depending on any of that — it is eleven lines of string handling — so it sits here, in a
+// file that imports nothing, and `render-units.mjs` re-exports it so its readers keep one reader.
+export function parseEnvFile(text) {
+  const out = {};
+  for (const line of String(text ?? "").split("\n")) {
+    const m = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line);
+    if (!m) continue;
+    let v = m[2].trim();
+    if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) v = v.slice(1, -1);
+    out[m[1]] = v;
+  }
+  return out;
+}
+
 export function mergeEnvFile(text, additions, { by = "`npm start` (bin/start.mjs)", notes = {}, refresh = [] } = {}) {
   const body = typeof text === "string" ? text : "";
   const present = new Set();

package/shared/invocation.mjs

@@ -205,6 +205,24 @@ export function invocationForm(env = process.env, io = FS, installDir = INSTALL_
     // right there and naming it in full is true from any directory.
     return { form: "shim-path", prefix: `${globalDir}${sep}`, shim: globalExe, dir: globalDir, onPath, shadowedBy, staleInterpreter: null, via: "global" };
   }
+  // ── FROM NPX'S CACHE, THE PUBLISHED VERSION, NOT THE CACHE ──────────────────────────────────────────
+  //
+  // `in-place` below names the directory this install runs from, and under npx that is npm's cache:
+  // `cd <npm's cache> && npx clearotron …`. npm deletes that directory when it cleans its cache, so every
+  // command a verb printed there stopped working before its reader typed it (a packaged-install drive of
+  // `doctor`, 2026-09-11, found thirteen). `npx -p clearotron@<version>` fetches this same version from any
+  // directory. It is the decision `browserCommand` makes for a page, `npx clearotron@<version> <verb>`,
+  // spelled for a PREFIX, which the word `clearotron` follows. Asked after a shim of ours and a global
+  // install, which are stronger evidence than the cache path; a version that cannot be read falls through
+  // to `in-place` rather than naming a guess.
+  const npxVersion = npxVersionOf(installDir, io.read ?? readFileSync);
+  if (npxVersion) {
+    return {
+      form: "npx-pinned", prefix: `npx -p clearotron@${npxVersion} `, shim: path, dir,
+      onPath: false, shadowedBy: null, shimKind: shim.kind, otherInstall: shim.installDir,
+      staleInterpreter: shim.interpreterMissing === true ? shim.interpreter : null,
+    };
+  }
   // ✕ A BROKEN SHIM MUST NOT BE THE FORM WE HAND BACK, however well it identifies itself. Driven and
   // caught: doctor reported the stale interpreter and then told the reader to run `clearotron install`
   // to fix it — through the very shim it had just called broken. The advice for repairing a route

package/shared/running-start.mjs

@@ -0,0 +1,73 @@
+// 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
+//
+// running-start.mjs — which foreground `clearotron start` processes are serving on this machine, and where.
+//
+// `status` promises "is the product up, and on which ports", and knew only about background units. With
+// the product running the way the README starts it — `clearotron start` in a terminal — it printed a
+// sentence about units the reader never installed, and `stop` said nothing was running while the portal
+// answered 200 (measured on a published beta, 2026-09-11). A foreground start now leaves one small record
+// here while it serves, and both verbs read it.
+//
+// THE RECORD IS AN ADDRESS, NEVER PROOF OF LIFE. A start killed outright leaves its record behind, so a
+// record whose process is gone is read as absent, and `status` asks the portal itself before saying the
+// product is up. Three answers, all honest: up; started but not answering; not running.
+
+import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * Where the records live: one file per serving process, beside the settings and the revocation list.
+ *
+ * `~/.config/clearotron` is this product's per-user directory and the only one it reads. An XDG state
+ * directory would be the tidier home for this, and it would be a NEW environment variable read by product
+ * code — a thing this repo documents in two contract files and classifies in another repo. Not worth a
+ * paired change for a file the reader never opens.
+ */
+export function runningDir({ home = homedir() } = {}) {
+  return join(home, ".config", "clearotron", "running");
+}
+
+/** Is this process alive? EPERM means it exists and belongs to somebody else, which is alive. */
+export function pidAlive(pid) {
+  try { process.kill(pid, 0); return true; } catch (e) { return e?.code === "EPERM"; }
+}
+
+/**
+ * Record one serving start. Returns the function that removes the record; calling it twice is harmless,
+ * so the caller can hang it on both its own shutdown and the process's `exit`.
+ */
+export function recordRunning(rec, { dir = runningDir() } = {}) {
+  mkdirSync(dir, { recursive: true });
+  const file = join(dir, `${rec.pid}.json`);
+  const tmp = `${file}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(rec, null, 2)}\n`, { mode: 0o600 });
+  renameSync(tmp, file);
+  let gone = false;
+  return () => {
+    if (gone) return;
+    gone = true;
+    try { rmSync(file, { force: true }); } catch { /* already gone */ }
+  };
+}
+
+/** Every record whose process is alive, oldest pid first. Reads; removes nothing. */
+export function readRunning({ dir = runningDir(), alive = pidAlive } = {}) {
+  let names;
+  try { names = readdirSync(dir); } catch { return []; }
+  const out = [];
+  for (const name of names.filter((n) => /^\d+\.json$/.test(n))) {
+    let rec;
+    try { rec = JSON.parse(readFileSync(join(dir, name), "utf8")); } catch { continue; }
+    if (!Number.isInteger(rec?.pid) || typeof rec?.url !== "string" || !rec?.ports) continue;
+    if (!alive(rec.pid)) continue;   // a start that did not exit cleanly: its record says nothing now
+    out.push(rec);
+  }
+  return out.sort((a, b) => a.pid - b.pid);
+}
+
+/** Does the portal at `url` answer? A timeout or a refusal is "no", never "unknown dressed as yes". */
+export async function probe(url, { timeoutMs = 2000 } = {}) {
+  try { return (await fetch(url, { signal: AbortSignal.timeout(timeoutMs) })).ok; } catch { return false; }
+}