@vornrun/connector-sdk 0.6.1 → 0.7.0-beta.10

package/dist/chunk-XOP6JKBX.js

@@ -0,0 +1,2220 @@
+// src/packaging.ts
+import { builtinModules } from "module";
+import { readFileSync } from "fs";
+import { dirname, isAbsolute, join, resolve } from "path";
+var MAX_PACK_BYTES = 8 * 1024 * 1024;
+var LIFECYCLE_SCRIPTS = [
+  "preinstall",
+  "install",
+  "postinstall",
+  "prepare",
+  "prepublish",
+  "prepublishOnly",
+  "postpublish"
+];
+var BUILTINS = new Set(builtinModules);
+function finding(code, target, message) {
+  return { level: "error", code, target, message };
+}
+function lifecycleScriptFindings(pkg) {
+  const scripts = pkg?.scripts;
+  if (!scripts || typeof scripts !== "object") return [];
+  const named = LIFECYCLE_SCRIPTS.filter((name) => typeof scripts[name] === "string");
+  if (named.length === 0) return [];
+  return [
+    finding(
+      "lifecycle-scripts",
+      "package.json",
+      `Remove the ${named.join(", ")} script(s); a pack is installed by copying files, never by running them`
+    )
+  ];
+}
+function bundleDependencyFindings(external) {
+  const specifiers = /* @__PURE__ */ new Set();
+  for (const specifier of external) {
+    if (specifier.startsWith(".") || specifier.startsWith("/")) continue;
+    if (specifier.startsWith("node:") || BUILTINS.has(specifier)) continue;
+    specifiers.add(specifier);
+  }
+  if (specifiers.size === 0) return [];
+  return [
+    finding(
+      "runtime-dependencies",
+      "bundle",
+      `${[...specifiers].sort().join(", ")} stayed outside the bundle; a pack must launch with no install step`
+    )
+  ];
+}
+function packageDirFor(resolveDir, entry) {
+  const from = resolve(resolveDir);
+  if (entry === void 0) return from;
+  return entry.startsWith(".") || isAbsolute(entry) ? dirname(resolve(from, entry)) : from;
+}
+function readNearestPackageJson(fromDir) {
+  let current = resolve(fromDir);
+  for (; ; ) {
+    try {
+      return JSON.parse(readFileSync(join(current, "package.json"), "utf8"));
+    } catch {
+      const parent = dirname(current);
+      if (parent === current) return void 0;
+      current = parent;
+    }
+  }
+}
+function packEntryContents(entry, sdkModule = "@vornrun/connector-sdk") {
+  return [
+    `import { serveConnector } from ${JSON.stringify(sdkModule)}`,
+    `import * as entry from ${JSON.stringify(entry)}`,
+    "const exported = Object.values(entry).find((value) => value && Array.isArray(value.triggers))",
+    `if (!exported) throw new Error(${JSON.stringify(`${entry} exports no connector`)})`,
+    "await serveConnector(exported)",
+    ""
+  ].join("\n");
+}
+async function esbuildBundle(request) {
+  const { build } = await import("esbuild");
+  const result = await build({
+    stdin: {
+      contents: request.contents,
+      resolveDir: request.resolveDir,
+      sourcefile: "vorn-connector-pack.js",
+      loader: "js"
+    },
+    bundle: true,
+    platform: "node",
+    target: "node20",
+    format: "esm",
+    write: false,
+    metafile: true,
+    legalComments: "none"
+  });
+  const output = Object.values(result.metafile.outputs)[0];
+  return {
+    code: result.outputFiles[0].text,
+    external: (output?.imports ?? []).filter((item) => item.external).map((item) => item.path)
+  };
+}
+
+// src/normalize.ts
+var RESERVED_KEYS = [
+  "externalId",
+  "title",
+  "url",
+  "description",
+  "status",
+  "labels",
+  "assignee",
+  "updatedAt"
+];
+var UNSAFE_KEYS = ["__proto__", "constructor", "prototype"];
+function itemExternalId(item) {
+  return String(item.externalId ?? "").trim();
+}
+function itemTimestamp(item, fallback) {
+  return isoTimestamp(item.updatedAt, fallback);
+}
+function isoTimestamp(value, fallback) {
+  if (value === void 0) return fallback;
+  const date = value instanceof Date ? value : new Date(value);
+  if (Number.isNaN(date.getTime())) {
+    throw new Error(`Invalid updatedAt: ${String(value)}`);
+  }
+  return date.toISOString();
+}
+function normalizeItem(item, polledAt) {
+  const externalId = itemExternalId(item);
+  if (!externalId) {
+    throw new Error("Connector item is missing externalId");
+  }
+  if (!item.title || !item.title.trim()) {
+    throw new Error(`Connector item ${externalId} is missing title`);
+  }
+  const extra = {};
+  for (const [key, value] of Object.entries(item.data ?? {})) {
+    if (RESERVED_KEYS.includes(key)) continue;
+    if (UNSAFE_KEYS.includes(key)) continue;
+    extra[key] = value;
+  }
+  return {
+    ...extra,
+    externalId,
+    title: item.title,
+    url: item.url ?? "",
+    description: item.description ?? "",
+    status: item.status ?? "open",
+    labels: item.labels ?? [],
+    ...item.assignee !== void 0 && { assignee: item.assignee },
+    updatedAt: isoTimestamp(item.updatedAt, polledAt)
+  };
+}
+function normalizeItems(items, polledAt) {
+  const seen = /* @__PURE__ */ new Set();
+  return items.map((item) => {
+    const normalized = normalizeItem(item, polledAt);
+    if (seen.has(normalized.externalId)) {
+      throw new Error(`Duplicate externalId "${normalized.externalId}" in one poll page`);
+    }
+    seen.add(normalized.externalId);
+    return normalized;
+  });
+}
+
+// src/dedupe.ts
+var MAX_BOUNDARY_IDS = 500;
+function decodeCursor(cursor, strategy) {
+  if (!cursor) return void 0;
+  let parsed;
+  try {
+    parsed = JSON.parse(cursor);
+  } catch (error) {
+    throw new Error(`Cursor is not valid SDK cursor JSON: ${cursor}`, { cause: error });
+  }
+  const state = parsed;
+  if (!state || typeof state !== "object" || state.v !== 1 || state.s !== strategy) {
+    throw new Error(`Cursor does not belong to the "${strategy}" strategy: ${cursor}`);
+  }
+  const wellFormed = state.s === "timestamp" ? typeof state.t === "string" && Array.isArray(state.ids) && state.ids.every((id) => typeof id === "string") : typeof state.id === "string";
+  if (!wellFormed) {
+    throw new Error(`Cursor is missing the fields the "${strategy}" strategy needs: ${cursor}`);
+  }
+  return state;
+}
+function compare(left, right) {
+  if (left === right) return 0;
+  return left < right ? -1 : 1;
+}
+function page(chronological, context, hadCursor, nextCursor) {
+  const delivered = context.limit === void 0 ? chronological : chronological.slice(0, context.limit);
+  if (delivered.length === 0) {
+    return { items: [], ...context.cursor !== void 0 && { nextCursor: context.cursor } };
+  }
+  return {
+    items: delivered.map((entry) => entry.item),
+    nextCursor: JSON.stringify(nextCursor(delivered)),
+    // Only drain a backlog we know we truncated, and only once a cursor
+    // exists — a first poll should not pull the source's entire history.
+    hasMore: chronological.length > delivered.length && hadCursor
+  };
+}
+function timestampPoll(fetched, state, context, polledAt) {
+  const boundary = state?.t ?? context.since;
+  const seen = new Set(state?.ids ?? []);
+  const fresh = [];
+  const pinnedAlreadySeen = [];
+  for (const item of fetched) {
+    const id = itemExternalId(item);
+    const pinned = item.updatedAt === void 0 && boundary !== void 0;
+    const at = pinned ? boundary : itemTimestamp(item, polledAt);
+    const isNew = boundary === void 0 || at > boundary || at === boundary && !seen.has(id);
+    if (isNew) fresh.push({ item, at, id, ...pinned && { pinned: true } });
+    else if (pinned) pinnedAlreadySeen.push(id);
+  }
+  fresh.sort((left, right) => compare(left.at, right.at) || compare(left.id, right.id));
+  return page(fresh, context, state !== void 0, (delivered) => {
+    const newest = delivered[delivered.length - 1].at;
+    const atNewest = [];
+    for (let i = delivered.length - 1; i >= 0 && delivered[i].at === newest; i -= 1) {
+      atNewest.push(delivered[i].id);
+    }
+    const carried = newest === boundary ? [...seen, ...atNewest] : [
+      ...pinnedAlreadySeen,
+      ...delivered.filter((entry) => entry.pinned).map((entry) => entry.id),
+      ...atNewest
+    ];
+    return { v: 1, s: "timestamp", t: newest, ids: carried.slice(-MAX_BOUNDARY_IDS) };
+  });
+}
+function lastItemPoll(fetched, state, context, polledAt) {
+  const keyed = fetched.map((item) => ({
+    item,
+    at: itemTimestamp(item, polledAt),
+    id: itemExternalId(item)
+  }));
+  const stopAt = state ? keyed.findIndex((entry) => entry.id === state.id) : -1;
+  const chronological = (stopAt === -1 ? keyed : keyed.slice(0, stopAt)).reverse();
+  return page(chronological, context, state !== void 0, (delivered) => ({
+    v: 1,
+    s: "lastItem",
+    id: delivered[delivered.length - 1].id
+  }));
+}
+async function pollWithDedupe(trigger, context) {
+  const strategy = trigger.dedupe;
+  const fetchItems = trigger.fetch;
+  if (!strategy || !fetchItems) {
+    throw new Error(`Trigger ${trigger.type} is not a declarative trigger`);
+  }
+  const polledAt = context.now();
+  if (strategy === "lastItem") {
+    const state2 = decodeCursor(context.cursor, "lastItem");
+    const fetched2 = await runFetch(trigger.type, fetchItems, {
+      config: context.config,
+      ...state2 && { lastItemId: state2.id },
+      ...context.limit !== void 0 && { limit: context.limit },
+      now: context.now,
+      fetch: context.fetch
+    });
+    return lastItemPoll(fetched2, state2, context, polledAt);
+  }
+  const state = decodeCursor(context.cursor, "timestamp");
+  const since = state?.t ?? context.since;
+  const fetched = await runFetch(trigger.type, fetchItems, {
+    config: context.config,
+    ...since !== void 0 && { since },
+    ...context.limit !== void 0 && { limit: context.limit },
+    now: context.now,
+    fetch: context.fetch
+  });
+  return timestampPoll(fetched, state, context, polledAt);
+}
+async function runFetch(type, fetchItems, context) {
+  const fetched = await fetchItems(context);
+  if (!Array.isArray(fetched)) {
+    throw new Error(`Trigger ${type} fetch() did not return an array`);
+  }
+  return fetched;
+}
+
+// src/post-receive.ts
+var UNSAFE_KEYS2 = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function segments(path) {
+  return path.split(".").map((part) => part.trim()).filter((part) => part !== "");
+}
+function valueAt(value, path) {
+  let current = value;
+  for (const key of segments(path)) {
+    if (UNSAFE_KEYS2.has(key)) return void 0;
+    if (Array.isArray(current)) {
+      const index = Number(key);
+      if (!Number.isInteger(index)) return void 0;
+      current = current[index];
+      continue;
+    }
+    if (!isRecord(current)) return void 0;
+    current = Object.prototype.hasOwnProperty.call(current, key) ? current[key] : void 0;
+  }
+  return current;
+}
+function withValueAt(value, path, next) {
+  const keys = segments(path);
+  if (keys.length === 0) return next;
+  const [head, ...rest] = keys;
+  if (UNSAFE_KEYS2.has(head)) return value;
+  if (Array.isArray(value)) {
+    const index = Number(head);
+    if (!Number.isInteger(index)) return value;
+    const copy = [...value];
+    copy[index] = rest.length === 0 ? next : withValueAt(copy[index], rest.join("."), next);
+    return copy;
+  }
+  const base = isRecord(value) ? value : {};
+  return {
+    ...base,
+    [head]: rest.length === 0 ? next : withValueAt(base[head], rest.join("."), next)
+  };
+}
+function pick(value, keys) {
+  if (Array.isArray(value)) return value.map((entry) => pick(entry, keys));
+  if (!isRecord(value)) return value;
+  const out = {};
+  for (const key of keys) {
+    if (UNSAFE_KEYS2.has(key)) continue;
+    if (Object.prototype.hasOwnProperty.call(value, key)) out[key] = value[key];
+  }
+  return out;
+}
+function rename(value, from, to) {
+  if (Array.isArray(value)) return value.map((entry) => rename(entry, from, to));
+  if (!isRecord(value)) return value;
+  if (UNSAFE_KEYS2.has(from) || UNSAFE_KEYS2.has(to)) return value;
+  if (!Object.prototype.hasOwnProperty.call(value, from)) return value;
+  const out = {};
+  for (const [key, entry] of Object.entries(value)) {
+    if (key === from) out[to] = entry;
+    else if (key !== to) out[key] = entry;
+  }
+  return out;
+}
+function applyOp(value, op) {
+  if (op.op === "flatten") return valueAt(value, op.path);
+  const target = op.path === void 0 ? value : valueAt(value, op.path);
+  if (op.path !== void 0 && target === void 0) return value;
+  let next;
+  if (op.op === "pick") next = pick(target, op.keys);
+  else if (op.op === "rename") next = rename(target, op.from, op.to);
+  else if (op.op === "filter") {
+    next = Array.isArray(target) ? target.filter((entry) => isRecord(entry) && valueAt(entry, op.key) === op.equals) : target;
+  } else {
+    next = Array.isArray(target) ? target.map((entry) => applyPostReceive(entry, op.ops)) : target;
+  }
+  return op.path === void 0 ? next : withValueAt(value, op.path, next);
+}
+function applyPostReceive(value, ops) {
+  return (ops ?? []).reduce(applyOp, value);
+}
+
+// src/request.ts
+var MAX_ERROR_BODY = 500;
+var PLACEHOLDER = /\{\{\s*(args|config)\.([A-Za-z0-9_.-]+)\s*\}\}/g;
+var WHOLE_PLACEHOLDER = /^\{\{\s*(args|config)\.([A-Za-z0-9_.-]+)\s*\}\}$/;
+function lookup(source, path, scope) {
+  return valueAt(source === "args" ? scope.args : scope.config, path);
+}
+var intoUrl = (value, source) => source === "config" ? value : encodeURIComponent(value);
+function intoHeader(name) {
+  return (value) => {
+    if (/[\r\n]/.test(value)) {
+      throw new Error(`Header "${name}" would carry a line ending, which is not allowed`);
+    }
+    return value;
+  };
+}
+function resolveTemplates(value, scope, substitute) {
+  if (typeof value === "string") {
+    const whole = WHOLE_PLACEHOLDER.exec(value);
+    if (whole) {
+      const resolved = lookup(whole[1], whole[2], scope);
+      if (substitute === void 0 || resolved === void 0 || resolved === null) return resolved;
+      return substitute(String(resolved), whole[1]);
+    }
+    return value.replace(PLACEHOLDER, (_match, source, path) => {
+      const resolved = lookup(source, path, scope);
+      if (resolved === void 0 || resolved === null) return "";
+      const text = String(resolved);
+      return substitute === void 0 ? text : substitute(text, source);
+    });
+  }
+  if (Array.isArray(value)) return value.map((entry) => resolveTemplates(entry, scope, substitute));
+  if (typeof value === "object" && value !== null) {
+    const out = {};
+    for (const [key, entry] of Object.entries(value)) {
+      out[key] = resolveTemplates(entry, scope, substitute);
+    }
+    return out;
+  }
+  return value;
+}
+function resolveHeaders(raw, scope) {
+  const out = {};
+  for (const [name, value] of Object.entries(raw ?? {})) {
+    const resolved = resolveTemplates(value, scope, intoHeader(name));
+    if (resolved === void 0 || resolved === null || resolved === "") continue;
+    out[name] = String(resolved);
+  }
+  return out;
+}
+function stringMap(raw) {
+  const out = {};
+  if (typeof raw !== "object" || raw === null) return out;
+  for (const [key, value] of Object.entries(raw)) {
+    if (value === void 0 || value === null || value === "") continue;
+    out[key] = String(value);
+  }
+  return out;
+}
+function resolveRequest(request, scope) {
+  const method = (request.method ?? "GET").toUpperCase();
+  const rawUrl = resolveTemplates(request.url, scope, intoUrl);
+  if (typeof rawUrl !== "string" || rawUrl.trim() === "") {
+    throw new Error("Request has no URL once its templates are resolved");
+  }
+  let url;
+  try {
+    url = new URL(rawUrl);
+  } catch {
+    throw new Error(`Request URL is not a URL once its templates are resolved: "${rawUrl}"`);
+  }
+  for (const [key, value] of Object.entries(stringMap(resolveTemplates(request.query, scope)))) {
+    url.searchParams.set(key, value);
+  }
+  const headers = resolveHeaders(request.headers, scope);
+  const resolved = { url: url.toString(), method, headers };
+  if (request.body !== void 0 && method !== "GET" && method !== "HEAD") {
+    const body = resolveTemplates(request.body, scope);
+    if (body !== void 0) {
+      resolved.body = typeof body === "string" ? body : JSON.stringify(body);
+      if (!Object.keys(headers).some((key) => key.toLowerCase() === "content-type")) {
+        resolved.headers["content-type"] = typeof body === "string" ? "text/plain" : "application/json";
+      }
+    }
+  }
+  return resolved;
+}
+async function readBody(response) {
+  const text = await response.text();
+  if (text === "") return void 0;
+  const type = response.headers.get("content-type") ?? "";
+  if (!type.includes("json")) return text;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+function describeFailure(response, body) {
+  const detail = typeof body === "string" ? body : body === void 0 ? "" : JSON.stringify(body);
+  const quoted = detail.length > MAX_ERROR_BODY ? `${detail.slice(0, MAX_ERROR_BODY)}\u2026` : detail;
+  return `Request failed with ${response.status} ${response.statusText}${quoted ? `: ${quoted}` : ""}`;
+}
+async function sendRequest(resolved, options) {
+  const response = await options.fetchImpl(resolved.url, {
+    method: resolved.method,
+    headers: resolved.headers,
+    ...resolved.body !== void 0 && { body: resolved.body }
+  });
+  const body = await readBody(response);
+  if (!response.ok) throw new Error(describeFailure(response, body));
+  return { response, body };
+}
+function asOutput(value) {
+  if (Array.isArray(value)) return { items: value };
+  if (typeof value === "object" && value !== null) return value;
+  return value === void 0 ? {} : { result: value };
+}
+var MAX_REQUEST_PAGES = 100;
+var LINK_NEXT = /<([^>]+)>\s*;[^,]*\brel\s*=\s*"?next"?/i;
+function nextLink(header) {
+  const match = header === null ? null : LINK_NEXT.exec(header);
+  return match ? match[1] : void 0;
+}
+function pageItems(body, itemsPath) {
+  const value = itemsPath === void 0 ? body : valueAt(body, itemsPath);
+  return Array.isArray(value) ? value : void 0;
+}
+async function collectPages(request, strategy, scope, options) {
+  const collected = [];
+  const seen = /* @__PURE__ */ new Set();
+  let page2 = strategy.kind === "page" ? strategy.startPage ?? 1 : 0;
+  let cursor;
+  let nextUrl;
+  for (let index = 0; index < MAX_REQUEST_PAGES; index++) {
+    const resolved = resolveRequest(request, scope);
+    if (nextUrl !== void 0) resolved.url = nextUrl;
+    if (strategy.kind === "cursor" && cursor !== void 0) {
+      const url = new URL(resolved.url);
+      url.searchParams.set(strategy.param, cursor);
+      resolved.url = url.toString();
+    }
+    if (strategy.kind === "page") {
+      const url = new URL(resolved.url);
+      url.searchParams.set(strategy.param, String(page2));
+      resolved.url = url.toString();
+    }
+    if (seen.has(resolved.url)) {
+      throw new Error(`Request for ${request.url} asked for the same page twice`);
+    }
+    seen.add(resolved.url);
+    const { response, body } = await sendRequest(resolved, options);
+    const items = pageItems(body, strategy.itemsPath);
+    if (items === void 0) {
+      if (index === 0) {
+        const where = strategy.itemsPath === void 0 ? "the response is not a list" : `the response has no list at "${strategy.itemsPath}"`;
+        throw new Error(`Cannot page through this request: ${where}`);
+      }
+      return collected;
+    }
+    collected.push(...items);
+    if (items.length === 0) return collected;
+    if (strategy.kind === "cursor") {
+      const next = valueAt(body, strategy.cursorPath);
+      if (next === void 0 || next === null || next === "") return collected;
+      cursor = String(next);
+      continue;
+    }
+    if (strategy.kind === "link") {
+      nextUrl = nextLink(response.headers.get("link"));
+      if (nextUrl === void 0) return collected;
+      continue;
+    }
+    page2 += 1;
+  }
+  throw new Error(`Request for ${request.url} exceeded ${MAX_REQUEST_PAGES} pages`);
+}
+async function executeRequest(request, postReceive, scope, options) {
+  if (request.paginate) {
+    const items = await collectPages(request, request.paginate, scope, options);
+    return asOutput(applyPostReceive(items, postReceive));
+  }
+  const { body } = await sendRequest(resolveRequest(request, scope), options);
+  return asOutput(applyPostReceive(body, postReceive));
+}
+
+// src/resilience.ts
+var RETRYABLE_STATUS = /* @__PURE__ */ new Set([408, 425, 429, 500, 502, 503, 504]);
+var DEFAULT_ATTEMPTS = 3;
+var DEFAULT_BASE_DELAY_MS = 250;
+var DEFAULT_MAX_DELAY_MS = 3e4;
+var MAX_ATTEMPTS = 10;
+var MAX_TOTAL_WAIT_MS = 12e4;
+var wait = (ms) => new Promise((resolve3) => {
+  setTimeout(resolve3, ms);
+});
+function retryAfterMs(header, now) {
+  if (!header) return void 0;
+  const trimmed = header.trim();
+  if (trimmed === "") return void 0;
+  const seconds = Number(trimmed);
+  if (Number.isFinite(seconds)) return Math.max(0, seconds * 1e3);
+  const at = Date.parse(trimmed);
+  if (Number.isNaN(at)) return void 0;
+  return Math.max(0, at - now);
+}
+function backoffMs(attempt, policy = {}) {
+  const base = policy.baseDelayMs ?? DEFAULT_BASE_DELAY_MS;
+  const max = policy.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
+  return Math.min(max, base * 2 ** attempt);
+}
+function resilientFetch(options) {
+  const attempts = Math.min(MAX_ATTEMPTS, Math.max(1, options.retry?.attempts ?? DEFAULT_ATTEMPTS));
+  const sleep = options.sleep ?? wait;
+  const ceiling = options.retry?.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
+  const send = async (input, init) => {
+    let waited = 0;
+    const pause = async (ms) => {
+      if (waited + ms > MAX_TOTAL_WAIT_MS) return false;
+      waited += ms;
+      await sleep(ms);
+      return true;
+    };
+    for (let attempt = 0; attempt < attempts; attempt++) {
+      const last = attempt === attempts - 1;
+      try {
+        const response = await options.fetchImpl(input, init);
+        if (!RETRYABLE_STATUS.has(response.status)) return response;
+        if (!options.retryable || last) return response;
+        const asked = retryAfterMs(response.headers.get("retry-after"), Date.now());
+        const delay = asked === void 0 ? backoffMs(attempt, options.retry) : Math.min(asked, ceiling);
+        if (!await pause(delay)) return response;
+      } catch (error) {
+        if (!options.retryable || last) throw error;
+        if (!await pause(backoffMs(attempt, options.retry))) throw error;
+      }
+    }
+    throw new Error("Request was never attempted");
+  };
+  return send;
+}
+
+// src/runtime.ts
+var MAX_POLL_PAGES = 1e3;
+async function runPoll(connector, triggerType, options = {}) {
+  const trigger = connector.triggers.find((entry) => entry.type === triggerType);
+  if (!trigger) {
+    throw new Error(`Connector ${connector.id} has no trigger "${triggerType}"`);
+  }
+  const now = options.now ?? (() => (/* @__PURE__ */ new Date()).toISOString());
+  const polledAt = now();
+  const context = {
+    config: options.config ?? {},
+    ...options.since !== void 0 && { since: options.since },
+    ...options.cursor !== void 0 && { cursor: options.cursor },
+    ...options.limit !== void 0 && { limit: options.limit },
+    now,
+    // A poll only reads, so every failure it meets is worth trying again.
+    fetch: resilientFetch({
+      fetchImpl: options.fetchImpl ?? globalThis.fetch,
+      retryable: true,
+      ...options.retry !== void 0 && { retry: options.retry },
+      ...options.sleep !== void 0 && { sleep: options.sleep }
+    })
+  };
+  const outcome = typeof trigger.poll === "function" ? await trigger.poll(context) : await pollWithDedupe(trigger, context);
+  if (!outcome || !Array.isArray(outcome.items)) {
+    throw new Error(`Trigger ${triggerType} did not return an items array`);
+  }
+  if (outcome.hasMore && !outcome.nextCursor) {
+    throw new Error(`Trigger ${triggerType} reported more pages without a nextCursor`);
+  }
+  return {
+    items: normalizeItems(outcome.items, polledAt),
+    ...outcome.nextCursor !== void 0 && { nextCursor: outcome.nextCursor },
+    hasMore: outcome.hasMore === true
+  };
+}
+async function drainPoll(connector, triggerType, options = {}) {
+  const collected = [];
+  let cursor = options.cursor;
+  for (let page2 = 0; page2 < MAX_POLL_PAGES; page2++) {
+    const result = await runPoll(connector, triggerType, {
+      ...options,
+      ...cursor !== void 0 && { cursor }
+    });
+    collected.push(...result.items);
+    if (!result.hasMore) return collected;
+    if (result.nextCursor === cursor) {
+      throw new Error(`Trigger ${triggerType} did not advance its cursor`);
+    }
+    cursor = result.nextCursor;
+  }
+  throw new Error(`Trigger ${triggerType} exceeded ${MAX_POLL_PAGES} pages`);
+}
+var SAFE_METHODS = /* @__PURE__ */ new Set(["GET", "HEAD"]);
+async function runOptions(connector, name, options = {}) {
+  const loader = connector.options?.[name];
+  if (!loader) {
+    throw new Error(`Connector ${connector.id} serves no options set "${name}"`);
+  }
+  const loaded = await loader({
+    config: options.config ?? {},
+    now: options.now ?? (() => (/* @__PURE__ */ new Date()).toISOString()),
+    fetch: resilientFetch({
+      fetchImpl: options.fetchImpl ?? globalThis.fetch,
+      retryable: true,
+      ...options.retry !== void 0 && { retry: options.retry },
+      ...options.sleep !== void 0 && { sleep: options.sleep }
+    })
+  });
+  if (!Array.isArray(loaded)) {
+    throw new Error(`Options set "${name}" did not return an array`);
+  }
+  return loaded.map(
+    (entry) => typeof entry === "string" ? { value: entry } : { ...entry, value: String(entry.value) }
+  );
+}
+var MAX_QUOTED_VALUE = 80;
+function quote(value) {
+  return value.length > MAX_QUOTED_VALUE ? `${value.slice(0, MAX_QUOTED_VALUE)}\u2026` : value;
+}
+function coerceArg(value, type) {
+  if (typeof value !== "string") return value;
+  if (type === "number") {
+    const parsed = Number(value);
+    if (Number.isNaN(parsed)) throw new Error(`Expected a number, got "${quote(value)}"`);
+    return parsed;
+  }
+  if (type === "boolean") {
+    if (value === "true") return true;
+    if (value === "false") return false;
+    throw new Error(`Expected a boolean, got "${quote(value)}"`);
+  }
+  if (type === "json") {
+    try {
+      return JSON.parse(value);
+    } catch {
+      throw new Error(`Expected JSON, got "${quote(value)}"`);
+    }
+  }
+  return value;
+}
+async function runAction(connector, actionType, args, options = {}) {
+  const action = connector.actions.find((entry) => entry.type === actionType);
+  if (!action) {
+    throw new Error(`Connector ${connector.id} has no action "${actionType}"`);
+  }
+  const coerced = { ...args };
+  for (const input of action.inputs ?? []) {
+    const value = coerced[input.key];
+    if (value === void 0 || value === "") {
+      if (input.required) throw new Error(`Action ${actionType} requires "${input.key}"`);
+      delete coerced[input.key];
+      continue;
+    }
+    try {
+      coerced[input.key] = coerceArg(value, input.type);
+    } catch (error) {
+      throw new Error(
+        `Action ${actionType} argument "${input.key}": ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
+      );
+    }
+  }
+  const config = options.config ?? {};
+  const method = (action.request?.method ?? "GET").toUpperCase();
+  const retryable = action.idempotent === true || action.request !== void 0 && SAFE_METHODS.has(method);
+  const fetchImpl = resilientFetch({
+    fetchImpl: options.fetchImpl ?? globalThis.fetch,
+    retryable,
+    ...options.retry !== void 0 && { retry: options.retry },
+    ...options.sleep !== void 0 && { sleep: options.sleep }
+  });
+  if (action.request !== void 0) {
+    try {
+      return await executeRequest(
+        action.request,
+        action.postReceive,
+        { args: coerced, config },
+        { fetchImpl }
+      );
+    } catch (error) {
+      throw new Error(
+        `Action ${actionType}: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
+      );
+    }
+  }
+  if (typeof action.run !== "function") {
+    throw new Error(`Action ${actionType} has neither a run() implementation nor a request`);
+  }
+  const output = await action.run(coerced, {
+    config,
+    now: options.now ?? (() => (/* @__PURE__ */ new Date()).toISOString()),
+    fetch: fetchImpl
+  });
+  return output ?? {};
+}
+
+// src/define.ts
+var KEY_PATTERN = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
+var PATH_DATA_PATTERN = /^[MmZzLlHhVvCcSsQqTtAa0-9\s,.\-+eE]+$/;
+var VIEW_BOX_PATTERN = /^-?[\d.]+\s+-?[\d.]+\s+-?[\d.]+\s+-?[\d.]+$/;
+var DEDUPE_STRATEGIES = ["timestamp", "lastItem"];
+var AUTH_RUNGS = ["none", "cli", "key", "oauth"];
+var ABSOLUTE_URL_PATTERN = /^https?:\/\//i;
+var CONFIG_ROOTED_URL_PATTERN = /^\{\{\s*config\./;
+function assertUnique(kind, keys) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const key of keys) {
+    if (seen.has(key)) throw new Error(`Duplicate ${kind} "${key}"`);
+    seen.add(key);
+  }
+}
+function assertAuth(definition) {
+  const auth = definition.auth;
+  if (!auth) return;
+  const id = definition.id;
+  if (!AUTH_RUNGS.includes(auth.rung)) {
+    throw new Error(
+      `Connector ${id} declares unknown auth rung ${JSON.stringify(auth.rung)}; expected ${AUTH_RUNGS.join(", ")}`
+    );
+  }
+  if (auth.rung === "cli" && !auth.probe?.command?.trim()) {
+    throw new Error(`Connector ${id} borrows a CLI login but declares no probe command to ask it`);
+  }
+  if (auth.rung === "key") {
+    const keys = auth.keys ?? [];
+    if (keys.length === 0) {
+      throw new Error(`Connector ${id} signs in with a key but names no config field holding it`);
+    }
+    const declared = new Set((definition.config ?? []).map((field) => field.key));
+    for (const key of keys) {
+      if (!declared.has(key)) {
+        throw new Error(`Connector ${id} names auth key "${key}", which is not a config field`);
+      }
+    }
+  }
+  if (auth.rung === "none") {
+    const secret = (definition.config ?? []).find((field) => field.secret === true);
+    if (secret) {
+      throw new Error(
+        `Connector ${id} claims it needs no sign-in but declares secret field "${secret.key}"`
+      );
+    }
+  }
+}
+function envNameFor(key, explicit) {
+  if (explicit) return explicit;
+  return key.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/[-\s]+/g, "_").toUpperCase();
+}
+function defineConnector(definition) {
+  if (!KEY_PATTERN.test(definition.id ?? "")) {
+    throw new Error(`Connector id "${definition.id}" must start with a letter and be url-safe`);
+  }
+  if (!definition.name?.trim()) {
+    throw new Error(`Connector ${definition.id} is missing a name`);
+  }
+  if (definition.icon) {
+    const { viewBox, paths } = definition.icon;
+    if (!Array.isArray(paths) || paths.length === 0) {
+      throw new Error(`Connector ${definition.id} has an icon with no paths`);
+    }
+    for (const path of paths) {
+      if (typeof path !== "string" || !PATH_DATA_PATTERN.test(path)) {
+        throw new Error(
+          `Connector ${definition.id} has an icon path that is not SVG path data. Only path data is accepted, not markup.`
+        );
+      }
+    }
+    if (viewBox !== void 0 && !VIEW_BOX_PATTERN.test(viewBox)) {
+      throw new Error(`Connector ${definition.id} has an icon viewBox that is not four numbers`);
+    }
+  }
+  const triggers = definition.triggers ?? [];
+  const actions = definition.actions ?? [];
+  if (triggers.length === 0 && actions.length === 0) {
+    throw new Error(`Connector ${definition.id} declares no triggers and no actions`);
+  }
+  for (const trigger of triggers) {
+    if (!KEY_PATTERN.test(trigger.type ?? "")) {
+      throw new Error(`Trigger type "${trigger.type}" must start with a letter and be url-safe`);
+    }
+    const loose = trigger;
+    const declarative = typeof loose.fetch === "function";
+    const imperative = typeof loose.poll === "function";
+    if (declarative && imperative) {
+      throw new Error(`Trigger ${trigger.type} declares both fetch() and poll(); pick one`);
+    }
+    if (declarative !== (loose.dedupe !== void 0)) {
+      throw new Error(
+        `Trigger ${trigger.type} needs fetch() and a dedupe strategy together, not one alone`
+      );
+    }
+    if (loose.dedupe !== void 0 && !DEDUPE_STRATEGIES.includes(loose.dedupe)) {
+      throw new Error(
+        `Trigger ${trigger.type} has unknown dedupe strategy ${JSON.stringify(loose.dedupe)}; expected ${DEDUPE_STRATEGIES.join(" or ")}`
+      );
+    }
+    if (loose.poll !== void 0 && !imperative) {
+      throw new Error(`Trigger ${trigger.type} declares poll but it is not a function`);
+    }
+    if (!declarative && !imperative) {
+      throw new Error(`Trigger ${trigger.type} is missing a fetch() or poll() implementation`);
+    }
+  }
+  for (const action of actions) {
+    if (!KEY_PATTERN.test(action.type ?? "")) {
+      throw new Error(`Action type "${action.type}" must start with a letter and be url-safe`);
+    }
+    const loose = action;
+    const written = typeof loose.run === "function";
+    const declared = loose.request !== void 0;
+    if (written && declared) {
+      throw new Error(`Action ${action.type} declares both run() and a request; pick one`);
+    }
+    if (!written && !declared) {
+      throw new Error(`Action ${action.type} is missing a run() implementation or a request`);
+    }
+    if (declared) {
+      const request = loose.request;
+      if (typeof request?.url !== "string" || request.url.trim() === "") {
+        throw new Error(`Action ${action.type} declares a request with no URL`);
+      }
+      const url = request.url.trim();
+      if (!ABSOLUTE_URL_PATTERN.test(url) && !CONFIG_ROOTED_URL_PATTERN.test(url)) {
+        throw new Error(
+          `Action ${action.type} declares the request URL "${url}", which is neither absolute nor rooted in a {{config.\u2026}} value`
+        );
+      }
+    }
+    if (!declared && loose.postReceive !== void 0) {
+      throw new Error(`Action ${action.type} has postReceive but no request for it to reshape`);
+    }
+    for (const input of action.inputs ?? []) {
+      if (input.loadOptions !== void 0 && definition.options?.[input.loadOptions] === void 0) {
+        throw new Error(
+          `Action ${action.type} argument "${input.key}" loads options from "${input.loadOptions}", which the connector does not serve`
+        );
+      }
+    }
+  }
+  assertUnique(
+    "trigger",
+    triggers.map((trigger) => trigger.type)
+  );
+  assertUnique(
+    "action",
+    actions.map((action) => action.type)
+  );
+  assertUnique(
+    "config field",
+    (definition.config ?? []).map((field) => field.key)
+  );
+  assertAuth(definition);
+  return {
+    ...definition,
+    version: definition.version ?? "0.0.0",
+    config: definition.config ?? [],
+    triggers,
+    actions
+  };
+}
+function resolveConfig(connector, env = process.env) {
+  const config = {};
+  const missing = [];
+  for (const field of connector.config) {
+    const name = envNameFor(field.key, field.env);
+    const value = env[name] ?? field.default;
+    if (value === void 0 || value === "") {
+      if (field.required) missing.push(`${field.key} (${name})`);
+      continue;
+    }
+    config[field.key] = value;
+  }
+  if (missing.length > 0) {
+    throw new Error(
+      `Connector ${connector.id} is missing required configuration: ${missing.join(", ")}`
+    );
+  }
+  return config;
+}
+
+// src/setup.ts
+function pollToolName(triggerType) {
+  return `poll_${triggerType}`;
+}
+var MANIFEST_TOOL = "vorn_connector_manifest";
+var PREFLIGHT_TOOL = "vorn_connector_preflight";
+var OPTIONS_TOOL = "vorn_connector_options";
+function connectionSetup(connector, triggerType) {
+  const trigger = connector.triggers.find((entry) => entry.type === triggerType);
+  if (!trigger) {
+    throw new Error(`Connector ${connector.id} has no trigger "${triggerType}"`);
+  }
+  return {
+    connectorId: connector.id,
+    triggerType,
+    filters: {
+      pollTool: pollToolName(triggerType),
+      itemsPath: "items",
+      idField: "externalId",
+      timestampField: "updatedAt",
+      titleField: "title",
+      urlField: "url",
+      cursorArg: "cursor",
+      cursorPath: "nextCursor"
+    },
+    env: connector.config.map((field) => ({
+      name: envNameFor(field.key, field.env),
+      required: field.required === true,
+      secret: field.secret === true,
+      ...field.description !== void 0 && { description: field.description },
+      ...field.builderHint !== void 0 && { builderHint: field.builderHint }
+    }))
+  };
+}
+function connectorManifest(connector) {
+  return {
+    id: connector.id,
+    name: connector.name,
+    version: connector.version,
+    ...connector.description !== void 0 && { description: connector.description },
+    ...connector.icon !== void 0 && { icon: connector.icon },
+    ...connector.auth !== void 0 && { auth: connector.auth },
+    triggers: connector.triggers.map((trigger) => ({
+      type: trigger.type,
+      label: trigger.label,
+      ...trigger.description !== void 0 && { description: trigger.description },
+      // Carried through so the app can seed a connection's status mapping and
+      // its polling workflow. Absent when the connector said nothing, which is
+      // different from saying there is nothing.
+      ...trigger.statusMapping !== void 0 && { statusMapping: trigger.statusMapping },
+      ...trigger.defaultWorkflow !== void 0 && { defaultWorkflow: trigger.defaultWorkflow },
+      setup: connectionSetup(connector, trigger.type)
+    })),
+    actions: connector.actions.map((action) => ({
+      type: action.type,
+      label: action.label,
+      ...action.description !== void 0 && { description: action.description },
+      inputs: (action.inputs ?? []).map((input) => ({
+        key: input.key,
+        label: input.label,
+        type: input.type ?? "string",
+        required: input.required === true,
+        ...input.options !== void 0 && { options: input.options },
+        ...input.loadOptions !== void 0 && { loadOptions: input.loadOptions },
+        ...input.builderHint !== void 0 && { builderHint: input.builderHint }
+      })),
+      ...action.outputs !== void 0 && { outputs: action.outputs },
+      ...action.sample !== void 0 && { sample: action.sample }
+    }))
+  };
+}
+
+// src/harness.ts
+function matches(route, method, url) {
+  if (route.method && route.method.toUpperCase() !== method) return false;
+  if (route.url instanceof RegExp) return route.url.test(url);
+  let pathname;
+  try {
+    pathname = new URL(url).pathname;
+  } catch {
+    return false;
+  }
+  return route.url.endsWith("/") ? pathname.startsWith(route.url) : pathname === route.url;
+}
+function reply(route) {
+  const body = typeof route.body === "string" ? route.body : JSON.stringify(route.body ?? {});
+  return new Response(body, {
+    status: route.status ?? 200,
+    headers: { "content-type": "application/json", ...route.headers }
+  });
+}
+var MockRouteMissError = class extends Error {
+  constructor(method, url) {
+    super(`No mock route for ${method} ${url}`);
+    this.name = "MockRouteMissError";
+  }
+};
+function escapedMockHttp(error) {
+  for (let current = error; current instanceof Error; current = current.cause) {
+    if (current instanceof MockRouteMissError) return true;
+    if (current.message.includes("No mock route for ")) return true;
+  }
+  return false;
+}
+var serving = false;
+async function withMockHttp(routes, body) {
+  if (serving) {
+    throw new Error(
+      "withMockHttp is already serving; give one call every route it needs rather than installing a second stub"
+    );
+  }
+  serving = true;
+  const calls = [];
+  const original = globalThis.fetch;
+  globalThis.fetch = (async (input, init) => {
+    const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+    const own = typeof input === "object" && "method" in input ? input.method : void 0;
+    const method = (init?.method ?? own ?? "GET").toUpperCase();
+    calls.push({
+      method,
+      url,
+      ...typeof init?.body === "string" && { body: init.body }
+    });
+    const route = routes.find((candidate) => matches(candidate, method, url));
+    if (!route) throw new MockRouteMissError(method, url);
+    return reply(route);
+  });
+  try {
+    return { result: await body(), calls };
+  } finally {
+    globalThis.fetch = original;
+    serving = false;
+  }
+}
+function createConnectorHarness(connector, harnessOptions = {}) {
+  const defaults = (options = {}) => ({
+    ...harnessOptions.config && { config: harnessOptions.config },
+    ...harnessOptions.now && { now: harnessOptions.now },
+    ...harnessOptions.fetchImpl && { fetchImpl: harnessOptions.fetchImpl },
+    ...harnessOptions.sleep && { sleep: harnessOptions.sleep },
+    ...options
+  });
+  return {
+    poll: (triggerType, options) => runPoll(connector, triggerType, defaults(options)),
+    drain: (triggerType, options) => drainPoll(connector, triggerType, defaults(options)),
+    execute: (actionType, args = {}) => runAction(connector, actionType, args, {
+      ...harnessOptions.config && { config: harnessOptions.config },
+      ...harnessOptions.now && { now: harnessOptions.now },
+      ...harnessOptions.fetchImpl && { fetchImpl: harnessOptions.fetchImpl },
+      ...harnessOptions.sleep && { sleep: harnessOptions.sleep }
+    }),
+    manifest: () => connectorManifest(connector),
+    async pollTwice(triggerType, options) {
+      const first = await drainPoll(connector, triggerType, defaults(options));
+      const watermark = first.reduce(
+        (newest, item) => newest === void 0 || item.updatedAt > newest ? item.updatedAt : newest,
+        options?.since
+      );
+      const second = await drainPoll(
+        connector,
+        triggerType,
+        defaults({ ...options, ...watermark !== void 0 && { since: watermark } })
+      );
+      return watermark === void 0 ? second : second.filter((item) => item.updatedAt > watermark);
+    },
+    withMockHttp
+  };
+}
+
+// src/check.ts
+var EXECUTABLE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+var CREDENTIAL_NAME = /(secret|token|password|passphrase|api[-_]?key|credential)/i;
+var INPUT_TYPES = /* @__PURE__ */ new Set(["string", "number", "boolean", "select", "json"]);
+function finding2(level, code, target, message) {
+  return { level, code, target, message };
+}
+function authFindings(connector) {
+  const auth = connector.auth;
+  if (!auth) {
+    return [
+      finding2(
+        "warn",
+        "auth-undeclared",
+        connector.id,
+        "does not say how it signs in, so the app cannot tell anyone before they install it"
+      )
+    ];
+  }
+  const found = [];
+  const command = auth.probe?.command?.trim() ?? "";
+  const args = auth.probe?.args ?? [];
+  if (auth.rung === "cli") {
+    if (!EXECUTABLE_NAME.test(command)) {
+      found.push(
+        finding2(
+          "error",
+          "auth-probe-missing",
+          `${connector.id} auth`,
+          `probe command "${command}" is not a bare executable name, so the host drops it and the rung promises a sign-in it cannot ask for`
+        )
+      );
+    }
+    if (args.some((arg) => typeof arg !== "string")) {
+      found.push(
+        finding2(
+          "error",
+          "auth-probe-missing",
+          `${connector.id} auth`,
+          "probe arguments must all be strings, or the host drops the probe"
+        )
+      );
+    }
+  }
+  return found;
+}
+function secretFindings(connector) {
+  const named = new Set(connector.auth?.keys ?? []);
+  return connector.config.filter((field) => !field.secret).filter((field) => named.has(field.key) || CREDENTIAL_NAME.test(field.key)).map(
+    (field) => finding2(
+      named.has(field.key) ? "error" : "warn",
+      "secret-not-marked",
+      `config ${field.key}`,
+      "holds a credential but is not marked `secret`, so Vorn would store it unencrypted"
+    )
+  );
+}
+function actionShapeFindings(action) {
+  const target = `action ${action.type}`;
+  const found = [];
+  if (!action.outputs?.length) {
+    found.push(
+      finding2(
+        "warn",
+        "action-no-outputs",
+        target,
+        "declares no outputs, so a later step has nothing to autocomplete from"
+      )
+    );
+  }
+  for (const input of action.inputs ?? []) {
+    if (input.type !== void 0 && !INPUT_TYPES.has(input.type)) {
+      found.push(
+        finding2(
+          "error",
+          "input-type-unsupported",
+          `${target} input ${input.key}`,
+          `declares type "${input.type}", which Vorn cannot draw a field for`
+        )
+      );
+    }
+    if (input.type === "select" && !input.options?.length && !input.loadOptions) {
+      found.push(
+        finding2(
+          "error",
+          "input-type-unsupported",
+          `${target} input ${input.key}`,
+          "is a select with neither fixed options nor a loadOptions set to draw from"
+        )
+      );
+    }
+  }
+  return found;
+}
+async function packageFindings(options) {
+  if (options.packageDir === void 0) return [];
+  const pkg = readNearestPackageJson(packageDirFor(options.packageDir, options.entry));
+  const found = [...lifecycleScriptFindings(pkg)];
+  const vorn = pkg?.vorn;
+  const keywords = Array.isArray(vorn?.keywords) ? vorn.keywords : [];
+  if (keywords.length === 0) {
+    found.push(
+      finding2(
+        "warn",
+        "keywords-missing",
+        "package.json",
+        "names no keywords, so the connector is findable only by its own name"
+      )
+    );
+  }
+  if (options.bundle && options.entry !== void 0) {
+    const built = await options.bundle({
+      contents: packEntryContents(options.entry),
+      resolveDir: options.packageDir
+    });
+    found.push(...bundleDependencyFindings(built.external));
+  }
+  return found;
+}
+function sampleArg(input) {
+  if (input.type === "number") return "1";
+  if (input.type === "boolean") return "false";
+  if (input.type === "json") return "{}";
+  if (input.type === "select") return input.options?.[0]?.value ?? "check";
+  return "check";
+}
+function mockConfig(connector) {
+  const config = {};
+  for (const field of connector.config) {
+    config[field.key] = field.default ?? `mock-${field.key}`;
+  }
+  return config;
+}
+async function mockFindings(connector, options) {
+  if (!options.mock) return [];
+  const config = options.config ?? mockConfig(connector);
+  const routes = options.mockRoutes ?? [{ url: /.*/ }];
+  const level = options.mockRoutes?.length ? "error" : "warn";
+  const found = [];
+  for (const action of connector.actions) {
+    const args = Object.fromEntries(
+      (action.inputs ?? []).map((input) => [input.key, sampleArg(input)])
+    );
+    const { result: thrown, calls } = await withMockHttp(routes, async () => {
+      try {
+        await runAction(connector, action.type, args, {
+          config,
+          ...options.now && { now: options.now }
+        });
+        return void 0;
+      } catch (error) {
+        return error;
+      }
+    });
+    if (thrown !== void 0) {
+      const reason = thrown instanceof Error ? thrown.message : String(thrown);
+      const escaped = escapedMockHttp(thrown);
+      found.push(
+        finding2(
+          escaped ? "error" : level,
+          escaped ? "mock-network-escape" : "mock-action-failed",
+          `action ${action.type}`,
+          `did not run against served HTTP: ${reason}`
+        )
+      );
+      continue;
+    }
+    if (calls.length === 0) {
+      found.push(
+        finding2(
+          "warn",
+          "mock-not-observed",
+          `action ${action.type}`,
+          "made no request the stub could see, so this run vouches for nothing it did"
+        )
+      );
+    }
+  }
+  return found;
+}
+var AUTH_FAILURE = /\b(401|403|unauthor|unauthenticat|forbidden|invalid[- ]?(token|credential))/i;
+function liveRunnable(action) {
+  if (action.idempotent !== true) return false;
+  if (action.sample !== void 0) return true;
+  return !(action.inputs ?? []).some((input) => input.required === true);
+}
+function liveExamines(connector) {
+  return connector.preflight !== void 0 || connector.actions.some(liveRunnable);
+}
+async function liveFindings(connector, options) {
+  if (!options.live) return [];
+  const found = [];
+  if (connector.preflight) {
+    try {
+      const result = await connector.preflight();
+      if (!result.ok) {
+        found.push(
+          finding2(
+            "error",
+            "preflight-failed",
+            connector.id,
+            result.message ?? "reported that it is not ready, without saying why"
+          )
+        );
+        return found;
+      }
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      found.push(finding2("error", "preflight-failed", connector.id, `threw: ${reason}`));
+      return found;
+    }
+  }
+  for (const action of connector.actions.filter(liveRunnable)) {
+    try {
+      await runAction(connector, action.type, action.sample ?? {}, {
+        config: options.config ?? {},
+        ...options.now && { now: options.now }
+      });
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      found.push(
+        finding2(
+          AUTH_FAILURE.test(reason) ? "error" : "warn",
+          "live-action-failed",
+          `action ${action.type}`,
+          `threw: ${reason}`
+        )
+      );
+    }
+  }
+  return found;
+}
+function sampleTrigger(trigger) {
+  return { ...trigger, poll: void 0, fetch: () => trigger.sample ?? [] };
+}
+async function checkPollBehaviour(connector, trigger, options) {
+  const found = [];
+  const probe = { ...connector, triggers: [trigger] };
+  const target = `trigger ${trigger.type}`;
+  const now = options.now ?? (() => (/* @__PURE__ */ new Date()).toISOString());
+  const attempt = async (cursor, code, what) => {
+    try {
+      return await runPoll(probe, trigger.type, {
+        config: options.config ?? {},
+        ...cursor !== void 0 && { cursor },
+        now
+      });
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      return finding2("error", code, target, `${what} threw: ${reason}`);
+    }
+  };
+  const first = await attempt(void 0, "poll-failed", "first poll");
+  if ("level" in first) return [first];
+  if (first.items.length === 0) {
+    found.push(
+      finding2("warn", "no-items", target, "returned nothing, so delivery could not be verified")
+    );
+    return found;
+  }
+  if (first.nextCursor === void 0) {
+    found.push(
+      finding2(
+        "error",
+        "no-cursor",
+        target,
+        "returned items but no nextCursor, so every poll will redeliver them"
+      )
+    );
+    return found;
+  }
+  const second = await attempt(
+    first.nextCursor,
+    "cursor-rejected",
+    "re-polling with its own nextCursor"
+  );
+  if ("level" in second) return [...found, second];
+  const delivered = new Set(first.items.map((item) => item.externalId));
+  const repeated = second.items.filter((item) => delivered.has(item.externalId));
+  if (repeated.length > 0) {
+    found.push(
+      finding2(
+        "error",
+        "redelivers-items",
+        target,
+        `re-polling with its own nextCursor returned ${repeated.length} already-delivered item(s), starting with "${repeated[0].externalId}"`
+      )
+    );
+  }
+  if (second.hasMore && second.nextCursor === first.nextCursor) {
+    found.push(
+      finding2("error", "stuck-cursor", target, "reports more pages but its cursor never advances")
+    );
+  }
+  return found;
+}
+async function checkConnector(connector, options = {}) {
+  const found = [];
+  if (!connector.description?.trim()) {
+    found.push(
+      finding2(
+        "warn",
+        "missing-description",
+        connector.id,
+        "has no description; agents use it to decide when the connector applies"
+      )
+    );
+  }
+  found.push(...authFindings(connector));
+  found.push(...secretFindings(connector));
+  found.push(...await packageFindings(options));
+  found.push(...await mockFindings(connector, options));
+  found.push(...await liveFindings(connector, options));
+  const perTrigger = await Promise.all(
+    connector.triggers.map(async (trigger) => {
+      const target = `trigger ${trigger.type}`;
+      const triggerFindings = [];
+      if (!trigger.description?.trim()) {
+        triggerFindings.push(finding2("warn", "missing-description", target, "has no description"));
+      }
+      if (options.live) {
+        triggerFindings.push(...await checkPollBehaviour(connector, trigger, options));
+      } else if (!trigger.sample?.length) {
+        triggerFindings.push(
+          finding2(
+            "warn",
+            "unverifiable",
+            target,
+            "has no sample items and no credentials were supplied, so nothing could be verified"
+          )
+        );
+      } else if (!trigger.dedupe) {
+        triggerFindings.push(
+          finding2(
+            "warn",
+            "sample-unusable",
+            target,
+            "declares sample items but implements poll() directly, so they cannot be replayed; re-run with --live"
+          )
+        );
+      } else {
+        triggerFindings.push(
+          ...await checkPollBehaviour(connector, sampleTrigger(trigger), options)
+        );
+      }
+      return triggerFindings;
+    })
+  );
+  found.push(...perTrigger.flat());
+  for (const action of connector.actions) {
+    const target = `action ${action.type}`;
+    if (!action.description?.trim()) {
+      found.push(
+        finding2("warn", "missing-description", target, "has no description for the agent to read")
+      );
+    }
+    if (action.idempotent === void 0) {
+      found.push(
+        finding2(
+          "warn",
+          "missing-idempotent",
+          target,
+          "does not declare `idempotent`, so an agent cannot tell whether retrying is safe"
+        )
+      );
+    }
+    found.push(...actionShapeFindings(action));
+    for (const input of action.inputs ?? []) {
+      if (!input.description?.trim()) {
+        found.push(
+          finding2(
+            "warn",
+            "missing-description",
+            `${target} input ${input.key}`,
+            "has no description"
+          )
+        );
+      }
+    }
+  }
+  return found;
+}
+var CHECK_OWNERS = {
+  "pack-too-large": null,
+  "missing-description": "manifest",
+  "auth-undeclared": "auth",
+  "auth-probe-missing": "auth",
+  "secret-not-marked": "secrets",
+  "action-no-outputs": "actions",
+  "input-type-unsupported": "actions",
+  "missing-idempotent": "actions",
+  "poll-failed": "dedupe",
+  "no-items": "dedupe",
+  "no-cursor": "dedupe",
+  "cursor-rejected": "dedupe",
+  "redelivers-items": "dedupe",
+  "stuck-cursor": "dedupe",
+  unverifiable: "dedupe",
+  "sample-unusable": "dedupe",
+  "lifecycle-scripts": "no-lifecycle-scripts",
+  "keywords-missing": "keywords",
+  "runtime-dependencies": "no-runtime-deps",
+  "mock-action-failed": "mock",
+  "mock-network-escape": "mock",
+  "mock-not-observed": "mock",
+  "preflight-failed": "live",
+  "live-action-failed": "live"
+};
+function checksRun(connector, options) {
+  const names = ["manifest", "auth"];
+  if (connector.config.length > 0) names.push("secrets");
+  if (connector.actions.length > 0) names.push("actions");
+  if (connector.triggers.length > 0) names.push("dedupe");
+  if (options.packageDir !== void 0) names.push("no-lifecycle-scripts", "keywords");
+  if (options.bundle && options.entry !== void 0) names.push("no-runtime-deps");
+  if (options.mock && connector.actions.length > 0) names.push("mock");
+  if (options.live && liveExamines(connector)) names.push("live");
+  return names;
+}
+async function runConformance(connector, options = {}) {
+  const findings = await checkConnector(connector, options);
+  const spoiled = new Set(findings.map((item) => CHECK_OWNERS[item.code]).filter(Boolean));
+  const passed = checksRun(connector, options).filter((name) => !spoiled.has(name));
+  const failed = findings.some((item) => item.level === "error");
+  const now = options.now ?? (() => (/* @__PURE__ */ new Date()).toISOString());
+  return {
+    findings,
+    passed,
+    // A receipt listing nothing would read as verified while vouching for
+    // nothing at all, which is worse than saying nothing.
+    ...!failed && passed.length > 0 && {
+      receipt: {
+        schema: 1,
+        version: connector.version,
+        checkedAt: now(),
+        checks: passed
+      }
+    }
+  };
+}
+function formatFindings(findings) {
+  return findings.map((item) => `${item.level.padEnd(5)}  ${item.target}: ${item.message} [${item.code}]`).join("\n");
+}
+
+// src/pack.ts
+import { mkdtemp, mkdir, rm, stat, writeFile } from "fs/promises";
+import { tmpdir } from "os";
+import { join as join2, resolve as resolve2 } from "path";
+function finding3(code, target, message) {
+  return { level: "error", code, target, message };
+}
+function packFileName(connector) {
+  return `${connector.id}-${connector.version}.vorn.tgz`;
+}
+async function packConnector(connector, options) {
+  const resolveDir = resolve2(options.resolveDir ?? process.cwd());
+  const entryDir = packageDirFor(resolveDir, options.entry);
+  const findings = await checkConnector(connector);
+  findings.push(...lifecycleScriptFindings(readNearestPackageJson(entryDir)));
+  if (findings.some((item) => item.level === "error")) return { findings };
+  const contents = packEntryContents(options.entry, options.sdkModule);
+  const bundle = options.bundle ?? esbuildBundle;
+  const built = await bundle({ contents, resolveDir });
+  findings.push(...bundleDependencyFindings(built.external));
+  if (findings.some((item) => item.level === "error")) return { findings };
+  const outDir = resolve2(options.outDir ?? process.cwd());
+  await mkdir(outDir, { recursive: true });
+  const file = join2(outDir, packFileName(connector));
+  const staging = await mkdtemp(join2(tmpdir(), "vorn-pack-"));
+  try {
+    await writeFile(join2(staging, "index.js"), built.code, "utf8");
+    await writeFile(
+      join2(staging, "manifest.json"),
+      `${JSON.stringify(connectorManifest(connector), null, 2)}
+`,
+      "utf8"
+    );
+    const { create } = await import("tar");
+    await create({ gzip: true, file, cwd: staging }, ["manifest.json", "index.js"]);
+  } finally {
+    await rm(staging, { recursive: true, force: true });
+  }
+  const bytes = (await stat(file)).size;
+  const maxBytes = options.maxBytes ?? MAX_PACK_BYTES;
+  if (bytes > maxBytes) {
+    await rm(file, { force: true });
+    return {
+      findings: [
+        ...findings,
+        finding3(
+          "pack-too-large",
+          "bundle",
+          `The pack is ${Math.round(bytes / 1024)} KB; Vorn installs at most ${Math.round(maxBytes / 1024)} KB`
+        )
+      ]
+    };
+  }
+  return { findings, file, bytes };
+}
+
+// src/scaffold.ts
+var ID_PATTERN = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
+var SDK_DEPENDENCY_RANGE = "^0.7.0-beta.9";
+var SCAFFOLD_VERSION = "0.1.0";
+var VITEST_RANGE = "^4.1.10";
+function jsonFile(value) {
+  return `${JSON.stringify(value, null, 2)}
+`;
+}
+function titleCase(id) {
+  return id.split(/[-_]+/).filter((part) => part !== "").map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
+}
+function packageJson(id, description, inRepo) {
+  return jsonFile({
+    name: inRepo ? `@vornrun/connector-${id}` : `vorn-connector-${id}`,
+    version: SCAFFOLD_VERSION,
+    description,
+    type: "module",
+    license: "MIT",
+    bin: { [`vorn-connector-${id}`]: "dist/index.js" },
+    main: "./dist/index.js",
+    types: "./dist/index.d.ts",
+    files: ["dist", "README.md", ...inRepo ? ["CHANGELOG.md"] : []],
+    ...inRepo && {
+      repository: {
+        type: "git",
+        url: "git+https://github.com/vorn-run/connectors.git",
+        directory: `packages/${id}`
+      }
+    },
+    scripts: {
+      // In the repository the config file is the one definition of the build.
+      build: inRepo ? "tsup" : "tsup src/index.ts --format esm --target node22 --clean --dts",
+      check: "vorn-connector check src/index.ts",
+      pack: "vorn-connector pack src/index.ts",
+      test: "vitest run",
+      typecheck: "tsc --noEmit"
+    },
+    dependencies: { "@vornrun/connector-sdk": SDK_DEPENDENCY_RANGE },
+    devDependencies: {
+      ...inRepo && { "@types/node": "^22.10.2", "@vitest/coverage-v8": VITEST_RANGE },
+      tsup: "^8.5.1",
+      typescript: "^6.0.3",
+      vitest: VITEST_RANGE
+    },
+    // Read by the catalog build: how this connector is filed, found, and what it asks of you.
+    vorn: {
+      category: "Other",
+      keywords: [id],
+      ...inRepo && { auth: "Say in one line what signing in takes." }
+    }
+  });
+}
+function tsconfig() {
+  return jsonFile({
+    compilerOptions: {
+      target: "ES2022",
+      lib: ["ES2022"],
+      module: "ESNext",
+      moduleResolution: "bundler",
+      allowSyntheticDefaultImports: true,
+      esModuleInterop: true,
+      strict: true,
+      skipLibCheck: true,
+      types: ["node"],
+      noEmit: true,
+      ignoreDeprecations: "6.0",
+      allowImportingTsExtensions: true
+    },
+    include: ["src/**/*", "vitest.config.ts"]
+  });
+}
+function tsupConfig() {
+  return `import { defineConfig } from 'tsup'
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm'],
+  target: 'node22',
+  clean: true,
+  dts: true,
+  // Vorn spawns the built file directly.
+  banner: { js: '#!/usr/bin/env node' }
+})
+`;
+}
+function vitestConfig() {
+  return `import shared from '../../vitest.shared.ts'
+
+export default shared
+`;
+}
+function changelog() {
+  return `# Changelog
+
+## ${SCAFFOLD_VERSION}
+
+- First release.
+`;
+}
+function connectorSource(id, name, description) {
+  return `import { defineConnector } from '@vornrun/connector-sdk'
+
+export const connector = defineConnector({
+  id: ${JSON.stringify(id)},
+  name: ${JSON.stringify(name)},
+  description: ${JSON.stringify(description)},
+  version: '${SCAFFOLD_VERSION}',
+  // Prefer a login the machine already has: { rung: 'cli', probe: { command: 'tool', args: ['auth', 'status'] } }
+  auth: { rung: 'key', keys: ['apiToken'] },
+  config: [
+    {
+      key: 'apiToken',
+      label: 'API token',
+      required: true,
+      secret: true,
+      builderHint: 'Say where a token is created and which scopes it needs'
+    },
+    { key: 'baseUrl', label: 'Base URL', default: 'https://api.example.com' }
+  ],
+  triggers: [
+    {
+      type: 'itemCreated',
+      label: 'Item created',
+      description: 'Items created since the last poll',
+      // Return what is there; the SDK handles cursors and de-duplication.
+      dedupe: 'timestamp',
+      async fetch(context) {
+        const url = new URL('/v1/items', context.config.baseUrl)
+        if (context.since) url.searchParams.set('updated_since', context.since)
+        // \`context.fetch\` retries and backs off; the global one does not.
+        const response = await context.fetch(url, {
+          headers: { authorization: 'Bearer ' + context.config.apiToken }
+        })
+        if (!response.ok) throw new Error('Listing items failed with ' + response.status)
+        const body = (await response.json()) as { items: Array<Record<string, string>> }
+        return body.items.map((item) => ({
+          externalId: item.id,
+          title: item.title,
+          url: item.html_url,
+          updatedAt: item.updated_at
+        }))
+      }
+    }
+  ],
+  actions: [
+    {
+      type: 'createItem',
+      label: 'Create item',
+      description: 'Create one item',
+      inputs: [
+        { key: 'title', label: 'Title', required: true },
+        { key: 'body', label: 'Body' }
+      ],
+      outputs: [{ key: 'id', type: 'string', description: 'The created item' }],
+      // Declared, not written: the SDK fills the templates, sends it, and keeps what postReceive names.
+      request: {
+        method: 'POST',
+        url: '{{config.baseUrl}}/v1/items',
+        headers: { authorization: 'Bearer {{config.apiToken}}' },
+        body: { title: '{{args.title}}', body: '{{args.body}}' }
+      },
+      postReceive: [{ op: 'pick', keys: ['id'] }]
+    }
+  ]
+})
+`;
+}
+function entrySource() {
+  return `import { realpathSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { serveConnector } from '@vornrun/connector-sdk'
+import { connector } from './connector'
+
+/** True when this file was run directly rather than imported. */
+export function isEntryPoint(moduleUrl: string, argv = process.argv): boolean {
+  const invoked = argv[1]
+  if (invoked === undefined) return false
+  try {
+    return realpathSync(fileURLToPath(moduleUrl)) === realpathSync(invoked)
+  } catch {
+    return false
+  }
+}
+
+/** Serve on stdio when run directly, which is what Vorn spawns; says whether it did. */
+export async function serveIfEntryPoint(
+  moduleUrl: string,
+  serve: (c: typeof connector) => Promise<void> = serveConnector
+): Promise<boolean> {
+  if (!isEntryPoint(moduleUrl)) return false
+  await serve(connector)
+  return true
+}
+`;
+}
+function entryTestSource() {
+  return `import { describe, expect, it, vi } from 'vitest'
+import { realpathSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { isEntryPoint, serveIfEntryPoint } from './entry'
+import connector, { connector as named } from './index'
+
+const HERE = import.meta.url
+
+describe('isEntryPoint', () => {
+  it('is false when the process was started without a script', () => {
+    expect(isEntryPoint(HERE, ['node'])).toBe(false)
+  })
+
+  it('is true when argv points at this module, through a symlink or not', () => {
+    expect(isEntryPoint(HERE, ['node', fileURLToPath(HERE)])).toBe(true)
+    expect(isEntryPoint(HERE, ['node', realpathSync(fileURLToPath(HERE))])).toBe(true)
+  })
+
+  it('is false when the module is running under the test runner', () => {
+    expect(isEntryPoint(HERE)).toBe(false)
+  })
+
+  it('is false rather than throwing when a path cannot be resolved', () => {
+    expect(isEntryPoint(HERE, ['node', '/nowhere/that/exists'])).toBe(false)
+  })
+})
+
+describe('serveIfEntryPoint', () => {
+  it('starts nothing when the module was merely imported', async () => {
+    const serve = vi.fn(async () => {})
+    expect(await serveIfEntryPoint(HERE, serve)).toBe(false)
+    expect(serve).not.toHaveBeenCalled()
+  })
+})
+
+describe('the packaged connector', () => {
+  it('is the same connector under both exports', () => {
+    expect(connector).toBe(named)
+    expect(connector.version).toMatch(/^\\d+\\.\\d+\\.\\d+/)
+  })
+})
+`;
+}
+function indexSource() {
+  return `import { connector } from './connector'
+import { serveIfEntryPoint } from './entry'
+
+export { connector }
+export default connector
+
+await serveIfEntryPoint(import.meta.url)
+`;
+}
+function testSource(name) {
+  return `import { describe, expect, it, vi } from 'vitest'
+import { createConnectorHarness } from '@vornrun/connector-sdk'
+import { connector } from './connector'
+
+/** Answers the connector's calls from here, so the test needs no network. */
+function fakeFetch(body: unknown) {
+  return vi.fn(async () =>
+    new Response(JSON.stringify(body), { headers: { 'content-type': 'application/json' } })
+  ) as unknown as typeof fetch
+}
+
+const config = { apiToken: 'test-token', baseUrl: 'https://api.example.com' }
+
+describe(${JSON.stringify(name)}, () => {
+  it('reports the items the source lists', async () => {
+    const harness = createConnectorHarness(connector, {
+      config,
+      fetchImpl: fakeFetch({
+        items: [
+          {
+            id: '1',
+            title: 'First item',
+            html_url: 'https://example.com/1',
+            updated_at: '2026-01-01T00:00:00.000Z'
+          }
+        ]
+      })
+    })
+
+    const page = await harness.poll('itemCreated')
+
+    expect(page.items).toHaveLength(1)
+    expect(page.items[0].externalId).toBe('1')
+  })
+
+  it('does not deliver the same item twice', async () => {
+    const harness = createConnectorHarness(connector, {
+      config,
+      fetchImpl: fakeFetch({
+        items: [
+          {
+            id: '1',
+            title: 'First item',
+            html_url: 'https://example.com/1',
+            updated_at: '2026-01-01T00:00:00.000Z'
+          }
+        ]
+      })
+    })
+
+    expect(await harness.pollTwice('itemCreated')).toEqual([])
+  })
+
+  it('creates an item and keeps only its id', async () => {
+    const harness = createConnectorHarness(connector, {
+      config,
+      fetchImpl: fakeFetch({ id: '42', extra: 'ignored' })
+    })
+
+    expect(await harness.execute('createItem', { title: 'A title' })).toEqual({ id: '42' })
+  })
+})
+`;
+}
+function readme(id, name, description) {
+  return `# ${name}
+
+${description}
+
+## Build and check
+
+\`\`\`sh
+yarn install
+yarn build
+yarn check      # verifies the connector against Vorn's contract
+yarn test
+yarn pack       # writes ${id}-${SCAFFOLD_VERSION}.vorn.tgz, installable in Vorn
+\`\`\`
+
+## Settings
+
+| Setting | Environment | Required |
+| --- | --- | --- |
+| API token | \`API_TOKEN\` | yes |
+| Base URL | \`BASE_URL\` | no |
+
+## What it offers
+
+- **Item created** \u2014 polls for items created since the last run.
+- **Create item** \u2014 creates one item and returns its id.
+
+Rename the trigger, the action and the settings to whatever this connector
+really talks to; the shapes here are a starting point, not a rule.
+`;
+}
+function scaffoldFiles(options) {
+  if (!ID_PATTERN.test(options.id ?? "")) {
+    throw new Error(`Connector id "${options.id}" must start with a letter and be url-safe`);
+  }
+  const name = options.name?.trim() || titleCase(options.id);
+  const description = options.description?.trim() || `${name} connector for Vorn`;
+  const inRepo = options.repoConventions ?? false;
+  return [
+    { path: "package.json", contents: packageJson(options.id, description, inRepo) },
+    { path: "src/connector.ts", contents: connectorSource(options.id, name, description) },
+    { path: "src/entry.ts", contents: entrySource() },
+    { path: "src/index.ts", contents: indexSource() },
+    { path: "src/connector.test.ts", contents: testSource(name) },
+    { path: "src/entry.test.ts", contents: entryTestSource() },
+    { path: "README.md", contents: readme(options.id, name, description) },
+    ...inRepo ? [
+      { path: "CHANGELOG.md", contents: changelog() },
+      { path: "tsconfig.json", contents: tsconfig() },
+      { path: "tsup.config.ts", contents: tsupConfig() },
+      { path: "vitest.config.ts", contents: vitestConfig() }
+    ] : []
+  ];
+}
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+function json(value) {
+  return {
+    // Vorn reads `structuredContent` to build step output and to find the
+    // `items` array a poll returned; the text block keeps the result readable
+    // in any generic MCP client.
+    content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
+    structuredContent: value
+  };
+}
+function failure(error) {
+  return {
+    content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }],
+    isError: true
+  };
+}
+function describeInput(input) {
+  const base = input.description ?? input.label;
+  if (input.loadOptions !== void 0) {
+    return `${base}. Choices come from this connector's "${input.loadOptions}" list.`;
+  }
+  if (input.type === "json") return `${base}. Takes JSON.`;
+  const choices = (input.options ?? []).map((option) => option.value).filter((value) => typeof value === "string" && value !== "");
+  if (choices.length > 0) return `${base}. Suggested values: ${choices.join(", ")}.`;
+  return base;
+}
+function inputShape(inputs) {
+  const shape = {};
+  for (const input of inputs) {
+    const base = z.string().describe(describeInput(input));
+    shape[input.key] = input.required ? base : base.optional();
+  }
+  return shape;
+}
+function scalar(type) {
+  if (type === "number") return z.number();
+  if (type === "boolean") return z.boolean();
+  return z.string();
+}
+function outputSchema(outputs) {
+  const shape = {};
+  for (const output of outputs) {
+    shape[output.key] = scalar(output.type).optional().describe(output.description ?? output.key);
+  }
+  return z.looseObject(shape);
+}
+function createConnectorServer(connector, options = {}) {
+  const server = new McpServer(
+    { name: connector.id, version: connector.version },
+    { capabilities: { tools: {} } }
+  );
+  let cached = options.config;
+  const config = () => cached ??= resolveConfig(connector);
+  server.registerTool(
+    MANIFEST_TOOL,
+    {
+      description: `Describe the ${connector.name} connector and how to configure it`,
+      inputSchema: {},
+      outputSchema: z.looseObject({})
+    },
+    () => json(connectorManifest(connector))
+  );
+  if (connector.preflight) {
+    const preflight = connector.preflight.bind(connector);
+    server.registerTool(
+      PREFLIGHT_TOOL,
+      {
+        description: `Check whether ${connector.name} can run right now`,
+        inputSchema: {},
+        // Declared rather than left open like the manifest's: this shape is
+        // fixed, so a caller can validate against it. Still loose, because a
+        // connector adding a field of its own should not fail the call.
+        outputSchema: z.looseObject({
+          ok: z.boolean().describe("Whether the connector could run right now"),
+          message: z.string().optional().describe("What to do about it, when it could not")
+        })
+      },
+      async () => {
+        try {
+          return json({ ...await preflight() });
+        } catch (error) {
+          return json({
+            ok: false,
+            message: error instanceof Error ? error.message : String(error)
+          });
+        }
+      }
+    );
+  }
+  const optionSets = Object.keys(connector.options ?? {});
+  if (optionSets.length > 0) {
+    server.registerTool(
+      OPTIONS_TOOL,
+      {
+        description: `List what one of ${connector.name}'s fields can be set to`,
+        inputSchema: {
+          name: z.enum(optionSets).describe("Which options set to list")
+        },
+        outputSchema: z.looseObject({
+          options: z.array(z.looseObject({ value: z.string(), label: z.string().optional() })).describe("The choices, each a value to send and words to show")
+        })
+      },
+      async (args) => {
+        try {
+          return json({
+            options: await runOptions(connector, args.name, {
+              config: config(),
+              ...options.now && { now: options.now }
+            })
+          });
+        } catch (error) {
+          return failure(error);
+        }
+      }
+    );
+  }
+  for (const trigger of connector.triggers) {
+    server.registerTool(
+      pollToolName(trigger.type),
+      {
+        description: trigger.description ?? `Poll ${connector.name} for ${trigger.label}`,
+        inputSchema: {
+          since: z.string().optional().describe("Only return items changed after this ISO timestamp"),
+          cursor: z.string().optional().describe("Opaque cursor from a previous page"),
+          limit: z.string().optional().describe("Maximum number of items to return")
+        },
+        outputSchema: z.looseObject({
+          items: z.array(z.looseObject({})).describe("Normalized items"),
+          nextCursor: z.string().optional().describe("Cursor for the next page"),
+          hasMore: z.boolean().describe("Whether another page is immediately available")
+        })
+      },
+      async (args) => {
+        try {
+          const limit = args.limit === void 0 ? void 0 : Number(args.limit);
+          if (limit !== void 0 && !Number.isFinite(limit)) {
+            throw new Error(`Invalid limit "${args.limit}"`);
+          }
+          return json(
+            await runPoll(connector, trigger.type, {
+              config: config(),
+              ...args.since !== void 0 && { since: args.since },
+              ...args.cursor !== void 0 && { cursor: args.cursor },
+              ...limit !== void 0 && { limit },
+              ...options.now && { now: options.now }
+            })
+          );
+        } catch (error) {
+          return failure(error);
+        }
+      }
+    );
+  }
+  for (const action of connector.actions) {
+    const base = action.description ?? `${action.label} in ${connector.name}`;
+    const retryHint = action.idempotent === void 0 ? "" : action.idempotent ? " Safe to retry: repeating this call with the same arguments has no additional effect." : " Not idempotent: repeating this call performs the operation again.";
+    server.registerTool(
+      action.type,
+      {
+        // Carries the authored label, so a picker can name the action rather than its tool.
+        title: action.label,
+        description: `${base}${retryHint}`,
+        inputSchema: inputShape(action.inputs ?? []),
+        outputSchema: outputSchema(action.outputs ?? [])
+      },
+      async (args) => {
+        try {
+          return json(
+            await runAction(connector, action.type, args, {
+              config: config(),
+              ...options.now && { now: options.now }
+            })
+          );
+        } catch (error) {
+          return failure(error);
+        }
+      }
+    );
+  }
+  return server;
+}
+async function serveConnector(connector, options = {}) {
+  const server = createConnectorServer(connector, options);
+  await server.connect(new StdioServerTransport());
+}
+
+export {
+  MAX_PACK_BYTES,
+  lifecycleScriptFindings,
+  bundleDependencyFindings,
+  readNearestPackageJson,
+  esbuildBundle,
+  normalizeItem,
+  normalizeItems,
+  pollWithDedupe,
+  valueAt,
+  applyPostReceive,
+  resolveTemplates,
+  resolveRequest,
+  asOutput,
+  MAX_REQUEST_PAGES,
+  nextLink,
+  executeRequest,
+  retryAfterMs,
+  backoffMs,
+  resilientFetch,
+  MAX_POLL_PAGES,
+  runPoll,
+  drainPoll,
+  runOptions,
+  runAction,
+  envNameFor,
+  defineConnector,
+  resolveConfig,
+  pollToolName,
+  MANIFEST_TOOL,
+  PREFLIGHT_TOOL,
+  OPTIONS_TOOL,
+  connectionSetup,
+  connectorManifest,
+  MockRouteMissError,
+  escapedMockHttp,
+  withMockHttp,
+  createConnectorHarness,
+  checkConnector,
+  CHECK_OWNERS,
+  runConformance,
+  formatFindings,
+  packFileName,
+  packConnector,
+  titleCase,
+  scaffoldFiles,
+  createConnectorServer,
+  serveConnector
+};