clearotron 0.3.0-beta.7 → 0.3.0-beta.9

package/shared/permanent-install.mjs

@@ -201,3 +201,37 @@ export function demoProgramPlan({ base, installDir = INSTALL_DIR, platform = pro
     npmArgs: ["install", "--global", "--prefix", prefix, "--prefer-offline", "--no-fund", "--no-audit", `clearotron@${version}`],
   };
 }
+
+/**
+ * Lays the demo's copy down when it is missing or another version, and returns its root; `null` when there
+ * is no copy to use (not run from npx, or a copy that could not be made). It never stops the demo: if npm
+ * fails, the demo runs from npx's cache as before and says what that costs. `demoProgramPlan` decides;
+ * this is the one place that acts on it, for `demo` and for a `start --demo` run from npx.
+ */
+export function ensureDemoProgram({ base, say, env = process.env, run = spawnSync, exists = existsSync, plan = demoProgramPlan({ base }) }) {
+  if (plan?.current) return plan.root;
+  if (!plan || plan.skip) return null;
+  say(`  program        copying clearotron ${plan.version} into ${plan.prefix}, so the commands below and your assistant's connection survive npm cleaning its cache`);
+  // The npm that launched this, when npm says which: no second npm is guessed at.
+  const npmCli = env.npm_execpath;
+  const opts = { stdio: ["ignore", "ignore", "pipe"], encoding: "utf8", timeout: 180_000 };
+  const r = npmCli && exists(npmCli) ? run(process.execPath, [npmCli, ...plan.npmArgs], opts) : run("npm", plan.npmArgs, opts);
+  if (r.status === 0 && exists(join(plan.root, "mcp-server", "server.mjs"))) return plan.root;
+  const why = r.error ? r.error.message : String(r.stderr ?? "").trim().split("\n").pop() || `npm exited ${r.status}`;
+  say(`  program        could not be copied (${why}). The commands and the connect line below run from npm's temporary`);
+  say("                 cache, so they stop working when npm cleans it; start the demo again to retry.");
+  return null;
+}
+
+/**
+ * The environment a demo's services get when they run from the demo's copy. What makes their printed
+ * commands name the copy is running from it: `invocationPrefix` answers from the running install. npm's
+ * marks of an npx arrival (`npm_command=exec` among them) and the npx path the dispatcher hands down
+ * describe a process npm started, which the copy is not, so they are taken off, as `install` takes them
+ * off when it moves out of the cache.
+ */
+export function demoProgramEnv(env = process.env) {
+  const out = { ...env };
+  for (const k of ["npm_command", "npm_lifecycle_event", "npm_execpath", "CLEAROTRON_INVOKED_AS"]) delete out[k];
+  return out;
+}

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; }
+}