@ontrove/sdk 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @ontrove/sdk
+
+## 0.1.0
+
+Initial release — the connector authoring SDK: `defineConnector`, the `sync(ctx)`
+capability object, the document shape, the local-run harness, and manifest
+validation.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hollyburn Analytics Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,177 @@
+# @ontrove/sdk
+
+The thin standard library for authoring **Trove connectors**. You write a
+`sync(ctx)` that fetches from a source and returns documents; the SDK owns the
+document shape, the typed `ctx` capability object, the watermark/cursor model,
+the local-run harness the CLI drives, and manifest validation.
+
+It is symmetric with the hosted-MCP SDK
+([`@ontrove/mcp`](https://www.npmjs.com/package/@ontrove/mcp)) `defineMcpServer`
+contract: a connector returns documents to be _stored_ (batch `sync`); an MCP
+server returns tool results to be _read live_.
+
+See the full [SDK Reference](https://docs.ontrove.sh/connectors/sdk-reference/),
+the [manifest.json reference](https://docs.ontrove.sh/connectors/manifest/), and
+the [cursors & sources model](https://docs.ontrove.sh/connectors/cursors-and-sources/)
+in the docs.
+
+## Install
+
+```bash
+npm install @ontrove/sdk
+```
+
+## Quickstart
+
+A connector's `index.ts` must `export default defineConnector(...)`. Your `sync`
+fetches from the source and returns documents — each field maps 1:1 onto the
+`IngestDocumentInput` the Mac app pushes via `ingestDocuments`.
+
+### Hacker News front page
+
+```ts
+import { defineConnector } from '@ontrove/sdk';
+
+export default defineConnector({
+  async sync(ctx) {
+    const res = await ctx.fetch('https://hn.algolia.com/api/v1/search?tags=front_page');
+    const { hits } = await res.json();
+    ctx.log(`fetched ${hits.length} front-page stories`);
+
+    return {
+      documents: hits.map((hit) => ({
+        id: hit.objectID, // → externalId; the dedup key
+        title: hit.title,
+        text: hit.story_text ?? hit.title,
+        url: hit.url,
+        author: hit.author,
+        date: new Date(hit.created_at_i * 1000).toISOString(),
+        contentType: 'bookmark',
+      })),
+      // Advance the cursor to the newest story's timestamp.
+      cursor: { type: 'date', value: new Date(hits[0].created_at_i * 1000).toISOString() },
+    };
+  },
+});
+```
+
+### RSS feed (incremental, date watermark)
+
+> `parseRss` / `stripHtml` below are **your own helpers** — the SDK ships no XML
+> parser. Bring your own (e.g. [`fast-xml-parser`](https://www.npmjs.com/package/fast-xml-parser)).
+
+```ts
+import { defineConnector } from '@ontrove/sdk';
+// import { parseRss, stripHtml } from './rss-helpers'; // your own — see note above
+
+export default defineConnector({
+  async sync(ctx) {
+    const feedUrl = ctx.config.feedUrl as string;
+    const since = ctx.cursor.type === 'date' ? new Date(ctx.cursor.value) : new Date(0);
+
+    const res = await ctx.fetch(feedUrl);
+    if (!res.ok) {
+      // Throw to fail the run; the Mac app retries next tick. Already-pushed docs persist.
+      throw new Error(`feed returned ${res.status} ${res.statusText}`);
+    }
+
+    const items = parseRss(await res.text()).filter((i) => new Date(i.pubDate) > since);
+    const documents = items.map((item) => ({
+      id: item.guid,
+      title: item.title,
+      text: stripHtml(item.contentEncoded ?? item.description),
+      url: item.link,
+      author: item.creator ?? feedUrl,
+      date: item.pubDate,
+    }));
+
+    const newest = items[0]?.pubDate;
+    return newest
+      ? { documents, cursor: { type: 'date', value: newest } }
+      : { documents };
+  },
+});
+```
+
+A bare array is accepted too — `return documents;` is shorthand for
+`{ documents }` with no cursor change.
+
+## The `ctx` object
+
+| Member        | Type                                        | Description                                                                 |
+| ------------- | ------------------------------------------- | --------------------------------------------------------------------------- |
+| `ctx.config`  | `C` (typed preferences)                     | The user's setup preferences. **Never credentials.**                        |
+| `ctx.cursor`  | `Watermark` (read-only)                     | The source's current watermark; `{ type: 'none' }` on first sync.           |
+| `ctx.fetch`   | `(url, init?) => Promise<Response>`         | Standard `fetch` — routes through the Mac app's networking.                 |
+| `ctx.log`     | `(...args) => void`                         | Structured log entry, surfaced in connector logs.                           |
+| `ctx.now`     | `() => Date`                                | Injected clock (deterministic under test).                                  |
+
+`ctx.credentials` (Keychain-resolved auth) and `ctx.browser` (Playwright) are
+**proposed**, not part of the shipped contract, and intentionally absent.
+
+## The document shape → `IngestDocumentInput`
+
+`ConnectorDocument` maps 1:1 onto the GraphQL `IngestDocumentInput` wire type:
+
+| `ConnectorDocument` | `IngestDocumentInput` | Required                       |
+| ------------------- | --------------------- | ------------------------------ |
+| `id`                | `externalId`          | **Yes**                        |
+| `title`             | `title`               | No                             |
+| `text`              | `text`                | One of `text` / `audioUrl`     |
+| `audioUrl`          | `audioUrl`            | One of `text` / `audioUrl`     |
+| `url`               | `url`                 | No                             |
+| `author`            | `author`              | No                             |
+| `date`              | `date` (ISO 8601)     | No                             |
+| `tags`              | `tags`                | No                             |
+| `metadata`          | `metadata` (JSON)     | No                             |
+| `contentType`       | `contentType`         | No (default `text`)            |
+
+Dedup is keyed on `(source, id)`, so `sync` is safe to retry — re-returning the
+same `id` is skipped.
+
+## Watermarks
+
+A `Watermark` describes how a source resumes between syncs:
+
+- `{ type: 'date', value }` — time-ordered sources with "since &lt;date&gt;" filtering (RSS, most APIs).
+- `{ type: 'idSet', values, max? }` — monotonic ids, no reliable date filter.
+- `{ type: 'none' }` — re-fetch everything; rely on dedup. Always correct, less efficient.
+
+## Local run harness
+
+`runConnector` is what `trove connector dev` / `trove connector test` call. It
+builds a `ctx`, runs `sync`, validates and dedups the documents:
+
+```ts
+import { runConnector } from '@ontrove/sdk';
+import connector from './index.js';
+
+const { documents, cursor, duplicatesSkipped } = await runConnector(connector, {
+  config: { feedUrl: 'https://example.com/feed.xml' },
+  cursor: { type: 'date', value: '2026-06-01T00:00:00Z' },
+});
+```
+
+## Manifest validation
+
+`validateConnectorManifest` backs `trove connector validate`. It checks required
+fields and the `id`/`version` patterns, and lints `config` for credential-shaped
+keys — the same spirit as the cloud's `validateConfig` (config holds preferences
+only; credentials live in the macOS Keychain).
+
+```ts
+import { validateConnectorManifest } from '@ontrove/sdk';
+
+const { valid, errors } = validateConnectorManifest(manifest);
+if (!valid) throw new Error(errors.join('\n'));
+```
+
+## Support
+
+Guides and the full reference live at [docs.ontrove.sh](https://docs.ontrove.sh).
+
+Report bugs or security issues to <matt@hollyburnanalytics.com>.
+
+## License
+
+Released under the [MIT License](./LICENSE). © 2026 Hollyburn Analytics Inc.

package/dist/define.d.ts

@@ -0,0 +1,49 @@
+/**
+ * `defineConnector` — the single entry point for authoring a Trove connector
+ * (connectors/sdk-reference). It is the symmetric sibling of `defineMcpServer`
+ * in `@ontrove/mcp`.
+ *
+ * It is an identity function with light, eager validation: it confirms the value
+ * is a connector object with a `sync` method, so a typo (`snyc`, a missing
+ * `sync`, a non-function) fails at authoring/deploy time with a clear message
+ * rather than at the first scheduled run. It does **not** execute `sync` — that is
+ * {@link runConnector}'s job.
+ *
+ * @module
+ */
+import type { ConnectorContext, ConnectorDocument, ConnectorSyncResult, TroveConnector } from './types.js';
+/**
+ * Validate and return a connector definition unchanged.
+ *
+ * Using `defineConnector(...)` (rather than a bare `satisfies TroveConnector`)
+ * gives an eager runtime check: the CLI calls this when loading a connector
+ * module so a malformed export is rejected before any sync runs. The returned
+ * value is the same object, with full inferred types preserved.
+ *
+ * @typeParam C - The shape of the connector's typed `ctx.config` preferences.
+ * @param connector - The connector object to validate.
+ * @returns The same connector object.
+ * @throws {Error} If `connector` is not an object with a `sync` function.
+ *
+ * @example
+ * ```ts
+ * export default defineConnector({
+ *   async sync(ctx) {
+ *     const res = await ctx.fetch(ctx.config.feedUrl as string);
+ *     return parseRss(await res.text());
+ *   },
+ * });
+ * ```
+ */
+export declare function defineConnector<C = Record<string, unknown>>(connector: TroveConnector<C>): TroveConnector<C>;
+/**
+ * A connector authored inline as a single `sync` function, for the common case
+ * where the connector has no other members. Equivalent to
+ * `defineConnector({ sync })`.
+ *
+ * @typeParam C - The shape of the connector's typed `ctx.config` preferences.
+ * @param sync - The connector's `sync(ctx)` implementation.
+ * @returns A validated {@link TroveConnector} wrapping `sync`.
+ */
+export declare function defineSync<C = Record<string, unknown>>(sync: (ctx: ConnectorContext<C>) => Promise<ConnectorSyncResult | ConnectorDocument[]>): TroveConnector<C>;
+//# sourceMappingURL=define.d.ts.map

package/dist/define.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../src/define.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACnB,cAAc,EACf,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,eAAe,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACzD,SAAS,EAAE,cAAc,CAAC,CAAC,CAAC,GAC3B,cAAc,CAAC,CAAC,CAAC,CAQnB;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpD,IAAI,EAAE,CAAC,GAAG,EAAE,gBAAgB,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,mBAAmB,GAAG,iBAAiB,EAAE,CAAC,GACrF,cAAc,CAAC,CAAC,CAAC,CAEnB"}

package/dist/define.js

@@ -0,0 +1,57 @@
+/**
+ * `defineConnector` — the single entry point for authoring a Trove connector
+ * (connectors/sdk-reference). It is the symmetric sibling of `defineMcpServer`
+ * in `@ontrove/mcp`.
+ *
+ * It is an identity function with light, eager validation: it confirms the value
+ * is a connector object with a `sync` method, so a typo (`snyc`, a missing
+ * `sync`, a non-function) fails at authoring/deploy time with a clear message
+ * rather than at the first scheduled run. It does **not** execute `sync` — that is
+ * {@link runConnector}'s job.
+ *
+ * @module
+ */
+/**
+ * Validate and return a connector definition unchanged.
+ *
+ * Using `defineConnector(...)` (rather than a bare `satisfies TroveConnector`)
+ * gives an eager runtime check: the CLI calls this when loading a connector
+ * module so a malformed export is rejected before any sync runs. The returned
+ * value is the same object, with full inferred types preserved.
+ *
+ * @typeParam C - The shape of the connector's typed `ctx.config` preferences.
+ * @param connector - The connector object to validate.
+ * @returns The same connector object.
+ * @throws {Error} If `connector` is not an object with a `sync` function.
+ *
+ * @example
+ * ```ts
+ * export default defineConnector({
+ *   async sync(ctx) {
+ *     const res = await ctx.fetch(ctx.config.feedUrl as string);
+ *     return parseRss(await res.text());
+ *   },
+ * });
+ * ```
+ */
+export function defineConnector(connector) {
+    if (connector === null || typeof connector !== 'object') {
+        throw new Error('defineConnector: expected a connector object with a `sync` method');
+    }
+    if (typeof connector.sync !== 'function') {
+        throw new Error('defineConnector: connector must have a `sync(ctx)` function');
+    }
+    return connector;
+}
+/**
+ * A connector authored inline as a single `sync` function, for the common case
+ * where the connector has no other members. Equivalent to
+ * `defineConnector({ sync })`.
+ *
+ * @typeParam C - The shape of the connector's typed `ctx.config` preferences.
+ * @param sync - The connector's `sync(ctx)` implementation.
+ * @returns A validated {@link TroveConnector} wrapping `sync`.
+ */
+export function defineSync(sync) {
+    return defineConnector({ sync });
+}

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `@ontrove/sdk` — the thin standard library for authoring **Trove connectors**.
+ * You write a `sync(ctx)` that fetches from a source and returns documents; the
+ * SDK owns the document shape (which maps 1:1 onto `IngestDocumentInput`), the
+ * typed `ctx` capability object, the watermark/cursor model, the local-run
+ * harness the CLI drives, and manifest validation.
+ *
+ * It is the symmetric sibling of `@ontrove/mcp`: a connector returns documents to
+ * be _stored_ (`defineConnector` + `sync`); an MCP server returns tool results to
+ * be _read live_ (`defineMcpServer`).
+ *
+ * @example
+ * ```ts
+ * import { defineConnector } from '@ontrove/sdk';
+ *
+ * export default defineConnector({
+ *   async sync(ctx) {
+ *     const res = await ctx.fetch('https://hn.algolia.com/api/v1/search?tags=front_page');
+ *     const { hits } = await res.json();
+ *     return hits.map((hit) => ({
+ *       id: hit.objectID,
+ *       title: hit.title,
+ *       text: hit.story_text ?? hit.title,
+ *       url: hit.url,
+ *       author: hit.author,
+ *       date: new Date(hit.created_at_i * 1000).toISOString(),
+ *       contentType: 'bookmark',
+ *     }));
+ *   },
+ * });
+ * ```
+ *
+ * @module
+ */
+export { defineConnector, defineSync } from './define.js';
+export { isCredentialConfigKey, type ManifestValidationResult, validateConnectorManifest, } from './manifest.js';
+export { type RunOptions, type RunResult, runConnector, } from './runtime.js';
+export type { ConnectorContentType, ConnectorContext, ConnectorDocument, ConnectorManifest, ConnectorSyncResult, FetchLike, ManifestConfigField, TroveConnector, Watermark, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EACL,qBAAqB,EACrB,KAAK,wBAAwB,EAC7B,yBAAyB,GAC1B,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,KAAK,UAAU,EACf,KAAK,SAAS,EACd,YAAY,GACb,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,oBAAoB,EACpB,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,EACnB,SAAS,EACT,mBAAmB,EACnB,cAAc,EACd,SAAS,GACV,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,37 @@
+/**
+ * `@ontrove/sdk` — the thin standard library for authoring **Trove connectors**.
+ * You write a `sync(ctx)` that fetches from a source and returns documents; the
+ * SDK owns the document shape (which maps 1:1 onto `IngestDocumentInput`), the
+ * typed `ctx` capability object, the watermark/cursor model, the local-run
+ * harness the CLI drives, and manifest validation.
+ *
+ * It is the symmetric sibling of `@ontrove/mcp`: a connector returns documents to
+ * be _stored_ (`defineConnector` + `sync`); an MCP server returns tool results to
+ * be _read live_ (`defineMcpServer`).
+ *
+ * @example
+ * ```ts
+ * import { defineConnector } from '@ontrove/sdk';
+ *
+ * export default defineConnector({
+ *   async sync(ctx) {
+ *     const res = await ctx.fetch('https://hn.algolia.com/api/v1/search?tags=front_page');
+ *     const { hits } = await res.json();
+ *     return hits.map((hit) => ({
+ *       id: hit.objectID,
+ *       title: hit.title,
+ *       text: hit.story_text ?? hit.title,
+ *       url: hit.url,
+ *       author: hit.author,
+ *       date: new Date(hit.created_at_i * 1000).toISOString(),
+ *       contentType: 'bookmark',
+ *     }));
+ *   },
+ * });
+ * ```
+ *
+ * @module
+ */
+export { defineConnector, defineSync } from './define.js';
+export { isCredentialConfigKey, validateConnectorManifest, } from './manifest.js';
+export { runConnector, } from './runtime.js';

package/dist/manifest.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Connector manifest validation for `trove connector validate`
+ * (see the connectors manifest reference).
+ *
+ * Two checks live here:
+ *
+ * 1. **Shape validation** — required fields (`id`, `name`, `version`), the
+ *    `id` pattern (`^[a-z0-9-]+$`), and well-formedness of `config`.
+ * 2. **Credential-key lint** — the same spirit as the server-side
+ *    `validateConfig` (`src/graphql/validate-config.ts`, invariant #6): a
+ *    connector's `config` holds **user preferences only, never credentials**.
+ *    The cloud rejects writes whose config contains credential-shaped keys, so
+ *    the SDK lints the manifest locally to catch the mistake before deploy. Auth
+ *    material belongs in the (PROPOSED) `auth` block — surfaced from the macOS
+ *    Keychain — not in `config`.
+ *
+ * The deny-list below is kept deliberately identical in spirit to the
+ * authoritative cloud list so the two cannot meaningfully drift.
+ *
+ * @module
+ */
+/**
+ * Whether a single config key looks like a credential and must be rejected.
+ * Mirrors the cloud's `isSensitiveConfigKey`.
+ *
+ * @param key - The config key to test.
+ * @returns True if the key matches a credential pattern.
+ */
+export declare function isCredentialConfigKey(key: string): boolean;
+/**
+ * The outcome of {@link validateConnectorManifest}.
+ */
+export interface ManifestValidationResult {
+    /** True when no errors were found. */
+    valid: boolean;
+    /** Human-readable error messages; empty when `valid` is true. */
+    errors: string[];
+}
+/**
+ * Validate a connector `manifest.json` for `trove connector validate`.
+ *
+ * Checks required fields and the `id`/`version` patterns, validates the `config`
+ * descriptors, and runs the credential-key lint (rejecting credential-shaped
+ * `config` keys — same spirit as the server-side `validateConfig`). Returns a
+ * structured result rather than throwing, so the CLI can print all errors at
+ * once.
+ *
+ * @param manifest - The parsed manifest object to validate.
+ * @returns `{ valid, errors }` — `valid: true` with an empty `errors` array on success.
+ */
+export declare function validateConnectorManifest(manifest: unknown): ManifestValidationResult;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AA+CH;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAG1D;AAuCD;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,sCAAsC;IACtC,KAAK,EAAE,OAAO,CAAC;IACf,iEAAiE;IACjE,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,OAAO,GAAG,wBAAwB,CAkCrF"}

package/dist/manifest.js

@@ -0,0 +1,144 @@
+/**
+ * Connector manifest validation for `trove connector validate`
+ * (see the connectors manifest reference).
+ *
+ * Two checks live here:
+ *
+ * 1. **Shape validation** — required fields (`id`, `name`, `version`), the
+ *    `id` pattern (`^[a-z0-9-]+$`), and well-formedness of `config`.
+ * 2. **Credential-key lint** — the same spirit as the server-side
+ *    `validateConfig` (`src/graphql/validate-config.ts`, invariant #6): a
+ *    connector's `config` holds **user preferences only, never credentials**.
+ *    The cloud rejects writes whose config contains credential-shaped keys, so
+ *    the SDK lints the manifest locally to catch the mistake before deploy. Auth
+ *    material belongs in the (PROPOSED) `auth` block — surfaced from the macOS
+ *    Keychain — not in `config`.
+ *
+ * The deny-list below is kept deliberately identical in spirit to the
+ * authoritative cloud list so the two cannot meaningfully drift.
+ *
+ * @module
+ */
+/**
+ * Credential-shaped key patterns that may NOT appear in a connector's `config`
+ * (invariant #6). Mirrors the authoritative cloud deny-list in
+ * `src/graphql/validate-config.ts`. Matched case-insensitively and
+ * separator-insensitively as substrings, so `apiKey`, `api_key`, `access_token`,
+ * and `refreshToken` all match.
+ */
+const CREDENTIAL_KEY_PATTERNS = [
+    'session',
+    'cookie',
+    'token',
+    'api_key',
+    'apikey',
+    'password',
+    'secret',
+    'auth',
+    'credential',
+    'bearer',
+    'access_key',
+    'private_key',
+];
+/** The `id` pattern: lowercase letters, digits, and hyphens. */
+const ID_RE = /^[a-z0-9-]+$/;
+/** A permissive semver check — `MAJOR.MINOR.PATCH` with optional pre-release/build. */
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:[-+].+)?$/;
+/**
+ * Normalize a config key for credential-pattern matching: lowercase and strip
+ * `_`/`-` separators so `api_key`, `apiKey`, and `api-key` collapse to one form.
+ * Identical to the cloud's `normalizeKey`.
+ *
+ * @param key - The config key to normalize.
+ * @returns The normalized comparable form.
+ */
+function normalizeKey(key) {
+    return key.toLowerCase().replaceAll('_', '').replaceAll('-', '');
+}
+/** Pre-normalized credential patterns, computed once. */
+const NORMALIZED_CREDENTIAL_PATTERNS = CREDENTIAL_KEY_PATTERNS.map(normalizeKey);
+/**
+ * Whether a single config key looks like a credential and must be rejected.
+ * Mirrors the cloud's `isSensitiveConfigKey`.
+ *
+ * @param key - The config key to test.
+ * @returns True if the key matches a credential pattern.
+ */
+export function isCredentialConfigKey(key) {
+    const normalized = normalizeKey(key);
+    return NORMALIZED_CREDENTIAL_PATTERNS.some((pattern) => normalized.includes(pattern));
+}
+/**
+ * Push an error if a required string field is missing or empty.
+ *
+ * @param value - The candidate field value.
+ * @param field - The field name, for the message.
+ * @param errors - The accumulator to append to.
+ */
+function requireString(value, field, errors) {
+    if (typeof value !== 'string' || value.length === 0) {
+        errors.push(`manifest.${field} is required and must be a non-empty string`);
+    }
+}
+/**
+ * Validate the `config` block: each value must be an object descriptor, and no
+ * key may be credential-shaped.
+ *
+ * @param config - The manifest `config` object.
+ * @param errors - The accumulator to append to.
+ */
+function validateConfigBlock(config, errors) {
+    const offending = [];
+    for (const [key, descriptor] of Object.entries(config)) {
+        if (isCredentialConfigKey(key))
+            offending.push(key);
+        if (descriptor === null || typeof descriptor !== 'object' || Array.isArray(descriptor)) {
+            errors.push(`manifest.config.${key} must be a field descriptor object`);
+        }
+    }
+    if (offending.length > 0) {
+        const unique = [...new Set(offending)];
+        errors.push(`manifest.config must not contain credential-shaped key(s): ${unique.join(', ')}. ` +
+            'Connector credentials belong in the macOS Keychain (declared as `auth`), not in `config`.');
+    }
+}
+/**
+ * Validate a connector `manifest.json` for `trove connector validate`.
+ *
+ * Checks required fields and the `id`/`version` patterns, validates the `config`
+ * descriptors, and runs the credential-key lint (rejecting credential-shaped
+ * `config` keys — same spirit as the server-side `validateConfig`). Returns a
+ * structured result rather than throwing, so the CLI can print all errors at
+ * once.
+ *
+ * @param manifest - The parsed manifest object to validate.
+ * @returns `{ valid, errors }` — `valid: true` with an empty `errors` array on success.
+ */
+export function validateConnectorManifest(manifest) {
+    const errors = [];
+    if (manifest === null || typeof manifest !== 'object' || Array.isArray(manifest)) {
+        return { valid: false, errors: ['manifest must be a JSON object'] };
+    }
+    const m = manifest;
+    requireString(m.id, 'id', errors);
+    if (typeof m.id === 'string' && m.id.length > 0 && !ID_RE.test(m.id)) {
+        errors.push('manifest.id must match ^[a-z0-9-]+$ (lowercase letters, digits, hyphens)');
+    }
+    requireString(m.name, 'name', errors);
+    requireString(m.version, 'version', errors);
+    if (typeof m.version === 'string' && m.version.length > 0 && !SEMVER_RE.test(m.version)) {
+        errors.push('manifest.version must be a semver string (e.g. "1.0.0")');
+    }
+    if (m.config !== undefined) {
+        if (m.config === null || typeof m.config !== 'object' || Array.isArray(m.config)) {
+            errors.push('manifest.config must be an object');
+        }
+        else {
+            validateConfigBlock(m.config, errors);
+        }
+    }
+    if (m.needs_browser !== undefined && typeof m.needs_browser !== 'boolean') {
+        errors.push('manifest.needs_browser must be a boolean');
+    }
+    return { valid: errors.length === 0, errors };
+}

package/dist/runtime.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The local-run harness — what makes `trove connector dev` / `trove connector test`
+ * work (connectors/sdk-reference; connectors/cursors-and-sources).
+ *
+ * {@link runConnector} builds a {@link ConnectorContext} from a `{ config, cursor }`
+ * spec, invokes `sync(ctx)`, then normalizes and validates the result: it accepts
+ * either a `ConnectorSyncResult` or a bare `ConnectorDocument[]`, deduplicates by
+ * `id` (first occurrence wins, matching server-side `(source, id)` dedup), and
+ * validates every document's required fields, surfacing problems clearly instead
+ * of pushing a malformed payload to the cloud.
+ *
+ * It is the symmetric sibling of `@ontrove/mcp`'s `dispatch`/`toFetchHandler`: that
+ * runs a tool call end-to-end without the hosted runtime; this runs a connector
+ * sync end-to-end without the Mac app sync engine.
+ *
+ * @module
+ */
+import type { ConnectorDocument, FetchLike, TroveConnector, Watermark } from './types.js';
+/**
+ * The options {@link runConnector} builds a `ctx` from. The CLI passes the
+ * source's stored config and current cursor; tests inject `fetch`, `log`, and
+ * `now` for determinism.
+ *
+ * @typeParam C - The shape of the connector's typed `ctx.config` preferences.
+ */
+export interface RunOptions<C = Record<string, unknown>> {
+    /** The source's preference values (no credentials). Defaults to `{}`. */
+    config?: C;
+    /** The source's current watermark. Defaults to `{ type: 'none' }`. */
+    cursor?: Watermark;
+    /** The fetch implementation to expose as `ctx.fetch`. Defaults to global `fetch`. */
+    fetchImpl?: FetchLike;
+    /** A sink for `ctx.log(...)` calls. Defaults to collecting into the returned `logs`. */
+    logSink?: (args: unknown[]) => void;
+    /** The clock backing `ctx.now()`. Defaults to `() => new Date()`. */
+    now?: () => Date;
+}
+/**
+ * The outcome of {@link runConnector}: the validated, deduped documents, the
+ * resolved cursor, and the captured log lines. Mirrors enough of what the cloud
+ * ingest reports for `trove connector test` to print a useful summary.
+ */
+export interface RunResult {
+    /** The validated, deduped documents `sync` returned. */
+    documents: ConnectorDocument[];
+    /** The cursor `sync` returned, or `{ type: 'none' }` if it returned none. */
+    cursor: Watermark;
+    /** Captured `ctx.log(...)` lines (when no custom `logSink` was supplied). */
+    logs: unknown[][];
+    /** Count of documents dropped as duplicates of an earlier `id`. */
+    duplicatesSkipped: number;
+}
+/**
+ * Run a connector's `sync` against a built `ctx` and collect/validate the result.
+ *
+ * This is the harness the CLI drives for `trove connector dev` / `trove connector
+ * test`: it builds the {@link ConnectorContext} from `{ config, cursor }`, runs
+ * `sync(ctx)`, normalizes a bare-array return, validates every document's
+ * required fields (clear, indexed errors), and dedups by `id`. Errors thrown by
+ * `sync` itself propagate unchanged so the CLI can report a failed run exactly as
+ * the Mac app would.
+ *
+ * @typeParam C - The shape of the connector's typed `ctx.config` preferences.
+ * @param connector - The connector whose `sync` to run.
+ * @param options - The `{ config, cursor }` spec plus test injection points.
+ * @returns The validated, deduped {@link RunResult}.
+ * @throws {Error} If `sync` throws, returns a malformed value, or a document fails validation.
+ */
+export declare function runConnector<C = Record<string, unknown>>(connector: TroveConnector<C>, options?: RunOptions<C>): Promise<RunResult>;
+//# sourceMappingURL=runtime.d.ts.map