@nailuogg/pi-find-packages 0.1.3 → 0.1.4

package/README.md

@@ -7,7 +7,7 @@ A [pi](https://pi.dev) extension providing a local catalog of the pi package eco
 - **Offline catalog**: syncs the full `keywords:pi-package` corpus (~5k+ packages) from npm to local JSONL; search with jq/grep over descriptions, names, and keywords — no dependence on npm's keyword-matched search
 - **`/find-packages <need>`**: retrieve candidates → read-only source analysis in a sandbox → comparison table and recommendation against criteria (feature overlap / peer compatibility / maintenance activity / supply-chain signals)
 - **Cold start**: the package ships a bundled catalog snapshot (`data/catalog.jsonl.gz`); install and use immediately with zero network requests on first run
-- **Docker isolation by default**: candidate repos are cloned and unpacked inside a credential-free, non-root container; isolation can be disabled explicitly (a risk warning is shown on every use — not recommended)
+- **Docker isolation by default**: candidate repos are fetched and unpacked inside a credential-free, non-root container (read-only root, no capabilities, no-new-privileges, tmpfs work dirs; no host source mount); isolation can be disabled explicitly (a risk warning is shown on every use — not recommended)
 
 ## Install
 
@@ -39,9 +39,7 @@ qmd collection add "$HOME/.pi/agent/data/pi-find-packages/readmes" --name pi-pkg
 qmd collection show pi-pkg-readmes   # confirm the path matches your data directory
 ```
 
-Substitute your real data directory when `PI_CODING_AGENT_DIR` is set. Afterwards
-`/find-packages` keeps the corpus current on its own: each reviewed candidate's README is
-saved into `readmes/` and indexed with `qmd update && qmd embed`.
+Substitute your real data directory when `PI_CODING_AGENT_DIR` is set. Afterwards `/find-packages` uses qmd results only as leads: verify each candidate against its current npm version and the cached README's first line, then overwrite that README after review and index with `qmd update && qmd embed`. It does not bulk-update READMEs.
 
 ## Refreshing the catalog
 
@@ -69,7 +67,7 @@ the latest npm publish and therefore updates on release cadence.
 docker build -t pi-find-packages-analysis -f docker/Dockerfile.analysis docker
 ```
 
-The image contains no pi and no credentials: it exists solely to clone/unpack/read third-party source. Never execute a candidate package's install scripts or build artifacts in any environment.
+The image contains no pi and no credentials: it exists solely to fetch, verify, unpack and read third-party source. Runtime must use a read-only root, `--cap-drop=ALL`, `--security-opt=no-new-privileges`, the non-root analyst user, and tmpfs `/analysis` and `/tmp` mounts (`mode=1777`); never bind-mount candidate source from the host. Allow required npm registry/GitHub access. Only analysis text returns to the host. Never execute a candidate package's install scripts or build artifacts in any environment.
 
 ## Releasing
 

package/extensions/find-packages.ts

@@ -36,7 +36,14 @@ export default function activate(pi: ExtensionAPI) {
     mkdirSync(dataDir, { recursive: true });
     if (existsSync(bundled)) {
       writeFileSync(catalog, gunzipSync(readFileSync(bundled)));
-      pi.appendEntry("find-packages", { event: "cold-start-extract", from: bundled });
+      // pi only accepts registration calls while a factory runs; action methods
+      // such as appendEntry throw until pi commits the extension, and a throw here
+      // makes pi reject the whole extension (breaking every first run). Pure fs work
+      // is fine, so the audit entry is deferred to a session event instead.
+      const extracted = { event: "cold-start-extract", from: bundled };
+      pi.on("session_start", () => {
+        pi.appendEntry("find-packages", extracted);
+      });
     }
   }
 
@@ -171,18 +178,14 @@ export default function activate(pi: ExtensionAPI) {
         `**${query}**`,
         "",
         "Steps:",
-        "1. Search: run multiple jq/grep keyword passes over `" + catalog + "` against description/keywords/name, trying synonyms as needed; "
-        + (semanticEnabled()
-            ? "also run `qmd query --collection pi-pkg-readmes` for semantic search over cached READMEs (skip if empty); "
-            : "")
-        + "pick the 3-5 most relevant candidates.",
-        "2. Review each candidate: `npm view <pkg>` for version/deps/peer, plus the README and registry metadata on the host; judge maintenance activity, dependency surface, and supply-chain signals. Any cloning or unpacking of candidate source happens in step 3's sandbox only — never fetch candidate source on the host. "
-        + "After reviewing, save the package README to `" + join(dataDir, "readmes") + "/<name with / replaced by __>.md` (first line `# <name> <version> <date>`) "
-        + (semanticEnabled() ? "then refresh the semantic index with `qmd update && qmd embed`" : "") + ".",
+        `1. Search: run multiple jq/grep keyword passes over \`${catalog}\` against description/keywords/name, trying synonyms as needed; `
+        + (semanticEnabled() ? "also run `qmd query --collection pi-pkg-readmes` for semantic search over cached READMEs (skip if empty); " : "")
+        + `for broad jq searches, count matches first, then narrow terms or page results; never shortlist from truncated output. ${semanticEnabled() ? "Treat qmd hits only as leads: verify the current npm version against the cached README's first line, then after review overwrite that README with the verified version/date and run `qmd update && qmd embed`; never bulk-update. " : ""}Pick the 3-5 most relevant candidates.`,
+        `2. Review each candidate: npm view <pkg> for version/deps/peer, plus the README and registry metadata on the host; judge maintenance activity, dependency surface, and supply-chain signals. Any cloning or unpacking of candidate source happens in step 3's sandbox only — never fetch candidate source on the host. Save the reviewed README to \`${join(dataDir, "readmes")}/<name with / replaced by __>.md\` (first line \`# <name> <version> <date>\`)${semanticEnabled() ? " and refresh the semantic index with qmd update && qmd embed" : ""}.`,
         `3. Execution environment: ${iso === "docker"
-          ? "all cloning/unpacking/source analysis must run inside the Docker container (see " + join(pkgDir, "docker/Dockerfile.analysis") + "); the host only receives analysis text; never run a candidate's install scripts."
+          ? "All source analysis must run inside the Docker container with --read-only --cap-drop=ALL --security-opt=no-new-privileges, as the image's non-root analyst user, and tmpfs mounts for /analysis and /tmp with mode=1777 (no host candidate-source bind mount). Allow network access needed for npm registry/GitHub. Fetch, verify, unpack and analyze candidate source only inside the container; only analysis text may reach the host. Never run candidate scripts or build artifacts."
           : "not isolated — analyze read-only on the host (see the risk note above)."}`,
-        "4. Criteria: feature overlap with the current setup / installed packages (Unix philosophy: features must not cross); pi compatibility (peer ranges); maintenance activity; dependency and supply-chain safety.",
+        "4. Criteria: feature overlap with the current setup / installed packages (Unix philosophy: features must not cross); pi compatibility (check actual pi --version and the candidate peer range; note installed package-directory versus running-version drift rather than treating drift alone as incompatibility); maintenance activity; dependency and supply-chain safety.",
         "5. Output: a candidate comparison table (name/version/activity/fit/risk) + a clear recommendation with reasons. The analysis report is not install authorization — I decide whether to integrate.",
         riskNote,
       ].filter(Boolean).join("\n");

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@nailuogg/pi-find-packages",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Local catalog of the pi package ecosystem with /find-packages: offline search, cold-start data, and sandboxed source analysis for integration review",
   "type": "module",
+  "scripts": {
+    "test": "node --test"
+  },
   "keywords": [
     "pi-package",
     "pi",

package/skills/find-packages/SKILL.md

@@ -48,6 +48,8 @@ jq -r 'select((.name + " " + (.description // "") + " " + ((.keywords // [])|joi
   | [.name, .version, (.publisher // ""), .date] | @tsv' "$CAT"
 ```
 
+For broad searches, count matches first, then narrow the terms or page through results. Never choose a shortlist from truncated output.
+
 Expected output — tab-separated, one candidate per line:
 
 ```text
@@ -60,7 +62,7 @@ Expected output — tab-separated, one candidate per line:
 **Semantic search (optional).** Only when `qmd` is installed and `semantic` is not `"off"` — see
 Configuration. It searches cached READMEs of previously reviewed packages only, so check the collection
 first and skip semantic search while it is empty — `qmd query` spends an LLM expansion pass per call,
-`qmd ls` is free:
+`qmd ls` is free. Treat results only as leads; verify current facts against npm:
 
 ```bash
 qmd ls pi-pkg-readmes                                  # "No files found" → skip
@@ -89,15 +91,30 @@ Run every candidate through all four checks; record the evidence for each one.
 | Check | How to verify | Verdict |
 |---|---|---|
 | **Feature overlap** (hard rule) | Compare against pi built-ins and the packages installed in the `packages` array of `$PI_CODING_AGENT_DIR/settings.json` and of the project `.pi/settings.json` | Any overlap → recommend against, whatever the other checks say |
-| **pi compatibility** | `npm view <pkg> peerDependencies` | Peer range must cover the current pi version |
+| **pi compatibility** | Check actual `pi --version` and `npm view <pkg> peerDependencies` | Compare the peer range with the running version. If the installed package-directory copy reports another version, record that drift; do not call it incompatible on drift alone |
 | **Maintenance activity** | Catalog `date` (last publish) plus the last commit in `repo` | Stale on both → note as risk, not a blocker |
 | **Supply chain** | `npm view <pkg> maintainers dependencies scripts` | Flag `install`/`preinstall` scripts, large dependency trees, and any path that sends data off-host |
 
 ## 4. Analyze sources in the sandbox
 
 Source analysis runs in Docker by default, using `../../docker/Dockerfile.analysis` (node24-slim + git +
-ripgrep, no credentials). Clone, unpack and read candidate code **inside the container**; only analysis
-text reaches the host.
+ripgrep, no credentials). Do not mount candidate source from the host. Run read-only with
+`--cap-drop=ALL --security-opt=no-new-privileges`, as the non-root analyst user, and tmpfs mounts for
+`/analysis` and `/tmp` with `mode=1777`. Allow network access needed for npm registry/GitHub. Fetch,
+verify, unpack and read candidate code **inside the container**; only analysis text reaches the host.
+
+Before analysis, replace `<image>` with the built analysis image name and run this preflight to confirm
+non-root execution and writable workdirs:
+
+```bash
+docker run --rm --read-only --cap-drop=ALL --security-opt=no-new-privileges \
+  --tmpfs /analysis:rw,mode=1777 --tmpfs /tmp:rw,mode=1777 \
+  <image> -c 'test "$(id -u)" -ne 0 && touch /analysis/.probe /tmp/.probe'
+```
+
+This preflight only checks the runtime. Fetching candidate source, verifying its integrity, and
+unpacking it must still happen inside a container with the same security options; never bind-mount
+candidate source from the host.
 
 **Never execute a candidate's install scripts or build artifacts** — not on the host and not in the
 container. Reading `package.json`, the README or registry metadata needs no container, so shallow
@@ -119,9 +136,10 @@ Compare the shortlist in a table, then give one recommendation with reasons:
 
 ## README cache
 
-After reviewing a candidate, save its README to
-`<catalog dir>/readmes/<name with / replaced by __>.md`, first line `# <name> <version> <date>`, then
-refresh the semantic index:
+After reviewing a candidate, verify the current npm version and compare it with the first line of any
+cached README; qmd hits are leads only. Overwrite that candidate's README at
+`<catalog dir>/readmes/<name with / replaced by __>.md`, first line `# <name> <verified version> <date>`,
+then refresh the semantic index. Never bulk-update README files:
 
 ```bash
 qmd update && qmd embed