@bjorntech/key-ferry 0.1.8 → 0.1.9

package/docs/troubleshooting.md

@@ -75,7 +75,7 @@ An object supports an explicit mapping:
 
 The MCP server must already exist in `mcp.servers` and must be `type: "local"`.
 Remote or missing servers are not silently routed. Replace the illustrative
-command in `examples/opencode.jsonc` with a real local MCP command before
+command in `examples/single-project/opencode.json` with a real local MCP command before
 launching it; the example command is not an installed fixture.
 
 The server remains disabled when the sidecar is not ready, startup or refresh
@@ -212,3 +212,28 @@ That command is a gated synthetic compatibility check. The normal suite and
 live fixtures are separate verification layers; these commands do not certify
 production deployments, every external MCP provider, or a fully live OpenCode
 host/TUI session.
+
+## Global/project activation and readiness
+
+A native plugin being active does not mean its broker is ready. During startup,
+wait for the selected scope to report its ready phase; mapped servers remain
+fail-closed while it is starting. A disabled integration does not register the
+status RPC, so a status request returning 404 is expected rather than evidence
+of a broken Varlock backend.
+
+The generated RPC client already wraps input objects. Use `status({})` (and the
+same shape for refresh/doctor), not a manually double-wrapped payload. A 400 or
+404 from a bad probe does not prove the broker failed. Check the reported phase,
+wait for startup, then use explicit refresh or doctor for the selected active
+group. Status is pure and does not re-authenticate. Refresh and doctor do not
+activate an inactive or manual project; use `activateProject({})` first, or the
+project TUI command.
+
+Global and project groups are independent. A project file is eligible only when
+the global `projectConfig.enabled` option is explicitly true. Global automatic
+activation can be restricted to manual by the project file, but a project
+cannot override a global manual policy. Project mappings never inherit the
+global mapping set; duplicate names require explicit `overrides`, and unrelated
+global servers continue unchanged. Review project repositories before enabling
+automatic activation: this is an execution-policy convenience, not a sandbox or
+provider-authentication boundary.

package/examples/README.md

@@ -0,0 +1,47 @@
+# Configuration examples
+
+These examples use the public package name `@bjorntech/key-ferry` and synthetic
+values only. They do not start an MCP server or contact a provider.
+
+## Primary setup: global plugin plus project MCPs
+
+Use the `global/` and `project/` pair when installing Key Ferry once in the
+user's global OpenCode configuration:
+
+1. Copy `global/opencode.json` into the user's native global configuration at
+   `~/.config/opencode/opencode.json` (a generic public user-home path, not a
+   repository-specific path). Keep unrelated settings. Set its
+   `projectDirectory` to the absolute path of the Varlock root chosen for the
+   global key set, and copy `global/.env.schema` there.
+2. Copy `project/opencode.json` to the project root as the native
+   `opencode.json`, and copy `project/.env.schema` to the separate project
+   Varlock root selected for `PROJECT_API_KEY`.
+3. Copy `project/.opencode/key-ferry.jsonc` to the project at that path. It
+   maps the project's existing MCP name to its project key; it is not another
+   plugin entry.
+
+The global and project schemas and mappings are separate key sets. The native
+project file defines MCPs only, while the global file installs the plugin and
+its global MCP definition. The `global-mcp` and `project-mcp` names match the
+maps in their corresponding files. The sample commands are placeholders and
+must be replaced with real local commands before use. For remote servers,
+keep the server's URL and proxy decorators aligned; this example does not
+wire a remote backend automatically.
+
+The global `projectDirectory` placeholder is intentionally generic. Replace it
+with an absolute path selected by the user; do not commit a real local path or
+credential.
+
+## Alternative: one intentionally project-configured plugin
+
+`single-project/` is the supported legacy flat setup. Copy its native
+`opencode.json` and `.env.schema` together into one project root. Use this
+alternative only when intentionally configuring the plugin in that project;
+do not combine it with an existing globally configured Key Ferry mapping,
+because host plugin options replace one another. It is an alternative to the
+primary global-plus-project pair, not an additional layer.
+
+Both native `opencode.json` files are strict JSON for ordinary editors. The
+Key Ferry project mapping remains JSONC because its loader supports comments;
+its filename is intentionally `key-ferry.jsonc`. `.env.schema` comments are
+Varlock semantic decorators and must remain intact.

package/examples/global/.env.schema

@@ -0,0 +1,6 @@
+# Synthetic global-root example only. Do not put a real credential here.
+# @proxyConfig={egress="strict"}
+# ---
+# @proxy(domain="global.example.test")
+# @placeholder=global-test-placeholder
+GLOBAL_API_KEY=global-test-placeholder

package/examples/global/opencode.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": [
+    {
+      "package": "@bjorntech/key-ferry",
+      "options": {
+        "enabled": true,
+        "projectDirectory": "/absolute/path/to/global-varlock-project",
+        "projectConfig": {
+          "enabled": true,
+          "activation": "auto",
+          "file": ".opencode/key-ferry.jsonc"
+        },
+        "requireStrictEgress": true,
+        "servers": {
+          "global-mcp": {
+            "env": ["GLOBAL_API_KEY"]
+          }
+        }
+      }
+    }
+  ],
+  "mcp": {
+    "servers": {
+      "global-mcp": {
+        "type": "local",
+        "command": ["node", "./path/to/your-global-mcp-server.mjs"]
+      }
+    }
+  }
+}

package/examples/project/.env.schema

@@ -0,0 +1,6 @@
+# Synthetic project-root example only. Do not put a real credential here.
+# @proxyConfig={egress="strict"}
+# ---
+# @proxy(domain="project.example.test")
+# @placeholder=project-test-placeholder
+PROJECT_API_KEY=project-test-placeholder

package/examples/project/.opencode/key-ferry.jsonc

@@ -0,0 +1,10 @@
+{
+  // Copy this file to the project root at .opencode/key-ferry.jsonc.
+  // The project group is additive: it never imports global mappings.
+  "enabled": true,
+  "servers": {
+    "project-mcp": {
+      "env": ["PROJECT_API_KEY"],
+    },
+  },
+}

package/examples/project/opencode.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "servers": {
+      "project-mcp": {
+        "type": "local",
+        "command": ["node", "./path/to/your-project-mcp-server.mjs"]
+      }
+    }
+  }
+}

package/examples/{opencode.jsonc → single-project/opencode.json}

@@ -2,8 +2,6 @@
   "$schema": "https://opencode.ai/config.json",
   "plugins": [
     {
-      // Merge this entry into your existing config; preserve unrelated
-      // plugins and MCP servers.
       "package": "@bjorntech/key-ferry",
       "options": {
         "enabled": true,
@@ -14,31 +12,34 @@
         "requireStrictEgress": true,
         "servers": {
           "example-local-mcp": {
-            "env": ["FAKE_API_KEY"],
+            "env": ["FAKE_API_KEY"]
           },
           "example-remote-mcp": {
             "remote": {
               "headers": {
-                "Authorization": { "env": "REMOTE_API_KEY", "prefix": "Bearer " },
-                "X-Tenant": "REMOTE_TENANT",
-              },
-            },
-          },
-        },
-      },
-    },
+                "Authorization": {
+                  "env": "REMOTE_API_KEY",
+                  "prefix": "Bearer "
+                },
+                "X-Tenant": "REMOTE_TENANT"
+              }
+            }
+          }
+        }
+      }
+    }
   ],
   "mcp": {
     "servers": {
       "example-local-mcp": {
         "type": "local",
-        "command": ["node", "./path/to/your-mcp-server.mjs"],
+        "command": ["node", "./path/to/your-mcp-server.mjs"]
       },
       "example-remote-mcp": {
         "type": "remote",
         "url": "https://mcp.example.test/mcp",
-        "oauth": false,
-      },
-    },
-  },
+        "oauth": false
+      }
+    }
+  }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@bjorntech/key-ferry",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Project-scoped Key Ferry integration for OpenCode V2",
   "keywords": [],
   "homepage": "https://github.com/bjorntech/key-ferry#readme",
@@ -75,6 +75,9 @@
     "prepack": "npm run build",
     "prepublishOnly": "npm run quality && npm run build"
   },
+  "dependencies": {
+    "jsonc-parser": "3.3.1"
+  },
   "devDependencies": {
     "@opencode/plugin": "2.0.30",
     "@types/istanbul-lib-coverage": "2.0.6",