@vornrun/connector-sdk 0.7.0-beta.8 → 0.7.0

package/README.md

@@ -84,6 +84,73 @@ await serveConnector(connector)
 
 Publish it like any other package (`"bin": { "acme-connector": "dist/bin.js" }`).
 
+`vorn-connector new acme` writes all of the above — package, entry, definition,
+a test that needs no network — already building, checking and packing.
+
+## Declare an action instead of writing one
+
+Most actions put arguments into a request and keep part of the answer. Say that
+and the SDK does the rest: `{{args.x}}` and `{{config.y}}` are filled in, an
+argument nobody supplied is left out, a failed status is raised with what the
+body said, and `postReceive` reshapes what came back.
+
+```ts
+{
+  type: 'createIssue',
+  label: 'Create issue',
+  idempotent: false,
+  inputs: [{ key: 'title', label: 'Title', required: true }],
+  request: {
+    method: 'POST',
+    url: '{{config.baseUrl}}/issues',
+    headers: { authorization: 'Bearer {{config.apiToken}}' },
+    body: { title: '{{args.title}}' }
+  },
+  // pick · rename · flatten · filter · map, applied left to right.
+  postReceive: [{ op: 'pick', keys: ['id', 'html_url'] }]
+}
+```
+
+Add `paginate` to follow every page rather than the first — `{ kind: 'cursor',
+cursorPath: 'next', param: 'cursor' }`, `{ kind: 'page', param: 'page' }` or
+`{ kind: 'link' }` — and the pages arrive concatenated.
+
+Retry, backoff and rate-limit handling are applied for you, to declared
+requests and to `context.fetch` alike. A read is always retried; a write only
+when the action declares `idempotent: true`, because repeating a create makes a
+second one. Prefer `context.fetch` over the global one in a hand-written action.
+
+## Offer a field the choices it has
+
+A `select` with fixed choices carries them; one whose choices only exist against
+a live connection names a set the connector serves.
+
+Choices are **suggestions, not a closed set**. Vorn draws a picker while the
+value is one of them and its template-aware input whenever it is not, because a
+step is entitled to compute the value from an earlier one — so the served tool
+schema keeps the argument a plain string and lists the choices in its
+description. Your action still receives whatever was finally sent, and it is
+the connector's job to refuse a value it cannot use.
+
+```ts
+options: { channels: async ({ config, fetch }) => ['general', 'random'] },
+actions: [{
+  type: 'post',
+  label: 'Post',
+  inputs: [{ key: 'channel', label: 'Channel', type: 'select', loadOptions: 'channels' }],
+  request: { method: 'POST', url: '{{config.baseUrl}}/post/{{args.channel}}' }
+}]
+```
+
+`loadOptions` is served today but not yet consumed: the SDK registers a
+`vorn_connector_options` tool and answers it, and the manifest carries the set's
+name, but the app does not fetch the list yet — such a field is edited as text
+until it does. Declaring it now is what makes it work then; a field whose
+choices are already known should use `options` instead.
+
+A `json` argument arrives parsed. `builderHint` on a field is a note for whoever
+writes the next connector, not for whoever runs this one.
+
 ## Poll a database instead of an API
 
 Nothing about a trigger is HTTP-specific — it just returns items. A SQL pull
@@ -135,6 +202,25 @@ Two rules make a pull trigger reliable, and the SDK enforces both:
    it. Use `>=` when filtering on `since` and sort ascending; returning a few
    items again is free, because the SDK drops anything already delivered.
 
+## Act through a signed-in window
+
+A service with no API to key can still be reached as the person using it. Declare the `browser` rung with the page to sign in on, the origins the connector may act on, and a check that answers 2xx only while someone is signed in:
+
+```ts
+auth: {
+  rung: 'browser',
+  browser: {
+    signInUrl: 'https://example.com/login',
+    origins: ['https://example.com', 'https://*.example.com'],
+    check: { url: 'https://example.com/api/me', identity: ['name', 'handle'] }
+  }
+}
+```
+
+Vorn opens a window on a browser profile that belongs to one connection, and the person signs in there. The connector's code then gets `ctx.session.fetch` beside `ctx.fetch`. A call through `ctx.session.fetch` runs inside that signed-in window as a same-origin request, so the service sees its own page asking and no cookie reaches the connector. Calls outside `origins` are refused. `ctx.fetch` stays a plain fetch for public reads, such as a feed, which work before anyone signs in. A `browser` connector's declared `request` actions go through the window.
+
+`--mock` serves signed-in calls from the same routes as every other call. A `--live` run from a terminal has no window, so it skips them.
+
 ## Dedupe strategies
 
 `dedupe` tells the SDK how to recognize new items, and it then owns the cursor
@@ -198,6 +284,48 @@ trigger and they are replayed through the real dedupe pipeline, so a connector
 can be checked before anyone has credentials for it; pass `--live` to poll the
 real source instead.
 
+`--mock` is the full gate, and the one to run in CI. It answers every HTTP
+request from routes instead of the network, runs each action on its own
+declared arguments, and asks the questions `pack` asks about the package —
+install-time scripts, and anything that would still need a registry at launch:
+
+```console
+$ npx vorn-connector check ./dist/index.js --mock --receipt verified.json
+Verified manifest, auth, secrets, actions, dedupe, no-lifecycle-scripts, keywords, no-runtime-deps, mock — wrote verified.json
+```
+
+`--receipt <file>` writes what was verified, for a catalog to carry:
+
+```json
+{ "schema": 1, "version": "1.2.0", "checkedAt": "…", "checks": ["manifest", "…"] }
+```
+
+A check that could not run is left out rather than listed as passed, and a
+connector with any error gets no receipt at all.
+
+`--live` additionally asks `preflight` whether the connector can sign in, then
+runs each action that declared `idempotent: true`. Actions that did not are
+never called: a smoke test must leave nothing behind.
+
+In a unit test the same stub is available directly, so an author can assert on
+what their connector sent:
+
+```ts
+const { result, calls } = await harness.withMockHttp(
+  [{ url: '/api/messages', method: 'POST', body: { id: 'm-1' } }],
+  () => harness.execute('post', { text: 'hi' })
+)
+expect(calls[0].url).toBe('https://acme.test/api/messages')
+```
+
+A request no route matches is refused rather than served, so a test says which
+call escaped instead of quietly reaching a real service.
+
+The stub replaces `fetch`, and only `fetch`. A connector that shells out to a
+CLI or opens its own socket is not intercepted by it, so `--mock` reports any
+action the stub never heard from as `mock-not-observed` and leaves `mock` out
+of the receipt rather than vouching for a run it did not see.
+
 ```ts
 {
   type: 'newTicket',
@@ -257,6 +385,23 @@ hand:
 npx vorn-connector setup ./dist/index.js
 ```
 
+### Where a config field is read from
+
+A field is read from the environment variable it names in `env`, or from its
+key in CONSTANT_CASE when it names none — `apiToken` becomes `API_TOKEN`. The
+same rule decides what `--live` reads and what the host must set when it hands
+a connector its credentials, so it is exported rather than kept private:
+
+```ts
+import { envNameFor } from '@vornrun/connector-sdk'
+
+envNameFor('apiToken') // API_TOKEN
+envNameFor('apiToken', 'GH_TOKEN') // GH_TOKEN — an explicit env always wins
+```
+
+Anything computing these names on the host side should call this rather than
+re-implement it, or the two will disagree about a field named `oauth2Token`.
+
 ## Pack it as a file
 
 `vorn-connector pack` builds a single installable file: the manifest plus one
@@ -298,9 +443,125 @@ reads the manifest.
 Paths are filled with `currentColor`, so the icon picks up the surrounding
 text color instead of fighting the theme.
 
+## Extensions
+
+A connector polls a service. An **extension** contributes to a session card
+instead: a footer band under the status bar, a pane beside the terminal, or a
+handler offered when a link in the terminal is clicked. It is the same pack —
+same manifest, same check, same receipt, same catalog — declared with
+`defineExtension` rather than `defineConnector`.
+
+```ts
+import { defineExtension } from '@vornrun/connector-sdk'
+
+export const connector = defineExtension({
+  id: 'review',
+  name: 'Review',
+  description: 'Reads the session',
+  permissions: ['terminal.read'],
+  activates: { workspaceContains: ['package.json'] },
+  footers: [
+    {
+      id: 'checks',
+      title: 'Checks',
+      every: 30,
+      async run(context) {
+        const output = await context.host.output({ lines: 200 })
+        return [{ label: 'tests', value: /FAIL/.test(output) ? 'failing' : 'passing' }]
+      }
+    }
+  ],
+  panes: [{ id: 'report', title: 'Report', web: 'web/report/index.html' }]
+})
+```
+
+Start one with `vorn-connector new review --extension`.
+
+### What it may ask the host for
+
+Every method of `context.host` costs one permission, and the manifest has to
+declare it. A call outside what was declared is refused rather than answered —
+by `check` against its stub host, and by Vorn at run time — so what a person
+agreed to when installing is what the extension can reach.
+
+| Permission           | Host method          | What it grants                       |
+| -------------------- | -------------------- | ------------------------------------ |
+| `git.read`           | `diff()`, `status()` | The worktree's diff and status       |
+| `terminal.read`      | `output()`           | The session's recent terminal output |
+| `terminal.selection` | `selection()`        | The text selected in the terminal    |
+| `terminal.send`      | `send(text)`         | Typing into the session's terminal   |
+| `card.rename`        | `rename(name)`       | Naming the session card              |
+| `agent.usage`        | `usage()`            | Context and provider allowance       |
+
+Ask for only what the extension spends: `check` names a permission that was
+declared and never used.
+
+### Where it shows
+
+`activates` on the extension, and `when` on any one contribution, narrow where
+it appears. Every declared field has to hold, and each is satisfied by any one
+of its values, so an extension is simply absent where it has nothing to say.
+
+```ts
+activates: {
+  workspaceContains: ['Cargo.toml'],   // paths relative to the worktree
+  remoteHost: ['github.com'],
+  agent: ['claude', 'shell'],
+  platform: ['darwin', 'linux']
+}
+```
+
+### What a pane is drawn from
+
+A pane is either a page the pack carries or a program it runs. A page lives
+under `web/` in the package, and the directory it sits in is carried into the
+pack, so its stylesheet and script travel with it. Vorn serves the page and
+answers `bridge/<method>` beside it, on the page's own origin: the page holds no
+token, and Vorn grants the call exactly the permissions the manifest declared,
+knowing from the origin which pane is asking. A program is argv, run in the
+session's worktree and drawn as a terminal.
+
+```js
+const response = await fetch('bridge/output', {
+  method: 'POST',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify({ lines: 200 })
+})
+const output = (await response.json()).result
+```
+
+```ts
+panes: [
+  { id: 'report', title: 'Report', web: 'web/report/index.html' },
+  { id: 'log', title: 'Log', command: ['./bin/log'], when: { agent: ['shell'] } }
+]
+```
+
+### What a link handler is offered for
+
+A handler names the pattern it matches against clicked text, and one example
+link it is for. The example is what `check` runs the handler on, so a handler is
+proved against a link it will really be offered for rather than a made-up one.
+
+```ts
+linkHandlers: [
+  {
+    id: 'pull-request',
+    title: 'Pull request',
+    pattern: 'https://github\\.com/[^/]+/[^/]+/pull/\\d+',
+    example: 'https://github.com/vorn-run/vorn/pull/1',
+    async run(context) {
+      await context.host.send(`Look at ${context.url}`)
+      return { openPane: 'report' }
+    }
+  }
+]
+```
+
 ## CLI
 
 ```
+vorn-connector new <id>                   Scaffold a new connector, ready to build
 vorn-connector manifest <module>          Print the manifest as JSON
 vorn-connector setup <module> [trigger]   Print the Vorn connection settings
 vorn-connector poll <module> <trigger>    Run one poll against the environment
@@ -309,11 +570,15 @@ vorn-connector pack <module>              Build an installable .vorn.tgz pack
 vorn-connector serve <module>             Serve on stdio (what Vorn runs)
 ```
 
-`pack` accepts `--out <dir>`.
+`new` accepts `--out <dir>`, `--name "Display Name"`, `--repo-conventions`,
+which shapes the package the way the connectors repository expects it (scoped
+name, changelog, compiler and test settings), and `--extension`, which
+scaffolds an extension rather than a connector; `pack` accepts `--out <dir>`.
 
 `poll` accepts `--since <iso>` and `--limit <n>`, and reads the connector's
 declared config from your shell environment — the fastest way to confirm
 credentials and field mapping before wiring anything up.
 
-`check` runs against declared `sample` data by default and takes `--live` to
-poll the real source instead.
+`check` runs against declared `sample` data by default. `--mock` serves its
+HTTP and runs every action, `--live` polls the real source and runs the actions
+that are safe to repeat, and `--receipt <file>` writes down what was verified.