@nailuogg/pi-find-packages 0.1.1 → 0.1.3

package/README.md

@@ -21,10 +21,27 @@ pi install /path/to/pi-find-packages   # local trial
 
 `<PI_CODING_AGENT_DIR>/data/pi-find-packages/` (default `~/.pi/agent/data/pi-find-packages/`)
 
-- `catalog.jsonl` — catalog data (one package per line: name/version/description/date/author/keywords/repo)
+- `catalog.jsonl` — catalog data (one package per line: name/version/description/date/author/publisher/keywords/repo)
 - `config.json` — `{"isolation": "docker" | "off", "semantic": "auto" | "on" | "off"}`
   - `isolation` defaults to `docker` (sandboxed source analysis)
   - `semantic` controls semantic search over lazily-cached READMEs (via [qmd](https://github.com/tobi/qmd)); defaults to `auto`: enabled automatically when the `qmd` binary is present, force with `"on"`, disable with `"off"`
+- `readmes/` — READMEs of reviewed candidates, the corpus behind semantic search (see below)
+
+## Semantic search setup (optional)
+
+Semantic search reads a qmd collection named `pi-pkg-readmes`, pointed at the `readmes/`
+directory above. Nothing in this package registers that collection, and qmd does not create
+it on demand: an unregistered directory simply stays empty, so semantic search degrades to
+lexical search with no error. Register it once:
+
+```bash
+qmd collection add "$HOME/.pi/agent/data/pi-find-packages/readmes" --name pi-pkg-readmes
+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`.
 
 ## Refreshing the catalog
 
@@ -58,8 +75,10 @@ The image contains no pi and no credentials: it exists solely to clone/unpack/re
 
 Publishing is automated: push a tag `v<version>` matching `package.json`, and the
 `publish.yml` workflow verifies the version, publishes `@nailuogg/pi-find-packages`
-to npm, and creates a GitHub release. The `NPM_TOKEN` repository secret must hold a
-granular npm access token scoped to the `@nailuogg` packages (npmjs.com → Access Keys).
+to npm, and creates a GitHub release. Publishing uses npm **Trusted Publishing (OIDC)**: the package's npm settings list
+this repository and `publish.yml` as a trusted publisher, so CI authenticates with a
+short-lived OIDC token — no `NPM_TOKEN` secret involved. Requires the workflow to run
+with `id-token: write` (set) and npm >= 11.5.1 (the workflow installs the latest npm).
 
 ## Security boundaries
 

package/extensions/find-packages.ts

@@ -163,7 +163,7 @@ export default function activate(pi: ExtensionAPI) {
               "",
               "⚠️ **Isolation disabled (isolation: off)**: candidate source will be cloned/unpacked on the host.",
               "Third-party packages may contain malicious install scripts or build logic; host-side analysis is not sandboxed.",
-              "This mode is not recommended. Delete data/pi-find-packages/config.json or set isolation:\"docker\" to restore the default.",
+              "This mode is not recommended. Delete " + configFile + " or set isolation:\"docker\" to restore the default.",
             ].join("\n")
           : "";
       const prompt = [
@@ -171,15 +171,17 @@ export default function activate(pi: ExtensionAPI) {
         `**${query}**`,
         "",
         "Steps:",
-        "1. Search: run multiple jq/grep keyword passes over `~/.pi/agent/data/pi-find-packages/catalog.jsonl` against description/keywords/name, trying synonyms as needed; "
+        "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 (read-only): `npm view <pkg>` for version/deps/peer; clone or download source via the repo link; read entry points, extension points, and the README; judge maintenance activity, dependency surface, and supply-chain signals. "
-        + "After reviewing, save the package README to `~/.pi/agent/data/pi-find-packages/readmes/<name with / replaced by __>.md` (first line `# <name> <version> <date>`)"
-        + (semanticEnabled() ? ", then run `qmd index pi-pkg-readmes` to update the index" : "") + ".",
-        `3. Execution environment: ${iso === "docker" ? "all cloning/unpacking/source analysis must run inside the Docker container (see docker/Dockerfile.analysis); the host only receives analysis text; never run a candidate's install scripts." : "not isolated — analyze read-only on the host (see the risk note above)."}`,
+        "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`" : "") + ".",
+        `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."
+          : "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.",
         "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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nailuogg/pi-find-packages",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "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",
   "keywords": [
@@ -37,5 +37,14 @@
   },
   "publishConfig": {
     "access": "public"
-  }
+  },
+  "files": [
+    "extensions/",
+    "skills/",
+    "scripts/",
+    "data/",
+    "docker/",
+    "README.md",
+    "LICENSE"
+  ]
 }

package/skills/find-packages/SKILL.md

@@ -1,37 +1,162 @@
-# find-packages: pi package catalog search & integration review
+---
+name: find-packages
+description: >-
+  Search a local offline catalog of the pi package ecosystem (npm keywords:pi-package) and review a
+  candidate package before installing it. Use when the user wants to find, compare, or evaluate a pi
+  package, extension, or skill to install: lexical and semantic catalog search over cached READMEs,
+  catalog refresh when stale, and a fixed integration review (feature overlap with pi built-ins and
+  installed packages, peer compatibility, maintenance activity, supply chain) plus sandboxed Docker
+  source analysis.
+license: MIT
+compatibility: >-
+  Requires jq, node >= 22 and npm; docker for source analysis; network access for catalog refresh and
+  npm view. qmd is optional and only enables semantic search over cached READMEs. POSIX shell assumed.
+---
 
-Maintains a local catalog of the pi package ecosystem (same source as pi.dev/packages: npm `keywords:pi-package`) for offline/semantic package discovery, plus a standard integration-evaluation workflow.
+# find-packages
 
-## Data
+Find pi packages in a local, offline catalog of the pi ecosystem (npm `keywords:pi-package`) and review
+a candidate before it gets installed. Search is lexical (`jq`), optionally semantic; review is a fixed
+rubric with sandboxed Docker source analysis.
 
-- Catalog file: `~/.pi/agent/data/pi-find-packages/catalog.jsonl` (one package per line: name/version/description/date/author/keywords/npm/repo)
-- Refresh (pick the first that works):
-  1. `/find-packages update` — pulls the latest snapshot from the jsDelivr `data` branch (falls back to the npmmirror tarball of the latest published version); checksum-verified, atomic replace
-  2. `node <package-dir>/scripts/sync-catalog.mjs` — full rebuild from the npm registry search API (~40 requests). Only run when the file is older than 30 days or the user asks; avoid hammering the registry.
+Catalog: `${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}/data/pi-find-packages/catalog.jsonl` — one JSON object
+per line, with fields `name`, `version`, `description`, `date` (last publish), `author` (frequently
+empty), `publisher` (use this as the maintainer), `keywords`, `npm`, `repo`, `homepage`. The same
+directory holds `config.json` and the `readmes/` cache.
 
-## Search methods
+Throughout this file, paths are relative to this skill directory; `../../` is the package root.
 
-1. Lexical: `jq -r 'select(.description|test("keyword";"i")) | [.name,.version,.description] | @tsv' catalog.jsonl` — try multiple synonym groups (English-first; cover channel words like remote/telegram/discord/web).
-2. Semantic (optional): `qmd query --collection pi-pkg-readmes "need description"` — searches cached READMEs of previously reviewed packages (grows over time; skip when the cache is empty). Only use when the `qmd` binary is available and not disabled via `"semantic":"off"` in `config.json`; otherwise skip this step and rely on lexical search.
-3. When both come up empty, fall back to `npm search` and note the catalog may be stale.
+## Workflow
 
-## README cache (written as a side effect of review)
+1. **Search** the catalog for candidates — §1.
+2. **Shortlist** the 3–5 closest matches.
+3. **Review** each candidate against the rubric — §3. Feature overlap is a hard rule.
+4. **Analyze sources** inside the Docker sandbox when the review needs code-level evidence — §4.
+5. **Report** a comparison table plus a recommendation — §5.
 
-After reviewing a candidate, save its README to `~/.pi/agent/data/pi-find-packages/readmes/<name with / replaced by __>.md`, first line `# <name> <version> <date>`; then run `qmd index pi-pkg-readmes` to update the index. **Never bulk-fetch all READMEs** — the corpus grows with real reviews.
+Complete the steps in order; never skip the overlap check in step 3.
 
-## Integration review (check every candidate)
+## 1. Search the catalog
 
-- **Feature overlap**: does it overlap installed packages (`packages` arrays in `~/.pi/agent/settings.json` and the project `.pi/settings.json`) or pi built-ins? No overlap is a hard rule.
-- **Compatibility**: does `npm view <pkg> peerDependencies` cover the current pi version?
-- **Activity**: latest publish date, latest repo commit.
-- **Supply chain**: author/maintainers, dependency count, install/preinstall scripts in package.json, any data-exfiltration paths.
+Run one pass per synonym group, English first, and always include channel/transport words
+(remote, telegram, discord, web, vnc) when the need is about access or reach:
 
-## Execution environment
+```bash
+CAT="${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}/data/pi-find-packages/catalog.jsonl"
+jq -r 'select((.name + " " + (.description // "") + " " + ((.keywords // [])|join(" ")))
+  | test("remote|telegram|discord";"i"))
+  | [.name, .version, (.publisher // ""), .date] | @tsv' "$CAT"
+```
 
-- **Source analysis must run inside Docker by default** (clone/unpack candidate code via `docker/Dockerfile.analysis`: node24-slim + git + ripgrep, no credentials). The host only receives analysis text. **Never execute a candidate's install scripts or build artifacts.**
-- `"isolation":"off"` in `data/pi-find-packages/config.json` disables isolation — a risk warning is shown on every use; not recommended.
-- Shallow lookups (`npm view`, registry JSON) do not need the container.
+Expected output — tab-separated, one candidate per line:
 
-## Output convention
+```text
+@99percentpeople/pi-ssh-remote	0.6.2	GitHub Actions	2026-09-08T08:29:12.985Z
+@bacnh85/pi-a2a	0.7.11	bacnh85	2026-09-21T03:51:02.441Z
+```
 
-Candidate comparison table (name/version/last publish/activity/fit/risk) + a clear recommendation with reasons. **An analysis report is not install authorization** — the user decides whether to `pi install`.
+`.description` and `.keywords` can be `null`, hence the `// ""` guards. Keep `test()` case-insensitive.
+
+**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:
+
+```bash
+qmd ls pi-pkg-readmes                                  # "No files found" → skip
+qmd query --collection pi-pkg-readmes "<one sentence>"
+```
+
+**When both come up empty**, fall back to `npm search` and say in the report that the catalog may be
+stale.
+
+## 2. Refresh the catalog
+
+Refresh only when the catalog is missing, older than 30 days (`find "$CAT" -mtime +30`), or the user
+asks. Avoid hammering the registry.
+
+1. `/find-packages update` — the command provided by this package's extension. Pulls the snapshot from
+   the jsDelivr `data` branch (checksum-verified against the published `.sha256`), then falls back to
+   the npmmirror tarball of the latest published version.
+2. Last resort, when both CDNs fail: run `node ../../scripts/sync-catalog.mjs` to rebuild the catalog
+   locally from the npm registry search API (~40 requests). It writes `catalog.jsonl`, its `.gz` and
+   `.sha256` into the catalog directory; CI invokes the same script with `--out <dir>`.
+
+## 3. Integration review
+
+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 |
+| **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.
+
+**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
+lookups stay on the host.
+
+`isolation: "off"` in `config.json` disables isolation and moves analysis to the host; every use shows a
+risk warning. Do not recommend it, and do not fall back to host-side analysis on your own when Docker is
+unavailable — report the blocker instead.
+
+## 5. Report
+
+Compare the shortlist in a table, then give one recommendation with reasons:
+
+| name | version | last publish | activity | fit | risk |
+|---|---|---|---|---|---|
+| @acme/pi-search | 1.2.0 | 2026-09-05 | active (7d) | no overlap | low |
+
+**A report is not install authorization.** The user decides whether to run `pi install`.
+
+## 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:
+
+```bash
+qmd update && qmd embed
+```
+
+This cache is the corpus behind semantic search. Never bulk-fetch READMEs — it grows one real review at
+a time.
+
+**One-time setup.** Semantic search needs this directory registered as the qmd collection
+`pi-pkg-readmes`, and nothing in this package registers it: an unregistered directory stays empty and
+semantic search then degrades to lexical search without any error. Register it once:
+
+```bash
+qmd collection add "<catalog dir>/readmes" --name pi-pkg-readmes
+```
+
+Check where the collection points with `qmd collection show pi-pkg-readmes`. If it points at another
+directory, say so and give the user the command above instead of saving READMEs into a directory that is
+never indexed.
+
+## Configuration
+
+`<catalog dir>/config.json` (absent file → defaults apply):
+
+- `isolation`: `"docker"` (default) | `"off"` — source-analysis environment.
+- `semantic`: `"auto"` (default) | `"on"` | `"off"` — `auto` enables semantic search exactly when the
+  `qmd` binary is present.
+
+## Edge cases
+
+| Situation | Action |
+|---|---|
+| `catalog.jsonl` missing | Cold start extracts it automatically; if it is still missing, run `/find-packages update` |
+| Catalog older than 30 days, or no matches | Refresh (§2), then search again; note staleness in the report if the refresh fails |
+| `qmd` missing, or `semantic: "off"` | Skip semantic search; rely on lexical passes |
+| `pi-pkg-readmes` empty or registered against another directory | Still skip semantic search, but tell the user the one-time setup command — an unindexed cache never becomes searchable on its own |
+| Docker unavailable | Stop before source analysis, report the blocker, and ask the user how to proceed |
+| `config.json` absent | Defaults apply: Docker isolation on, semantic `auto` |

package/.github/workflows/publish.yml

@@ -1,40 +0,0 @@
-name: publish
-
-on:
-  push:
-    tags: ["v*"]
-
-permissions:
-  contents: write # create the GitHub release
-  id-token: write # reserved for a future Trusted-Publishing (OIDC) switch
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 24
-          registry-url: https://registry.npmjs.org/
-          # reads NODE_AUTH_TOKEN from env to write ~/.npmrc
-
-      - name: Verify version matches tag
-        run: |
-          PKG_VERSION="${GITHUB_REF_NAME#v}"
-          TAG_VERSION="$(node -p "require('./package.json').version")"
-          if [ "${PKG_VERSION}" != "${TAG_VERSION}" ]; then
-            echo "::error::tag ${GITHUB_REF_NAME} != package.json version ${TAG_VERSION}"
-            exit 1
-          fi
-
-      - name: Publish
-        run: npm publish
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-
-      - name: Create GitHub release
-        run: gh release create "${GITHUB_REF_NAME}" --verify-tag --generate-notes
-        env:
-          GH_TOKEN: ${{ github.token }}

package/.github/workflows/update-data.yml

@@ -1,45 +0,0 @@
-name: update-data
-
-on:
-  schedule:
-    - cron: "17 3 * * *" # daily, off the hour
-  workflow_dispatch:
-
-permissions:
-  contents: write
-
-jobs:
-  refresh:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 24
-
-      - name: Fetch latest catalog
-        run: node scripts/sync-catalog.mjs --out "${RUNNER_TEMP}/catalog"
-
-      - name: Skip if unchanged
-        id: diff
-        run: |
-          NEW="${RUNNER_TEMP}/catalog/catalog.jsonl.gz"
-          OLD="$(curl -fsSL --max-time 30 https://cdn.jsdelivr.net/gh/${GITHUB_REPOSITORY}@data/data/catalog.jsonl.gz 2>/dev/null | sha256sum | cut -d' ' -f1 || true)"
-          CUR="$(sha256sum "${NEW}" | cut -d' ' -f1)"
-          echo "changed=$([[ "${CUR}" != "${OLD}" ]] && echo true || echo false)" >> "$GITHUB_OUTPUT"
-
-      - name: Push to data branch
-        if: steps.diff.outputs.changed == 'true'
-        run: |
-          git config user.name "github-actions[bot]"
-          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-          git fetch origin data || true
-          git checkout -B data origin/data 2>/dev/null || git checkout -B data
-          mkdir -p data
-          cp "${RUNNER_TEMP}/catalog/catalog.jsonl"      data/
-          cp "${RUNNER_TEMP}/catalog/catalog.jsonl.gz"   data/
-          cp "${RUNNER_TEMP}/catalog/catalog.jsonl.gz.sha256" data/
-          git add data/
-          git commit -qm "chore(data): refresh catalog ($(date -u +%Y-%m-%d))"
-          git push origin data