@lincoln504/pi-research 1.7.5 → 1.7.6

package/agent-skill/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.7.5", "package": "@lincoln504/pi-research", "engine": "pi-research-sdk", "openclaw": { "requires": { "bins": ["node"] } } }
+metadata: { "author": "Lincoln Deen", "version": "1.7.6", "package": "@lincoln504/pi-research", "engine": "pi-research-sdk", "openclaw": { "requires": { "bins": ["node"] } } }
 allowed-tools: Bash(node:*)
 ---
 

package/dist/cli-bin.mjs

@@ -34,24 +34,62 @@
  * the user reached for.
  */
 
+import { existsSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 
 const REQUIRED_PEERS = ['@earendil-works/pi-ai', '@earendil-works/pi-coding-agent'];
 
-const missing = REQUIRED_PEERS.filter((name) => {
+/**
+ * Probe one peer dependency.
+ *
+ *   'ok'      — resolves, and the file it resolves to exists
+ *   'missing' — does not resolve at all (the --legacy-peer-deps case)
+ *   'broken'  — resolves (its package.json and exports map are readable) but the
+ *               file those point at is not on disk
+ *
+ * The 'broken' case is checked with existsSync rather than by importing the
+ * module. Resolving is not loading: an interrupted install, a pruned
+ * node_modules or a bad package-cache restore leaves a package that resolves
+ * perfectly and then fails to load, which would pass this preflight and die
+ * inside cli.mjs with the same raw ERR_MODULE_NOT_FOUND this shim exists to
+ * replace. Importing it here instead would work, but it runs the host
+ * package's module side effects before the CLI proper has decided to start, so
+ * the cheap existence check is the right trade.
+ *
+ * @returns {'ok' | 'missing' | 'broken'}
+ */
+function probePeer(name) {
+  let resolved;
   try {
-    import.meta.resolve(name);
-    return false;
+    resolved = import.meta.resolve(name);
   } catch {
-    return true;
+    return 'missing';
   }
-});
+  try {
+    return existsSync(fileURLToPath(resolved)) ? 'ok' : 'broken';
+  } catch {
+    // Resolved to something fileURLToPath cannot turn into a path (not a file:
+    // URL). It resolved, so treat it as present rather than inventing a failure.
+    return 'ok';
+  }
+}
+
+const status = new Map(REQUIRED_PEERS.map((name) => [name, probePeer(name)]));
+const missing = REQUIRED_PEERS.filter((name) => status.get(name) === 'missing');
+const broken = REQUIRED_PEERS.filter((name) => status.get(name) === 'broken');
 
-if (missing.length > 0) {
+if (missing.length > 0 || broken.length > 0) {
+  // The remedy names the packages that are ACTUALLY absent. It used to hardcode
+  // `npm install -g @earendil-works/pi-coding-agent` with the comment "add just
+  // the missing host package", which was wrong whenever pi-ai was the missing
+  // one: the instruction named a package the user already had, and following it
+  // changed nothing. Reported by review 2026-10-01.
+  const needsInstall = [...missing, ...broken];
   const lines = [
     '',
     'Error: pi-research cannot start — it is missing required runtime dependencies:',
     ...missing.map((name) => `    ${name}`),
+    ...broken.map((name) => `    ${name}  (installed, but its files are incomplete)`),
     '',
     'These are PEER dependencies. pi provides its own copies when it loads this',
     'package as an extension, and npm >= 7 installs them automatically for a',
@@ -59,10 +97,11 @@ if (missing.length > 0) {
     'what --legacy-peer-deps, yarn classic, and a pnpm config with',
     'auto-install-peers=false do.',
     '',
-    'Either of these fixes it:',
+    'Install the missing package(s), or reinstall this package, which resolves',
+    'them as peers:',
     '',
-    '    npm install -g @earendil-works/pi-coding-agent   # add just the missing host package',
-    '    npm install -g @lincoln504/pi-research           # or reinstall, resolving peers',
+    `    npm install -g ${needsInstall.join(' ')}`,
+    '    npm install -g @lincoln504/pi-research',
     '',
   ];
   process.stderr.write(lines.join('\n'));

package/docs/CHANGELOG.md

@@ -5,6 +5,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.7.6] - 2026-10-01
+
+### Fixed
+
+- **The missing-peer remedy names the package that is actually missing.** The 1.7.5 shim's bullet list correctly enumerated every absent `@earendil-works/pi-*` package, but the command underneath it was hardcoded to `npm install -g @earendil-works/pi-coding-agent` with the comment "add just the missing host package". When `pi-ai` (and not `pi-coding-agent`) was the absent one, the instruction named a package the user already had and following it changed nothing. The remedy is now built from the detected set, so both peers are named when both are missing and only the absent one is named otherwise. Caught in review; pinned by a test that asserts the present package is never the one the remedy suggests installing.
+- **The bin preflight detects an install whose files are incomplete, not just an absent package.** It resolved each peer and treated a successful resolve as healthy. Resolving is not loading: an interrupted install, a pruned `node_modules` or a bad package-cache restore leaves `package.json` and its `exports` map intact with the file they point at gone, so the preflight passed it through and the bundle died on that import with the raw `ERR_MODULE_NOT_FOUND` the shim exists to replace. The preflight now also checks that the resolved file exists and reports `installed, but its files are incomplete` with the same exit 78. Checked with `existsSync` rather than by importing the module, which would run the host packages' side effects before the CLI has decided to start. Verified by reverting each half in isolation: without the `argv[1]` rewrite the stub engine exits 97, with a resolve-only preflight a deliberately truncated peer produces `ERR_MODULE_NOT_FOUND`, and the fixed shim produces exit 78.
+- **`dist/cli-bin.mjs` ships executable.** It was published at mode 644 against 755 for `dist/cli.mjs`, because the build copies it with `copyFileSync`, which preserves the committed source mode. Every package manager chmods the declared `bin` target itself, so no install was broken, but the shipped artifact should not depend on that. The build now chmods 755 and the source is committed executable.
+
 ## [1.7.5] - 2026-10-01
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lincoln504/pi-research",
-  "version": "1.7.5",
+  "version": "1.7.6",
   "description": "Web research for your agents with smart and safe tooling + knowledge store",
   "type": "module",
   "private": false,

package/scripts/build.cjs

@@ -57,6 +57,14 @@ function copyWebGpuProbe() {
 function copyCliBin() {
   fs.mkdirSync(p('dist'), { recursive: true });
   fs.copyFileSync(p('src', 'cli-bin.mjs'), p('dist', 'cli-bin.mjs'));
+  // copyFileSync preserves the SOURCE mode. The source is committed executable
+  // (100755) so this is belt-and-braces, but nothing about the shipped bin should
+  // depend on the source file's mode or on the umask of whatever builds it. The
+  // bin is what the OS executes, so ship it executable like dist/cli.mjs: every
+  // package manager does its own chmod on the declared bin target, but nothing
+  // should depend on that. (Flagged in review 2026-10-01: the packed 1.7.5 tarball
+  // had dist/cli.mjs at 755 and dist/cli-bin.mjs at 644.)
+  fs.chmodSync(p('dist', 'cli-bin.mjs'), 0o755);
 }
 
 // Build the browser worker bundle. Factored out so the cli target can guarantee

package/src/cli-bin.mjs

@@ -34,24 +34,62 @@
  * the user reached for.
  */
 
+import { existsSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 
 const REQUIRED_PEERS = ['@earendil-works/pi-ai', '@earendil-works/pi-coding-agent'];
 
-const missing = REQUIRED_PEERS.filter((name) => {
+/**
+ * Probe one peer dependency.
+ *
+ *   'ok'      — resolves, and the file it resolves to exists
+ *   'missing' — does not resolve at all (the --legacy-peer-deps case)
+ *   'broken'  — resolves (its package.json and exports map are readable) but the
+ *               file those point at is not on disk
+ *
+ * The 'broken' case is checked with existsSync rather than by importing the
+ * module. Resolving is not loading: an interrupted install, a pruned
+ * node_modules or a bad package-cache restore leaves a package that resolves
+ * perfectly and then fails to load, which would pass this preflight and die
+ * inside cli.mjs with the same raw ERR_MODULE_NOT_FOUND this shim exists to
+ * replace. Importing it here instead would work, but it runs the host
+ * package's module side effects before the CLI proper has decided to start, so
+ * the cheap existence check is the right trade.
+ *
+ * @returns {'ok' | 'missing' | 'broken'}
+ */
+function probePeer(name) {
+  let resolved;
   try {
-    import.meta.resolve(name);
-    return false;
+    resolved = import.meta.resolve(name);
   } catch {
-    return true;
+    return 'missing';
   }
-});
+  try {
+    return existsSync(fileURLToPath(resolved)) ? 'ok' : 'broken';
+  } catch {
+    // Resolved to something fileURLToPath cannot turn into a path (not a file:
+    // URL). It resolved, so treat it as present rather than inventing a failure.
+    return 'ok';
+  }
+}
+
+const status = new Map(REQUIRED_PEERS.map((name) => [name, probePeer(name)]));
+const missing = REQUIRED_PEERS.filter((name) => status.get(name) === 'missing');
+const broken = REQUIRED_PEERS.filter((name) => status.get(name) === 'broken');
 
-if (missing.length > 0) {
+if (missing.length > 0 || broken.length > 0) {
+  // The remedy names the packages that are ACTUALLY absent. It used to hardcode
+  // `npm install -g @earendil-works/pi-coding-agent` with the comment "add just
+  // the missing host package", which was wrong whenever pi-ai was the missing
+  // one: the instruction named a package the user already had, and following it
+  // changed nothing. Reported by review 2026-10-01.
+  const needsInstall = [...missing, ...broken];
   const lines = [
     '',
     'Error: pi-research cannot start — it is missing required runtime dependencies:',
     ...missing.map((name) => `    ${name}`),
+    ...broken.map((name) => `    ${name}  (installed, but its files are incomplete)`),
     '',
     'These are PEER dependencies. pi provides its own copies when it loads this',
     'package as an extension, and npm >= 7 installs them automatically for a',
@@ -59,10 +97,11 @@ if (missing.length > 0) {
     'what --legacy-peer-deps, yarn classic, and a pnpm config with',
     'auto-install-peers=false do.',
     '',
-    'Either of these fixes it:',
+    'Install the missing package(s), or reinstall this package, which resolves',
+    'them as peers:',
     '',
-    '    npm install -g @earendil-works/pi-coding-agent   # add just the missing host package',
-    '    npm install -g @lincoln504/pi-research           # or reinstall, resolving peers',
+    `    npm install -g ${needsInstall.join(' ')}`,
+    '    npm install -g @lincoln504/pi-research',
     '',
   ];
   process.stderr.write(lines.join('\n'));