clearotron 0.3.0-beta.4 → 0.3.0-beta.6

package/shared/permanent-install.mjs

@@ -0,0 +1,167 @@
+// 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
+//
+// WHERE THIS PROGRAM LIVES, AND WHY NEVER IN NPX'S CACHE.
+//
+// `npx clearotron install` runs the package from npm's cache, under `_npx/<hash>/`. That directory is
+// npm's, not ours: a later `npx clearotron@<newer>` unpacks somewhere else, and a cache clean deletes it.
+// Everything the install wired to its own directory went with it — the `clearotron` launcher, and the
+// connect line an assistant was registered with — so an assistant kept launching the old server after an
+// update, and lost Clearotron without a word after a clean. Owner ruling, 2026-09-11: an install run from
+// npx puts the program in a permanent place it owns, the one `npm install -g` would use, and points
+// everything there.
+//
+// THE PLACE IS THE PREFIX `~/.local`. npm puts the package at `~/.local/lib/node_modules/clearotron` and
+// its executable in `~/.local/bin`, the directory the launcher already goes in. It needs no root, and it
+// is the layout `invocationForm` already recognises as a global install.
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { globalBinDirFrom } from "./invocation.mjs";
+
+/** The root of THIS install — `<root>/shared/permanent-install.mjs` is this file. */
+export const INSTALL_DIR = dirname(dirname(fileURLToPath(import.meta.url)));
+
+/** npx materialises a package under `_npx/` in npm's cache, and nothing else this runs from does. */
+export function inNpxCache(dir = INSTALL_DIR) {
+  return /[\\/]_npx[\\/]/.test(String(dir ?? ""));
+}
+
+/** The prefix an install run from npx moves to. `null` when the environment names no home. */
+export function permanentPrefix(env = process.env) {
+  const home = String(env?.HOME ?? "").trim();
+  return home ? join(home, ".local") : null;
+}
+
+/** Where npm puts this package under a prefix: the layout `globalBinDirFrom` reads back. */
+export function packageRootUnder(prefix) {
+  return join(prefix, "lib", "node_modules", "clearotron");
+}
+
+/** The version this install is, from its own manifest. `null` when that cannot be read. */
+export function ownVersion(installDir = INSTALL_DIR, read = readFileSync) {
+  try { return JSON.parse(read(join(installDir, "package.json"), "utf8")).version ?? null; } catch { return null; }
+}
+
+/**
+ * The npm dist-tag a version was published under: `0.3.0-beta.5` came from `beta`, `0.3.0` from `latest`.
+ * An update follows the channel the install came from, so a verb that means "newer" never moves a beta
+ * install onto the stable line, or the reverse.
+ */
+export function channelOf(version) {
+  const pre = /^\d+\.\d+\.\d+-([A-Za-z]+)/.exec(String(version ?? ""))?.[1];
+  return pre ? pre.toLowerCase() : "latest";
+}
+
+/**
+ * What `install` does first when it runs from npx. PURE given its inputs.
+ *
+ * `null` when there is nothing to move, because this install is not in npx's cache. Otherwise a plan, or
+ * `{ skip }` naming why the move cannot be made here: Windows, where no launcher is written either; no
+ * home; or a version that cannot be read, since installing some other version would be a silent upgrade.
+ */
+export function relocationPlan({ installDir = INSTALL_DIR, env = process.env, platform = process.platform, version = ownVersion(installDir) } = {}) {
+  if (!inNpxCache(installDir)) return null;
+  if (platform === "win32") return { skip: "windows" };
+  const prefix = permanentPrefix(env);
+  if (!prefix) return { skip: "no-home" };
+  if (!version) return { skip: "no-version" };
+  const root = packageRootUnder(prefix);
+  return {
+    prefix, root, version,
+    entry: join(root, "bin", "clearotron.mjs"),
+    // --prefer-offline: npx has just fetched exactly this version, so npm's cache already holds it.
+    npmArgs: ["install", "--global", "--prefix", prefix, "--prefer-offline", "--no-fund", "--no-audit", `clearotron@${version}`],
+  };
+}
+
+/**
+ * Semver order, a prerelease below its release: 0.3.0-beta.5 < 0.3.0-beta.10 < 0.3.0 < 0.3.1. Negative,
+ * zero or positive as `a` sorts before, with or after `b`; `null` when either cannot be read as a version.
+ */
+export function compareVersions(a, b) {
+  const parse = (v) => {
+    const m = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(String(v ?? "").trim());
+    return m ? { core: [+m[1], +m[2], +m[3]], pre: m[4] ? m[4].split(".") : [] } : null;
+  };
+  const x = parse(a), y = parse(b);
+  if (!x || !y) return null;
+  for (let i = 0; i < 3; i++) if (x.core[i] !== y.core[i]) return x.core[i] - y.core[i];
+  if (!x.pre.length || !y.pre.length) return y.pre.length - x.pre.length;
+  for (let i = 0; i < Math.max(x.pre.length, y.pre.length); i++) {
+    const p = x.pre[i], q = y.pre[i];
+    if (p === undefined) return -1;
+    if (q === undefined) return 1;
+    if (p === q) continue;
+    const pn = /^\d+$/.test(p), qn = /^\d+$/.test(q);
+    if (pn && qn) return +p - +q;
+    if (pn !== qn) return pn ? -1 : 1;
+    return p < q ? -1 : 1;
+  }
+  return 0;
+}
+
+/**
+ * WHICH PUBLISHED VERSION AN UPDATE INSTALLS. PURE given the dist-tags npm reports.
+ *
+ * A beta install follows `beta` AND `latest`, and takes whichever is newer. Following `beta` alone left
+ * every beta tester on the last beta once the release went to `latest`, because `beta` is not moved on
+ * a stable release. A stable install follows `latest` only, so an update never moves it onto a
+ * prerelease. The exact version is installed, so npm cannot resolve the tag to something else between
+ * this read and the install.
+ *
+ * `current` when nothing published is newer than the running version. Tags that cannot be read fall back
+ * to the channel's own tag, with `unread` set so the caller can say so.
+ */
+export function updateTarget({ version, distTags }) {
+  const channel = channelOf(version);
+  let best = null;
+  for (const tag of channel === "latest" ? ["latest"] : [channel, "latest"]) {
+    const v = distTags?.[tag];
+    if (compareVersions(v, v) !== 0) continue;
+    if (!best || compareVersions(v, best.version) > 0) best = { tag, version: v };
+  }
+  if (!best) return { tag: channel, version: null, spec: channel, current: false, unread: true };
+  const newer = compareVersions(best.version, version);
+  return { ...best, spec: best.version, current: newer !== null && newer <= 0, unread: false };
+}
+
+/** npm's dist-tags for the package, e.g. `{ latest: "0.3.0", beta: "0.3.0-beta.5" }`. `null` when npm cannot answer. */
+export function readDistTags(run = spawnSync) {
+  const r = run("npm", ["view", "clearotron", "dist-tags", "--json"], { encoding: "utf8", timeout: 60_000 });
+  if (r.error || r.status !== 0) return null;
+  try {
+    const tags = JSON.parse(r.stdout);
+    return tags && typeof tags === "object" && !Array.isArray(tags) ? tags : null;
+  } catch { return null; }
+}
+
+/**
+ * How a packaged install updates itself: the same npm command, at the prefix it lives under, to the
+ * version `updateTarget` picks. `null` for a layout this cannot name — a checkout, npx's cache, or a
+ * package that is not under `<prefix>/lib/node_modules` — and npm is not asked anything then.
+ */
+export function packagedUpdate({ installDir = INSTALL_DIR, version = ownVersion(installDir), distTags } = {}) {
+  if (inNpxCache(installDir)) return null;
+  const bin = globalBinDirFrom(installDir);
+  if (!bin) return null;
+  const prefix = dirname(bin);
+  const target = updateTarget({ version, distTags: distTags === undefined ? readDistTags() : distTags });
+  return {
+    prefix, installed: version, ...target,
+    npmArgs: ["install", "--global", "--prefix", prefix, "--no-fund", "--no-audit", `clearotron@${target.spec}`],
+  };
+}
+
+/**
+ * The install root a connect line should name. The running root, unless that is npx's cache and the
+ * permanent install exists, in which case the permanent one: an assistant registered against the cache
+ * loses Clearotron when the cache is cleaned, which is the defect this file exists to end.
+ */
+export function stableInstallRoot({ installRoot = INSTALL_DIR, env = process.env, exists = existsSync } = {}) {
+  if (!inNpxCache(installRoot)) return installRoot;
+  const prefix = permanentPrefix(env);
+  const root = prefix ? packageRootUnder(prefix) : null;
+  return root && exists(join(root, "mcp-server", "server.mjs")) ? root : installRoot;
+}

package/shared/stdio-connect.mjs

@@ -31,6 +31,7 @@
 
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { stableInstallRoot } from "./permanent-install.mjs";
 
 /** The install root — the directory holding `mcp-server/`, resolved from this module rather than cwd. */
 export const INSTALL_ROOT = join(fileURLToPath(new URL(".", import.meta.url)), "..");
@@ -49,10 +50,8 @@ export const STDIO_SERVER_NAME = "trademark-artifacts";
  * @param {{ installRoot?: string, workDir?: string|null }} [opts]
  * @returns {string} the exact command to run
  */
-export function stdioConnectCommand({ installRoot = INSTALL_ROOT, workDir = null } = {}) {
-  const server = join(installRoot, "mcp-server", "server.mjs");
-  const env = workDir ? ` -e CLEAROTRON_WORK_DIR=${workDir}` : "";
-  return `claude mcp add ${STDIO_SERVER_NAME}${env} -- node ${server}`;
+export function stdioConnectCommand({ installRoot = stableInstallRoot({ installRoot: INSTALL_ROOT }), workDir = null, reportsDir = null, platform = process.platform } = {}) {
+  return STDIO_SHAPES["claude-cli"].render({ server: join(installRoot, "mcp-server", "server.mjs"), workDir, reportsDir, platform });
 }
 
 /**
@@ -89,24 +88,42 @@ export function stdioConnectOffer(opts = {}) {
 // So the three facts are resolved ONCE and rendered three ways. A row names its shape; nothing switches
 // on a client's name. Adding a host is a renderer plus a row, and it cannot invent a different route.
 
+/**
+ * The settings the server is started with: the workspace it reads runs from, and the folder its reports are
+ * published to. Handed over rather than left to the server's own defaults, so it reads what the services
+ * read: a demo's own base, not the real install's workspace. Only what is set is written.
+ */
+function envOf({ workDir = null, reportsDir = null } = {}) {
+  return { ...(workDir ? { CLEAROTRON_WORK_DIR: workDir } : {}), ...(reportsDir ? { CLEAROTRON_REPORTS_DIR: reportsDir } : {}) };
+}
+const envFlags = (o) => Object.entries(envOf(o)).map(([k, v]) => ` -e ${k}=${v}`).join("");
+const envBlock = (o) => (Object.keys(envOf(o)).length ? { env: envOf(o) } : {});
+
+/**
+ * The argument that ends Claude Code's own options. Windows PowerShell 5.1 drops a bare `--` before it
+ * reaches a native program, so the line failed with "missing required argument"; quoted, every shell passes
+ * it through (bash, zsh, PowerShell and cmd alike), so a Windows install is handed the quoted form.
+ */
+const separator = (platform = process.platform) => (platform === "win32" ? '"--"' : "--");
+
 /** How each host takes the same three facts. A row of CONNECT_CLIENTS names one of these by key. */
 export const STDIO_SHAPES = Object.freeze({
   "claude-cli": {
     kind: "command",
     where: null,
-    render: ({ server, workDir }) =>
-      `claude mcp add ${STDIO_SERVER_NAME}${workDir ? ` -e CLEAROTRON_WORK_DIR=${workDir}` : ""} -- node ${server}`,
+    render: ({ server, workDir, reportsDir, platform }) =>
+      `claude mcp add ${STDIO_SERVER_NAME} --scope user${envFlags({ workDir, reportsDir })} ${separator(platform)} node ${server}`,
     after: null,
   },
   "desktop-json": {
     kind: "config",
     where: "Settings → Developer → Edit Config",
-    render: ({ server, workDir }) => JSON.stringify({
+    render: ({ server, workDir, reportsDir }) => JSON.stringify({
       mcpServers: {
         [STDIO_SERVER_NAME]: {
           command: "node",
           args: [server],
-          ...(workDir ? { env: { CLEAROTRON_WORK_DIR: workDir } } : {}),
+          ...envBlock({ workDir, reportsDir }),
         },
       },
     }, null, 2),
@@ -117,10 +134,10 @@ export const STDIO_SHAPES = Object.freeze({
   "generic-json": {
     kind: "config",
     where: "your agent's MCP server configuration",
-    render: ({ server, workDir }) => JSON.stringify({
+    render: ({ server, workDir, reportsDir }) => JSON.stringify({
       command: "node",
       args: [server],
-      ...(workDir ? { env: { CLEAROTRON_WORK_DIR: workDir } } : {}),
+      ...envBlock({ workDir, reportsDir }),
     }, null, 2),
     after: null,
   },
@@ -134,11 +151,12 @@ export const STDIO_SHAPES = Object.freeze({
     // Codex does not forward the shell environment, and a credential would have to be forwarded BY NAME
     // rather than written into a file. This server takes no credential — the work directory is a path,
     // not a secret — so `env` is correct here and would not be for a server that wanted a key.
-    render: ({ server, workDir }) => [
+    render: ({ server, workDir, reportsDir }) => [
       `[mcp_servers.${STDIO_SERVER_NAME}]`,
       `command = "node"`,
       `args = ["${server}"]`,
-      ...(workDir ? [`env = { CLEAROTRON_WORK_DIR = "${workDir}" }`] : []),
+      ...(Object.keys(envOf({ workDir, reportsDir })).length
+        ? [`env = { ${Object.entries(envOf({ workDir, reportsDir })).map(([k, v]) => `${k} = "${v}"`).join(", ")} }`] : []),
     ].join("\n"),
     after: null,
   },
@@ -215,13 +233,13 @@ export function remoteConnectFor(shape, { address = null } = {}) {
  * absence is a finding: a row naming a shape nobody implemented should surface as missing, and the
  * table's own arm refuses such a row outright.
  */
-export function stdioConnectFor(shape, { installRoot = INSTALL_ROOT, workDir = null } = {}) {
+export function stdioConnectFor(shape, { installRoot = stableInstallRoot({ installRoot: INSTALL_ROOT }), workDir = null, reportsDir = null, platform = process.platform } = {}) {
   const spec = Object.hasOwn(STDIO_SHAPES, String(shape ?? "")) ? STDIO_SHAPES[shape] : null;
   if (!spec) return null;
   const server = join(installRoot, "mcp-server", "server.mjs");
   return {
     shape, kind: spec.kind, where: spec.where, after: spec.after,
-    text: spec.render({ server, workDir }),
+    text: spec.render({ server, workDir, reportsDir, platform }),
     name: STDIO_SERVER_NAME,
   };
 }

package/shared/verb-shim.mjs

@@ -18,7 +18,7 @@
 // install "I wrote that shim, and it points at ME". If the sentence that writes it and the sentence
 // that matches it sat in different files, a change to either would leave the other quietly answering
 // the old question — the shape recorded as "a mechanical rename must move both ends".
-import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { chmodSync, closeSync, existsSync, lstatSync, mkdirSync, openSync, readSync, realpathSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { delimiter, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -84,6 +84,15 @@ function readHead(path, cap = 4096) {
  * exactly the `which` mistake shared/invocation.mjs refuses to make, wearing different clothes.
  */
 export function inspectShim(path, { installDir = INSTALL_DIR, read = readHead } = {}) {
+  // NPM'S OWN LINK INTO THIS INSTALL IS OURS TO REPLACE. An install moved out of npx's cache is put in
+  // place by `npm install --global --prefix ~/.local`, and npm links `~/.local/bin/clearotron` to the
+  // package's executable: the very path the shim goes in. Read as a file it carries no marker, so it was
+  // reported as somebody else's and left alone, and it reaches `node` through `env`, which a service's
+  // PATH may not carry. A link that resolves to THIS install's own executable is replaced with the shim.
+  try {
+    if (lstatSync(path).isSymbolicLink() && realpathSync(path) === realpathSync(join(installDir, "bin", "clearotron.mjs")))
+      return { kind: "npm-link", installDir, interpreter: null, interpreterMissing: null };
+  } catch { /* not a link, or one that leads nowhere: read below as a file */ }
   let head;
   try {
     head = read(path);

package/shared/wsl.mjs

@@ -0,0 +1,23 @@
+// 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
+//
+// Whether this is a Linux running under Windows. Shared because two readers need the one answer: the install
+// (which binaries on a Windows drive to pass over) and the connect lines (which must say to run them inside
+// WSL, where their paths exist).
+import { readFileSync } from "node:fs";
+
+/**
+ * BOTH SIGNALS INJECTABLE, for the reason `platformEngineRefusal` gives: the readers this protects are the
+ * ones who cannot run this suite to find out, so a Linux runner has to be able to drive both answers
+ * rather than read the source and agree with it.
+ *
+ * A READ THAT FAILS ANSWERS "NOT WSL", and that is the direction that changes nothing: it leaves the
+ * resolution exactly as it was before this existed. Claiming WSL on a could-not-read would start refusing
+ * candidates under /mnt on an ordinary Linux box with an ordinary mount.
+ */
+export function isWsl({ env = process.env, procVersion = null } = {}) {
+  if (String(env.WSL_DISTRO_NAME ?? "").trim()) return true;
+  if (String(env.WSL_INTEROP ?? "").trim()) return true;
+  const v = procVersion ?? (() => { try { return readFileSync("/proc/version", "utf8"); } catch { return ""; } })();
+  return /microsoft|wsl/i.test(v);
+}