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

[phorcys420]

What

One-way Discord → Linear bridge for the #help forum (MVP for DEVREL-329).

• New help thread → new Linear issue
• New message → issue comment
• Status change (closed/reopened, waiting-for-user/team) → workflow state + labels
• One-way only (no Linear → Discord, no two-way)
• Off by default, toggled via config.linearBridge.enabled

How it's wired

discord.js has no middleware, so the help flow now emits enriched domain events on an internal typed bus (src/lib/bus.ts, no new dep) and the bridge subscribes. The bridge never re-runs isHelpPost.

• helpThreadCreated, helpMessagePosted, helpThreadStatusChanged emitted from events/channels.ts, events/messages.ts, and lib/discord/help.ts.
• Bridge lib under src/bridge/linear/ (subfolder so future bridges sit beside it), using @linear/sdk.

Mapping & metadata (stateless)

• Thread↔issue link lives on Linear as an attachment: url = thread URL (also the issue's Link), title "Discord thread", metadata { threadId, tagIds, tagNames, status, waiting }, readable subtitle. Lookup/dedup via attachmentsForURL.

Labels

• Single team-scoped group Discord (#help) (created with teamId, never global).
• One label per applied tag (except open/closed); label description = the Discord tag ID, and find-or-create matches on that (rename-safe, no dupes). Diffed on status change.
• config.linearBridge.labels.enabled = false → attachment metadata only.

Config

linearBridge { enabled, apiKey, teamId, labels{ enabled, groupName } }, default off. apiKey is env-only (Codercord_linearBridge__apiKey); validateLinearBridgeConfig() exits at startup if enabled without apiKey/teamId.

Backfill

scripts/discord-linear-sync.ts (bun run sync:linear) reuses the same lib to seed existing threads.

Notes / follow-ups

• Adds the privileged MessageContent intent in code; it must be enabled in the Discord dev portal or comment bodies come through empty.
• closed/reopened is emitted only from the ThreadUpdate handler (not close.ts) since /close triggers ThreadUpdate too, avoiding duplicate status comments.
• Out of scope (future issues): Linear → Discord, two-way sync, mention/issue-link resolution, cross-restart message dedup.

Verification

tsc --noEmit clean (incl. script), bun lint/format clean, runtime smoke tests for disabled/enabled/fail-fast paths pass. Bot behavior unchanged when disabled.

Implementation plan

Plan: Discord to Linear bridge (codercord)

Repo coder/codercord · branch phorcys/linear-bridge · one-way MVP for DEVREL-329.

What it does

• Mirrors #help forum threads into Linear: new thread -> new issue; new message -> issue comment; status change -> workflow state + labels.
• One-way only (no Linear -> Discord, no two-way).
• Off by default, toggled via config.linearBridge.enabled.

How it's wired: internal event bus

discord.js has no middleware, so the help flow emits enriched domain events and the bridge subscribes. Bridge never re-runs isHelpPost.

src/lib/bus.ts (typed EventEmitter, no new dep) with:

• helpThreadCreated(ctx)
• helpMessagePosted(ctx)
• helpThreadStatusChanged(ctx)

Emitted from the existing handlers (events/channels.ts, events/messages.ts, lib/discord/help.ts applyWaitingTag, commands/util/close.ts). Emits are best-effort so a consumer error can't break the help flow.

Context resolver in lib/discord/help.ts:

getHelpThreadContext(thread) -> {
  thread, url, title,
  status: "open" | "closed",
  waiting: "user" | "team" | null,
  tags: { id, name }[]   // applied tags minus open/closed
}

Linear side

New dep @linear/sdk. Code under src/bridge/linear/ (subfolder so future bridges live beside it):

• client.ts — LinearClient from config.linearBridge.apiKey.
• api.ts — thin wrappers: find/create issue, comment, set state, attachment upsert, label group + label ensure.
• index.ts — orchestration: mirrorThreadCreated, mirrorMessage, mirrorStatus, ensureIssueForThread.
• src/events/bridge.ts — registerEvents(client); if enabled, subscribe to the bus. Wired into src/index.ts.

Mapping & metadata (stateless)

• Thread<->issue link lives on Linear: an attachment with url = thread URL (also the issue's Link), title "Discord thread", plus metadata { threadId, tagIds, tagNames, status, waiting } and a readable subtitle.
• Lookup/dedup via attachmentsForURL; in-run Map is just a cache.
• Status -> Linear workflow state (closed -> Done, etc.), best-effort.

Labels

• Single team-scoped group Discord (#help) (created with teamId, never global).
• One label per applied tag (except open/closed), name kept verbatim.
• Label description = the Discord tag ID; find-or-create matches on that (rename-safe, no dupes).
• On status change, recompute desired labels from ctx.tags and diff.
• config.linearBridge.labels.enabled = false -> metadata only.

Config (config.ts + config.json.example)

linearBridge: {
  enabled: boolean;   // default false
  apiKey: string;     // env only
  teamId: string;     // required when enabled
  labels?: { enabled: boolean; groupName: string }; // default on, "Discord (#help)"
}

configmasher mandatory is static, so validateLinearBridgeConfig() throws at startup if enabled but apiKey/teamId missing.

Backfill script

scripts/discord-linear-sync.ts (bun scripts/discord-linear-sync.ts, plus a sync:linear package script): logs in, walks active help threads like catchUpHelpPosts, and runs the same src/bridge/linear lib. Keeps the always-on bot lean.

Also

• Add GatewayIntentBits.MessageContent in index.ts (privileged; needs the Discord dev-portal toggle or comment bodies are empty).
• Update AGENTS.md layout + config example.

---

Generated by Coder Agents on behalf of @phorcys420.