@lanes-sh/link 0.3.2 → 0.4.1

package/src/providers/discord/specs/vendor.ts

@@ -0,0 +1,164 @@
+/**
+ * Vendor a trimmed OpenAPI spec for Discord's v10 HTTP API.
+ *
+ * Discord publishes an OpenAPI document of its own, which is unusual and
+ * welcome, but ships it as a public preview: "subject to breaking changes
+ * without advance notice, and should not be used within production
+ * environments". Vendoring is what answers that. The committed copy never moves
+ * under us, so a breaking change upstream becomes a diff in a refresh commit
+ * rather than a provider that stops working — and the surface an operator's bot
+ * token can reach stays reviewable.
+ *
+ *   bun run vendor:discord
+ *
+ * The pipeline is `src/providers/shared/vendor-spec.ts`. What stays here is what
+ * only Discord knows: which operations are worth exposing, and the three shapes
+ * in its document that the generator cannot take as written.
+ */
+
+import { vendorSpec } from '../../shared/vendor-spec.ts';
+
+const SOURCE = 'https://raw.githubusercontent.com/discord/discord-api-spec/main/specs/openapi.json';
+
+/**
+ * The operations this provider exposes, out of 242 in the document.
+ *
+ * Curated hard, and the curation is load-bearing rather than tidy: `connect`
+ * writes one policy rule, `discord.*`, so an operation vendored here is an
+ * operation an agent may call. This list *is* the boundary. Discord's own API
+ * would otherwise hand over kick, ban, timeout, role assignment, channel
+ * deletion, and guild settings against a server the operator owns.
+ *
+ * What is deliberately absent, so a later refresh does not quietly add it back:
+ * `bulk_delete_messages` (a mass action no announcement workflow needs), every
+ * `deprecated_*` pin variant (superseded paths, kept by Discord for old
+ * clients), and everything under members, roles, bans, invites, and guild
+ * settings.
+ */
+const READS = [
+  // Whose token this is. The first call worth making after connecting, and the
+  // one that proves the `Bot ` prefix survived being pasted.
+  'get_my_user',
+  // Navigation: which servers the bot was added to, what is in them, and what
+  // one channel is. An agent cannot post to a channel it cannot name.
+  'list_my_guilds',
+  'get_guild',
+  'list_guild_channels',
+  'get_channel',
+  // The triage read. Discord exposes no message search to bots, so reading a
+  // channel means paging `list_messages` with `after` and `limit`.
+  'list_messages',
+  'get_message',
+  'list_pins',
+  'list_message_reactions_by_emoji',
+  'get_active_guild_threads',
+] as const;
+
+const WRITES = [
+  // Posting, as the app.
+  'create_message',
+  // Editing and retracting one's own announcement. `update_message` is the
+  // typo fix; `delete_message` is the retraction, which is why it is here and
+  // `bulk_delete_messages` is not.
+  'update_message',
+  'delete_message',
+  // Publishing a message posted in an announcement channel out to the servers
+  // that follow it — the one operation that makes an announcement channel worth
+  // using rather than an ordinary one.
+  'crosspost_message',
+  // Triage marking: react to it, pin it, or turn it into a thread. All three
+  // are how a human reads back what the agent decided.
+  'add_my_message_reaction',
+  'create_pin',
+  'create_thread_from_message',
+] as const;
+
+/**
+ * Posting under the operator's own name rather than the app's.
+ *
+ * Discord has no API for acting as a user account — automating one violates
+ * their terms — so an integration posts as an application, and an application's
+ * messages carry an `APP` badge that cannot be removed. What *can* be set is the
+ * name and avatar, and `execute_webhook` sets them per message. So an
+ * announcement can read as the operator while an ordinary reply reads as the
+ * integration, from one bot token.
+ *
+ * The cost is stated in `docs/detailed/security.md`: `create_webhook` and
+ * `list_channel_webhooks` return the webhook's token in their response, and a
+ * webhook token is a standalone credential for posting to that channel.
+ */
+const WEBHOOKS = ['list_channel_webhooks', 'create_webhook', 'execute_webhook'] as const;
+
+/**
+ * Discord's v2 message components, collapsed to open objects.
+ *
+ * `mcp-from-openapi` inlines `$ref`s, and this union is referenced by four
+ * request schemas and again from inside two of its own members — so inlining
+ * duplicates the whole tree six times over. There is no wrapper schema to
+ * collapse instead; the union is written out inline at each site.
+ *
+ * Measured, this is the difference between a provider that ships and one that
+ * cannot: `execute_webhook` generates a 148.9 KB input schema against a 64 KB
+ * per-tool budget, `create_message` 76.2 KB, `update_message` 72.6 KB, and the
+ * whole surface 305.4 KB against a 192 KB budget. Opaque brings the worst tool to
+ * 10.4 KB and the surface to 34.1 KB.
+ *
+ * `RichEmbed` is deliberately *not* here. It costs 3.1 KB — 1.6% of the surface
+ * budget — and it is how an announcement gets a title, a colour, and fields, so
+ * it is the one rich shape worth schematising. Collapsing it instead was
+ * measured and moves the worst tool from 148.9 KB to 144.2 KB, which is to say
+ * embeds were never the problem.
+ */
+const OPAQUE = [
+  'ActionRowComponentForMessageRequest',
+  'ContainerComponentForMessageRequest',
+  'FileComponentForMessageRequest',
+  'MediaGalleryComponentForMessageRequest',
+  'SectionComponentForMessageRequest',
+  'SeparatorComponentForMessageRequest',
+  'TextDisplayComponentForMessageRequest',
+];
+
+await vendorSpec('discord', {
+  source: SOURCE,
+  outputDirectory: import.meta.dir,
+  out: 'discord.v10.json',
+  operations: [...READS, ...WRITES, ...WEBHOOKS],
+  opaque: OPAQUE,
+  opaqueNote:
+    'Structure omitted: this union inlines to hundreds of kilobytes. ' +
+    'Pass the object as documented at https://discord.com/developers/docs/components/reference.',
+  vendoredNote:
+    'Trimmed by src/providers/discord/specs/vendor.ts. Committed deliberately: upstream is a public preview that may change without notice, and a spec decides which paths are called with the operator bot token — so it must be reviewable rather than fetched at connect time.',
+
+  // Discord declares path parameters on the path item, not the operation. That
+  // is legal, and `mcp-from-openapi`'s validator does not read it: without this
+  // the document fails outright with 29 × MISSING_PATH_PARAMETER and generates
+  // no tools at all.
+  hoistPathParameters: true,
+
+  // `create_message`, `update_message` and `execute_webhook` also offer
+  // `multipart/form-data`, whose file fields are named `files[0]`. That is not a
+  // legal tool property name, and one illegal name rejects the entire tools list
+  // for every provider on the endpoint — so the only thing standing between us
+  // and that is the generator preferring JSON of its own accord.
+  //
+  // The transport can now form-encode as well as JSON-encode (ADR-045), but not
+  // multipart, so a multipart branch is unsendable regardless of which one the
+  // generator picks. Attachments are unavailable as a result, which is the honest
+  // state: ADR-017's machinery is the route to them, not a branch nothing sends.
+  requestContentTypes: ['application/json'],
+
+  // `execute_webhook`'s body is a top-level `anyOf` of two complete payload
+  // schemas. A union has no `properties` to walk, so the generator emits one
+  // argument literally named `body` and the connector then sends
+  // `{"body":{"content":"…"}}` where Discord expects `{"content":"…"}`. Nothing
+  // in the test suite can see this: the name is legal, the size is fine, the
+  // base_url matches — only a live call fails.
+  //
+  // Naming the branch that is actually wanted flattens it back to 17 real
+  // arguments. Lossless: the other branch's properties are a strict subset.
+  rewriteRequestBody: {
+    execute_webhook: { $ref: '#/components/schemas/IncomingWebhookRequestPartial' },
+  },
+});

package/src/providers/google/specs/vendor.ts

@@ -15,23 +15,13 @@
  * command rather than a hand edit.
  *
  *   bun run vendor:google
+ *
+ * The pipeline itself is `src/providers/shared/vendor-spec.ts`. What stays here
+ * is what only Google knows: which operations are worth exposing, and which of
+ * its system parameters have to go.
  */
 
-import { mkdir, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { OpenAPIToolGenerator, type McpOpenAPITool } from 'mcp-from-openapi';
-
-/** Kept in step with `BUDGET_KB` in `src/cli/tools.test.ts`, which enforces it. */
-const BUDGET_KB = 64;
-
-interface Spec {
-  openapi: string;
-  info: Record<string, unknown>;
-  servers?: Array<{ url: string }>;
-  paths: Record<string, Record<string, { operationId?: string } & Record<string, unknown>>>;
-  components?: { schemas?: Record<string, unknown> } & Record<string, unknown>;
-  [key: string]: unknown;
-}
+import { vendorSpec } from '../../shared/vendor-spec.ts';
 
 /**
  * The operations each provider exposes.
@@ -321,126 +311,6 @@ const SELECTION: Record<
   // field but `title` on it anyway.
 };
 
-/** Every `$ref` target reachable from a value, transitively. */
-function referenced(root: unknown, schemas: Record<string, unknown>): Set<string> {
-  const found = new Set<string>();
-  const queue: unknown[] = [root];
-
-  while (queue.length > 0) {
-    const node = queue.pop();
-    if (node === null || typeof node !== 'object') continue;
-
-    if (Array.isArray(node)) {
-      queue.push(...node);
-      continue;
-    }
-
-    for (const [key, value] of Object.entries(node)) {
-      if (key === '$ref' && typeof value === 'string') {
-        const name = value.replace('#/components/schemas/', '');
-        if (!found.has(name) && name in schemas) {
-          found.add(name);
-          queue.push(schemas[name]);
-        }
-        continue;
-      }
-      queue.push(value);
-    }
-  }
-
-  return found;
-}
-
-/**
- * Cut reference cycles, replacing the back-edge with an open object.
- *
- * Gmail's `MessagePart` contains `MessagePart[]` — a MIME tree, so the
- * recursion is honest — and the OpenAPI tool generator inlines `$ref`s, so it
- * recurses until the stack ends. That silently costs the two draft-writing
- * operations, which are the useful half of `gmail.compose`.
- *
- * Cutting the back-edge rather than dropping the operation keeps the tool: the
- * field that matters for creating a draft is `raw`, an RFC 2822 message, and
- * nothing below the cut is required to fill it in. A depth-first walk marks the
- * names currently on the path, and any `$ref` reaching back to one of them
- * becomes a plain object.
- */
-function cutCycles(schemas: Record<string, unknown>): number {
-  let cuts = 0;
-
-  const walk = (node: unknown, path: Set<string>): void => {
-    if (node === null || typeof node !== 'object') return;
-
-    if (Array.isArray(node)) {
-      for (const item of node) walk(item, path);
-      return;
-    }
-
-    const record = node as Record<string, unknown>;
-    for (const [key, value] of Object.entries(record)) {
-      if (key === '$ref' && typeof value === 'string') {
-        const name = value.replace('#/components/schemas/', '');
-        if (path.has(name)) {
-          delete record['$ref'];
-          record['type'] = 'object';
-          record['additionalProperties'] = true;
-          record['description'] = `A nested ${name}. Structure omitted: it recurses.`;
-          cuts++;
-        } else if (name in schemas) {
-          walk(schemas[name], new Set([...path, name]));
-        }
-        continue;
-      }
-      walk(value, path);
-    }
-  };
-
-  for (const [name, schema] of Object.entries(schemas)) walk(schema, new Set([name]));
-  return cuts;
-}
-
-/**
- * Replace a named schema with an open object.
- *
- * Same device as `cutCycles` and a different disease. That one cuts recursion;
- * this one cuts *fan-out*. `mcp-from-openapi` inlines `$ref`s, so a schema's
- * cost to us is not its size in the document but its size once every reference
- * below it has been expanded — and Sheets' `Request` is a union of some eighty
- * variants, each with its own nested grid, filter, and chart schemas, sharing
- * sub-schemas that inlining duplicates per occurrence.
- *
- * Measured: `sheets.spreadsheets.batchUpdate` generates a 2,469KB input schema,
- * against 45KB for the whole of Drive. That is unusable — it would be sent on
- * every `tools/list` — and it is also the only operation that can add a tab,
- * freeze a header, or format a cell, so dropping it is no better.
- *
- * Opaque keeps the operation and costs 3KB. The agent fills in `requests` from
- * the API it already knows, which is the same bet `raw` makes for a Gmail draft:
- * a well-known wire format is cheaper described than schematised. The pointer to
- * Google's reference is in the description because that is the only thing lost.
- *
- * Applied before `referenced`, so the schemas that were reachable only through
- * the replaced one leave the document entirely rather than lingering unused.
- */
-function makeOpaque(schemas: Record<string, unknown>, names: readonly string[]): number {
-  let replaced = 0;
-
-  for (const name of names) {
-    if (!(name in schemas)) continue;
-    const original = schemas[name] as { description?: string };
-    schemas[name] = {
-      type: 'object',
-      additionalProperties: true,
-      description:
-        `${original.description ?? `A ${name}.`} Structure omitted: it expands to megabytes ` +
-        'when inlined. Pass the object as documented at https://developers.google.com/workspace.',
-    };
-    replaced++;
-  }
-
-  return replaced;
-}
-
 /**
  * Google's system parameters, dropped from every operation.
  *
@@ -474,188 +344,33 @@ const SYSTEM_PARAMETERS = new Set([
 ]);
 
 /**
- * Strip system parameters from a path item or an operation.
- *
- * They arrive as `$ref`s into `components.parameters`, and the component *key*
- * is not the parameter name — `$.xgafv` is keyed `_.xgafv`, because a `$` is
- * awkward in a JSON pointer. Matching on the key would therefore miss exactly
- * the one that breaks everything, so the ref is resolved first.
+ * The note recorded in each spec's `info`, and the one `makeOpaque` leaves
+ * behind. Both are baked into the committed JSON, so they are passed verbatim
+ * rather than reworded.
  */
-function dropSystemParameters(
-  holder: Record<string, unknown>,
-  components: Record<string, unknown>,
-): number {
-  const parameters = holder['parameters'];
-  if (!Array.isArray(parameters)) return 0;
-
-  const nameOf = (parameter: unknown): string | undefined => {
-    const record = parameter as { name?: string; $ref?: string };
-    if (record.name) return record.name;
-    if (!record.$ref) return undefined;
-
-    const key = record.$ref.replace('#/components/parameters/', '');
-    return (components[key] as { name?: string } | undefined)?.name;
-  };
-
-  const kept = parameters.filter((parameter) => {
-    const name = nameOf(parameter);
-    return !(name && SYSTEM_PARAMETERS.has(name));
+const VENDORED_NOTE =
+  'Trimmed by src/providers/google/specs/vendor.ts. Committed deliberately: a spec decides which paths are called with the operator token, so it must be reviewable rather than fetched at connect time.';
+
+const OPAQUE_NOTE =
+  'Structure omitted: it expands to megabytes when inlined. ' +
+  'Pass the object as documented at https://developers.google.com/workspace.';
+
+for (const [id, selection] of Object.entries(SELECTION)) {
+  await vendorSpec(id, {
+    source: selection.source,
+    // `import.meta.dir` *is* the specs directory — this script lives beside what
+    // it writes. It used to be `scripts/vendor-google-specs.ts` and reached
+    // across the tree; commit 3cd03ce moved the script and the specs together
+    // but not the path arithmetic, so for a while this resolved to
+    // `src/providers/google/providers/builtin/specs`, created it, reported
+    // success, and left the committed spec untouched — making the documented
+    // "re-run the script" step a silent no-op.
+    outputDirectory: import.meta.dir,
+    out: selection.out,
+    operations: selection.operations,
+    ...(selection.opaque ? { opaque: selection.opaque } : {}),
+    opaqueNote: OPAQUE_NOTE,
+    vendoredNote: VENDORED_NOTE,
+    systemParameters: SYSTEM_PARAMETERS,
   });
-
-  holder['parameters'] = kept;
-  return parameters.length - kept.length;
-}
-
-const METHODS = ['get', 'post', 'put', 'patch', 'delete', 'head'];
-
-async function vendor(id: string): Promise<void> {
-  const { source, out, operations, opaque } = SELECTION[id]!;
-  const wanted = new Set(operations);
-
-  const response = await fetch(source);
-  if (!response.ok) throw new Error(`${source}: HTTP ${response.status}`);
-  const spec = (await response.json()) as Spec;
-
-  const paths: Spec['paths'] = {};
-  const seen = new Set<string>();
-
-  for (const [path, item] of Object.entries(spec.paths)) {
-    const kept: Record<string, unknown> = {};
-    for (const [method, operation] of Object.entries(item)) {
-      // Path-level keys are not operations and must survive: `parameters` here
-      // is where Google puts the query parameters shared by every method on the
-      // path, and `fields` is one of them — which `drive.about.get` *requires*.
-      // Dropping it produced a tool with no arguments at all and a 400 on every
-      // call.
-      if (!METHODS.includes(method)) {
-        kept[method] = operation;
-        continue;
-      }
-      const operationId = operation.operationId;
-      if (!operationId || !wanted.has(operationId)) continue;
-      kept[method] = operation;
-      seen.add(operationId);
-    }
-
-    // Only path-level keys survived, so no operation here was wanted.
-    if (!Object.keys(kept).some((key) => METHODS.includes(key))) continue;
-    if (Object.keys(kept).length > 0) paths[path] = kept as Spec['paths'][string];
-  }
-
-  const componentParameters = (spec.components?.['parameters'] ?? {}) as Record<string, unknown>;
-
-  let dropped = 0;
-  for (const item of Object.values(paths)) {
-    dropped += dropSystemParameters(item as unknown as Record<string, unknown>, componentParameters);
-    for (const [method, operation] of Object.entries(item)) {
-      if (!METHODS.includes(method)) continue;
-      dropped += dropSystemParameters(
-        operation as unknown as Record<string, unknown>,
-        componentParameters,
-      );
-    }
-  }
-
-  // Drop response schemas.
-  //
-  // Two reasons, and the second is the blocking one. Nothing reads them: the
-  // connector hands the response body back as text, because an agent wants the
-  // JSON, not a validated shape. And Gmail's response schemas are recursive —
-  // `Message.payload` is a `MessagePart`, which contains `MessagePart[]` — which
-  // sends the OpenAPI tool generator into infinite recursion and silently drops
-  // eight of Gmail's twelve operations from the tool list.
-  for (const item of Object.values(paths)) {
-    for (const [method, operation] of Object.entries(item)) {
-      if (!METHODS.includes(method)) continue;
-      (operation as { responses?: unknown }).responses = {
-        '200': { description: 'Success. The response body is returned verbatim.' },
-      };
-    }
-  }
-
-  const missing = operations.filter((operationId) => !seen.has(operationId));
-  if (missing.length > 0) {
-    // Loudly, rather than shipping a provider quietly missing capabilities: an
-    // upstream rename should fail the refresh, not shrink the tool list.
-    throw new Error(`${id}: these operations are not in the spec — ${missing.join(', ')}`);
-  }
-
-  const schemas = spec.components?.schemas ?? {};
-  const opaqued = makeOpaque(schemas, opaque ?? []);
-  const keep = referenced(paths, schemas);
-  const trimmedSchemas = Object.fromEntries(
-    Object.entries(schemas).filter(([name]) => keep.has(name)),
-  );
-  const cuts = cutCycles(trimmedSchemas);
-
-  const trimmed: Spec = {
-    openapi: spec.openapi,
-    info: {
-      ...spec.info,
-      'x-vendored-from': source,
-      'x-vendored-note':
-        'Trimmed by src/providers/google/specs/vendor.ts. Committed deliberately: a spec decides which paths are called with the operator token, so it must be reviewable rather than fetched at connect time.',
-    },
-    ...(spec.servers ? { servers: spec.servers } : {}),
-    paths,
-    components: { ...spec.components, schemas: trimmedSchemas },
-  };
-
-  // `import.meta.dir` *is* the specs directory — this script lives beside what it
-  // writes. It used to be `scripts/vendor-google-specs.ts` and reached across the
-  // tree; commit 3cd03ce moved the script and the specs together but not the path
-  // arithmetic, so for a while this resolved to
-  // `src/providers/google/providers/builtin/specs`, created it, reported success,
-  // and left the committed spec untouched — making the documented "re-run the
-  // script" step a silent no-op.
-  const directory = import.meta.dir;
-  await mkdir(directory, { recursive: true });
-  await writeFile(join(directory, out), `${JSON.stringify(trimmed, null, 2)}\n`);
-
-  const size = Math.round(JSON.stringify(trimmed).length / 1024);
-  console.log(
-    `  ${id.padEnd(6)} ${String(Object.keys(paths).length).padStart(2)} paths, ` +
-      `${seen.size} operations, ${Object.keys(trimmedSchemas).length} schemas, ` +
-      `${cuts} cycle${cuts === 1 ? '' : 's'} cut, ${opaqued} made opaque, ` +
-      `${dropped} system params dropped, ${size}KB`,
-  );
-
-  await reportLargestTools(trimmed);
 }
-
-/**
- * The number the budget is actually about.
- *
- * Everything on the line above counts the *spec*; `cli/tools.test.ts` measures
- * the **generated input schema**, and the two differ by orders of magnitude
- * because `mcp-from-openapi` inlines `$ref`s — a schema shared by ten fields is
- * ten copies once generated. Reasoning about `spreadsheets.create` from a schema
- * count put it at 122 KB when the real figure was 1,133 KB, which is the whole
- * difference between "just over" and "seventeen times over".
- *
- * Printed here so the refresh that adds an operation shows its cost, rather than
- * leaving it to a test failure to say so after the fact.
- */
-async function reportLargestTools(trimmed: Spec): Promise<void> {
-  try {
-    const generator = await OpenAPIToolGenerator.fromJSON(trimmed);
-    const measured = (await generator.generateTools())
-      .map((tool: McpOpenAPITool) => ({
-        name: tool.metadata.operationId ?? tool.name,
-        kb: JSON.stringify(tool.inputSchema).length / 1024,
-      }))
-      .sort((a, b) => b.kb - a.kb);
-
-    for (const { name, kb } of measured.slice(0, 3)) {
-      const over = kb > BUDGET_KB ? `  ✗ over the ${BUDGET_KB}KB budget` : '';
-      console.log(`         ${name.padEnd(38)} ${kb.toFixed(1).padStart(8)}KB${over}`);
-    }
-  } catch (error) {
-    // A generator failure is a real problem, but it is `tools.test.ts`'s to
-    // report against every provider at once. Refusing to finish the vendoring
-    // over it would leave the specs half-written.
-    console.log(`         (could not measure generated schemas: ${String(error)})`);
-  }
-}
-
-for (const id of Object.keys(SELECTION)) await vendor(id);

package/src/providers/index.ts

@@ -1,5 +1,7 @@
 import type { ProviderDefinition, ProviderManifest } from '#connectivity';
+import { bunq } from './bunq/index.ts';
 import { calendar } from './google/calendar/index.ts';
+import { discord } from './discord/index.ts';
 import { contacts } from './google/contacts/index.ts';
 import { docs } from './google/docs/index.ts';
 import { github } from './github/index.ts';
@@ -16,6 +18,7 @@ import { icloudDrive } from './icloud/drive/index.ts';
 import { icloudMail } from './icloud/mail/index.ts';
 import { linear } from './linear/index.ts';
 import { notion } from './notion/index.ts';
+import { reddit } from './reddit/index.ts';
 import { slack } from './slack/index.ts';
 
 /**
@@ -53,6 +56,8 @@ export const PROVIDERS: readonly (ProviderManifest | ProviderDefinition)[] = [
   linear,
   github,
   slack,
+  reddit,
+  discord,
   gmail,
   drive,
   sheets,
@@ -67,6 +72,7 @@ export const PROVIDERS: readonly (ProviderManifest | ProviderDefinition)[] = [
   icloudCalendar,
   icloudContacts,
   icloudDrive,
+  bunq,
 ];
 
 /** The manifest half of an entry, whichever shape it arrived in. */
@@ -95,8 +101,11 @@ export {
   tasks,
 } from './google/index.ts';
 export { icloudCalendar, icloudContacts, icloudDrive, icloudMail } from './icloud/index.ts';
+export { bunq } from './bunq/index.ts';
+export { discord } from './discord/index.ts';
 export { github } from './github/index.ts';
 export { linear } from './linear/index.ts';
 export { notion } from './notion/index.ts';
+export { reddit } from './reddit/index.ts';
 export { slack } from './slack/index.ts';
 export { SCOPE_MEANINGS, type ScopeMeaning } from './scopes.ts';