@openontology/opencode-palantir 0.1.4 → 0.1.5-next.9

package/README.md

@@ -1,30 +1,61 @@
 # opencode-palantir
 
-OpenCode plugin that provides **Palantir Foundry documentation** to AI agents via a local Parquet
-database.
+[![npm](https://img.shields.io/npm/v/@openontology/opencode-palantir?logo=npm&label=npm)](https://www.npmjs.com/package/@openontology/opencode-palantir)
+[![downloads](https://img.shields.io/npm/dm/@openontology/opencode-palantir?logo=npm&label=downloads)](https://www.npmjs.com/package/@openontology/opencode-palantir)
+![CI](https://img.shields.io/github/actions/workflow/status/anand-testcompare/opencode-palantir/pr.yml?branch=main&label=CI&logo=github)
+![bun](https://img.shields.io/badge/bun-1.3.2-000000?logo=bun&logoColor=white)
+![@opencode-ai/plugin](https://img.shields.io/github/package-json/dependency-version/anand-testcompare/opencode-palantir/dev/%40opencode-ai%2Fplugin?label=opencode%20plugin%20api&logo=npm)
+![palantir-mcp](https://img.shields.io/npm/v/palantir-mcp?logo=npm&label=palantir-mcp)
+![hyparquet](https://img.shields.io/github/package-json/dependency-version/anand-testcompare/opencode-palantir/hyparquet?label=hyparquet&logo=npm)
 
-## Features
+OpenCode plugin that provides:
 
-- Fetches all ~3,600 pages from Palantir's public documentation
-- Stores in a local Parquet file for fast offline access (~17MB)
-- Exposes `get_doc_page` and `list_all_docs` tools for AI agents
+- Palantir public documentation tools backed by a local Parquet database
+- Foundry MCP bootstrapping helpers (commands, agents, and optional auto-bootstrap)
 
-## Quick start (OpenCode users)
+NPM package: https://www.npmjs.com/package/@openontology/opencode-palantir
 
-### 1) Enable the plugin in `opencode.json` / `opencode.jsonc`
+## Supported OS
 
-Add the plugin to your OpenCode config:
+- Supported: macOS, Linux
+- Windows: not supported (WSL2 might work, but we don’t debug Windows-specific issues)
+
+## Install (OpenCode)
+
+Add the plugin in your OpenCode config (`opencode.jsonc`):
 
 ```jsonc
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugin": ["@openontology/opencode-palantir@^0.1.1"]
+  "plugin": ["@openontology/opencode-palantir@^0.1.4"]
 }
 ```
 
 Restart OpenCode.
 
-### 2) (Optional) Install per-project
+After enabling the plugin, OpenCode will automatically register:
+
+- Tools: `get_doc_page`, `list_all_docs`
+- Commands: `/refresh-docs`, `/refresh-docs-rescrape`, `/setup-palantir-mcp`, `/rescan-palantir-mcp-tools`
+- Agents: `foundry-librarian`, `foundry`
+
+### Versions: how to get the latest
+
+Prefer **pinned** or **semver range** installs (like `@^0.1.4`), and update intentionally.
+
+Avoid using `@latest` in config:
+
+- it can make startup slower (npm resolution/install on startup)
+- it makes behavior less deterministic
+- depending on caching, you may not get the upgrade behavior you expect
+
+To find the newest version and changelog:
+
+- NPM versions: https://www.npmjs.com/package/@openontology/opencode-palantir
+- GitHub releases: https://github.com/anand-testcompare/opencode-palantir/releases
+- Repo changelog: `CHANGELOG.md`
+
+### (Optional) Install per-project
 
 In your project repo, add the plugin as a dependency inside `.opencode/` (keeps plugin deps separate
 from your app deps):
@@ -35,7 +66,7 @@ mkdir -p .opencode
 cat > .opencode/package.json <<'EOF'
 {
   "dependencies": {
-    "@openontology/opencode-palantir": "^0.1.1"
+    "@openontology/opencode-palantir": "^0.1.4"
   }
 }
 EOF
@@ -45,8 +76,6 @@ EOF
 
 Then create a tiny wrapper file in `.opencode/plugins/`:
 
-Create a tiny wrapper file in `.opencode/plugins/`:
-
 ```bash
 mkdir -p .opencode/plugins
 
@@ -59,62 +88,149 @@ EOF
 
 OpenCode automatically loads `.js`/`.ts` files from `.opencode/plugins/` at startup.
 
-> If your OpenCode setup uses an `opencode.json` / `opencode.jsonc` that restricts plugin loading,
-> make sure `.opencode/plugins/` (or the specific plugin file) is included.
+## Environment variables (Foundry MCP)
+
+This plugin never writes secrets to disk. In `opencode.jsonc`, the token is always referenced as
+`{env:FOUNDRY_TOKEN}`.
+
+### Variables
+
+- `FOUNDRY_URL`
+  - Foundry base URL (used for auto-bootstrap and can be used as a default for `/setup-palantir-mcp`)
+  - Example: `https://YOUR-STACK.palantirfoundry.com`
+- `FOUNDRY_TOKEN`
+  - Foundry token used by `palantir-mcp` for tool discovery
+  - Must be exported (not just set in a shell)
+
+### Recommended setup (zsh, macOS/Linux)
+
+Use your existing shell secrets file. For example, if you already source `~/.shell_secrets` from
+`~/.zshrc`, add:
+
+```zsh
+export FOUNDRY_URL='https://YOUR-STACK.palantirfoundry.com'
+export FOUNDRY_TOKEN='YOUR_TOKEN'
+```
+
+Lock it down:
+
+```bash
+chmod 600 ~/.shell_secrets
+```
+
+Ensure `~/.zshrc` sources it:
+
+```zsh
+if [ -f "$HOME/.shell_secrets" ]; then
+  source "$HOME/.shell_secrets"
+fi
+```
+
+If you still see “token not exported” errors, verify `echo $FOUNDRY_TOKEN` prints a value and that
+it’s `export`ed in the environment where OpenCode is launched.
 
-### 3) Get `docs.parquet`
+## Docs tools (Palantir public docs)
 
-This package does **not** ship with docs bundled. You have two options:
+The docs DB is a local file:
 
-#### Option A (recommended): fetch inside OpenCode
+- `data/docs.parquet` (in your repo root)
 
-In OpenCode, run:
+### First-run behavior
 
-- `/refresh-docs`
+On startup and tool usage, the plugin automatically ensures `data/docs.parquet` exists by using a
+prebuilt snapshot (download/copy). In most repos, docs tools should work without any manual setup.
 
-This downloads the docs and writes them to `data/docs.parquet` in your project root.
+### Refresh commands
 
-#### Option B: download a prebuilt Parquet file
+- `/refresh-docs` (recommended)
+  - Force refresh from a prebuilt snapshot (no live rescrape)
+- `/refresh-docs-rescrape` (unsafe/experimental fallback)
+  - Live-rescrapes palantir.com docs and rebuilds `data/docs.parquet`
+  - Use only when snapshot download/copy is blocked
 
-Download `data/docs.parquet` from this GitHub repo and place it at:
+### Tools
 
-- `<your-project>/data/docs.parquet`
+- `get_doc_page`
+  - Retrieve a doc page by URL, or fuzzy match by query
+- `list_all_docs`
+  - List docs with pagination and optional query/scope filtering
 
-## Using the tools
+## Foundry MCP helpers
 
-When installed, this plugin exposes:
+This plugin registers Foundry commands and agents automatically at startup (config-driven).
 
-- **`get_doc_page`** - Retrieve a specific doc page by URL
-- **`list_all_docs`** - List all available documentation pages
+### Auto-bootstrap (no command required)
 
-If `data/docs.parquet` is missing, both tools will instruct you to run `/refresh-docs`.
+If you set both `FOUNDRY_TOKEN` and `FOUNDRY_URL`, the plugin will automatically and idempotently
+patch repo-root `opencode.jsonc` to initialize:
 
-## Foundry MCP setup helpers
+- `mcp.palantir-mcp` local server config
+- global tool deny: `tools.palantir-mcp_* = false`
+- per-agent allow/deny toggles under `foundry-librarian` and `foundry`
 
-This plugin also provides two OpenCode commands to set up `palantir-mcp` with project-scoped tool
-gating and Foundry sub-agents:
+### Guided setup and maintenance
 
-- **`/setup-palantir-mcp <foundry_api_url>`**
+- `/setup-palantir-mcp <foundry_api_url>`
   - Creates/patches repo-root `opencode.jsonc`
   - Adds `mcp.palantir-mcp` (if missing) as a local `npx palantir-mcp --foundry-api-url ...` server
   - Enforces global deny: `tools.palantir-mcp_* = false`
   - Creates `foundry-librarian` and `foundry` agents
-  - Dynamically discovers the current `palantir-mcp` tool list and writes explicit `true/false`
-    per-tool toggles under each Foundry agent
-- **`/rescan-palantir-mcp-tools`**
-  - Re-discovers the `palantir-mcp` tool list and adds any missing explicit toggles
+  - Discovers `palantir-mcp` tools and writes explicit `true/false` toggles under each agent
+- `/rescan-palantir-mcp-tools`
+  - Re-discovers the `palantir-mcp` tool list and adds missing explicit toggles
   - Never overwrites existing `palantir-mcp_*` toggles
 
-Auth is always env-only. The token is referenced as `{env:FOUNDRY_TOKEN}` and is never written to
-disk.
+### About palantir-mcp versions (important)
+
+The generated MCP server uses `npx -y palantir-mcp ...` by default.
 
-## Setup (this repo)
+Notes:
+
+- First run can be slow (npx may need to download/install).
+- `@latest` / unpinned installs are less deterministic.
+
+Recommendation: once you’re set up, pin the version in `opencode.jsonc`:
+
+```jsonc
+{
+  "mcp": {
+    "palantir-mcp": {
+      "type": "local",
+      "command": [
+        "npx",
+        "-y",
+        "palantir-mcp@<version>",
+        "--foundry-api-url",
+        "https://YOUR-STACK.palantirfoundry.com"
+      ]
+    }
+  }
+}
+```
+
+## Development (this repo)
+
+### Setup
 
 ```bash
-bun install
+mise run setup
 ```
 
-## Fetching Documentation
+### Common tasks
+
+- Build: `mise run build`
+- Test: `mise run test`
+- Lint: `mise run lint`
+- Typecheck: `mise run typecheck`
+- Format: `mise run format`
+
+### Smoke test the built artifact
+
+```bash
+mise run smoke
+```
+
+### Fetch docs parquet (local dev)
 
 Fetch all Palantir docs into `data/docs.parquet` (~2 minutes, ~17MB file):
 
@@ -122,9 +238,7 @@ Fetch all Palantir docs into `data/docs.parquet` (~2 minutes, ~17MB file):
 bun run src/docs/fetch-cli.ts
 ```
 
-## Querying the Data
-
-### Schema
+### Parquet schema (local dev)
 
 The Parquet file contains a single row group with the following columns:
 
@@ -137,7 +251,7 @@ The Parquet file contains a single row group with the following columns:
 | `meta`       | string  | JSON-encoded metadata               |
 | `fetched_at` | string  | ISO 8601 timestamp of when fetched  |
 
-### Bun
+Example (Bun):
 
 ```typescript
 import { parquetReadObjects } from 'hyparquet';
@@ -147,76 +261,6 @@ const file = await Bun.file('data/docs.parquet').arrayBuffer();
 // List all pages (url + title only)
 const pages = await parquetReadObjects({ file, columns: ['url', 'title'] });
 console.log(`${pages.length} pages`);
-
-// Search by title
-const matches = pages.filter((p) => p.title.includes('Pipeline'));
-console.log(matches.slice(0, 10));
-
-// Get a specific page's content by row index
-const urlToRow = new Map(pages.map((p, i) => [p.url, i]));
-const rowIndex = urlToRow.get('/foundry/ontology/overview/');
-if (rowIndex !== undefined) {
-  const [page] = await parquetReadObjects({
-    file,
-    rowStart: rowIndex,
-    rowEnd: rowIndex + 1,
-  });
-  console.log(page.content);
-}
-```
-
-## OpenCode Tools
-
-When installed as an OpenCode plugin, exposes:
-
-- **`get_doc_page`** - Retrieve a specific doc page by URL
-- **`list_all_docs`** - List all available documentation pages
-- **`/refresh-docs`** - Command hook to re-fetch all documentation
-
-### Installing in OpenCode (this repo only)
-
-For local development against `dist/`, you can point the wrapper at the built artifact:
-
-```bash
-mkdir -p .opencode/plugins
-
-cat > .opencode/plugins/opencode-palantir.js <<'EOF'
-import plugin from '../../dist/index.js';
-
-export default plugin;
-EOF
-```
-
-## Development
-
-Build the plugin:
-
-```bash
-mise run build
-```
-
-Run tests:
-
-```bash
-mise run test
-```
-
-Smoke test the built artifact (build + verify tools load from `dist/index.js`):
-
-```bash
-mise run smoke
-```
-
-Lint code:
-
-```bash
-mise run lint
-```
-
-Format with Prettier:
-
-```bash
-mise run format
 ```
 
 ## Release notes