@openontology/opencode-palantir 0.1.4 → 0.1.5

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`, `/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,146 @@ 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.
+
+## Docs tools (Palantir public docs)
 
-### 3) Get `docs.parquet`
+This package does **not** ship with docs bundled. The docs DB is a local file:
 
-This package does **not** ship with docs bundled. You have two options:
+- `data/docs.parquet` (in your repo root)
 
-#### Option A (recommended): fetch inside OpenCode
+### Fetch docs
 
 In OpenCode, run:
 
 - `/refresh-docs`
 
-This downloads the docs and writes them to `data/docs.parquet` in your project root.
+This downloads the docs and writes `data/docs.parquet`.
 
-#### Option B: download a prebuilt Parquet file
+### Tools
 
-Download `data/docs.parquet` from this GitHub repo and place it at:
+- `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
 
-- `<your-project>/data/docs.parquet`
+If `data/docs.parquet` is missing, both tools will tell you to run `/refresh-docs`.
 
-## 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.
+
+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
+mise run setup
+```
+
+### Common tasks
+
+- Build: `mise run build`
+- Test: `mise run test`
+- Lint: `mise run lint`
+- Typecheck: `mise run typecheck`
+- Format: `mise run format`
 
-## Setup (this repo)
+### Smoke test the built artifact
 
 ```bash
-bun install
+mise run smoke
 ```
 
-## Fetching Documentation
+### Fetch docs parquet (local dev)
 
 Fetch all Palantir docs into `data/docs.parquet` (~2 minutes, ~17MB file):
 
@@ -122,9 +235,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 +248,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 +258,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

package/dist/index.js

@@ -1,7 +1,7 @@
 // @bun
 // src/index.ts
-import { tool } from "@opencode-ai/plugin/tool";
 import path4 from "path";
+import { tool } from "@opencode-ai/plugin/tool";
 
 // node_modules/hyparquet/src/constants.js
 var ParquetTypes = [
@@ -7869,6 +7869,20 @@ function formatError3(err) {
 function isRecord2(value) {
   return !!value && typeof value === "object" && !Array.isArray(value);
 }
+function stableSortJson(value) {
+  if (Array.isArray(value))
+    return value.map(stableSortJson);
+  if (!isRecord2(value))
+    return value;
+  const out = {};
+  for (const k of Object.keys(value).sort((a, b) => a.localeCompare(b))) {
+    out[k] = stableSortJson(value[k]);
+  }
+  return out;
+}
+function stableJsonStringify(value) {
+  return JSON.stringify(stableSortJson(value));
+}
 function formatWarnings(warnings) {
   if (warnings.length === 0)
     return "";
@@ -7902,8 +7916,81 @@ async function resolveProfile(worktree) {
     };
   }
 }
+function hasPalantirToolToggles(data, agentName) {
+  const agents = data["agent"];
+  if (!isRecord2(agents))
+    return false;
+  const agent = agents[agentName];
+  if (!isRecord2(agent))
+    return false;
+  const tools = agent["tools"];
+  if (!isRecord2(tools))
+    return false;
+  return Object.keys(tools).some((k) => k.startsWith("palantir-mcp_"));
+}
+function isAutoBootstrapAlreadyComplete(data) {
+  const foundryUrl = extractFoundryApiUrlFromMcpConfig(data);
+  const toolsRoot = data["tools"];
+  const hasGlobalDeny = isRecord2(toolsRoot) && toolsRoot["palantir-mcp_*"] === false;
+  const hasAgentToggles = hasPalantirToolToggles(data, "foundry-librarian") && hasPalantirToolToggles(data, "foundry");
+  return !!foundryUrl && hasGlobalDeny && hasAgentToggles;
+}
+async function autoBootstrapPalantirMcpIfConfigured(worktree) {
+  try {
+    const tokenRaw = process.env.FOUNDRY_TOKEN;
+    const urlRaw = process.env.FOUNDRY_URL;
+    if (!tokenRaw || tokenRaw.trim().length === 0)
+      return;
+    if (!urlRaw || urlRaw.trim().length === 0)
+      return;
+    const normalized = normalizeFoundryBaseUrl(urlRaw);
+    if ("error" in normalized)
+      return;
+    const readJsonc = await readOpencodeJsonc(worktree);
+    if (!readJsonc.ok && !("missing" in readJsonc))
+      return;
+    const readLegacy = await readLegacyOpencodeJson(worktree);
+    if (!readLegacy.ok && !("missing" in readLegacy))
+      return;
+    const baseJsoncData = readJsonc.ok ? readJsonc.data : {};
+    const base = isRecord2(baseJsoncData) ? baseJsoncData : {};
+    const merged = readLegacy.ok ? mergeLegacyIntoJsonc(readLegacy.data, base) : { ...base };
+    if (isAutoBootstrapAlreadyComplete(merged))
+      return;
+    const existingMcpUrlRaw = extractFoundryApiUrlFromMcpConfig(merged);
+    const existingMcpUrlNorm = existingMcpUrlRaw ? normalizeFoundryBaseUrl(existingMcpUrlRaw) : null;
+    const { profile } = await resolveProfile(worktree);
+    const discoveryUrl = existingMcpUrlNorm && "url" in existingMcpUrlNorm ? existingMcpUrlNorm.url : normalized.url;
+    const toolNames = await listPalantirMcpTools(discoveryUrl);
+    if (toolNames.length === 0)
+      return;
+    const allowlist = computeAllowedTools(profile, toolNames);
+    const patch = patchConfigForSetup(merged, {
+      foundryApiUrl: normalized.url,
+      toolNames,
+      profile,
+      allowlist
+    });
+    const jsoncMissing = !readJsonc.ok && "missing" in readJsonc;
+    const needsMigration = jsoncMissing && readLegacy.ok;
+    const changed = needsMigration || stableJsonStringify(merged) !== stableJsonStringify(patch.data);
+    if (!changed)
+      return;
+    const outPath = path3.join(worktree, OPENCODE_JSONC_FILENAME);
+    const text = stringifyJsonc(patch.data);
+    await writeFileAtomic(outPath, text);
+    if (readLegacy.ok) {
+      await renameLegacyToBak(worktree);
+    }
+  } catch (err) {
+    return;
+  }
+}
 async function setupPalantirMcp(worktree, rawArgs) {
-  const urlArg = rawArgs.trim();
+  const urlFromArgs = rawArgs.trim();
+  const urlFromEnvRaw = process.env.FOUNDRY_URL;
+  const urlFromEnv = typeof urlFromEnvRaw === "string" ? urlFromEnvRaw.trim() : "";
+  const urlArg = urlFromArgs || urlFromEnv;
   if (!urlArg) {
     return [
       "[ERROR] Missing Foundry base URL.",
@@ -7911,6 +7998,9 @@ async function setupPalantirMcp(worktree, rawArgs) {
       "Usage:",
       "  /setup-palantir-mcp <foundry_api_url>",
       "",
+      "Or set:",
+      "  export FOUNDRY_URL=<foundry_api_url>",
+      "",
       "Example:",
       "  /setup-palantir-mcp https://23dimethyl.usw-3.palantirfoundry.com"
     ].join(`
@@ -8056,6 +8146,92 @@ var NO_DB_MESSAGE = "Documentation database not found. Run /refresh-docs to down
 var plugin = async (input) => {
   const dbPath = path4.join(input.worktree, "data", "docs.parquet");
   let dbInstance = null;
+  let autoBootstrapStarted = false;
+  function ensureCommandDefinitions(cfg) {
+    if (!cfg.command)
+      cfg.command = {};
+    if (!cfg.command["refresh-docs"]) {
+      cfg.command["refresh-docs"] = {
+        template: "Refresh Palantir documentation database.",
+        description: "Download Palantir docs and write data/docs.parquet (local)."
+      };
+    }
+    if (!cfg.command["setup-palantir-mcp"]) {
+      cfg.command["setup-palantir-mcp"] = {
+        template: "Set up palantir-mcp for this repo.",
+        description: "Guided MCP setup for Foundry. Usage: /setup-palantir-mcp <foundry_api_url>. Requires FOUNDRY_TOKEN for tool discovery."
+      };
+    }
+    if (!cfg.command["rescan-palantir-mcp-tools"]) {
+      cfg.command["rescan-palantir-mcp-tools"] = {
+        template: "Re-scan palantir-mcp tools and patch tool gating.",
+        description: "Re-discovers the palantir-mcp tool list and adds missing palantir-mcp_* toggles (does not overwrite existing toggles). Requires FOUNDRY_TOKEN."
+      };
+    }
+  }
+  function ensureAgentDefaults2(agent, agentName) {
+    const defaultDescription = agentName === "foundry-librarian" ? "Foundry exploration and context gathering (parallel-friendly)" : "Foundry execution agent (uses only enabled palantir-mcp tools)";
+    if (agent.mode !== "subagent" && agent.mode !== "primary" && agent.mode !== "all") {
+      agent.mode = "subagent";
+    }
+    if (typeof agent["hidden"] !== "boolean")
+      agent["hidden"] = false;
+    if (typeof agent.description !== "string")
+      agent.description = defaultDescription;
+    if (typeof agent.prompt !== "string") {
+      agent.prompt = agentName === "foundry-librarian" ? [
+        "You are the Foundry librarian.",
+        "",
+        "- Focus on exploration and context gathering.",
+        "- Split independent exploration tasks and run them in parallel when possible.",
+        "- Return compact summaries and cite the tool calls you ran.",
+        "- Avoid dumping massive schemas unless explicitly asked."
+      ].join(`
+`) : [
+        "You are the Foundry execution agent.",
+        "",
+        "- Use only enabled palantir-mcp tools.",
+        "- Prefer working from summaries produced by @foundry-librarian.",
+        "- Keep operations focused and deterministic."
+      ].join(`
+`);
+    }
+    if (!agent.tools)
+      agent.tools = {};
+    if (agentName === "foundry-librarian") {
+      if (agent.tools.get_doc_page === undefined)
+        agent.tools.get_doc_page = true;
+      if (agent.tools.list_all_docs === undefined)
+        agent.tools.list_all_docs = true;
+      return;
+    }
+    if (agent.tools.get_doc_page === undefined)
+      agent.tools.get_doc_page = false;
+    if (agent.tools.list_all_docs === undefined)
+      agent.tools.list_all_docs = false;
+  }
+  function ensureAgentDefinitions(cfg) {
+    if (!cfg.agent)
+      cfg.agent = {};
+    const librarian = cfg.agent["foundry-librarian"] ?? {};
+    ensureAgentDefaults2(librarian, "foundry-librarian");
+    cfg.agent["foundry-librarian"] = librarian;
+    const foundry = cfg.agent.foundry ?? {};
+    ensureAgentDefaults2(foundry, "foundry");
+    cfg.agent.foundry = foundry;
+  }
+  function maybeStartAutoBootstrap() {
+    if (autoBootstrapStarted)
+      return;
+    const token = process.env.FOUNDRY_TOKEN;
+    const url = process.env.FOUNDRY_URL;
+    if (!token || token.trim().length === 0)
+      return;
+    if (!url || url.trim().length === 0)
+      return;
+    autoBootstrapStarted = true;
+    autoBootstrapPalantirMcpIfConfigured(input.worktree);
+  }
   async function getDb() {
     if (!dbInstance) {
       dbInstance = await createDatabase(dbPath);
@@ -8159,6 +8335,11 @@ var plugin = async (input) => {
     return score;
   }
   return {
+    config: async (cfg) => {
+      ensureCommandDefinitions(cfg);
+      ensureAgentDefinitions(cfg);
+      maybeStartAutoBootstrap();
+    },
     tool: {
       get_doc_page: tool({
         description: "Retrieve a Palantir documentation page. Provide either a URL path (preferred) or a free-text query; the tool will handle common URL variants (full URLs, missing /docs prefix, trailing slashes).",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openontology/opencode-palantir",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "collection of tools, agents, hooks to supercharge development in foundry",
   "license": "MIT",
   "author": {