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

package/dist/cli.d.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { B as BundleRequest, a as BundleOutput } from './pack-C3ZJx9d4.js';
+import { B as BundleRequest, a as BundleOutput, C as CheckFinding } from './check-62s2GvcO.js';
 
 interface CliDeps {
     load(modulePath: string): Promise<unknown>;
@@ -9,7 +9,14 @@ interface CliDeps {
     cwd?: string;
     /** Replaced in tests so pack does not shell out to a bundler. */
     bundle?(request: BundleRequest): Promise<BundleOutput>;
+    /** Replaced in tests so pack does not start the staged bundle. */
+    launch?(dir: string): Promise<CheckFinding[]>;
+    /** Writes a scaffold file or a receipt; replaced in tests so nothing touches disk. */
+    writeFile?(path: string, contents: string): Promise<void>;
+    /** Replaced in tests beside writeFile. */
+    exists?(path: string): boolean;
 }
 declare function runCli(argv: string[], deps: CliDeps): Promise<number>;
+declare function isEntryPoint(moduleUrl: string, argv?: readonly string[]): boolean;
 
-export { type CliDeps, runCli };
+export { type CliDeps, isEntryPoint, runCli };

package/dist/cli.js

@@ -1,21 +1,26 @@
 #!/usr/bin/env node
 import {
-  checkConnector,
   connectionSetup,
   connectorManifest,
+  esbuildBundle,
   formatFindings,
   packConnector,
   resolveConfig,
+  runConformance,
   runPoll,
+  scaffoldFiles,
   serveConnector
-} from "./chunk-NXZBUV63.js";
+} from "./chunk-ZKHXHE3O.js";
 
 // src/cli.ts
-import { pathToFileURL } from "url";
-import { resolve } from "path";
-var USAGE = `vorn-connector <command> <module> [options]
+import { fileURLToPath, pathToFileURL } from "url";
+import { existsSync, realpathSync } from "fs";
+import { dirname, join, resolve } from "path";
+import { mkdir, writeFile } from "fs/promises";
+var USAGE = `vorn-connector <command> <module | id> [options]
 
 Commands:
+  new <id>                      Scaffold a new connector, ready to build
   manifest <module>             Print the connector manifest as JSON
   setup <module> [trigger]      Print the Vorn connection settings to paste
   check <module>                Verify the connector against Vorn's contract
@@ -27,8 +32,13 @@ Options:
   --since <iso>                 Lower bound passed to poll
   --limit <n>                   Maximum items to request
   --live                        Let check poll for real using the environment
-  --out <dir>                   Directory pack writes the archive to`;
-var BOOLEAN_FLAGS = /* @__PURE__ */ new Set(["live"]);
+  --mock                        Run every action against served HTTP, not the network
+  --receipt <file>              Where check writes what it verified, as JSON
+  --out <dir>                   Directory new and pack write to
+  --name <name>                 Display name for a new connector
+  --repo-conventions            Scaffold a package shaped for the connectors repository
+  --extension                   Scaffold an extension \u2014 footers, panes and link handlers`;
+var BOOLEAN_FLAGS = /* @__PURE__ */ new Set(["live", "mock", "repo-conventions", "extension"]);
 function parseArgs(args) {
   const flags = {};
   const positional = [];
@@ -58,7 +68,7 @@ function pickConnector(loaded, modulePath) {
   const connector = candidate;
   if (!connector || typeof connector !== "object" || !Array.isArray(connector.triggers)) {
     throw new Error(
-      `${modulePath} does not export a connector built with defineConnector() (default or named "connector")`
+      `${modulePath} does not export a connector built with defineConnector() or defineExtension() (default or named "connector")`
     );
   }
   return connector;
@@ -70,11 +80,37 @@ async function runCli(argv, deps) {
     return command ? 0 : 1;
   }
   if (!modulePath) {
-    deps.write(`Missing <module> argument
+    deps.write(`Missing <${command === "new" ? "id" : "module"}> argument
 
 ${USAGE}`);
     return 1;
   }
+  if (command === "new") {
+    const { flags: flags2 } = parseArgs(rest);
+    if (!deps.writeFile) {
+      deps.write("This build cannot write files");
+      return 1;
+    }
+    const files = scaffoldFiles({
+      id: modulePath,
+      ...flags2.name !== void 0 && { name: flags2.name },
+      ...flags2["repo-conventions"] === "true" && { repoConventions: true },
+      ...flags2.extension === "true" && { kind: "extension" }
+    });
+    const root = join(flags2.out ?? deps.cwd ?? ".", modulePath);
+    if ((deps.exists ?? existsSync)(root)) {
+      deps.write(`${root} already exists; a scaffold never overwrites`);
+      return 1;
+    }
+    for (const file of files) {
+      await deps.writeFile(join(root, file.path), file.contents);
+    }
+    deps.write(`Created ${modulePath} in ${root}`);
+    for (const file of files) deps.write(`  ${file.path}`);
+    deps.write(`
+Next: cd ${root} && yarn install && yarn check`);
+    return 0;
+  }
   const connector = pickConnector(await deps.load(modulePath), modulePath);
   const { flags, positional } = parseArgs(rest);
   switch (command) {
@@ -98,14 +134,33 @@ ${USAGE}`);
       return 0;
     }
     case "check": {
-      const findings = await checkConnector(connector, {
+      const packaged = flags.mock === "true" ? {
+        mock: true,
+        packageDir: deps.cwd ?? process.cwd(),
+        entry: modulePath,
+        bundle: deps.bundle ?? esbuildBundle
+      } : {};
+      const run = await runConformance(connector, {
+        ...packaged,
         ...flags.live === "true" && {
           live: true,
           config: resolveConfig(connector, deps.env ?? process.env)
         }
       });
+      const { findings } = run;
       const errors = findings.filter((item) => item.level === "error");
       if (findings.length > 0) deps.write(formatFindings(findings));
+      if (flags.receipt !== void 0) {
+        if (run.receipt) {
+          const write = deps.writeFile ?? ((path, contents) => writeFile(path, contents));
+          await write(flags.receipt, `${JSON.stringify(run.receipt, null, 2)}
+`);
+          deps.write(`Verified ${run.receipt.checks.join(", ")} \u2014 wrote ${flags.receipt}`);
+        } else {
+          deps.write(`No receipt written: nothing could be vouched for`);
+          if (errors.length === 0) return 1;
+        }
+      }
       deps.write(
         errors.length > 0 ? `
 ${errors.length} error(s), ${findings.length - errors.length} warning(s)` : `
@@ -118,7 +173,8 @@ ${connector.id} passed with ${findings.length} warning(s)`
         entry: modulePath,
         ...flags.out !== void 0 && { outDir: flags.out },
         ...deps.cwd !== void 0 && { resolveDir: deps.cwd },
-        ...deps.bundle !== void 0 && { bundle: deps.bundle }
+        ...deps.bundle !== void 0 && { bundle: deps.bundle },
+        ...deps.launch !== void 0 && { launch: deps.launch }
       });
       if (result.findings.length > 0) deps.write(formatFindings(result.findings));
       const errors = result.findings.filter((item) => item.level === "error");
@@ -164,12 +220,25 @@ ${USAGE}`);
       return 1;
   }
 }
-var invokedDirectly = process.argv[1] !== void 0 && import.meta.url === pathToFileURL(resolve(process.argv[1])).href;
+function isEntryPoint(moduleUrl, argv = process.argv) {
+  const invoked = argv[1];
+  if (invoked === void 0) return false;
+  try {
+    return realpathSync(fileURLToPath(moduleUrl)) === realpathSync(resolve(invoked));
+  } catch {
+    return false;
+  }
+}
+var invokedDirectly = isEntryPoint(import.meta.url);
 if (invokedDirectly) {
   runCli(process.argv.slice(2), {
     load: (modulePath) => modulePath.startsWith(".") || modulePath.startsWith("/") ? import(pathToFileURL(resolve(modulePath)).href) : import(modulePath),
     write: (line) => process.stdout.write(`${line}
-`)
+`),
+    writeFile: async (path, contents) => {
+      await mkdir(dirname(path), { recursive: true });
+      await writeFile(path, contents);
+    }
   }).then((code) => {
     process.exitCode = code;
   }).catch((error) => {
@@ -179,5 +248,6 @@ if (invokedDirectly) {
   });
 }
 export {
+  isEntryPoint,
   runCli
 };

package/dist/index.d.ts

@@ -1,7 +1,11 @@
-import { C as ConnectorDefinition, b as Connector, c as ConnectorConfig, T as TriggerDefinition, P as PollContext, d as PollOutcome, e as ConnectorItem, N as NormalizedItem, f as ConnectorIcon, S as StatusSuggestion, D as DefaultWorkflow } from './pack-C3ZJx9d4.js';
-export { A as ActionContext, g as ActionDefinition, h as ActionInputField, a as BundleOutput, B as BundleRequest, i as CheckFinding, j as CheckOptions, k as ConnectorConfigField, l as DedupeStrategy, F as FetchContext, M as MAX_PACK_BYTES, m as PackOptions, n as PackResult, o as PreflightResult, p as bundleDependencyFindings, q as checkConnector, r as formatFindings, s as lifecycleScriptFindings, t as packConnector, u as packFileName, v as readNearestPackageJson } from './pack-C3ZJx9d4.js';
+import { E as ExtensionPermission, b as ExtensionHostMethod, c as ConnectorDefinition, d as Connector, e as ExtensionDefinition, f as ConnectorConfig, g as ExtensionHost, T as TriggerDefinition, P as PollContext, h as PollOutcome, i as ConnectorItem, N as NormalizedItem, j as PostReceiveOp, A as ActionRequest, B as BundleRequest, a as BundleOutput, C as CheckFinding } from './check-62s2GvcO.js';
+export { k as ActionContext, l as ActionDefinition, m as ActionInputField, n as ActionInputOption, o as ActionInputType, p as ActionOutputField, q as ActivationPredicate, r as AuthRung, s as BrowserSignIn, t as CHECK_OWNERS, u as CheckCode, v as CheckOptions, w as ConformanceRun, x as ConnectionSetup, y as ConnectorAuth, z as ConnectorConfigField, D as ConnectorHarness, F as ConnectorIcon, G as ConnectorKind, H as ConnectorManifest, I as ConnectorVerification, J as DedupeStrategy, K as DefaultWorkflow, L as ExtensionAgent, M as ExtensionContext, O as ExtensionContributions, Q as ExtensionPlatform, R as ExtensionUsage, S as ExtensionUsageWindow, U as FetchContext, V as FooterContribution, W as FooterItem, X as HarnessOptions, Y as LinkContext, Z as LinkHandled, _ as LinkHandlerContribution, $ as MANIFEST_TOOL, a0 as MAX_PACK_BYTES, a1 as MAX_POLL_PAGES, a2 as ManifestContributions, a3 as MockCall, a4 as MockHostAnswers, a5 as MockHostRun, a6 as MockRoute, a7 as MockRouteMissError, a8 as MockRun, a9 as OPTIONS_TOOL, aa as OptionsContext, ab as OptionsLoader, ac as PREFLIGHT_TOOL, ad as PaginationStrategy, ae as PaneContribution, af as PollPage, ag as PreflightResult, ah as ResilientFetchOptions, ai as RetryPolicy, aj as RunActionOptions, ak as RunPollOptions, al as SessionContext, am as StatusSuggestion, an as backoffMs, ao as bundleDependencyFindings, ap as bundledRequireFindings, aq as checkConnector, ar as connectionSetup, as as connectorManifest, at as createConnectorHarness, au as drainPoll, av as esbuildBundle, aw as escapedMockHttp, ax as footerToolName, ay as formatFindings, az as handlerToolName, aA as lifecycleScriptFindings, aB as mockExtensionHost, aC as pollToolName, aD as readNearestPackageJson, aE as resilientFetch, aF as retryAfterMs, aG as runAction, aH as runConformance, aI as runOptions, aJ as runPoll, aK as withMockHttp } from './check-62s2GvcO.js';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 
+/** Everything an extension may ask the host for; anything else is not grantable. */
+declare const EXTENSION_PERMISSIONS: ExtensionPermission[];
+/** What each host method costs, read by the bridge that grants it and the check that gates it. */
+declare const HOST_PERMISSIONS: Record<ExtensionHostMethod, ExtensionPermission>;
 /** Environment variable a config field reads from, e.g. `apiToken` → `API_TOKEN`. */
 declare function envNameFor(key: string, explicit?: string): string;
 /**
@@ -12,6 +16,15 @@ declare function envNameFor(key: string, explicit?: string): string;
  * MCP tool once the connector is already installed in someone's app.
  */
 declare function defineConnector(definition: ConnectorDefinition): Connector;
+/**
+ * Validate an extension and fill in its defaults.
+ *
+ * An extension is a pack like a connector, so it goes through the same
+ * manifest, pack, check and catalog; what differs is that it contributes to a
+ * session card rather than polling a service. Failing here — at import time —
+ * keeps a mistyped permission or an unreachable page from reaching a card.
+ */
+declare function defineExtension(definition: ExtensionDefinition): Connector;
 /**
  * Read the connector's declared config out of the environment. Vorn supplies
  * these through the connection's `env` / `secretEnv` maps, so a missing
@@ -20,6 +33,64 @@ declare function defineConnector(definition: ConnectorDefinition): Connector;
  */
 declare function resolveConfig(connector: Connector, env?: NodeJS.ProcessEnv): ConnectorConfig;
 
+/**
+ * How an extension asks the host for what it was granted.
+ *
+ * The extension runs as its own process, so the bridge is an HTTP endpoint the
+ * host serves and names in the environment, with a token that says which
+ * extension is calling. The host grants exactly the permissions the manifest
+ * declared, which is why a call outside them comes back refused rather than
+ * empty — the same answer the check's stub gives, so an extension meets the
+ * rule once rather than twice.
+ */
+/** Where the host answers, and the token that says who is asking. */
+declare const HOST_URL_ENV = "VORN_EXTENSION_HOST";
+declare const HOST_TOKEN_ENV = "VORN_EXTENSION_TOKEN";
+/** The host refused a call the extension's manifest never asked for. */
+declare class PermissionDeniedError extends Error {
+    constructor(method: string, detail: string);
+}
+interface HostBridgeOptions {
+    sessionId: string;
+    env?: NodeJS.ProcessEnv;
+    /** Replaced in tests so nothing opens a socket. */
+    fetchImpl?: typeof fetch;
+}
+/** The host as an extension process reaches it, over the bridge Vorn served it. */
+declare function createExtensionHost(options: HostBridgeOptions): ExtensionHost;
+
+/** Where Vorn serves a browser-sign-in connector the window it signed in through. */
+declare const BROWSER_HOST_ENV = "VORN_BROWSER_HOST";
+declare const BROWSER_TOKEN_ENV = "VORN_BROWSER_TOKEN";
+/** The tool call a window request belongs to, so Vorn can tell a step's own requests from another's. */
+declare const SESSION_CALL_META = "vorn/sessionCall";
+declare const SESSION_CALL_HEADER = "x-vorn-session-call";
+/** The signed-in window could not make the call: Vorn is closed, too old, or not the caller. */
+declare class SessionUnavailableError extends Error {
+    /** Asking again cannot bring the window back, so the SDK's retries let this through at once. */
+    readonly retryable = false;
+    constructor(message: string);
+}
+/** Vorn refused the call itself, for instance because it is off the connector's origins. */
+declare class SessionRefusedError extends Error {
+    readonly retryable = false;
+    constructor(message: string);
+}
+interface SessionFetchOptions {
+    env?: NodeJS.ProcessEnv;
+    /** Replaced in tests so nothing opens a socket. */
+    fetchImpl?: typeof fetch;
+    /** The key of the tool call these requests belong to, from its MCP metadata. */
+    call?: string;
+}
+/** A fetch whose requests run inside the connection's signed-in Vorn window, so no cookie reaches this process. */
+declare function createSessionFetch(options?: SessionFetchOptions): typeof fetch;
+
+/** An origin a connector may act on: `https://host`, or `https://*.host` for every subdomain. */
+declare const ORIGIN_PATTERN: RegExp;
+/** Whether `url` is on one of the declared origins. */
+declare function withinOrigins(origins: readonly string[], url: string): boolean;
+
 /**
  * Run a declarative trigger: call the author's `fetch`, then apply the chosen
  * dedupe strategy.
@@ -46,119 +117,99 @@ declare function normalizeItem(item: ConnectorItem, polledAt: string): Normalize
  */
 declare function normalizeItems(items: ConnectorItem[], polledAt: string): NormalizedItem[];
 
-interface PollPage {
-    items: NormalizedItem[];
-    nextCursor?: string;
-    hasMore: boolean;
-}
-interface RunPollOptions {
-    config?: ConnectorConfig;
-    since?: string;
-    cursor?: string;
-    limit?: number;
-    now?: () => string;
+/** The value at a dotted path, or undefined if any step is missing. */
+declare function valueAt(value: unknown, path: string): unknown;
+/** Run a response through the declared ops, left to right. */
+declare function applyPostReceive(value: unknown, ops: PostReceiveOp[] | undefined): unknown;
+
+interface RequestScope {
+    args: Record<string, unknown>;
+    config: ConnectorConfig;
 }
-/** Longest chain of pages `drainPoll` will follow before calling it a bug. */
-declare const MAX_POLL_PAGES = 1000;
 /**
- * Run one poll page and normalize it. Shared by the MCP server, the CLI and
- * the test harness so all three observe exactly what Vorn will observe.
+ * How a substituted value is written into its surroundings.
+ *
+ * A value's meaning depends on where it lands: a path segment has to be
+ * escaped, a header has characters it may not contain at all. Passing that
+ * decision in means the substitution is made safe once, here, instead of by
+ * every author who interpolates an argument.
  */
-declare function runPoll(connector: Connector, triggerType: string, options?: RunPollOptions): Promise<PollPage>;
+type Substitution = (value: string, source: 'args' | 'config') => string;
 /**
- * Follow `hasMore` to the end of a trigger's backlog. Mirrors how Vorn drains
- * a connector, including its refusal to follow a cursor that does not move —
- * so an author sees the infinite loop in a unit test instead of in the app.
+ * Resolve `{{args.x}}` and `{{config.y}}` inside a value.
+ *
+ * A whole-string placeholder keeps the referenced value's own type, so a body
+ * can carry a number or an object; a placeholder among other text is rendered
+ * into the string. An unset reference resolves to `undefined` on its own and to
+ * the empty string when it is part of a larger one, which is what lets an
+ * optional argument simply not appear.
+ *
+ * With a `substitute`, every resolved value passes through it — including a
+ * whole-string one, which then arrives as text rather than keeping its type,
+ * because a place that needs escaping is a place that holds a string.
  */
-declare function drainPoll(connector: Connector, triggerType: string, options?: RunPollOptions): Promise<NormalizedItem[]>;
-interface RunActionOptions {
-    config?: ConnectorConfig;
-    now?: () => string;
+declare function resolveTemplates(value: unknown, scope: RequestScope, substitute?: Substitution): unknown;
+interface ResolvedRequest {
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
 }
-/**
- * Run an action with its declared inputs validated and coerced. Vorn renders
- * every action argument as a template string, so numbers and booleans arrive
- * as text and have to be converted back here.
- */
-declare function runAction(connector: Connector, actionType: string, args: Record<string, unknown>, options?: RunActionOptions): Promise<Record<string, unknown>>;
-
-/** MCP tool name a trigger is served under. */
-declare function pollToolName(triggerType: string): string;
-/** Tool that reports the connector's manifest and setup hints. */
-declare const MANIFEST_TOOL = "vorn_connector_manifest";
-/**
- * Tool that reports whether the connector can run right now. Present only when
- * the connector declares a `preflight`, so its absence means "nothing to
- * check" rather than "check passed".
- */
-declare const PREFLIGHT_TOOL = "vorn_connector_preflight";
-interface ConnectionSetup {
-    connectorId: string;
-    triggerType: string;
-    /** Values to paste into Vorn's MCP connection form. */
-    filters: {
-        pollTool: string;
-        itemsPath: 'items';
-        idField: 'externalId';
-        timestampField: 'updatedAt';
-        titleField: 'title';
-        urlField: 'url';
-        cursorArg: 'cursor';
-        cursorPath: 'nextCursor';
-    };
-    /** Environment variable names the connector reads. */
-    env: Array<{
-        name: string;
-        required: boolean;
-        secret: boolean;
-        description?: string;
-    }>;
+/** Build the exact call a declared request makes, with its templates resolved. */
+declare function resolveRequest(request: ActionRequest, scope: RequestScope): ResolvedRequest;
+interface SendOptions {
+    fetchImpl: typeof fetch;
 }
 /**
- * Describe how to wire one trigger into a Vorn MCP connection.
+ * The action's result, as Vorn stores it.
  *
- * Every SDK connector normalizes to the same field names, so this mapping is
- * fixed; it is generated rather than documented so a rename in the SDK cannot
- * drift away from the setup instructions users copy. `cursorArg` hands the
- * connector back its own cursor each poll, which is what lets its dedupe
- * strategy — rather than Vorn's timestamp comparison — decide what is new.
+ * A step's output is a record, so a response that is a list becomes `items` —
+ * the name the rest of this SDK already uses for one — and any other bare
+ * value becomes `result`.
  */
-declare function connectionSetup(connector: Connector, triggerType: string): ConnectionSetup;
-interface ConnectorManifest {
-    id: string;
-    name: string;
-    version: string;
-    description?: string;
-    icon?: ConnectorIcon;
-    triggers: Array<{
-        type: string;
-        label: string;
-        description?: string;
-        /** Seeds a connection's status mapping; absent when the connector was silent. */
-        statusMapping?: StatusSuggestion[];
-        /** Seeds the polling workflow created with the connection. */
-        defaultWorkflow?: DefaultWorkflow;
-        setup: ConnectionSetup;
-    }>;
-    actions: Array<{
-        type: string;
-        label: string;
-        description?: string;
-        inputs: Array<{
-            key: string;
-            label: string;
-            type: string;
-            required: boolean;
-        }>;
-    }>;
+declare function asOutput(value: unknown): Record<string, unknown>;
+/** Longest chain of pages a declared request will follow before calling it a bug. */
+declare const MAX_REQUEST_PAGES = 100;
+/** The URL of the next page, as a paged HTTP API states it in its `Link` header. */
+declare function nextLink(header: string | null): string | undefined;
+/** Run a declared request end to end: resolve, send, follow its pages, reshape. */
+declare function executeRequest(request: ActionRequest, postReceive: PostReceiveOp[] | undefined, scope: RequestScope, options: SendOptions): Promise<Record<string, unknown>>;
+
+interface PackOptions {
+    /** Module specifier the connector was loaded from, bundled as the pack entry. */
+    entry: string;
+    /** Directory the `.vorn.tgz` is written to; defaults to the working directory. */
+    outDir?: string;
+    /** Directory module specifiers resolve from; defaults to the working directory. */
+    resolveDir?: string;
+    /** SDK specifier the generated stdio entry imports; overridden in tests. */
+    sdkModule?: string;
+    /** Size ceiling for the written archive; defaults to `MAX_PACK_BYTES`. */
+    maxBytes?: number;
+    /** Size ceiling for what the archive unpacks to; defaults to `MAX_UNPACKED_BYTES`. */
+    maxUnpackedBytes?: number;
+    /** Replaced in tests so packing does not shell out to a bundler. */
+    bundle?(request: BundleRequest): Promise<BundleOutput>;
+    /** Replaced in tests whose subject is the archive rather than the launch; defaults to starting it for real. */
+    launch?(dir: string): Promise<CheckFinding[]>;
+}
+interface PackResult {
+    findings: CheckFinding[];
+    /** Absolute path of the written pack; absent when a gate failed. */
+    file?: string;
+    bytes?: number;
 }
-/** Full machine-readable description of a connector, served over MCP and printed by the CLI. */
-declare function connectorManifest(connector: Connector): ConnectorManifest;
+/** File name Vorn recognizes as a connector pack. */
+declare function packFileName(connector: Connector): string;
+/** The entry is generated, not the author's bin, so every pack launches alike. */
+declare function packConnector(connector: Connector, options: PackOptions): Promise<PackResult>;
 
 interface ConnectorServerOptions {
     /** Resolved connector configuration. Defaults to reading `process.env`. */
     config?: ConnectorConfig;
     now?: () => string;
+    /** The host an extension's contributions talk to; defaults to the bridge Vorn served. */
+    host?(sessionId: string): ExtensionHost;
 }
 /**
  * Expose a connector as an MCP server.
@@ -172,28 +223,36 @@ declare function createConnectorServer(connector: Connector, options?: Connector
 /** Serve a connector on stdio. This is the one line a connector's bin needs. */
 declare function serveConnector(connector: Connector, options?: ConnectorServerOptions): Promise<void>;
 
-interface HarnessOptions {
-    config?: ConnectorConfig;
-    /** Fixed clock, so `updatedAt` defaults and cursors are deterministic. */
-    now?: () => string;
-}
-interface ConnectorHarness {
-    poll(triggerType: string, options?: RunPollOptions): Promise<PollPage>;
-    drain(triggerType: string, options?: RunPollOptions): Promise<NormalizedItem[]>;
-    execute(actionType: string, args?: Record<string, unknown>): Promise<Record<string, unknown>>;
-    manifest(): ConnectorManifest;
-    /**
-     * Poll repeatedly the way Vorn does — carrying the newest `updatedAt`
-     * forward as the watermark — and return only items a real installation
-     * would treat as new. Catches the classic connector bug where a poll
-     * ignores its lower bound and re-delivers the same backlog forever.
-     */
-    pollTwice(triggerType: string, options?: RunPollOptions): Promise<NormalizedItem[]>;
-}
 /**
- * Run a connector in-process, exactly as the MCP server would, without
- * spawning anything. Authors get real assertions in a plain unit test.
+ * The files a new connector starts as.
+ *
+ * A connector is mostly boilerplate — a package that builds, an entry that
+ * serves, a definition, a test that proves it without a network — and getting
+ * that boilerplate right is the slowest part of writing the interesting bit.
+ * Generating it means every connector starts from the same shape, which is
+ * also the shape `check` and `pack` expect to find.
+ *
+ * The files are returned rather than written so the decision of what to write
+ * stays testable, and the writing stays in the CLI.
  */
-declare function createConnectorHarness(connector: Connector, harnessOptions?: HarnessOptions): ConnectorHarness;
+interface ScaffoldOptions {
+    id: string;
+    /** Defaults to the id in title case. */
+    name?: string;
+    description?: string;
+    /** Emit the shape the connectors repository expects of a package inside it. */
+    repoConventions?: boolean;
+    /** What to start: a connector that polls a service, or an extension that contributes to a card. */
+    kind?: 'connector' | 'extension';
+}
+interface ScaffoldFile {
+    /** Relative to the directory the connector is created in. */
+    path: string;
+    contents: string;
+}
+/** `acme-tickets` → `Acme Tickets`, so a generated name reads like a name. */
+declare function titleCase(id: string): string;
+/** Every file a new connector or extension starts with, ready to build, check and pack. */
+declare function scaffoldFiles(options: ScaffoldOptions): ScaffoldFile[];
 
-export { type ConnectionSetup, Connector, ConnectorConfig, ConnectorDefinition, type ConnectorHarness, ConnectorIcon, ConnectorItem, type ConnectorManifest, type ConnectorServerOptions, DefaultWorkflow, type HarnessOptions, MANIFEST_TOOL, MAX_POLL_PAGES, NormalizedItem, PREFLIGHT_TOOL, PollContext, PollOutcome, type PollPage, type RunActionOptions, type RunPollOptions, StatusSuggestion, TriggerDefinition, connectionSetup, connectorManifest, createConnectorHarness, createConnectorServer, defineConnector, drainPoll, envNameFor, normalizeItem, normalizeItems, pollToolName, pollWithDedupe, resolveConfig, runAction, runPoll, serveConnector };
+export { ActionRequest, BROWSER_HOST_ENV, BROWSER_TOKEN_ENV, BundleOutput, BundleRequest, CheckFinding, Connector, ConnectorConfig, ConnectorDefinition, ConnectorItem, type ConnectorServerOptions, EXTENSION_PERMISSIONS, ExtensionDefinition, ExtensionHost, ExtensionHostMethod, ExtensionPermission, HOST_PERMISSIONS, HOST_TOKEN_ENV, HOST_URL_ENV, type HostBridgeOptions, MAX_REQUEST_PAGES, NormalizedItem, ORIGIN_PATTERN, type PackOptions, type PackResult, PermissionDeniedError, PollContext, PollOutcome, PostReceiveOp, type RequestScope, type ResolvedRequest, SESSION_CALL_HEADER, SESSION_CALL_META, type ScaffoldFile, type ScaffoldOptions, type SessionFetchOptions, SessionRefusedError, SessionUnavailableError, type Substitution, TriggerDefinition, applyPostReceive, asOutput, createConnectorServer, createExtensionHost, createSessionFetch, defineConnector, defineExtension, envNameFor, executeRequest, nextLink, normalizeItem, normalizeItems, packConnector, packFileName, pollWithDedupe, resolveConfig, resolveRequest, resolveTemplates, scaffoldFiles, serveConnector, titleCase, valueAt, withinOrigins };