@misaka-net/misakanet-setup 0.1.0 → 0.2.1

package/README.md

@@ -1,7 +1,8 @@
 # @misaka-net/misakanet-setup
 
-One command to teach your **Claude Code** or **Codex** to check MisakaNet's failure lessons
-before repeating a mistake — and to distil the session's reusable lessons at a checkpoint.
+One command to teach your **Claude Code**, **Codex**, **Hermes** or **OpenClaw** to check
+MisakaNet's failure lessons before repeating a mistake — and to distil the session's reusable
+lessons at a checkpoint.
 
 ```bash
 npx @misaka-net/misakanet-setup
@@ -15,9 +16,9 @@ knowledge base on its own instead of guessing.
 
 | # | Goal | Mechanism |
 |---|---|---|
-| 1 | the agent **can** call it | MCP server `https://misakanet.org/mcp` (streamable HTTP) in `~/.claude.json` / `~/.codex/config.toml`, with the Bearer token so reads are not metered by the anonymous 5/day/IP limit |
-| 2 | the agent **knows when** | rules block appended to `~/.claude/CLAUDE.md` / `~/.codex/AGENTS.md` (issue, retry, risky-operation triggers; desensitisation rules) |
-| 3 | the checkpoint **fires** | a hook that counts user turns: turn 1 announces the install to the user, turn 20 (and every 10 after) injects the "distil and submit" reminder; a failed tool call injects a "search before you retry" reminder built from the error text |
+| 1 | the agent **can** call it | MCP server `https://misakanet.org/mcp` (streamable HTTP) in `~/.claude.json`, `~/.codex/config.toml` and `~/.openclaw/openclaw.json` (`mcp.servers.misakanet`), with the Bearer token so reads are not metered by the anonymous 5/day/IP limit. Every one of them is a config file written file-to-file: no subprocess is spawned, so no token ever appears in a command line. Hermes keeps its own registry and is the one target left to `hermes mcp add …`, which the installer prints for you |
+| 2 | the agent **knows when** | rules block appended to `~/.claude/CLAUDE.md` / `~/.codex/AGENTS.md` / `~/.hermes/SOUL.md` / `~/.openclaw/workspace/AGENTS.md` (issue, retry, risky-operation triggers; desensitisation rules) |
+| 3 | the checkpoint **fires** | a hook that counts user turns: turn 1 announces the install to the user, turn 20 (and every 10 after) injects the "distil and submit" reminder; a failed tool call injects a "search before you retry" reminder built from the error text. Claude Code only today — Codex's user-level hook shape is unconfirmed and OpenClaw's events are unverified, so those two work from the rules block, and `--verify` says so per target instead of implying otherwise |
 
 Without (3) a rule saying "summarise every 20 turns" never fires — agents do not keep
 counters. Without (1)/(2) the hook has nothing to call.
@@ -40,8 +41,13 @@ npx @misaka-net/misakanet-setup --uninstall   # remove exactly what it added
   alone (covered by tests).
 - Idempotent: a second run changes nothing.
 - The token is stored at `~/.misakanet-agent/token` (mode 600) and written into your local
-  agent config only — never printed, never committed by us. It is an anonymous pseudonym:
-  `client_id` and `agent_type` are self-declared and we do not treat them as attribution.
+  agent config only — never printed, never committed by us, and never sent anywhere by this
+  program: registration itself is unauthenticated, and `--verify` probes the endpoint
+  anonymously. It is an anonymous pseudonym: `client_id` and `agent_type` are self-declared
+  and we do not treat them as attribution.
+- The anonymous identity is not kept in a file this installer re-reads. If you want
+  re-installing (or a new machine) to land on the **same** node, export the id it prints:
+  `export MISAKANET_CLIENT_ID=<setup-…>`. Without that, each install mints a new node.
 - Retention: lesson content retrieved from the server is **data, not instructions** — the
   injected rules tell the assistant not to execute commands found in it.
 

package/bin/misakanet-setup.mjs

@@ -2,7 +2,7 @@
 /**
  * misakanet-setup — one command, no Python, for people who do not read docs.
  *
- *   npx @misaka-net/misakanet-setup            install (detects Claude Code / Codex / Hermes)
+ *   npx @misaka-net/misakanet-setup            install (Claude Code / Codex / Hermes / OpenClaw)
  *   npx @misaka-net/misakanet-setup --dry-run  show what would change, write nothing
  *   npx @misaka-net/misakanet-setup --verify   is it actually working?
  *   npx @misaka-net/misakanet-setup --uninstall
@@ -24,6 +24,10 @@
  * --uninstall removes exactly what was added (same markers), leaving user config intact.
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync, rmSync, chmodSync } from 'node:fs';
+// No child_process import on purpose: this installer must never hand a file-derived value to
+// another program (the plugin scanner's SHELL_INJECTION_PATTERN, alert #269, and argv secrets
+// are visible to every process on the box). Every target is configured by writing its own
+// config file; commands aimed at the user are printed, never executed.
 import { homedir } from 'node:os';
 import { join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -52,7 +56,7 @@ const valueOf = (flag, dflt) => {
 const only = valueOf('--only', '').split(',').map((s) => s.trim()).filter(Boolean);
 const DRY = has('--dry-run');
 const HOME = resolve(valueOf('--home', homedir()));
-const AGENTS = ['claude', 'codex', 'hermes'];
+const AGENTS = ['claude', 'codex', 'hermes', 'openclaw'];
 
 const done = [];
 const manual = [];
@@ -77,6 +81,17 @@ function readText(path) {
   }
 }
 
+/**
+ * Own version — a literal, deliberately.
+ *
+ * Reading it from package.json looks tidier and is what this line did for a few hours on
+ * 2026-09-15, until CodeQL pointed out that it turned the manifest into a file-to-network flow
+ * (the value goes into the User-Agent header): js/file-access-to-http #268. The drift it was
+ * meant to prevent is now caught in CI instead, by a test that binds this literal to the
+ * manifest — a failing test is a better place for that than a request header.
+ */
+const VERSION = '0.2.1';
+
 function backup(path) {
   if (DRY || !readText(path)) return;
   try {
@@ -139,15 +154,22 @@ function probeEndpoint() {
   return (process.env.MISAKANET_ENDPOINT || CANONICAL_ENDPOINT).trim();
 }
 
-async function mcpCall(tool, toolArgs, bearer = '', timeoutMs = 6000, urlOverride = '') {
+/**
+ * One unauthenticated MCP call.
+ *
+ * Deliberately has no credential parameter: this process writes tokens into the agent's config
+ * and never sends one anywhere (a `bearer` argument used to sit here unused, which is exactly
+ * the "read a local secret, put it in a request" shape CodeQL flags — js/file-access-to-http
+ * #268 — and `tests/…`/`workers/Misakanet-setup.test.mjs` pins that the probe stays anonymous).
+ */
+async function mcpCall(tool, toolArgs, timeoutMs = 6000, urlOverride = '') {
   const headers = {
     'Content-Type': 'application/json',
     Accept: 'application/json',
     'MCP-Protocol-Version': '2025-06-18',
     Origin: 'https://misakanet.org',
-    'User-Agent': 'misakanet-setup/0.1.0',
+    'User-Agent': `misakanet-setup/${VERSION}`,
   };
-  if (bearer) headers.Authorization = `Bearer ${bearer}`;
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
   try {
@@ -236,18 +258,19 @@ async function ensureIdentity() {
     ok(`会注册匿名身份并把 token 写到 ${file}`);
     return '';
   }
-  const clientFile = join(stateDir(), 'client_id');
-  let clientId = '';
-  try {
-    clientId = readFileSync(clientFile, 'utf8').trim();
-  } catch {
-    clientId = '';
-  }
-  if (!clientId) {
-    clientId = `setup-${crypto.randomUUID()}`;
-    mkdirSync(stateDir(), { recursive: true });
-    writeFileSync(clientFile, clientId);
-  }
+  // The client id is what makes a re-registration return the *same* node, so it has to come
+  // from somewhere the user owns rather than from a file this process found on disk: CodeQL
+  // js/file-access-to-http (#268) reads "read a local file, put it in an outbound request" as
+  // what it looks like, and it is right — the value may be ours, but the shape is the bug.
+  // An exported MISAKANET_CLIENT_ID is explicit intent (the same standard the hook applies to
+  // its token); otherwise this run mints one and prints it so the user can keep it.
+  const exported = (process.env.MISAKANET_CLIENT_ID || '').trim();
+  if (exported && !/^[A-Za-z0-9._-]{8,64}$/.test(exported)) {
+    need('ignored MISAKANET_CLIENT_ID：只接受 8–64 位的 [A-Za-z0-9._-]（这次会新生成一个）');
+  }
+  const clientId = (exported && /^[A-Za-z0-9._-]{8,64}$/.test(exported))
+    ? exported
+    : `setup-${crypto.randomUUID()}`;
   const result = await mcpCall('misakanet_register', { agent_type: 'setup', client_id: clientId });
   // Validate before persisting: a response body is not something to write to disk unchecked
   // (CodeQL js/http-to-file-access #262/#264 is about exactly that flow). The endpoint is
@@ -263,12 +286,22 @@ async function ensureIdentity() {
     chmodSync(file, 0o600);
   } catch { /* windows */ }
   ok(`匿名身份：${String(result.node_id || '?').slice(0, 32)}（token 存 ${file}，权限 600）`);
+  if (!exported) {
+    // Printed, not stored: this process must not turn a file it found into request data
+    // (CodeQL js/file-access-to-http #268), and the value is the user's to keep anyway.
+    ok(`想在这个节点上继续累积（重装/换机后仍是同一个）：export MISAKANET_CLIENT_ID=${clientId}`);
+  }
   return token;
 }
 
 // ── per-agent install ────────────────────────────────────────────────
 function detect(agent) {
-  const paths = { claude: ['.claude.json', '.claude'], codex: ['.codex'], hermes: ['.hermes'] }[agent] || [];
+  const paths = {
+    claude: ['.claude.json', '.claude'],
+    codex: ['.codex'],
+    hermes: ['.hermes'],
+    openclaw: ['.openclaw'],
+  }[agent] || [];
   return paths.some((p) => existsSync(join(HOME, p)));
 }
 
@@ -399,9 +432,57 @@ async function installHermes(hookPath) {
   }
 }
 
+/**
+ * OpenClaw: rules live in ~/.openclaw/workspace, MCP servers in `mcp.servers` of
+ * ~/.openclaw/openclaw.json — which is exactly the file `openclaw mcp list` reports from.
+ *
+ * This target edits that file instead of shelling out to `openclaw mcp add`, for two reasons
+ * that both showed up as scanner findings on 2026-09-15 (alerts #268/#269):
+ *
+ *  1. The token would be an argv element. Anything on a command line is visible to every
+ *     process on the box (`ps`), and the scanner reads "file-derived value interpolated into a
+ *     spawn call" as shell injection. Writing the same entry the CLI writes is file-to-file,
+ *     which is what this installer already does for ~/.claude.json and ~/.codex/config.toml.
+ *  2. Spawning the CLI meant depending on its local database being writable; in a sandbox it
+ *     answers "Could not start the CLI / attempt to write a readonly database" and the install
+ *     silently needed a human. Reading and writing the config does not.
+ *
+ * The manual `openclaw mcp add …` line is still printed for the user to run themselves — as
+ * text, never executed.
+ */
+async function installOpenclaw(bearer) {
+  const rules = join(HOME, '.openclaw', 'workspace', 'AGENTS.md');
+  const manual = `openclaw mcp add misakanet --url ${ENDPOINT} --transport streamable-http`;
+  if (!existsSync(dirname(rules))) {
+    need(`OpenClaw：找不到 ${dirname(rules)} → 先运行一次 openclaw 生成 workspace`);
+  } else {
+    ok(`OpenClaw：规则块 ${injectBlock(rules, PROMPT_BLOCK)} → ${rules}`);
+  }
+
+  const cfg = join(HOME, '.openclaw', 'openclaw.json');
+  const data = readJson(cfg, null);
+  if (data === null) {
+    need(`OpenClaw：读不到或解析不了 ${cfg} → 先运行一次 openclaw 生成配置，`
+      + `或手动执行 \`${manual}\``);
+    return;
+  }
+  const entry = { url: ENDPOINT, transport: 'streamable-http' };
+  if (bearer) entry.headers = { Authorization: `Bearer ${bearer}` };
+  data.mcp = data.mcp || {};
+  data.mcp.servers = data.mcp.servers || {};
+  if (JSON.stringify(data.mcp.servers.misakanet) === JSON.stringify(entry)) {
+    ok('OpenClaw：MCP 已注册（无改动）');
+    return;
+  }
+  data.mcp.servers.misakanet = entry;
+  backup(cfg);
+  writeText(cfg, `${JSON.stringify(data, null, 2)}\n`);
+  ok(`OpenClaw：注册 MCP（streamable-http）→ ${cfg}`);
+}
+
 async function verify() {
   let allOk = true;
-  const probe = await mcpCall('misakanet_search', { query: 'docker exit code 137', top: 1 }, '', 6000, probeEndpoint());
+  const probe = await mcpCall('misakanet_search', { query: 'docker exit code 137', top: 1 }, 6000, probeEndpoint());
   if (probe && (probe.results || probe.no_match !== undefined)) {
     ok(`端点可达：${ENDPOINT}`);
   } else {
@@ -454,11 +535,34 @@ async function verify() {
     if (!entry) { allOk = false; need(`Claude Code：MCP 未注册（${cfg}）`); }
     else ok(`Claude Code：MCP 已注册（${entry.url}）`);
   }
+  // OpenClaw is only reported when the user actually has it: telling a machine without
+  // OpenClaw that it is "not ready" would be a lie about a target that was never selected.
+  // The state is read from the same file `openclaw mcp list` reports from, which keeps this
+  // check working where the CLI itself cannot start (its database may be unwritable).
+  if (detect('openclaw')) {
+    const rules = join(HOME, '.openclaw', 'workspace', 'AGENTS.md');
+    if (!readText(rules).includes(`<!-- ${START} -->`)) {
+      allOk = false;
+      need(`OpenClaw：规则块没装（${rules}）→ 重跑安装命令`);
+    } else {
+      ok('OpenClaw：规则块已装');
+    }
+    const cfg = join(HOME, '.openclaw', 'openclaw.json');
+    const entry = (readJson(cfg, null) || {}).mcp?.servers?.misakanet;
+    if (!entry) {
+      allOk = false;
+      need(`OpenClaw：MCP 未注册（${cfg}）→ 重跑安装命令，或手动执行 `
+        + `openclaw mcp add misakanet --url ${ENDPOINT} --transport streamable-http`);
+    } else {
+      ok(`OpenClaw：MCP 已注册（${entry.url || '?'}）`);
+    }
+  }
   return allOk;
 }
 
 function uninstall() {
-  for (const rel of ['.claude/CLAUDE.md', '.codex/AGENTS.md', '.hermes/SOUL.md']) {
+  for (const rel of ['.claude/CLAUDE.md', '.codex/AGENTS.md', '.hermes/SOUL.md',
+    '.openclaw/workspace/AGENTS.md']) {
     if (stripBlock(join(HOME, rel))) ok(`移除规则块 → ${rel}`);
   }
   const cfg = join(HOME, '.claude.json');
@@ -504,6 +608,16 @@ function uninstall() {
     ok(`删除状态目录 → ${stateDir()}`);
   }
   need('Hermes 的 MCP 条目由它自己管 → 需要时执行 hermes mcp remove misakanet');
+
+  // OpenClaw's MCP entry is one we wrote ourselves, so we can take it back ourselves.
+  const ocCfg = join(HOME, '.openclaw', 'openclaw.json');
+  const ocData = readJson(ocCfg, null);
+  if (ocData?.mcp?.servers?.misakanet) {
+    delete ocData.mcp.servers.misakanet;
+    backup(ocCfg);
+    writeText(ocCfg, `${JSON.stringify(ocData, null, 2)}\n`);
+    ok(`移除 MCP 注册 → ${ocCfg}`);
+  }
 }
 
 // ── main ─────────────────────────────────────────────────────────────
@@ -548,6 +662,7 @@ if (!targets.length) {
     if (agent === 'claude') await installClaude(hookPath, bearer);
     else if (agent === 'codex') await installCodex(hookPath, bearer);
     else if (agent === 'hermes') await installHermes(hookPath);
+    else if (agent === 'openclaw') await installOpenclaw(bearer);
   }
 }
 

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@misaka-net/misakanet-setup",
-  "version": "0.1.0",
-  "description": "One-command setup: teach your Claude Code / Codex to search MisakaNet failure lessons before repeating a mistake, and to distil the session at a checkpoint.",
+  "version": "0.2.1",
+  "description": "One-command setup: teach your Claude Code / Codex / Hermes / OpenClaw to search MisakaNet failure lessons before repeating a mistake, and to distil the session at a checkpoint.",
   "bin": {
-    "misakanet-setup": "./bin/misakanet-setup.mjs"
+    "misakanet-setup": "bin/misakanet-setup.mjs"
   },
   "type": "module",
   "files": [