feat: one-way Discord to Linear bridge for #help threads

AGENTS.md

@@ -39,14 +39,27 @@ src/
     index.ts            Aggregates every command into a name -> command map.
     util/               close, reopen, walkthrough.
     product/            notes (ProductBoard context-menu command).
-  events/               commands, messages, channels, walkthrough handlers.
+  events/               commands, messages, channels, walkthrough, bridge handlers.
+  bridge/
+    linear/             Discord -> Linear mirror (client, api, orchestration).
   lib/
     config.ts           Typed config loader + mandatory field list.
-    discord/            channels, users, messages helpers.
+    discord/            channels, users, messages, help, helpThread helpers.
   ui/components/        StringSelectMenu builders for the walkthrough.
+scripts/
+  discord-linear-sync.ts  One-shot Linear backfill (bun run sync:linear).
 assets/tags.json        Canned response text.
 ```
 
+## Linear bridge
+
+The Linear bridge (`src/events/bridge.ts`) registers its own Discord listeners
+(`ThreadCreate`, `MessageCreate`, `ThreadUpdate`) and mirrors #help forum posts
+into Linear via `src/bridge/linear`. It reads enriched thread state through
+`new HelpThread(thread)` (`src/lib/discord/helpThread.ts`), whose getters derive
+status/waiting/tags from the thread's applied tags. Disabled by default via
+`config.linearBridge.enabled`.
+
 ## Conventions
 
 - **Imports**: Use the `.js` extension on relative imports (ESM/NodeNext),
@@ -68,6 +81,9 @@ environment file -> process environment. Keys are **case-sensitive**.
 
 - Copy `config.json.example` to `config.json` (gitignored) for local IDs.
 - Secrets come from the environment, e.g. `Codercord_token` (the bot token).
+- The Linear bridge API key is a secret too: `Codercord_linearBridge__apiKey`
+  (nested keys use `__`). `linearBridge.teamId` and `enabled` live in
+  `config.json`; the bridge exits at startup if enabled without apiKey/teamId.
 - Mandatory fields are declared in `src/lib/config.ts`; the process exits if
   any are missing.
 

config.json.example

@@ -19,5 +19,14 @@
       "macos": "1078432543696748634",
       "windows": "1078432538940416030",
       "vscode": "1078432889995268248"
+    },
+
+    "linearBridge": {
+      "enabled": false,
+      "teamId": "",
+      "labels": {
+        "enabled": true,
+        "groupName": "Discord (#help)"
+      }
     }
 }

package.json

@@ -20,6 +20,7 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
+    "@linear/sdk": "^90.0.0",
     "@uwu/configmasher": "^2.0.2",
     "discord.js": "^14.27.0",
     "ofetch": "^1.5.1",

src/bridge/ARCHITECTURE.md

@@ -0,0 +1,87 @@
+# Bridge architecture
+
+The bridge mirrors community conversations into Linear. Today it runs one way,
+Discord `#help` -> Linear, but the code is organized around a source-agnostic
+model so more platforms (e.g. GitHub Discussions) and the reverse direction can
+be added without threading platform specifics through the whole system.
+
+## Layout
+
+```
+src/bridge/
+  core/      # platform-agnostic: model, interfaces, orchestration, reconciler
+  discord/   # Discord connector: listeners + model mapping
+  linear/    # Linear connector: the hub store, split by concern
+```
+
+- `core/model.ts` - the shared vocabulary: `Post`, `Message`, `Author`,
+  `Attachment`, `Reaction`, `Reference`, `Label`, and `ExternalRef`
+  (`{ source, id, url }`). A connector maps its native objects onto these.
+- `core/connector.ts` - the `Source` and `Target` capability interfaces.
+- `core/mirror.ts` - `Mirror`, the orchestrator. Consumes model objects a
+  connector produces and drives the `Target`. All logic here is source-agnostic.
+- `core/reconciler.ts` - maps a post's lifecycle onto the hub workflow state.
+- `core/references.ts` - extractors for cross-links (other threads, GitHub
+  issues) that any connector can reuse.
+- `core/backfill.ts` - rate-limit retry used by startup import.
+- `discord/` - `DiscordConnector` (a `Source`) plus `map.ts`, which converts
+  discord.js objects into the model (mentions, emojis, attachments, references).
+- `linear/` - the hub, split into `client`, `issues`, `comments`, `reactions`,
+  `labels`, `emojis`, `attachments`, `state`, `assets`, with `index.ts` exposing
+  `LinearConnector` (a `Target`).
+
+## Source and Target are capabilities, not layers
+
+Everything syncs both ways eventually, so a platform is one module, not split
+across "source" and "target" folders. `Source` (reads events, enumerates for
+backfill, writes the hub link back) and `Target` (the hub store) are capability
+interfaces. Discord implements `Source` today; Linear implements `Target`. When
+a platform's reverse direction is built, its connector grows the other
+capability rather than moving between folders.
+
+## Identity and mapping
+
+A conversation maps to one hub issue. The mapping lives in a Linear **attachment**
+on the issue whose `url` is the source conversation's canonical URL; lookups are
+scoped to the configured team so a shared link (e.g. a GitHub URL attached to an
+unrelated issue) never resolves cross-team.
+
+Mirrored comments carry an invisible marker, a markdown reference-link definition
+`[<source>-msg]: <id>`, so a later edit/delete/reply finds the right comment. The
+marker is namespaced per source; Discord's is `discord-msg`.
+
+**Cardinality (future).** One issue is the hub, linked to N source entities at
+once: the same conversation can map to a Discord thread and a GitHub discussion
+via one attachment each. The marker's source namespace keeps per-source comments
+distinct on the shared issue.
+
+## Reconciliation model
+
+- **Posts always originate at a source.** Nothing is created in Linear; Linear
+  is a relay hub.
+- **The originating source is authoritative for its own content**: title, body,
+  lifecycle (open/closed and waiting state), and messages. If a source and Linear
+  disagree on a source-owned field, the source wins.
+- **Linear relays A -> Linear -> B.** The hub holds cross-source identity but
+  does not author content.
+- **No historical catch-up for Linear-originated changes.** Linear edits
+  propagate only when received live. Propagation of Linear-originated *comments*
+  is an open question, deferred.
+- **State transitions are computed against the current hub state**, not a source
+  old/new diff, so out-of-band changes (e.g. a `/close` command) are detected
+  reliably. See `core/reconciler.ts`: closed -> Done, waiting-on-user -> Blocked,
+  waiting-on-team -> In Progress, with a new live thread held in Triage until the
+  team engages; backfilled threads bypass that gate.
+
+## Future work (not built)
+
+- **Reverse direction (Linear -> source).** The intended inbound channel is
+  **Linear webhooks** (the SDK ships a webhook client). Each connector would grow
+  the write side of its platform.
+- **Echo suppression.** Every mirrored write is tagged with its origin (comments
+  already carry the source marker). Inbound events that match a mirror we just
+  wrote must be ignored so a `Linear -> Discord` write does not bounce back as a
+  new Discord event and loop. Only the origin tagging exists today; the ignore
+  step lands with the reverse direction.
+- **GitHub Discussions.** A new `github/` connector implementing `Source`,
+  reusing `core` unchanged. Its marker namespace would be `github-msg`.

src/bridge/core/backfill.ts

@@ -0,0 +1,22 @@
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// Retries an operation through hub rate limits. Linear's limits reset on a
+// rolling window, so back off and keep waiting rather than dropping work.
+export async function withRateLimitRetry<T>(
+  fn: () => Promise<T>,
+  isRateLimited: (err: unknown) => boolean,
+): Promise<T> {
+  let delayMs = 60_000;
+  for (;;) {
+    try {
+      return await fn();
+    } catch (err) {
+      if (!isRateLimited(err)) throw err;
+      console.warn("[bridge]", "rate limited, waiting", `${delayMs / 1000}s`);
+      await sleep(delayMs);
+      delayMs = Math.min(delayMs * 2, 15 * 60_000);
+    }
+  }
+}

src/bridge/core/bridge.ts

@@ -0,0 +1,27 @@
+import type { Client } from "discord.js";
+
+import { config, validateLinearBridgeConfig } from "@lib/config.js";
+
+import { DiscordConnector } from "@bridge/discord/index.js";
+import { LinearConnector } from "@bridge/linear/index.js";
+
+// Composition root: wires the Discord source to the Linear hub. Adding a source
+// (e.g. GitHub Discussions) means constructing another connector here.
+let connector: DiscordConnector | undefined;
+
+export function registerBridge(client: Client): void {
+  if (!config.linearBridge.enabled) {
+    console.log("[bridge]", "disabled");
+    return;
+  }
+  validateLinearBridgeConfig();
+  connector = new DiscordConnector(client, new LinearConnector());
+  connector.register();
+}
+
+export async function backfillBridge(client: Client): Promise<void> {
+  if (!config.linearBridge.enabled) return;
+  const source =
+    connector ?? new DiscordConnector(client, new LinearConnector());
+  await source.backfill();
+}

src/bridge/core/connector.ts

@@ -0,0 +1,82 @@
+import type {
+  ExternalRef,
+  Message,
+  Post,
+  Reaction,
+} from "@bridge/core/model.js";
+
+export interface IssueState {
+  type: string;
+  name: string;
+}
+
+export interface LinkedIssue {
+  id: string;
+  identifier: string;
+  url: string;
+}
+
+export type ReactionTarget = { issueId: string } | { commentId: string };
+
+// The hub store. Linear implements this today; every method speaks the
+// source-agnostic model so another hub could be swapped in. Keyed by the source
+// entity's ExternalRef (resolved to a hub issue via its URL attachment).
+export interface Target {
+  findIssueId(ref: ExternalRef): Promise<string | null>;
+  ensureIssue(post: Post): Promise<string>;
+  deleteIssue(ref: ExternalRef): Promise<void>;
+
+  // Refresh linking attachment, title, project and labels from the post.
+  reconcile(issueId: string, post: Post): Promise<void>;
+  syncLabels(issueId: string, post: Post): Promise<void>;
+
+  setDescription(issueId: string, text: string): Promise<void>;
+  updateDescription(issueId: string, message: Message): Promise<void>;
+
+  addComment(
+    issueId: string,
+    message: Message,
+    parentId?: string,
+  ): Promise<void>;
+  editComment(issueId: string, message: Message): Promise<boolean>;
+  deleteComment(issueId: string, ref: ExternalRef): Promise<boolean>;
+  mirroredMessageIds(issueId: string): Promise<Set<string>>;
+  resolveReplyParent(
+    issueId: string,
+    messageId: string,
+  ): Promise<string | null>;
+  findCommentId(issueId: string, messageId: string): Promise<string | null>;
+
+  // Plain system note (no marker), e.g. "thread closed".
+  note(issueId: string, body: string, createdAt?: Date): Promise<void>;
+
+  getState(issueId: string): Promise<IssueState | null>;
+  setState(
+    issueId: string,
+    type: "completed" | "triage" | "started",
+    name?: string,
+  ): Promise<void>;
+
+  addReaction(target: ReactionTarget, reaction: Reaction): Promise<void>;
+  removeReaction(target: ReactionTarget, reaction: Reaction): Promise<void>;
+
+  resolveByUrl(url: string): Promise<LinkedIssue | null>;
+  relate(issueId: string, otherId: string): Promise<void>;
+
+  issueRef(issueId: string): Promise<{ identifier: string; url: string }>;
+}
+
+// A platform that originates conversations (Discord today, GitHub Discussions
+// planned). It registers listeners that drive the mirror, enumerates posts for
+// backfill, and writes the hub link back into the source. Everything syncs both
+// ways eventually; a connector grows into the hub's role by implementing more of
+// the reverse direction, so Source and Target are capabilities one module can
+// hold rather than separate layers.
+export interface Source {
+  register(): void;
+  backfill(): Promise<void>;
+  announce(
+    post: Post,
+    issue: { identifier: string; url: string },
+  ): Promise<void>;
+}