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

package/README.md

@@ -257,6 +257,21 @@ hand:
 npx vorn-connector setup ./dist/index.js
 ```
 
+## Pack it as a file
+
+`vorn-connector pack` builds a single installable file: the manifest plus one
+bundled entry with every dependency inlined.
+
+```bash
+npx vorn-connector pack ./dist/index.js --out ./release
+# → release/acme-1.2.3.vorn.tgz
+```
+
+Packing runs `check` first, then two gates a pack must pass: the source package
+declares no install-time scripts, and nothing was left outside the bundle. A
+pack installs by copying files, so it works with no registry reachable — drop
+it on **Settings → Connectors** and Vorn launches it from disk.
+
 ### Ship an icon
 
 Without one, a connector shows the generic MCP glyph and is hard to pick out
@@ -290,9 +305,12 @@ vorn-connector manifest <module>          Print the manifest as JSON
 vorn-connector setup <module> [trigger]   Print the Vorn connection settings
 vorn-connector poll <module> <trigger>    Run one poll against the environment
 vorn-connector check <module>             Verify the connector against the contract
+vorn-connector pack <module>              Build an installable .vorn.tgz pack
 vorn-connector serve <module>             Serve on stdio (what Vorn runs)
 ```
 
+`pack` accepts `--out <dir>`.
+
 `poll` accepts `--since <iso>` and `--limit <n>`, and reads the connector's
 declared config from your shell environment — the fastest way to confirm
 credentials and field mapping before wiring anything up.

package/dist/{chunk-457KOZUU.js → chunk-NXZBUV63.js}

@@ -600,6 +600,147 @@ function connectorManifest(connector) {
   };
 }
 
+// src/pack.ts
+import { builtinModules } from "module";
+import { mkdtemp, mkdir, rm, stat, writeFile } from "fs/promises";
+import { readFileSync } from "fs";
+import { tmpdir } from "os";
+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 finding2(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 [
+    finding2(
+      "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 [
+    finding2(
+      "runtime-dependencies",
+      "bundle",
+      `${[...specifiers].sort().join(", ")} stayed outside the bundle; a pack must launch with no install step`
+    )
+  ];
+}
+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;
+    }
+  }
+}
+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)
+  };
+}
+function packFileName(connector) {
+  return `${connector.id}-${connector.version}.vorn.tgz`;
+}
+async function packConnector(connector, options) {
+  const resolveDir = resolve(options.resolveDir ?? process.cwd());
+  const entryDir = options.entry.startsWith(".") || isAbsolute(options.entry) ? dirname(resolve(resolveDir, options.entry)) : resolveDir;
+  const findings = await checkConnector(connector);
+  findings.push(...lifecycleScriptFindings(readNearestPackageJson(entryDir)));
+  if (findings.some((item) => item.level === "error")) return { findings };
+  const sdkModule = options.sdkModule ?? "@vornrun/connector-sdk";
+  const contents = [
+    `import { serveConnector } from ${JSON.stringify(sdkModule)}`,
+    `import * as entry from ${JSON.stringify(options.entry)}`,
+    "const exported = Object.values(entry).find((value) => value && Array.isArray(value.triggers))",
+    `if (!exported) throw new Error(${JSON.stringify(`${options.entry} exports no connector`)})`,
+    "await serveConnector(exported)",
+    ""
+  ].join("\n");
+  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 = resolve(options.outDir ?? process.cwd());
+  await mkdir(outDir, { recursive: true });
+  const file = join(outDir, packFileName(connector));
+  const staging = await mkdtemp(join(tmpdir(), "vorn-pack-"));
+  try {
+    await writeFile(join(staging, "index.js"), built.code, "utf8");
+    await writeFile(
+      join(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,
+        finding2(
+          "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/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -725,6 +866,8 @@ function createConnectorServer(connector, options = {}) {
     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 ?? [])
@@ -768,6 +911,12 @@ export {
   PREFLIGHT_TOOL,
   connectionSetup,
   connectorManifest,
+  MAX_PACK_BYTES,
+  lifecycleScriptFindings,
+  bundleDependencyFindings,
+  readNearestPackageJson,
+  packFileName,
+  packConnector,
   createConnectorServer,
   serveConnector
 };

package/dist/cli.d.ts

@@ -1,8 +1,14 @@
 #!/usr/bin/env node
+import { B as BundleRequest, a as BundleOutput } from './pack-C3ZJx9d4.js';
+
 interface CliDeps {
     load(modulePath: string): Promise<unknown>;
     write(line: string): void;
     env?: NodeJS.ProcessEnv;
+    /** Directory module paths resolve from; defaults to the working directory. */
+    cwd?: string;
+    /** Replaced in tests so pack does not shell out to a bundler. */
+    bundle?(request: BundleRequest): Promise<BundleOutput>;
 }
 declare function runCli(argv: string[], deps: CliDeps): Promise<number>;
 

package/dist/cli.js

@@ -4,10 +4,11 @@ import {
   connectionSetup,
   connectorManifest,
   formatFindings,
+  packConnector,
   resolveConfig,
   runPoll,
   serveConnector
-} from "./chunk-457KOZUU.js";
+} from "./chunk-NXZBUV63.js";
 
 // src/cli.ts
 import { pathToFileURL } from "url";
@@ -18,13 +19,15 @@ Commands:
   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
+  pack <module>                 Build an installable .vorn.tgz pack
   poll <module> <trigger>       Run one poll against the current environment
   serve <module>                Serve the connector on stdio (what Vorn runs)
 
 Options:
   --since <iso>                 Lower bound passed to poll
   --limit <n>                   Maximum items to request
-  --live                        Let check poll for real using the environment`;
+  --live                        Let check poll for real using the environment
+  --out <dir>                   Directory pack writes the archive to`;
 var BOOLEAN_FLAGS = /* @__PURE__ */ new Set(["live"]);
 function parseArgs(args) {
   const flags = {};
@@ -110,6 +113,26 @@ ${connector.id} passed with ${findings.length} warning(s)`
       );
       return errors.length > 0 ? 1 : 0;
     }
+    case "pack": {
+      const result = await packConnector(connector, {
+        entry: modulePath,
+        ...flags.out !== void 0 && { outDir: flags.out },
+        ...deps.cwd !== void 0 && { resolveDir: deps.cwd },
+        ...deps.bundle !== void 0 && { bundle: deps.bundle }
+      });
+      if (result.findings.length > 0) deps.write(formatFindings(result.findings));
+      const errors = result.findings.filter((item) => item.level === "error");
+      if (!result.file) {
+        deps.write(`
+${errors.length} error(s) \u2014 nothing was packed`);
+        return 1;
+      }
+      deps.write(
+        `
+Packed ${connector.id} ${connector.version} to ${result.file} (${Math.max(1, Math.round((result.bytes ?? 0) / 1024))} KB)`
+      );
+      return 0;
+    }
     case "poll": {
       const triggerType = positional[0];
       if (!triggerType) {

package/dist/index.d.ts

@@ -1,272 +1,7 @@
+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 { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 
-/**
- * Author-facing types for Vorn connectors.
- *
- * A connector written with this SDK runs as an ordinary MCP stdio server, so
- * it is shared as a normal npm package and installed by pointing a Vorn
- * connection at `npx -y <package>`. Nothing about the host app has to change
- * to accept a new connector.
- */
-/** A raw item as the author's code returns it. Only id and title are required. */
-interface ConnectorItem {
-    /** Stable upstream identity. Vorn dedupes on this, so it must not change. */
-    externalId: string | number;
-    title: string;
-    url?: string;
-    description?: string;
-    /** Raw upstream status (`open`, `Active`, `In Progress`, …). */
-    status?: string;
-    labels?: string[];
-    assignee?: string;
-    /**
-     * When the item last changed. Vorn advances its poll cursor from this field,
-     * so it must be monotonic per item and comparable as an ISO 8601 string.
-     * Defaults to poll time when omitted.
-     */
-    updatedAt?: string | Date;
-    /** Extra fields to expose to workflow templates as `{{trigger.item.<key>}}`. */
-    data?: Record<string, unknown>;
-}
-/** A connector item after normalization. This is the exact JSON Vorn sees. */
-interface NormalizedItem extends Record<string, unknown> {
-    externalId: string;
-    title: string;
-    url: string;
-    description: string;
-    status: string;
-    labels: string[];
-    updatedAt: string;
-    assignee?: string;
-}
-/** Declares a value the connector needs at runtime, read from the environment. */
-interface ConnectorConfigField {
-    key: string;
-    label: string;
-    /** Environment variable the value is read from. Defaults to CONSTANT_CASE(key). */
-    env?: string;
-    required?: boolean;
-    /** Secrets are stored encrypted by Vorn and never printed by the CLI. */
-    secret?: boolean;
-    description?: string;
-    default?: string;
-}
-type ConnectorConfig = Record<string, string | undefined>;
-interface PollContext {
-    config: ConnectorConfig;
-    /**
-     * Lower bound the host asked for, when it was able to supply one. Treat it
-     * as a hint: returning older items is safe because Vorn dedupes, but
-     * returning fewer than everything after `since` loses events.
-     */
-    since?: string;
-    /** Opaque cursor previously returned by this trigger, when supplied. */
-    cursor?: string;
-    /** Upper bound on items to return in one page. */
-    limit?: number;
-    /** Injectable clock so tests are deterministic. */
-    now(): string;
-}
-interface PollOutcome {
-    items: ConnectorItem[];
-    nextCursor?: string;
-    hasMore?: boolean;
-}
-/**
- * How the SDK decides which fetched items are new.
- *
- * - `timestamp` — for sources that expose a reliable "last changed" field and
- *   can filter on it. Handles the boundary case where several items share the
- *   newest timestamp, which is the classic source of both duplicates and
- *   silently dropped items.
- * - `lastItem` — for feeds that return newest-first with no dependable
- *   timestamp. The cursor is the newest id already delivered.
- */
-type DedupeStrategy = 'timestamp' | 'lastItem';
-/**
- * What a declarative trigger's `fetch` receives. Deliberately smaller than
- * {@link PollContext}: cursor encoding, ordering, windowing and de-duplication
- * are the SDK's job, so the author only has to answer "what is there now?".
- */
-interface FetchContext {
-    config: ConnectorConfig;
-    /**
-     * With `dedupe: 'timestamp'`, everything changed at or after this instant is
-     * worth returning. Absent on the very first poll. Returning a little too
-     * much is safe — the SDK drops what was already delivered.
-     */
-    since?: string;
-    /**
-     * With `dedupe: 'lastItem'`, the newest id already delivered. Absent on the
-     * very first poll. Return the feed newest-first and the SDK will stop there.
-     */
-    lastItemId?: string;
-    /** Upper bound on items worth returning in one call. */
-    limit?: number;
-    /** Injectable clock so tests are deterministic. */
-    now(): string;
-}
-/**
- * What an upstream state should become when an item is imported as a task.
- *
- * A suggestion, not a rule: it seeds the connection form, and the person
- * setting it up can change it. Without any, everything a connector imports
- * lands as `todo` regardless of whether it was closed a year ago.
- */
-interface StatusSuggestion {
-    /** The value the connector reports in `ConnectorItem.status`. */
-    upstream: string;
-    suggestedLocal: 'todo' | 'in_progress' | 'in_review' | 'done' | 'cancelled';
-}
-/**
- * The workflow to create when a connection is made.
- *
- * A connector that fires on a schedule is useless until something polls it, and
- * expecting every person to build that workflow by hand is how a connection
- * ends up configured and silent. Seeded workflows are ordinary, visible and
- * editable — the schedule is a starting point, not a fixed rule.
- */
-interface DefaultWorkflow {
-    name: string;
-    defaultCronFromMinutes: number;
-}
-interface TriggerBase {
-    /** Event key, e.g. `workItemCreated`. Becomes the `poll_<type>` MCP tool. */
-    type: string;
-    label: string;
-    description?: string;
-    /** Seeds the connection's status mapping; the person setting it up owns it. */
-    statusMapping?: StatusSuggestion[];
-    /** Seeds a polling workflow when a connection is created. */
-    defaultWorkflow?: DefaultWorkflow;
-    /**
-     * Representative items. `vorn-connector check` replays these through the
-     * real dedupe pipeline, so a connector can be verified before anyone has
-     * credentials for it.
-     */
-    sample?: ConnectorItem[];
-}
-/**
- * A trigger is either declarative or hand-written, never both — expressed as a
- * union so the invalid combinations are a type error at authoring time rather
- * than a throw when the connector is first loaded.
- */
-type TriggerDefinition = TriggerBase & ({
-    /**
-     * Declarative polling: return what the source has and let the SDK
-     * handle cursors and de-duplication.
-     */
-    dedupe: DedupeStrategy;
-    fetch(context: FetchContext): Promise<ConnectorItem[]> | ConnectorItem[];
-    poll?: never;
-} | {
-    /**
-     * Full control over cursors and paging. Use only when the source's
-     * paging cannot be expressed as "give me everything since X".
-     */
-    poll(context: PollContext): Promise<PollOutcome> | PollOutcome;
-    dedupe?: never;
-    fetch?: never;
-});
-interface ActionInputField {
-    key: string;
-    label: string;
-    type?: 'string' | 'number' | 'boolean';
-    required?: boolean;
-    description?: string;
-}
-/**
- * A field the action is known to return. Declaring these is optional — extra
- * keys always pass through — but declared fields show up in Vorn's variable
- * autocomplete as `{{steps.<action>.<key>}}`.
- */
-interface ActionOutputField {
-    key: string;
-    type?: 'string' | 'number' | 'boolean';
-    description?: string;
-}
-interface ActionContext {
-    config: ConnectorConfig;
-    now(): string;
-}
-interface ActionDefinition {
-    /** Action key, e.g. `closeWorkItem`. Becomes an MCP tool of the same name. */
-    type: string;
-    label: string;
-    description?: string;
-    /**
-     * Whether repeating the call with the same arguments is safe. Surfaced in
-     * the MCP tool description, because an agent retrying a failed step has no
-     * other way to know whether it is about to create a second issue.
-     */
-    idempotent?: boolean;
-    inputs?: ActionInputField[];
-    outputs?: ActionOutputField[];
-    run(args: Record<string, unknown>, context: ActionContext): Promise<Record<string, unknown> | void> | Record<string, unknown> | void;
-}
-/**
- * A connector's own glyph, so an installed connector is recognizable in a list
- * rather than sharing one generic icon with every other one.
- *
- * Path data only — deliberately not markup. Vorn draws these itself as
- * `<path d="...">` inside an `<svg>` it owns, so a connector cannot inject
- * elements, scripts or external references into the app rendering it.
- */
-interface ConnectorIcon {
-    /** Defaults to `0 0 24 24`. */
-    viewBox?: string;
-    /** SVG path `d` data, drawn with `fill="currentColor"` so it inherits color. */
-    paths: string[];
-}
-/**
- * What a connector reports about its own readiness.
- *
- * `message` is shown to the user verbatim, so it should say what to do rather
- * than what went wrong — "run `gh auth login`" beats "not authenticated".
- */
-interface PreflightResult {
-    ok: boolean;
-    message?: string;
-}
-interface ConnectorDefinition {
-    /** Stable connector id, e.g. `azure-devops`. */
-    id: string;
-    name: string;
-    version?: string;
-    description?: string;
-    icon?: ConnectorIcon;
-    config?: ConnectorConfigField[];
-    triggers?: TriggerDefinition[];
-    actions?: ActionDefinition[];
-    /**
-     * Whether this connector could work right now, asked before anyone waits on
-     * a poll.
-     *
-     * A connector whose credentials come from config fields does not need this:
-     * a missing field is already a visible, nameable error. One that borrows an
-     * external tool's login — `gh auth login`, `az login` — has no field to be
-     * missing, so without this the first sign that the tool is absent or signed
-     * out is a poll failing some minutes after the connection was saved.
-     *
-     * Answer `ok: false` with a message saying what to do about it. Throwing is
-     * equivalent — the server catches it and reports the same shape with the
-     * error's message — so there is one result for a caller to read and no
-     * behaviour riding on which you choose. Prefer returning when the state is
-     * one you recognise, because then you get to write the sentence.
-     *
-     * Absent means there is nothing to check, which is not the same answer as a
-     * check that passed.
-     */
-    preflight?(): Promise<PreflightResult> | PreflightResult;
-}
-/** A validated definition. Every accessor below is guaranteed non-null. */
-interface Connector extends ConnectorDefinition {
-    readonly version: string;
-    readonly config: ConnectorConfigField[];
-    readonly triggers: TriggerDefinition[];
-    readonly actions: ActionDefinition[];
-}
-
 /** Environment variable a config field reads from, e.g. `apiToken` → `API_TOKEN`. */
 declare function envNameFor(key: string, explicit?: string): string;
 /**
@@ -285,36 +20,6 @@ declare function defineConnector(definition: ConnectorDefinition): Connector;
  */
 declare function resolveConfig(connector: Connector, env?: NodeJS.ProcessEnv): ConnectorConfig;
 
-interface CheckFinding {
-    /** `error` means the connector will misbehave in Vorn; `warn` is advisory. */
-    level: 'error' | 'warn';
-    code: string;
-    /** Which part of the connector the finding is about. */
-    target: string;
-    message: string;
-}
-interface CheckOptions {
-    /**
-     * Poll every trigger against the real source. Off by default, so a check
-     * runs on declared `sample` items and the definition alone.
-     */
-    live?: boolean;
-    /** Credentials, required by `live`. */
-    config?: ConnectorConfig;
-    now?: () => string;
-}
-/**
- * Check a connector against the contract Vorn relies on.
- *
- * The point is a feedback loop: a connector — hand-written or generated — can
- * be verified before it is ever installed, catching the failures that are
- * otherwise invisible until duplicate tasks show up in someone's inbox days
- * later.
- */
-declare function checkConnector(connector: Connector, options?: CheckOptions): Promise<CheckFinding[]>;
-/** Render findings for a terminal. Returns an empty string when all clear. */
-declare function formatFindings(findings: CheckFinding[]): string;
-
 /**
  * Run a declarative trigger: call the author's `fetch`, then apply the chosen
  * dedupe strategy.
@@ -491,4 +196,4 @@ interface ConnectorHarness {
  */
 declare function createConnectorHarness(connector: Connector, harnessOptions?: HarnessOptions): ConnectorHarness;
 
-export { type ActionContext, type ActionDefinition, type ActionInputField, type CheckFinding, type CheckOptions, type ConnectionSetup, type Connector, type ConnectorConfig, type ConnectorConfigField, type ConnectorDefinition, type ConnectorHarness, type ConnectorIcon, type ConnectorItem, type ConnectorManifest, type ConnectorServerOptions, type DedupeStrategy, type DefaultWorkflow, type FetchContext, type HarnessOptions, MANIFEST_TOOL, MAX_POLL_PAGES, type NormalizedItem, PREFLIGHT_TOOL, type PollContext, type PollOutcome, type PollPage, type PreflightResult, type RunActionOptions, type RunPollOptions, type StatusSuggestion, type TriggerDefinition, checkConnector, connectionSetup, connectorManifest, createConnectorHarness, createConnectorServer, defineConnector, drainPoll, envNameFor, formatFindings, normalizeItem, normalizeItems, pollToolName, pollWithDedupe, resolveConfig, runAction, runPoll, serveConnector };
+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 };

package/dist/index.js

@@ -1,7 +1,9 @@
 import {
   MANIFEST_TOOL,
+  MAX_PACK_BYTES,
   MAX_POLL_PAGES,
   PREFLIGHT_TOOL,
+  bundleDependencyFindings,
   checkConnector,
   connectionSetup,
   connectorManifest,
@@ -10,15 +12,19 @@ import {
   drainPoll,
   envNameFor,
   formatFindings,
+  lifecycleScriptFindings,
   normalizeItem,
   normalizeItems,
+  packConnector,
+  packFileName,
   pollToolName,
   pollWithDedupe,
+  readNearestPackageJson,
   resolveConfig,
   runAction,
   runPoll,
   serveConnector
-} from "./chunk-457KOZUU.js";
+} from "./chunk-NXZBUV63.js";
 
 // src/harness.ts
 function createConnectorHarness(connector, harnessOptions = {}) {
@@ -52,8 +58,10 @@ function createConnectorHarness(connector, harnessOptions = {}) {
 }
 export {
   MANIFEST_TOOL,
+  MAX_PACK_BYTES,
   MAX_POLL_PAGES,
   PREFLIGHT_TOOL,
+  bundleDependencyFindings,
   checkConnector,
   connectionSetup,
   connectorManifest,
@@ -63,10 +71,14 @@ export {
   drainPoll,
   envNameFor,
   formatFindings,
+  lifecycleScriptFindings,
   normalizeItem,
   normalizeItems,
+  packConnector,
+  packFileName,
   pollToolName,
   pollWithDedupe,
+  readNearestPackageJson,
   resolveConfig,
   runAction,
   runPoll,

package/dist/pack-C3ZJx9d4.d.ts

@@ -0,0 +1,340 @@
+/**
+ * Author-facing types for Vorn connectors.
+ *
+ * A connector written with this SDK runs as an ordinary MCP stdio server, so
+ * it is shared as a normal npm package and installed by pointing a Vorn
+ * connection at `npx -y <package>`. Nothing about the host app has to change
+ * to accept a new connector.
+ */
+/** A raw item as the author's code returns it. Only id and title are required. */
+interface ConnectorItem {
+    /** Stable upstream identity. Vorn dedupes on this, so it must not change. */
+    externalId: string | number;
+    title: string;
+    url?: string;
+    description?: string;
+    /** Raw upstream status (`open`, `Active`, `In Progress`, …). */
+    status?: string;
+    labels?: string[];
+    assignee?: string;
+    /**
+     * When the item last changed. Vorn advances its poll cursor from this field,
+     * so it must be monotonic per item and comparable as an ISO 8601 string.
+     * Defaults to poll time when omitted.
+     */
+    updatedAt?: string | Date;
+    /** Extra fields to expose to workflow templates as `{{trigger.item.<key>}}`. */
+    data?: Record<string, unknown>;
+}
+/** A connector item after normalization. This is the exact JSON Vorn sees. */
+interface NormalizedItem extends Record<string, unknown> {
+    externalId: string;
+    title: string;
+    url: string;
+    description: string;
+    status: string;
+    labels: string[];
+    updatedAt: string;
+    assignee?: string;
+}
+/** Declares a value the connector needs at runtime, read from the environment. */
+interface ConnectorConfigField {
+    key: string;
+    label: string;
+    /** Environment variable the value is read from. Defaults to CONSTANT_CASE(key). */
+    env?: string;
+    required?: boolean;
+    /** Secrets are stored encrypted by Vorn and never printed by the CLI. */
+    secret?: boolean;
+    description?: string;
+    default?: string;
+}
+type ConnectorConfig = Record<string, string | undefined>;
+interface PollContext {
+    config: ConnectorConfig;
+    /**
+     * Lower bound the host asked for, when it was able to supply one. Treat it
+     * as a hint: returning older items is safe because Vorn dedupes, but
+     * returning fewer than everything after `since` loses events.
+     */
+    since?: string;
+    /** Opaque cursor previously returned by this trigger, when supplied. */
+    cursor?: string;
+    /** Upper bound on items to return in one page. */
+    limit?: number;
+    /** Injectable clock so tests are deterministic. */
+    now(): string;
+}
+interface PollOutcome {
+    items: ConnectorItem[];
+    nextCursor?: string;
+    hasMore?: boolean;
+}
+/**
+ * How the SDK decides which fetched items are new.
+ *
+ * - `timestamp` — for sources that expose a reliable "last changed" field and
+ *   can filter on it. Handles the boundary case where several items share the
+ *   newest timestamp, which is the classic source of both duplicates and
+ *   silently dropped items.
+ * - `lastItem` — for feeds that return newest-first with no dependable
+ *   timestamp. The cursor is the newest id already delivered.
+ */
+type DedupeStrategy = 'timestamp' | 'lastItem';
+/**
+ * What a declarative trigger's `fetch` receives. Deliberately smaller than
+ * {@link PollContext}: cursor encoding, ordering, windowing and de-duplication
+ * are the SDK's job, so the author only has to answer "what is there now?".
+ */
+interface FetchContext {
+    config: ConnectorConfig;
+    /**
+     * With `dedupe: 'timestamp'`, everything changed at or after this instant is
+     * worth returning. Absent on the very first poll. Returning a little too
+     * much is safe — the SDK drops what was already delivered.
+     */
+    since?: string;
+    /**
+     * With `dedupe: 'lastItem'`, the newest id already delivered. Absent on the
+     * very first poll. Return the feed newest-first and the SDK will stop there.
+     */
+    lastItemId?: string;
+    /** Upper bound on items worth returning in one call. */
+    limit?: number;
+    /** Injectable clock so tests are deterministic. */
+    now(): string;
+}
+/**
+ * What an upstream state should become when an item is imported as a task.
+ *
+ * A suggestion, not a rule: it seeds the connection form, and the person
+ * setting it up can change it. Without any, everything a connector imports
+ * lands as `todo` regardless of whether it was closed a year ago.
+ */
+interface StatusSuggestion {
+    /** The value the connector reports in `ConnectorItem.status`. */
+    upstream: string;
+    suggestedLocal: 'todo' | 'in_progress' | 'in_review' | 'done' | 'cancelled';
+}
+/**
+ * The workflow to create when a connection is made.
+ *
+ * A connector that fires on a schedule is useless until something polls it, and
+ * expecting every person to build that workflow by hand is how a connection
+ * ends up configured and silent. Seeded workflows are ordinary, visible and
+ * editable — the schedule is a starting point, not a fixed rule.
+ */
+interface DefaultWorkflow {
+    name: string;
+    defaultCronFromMinutes: number;
+}
+interface TriggerBase {
+    /** Event key, e.g. `workItemCreated`. Becomes the `poll_<type>` MCP tool. */
+    type: string;
+    label: string;
+    description?: string;
+    /** Seeds the connection's status mapping; the person setting it up owns it. */
+    statusMapping?: StatusSuggestion[];
+    /** Seeds a polling workflow when a connection is created. */
+    defaultWorkflow?: DefaultWorkflow;
+    /**
+     * Representative items. `vorn-connector check` replays these through the
+     * real dedupe pipeline, so a connector can be verified before anyone has
+     * credentials for it.
+     */
+    sample?: ConnectorItem[];
+}
+/**
+ * A trigger is either declarative or hand-written, never both — expressed as a
+ * union so the invalid combinations are a type error at authoring time rather
+ * than a throw when the connector is first loaded.
+ */
+type TriggerDefinition = TriggerBase & ({
+    /**
+     * Declarative polling: return what the source has and let the SDK
+     * handle cursors and de-duplication.
+     */
+    dedupe: DedupeStrategy;
+    fetch(context: FetchContext): Promise<ConnectorItem[]> | ConnectorItem[];
+    poll?: never;
+} | {
+    /**
+     * Full control over cursors and paging. Use only when the source's
+     * paging cannot be expressed as "give me everything since X".
+     */
+    poll(context: PollContext): Promise<PollOutcome> | PollOutcome;
+    dedupe?: never;
+    fetch?: never;
+});
+interface ActionInputField {
+    key: string;
+    label: string;
+    type?: 'string' | 'number' | 'boolean';
+    required?: boolean;
+    description?: string;
+}
+/**
+ * A field the action is known to return. Declaring these is optional — extra
+ * keys always pass through — but declared fields show up in Vorn's variable
+ * autocomplete as `{{steps.<action>.<key>}}`.
+ */
+interface ActionOutputField {
+    key: string;
+    type?: 'string' | 'number' | 'boolean';
+    description?: string;
+}
+interface ActionContext {
+    config: ConnectorConfig;
+    now(): string;
+}
+interface ActionDefinition {
+    /** Action key, e.g. `closeWorkItem`. Becomes an MCP tool of the same name. */
+    type: string;
+    label: string;
+    description?: string;
+    /**
+     * Whether repeating the call with the same arguments is safe. Surfaced in
+     * the MCP tool description, because an agent retrying a failed step has no
+     * other way to know whether it is about to create a second issue.
+     */
+    idempotent?: boolean;
+    inputs?: ActionInputField[];
+    outputs?: ActionOutputField[];
+    run(args: Record<string, unknown>, context: ActionContext): Promise<Record<string, unknown> | void> | Record<string, unknown> | void;
+}
+/**
+ * A connector's own glyph, so an installed connector is recognizable in a list
+ * rather than sharing one generic icon with every other one.
+ *
+ * Path data only — deliberately not markup. Vorn draws these itself as
+ * `<path d="...">` inside an `<svg>` it owns, so a connector cannot inject
+ * elements, scripts or external references into the app rendering it.
+ */
+interface ConnectorIcon {
+    /** Defaults to `0 0 24 24`. */
+    viewBox?: string;
+    /** SVG path `d` data, drawn with `fill="currentColor"` so it inherits color. */
+    paths: string[];
+}
+/**
+ * What a connector reports about its own readiness.
+ *
+ * `message` is shown to the user verbatim, so it should say what to do rather
+ * than what went wrong — "run `gh auth login`" beats "not authenticated".
+ */
+interface PreflightResult {
+    ok: boolean;
+    message?: string;
+}
+interface ConnectorDefinition {
+    /** Stable connector id, e.g. `azure-devops`. */
+    id: string;
+    name: string;
+    version?: string;
+    description?: string;
+    icon?: ConnectorIcon;
+    config?: ConnectorConfigField[];
+    triggers?: TriggerDefinition[];
+    actions?: ActionDefinition[];
+    /**
+     * Whether this connector could work right now, asked before anyone waits on
+     * a poll.
+     *
+     * A connector whose credentials come from config fields does not need this:
+     * a missing field is already a visible, nameable error. One that borrows an
+     * external tool's login — `gh auth login`, `az login` — has no field to be
+     * missing, so without this the first sign that the tool is absent or signed
+     * out is a poll failing some minutes after the connection was saved.
+     *
+     * Answer `ok: false` with a message saying what to do about it. Throwing is
+     * equivalent — the server catches it and reports the same shape with the
+     * error's message — so there is one result for a caller to read and no
+     * behaviour riding on which you choose. Prefer returning when the state is
+     * one you recognise, because then you get to write the sentence.
+     *
+     * Absent means there is nothing to check, which is not the same answer as a
+     * check that passed.
+     */
+    preflight?(): Promise<PreflightResult> | PreflightResult;
+}
+/** A validated definition. Every accessor below is guaranteed non-null. */
+interface Connector extends ConnectorDefinition {
+    readonly version: string;
+    readonly config: ConnectorConfigField[];
+    readonly triggers: TriggerDefinition[];
+    readonly actions: ActionDefinition[];
+}
+
+interface CheckFinding {
+    /** `error` means the connector will misbehave in Vorn; `warn` is advisory. */
+    level: 'error' | 'warn';
+    code: string;
+    /** Which part of the connector the finding is about. */
+    target: string;
+    message: string;
+}
+interface CheckOptions {
+    /**
+     * Poll every trigger against the real source. Off by default, so a check
+     * runs on declared `sample` items and the definition alone.
+     */
+    live?: boolean;
+    /** Credentials, required by `live`. */
+    config?: ConnectorConfig;
+    now?: () => string;
+}
+/**
+ * Check a connector against the contract Vorn relies on.
+ *
+ * The point is a feedback loop: a connector — hand-written or generated — can
+ * be verified before it is ever installed, catching the failures that are
+ * otherwise invisible until duplicate tasks show up in someone's inbox days
+ * later.
+ */
+declare function checkConnector(connector: Connector, options?: CheckOptions): Promise<CheckFinding[]>;
+/** Render findings for a terminal. Returns an empty string when all clear. */
+declare function formatFindings(findings: CheckFinding[]): string;
+
+/** Largest pack Vorn will install, matched by the server's own verification. */
+declare const MAX_PACK_BYTES: number;
+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;
+    /** Replaced in tests so packing does not shell out to a bundler. */
+    bundle?(request: BundleRequest): Promise<BundleOutput>;
+}
+interface BundleRequest {
+    contents: string;
+    resolveDir: string;
+}
+interface BundleOutput {
+    code: string;
+    /** Specifiers the bundler left for the runtime to resolve. */
+    external: string[];
+}
+interface PackResult {
+    findings: CheckFinding[];
+    /** Absolute path of the written pack; absent when a gate failed. */
+    file?: string;
+    bytes?: number;
+}
+/** Reject a source package whose install would run code on the user's machine. */
+declare function lifecycleScriptFindings(pkg: unknown): CheckFinding[];
+/** Specifiers left outside a bundle, which would need a registry at launch. */
+declare function bundleDependencyFindings(external: string[]): CheckFinding[];
+/** Nearest package.json at or above a directory, or undefined when there is none. */
+declare function readNearestPackageJson(fromDir: string): Record<string, unknown> | undefined;
+/** 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>;
+
+export { type ActionContext as A, type BundleRequest as B, type ConnectorDefinition as C, type DefaultWorkflow as D, type FetchContext as F, MAX_PACK_BYTES as M, type NormalizedItem as N, type PollContext as P, type StatusSuggestion as S, type TriggerDefinition as T, type BundleOutput as a, type Connector as b, type ConnectorConfig as c, type PollOutcome as d, type ConnectorItem as e, type ConnectorIcon as f, type ActionDefinition as g, type ActionInputField as h, type CheckFinding as i, type CheckOptions as j, type ConnectorConfigField as k, type DedupeStrategy as l, type PackOptions as m, type PackResult as n, type PreflightResult as o, bundleDependencyFindings as p, checkConnector as q, formatFindings as r, lifecycleScriptFindings as s, packConnector as t, packFileName as u, readNearestPackageJson as v };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vornrun/connector-sdk",
-  "version": "0.7.0-beta.7",
+  "version": "0.7.0-beta.8",
   "description": "Build and share Vorn pull connectors as ordinary npm packages",
   "type": "module",
   "license": "MIT",
@@ -37,6 +37,8 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "esbuild": "^0.28.2",
+    "tar": "^7.5.21",
     "zod": "^4.4.3"
   },
   "devDependencies": {