@ory/opencode 0.14.0 → 1.0.0

package/README.md

@@ -2,9 +2,12 @@
 
 Security and developer experience for [OpenCode](https://opencode.ai), powered by [Ory](https://ory.com).
 
-**Security.** OpenCode runs real actions on your machine — editing files, running shell commands, calling APIs. The plugin gives every session a verifiable identity (you sign in once; OpenCode and any sub-agents it spawns each get their own), checks every tool call against permissions you control, and records each decision as an audit trace you can ship to your observability stack. It starts in watch mode so nothing is blocked on day one, and if Ory is ever unreachable it steps aside rather than locking you out.
+OpenCode runs real actions on your machine — editing files, running shell commands, calling APIs. This plugin gives those actions an identity, a permission check, and an audit trail.
 
-**Developer experience.** A single command installs the plugin and walks you through connecting — choose Ory Network, a local Docker stack, or audit-only, and it wires up the project, sign-in client, login, and permissions for you. It also helps you build Ory into your own app: ask in plain language to scaffold login, registration, and recovery pages, run a local Ory, or manage identities and permissions through the bundled MCP server.
+One command installs two independent halves:
+
+- **Developer experience** — the Ory skill catalog, `/ory:` slash commands, the local Ory dev stack, an MCP server, and activity logging. No account, no keys, nothing to configure: it works the moment it's installed.
+- **Ory Agent Security** — browser sign-in, brokered permission checks before tool calls, and the delegation trail. Opt-in connection details from the [Ory Console](https://console.ory.sh) switch it on, and it takes nothing away from the half above. See [Connect to Ory Agent Security](#connect-to-ory-agent-security).
 
 ## What you'll need
 
@@ -15,134 +18,141 @@ Security and developer experience for [OpenCode](https://opencode.ai), powered b
 
 ## Get started
 
-Run one command. It installs the plugin and walks you through connecting:
+Run one command:
 
 ```bash
 npx -y -p @ory/opencode ory-opencode install
 ```
 
-It opens a guided setup **in your browser** where you pick how to connect — the default takes just a click:
-
-- **Ory Network** *(default)* — sign in, or create a free account, in your browser. The project, keys, permissions, and login are all set up for you. Nothing to configure by hand.
-- **Local** — run a complete Ory on your laptop with Docker. No account, no signup, no keys. Great for trying it out.
-- **Audit-only** — skip Ory entirely and just log what OpenCode does.
-
-> No browser available (CI, SSH, headless)? The same walkthrough runs right in your terminal instead — or force it with `--no-web`.
-
-That's it. Confirm everything landed with:
+Confirm everything landed with:
 
 ```bash
 npx -y -p @ory/opencode ory-opencode status
 ```
 
-`status` is your one-stop check: what's configured, who's signed in, which tools are covered by permissions, and recent activity. Anything not set up yet shows as `(unset)`.
+`status` is your one-stop check: what's configured, who's signed in, which tools are covered by permissions, and recent activity. Until you connect Agent Security, the identity and permission rows say so and name what's missing.
 
-The installer registers the plugin in OpenCode's config (`opencode.json`) along with the Ory MCP server, a set of skills in `.opencode/skills/`, and the local-stack slash commands. Re-run install with `--reconfigure` to change your connection later, or `--no-configure` to skip the wizard. `ory-opencode uninstall` reverses it all.
+The installer registers the plugin in OpenCode's config (`opencode.json`) along with the Ory MCP server, a set of skills in `.opencode/skills/`, and the local-stack slash commands. `ory-opencode uninstall` reverses it all.
 
 <details>
 <summary>Prefer to register the plugin by hand?</summary>
 
-OpenCode loads the plugin in-process from `opencode.json`. If you only want the plugin — no MCP server, skills, or slash commands, and no guided setup — add it directly:
+OpenCode loads the plugin in-process from `opencode.json`. If you only want the plugin — no MCP server, skills, or slash commands — add it directly:
 
 ```json
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugin": ["@ory/opencode"]
+  "plugin": ["@ory/opencode@0.14.0"]
 }
 ```
 
-OpenCode fetches it from npm on next launch. Connect afterwards by running `ory-opencode install` (or `configure`) in a terminal — that's also what lands the skills and `/ory:` commands on disk.
+OpenCode fetches it from npm on next launch. Run `ory-opencode install` in a terminal to also land the skills and `/ory:` commands on disk.
+
+**Pin the version.** OpenCode installs each plugin spec into its own cache directory once and never re-resolves it, so a bare `"@ory/opencode"` (which means `@latest`) keeps loading whatever version was cached first — upgrades silently never take effect. `ory-opencode install` writes the pinned form for you, and checks that OpenCode will be able to install it.
 
 </details>
 
+## Skills and commands
+
+Installing the plugin drops the full Ory playbook catalog into OpenCode. **Skills** are model-invoked — just say what you want in plain language and the matching one takes over.
+
+| Skill | What it does for you |
+|---|---|
+| `ory-auth-setup` | Adds a complete auth system to your app — login, registration, recovery, verification, settings — on [Ory Elements](https://github.com/ory/elements) |
+| `ory-login-flow` | Builds just the pages, wired to Ory's self-service flows |
+| `ory-social-login` | "Sign in with…" for Google, GitHub, Apple, Microsoft, Discord, Slack, GitLab, Facebook |
+| `ory-local-dev` | Develops and tests login/permission flows against a local Ory — no project, no account, offline |
+| `ory-permissions-onboarding` | Walks a fresh install from observe mode to enforced per-tool permissions without getting blocked |
+| `ory-build-agent` | Drops `@ory/argus` into an agent *you* own — Claude Agent SDK, OpenAI Agents, Mastra, Vercel AI, LangGraph/PydanticAI |
+| `ory-build-integration` | Wires Ory into your app: Action webhooks, JWT validation at a gateway, live event streams |
+| `ory-contribute-integration` | Authors and submits an integration to the public `ory/integrates` registry |
+| `ory-e2b-sandbox` | Scaffolds an E2B sandbox template that boots with this plugin preinstalled |
+| `ory-temporal-worker` | Scaffolds a Temporal TypeScript worker where every Activity is authenticated, authorized, and audited |
+
+**Slash commands** run the local stack directly:
+
+| Command | What it does |
+|---|---|
+| `/ory:local-up` | Starts a local Ory (Identities, OAuth2, Permissions) in Docker and seeds a test user — it prints the email + password to sign in with |
+| `/ory:local-down` | Stops it, keeping your data volumes |
+| `/ory:temporal-up` | Starts a local Temporal dev server for the `ory-temporal-worker` scaffold |
+
+The local stack runs entirely on your laptop: Ory APIs at `http://localhost:4000`, a login UI on `:4455` (not `:3000`, to dodge Next.js port clashes), and the Ory Console on `:4100`.
+
+A built-in **Ory MCP server** rounds it out — OpenCode can manage identities, projects, and permissions straight from chat.
+
+So: ask OpenCode *"add Ory login to this app"* and it scaffolds the pages, starts a local Ory, and wires them together.
+
 ## What you get
 
-Once connected, every tool OpenCode runs is governed by Ory — three things happen automatically:
+Out of the box, every tool OpenCode runs produces a privacy-safe structured activity event in the unified local log.
+
+Once you connect to Ory Agent Security, two more things happen automatically:
 
 - **Who's driving.** You sign in once in your browser; OpenCode gets its own identity too. No tokens to copy around, and the "who acted on whose behalf" trail stays queryable later — even after tokens expire. (One nuance: OpenCode can't hard-block at session start, so browser sign-in there is advisory — it still runs and records correctly, the session just always proceeds. Per-tool checks are unaffected.)
-- **What it's allowed to do.** When OpenCode asks to use a tool, Ory checks whether it's permitted. It starts in **watch mode** — nothing is blocked, you just *see* what would be — so it never gets in your way on day one.
-- **A record of everything.** Every decision (allowed, denied, skipped) is logged as a trace you can send to Jaeger, Honeycomb, Grafana, or just a file.
+- **What it's allowed to do.** When OpenCode asks to use a tool, Ory checks whether it's permitted. It starts in **observe mode** — nothing is blocked, you just *see* what would be — so it never gets in your way on day one.
 
 If Ory is ever unreachable, the plugin gets out of the way and lets OpenCode keep working — so it can't lock you out.
 
 ### See what's happening
 
-Everything the plugin does is observable out of the box — no configuration required:
+Everything the plugin does is observable out of the box:
 
-- **Status at a glance.** `npx -y -p @ory/opencode ory-opencode status` shows what's configured, who's signed in, how many built-in tools your permissions cover, and the most recent tool-call activity.
-- **Live dashboard.** `npx -y -p @ory/opencode ory-opencode dashboard` opens the same picture in your browser — configuration, identities, permission coverage, Ory service health, and the latest tool-call activity, all refreshing live. From there you can flip **enforcement** on or off, toggle **user login**, and use **Change stack** to reconnect to a different Ory — no CLI required.
-- **Live traces.** Every tool call is recorded as an OpenTelemetry-style span. Watch them stream as the agent works:
+- **Activity log.** Privacy-safe activity is always appended to `~/.config/ory-agent-plugins/opencode/ory-agent-debug.log`. View events, decisions, and errors live with:
 
   ```bash
   npx -y -p @ory/opencode ory-opencode watch
   ```
 
-  Spans are also written to `~/.config/ory-agent-plugins/opencode/ory-agent-trace.ndjson` (NDJSON, one span per line) — tail that file, or point `OTEL_EXPORTER_OTLP_ENDPOINT` at a collector to ship them straight to Jaeger, Honeycomb, or Grafana.
-- **Debug log.** For a verbose play-by-play, set `ORY_AGENT_DEBUG=true`; structured logs land in `~/.config/ory-agent-plugins/opencode/ory-agent-debug.log`.
+  Set `ORY_AGENT_LOG_FILE` to override the path; set it empty to disable file persistence.
+- **Live debug.** Launch OpenCode with `ORY_AGENT_DEBUG=true` to add verbose local diagnostics, including raw shell commands, to the watched log and stderr. Secrets are recursively redacted; pass `watch --json` for NDJSON.
 
 ### Ready to enforce?
 
-When the watch-mode logs look right, turn on blocking with one command (setup already granted you the built-in tools):
+Once connected, the deny posture lives on the Ory project: when the observe-mode activity looks right, an admin promotes it to **enforce** in the **Ory Console** (Agent Security). Every session reads that posture live, so nothing has to be reinstalled.
 
 ```bash
-npx -y -p @ory/opencode ory-opencode permissions enforce
+npx -y -p @ory/opencode ory-opencode permissions   # what the project grants, and the live mode
 ```
 
-Now a denied tool is actually blocked and OpenCode shows why. In watch mode, OpenCode's own permission prompt is left in place for you to answer; only an explicit allow or a block-mode deny changes that. Go back to watch mode anytime with `permissions observe`. Prefer clicking? The dashboard has the same **Enforce** switch — flip it on, or back to watch mode, without touching the CLI. Use `permissions status` to see what's covered and `permissions bootstrap` to (re-)grant the built-in tools — or just ask OpenCode in chat, e.g. *"grant me use of the bash tool."*
+Then a denied tool is actually blocked and OpenCode shows why. In observe mode, OpenCode's own permission prompt is left in place for you to answer; only an explicit allow or an enforce-mode deny changes that.
 
-## Also: add login to your own app
+## Connect to Ory Agent Security
 
-Beyond securing OpenCode, the plugin helps you build Ory into whatever you're working on. Ask OpenCode *"add Ory login to this app"* and it scaffolds the login, registration, recovery, verification, and settings pages (using [Ory Elements](https://github.com/ory/elements)) wired to a local Ory — no signup or keys needed. Start that local Ory with `/ory:local-up` (it prints a test email + password to sign in with) and tear it down with `/ory:local-down`.
+Copy the connection details from the [Ory Console](https://console.ory.sh) under **Agent Security**:
 
-Bundled **skills** (just ask in plain language) cover more: `ory-auth-setup`, `ory-login-flow`, `ory-social-login` (Google, GitHub, Apple…), `ory-permissions-onboarding`, and playbooks for wiring Ory into your own agents, E2B sandboxes, or Temporal workers. A built-in **Ory MCP server** lets OpenCode manage identities, projects, and permissions straight from chat.
-
-## Configure by hand (CI / advanced)
-
-The guided setup covers most people. For scripted or CI setups, or to point at an existing Ory Network project, configure directly. Settings are saved to `~/.config/ory-agent-plugins/config.json` and shared across all your Ory agent plugins; environment variables win when both are set.
+| Value | Flag | Environment variable |
+|---|---|---|
+| Project URL | `--project-url` | `ORY_PROJECT_URL` |
+| Agent Security URL | `--agent-security-url` | `ORY_AGENT_SECURITY_URL` |
+| Sign-in client id override (default `ory-agent-security-login`) | `--oauth2-client-id` | `ORY_OAUTH2_CLIENT_ID` |
 
 ```bash
 npx -y -p @ory/opencode ory-opencode configure \
   --project-url https://<slug>.projects.oryapis.com \
-  --oauth2-client-id <sign-in client id>
+  --agent-security-url https://agents.console.ory.com
 ```
 
-OpenCode's own identity registers itself automatically on first run — nothing to create. The `--oauth2-client-id` is the one piece browser sign-in needs; the guided setup makes it for you, or see below to do it by hand. For logging-only with no checks, use `--audit-only`. The interactive user login runs every session (always on, non-blocking) and only needs `ORY_OAUTH2_CLIENT_ID` to complete the browser flow. The equivalent env vars are `ORY_PROJECT_URL`, `ORY_OAUTH2_CLIENT_ID`, and `ORY_AGENT_API_KEY`.
+`install` accepts the same flags, so you can register the plugin **and** connect in one shot (`install --project-url <URL> --agent-security-url <URL>`). The login client defaults to `ory-agent-security-login`; custom deployments can override it with `--oauth2-client-id`. Existing configurations fall back to the project URL when the Agent Security URL is unset. To turn sign-in and checks back off later, use `configure --disconnect`.
 
-<details>
-<summary>Create the sign-in client by hand</summary>
+**Ory Network or OEL.** Either works. For an Ory Network project the URL is `https://<slug>.projects.oryapis.com`; for a self-hosted **Ory Enterprise License** deployment, point `--project-url` at that deployment's base URL and use the sign-in client id from its Agent Security configuration. Everything downstream — sign-in, checks, delegation — is identical.
 
-The guided setup normally does this. To do it yourself, create a **public** OAuth2 client (no secret) listing all four loopback URLs — the plugin tries each in turn so sign-in survives a busy port:
+**There is nothing else for you to create.** The sign-in client, the permission model, the per-tool grants and blocks, and the observe/enforce posture are all provisioned in the Console by someone with project access. At runtime the plugin only *reads* permissions — it has no write path into your project, which is why installing it needs no workspace privilege. Each OpenCode session registers its own identity automatically on first use.
 
-```bash
-ory create oauth2-client --project <project-id> \
-  --name "Ory Agent Security · user login (PKCE)" \
-  --grant-type authorization_code,refresh_token \
-  --response-type code \
-  --scope openid,offline_access \
-  --token-endpoint-auth-method none \
-  --redirect-uri http://127.0.0.1:47823/callback \
-  --redirect-uri http://127.0.0.1:47824/callback \
-  --redirect-uri http://127.0.0.1:47825/callback \
-  --redirect-uri http://127.0.0.1:47826/callback
-```
-
-…or in the [Ory Console](https://console.ory.sh) under *OAuth2* → *Clients* → *Create client* (pick "Public client", "Authorization Code" + "Refresh Token" grants, scopes `openid offline_access`, and paste the four redirect URIs). Pass the resulting id to `configure --oauth2-client-id`. Running headless with a session token already? Set `ORY_USER_SESSION_TOKEN` and skip the browser step entirely.
-
-</details>
+Sign-in runs at the start of every session and never blocks — a declined, skipped, or timed-out login simply leaves that session without a user identity.
 
-With nothing configured, the plugin still loads and runs in **pass-through mode**: skills, commands, and logging work, but no checks run and nothing is blocked. Perfectly fine if you only want the app-building features.
+Settings are saved to `~/.config/ory-agent-plugins/config.json` and shared across all your Ory agent plugins; environment variables win when both are set. Running headless with an OAuth2 access token already? Set `ORY_USER_OAUTH2_TOKEN` and the browser step is skipped entirely.
 
 ## Commands
 
 ```
-ory-opencode install | uninstall        Install/remove; --reconfigure re-runs setup, --no-web forces the terminal wizard, --no-configure skips it
+ory-opencode install | uninstall         Install (add --project-url to also connect Agent Security) / remove
 ory-opencode status                      Show configuration, identities, permission coverage, recent activity
-ory-opencode dashboard                   Open the live browser dashboard (status + service health + Change stack)
-ory-opencode watch                       Tail the live trace stream (OTel spans)
-ory-opencode permissions <cmd>           status | bootstrap | observe (watch) | enforce (block)
-ory-opencode configure <flags>           Point at a project by hand (--project-url, --oauth2-client-id, --audit-only)
+ory-opencode permissions <cmd>           status  (read-only; grants + posture live in the Ory Console)
+ory-opencode configure <flags>           Connect a project (--project-url) or --disconnect
 ory-opencode agent <status|unregister>   Manage OpenCode's own auto-created identity
 ory-opencode local <up|down|status|…>    Run / manage a local Ory in Docker
+ory-opencode version                     Print plugin, core, and Node versions (--json for machine-readable)
 ```
 
 All prefixed with `npx -y -p @ory/opencode`.
@@ -150,10 +160,11 @@ All prefixed with `npx -y -p @ory/opencode`.
 ## Troubleshooting
 
 - **`/ory:local-up` fails** — make sure Docker is running and ports `4000`, `4100`, `4455`, and `16686` are free.
-- **Browser sign-in loops** — reset with `ory-opencode agent unregister` and try again.
-- **Install ran but never asked how to connect** — you're almost certainly on a stale `npx` cache. `npx -p @ory/opencode` (no version pin) reuses a previously-downloaded copy instead of re-resolving to the latest, so an older CLI whose install predates the setup wizard can run while you believe you're on the current release. The install banner prints the running version; confirm it with `npx -y -p @ory/opencode ory-opencode version`. To force the current release, clear the cache and reinstall: `rm -rf ~/.npm/_npx` then `npx -y -p @ory/opencode ory-opencode install`. Pinning an exact version (`@ory/opencode@<version>`) also bypasses the cached copy.
+- **Browser sign-in loops** (after connecting) — reset with `ory-opencode agent unregister` and try again.
+- **Running an older CLI than expected** — `npx -p @ory/opencode` (no version pin) reuses a previously-downloaded copy instead of re-resolving to the latest. The install banner prints the running version; confirm it with `npx -y -p @ory/opencode ory-opencode version`. To force the current release, clear the cache and reinstall: `rm -rf ~/.npm/_npx` then `npx -y -p @ory/opencode ory-opencode install`. Pinning an exact version (`@ory/opencode@<version>`) also bypasses the cached copy.
+- **Hooks don't seem to run, but skills and `/ory:` commands are there** — OpenCode isn't loading the plugin. It fetches plugins itself, with npm, into its own cache (`~/.cache/opencode/packages/<spec>/`), and neither outcome is visible in OpenCode: an install that succeeded is never re-resolved (so an older cached copy keeps loading), and one that failed is retried and fails the same way every session. Run `npx -y -p @ory/opencode ory-opencode status` — it reports the copy OpenCode will actually load, says when an install was attempted and failed, explains why the spec can't be resolved, and flags stale cache directories.
+- **The plugin can't be installed from your registry** — OpenCode's plugin install uses the npm configuration its own process inherits, so it goes to the public registry unless `npm_config_registry` says otherwise, and any `min-release-age` in your `.npmrc` applies to it as well. A build that isn't on the registry OpenCode reaches (a private or local publish) or a version newer than your freshness gate can't be installed, and `install`/`status` will tell you so. Either launch OpenCode against the right registry — `npm_config_registry=<registry> npm_config_min_release_age=0 opencode` — or point it at a local copy, which skips the registry entirely: `ory-opencode install --plugin-spec file:///path/to/node_modules/@ory/opencode`.
 - **`npm error code ENOVERSIONS` on install** — your npm has a freshness filter hiding brand-new versions. Wait it out, or run `npx -y --min-release-age=0 -p @ory/opencode ory-opencode install`.
-- **Want to see what's happening** — `npx -y -p @ory/opencode ory-opencode status` for a snapshot, `npx -y -p @ory/opencode ory-opencode watch` for the live trace stream, or set `ORY_AGENT_DEBUG=true` for a verbose log. Traces and logs live under `~/.config/ory-agent-plugins/opencode/` (see [See what's happening](#see-whats-happening)).
 
 ## Learn more
 

package/dist/cli/config.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Shared `opencode.json` mutation helpers for the Ory OpenCode plugin.
+ *
+ * Both CLI entry points (`ory-opencode install` and the `ory-opencode-setup`
+ * fallback binary) write the same two config keys, so the spec construction
+ * and the entry matching live here rather than being transcribed twice.
+ *
+ * ## Why the plugin spec is always a path
+ *
+ * OpenCode never loads an npm plugin from the project's `node_modules`. For an
+ * npm spec it installs the package into its own cache
+ * (`<xdgCache>/opencode/packages/<spec>/node_modules/<pkg>`) and short-circuits
+ * whenever that directory already exists — which produced two failure modes
+ * that were invisible to the user: a successful install was never re-resolved
+ * (so upgrades silently never took effect), and a failed install left an empty
+ * spec directory that was retried identically every session (so hooks never
+ * fired while skills and `/ory:` commands looked perfectly installed).
+ *
+ * Both are gone by construction. The plugin's runtime is resolved once, at
+ * install time, into the shared runtime store, and the spec written here is a
+ * `file://` URL pointing at it — so OpenCode imports the resolved copy
+ * directly, bypassing its cache and any registry. `resolveInstalledPlugin`
+ * remains, purely so `status` can report what will load and flag cache
+ * directories left over from earlier npm-spec installs.
+ */
+export declare const PLUGIN_MODULE = "@ory/opencode";
+export declare const MCP_SERVER_NAME = "ory";
+export declare const OPENCODE_SCHEMA_URL = "https://opencode.ai/config.json";
+/** A `plugin` array entry: a spec, or a `[spec, options]` pair. */
+export type PluginEntry = string | [string, unknown];
+export declare function entrySpec(entry: PluginEntry): string;
+/**
+ * Reduce a plugin spec to the package it points at, so config entries are
+ * matched by identity instead of by exact text. Handles the bare name
+ * (`@ory/opencode`), a pinned version (`@ory/opencode@0.14.0`), and the
+ * `file://…/node_modules/@ory/opencode` form a source install can write — so an
+ * install/uninstall replaces a previously written entry in any of those shapes
+ * rather than leaving a duplicate behind.
+ */
+export declare function pluginSpecName(spec: string): string;
+export declare function isOryPluginEntry(entry: PluginEntry): boolean;
+/**
+ * The spec to write into `opencode.json`: a `file://` URL for the directory the
+ * runtime resolved to.
+ *
+ * A path spec is what makes OpenCode import the copy we resolved rather than
+ * running its own npm install into a cache it then never re-checks.
+ */
+export declare function runtimePluginSpec(packageDir: string): string;
+export declare function mergePlugin(config: Record<string, unknown>, spec: string): Record<string, unknown>;
+export declare function removePlugin(config: Record<string, unknown>): Record<string, unknown>;
+export declare function mergeMcp(config: Record<string, unknown>, command: readonly string[]): Record<string, unknown>;
+export declare function removeMcp(config: Record<string, unknown>): Record<string, unknown>;
+export declare function findOryPluginEntry(config: Record<string, unknown>): PluginEntry | undefined;
+/**
+ * OpenCode's package cache root — `<xdgCache>/opencode`, matching the
+ * `xdg-basedir` resolution it uses internally.
+ */
+export declare function opencodeCacheRoot(): string;
+export declare function isPathSpec(spec: string): boolean;
+export interface ResolvedPlugin {
+    spec: string;
+    source: "file" | "npm";
+    /** Directory OpenCode will import the plugin from, if it exists yet. */
+    dir?: string;
+    /** Version found at `dir`. */
+    version?: string;
+    /**
+     * OpenCode has already created this spec's cache directory. With no `version`
+     * alongside it, that is positive evidence of an install that ran and *failed*
+     * — as opposed to one that has not been attempted yet.
+     */
+    attempted: boolean;
+    /** The spec's cache directory (npm specs only), whether or not it exists. */
+    cacheDir?: string;
+    /**
+     * Other spec directories OpenCode has already cached for this package. A
+     * leftover `@ory/opencode@latest` here is the classic stale-plugin symptom.
+     */
+    otherCached: Array<{
+        spec: string;
+        version?: string;
+    }>;
+}
+/**
+ * Work out which copy of the plugin OpenCode will load for a configured spec,
+ * plus any other copies it has cached. Purely observational — used by `status`
+ * so a stale cache is visible instead of being reported as a healthy install.
+ */
+export declare function resolveInstalledPlugin(spec: string): ResolvedPlugin;

package/dist/cli/config.js

@@ -0,0 +1,267 @@
+"use strict";
+/**
+ * Shared `opencode.json` mutation helpers for the Ory OpenCode plugin.
+ *
+ * Both CLI entry points (`ory-opencode install` and the `ory-opencode-setup`
+ * fallback binary) write the same two config keys, so the spec construction
+ * and the entry matching live here rather than being transcribed twice.
+ *
+ * ## Why the plugin spec is always a path
+ *
+ * OpenCode never loads an npm plugin from the project's `node_modules`. For an
+ * npm spec it installs the package into its own cache
+ * (`<xdgCache>/opencode/packages/<spec>/node_modules/<pkg>`) and short-circuits
+ * whenever that directory already exists — which produced two failure modes
+ * that were invisible to the user: a successful install was never re-resolved
+ * (so upgrades silently never took effect), and a failed install left an empty
+ * spec directory that was retried identically every session (so hooks never
+ * fired while skills and `/ory:` commands looked perfectly installed).
+ *
+ * Both are gone by construction. The plugin's runtime is resolved once, at
+ * install time, into the shared runtime store, and the spec written here is a
+ * `file://` URL pointing at it — so OpenCode imports the resolved copy
+ * directly, bypassing its cache and any registry. `resolveInstalledPlugin`
+ * remains, purely so `status` can report what will load and flag cache
+ * directories left over from earlier npm-spec installs.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OPENCODE_SCHEMA_URL = exports.MCP_SERVER_NAME = exports.PLUGIN_MODULE = void 0;
+exports.entrySpec = entrySpec;
+exports.pluginSpecName = pluginSpecName;
+exports.isOryPluginEntry = isOryPluginEntry;
+exports.runtimePluginSpec = runtimePluginSpec;
+exports.mergePlugin = mergePlugin;
+exports.removePlugin = removePlugin;
+exports.mergeMcp = mergeMcp;
+exports.removeMcp = removeMcp;
+exports.findOryPluginEntry = findOryPluginEntry;
+exports.opencodeCacheRoot = opencodeCacheRoot;
+exports.isPathSpec = isPathSpec;
+exports.resolveInstalledPlugin = resolveInstalledPlugin;
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const node_url_1 = require("node:url");
+exports.PLUGIN_MODULE = "@ory/opencode";
+exports.MCP_SERVER_NAME = "ory";
+exports.OPENCODE_SCHEMA_URL = "https://opencode.ai/config.json";
+function entrySpec(entry) {
+    return typeof entry === "string" ? entry : entry[0];
+}
+/**
+ * Reduce a plugin spec to the package it points at, so config entries are
+ * matched by identity instead of by exact text. Handles the bare name
+ * (`@ory/opencode`), a pinned version (`@ory/opencode@0.14.0`), and the
+ * `file://…/node_modules/@ory/opencode` form a source install can write — so an
+ * install/uninstall replaces a previously written entry in any of those shapes
+ * rather than leaving a duplicate behind.
+ */
+function pluginSpecName(spec) {
+    let raw = spec.trim();
+    if (raw.startsWith("file://")) {
+        try {
+            raw = (0, node_url_1.fileURLToPath)(raw);
+        }
+        catch {
+            raw = raw.slice("file://".length);
+        }
+    }
+    raw = raw.replace(/[/\\]+$/, "");
+    // Strip a trailing `@<version>`, but never the `@` that starts an npm scope
+    // (position 0) or a scope `@` in the middle of a path — a version suffix is
+    // the only one with no path separator after it.
+    const at = raw.lastIndexOf("@");
+    if (at > 0 && !/[/\\]/.test(raw.slice(at + 1)))
+        raw = raw.slice(0, at);
+    const parts = raw.split(/[/\\]/).filter(Boolean);
+    if (parts.length >= 2) {
+        return `${parts[parts.length - 2]}/${parts[parts.length - 1]}`;
+    }
+    return raw;
+}
+function isOryPluginEntry(entry) {
+    return pluginSpecName(entrySpec(entry)) === exports.PLUGIN_MODULE;
+}
+function readVersion(packageRoot) {
+    try {
+        const json = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
+        return typeof json.version === "string" ? json.version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The spec to write into `opencode.json`: a `file://` URL for the directory the
+ * runtime resolved to.
+ *
+ * A path spec is what makes OpenCode import the copy we resolved rather than
+ * running its own npm install into a cache it then never re-checks.
+ */
+function runtimePluginSpec(packageDir) {
+    return (0, node_url_1.pathToFileURL)(packageDir).href;
+}
+function mergePlugin(config, spec) {
+    const merged = { ...config };
+    const plugin = (merged.plugin ?? []).filter((p) => !isOryPluginEntry(p));
+    plugin.push(spec);
+    merged.plugin = plugin;
+    return merged;
+}
+function removePlugin(config) {
+    const merged = { ...config };
+    const plugin = (merged.plugin ?? []).filter((p) => !isOryPluginEntry(p));
+    if (plugin.length === 0) {
+        delete merged.plugin;
+    }
+    else {
+        merged.plugin = plugin;
+    }
+    return merged;
+}
+// OpenCode's config schema uses `mcp` (singular) with a `local` connector
+// shape `{ type: "local", command: [...] }`, not the generic `mcpServers`
+// helper from core. `command` is the resolved runtime's MCP shim, so the server
+// starts from the materialized copy instead of being re-resolved by npx.
+function mergeMcp(config, command) {
+    const merged = { ...config };
+    const mcp = { ...(merged.mcp ?? {}) };
+    mcp[exports.MCP_SERVER_NAME] = { type: "local", command: [...command] };
+    merged.mcp = mcp;
+    return merged;
+}
+function removeMcp(config) {
+    const merged = { ...config };
+    const mcp = { ...(merged.mcp ?? {}) };
+    delete mcp[exports.MCP_SERVER_NAME];
+    if (Object.keys(mcp).length === 0) {
+        delete merged.mcp;
+    }
+    else {
+        merged.mcp = mcp;
+    }
+    return merged;
+}
+function findOryPluginEntry(config) {
+    return (config.plugin ?? []).find(isOryPluginEntry);
+}
+// ─── resolving what OpenCode will actually load ─────────────────────
+/**
+ * OpenCode's package cache root — `<xdgCache>/opencode`, matching the
+ * `xdg-basedir` resolution it uses internally.
+ */
+function opencodeCacheRoot() {
+    const xdg = process.env.XDG_CACHE_HOME?.trim();
+    if (xdg)
+        return path.join(xdg, "opencode");
+    if (process.platform === "win32") {
+        const local = process.env.LOCALAPPDATA?.trim();
+        if (local)
+            return path.join(local, "opencode");
+    }
+    return path.join(os.homedir(), ".cache", "opencode");
+}
+function isPathSpec(spec) {
+    return (spec.startsWith("file://") ||
+        spec.startsWith(".") ||
+        path.isAbsolute(spec) ||
+        /^[A-Za-z]:[\\/]/.test(spec));
+}
+function specToDir(spec) {
+    if (!spec.startsWith("file://"))
+        return spec;
+    try {
+        return (0, node_url_1.fileURLToPath)(spec);
+    }
+    catch {
+        return spec.slice("file://".length);
+    }
+}
+function versionAt(dir) {
+    return readVersion(dir);
+}
+/**
+ * Work out which copy of the plugin OpenCode will load for a configured spec,
+ * plus any other copies it has cached. Purely observational — used by `status`
+ * so a stale cache is visible instead of being reported as a healthy install.
+ */
+function resolveInstalledPlugin(spec) {
+    const packagesDir = path.join(opencodeCacheRoot(), "packages");
+    const scopeDir = path.join(packagesDir, "@ory");
+    const otherCached = [];
+    let entries = [];
+    try {
+        entries = fs.readdirSync(scopeDir);
+    }
+    catch {
+        /* no cache yet */
+    }
+    for (const name of entries) {
+        if (name !== "opencode" && !name.startsWith("opencode@"))
+            continue;
+        const cachedSpec = `@ory/${name}`;
+        if (cachedSpec === spec)
+            continue;
+        otherCached.push({
+            spec: cachedSpec,
+            version: versionAt(path.join(packagesDir, cachedSpec, "node_modules", exports.PLUGIN_MODULE)),
+        });
+    }
+    if (isPathSpec(spec)) {
+        const dir = specToDir(spec);
+        const version = versionAt(dir);
+        return {
+            spec,
+            source: "file",
+            dir: version ? dir : undefined,
+            version,
+            attempted: fs.existsSync(dir),
+            otherCached,
+        };
+    }
+    const specDir = path.join(packagesDir, spec);
+    const dir = path.join(specDir, "node_modules", exports.PLUGIN_MODULE);
+    const version = versionAt(dir);
+    return {
+        spec,
+        source: "npm",
+        dir: version ? dir : undefined,
+        version,
+        attempted: fs.existsSync(specDir),
+        cacheDir: specDir,
+        otherCached,
+    };
+}