clearotron 0.3.2-beta.12 → 0.3.2-beta.14

package/shared/stdio-connect.mjs

@@ -32,6 +32,7 @@
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { stableInstallRoot } from "./permanent-install.mjs";
+import { tomlString } from "./toml-string.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)), "..");
@@ -50,8 +51,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 = 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 });
+export function stdioConnectCommand({ installRoot = stableInstallRoot({ installRoot: INSTALL_ROOT }), workDir = null, reportsDir = null, platform = process.platform, node = process.execPath } = {}) {
+  return STDIO_SHAPES["claude-cli"].render({ server: join(installRoot, "mcp-server", STDIO_ENTRY), workDir, reportsDir, platform, node });
 }
 
 /**
@@ -103,15 +104,38 @@ export function stdioConnectOffer(opts = {}) {
 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) } : {});
 
+// ── ONE WORD PER ARGUMENT, IN THE SHELL THAT READS THE LINE ───────────────────────────────────────────
+//
+// The command was the arguments joined with spaces, so a path with a space in it became two arguments:
+// `/tmp/Example User/node/bin/node` reached the assistant as `/tmp/Example` and `User/node/bin/node`
+// (measured on the published beta, 2026-09-19). Each argument is now written as one word for the shell it
+// is pasted into. A word made only of characters no shell treats specially is left bare, so the line for
+// an ordinary install reads exactly as it did.
+//
+// POSIX shells: single quotes, the one quoting in which no character is special. A single quote inside is
+// closed, escaped and reopened.
+const POSIX_BARE = /^[A-Za-z0-9_@%+=:,./-]+$/;
+export const posixWord = (s) => (POSIX_BARE.test(String(s)) ? String(s) : `'${String(s).replace(/'/g, "'\\''")}'`);
+// Windows: cmd and PowerShell both honour double quotes, and the program then splits its command line by
+// the C runtime's rules, under which backslashes are literal except where they run up to a quote; there
+// they are doubled, and a quote inside the word is escaped. A comma or a parenthesis is quoted too, because
+// PowerShell reads a bare one as an array or an expression. `$`, a backtick and `%` cannot be quoted the
+// same way for both shells, and a path holding one is left to the reader.
+const WINDOWS_BARE = /^[A-Za-z0-9_+=:./\\-]+$/;
+export const windowsWord = (s) => {
+  const w = String(s);
+  if (WINDOWS_BARE.test(w)) return w;
+  return `"${w.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\+)$/, "$1$1")}"`;
+};
+
 /**
  * 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" ? '"--"' : "--");
+const separator = (windowsShell) => (windowsShell ? '"--"' : "--");
 
 /**
  * WHAT THE HOST ACTUALLY RUNS, and on WSL that is not `node`.
@@ -125,6 +149,12 @@ const separator = (platform = process.platform) => (platform === "win32" ? '"--"
  * -e …`. The distribution is named from `WSL_DISTRO_NAME` when we have it, because a machine with more
  * than one would otherwise get whichever is default — which may be a distribution with no install.
  *
+ * AND IT IS NEVER LEFT BLANK (owner, 2026-09-19). With no name to hand the row used to drop `-d` and take
+ * the default distribution, which fails on a machine whose default is not this one, with nothing on screen
+ * to connect the failure to the choice. The row now carries WSL_DISTRO_PLACEHOLDER in the name's place,
+ * and the Windows side's hint says plainly to fill it in. `WSL_DISTRO_NAME` is the one place the name can
+ * be read from inside the distribution: `/etc/wsl.conf` holds settings for it, not its name.
+ *
  * THE ENVIRONMENT CROSSES THROUGH `env`, NOT THROUGH THE HOST'S OWN env BLOCK. A host on Windows sets
  * variables for the process it starts, which is `wsl.exe`; they do not cross the boundary into the
  * distribution, so a work directory set that way is silently absent on the other side and the server
@@ -134,17 +164,32 @@ const separator = (platform = process.platform) => (platform === "win32" ? '"--"
  * Off WSL the launcher is exactly what it always was, so every row on every other platform is
  * byte-identical to before. PURE.
  */
-export function stdioLauncher({ server, workDir = null, reportsDir = null, wsl = null } = {}) {
+/**
+ * WHICH NODE, AND WHICH FILE (owner, 2026-09-19). A line that said bare `node` ran whatever `node` the
+ * assistant's own PATH found. Through `wsl.exe -e`, a non-login shell, that was the distribution's system
+ * Node 18 while the demo ran on Node 22, and the server died on a syntax error before saying anything
+ * (measured on a Windows laptop). A desktop assistant on any platform starts from a bare PATH the same
+ * way. So every line names the absolute Node this install is running on, `process.execPath`, seen from
+ * where the line is composed, inside WSL when that is where the install is. It names `serve.mjs`, the
+ * entry that refuses an old Node in one plain line before the server loads.
+ */
+export const STDIO_ENTRY = "serve.mjs";
+
+/** What stands in the distribution's name when it cannot be read, and the line that says to fill it in. */
+export const WSL_DISTRO_PLACEHOLDER = "YOUR-WSL-DISTRIBUTION";
+export const WSL_DISTRO_FILL_IN = `Replace ${WSL_DISTRO_PLACEHOLDER} with this Linux's name before you paste it: \`wsl -l\` in Windows lists the names.`;
+
+export function stdioLauncher({ server, workDir = null, reportsDir = null, wsl = null, node = process.execPath } = {}) {
   const vars = envOf({ workDir, reportsDir });
-  if (!wsl) return { command: "node", args: [server], env: vars, crossesIntoWsl: false };
+  if (!wsl) return { command: node, args: [server], env: vars, crossesIntoWsl: false };
   const distro = String(wsl.distro ?? "").trim();
   return {
     command: "wsl.exe",
     // `-e` runs the command directly rather than through a login shell, so nothing of the reader's
     // profile can rewrite the arguments between Windows and the server.
-    args: [...(distro ? ["-d", distro] : []), "-e",
+    args: ["-d", distro || WSL_DISTRO_PLACEHOLDER, "-e",
       ...(Object.keys(vars).length ? ["env", ...Object.entries(vars).map(([k, v]) => `${k}=${v}`)] : []),
-      "node", server],
+      node, server],
     // Already carried inside the argument list above; a host-side env block would set them on the
     // Windows process and never reach the server.
     env: {},
@@ -157,21 +202,27 @@ export const STDIO_SHAPES = Object.freeze({
   "claude-cli": {
     kind: "command",
     where: null,
-    render: ({ server, workDir, reportsDir, platform, wsl }) => {
-      const l = stdioLauncher({ server, workDir, reportsDir, wsl });
+    render: ({ server, workDir, reportsDir, platform, wsl, node }) => {
+      const l = stdioLauncher({ server, workDir, reportsDir, wsl, node });
+      // WHICH SHELL READS IT. A native Windows install's line is pasted on Windows, and so is the row
+      // that crosses into WSL: it exists for an assistant on the Windows side. Everything else is pasted
+      // into a POSIX shell.
+      const windowsShell = platform === "win32" || l.crossesIntoWsl;
+      const word = windowsShell ? windowsWord : posixWord;
       // The host's own `-e` flags set variables for the process IT starts. Off WSL that is the server;
       // through the wrapper it is `wsl.exe`, and they stop at the boundary — so on WSL they ride inside
       // the command instead and this line carries none.
-      const flags = l.crossesIntoWsl ? "" : envFlags({ workDir, reportsDir });
-      return `claude mcp add ${STDIO_SERVER_NAME} --scope user${flags} ${separator(platform)} ${l.command} ${l.args.join(" ")}`;
+      const flags = l.crossesIntoWsl ? ""
+        : Object.entries(envOf({ workDir, reportsDir })).map(([k, v]) => ` -e ${windowsShell ? word(`${k}=${v}`) : `${k}=${word(v)}`}`).join("");
+      return `claude mcp add ${STDIO_SERVER_NAME} --scope user${flags} ${separator(windowsShell)} ${[l.command, ...l.args].map(word).join(" ")}`;
     },
     after: null,
   },
   "desktop-json": {
     kind: "config",
     where: "Settings → Developer → Edit Config",
-    render: ({ server, workDir, reportsDir, wsl }) => {
-      const l = stdioLauncher({ server, workDir, reportsDir, wsl });
+    render: ({ server, workDir, reportsDir, wsl, node }) => {
+      const l = stdioLauncher({ server, workDir, reportsDir, wsl, node });
       return JSON.stringify({
         mcpServers: {
           [STDIO_SERVER_NAME]: {
@@ -189,8 +240,8 @@ export const STDIO_SHAPES = Object.freeze({
   "generic-json": {
     kind: "config",
     where: "your agent's MCP server configuration",
-    render: ({ server, workDir, reportsDir, wsl }) => {
-      const l = stdioLauncher({ server, workDir, reportsDir, wsl });
+    render: ({ server, workDir, reportsDir, wsl, node }) => {
+      const l = stdioLauncher({ server, workDir, reportsDir, wsl, node });
       return JSON.stringify({
         command: l.command,
         args: l.args,
@@ -203,20 +254,21 @@ export const STDIO_SHAPES = Object.freeze({
     kind: "config",
     where: "~/.codex/config.toml",
     // Written out rather than produced by a TOML library: this is four lines with no user-supplied
-    // strings in key positions, and adding a dependency to emit them would be the larger risk.
+    // strings in key positions, and adding a dependency to emit them would be the larger risk. Every
+    // value goes through `tomlString`, so a Windows path's backslashes are escaped as TOML requires.
     //
     // `env` and not `env_vars`, deliberately, and CONNECT.md explains why the distinction matters:
     // 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, reportsDir, wsl }) => {
-      const l = stdioLauncher({ server, workDir, reportsDir, wsl });
+    render: ({ server, workDir, reportsDir, wsl, node }) => {
+      const l = stdioLauncher({ server, workDir, reportsDir, wsl, node });
       return [
         `[mcp_servers.${STDIO_SERVER_NAME}]`,
-        `command = "${l.command}"`,
-        `args = [${l.args.map((a) => `"${a}"`).join(", ")}]`,
+        `command = ${tomlString(l.command)}`,
+        `args = [${l.args.map(tomlString).join(", ")}]`,
         ...(Object.keys(l.env).length
-          ? [`env = { ${Object.entries(l.env).map(([k, v]) => `${k} = "${v}"`).join(", ")} }`] : []),
+          ? [`env = { ${Object.entries(l.env).map(([k, v]) => `${k} = ${tomlString(v)}`).join(", ")} }`] : []),
       ].join("\n");
     },
     after: null,
@@ -276,7 +328,7 @@ export const REMOTE_SHAPES = Object.freeze({
     label: "Copy block",
     render: ({ address }) => [
       `[mcp_servers.${STDIO_SERVER_NAME}]`,
-      `url = "${address}"`,
+      `url = ${tomlString(address)}`,
     ].join("\n"),
   },
   "claude-cli-http": {
@@ -288,7 +340,7 @@ export const REMOTE_SHAPES = Object.freeze({
     label: null,
     render: ({ address }) => [
       `[mcp_servers.${STDIO_SERVER_NAME}]`,
-      `url = "${address}"`,
+      `url = ${tomlString(address)}`,
       `bearer_token_env_var = "${KEY_ENV_VAR}"`,
     ].join("\n"),
   },
@@ -335,11 +387,11 @@ export function remoteConnectFor(shape, { address = null } = {}) {
  */
 export const WSL_ROW_HEADINGS = Object.freeze({ fromWindows: "From Windows", insideWsl: "Inside WSL" });
 
-export function stdioConnectFor(shape, { installRoot = stableInstallRoot({ installRoot: INSTALL_ROOT }), workDir = null, reportsDir = null, platform = process.platform, wsl = null } = {}) {
+export function stdioConnectFor(shape, { installRoot = stableInstallRoot({ installRoot: INSTALL_ROOT }), workDir = null, reportsDir = null, platform = process.platform, wsl = null, node = process.execPath } = {}) {
   const spec = Object.hasOwn(STDIO_SHAPES, String(shape ?? "")) ? STDIO_SHAPES[shape] : null;
   if (!spec) return null;
-  const server = join(installRoot, "mcp-server", "server.mjs");
-  const render = (target) => spec.render({ server, workDir, reportsDir, platform, wsl: target });
+  const server = join(installRoot, "mcp-server", STDIO_ENTRY);
+  const render = (target) => spec.render({ server, workDir, reportsDir, platform, wsl: target, node });
   const base = { shape, kind: spec.kind, where: spec.where, after: spec.after, name: STDIO_SERVER_NAME };
   // OFF WSL NOTHING CHANGES: one launcher, no variants, and `variants: null` rather than an empty array
   // so a consumer cannot read "this install has no sides" as "this install has two sides, both missing".
@@ -355,7 +407,7 @@ export function stdioConnectFor(shape, { installRoot = stableInstallRoot({ insta
     ...base,
     text: render(wsl),
     variants: [
-      { heading: WSL_ROW_HEADINGS.fromWindows, text: render(wsl) },
+      { heading: WSL_ROW_HEADINGS.fromWindows, text: render(wsl), hint: String(wsl.distro ?? "").trim() ? null : WSL_DISTRO_FILL_IN },
       { heading: WSL_ROW_HEADINGS.insideWsl, text: render(null) },
     ],
   };

package/shared/toml-string.mjs

@@ -0,0 +1,25 @@
+// 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
+//
+// ONE TOML STRING ENCODER, for every block this product writes.
+//
+// Two composers write TOML: the engine's per-run Codex configuration and the connection block a reader
+// pastes into `~/.codex/config.toml`. The second wrapped raw values in double quotes, so a Windows path
+// such as `C:\Program Files\nodejs\node.exe` produced a file TOML parsers refuse ("Unescaped '\' in a
+// string"). A value is a TOML string only once it has been through here.
+
+/**
+ * A TOML basic string holding exactly `s`. PURE.
+ *
+ * TOML requires the quotation mark, the backslash and every control character other than tab to be
+ * escaped (U+0000 to U+0008, U+000A to U+001F, and U+007F). The named escapes are used where TOML has one,
+ * and `\uXXXX` for the rest.
+ */
+export function tomlString(s) {
+  const esc = String(s ?? "")
+    .replace(/\\/g, "\\\\").replace(/"/g, '\\"')
+    .replace(/\x08/g, "\\b").replace(/\t/g, "\\t").replace(/\n/g, "\\n")
+    .replace(/\f/g, "\\f").replace(/\r/g, "\\r")
+    .replace(/[\x00-\x1f\x7f]/g, (c) => "\\u" + c.charCodeAt(0).toString(16).padStart(4, "0"));
+  return `"${esc}"`;
+}

package/shared/writing-standard-classes.mjs

@@ -443,9 +443,8 @@ const H1_BLOCK = /<h1\b[^>]*>([\s\S]*?)<\/h1>/g
  * heading was entirely its subject.
  */
 const isSubjectHeading = (inner) => {
-  const bare = String(inner)
-    .replace(/\{(?:[^{}]|\{[^{}]*\})*\}/g, '')   // JSX expressions, one level of nesting
-    .replace(/<[^>]*>/g, '')                      // nested tags
+  let bare = String(inner).replace(/\{(?:[^{}]|\{[^{}]*\})*\}/g, '')   // JSX expressions, one level of nesting
+  for (let prev = null; prev !== bare;) { prev = bare; bare = bare.replace(/<[^>]*>/g, '') }   // nested tags, until none is left
   return !/[A-Za-z]{2}/.test(bare)
 }