@vornrun/connector-sdk 0.7.0-beta.1 → 0.7.0-beta.11

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
@@ -198,6 +265,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 +366,38 @@ 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
+bundled entry with every dependency inlined.
+
+```bash
+npx vorn-connector pack ./dist/index.js --out ./release
+# → release/acme-1.2.3.vorn.tgz
+```
+
+Packing runs `check` first, then two gates a pack must pass: the source package
+declares no install-time scripts, and nothing was left outside the bundle. A
+pack installs by copying files, so it works with no registry reachable — drop
+it on **Settings → Connectors** and Vorn launches it from disk.
+
 ### Ship an icon
 
 Without one, a connector shows the generic MCP glyph and is hard to pick out
@@ -286,16 +427,23 @@ text color instead of fighting the theme.
 ## 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
 vorn-connector check <module>             Verify the connector against the contract
+vorn-connector pack <module>              Build an installable .vorn.tgz pack
 vorn-connector serve <module>             Serve on stdio (what Vorn runs)
 ```
 
+`new` accepts `--out <dir>`, `--name "Display Name"`, and `--repo-conventions`,
+which shapes the package the way the connectors repository expects it (scoped
+name, changelog, compiler and test settings); `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.