@lincoln504/pi-research 1.1.0 → 1.2.0

package/scripts/build.cjs

@@ -106,13 +106,31 @@ const TARGETS = {
     copyWebGpuProbe();
     copyPrompts();
   },
-  skill: () =>
-    esbuild.build({
+  skill: () => {
+    const entry = p('skills', 'pi-research', 'scripts', 'run.ts');
+    const outfile = p('skills', 'pi-research', 'scripts', 'run.mjs');
+    // The published package ships the BUILT run.mjs and deliberately excludes its
+    // run.ts source (package.json "files": "!skills/pi-research/scripts/run.ts"),
+    // yet it also ships prepare.cjs + build.cjs — and `prepare` runs `build.cjs all`.
+    // On any install that executes prepare against the shipped tree (npm install
+    // <dir>, file:, npm link, pi install <dir>) this target had no entry point and
+    // aborted the whole install with "Could not resolve run.ts". Registry .tgz and
+    // npx installs were unaffected only because prepare does not run there.
+    // Nothing to do when the artifact is already present and its source is not.
+    if (!fs.existsSync(entry)) {
+      if (fs.existsSync(outfile)) {
+        console.log('[build] skill: run.ts absent and run.mjs already built (published tree) — skipping');
+        return Promise.resolve();
+      }
+      throw new Error(`[build] skill: neither ${entry} nor a prebuilt ${outfile} exists`);
+    }
+    return esbuild.build({
       ...COMMON,
-      entryPoints: [p('skills', 'pi-research', 'scripts', 'run.ts')],
-      outfile: p('skills', 'pi-research', 'scripts', 'run.mjs'),
+      entryPoints: [entry],
+      outfile,
       banner: { js: SHEBANG },
-    }),
+    });
+  },
 };
 
 // The cli target's copyThreadWorker step depends on the worker output existing,

package/scripts/cleanup.cjs

@@ -1,6 +1,21 @@
 #!/usr/bin/env node
 
-const { execSync } = require('child_process');
+/**
+ * Uninstall-time cleanup: skill links, cache tree, state tree.
+ *
+ * IMPORTANT — this does NOT run on `npm uninstall`. npm removed the
+ * `preuninstall`/`postuninstall` lifecycle for the package being removed in
+ * npm 7; verified against npm 11, where `postinstall` fires on install but
+ * `preuninstall` never fires on uninstall. The `preuninstall` entry in
+ * package.json is retained for package managers that still honour it, but it
+ * must not be treated as the cleanup path.
+ *
+ * The supported paths are `pi-research skill uninstall` (removes the skill
+ * links via the same owned-only manifest logic) and running this script
+ * directly:  node <package-root>/scripts/cleanup.cjs
+ */
+
+const { spawnSync } = require('child_process');
 const { rmSync, existsSync, lstatSync, readlinkSync, readFileSync, writeFileSync, unlinkSync } = require('fs');
 const os = require('os');
 const path = require('path');
@@ -52,7 +67,7 @@ function removeInstalledSkills() {
     if (!owned) { kept.push(e); continue; }
     try {
       if (lstatSync(p).isSymbolicLink()) unlinkSync(p);
-      else rmSync(p, { recursive: true, force: true });
+      else rmSync(p, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 });
       console.log(`pi-research: removed skill install at ${p}`);
     } catch (err) {
       kept.push(e);
@@ -93,8 +108,17 @@ if (process.env.PI_RESEARCH_PURGE_BROWSERS === '1') {
   if (process.env.PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD !== '1') {
     try {
       const bin = resolveCamoufoxBin();
-      const cmd = bin ? `"${bin}" remove` : 'npx camoufox-js remove';
-      execSync(cmd, { stdio: 'inherit' });
+      // Argv array, not a shell string — see the matching note in setup.cjs: `bin`
+      // is derived from the install directory, and a shell string would let a
+      // directory name containing `$(…)` execute at uninstall time.
+      const isWin = process.platform === 'win32';
+      const res = bin
+        ? (isWin
+            ? spawnSync(`"${bin}"`, ['remove'], { stdio: 'inherit', shell: true })
+            : spawnSync(bin, ['remove'], { stdio: 'inherit' }))
+        : spawnSync('npx', ['camoufox-js', 'remove'], { stdio: 'inherit', shell: isWin });
+      if (res.error) throw res.error;
+      if (res.status !== 0) throw new Error(`camoufox remove exited with code ${res.status}`);
       console.log('pi-research: camoufox browser binaries removed.');
     } catch (error) {
       console.warn(`pi-research: could not remove camoufox binaries: ${error instanceof Error ? error.message : String(error)}`);
@@ -109,7 +133,7 @@ if (process.env.PI_RESEARCH_PURGE_BROWSERS === '1') {
 const legacyCacheDir = path.join(projectRoot, '.browser');
 if (existsSync(legacyCacheDir)) {
   try {
-    rmSync(legacyCacheDir, { recursive: true, force: true });
+    rmSync(legacyCacheDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 });
   } catch (error) {
     console.warn(`pi-research: could not remove ${legacyCacheDir}: ${error instanceof Error ? error.message : String(error)}`);
   }
@@ -126,7 +150,7 @@ if (existsSync(legacyCacheDir)) {
 function removeOwnedScratchDir(label, dir) {
   if (!dir || !existsSync(dir)) return;
   try {
-    rmSync(dir, { recursive: true, force: true });
+    rmSync(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 });
     console.log(`pi-research: removed ${label} ${dir}`);
   } catch (error) {
     console.warn(`pi-research: could not remove ${label} ${dir}: ${error instanceof Error ? error.message : String(error)}`);
@@ -136,14 +160,30 @@ function removeOwnedScratchDir(label, dir) {
 // Cache tree: browser profiles, webgpu-viability probe, downloaded embedding models.
 // Same resolution as config.ts (XDG_CACHE_HOME || ~/.cache, then pi-research) on
 // every platform. Shared camoufox binaries live in ~/.cache/camoufox (handled above).
-const cacheHome = process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
+// A RELATIVE XDG_CACHE_HOME is ignored, exactly as embedder-utils.ts does at runtime.
+// Honouring one here would rmSync a cwd-relative `pi-research` tree — deleting whatever
+// happens to sit there — while leaving the real cache untouched. This script's whole job
+// is deletion, so it must not resolve paths more loosely than the code that created them.
+const xdgCache = process.env.XDG_CACHE_HOME;
+const cacheHome = xdgCache && path.isAbsolute(xdgCache) ? xdgCache : path.join(os.homedir(), '.cache');
 removeOwnedScratchDir('cache dir', path.join(cacheHome, 'pi-research'));
 
 // State tree: transient run state, locks, backups, project-settings. Now lives in
 // pi-research's own namespace (~/.pi/research/state), honoring the same overrides
-// as getGlobalConfigDir()/PI_RESEARCH_STATE_DIR.
-const stateDir = process.env.PI_RESEARCH_STATE_DIR
-  || path.join(os.homedir(), process.env.PI_RESEARCH_CONFIG_DIR_NAME || '.pi', 'research', 'state');
+// as getGlobalConfigDir()/PI_RESEARCH_STATE_DIR — with the same strictness the
+// XDG guard above applies. A RELATIVE state dir would rmSync a tree relative to
+// wherever the user happens to invoke this script (generally NOT where the
+// runtime created state), and a config-dir name carrying a path separator could
+// traverse out of HOME entirely. Deletion must never resolve paths more loosely
+// than the code that created them.
+const stateOverride = process.env.PI_RESEARCH_STATE_DIR;
+const rawDirName = process.env.PI_RESEARCH_CONFIG_DIR_NAME;
+const dirName = rawDirName && !rawDirName.includes('/') && !rawDirName.includes('\\') && rawDirName !== '.' && rawDirName !== '..'
+  ? rawDirName
+  : '.pi';
+const stateDir = stateOverride && path.isAbsolute(stateOverride)
+  ? stateOverride
+  : path.join(os.homedir(), dirName, 'research', 'state');
 removeOwnedScratchDir('state dir', stateDir);
 
 process.exit(0);

package/scripts/prepare.cjs

@@ -15,14 +15,24 @@
 
 'use strict';
 
-const { execSync } = require('child_process');
+const { spawnSync } = require('child_process');
 const path = require('path');
 
 const ROOT = path.join(__dirname, '..');
 
-try {
-  execSync('node scripts/build.cjs all', { stdio: 'inherit', cwd: ROOT });
-} catch (err) {
-  console.error('[prepare] Build failed:', err.message);
+// spawnSync with an argv array, not execSync with a quoted string: execSync goes
+// through /bin/sh -c, where $(…), backticks and quotes stay live INSIDE double
+// quotes — so a Node binary path under a directory named with shell metacharacters
+// would execute them during npm ci / a git install. Same fix setup.cjs and
+// cleanup.cjs already carry. process.execPath (not a bare 'node') for the same
+// reason as ensure-native-deps.cjs: a PATH lookup can resolve a different
+// interpreter (nvm-windows, Volta, a portable Node) than the one running npm.
+const r = spawnSync(process.execPath, ['scripts/build.cjs', 'all'], { stdio: 'inherit', cwd: ROOT });
+if (r.error) {
+  console.error('[prepare] Build failed:', r.error.message);
   process.exit(1);
 }
+if (r.status !== 0) {
+  console.error(`[prepare] Build failed with exit code ${r.status}`);
+  process.exit(r.status ?? 1);
+}

package/scripts/setup.cjs

@@ -11,7 +11,7 @@
  *   PLAYWRIGHT_INSTALL_DEPS=true        - also install Linux system deps (or pass --system-deps)
  */
 
-const { execSync } = require('child_process');
+const { execSync, spawnSync } = require('child_process');
 const { existsSync, readdirSync, statSync } = require('fs');
 const { homedir } = require('os');
 const path = require('path');
@@ -95,18 +95,38 @@ if (process.env.PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD === '1') {
   if (!alreadyInstalled) {
     try {
       const bin = resolveCamoufoxBin();
-      const cmd = bin ? `"${bin}" fetch` : 'npx camoufox-js fetch';
+      // spawnSync with an ARGV ARRAY, never a shell string. `bin` is a filesystem
+      // path derived from the install directory, and execSync runs through
+      // `/bin/sh -c` where `$(…)`, backticks and quotes stay live INSIDE double
+      // quotes — so a package installed under a directory whose name contains
+      // shell metacharacters would execute them at install time. Windows still
+      // needs a shell to run the `.cmd` shim, and there the path is quoted; the
+      // runtime twin in ensure-browser.ts uses the same shape.
       // Bound the ~100MB download so a stalled/interrupted network fails fast
       // instead of hanging `npm install` forever (the catch below exits 0, and the
       // browser is re-fetchable manually). 15 min is ample even on slow links.
-      execSync(cmd, { stdio: 'inherit', env, timeout: 15 * 60 * 1000 });
+      const spawnOpts = { stdio: 'inherit', env, timeout: 15 * 60 * 1000 };
+      const res = bin
+        ? (isWindows
+            ? spawnSync(`"${bin}"`, ['fetch'], { ...spawnOpts, shell: true })
+            : spawnSync(bin, ['fetch'], spawnOpts))
+        : spawnSync('npx', ['camoufox-js', 'fetch'], { ...spawnOpts, shell: isWindows });
+      if (res.error) throw res.error;
+      if (res.status !== 0) throw new Error(`camoufox fetch exited with code ${res.status}`);
       browsersInstalled = true;
     } catch (error) {
       const msg = error instanceof Error ? error.message : String(error);
       console.error('ERROR: Camoufox browser install failed — pi-research will not work.');
       console.error('Run manually to fix: npx camoufox-js fetch');
       console.error(`Reason: ${msg}`);
-      process.exit(0);
+      // Exit 0 by default: the browser is fetched lazily on first use, so a restrictive
+      // network must not fail a user's install. But that also meant nothing here could
+      // ever turn CI red — a broken Windows launcher yielded a green `npm ci`. CI sets
+      // PI_RESEARCH_STRICT_SETUP=1 so the platform-specific spawn paths above are
+      // actually enforced somewhere.
+      const strict = process.env.PI_RESEARCH_STRICT_SETUP === '1' ||
+                     process.env.PI_RESEARCH_STRICT_SETUP === 'true';
+      process.exit(strict ? 1 : 0);
     }
   } else {
     browsersInstalled = true;

package/skills/pi-research/README.md

@@ -52,7 +52,13 @@ node "<skill_dir>/scripts/run.mjs" status  # verify detection
 Recommended. From the pi extension, run `/research-config` and choose
 Install in External Agents. It detects Claude, Codex, and OpenClaw and
 symlinks this skill into each one that is installed. Remove from External Agents
-removes those symlinks (cleanup also runs automatically on `npm uninstall`).
+removes those symlinks.
+
+Uninstalling the npm package does **not** remove them: npm 7 and newer do not run a
+package's own `preuninstall` script (verified against npm 11). Use Remove from
+External Agents first, or run `node scripts/cleanup.cjs` from the package directory,
+otherwise the symlinks, `~/.pi/research/state` and the `~/.cache/pi-research` model
+cache are all left behind.
 
 Cursor is not auto-installed — it has no global skills directory and only reads
 project-level `.cursor/skills/`. Symlink it per-project instead (see the table).
@@ -82,7 +88,8 @@ node "<skill_dir>/scripts/run.mjs" status
 ### Files
 
 - `SKILL.md` — the skill definition + system prompt (what agents read).
-- `scripts/run.mjs` — the launcher (compiled from `run.ts`).
+- `scripts/run.mjs` — the launcher (built from `run.ts`, which is a repo-only source
+  file and is not shipped in the npm package).
 - `references/configuration.md` — model/key setup and the full variable reference.
 
 ### License

package/skills/pi-research/SKILL.md

@@ -2,7 +2,7 @@
 name: pi-research
 description: "Multi-agent web research for any coding agent. Use for anything requiring current information from the internet — news, trends, product/service/company facts, statistics, people, places, events, APIs, library behavior, or 'what is X / how does X work' questions. Also use to search a local knowledge store of previously researched findings before doing live research. Powered by the pi-research engine (search, stealth scraping, security databases, Stack Exchange). Not for reading local files, running project commands, or analyzing this repository's own source."
 license: MIT
-metadata: { "author": "Lincoln Deen", "version": "1.1.0", "package": "@lincoln504/pi-research", "engine": "pi-research-sdk", "openclaw": { "requires": { "bins": ["node"] } } }
+metadata: { "author": "Lincoln Deen", "version": "1.2.0", "package": "@lincoln504/pi-research", "engine": "pi-research-sdk", "openclaw": { "requires": { "bins": ["node"] } } }
 allowed-tools: Bash(node:*)
 ---
 
@@ -55,17 +55,20 @@ node "<SKILL_DIR>/scripts/run.mjs" status    [--json]
 - **Cite the report's sources.** Carry its URLs/`[n]` references into your answer;
   attribute each non-trivial claim. Never present researched facts as unsourced;
   never invent or substitute sources.
-- **Surface the saved file.** If stderr/stdout ends with `Research report saved to: <path>`,
-  give the user that exact path. If absent, no file was written — say nothing about one.
+- **Surface the saved file.** Look for a saved-report line: stdout's report footer ends
+  with `Research report saved to: <path>`, and stderr carries `[pi-research] report saved
+  to: <path>`. Give the user that exact path. If neither appears, no file was written —
+  say nothing about one.
 
 ## Exit codes
 
 | Exit | Meaning | Action |
 |------|---------|--------|
 | `0` | Success | Read stdout; cite sources; relay any "saved to: <path>" line. |
-| `78` on `knowledge` | Store disabled/unconfigured | Silent; proceed to `research`. |
+| `78` on `knowledge` | Two cases — **read stderr to tell them apart.** | Says the store is **disabled**: silent; proceed to `research`. Mentions **credentials/model/API key**: this is the same hard config failure as `78` on `research` — **stop and relay full stderr**; don't silently continue, `research` will fail the same way. |
 | `78` on `research` | Engine missing or no model/key | **Stop. Relay full stderr** (it shows where to configure). Don't retry until fixed. |
 | `75` | Machine at capacity — other research runs are already using every slot | **Nothing is broken.** Wait for an in-flight run to finish, then retry this query once. Don't reconfigure anything and don't retry in a tight loop. |
+| `130` (and `129`/`131`/`143`) | Cancelled — the run was interrupted. These are the POSIX `128 + signal` codes: `130` Ctrl-C/SIGINT, `143` SIGTERM, `129` SIGHUP, `131` SIGQUIT. Treat **any exit ≥ 128 as a cancellation.** | **Nothing is broken and nothing failed.** Say the research was cancelled. **Do NOT re-run it** unless the user asks; they stopped it deliberately. |
 | `70` | Runtime error | Relay stderr; suggest one retry for transient failures (network, rate limit). |
 | `64` | Bad arguments | Fix args; don't surface unless the query itself is malformed. |
 
@@ -81,7 +84,7 @@ the new setting. Check the current one first if useful:
 
 ```
 node "<SKILL_DIR>/scripts/run.mjs" knowledge-config                    # current mode + where it's set
-node "<SKILL_DIR>/scripts/run.mjs" knowledge-config set none|project|global
+node "<SKILL_DIR>/scripts/run.mjs" knowledge-config set <none|project|global>   # pick ONE value
 ```
 
 The change applies to the current directory on the next run. Never change it unprompted.

package/skills/pi-research/references/configuration.md

@@ -52,7 +52,7 @@ shared store — the default), `project` (scoped to the current directory), or `
 
 ```sh
 node "<SKILL_DIR>/scripts/run.mjs" knowledge-config                     # current mode + its source
-node "<SKILL_DIR>/scripts/run.mjs" knowledge-config set none|project|global
+node "<SKILL_DIR>/scripts/run.mjs" knowledge-config set <none|project|global>   # pick ONE value
 ```
 
 `set` persists to the per-directory project registry (`~/.pi/research/state/
@@ -62,8 +62,12 @@ outranks both (the command says so when that happens).
 
 ### Exit codes
 
-`0` success · `64` bad arguments · `78` not configured (engine missing or no
-model/key; message lists the fix) · `70` runtime error (network/provider/internal).
+`0` success · `64` bad arguments · `70` runtime error (network/provider/internal) ·
+`75` machine at capacity — every concurrent-run slot is taken; wait and retry once ·
+`78` not configured (engine missing or no model/key; message lists the fix).
+
+A run stopped by a signal exits `128 + N`: `130` Ctrl-C (SIGINT), `143` SIGTERM,
+`129` SIGHUP, `131` SIGQUIT. See SKILL.md for the full table.
 
 ### Troubleshooting
 

package/skills/pi-research/scripts/run.mjs

@@ -3,13 +3,18 @@
 // skills/pi-research/scripts/run.ts
 import { spawn } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
-import { homedir } from "node:os";
+import { homedir, constants as osConstants } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 var PKG = "@lincoln504/pi-research";
 var REQUIRED_DEP = "@earendil-works/pi-coding-agent";
-var EXIT = { OK: 0, USAGE: 64, CONFIG: 78, SOFTWARE: 70 };
+var EXIT = { OK: 0, USAGE: 64, CONFIG: 78, SOFTWARE: 70, CANCELLED: 130 };
+var CANCELLING_SIGNALS = /* @__PURE__ */ new Set(["SIGINT", "SIGTERM", "SIGHUP", "SIGQUIT"]);
+function exitCodeForSignal(sig) {
+  const signum = osConstants.signals[sig];
+  return typeof signum === "number" ? 128 + signum : EXIT.CANCELLED;
+}
 var argv = process.argv.slice(2);
 var subcommand = argv[0];
 if (!subcommand || subcommand === "-h" || subcommand === "--help" || subcommand === "help") {
@@ -199,6 +204,17 @@ Set PI_RESEARCH_BIN to the engine's node CLI (\u2026\\dist\\cli.mjs) or PI_RESEA
       ...useShell ? { shell: true } : {}
     }
   );
+  for (const sig of CANCELLING_SIGNALS) {
+    try {
+      process.on(sig, () => {
+        try {
+          child.kill(sig);
+        } catch {
+        }
+      });
+    } catch {
+    }
+  }
   child.on("error", (err) => {
     process.stderr.write(`
 Error: failed to launch pi-research (${engine2.label}): ${err.message}
@@ -207,6 +223,12 @@ Error: failed to launch pi-research (${engine2.label}): ${err.message}
   });
   child.on("exit", (code, signal) => {
     if (signal) {
+      if (CANCELLING_SIGNALS.has(signal)) {
+        process.stderr.write(`
+pi-research cancelled (${signal}).
+`);
+        process.exit(exitCodeForSignal(signal));
+      }
       process.stderr.write(`
 Error: pi-research killed by ${signal}
 `);