@lanes-sh/link 0.3.2 → 0.4.1

package/src/providers/discord/hints.ts

@@ -0,0 +1,195 @@
+/**
+ * The documentation, because Discord's spec has none.
+ *
+ * Their OpenAPI document is machine-generated and carries a `summary` or
+ * `description` on 17 of its 242 operations — none of them ours. So
+ * `mcp-from-openapi` synthesises `POST /channels/{channel_id}/messages` and that
+ * is the *entire* description an agent would otherwise read. A hint is appended
+ * to it, which here means a hint is the whole of it.
+ *
+ * Every operation therefore gets one, including the ones whose names look
+ * self-explanatory. Two reasons. The names are self-explanatory to someone who
+ * already knows Discord's model, and the model has sharp edges — a channel id is
+ * not a channel name, `list_messages` pages backwards, an announcement is only
+ * publishable from one kind of channel. And `cli/tools.test.ts` looks each hint
+ * up by capability name, so a full set is also the check that all twenty tools
+ * generated: a hint keyed to a tool that silently failed to generate fails the
+ * suite, which is the one failure the size and shape tests cannot see.
+ *
+ * Prose costs 3.4 KB of a 192 KB surface budget. It is not the constraint.
+ */
+export const DISCORD_HINTS: Record<string, string> = {
+  get_my_user: [
+    'Returns the bot application this token belongs to — its id, username, and discriminator.',
+    'Costs nothing and needs no permissions, so it is the call to make first when a connection',
+    'is misbehaving: a 401 here means the stored token is wrong or is missing its `Bot ` prefix,',
+    'and everything else will fail the same way.',
+  ].join(' '),
+
+  list_my_guilds: [
+    'The servers this bot has been added to — not the servers you are a member of.',
+    'A server the bot was never invited to is invisible here and unreachable by every other',
+    'tool, so an empty list means the invite step was missed rather than that you have no servers.',
+    'Returns id, name, and your permissions in each. Start here to turn a server name into the',
+    'id every other call wants.',
+  ].join(' '),
+
+  get_guild: [
+    'One server by id: name, description, icon, owner, and feature flags.',
+    'Pass `with_counts: true` to also get approximate member and presence counts.',
+    'Use this to confirm you have the right server before posting to it.',
+  ].join(' '),
+
+  list_guild_channels: [
+    'Every channel in a server, which is how a channel *name* becomes the `channel_id`',
+    'the posting and reading tools require. Check the `type` field before posting:',
+    '0 is a normal text channel, 5 is an announcement channel (the only kind',
+    '`crosspost_message` works on), 15 is a forum, and 2 and 13 are voice and stage,',
+    'which cannot take messages. `parent_id` is the category a channel sits under.',
+  ].join(' '),
+
+  get_channel: [
+    'One channel by id — its name, type, topic, and which category it belongs to.',
+    'Worth calling before a first post to a channel an agent has not written to before,',
+    'to confirm it is the one intended and that it takes messages at all.',
+  ].join(' '),
+
+  list_messages: [
+    'Read a channel\'s recent messages. This is the triage read, and the only one:',
+    'Discord exposes no message search to bot applications, so finding something means',
+    'paging this and filtering yourself.',
+    'Newest first by default, up to `limit: 100` per call. Page *backwards* through history',
+    'with `before` set to the oldest id you have seen; page forward for new arrivals with',
+    '`after` set to the newest. `around` centres on one message.',
+    'If every `content` comes back empty, the Message Content intent is switched off for',
+    'this application — that is a toggle in the developer portal, not a permission on the',
+    'invite, and nothing else reports it.',
+  ].join(' '),
+
+  get_message: [
+    'One message by id, with its author, timestamp, attachments, reactions, and any embeds.',
+    'Use it to re-read a single message in full after `list_messages` has narrowed things down,',
+    'or to check whether an edit or a reaction landed.',
+  ].join(' '),
+
+  list_pins: [
+    'The pinned messages in a channel. Pinning is how this integration marks something as',
+    'handled or important where a human will see it, so this is the read that shows what',
+    'has been marked. Note the path is the current one — Discord also serves a deprecated',
+    'pins endpoint that is not exposed here.',
+  ].join(' '),
+
+  list_message_reactions_by_emoji: [
+    'Who reacted to a message with one specific emoji. Pass a Unicode emoji directly',
+    '(`emoji_name: "✅"`); a custom server emoji is `name:id`.',
+    'Useful for reading a lightweight vote or acknowledgement off a message rather than',
+    'asking people to reply.',
+  ].join(' '),
+
+  get_active_guild_threads: [
+    'Every thread in a server that is not archived, across all channels at once.',
+    'Cheaper than walking channels one at a time when the question is "what conversations',
+    'are open right now", which is the usual first step of a triage pass.',
+  ].join(' '),
+
+  create_message: [
+    'Post a message to a channel, as the bot application — it will carry an APP badge',
+    'and the application\'s own name and avatar. To post under your own name instead,',
+    'use `execute_webhook`.',
+    'For a plain message, pass `content` (up to 2000 characters, Discord-flavoured markdown).',
+    'For an announcement, prefer `embeds`: an embed gives you a title, a coloured left border,',
+    'a description, and up to 25 name/value `fields`, and it is what makes a post read as',
+    'deliberate rather than typed. `color` is a decimal integer, not a hex string —',
+    '0x5865F2 is 5793266.',
+    'Set `allowed_mentions` explicitly on anything that could ping a room:',
+    '`{"parse": []}` suppresses every mention even if the text contains @everyone.',
+    'Reply to something by passing `message_reference` with the message id.',
+    'Attachments are not available here — files need a multipart request, which Discord accepts',
+    'and this connector cannot encode.',
+  ].join(' '),
+
+  update_message: [
+    'Edit a message this application posted. It cannot edit anyone else\'s, including one',
+    'posted through a webhook — that needs the webhook\'s own edit endpoint.',
+    'This is the typo fix for an announcement already out. Only the fields you pass are',
+    'changed; passing `content` alone leaves existing embeds in place, and clearing an',
+    'embed means passing `embeds: []` explicitly.',
+    'Discord shows an "edited" marker afterwards, which cannot be suppressed.',
+  ].join(' '),
+
+  delete_message: [
+    'Delete a message — the retraction, for an announcement that should not have gone out.',
+    'Irreversible, and it leaves no trace in the channel for anyone who had not already read it.',
+    'The application can always delete its own messages; deleting somebody else\'s needs',
+    'Manage Messages in that channel.',
+    'There is deliberately no bulk delete here: this removes one message named by id, so',
+    'clearing a channel is not something an agent can do in one call.',
+  ].join(' '),
+
+  crosspost_message: [
+    'Publish a message that was posted in an *announcement* channel out to every server',
+    'that follows it. This is what makes an announcement channel worth using: subscribers',
+    'see the post in their own server without joining yours.',
+    'Only works on channel `type: 5`, and only on a message already posted there — so the',
+    'sequence is `create_message` then this, with the id it returned.',
+    'Rate limited far more tightly than posting, and it cannot be undone.',
+  ].join(' '),
+
+  add_my_message_reaction: [
+    'React to a message as this application. The cheapest way to mark a message as seen,',
+    'triaged, or categorised — a ✅ or 👀 costs nothing, notifies nobody, and is visible',
+    'to everyone reading the channel.',
+    'Pass a Unicode emoji directly (`emoji_name: "✅"`); a custom server emoji is `name:id`.',
+    'Remove one with the matching delete tool, which is not exposed here.',
+  ].join(' '),
+
+  create_pin: [
+    'Pin a message to its channel, where it stays visible in the channel\'s pinned list.',
+    'The heavier alternative to a reaction for marking something important: a pin is',
+    'channel-wide and appears in the header, so it is the right weight for "this is the',
+    'announcement that matters" and the wrong weight for routine triage.',
+    'Needs Manage Messages. A channel holds at most 50 pins.',
+  ].join(' '),
+
+  create_thread_from_message: [
+    'Start a thread hanging off an existing message, which is how a post becomes a',
+    'discussion without cluttering the channel. `name` is the thread title and is required.',
+    '`auto_archive_duration` is in minutes and accepts only 60, 1440, 4320, or 10080.',
+    'Use this to route a triaged message somewhere people can talk about it, rather than',
+    'replying inline where it scrolls away.',
+  ].join(' '),
+
+  list_channel_webhooks: [
+    'The webhooks already configured on a channel, with their ids and tokens.',
+    'Check here before calling `create_webhook`: a channel accumulates a webhook per call',
+    'and there is a limit of 15, so reusing the one you made last time is the difference',
+    'between a working integration and a channel full of clutter.',
+    'Needs Manage Webhooks. The response includes each webhook\'s token, which is a',
+    'credential — see the note on `execute_webhook`.',
+  ].join(' '),
+
+  create_webhook: [
+    'Create a webhook on a channel, which is what makes posting under your own name',
+    'possible. Do this once per channel and keep the id and token; call',
+    '`list_channel_webhooks` first to find an existing one rather than making another.',
+    '`name` is a fallback label only — the name and avatar that actually appear are the',
+    'ones passed per message to `execute_webhook`. `avatar` takes a base64 data URI,',
+    'not a URL, and is optional.',
+    'Needs Manage Webhooks. The returned `token` is a standalone credential: anybody',
+    'holding it can post to this channel without any other authentication.',
+  ].join(' '),
+
+  execute_webhook: [
+    'Post through a webhook, setting the name and avatar on the message itself.',
+    'This is how an announcement appears under your own name rather than the',
+    'application\'s: pass `username` and `avatar_url` and the message wears them.',
+    'It still carries an APP badge — Discord has no way to remove that, and no API for',
+    'posting as a real user account.',
+    'Takes the same `content` and `embeds` as `create_message`. Pass `wait: true` to get',
+    'the created message back, which is the only way to learn its id.',
+    '`thread_id` posts into an existing thread in the webhook\'s channel.',
+    'Note what this cannot do: a webhook only posts. It cannot read the channel, and the',
+    'message it creates cannot be edited by `update_message` — a webhook message is',
+    'editable only through the webhook that sent it.',
+  ].join(' '),
+};

package/src/providers/discord/index.ts

@@ -0,0 +1,121 @@
+import { defineProvider } from '#connectivity';
+import { DISCORD_HINTS } from './hints.ts';
+import { DISCORD_REDACT } from './redact.ts';
+
+/**
+ * Discord asks callers to identify themselves and blocks the ones that do not.
+ *
+ * Their documented format is `DiscordBot ($url, $version)`, and a request with a
+ * generic or absent agent is refused at the edge rather than by the API — so it
+ * presents as a network failure with no JSON to read. `connector.headers` on an
+ * `http` connector is what carries it (ADR-045 added the field for the same
+ * problem at Reddit).
+ *
+ * No handle or address in it: this file is public, and `architecture.test.ts`
+ * refuses a real identifier anywhere a reader can see. A name and a URL are what
+ * the check actually looks for.
+ */
+const DISCORD_USER_AGENT = 'DiscordBot (https://lanes.sh/link, 0.3)';
+
+/** The vendored spec sits beside this file. See `specs/vendor.ts`. */
+function specPath(name: string): string {
+  return new URL(`./specs/${name}`, import.meta.url).pathname;
+}
+
+/**
+ * Discord's v10 HTTP API, reached with a bot token the operator pasted.
+ *
+ * There is no user-account path and it is not for want of looking. Discord
+ * publishes no API for acting as yourself: automating a user token is
+ * self-botting, which their terms forbid and which gets accounts terminated, and
+ * the OAuth2 user scopes cover neither posting to a channel nor reading its
+ * history. Everything an integration can legitimately do, it does as an
+ * application. So a message will always carry an APP badge — that part is not
+ * negotiable — but the *name and avatar* on it are, per message, through a
+ * webhook. `execute_webhook` is why the three webhook operations are vendored:
+ * an announcement can read as the operator while an ordinary reply reads as the
+ * integration, from the one token.
+ *
+ * Not OAuth, and for a reason of its own rather than the one ADR-033 gave. That
+ * reason — a vendor matching its callback URL exactly, against a port the kernel
+ * picks — was withdrawn by ADR-045, which added `auth.redirect_uri`; so it is no
+ * longer an argument for a pasted token anywhere. What holds here is narrower and
+ * not fixable on our side: a Discord OAuth2 flow with the `bot` scope installs an
+ * application into a server, but the credential that then calls the API is the
+ * *application's* bot token, a property of the app rather than anything the
+ * exchange returns — so a browser flow would end with the operator still copying
+ * a token out of the developer portal. The `webhook.incoming` scope does return a
+ * usable credential, and it is write-only to a single channel: it cannot read, so
+ * it cannot serve the half of this that is triage.
+ *
+ * `auth.kind` is `header` rather than `bearer` because Discord's scheme word is
+ * `Bot`, not `Bearer`, and a bearer credential is assembled as `Bearer <token>`
+ * with no way to say otherwise. `header` writes the stored value into
+ * `Authorization` verbatim, so the value the operator pastes carries its own
+ * scheme — `Bot MTIz…`. That keeps the whole provider inside this folder at the
+ * cost of a prefix somebody can forget, which is why the prompt label spells it
+ * out and `troubleshooting` names it as the first thing to check.
+ *
+ * No `identity` block, and its absence is deliberate rather than an omission.
+ * The probe sends `Authorization: Bearer <stored value>`, which for this
+ * provider would be `Bearer Bot MTIz…` — a 401 and a null, after a network round
+ * trip, every single connect. Naming the connection falls to the operator
+ * instead. Re-running `connect` with the *same* label repairs the existing
+ * connection rather than adding a second one, because `settleIdentity` matches
+ * on the label; a scripted run passes `--display-name`.
+ */
+export const discord = defineProvider({
+  id: 'discord',
+  name: 'Discord',
+  description:
+    'Post announcements, read channels, and triage messages in the servers your bot has been added to, via the Discord v10 HTTP API.',
+  connector: {
+    kind: 'http',
+    base_url: 'https://discord.com/api/v10',
+    // Vendored, not fetched, and doubly so here: upstream is a public preview
+    // Discord says may break without notice, and `connect` grants everything a
+    // provider discovers. See `specs/vendor.ts`.
+    openapi: specPath('discord.v10.json'),
+    headers: { 'User-Agent': DISCORD_USER_AGENT },
+  },
+  auth: { kind: 'header', header: 'Authorization' },
+  redact: DISCORD_REDACT,
+  hints: DISCORD_HINTS,
+  setup: {
+    summary:
+      'Discord authenticates an integration as an application, not as you. You create one in ' +
+      'their developer portal, copy its bot token, and invite it to the servers you want ' +
+      'reachable. Posts will carry an APP badge; the name and avatar on them are yours to set. ' +
+      'You are asked for the token once.',
+    docs: 'docs/detailed/setup/discord.md',
+    docs_url: 'https://discord.com/developers/applications',
+    steps: [
+      'Open https://discord.com/developers/applications and choose "New Application". Name it whatever you want the posts to read as — this is the name people will see.',
+      'On the General Information page, set the icon. That is the avatar posts will carry.',
+      'Open the Bot tab. Set the username, then under "Privileged Gateway Intents" switch on MESSAGE CONTENT — without it every message you read comes back with an empty body, and nothing else will tell you why. An app in fewer than 10,000 servers can just toggle it; there is no review.',
+      'Still on the Bot tab, choose "Reset Token" and copy what it shows you. Discord shows it once. Paste it below prefixed with the word Bot and a space, exactly as: Bot MTIzNDU2Nzg5.abcdef',
+      'Turn off "Public Bot" on the same page unless you want strangers adding it to their servers.',
+      'Now invite it. Take the Application ID from General Information and open: https://discord.com/oauth2/authorize?client_id=<application-id>&scope=bot&permissions=309774593088',
+      'Pick a server you own and authorise. Those permission bits are exactly what the vendored operations need: view channels, send messages, manage messages (for pinning), read message history, add reactions, create public threads, send in threads, and manage webhooks. Repeat per server.',
+      'A private channel needs the bot added to it as well — server-wide permissions do not reach a channel it cannot see.',
+      'To rotate: "Reset Token" in the portal, then run: lanes link connect discord --replace',
+    ],
+    troubleshooting:
+      'Discord refused the token. Check the prefix first — the stored value must begin with ' +
+      '"Bot " and a token pasted bare is the usual cause of a 401 that names nothing. ' +
+      'After that: a token invalidated by a later "Reset Token", or an application that was ' +
+      'deleted. If calls authenticate but a channel 403s, the bot is in the server but not ' +
+      'that channel, or the invite was authorised without the permissions above. If reads ' +
+      'succeed and every message body is empty, the MESSAGE CONTENT intent is off. ' +
+      'Reset the token at https://discord.com/developers/applications and re-run: ' +
+      'lanes link connect discord --replace',
+    prompts: [
+      {
+        key: 'token',
+        label: 'Discord bot token, prefixed — Bot <token>',
+        secret: true,
+        scope: 'connection' as const,
+      },
+    ],
+  },
+});

package/src/providers/discord/redact.ts

@@ -0,0 +1,99 @@
+/**
+ * What survives into the audit log when Discord is read or posted to.
+ *
+ * The default withholds every value, which for a write log means recording that
+ * something was posted somewhere without recording where — so every operation
+ * here names its identifiers explicitly. Snowflake ids are kept throughout:
+ * which guild, which channel, which message, which webhook. Pagination cursors
+ * and limits are kept too, because "read 50 messages after this one" is the
+ * whole shape of a triage pass and none of it is anybody's content.
+ *
+ * Message bodies are withheld. `content`, `embeds`, `components`, `attachments`,
+ * `poll`, and a thread's `name` are the operator's own words, and a log that
+ * reproduces them is a second copy of the channel.
+ *
+ * Two departures worth stating.
+ *
+ * `allowed_mentions` is **kept** on every operation that posts. It is not
+ * content, it is the blast radius: whether a post was allowed to ping
+ * `@everyone` is exactly the fact an operator wants in the log, and it is
+ * unrecoverable from anywhere else once the message is edited or deleted.
+ *
+ * `username` is **kept** on `execute_webhook` and `webhook_token` is not.
+ * Keeping the username is what makes the log legible — a webhook post is
+ * deliberately wearing a name that is not the app's, and "posted as Ops in
+ * channel 123" answers the question the entry exists for. The token is a
+ * standalone credential for posting to that channel, so it is withheld by
+ * omission and appears as a type marker; `avatar_url` goes the same way for
+ * being cosmetic rather than a fact about what happened.
+ */
+export const DISCORD_REDACT: Record<string, string[]> = {
+  // Reads. Everything an argument can be here is an id, a cursor, or a count.
+  get_my_user: [],
+  list_my_guilds: ['before', 'after', 'limit', 'with_counts'],
+  get_guild: ['guild_id', 'with_counts'],
+  list_guild_channels: ['guild_id'],
+  get_channel: ['channel_id'],
+  list_messages: ['channel_id', 'around', 'before', 'after', 'limit'],
+  get_message: ['channel_id', 'message_id'],
+  list_pins: ['channel_id', 'before', 'limit'],
+  list_message_reactions_by_emoji: [
+    'channel_id',
+    'message_id',
+    'emoji_name',
+    'after',
+    'limit',
+    'type',
+  ],
+  get_active_guild_threads: ['guild_id'],
+
+  // Posting. `content`, `embeds`, `components`, `attachments`, `poll`, and
+  // `shared_client_theme` are withheld by omission.
+  create_message: [
+    'channel_id',
+    'allowed_mentions',
+    'message_reference',
+    'sticker_ids',
+    'flags',
+    'tts',
+    'nonce',
+    'enforce_nonce',
+  ],
+  update_message: [
+    'channel_id',
+    'message_id',
+    'allowed_mentions',
+    'sticker_ids',
+    'flags',
+  ],
+  delete_message: ['channel_id', 'message_id'],
+  crosspost_message: ['channel_id', 'message_id'],
+
+  // Triage marking. An emoji is a reaction, not private content, and which one
+  // was used is the entire meaning of the action.
+  add_my_message_reaction: ['channel_id', 'message_id', 'emoji_name'],
+  create_pin: ['channel_id', 'message_id'],
+  // `name` withheld: a thread title is the operator's words.
+  create_thread_from_message: [
+    'channel_id',
+    'message_id',
+    'auto_archive_duration',
+    'rate_limit_per_user',
+  ],
+
+  // Webhooks. `avatar` on creation is base64 image bytes; withholding it is the
+  // same call `gmail.send_message` makes about attachments.
+  list_channel_webhooks: ['channel_id'],
+  create_webhook: ['channel_id', 'name'],
+  execute_webhook: [
+    'webhook_id',
+    'username',
+    'thread_id',
+    'allowed_mentions',
+    'applied_tags',
+    'with_components',
+    'wait',
+    'flags',
+    'tts',
+  ],
+};