collavre_linear 0.1.0

data/app/javascript/collavre_linear.js

@@ -0,0 +1,199 @@
+// Linear integration modal opener.
+//
+// The core integrations menu renders a hidden `#linear-integration-btn` and a
+// menu item whose click-target controller clicks that button. This wires the
+// button click to show `#linear-integration-modal`, mirroring the GitHub engine
+// (collavre_github.js) which does the same for its `github-integration-*` ids.
+//
+// The modal is server-rendered (connect / link / linked states via ERB), but
+// its forms POST to JSON endpoints — Turbo would treat the JSON reply as a
+// failed navigation and leave the modal stuck in its old state. So we submit
+// them via fetch() and reload on success, transitioning to the next state.
+
+// Native window.confirm/alert don't render in the packaged Tauri desktop
+// (WKWebView) — they resolve silently, so a confirm-gated action would fire
+// unconfirmed and errors would vanish. Route through the shared in-app modal
+// like the GitHub/Slack/Notion engines do.
+import { alertDialog, confirmDialog } from 'collavre/lib/utils/dialog';
+
+let linearIntegrationInitialized = false;
+
+if (!linearIntegrationInitialized) {
+  linearIntegrationInitialized = true;
+
+  // The OAuth popup posts `linearConnected` to the opener when it closes.
+  // Reload so the modal re-renders in the connected (link-a-project) state.
+  // Bound to `window` once — it survives Turbo navigations, unlike the
+  // per-navigation element listeners set up in turbo:load below.
+  window.addEventListener('message', function (event) {
+    if (event.origin !== window.location.origin) return;
+    if (event.data && event.data.type === 'linearConnected') {
+      window.location.reload();
+    }
+  });
+
+  // Submit a modal form (link / resync / unlink / paste-secret) to its JSON
+  // endpoint and reload on success. Honors data-confirm and surfaces errors.
+  async function submitLinearModalForm(form, fallbackError) {
+    const confirmMsg = form.dataset.confirm;
+    // Only the destructive unlink form carries data-confirm.
+    if (confirmMsg && !(await confirmDialog(confirmMsg, { danger: true }))) return;
+
+    const genericError = fallbackError || 'Linear request failed.';
+    const token = document.querySelector('meta[name="csrf-token"]')?.content;
+    fetch(form.action, {
+      method: 'POST', // Rails method-override (_method field) handles DELETE
+      headers: {
+        Accept: 'application/json',
+        'X-CSRF-Token': token || '',
+        'X-Requested-With': 'XMLHttpRequest'
+      },
+      body: new FormData(form)
+    })
+      .then(async function (res) {
+        let data = {};
+        try { data = await res.json(); } catch (e) { /* non-JSON body */ }
+        if (res.ok && data.success) {
+          window.location.reload();
+        } else {
+          alertDialog(data.error || data.warning || genericError);
+        }
+      })
+      .catch(function () { alertDialog(genericError); });
+  }
+
+  // Populate the project/team dropdowns from the account's Linear workspace so
+  // users pick by name instead of typing raw IDs. Selecting a project scopes
+  // the team dropdown to that project's owning team(s) and auto-selects when a
+  // project has exactly one team. Fetched lazily (once) when the modal opens.
+  function loadLinkOptions(form) {
+    if (form.dataset.optionsLoaded === '1' || form.dataset.optionsLoading === '1') return;
+    form.dataset.optionsLoading = '1';
+
+    const status = form.querySelector('.linear-options-status');
+    const projectSelect = form.querySelector('select[name="linear_project_id"]');
+    const teamSelect = form.querySelector('select[name="team_id"]');
+    const submitBtn = form.querySelector('input[type="submit"],button[type="submit"]');
+    if (!projectSelect || !teamSelect) return;
+
+    const token = document.querySelector('meta[name="csrf-token"]')?.content;
+    fetch(form.dataset.optionsUrl, {
+      headers: { Accept: 'application/json', 'X-CSRF-Token': token || '', 'X-Requested-With': 'XMLHttpRequest' }
+    })
+      .then(async function (res) {
+        const data = await res.json().catch(function () { return {}; });
+        if (!res.ok) throw new Error(data.error || 'options failed');
+        return data;
+      })
+      .then(function (data) {
+        const teams = data.teams || [];
+        const projects = data.projects || [];
+        const teamName = {};
+        teams.forEach(function (t) { teamName[t.id] = t.name; });
+
+        if (projects.length === 0) {
+          if (status) status.textContent = form.dataset.noProjects;
+          return;
+        }
+
+        projects.forEach(function (p) {
+          const opt = document.createElement('option');
+          opt.value = p.id;
+          opt.textContent = p.name;
+          opt.dataset.teamIds = (p.team_ids || []).join(',');
+          projectSelect.appendChild(opt);
+        });
+
+        // Rebuild the team dropdown for the selected project's team(s).
+        function syncTeams() {
+          const chosen = projectSelect.selectedOptions[0];
+          const ids = (chosen && chosen.dataset.teamIds ? chosen.dataset.teamIds.split(',') : []).filter(Boolean);
+          // Keep the placeholder (first option), drop the rest.
+          while (teamSelect.options.length > 1) teamSelect.remove(1);
+          ids.forEach(function (id) {
+            const opt = document.createElement('option');
+            opt.value = id;
+            opt.textContent = teamName[id] || id;
+            teamSelect.appendChild(opt);
+          });
+          // Auto-select when the project has exactly one team.
+          teamSelect.value = ids.length === 1 ? ids[0] : '';
+          teamSelect.disabled = !projectSelect.value;
+          refreshSubmit();
+        }
+
+        function refreshSubmit() {
+          if (submitBtn) submitBtn.disabled = !(projectSelect.value && teamSelect.value);
+        }
+
+        projectSelect.addEventListener('change', syncTeams);
+        teamSelect.addEventListener('change', refreshSubmit);
+
+        projectSelect.disabled = false;
+        if (status) status.style.display = 'none';
+        form.dataset.optionsLoaded = '1';
+        syncTeams();
+      })
+      .catch(function () {
+        if (status) status.textContent = form.dataset.optionsFailed;
+        form.dataset.optionsLoading = '0'; // allow a retry on reopen
+      });
+  }
+
+  document.addEventListener('turbo:load', function () {
+    const openBtn = document.getElementById('linear-integration-btn');
+    const modal = document.getElementById('linear-integration-modal');
+    if (!openBtn || !modal) return;
+
+    const closeBtn = document.getElementById('close-linear-modal');
+
+    function showModal() {
+      modal.style.display = 'flex';
+      document.body.classList.add('no-scroll');
+      const linkForm = document.getElementById('linear-link-form');
+      if (linkForm && linkForm.dataset.optionsUrl) loadLinkOptions(linkForm);
+    }
+
+    function closeModal() {
+      modal.style.display = 'none';
+      document.body.classList.remove('no-scroll');
+    }
+
+    openBtn.addEventListener('click', function () {
+      showModal();
+    });
+
+    closeBtn?.addEventListener('click', closeModal);
+
+    modal.addEventListener('click', function (event) {
+      if (event.target === modal) closeModal();
+    });
+
+    // OAuth connect: open the popup first, then submit the hidden form with the
+    // native form.submit(). Turbo intercepts submit-button clicks (and would
+    // fetch() the store_creative endpoint, then auto-follow its 302 to Linear's
+    // cross-origin authorize URL → blocked by CORS). Native submit() is not
+    // intercepted, so the popup navigates for real and the redirect follows.
+    const connectBtn = document.getElementById('linear-connect-btn');
+    const connectForm = document.getElementById('linear-connect-form');
+    connectBtn?.addEventListener('click', function () {
+      const w = parseInt(connectBtn.dataset.windowWidth, 10) || 620;
+      const h = parseInt(connectBtn.dataset.windowHeight, 10) || 720;
+      const left = window.screenX + (window.outerWidth - w) / 2;
+      const top = window.screenY + (window.outerHeight - h) / 2;
+      window.open('', 'linear-auth-window', `width=${w},height=${h},left=${left},top=${top}`);
+      connectForm?.submit();
+    });
+
+    // Link / resync / unlink forms POST to JSON endpoints. Intercept their
+    // submit (the connect form is excluded — it's submitted natively above and
+    // form.submit() never fires this event) and drive them via fetch().
+    modal.querySelectorAll('form').forEach(function (form) {
+      if (form.id === 'linear-connect-form') return;
+      form.addEventListener('submit', function (event) {
+        event.preventDefault();
+        submitLinearModalForm(form, modal.dataset.errorGeneric);
+      });
+    });
+  });
+}

data/app/jobs/collavre_linear/inbound_apply_job.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module CollavreLinear
+  # Applies a verified inbound Linear webhook payload to local state.
+  #
+  # Usage:
+  #   CollavreLinear::InboundApplyJob.perform_later(payload)
+  #
+  # Signature verification, timestamp/replay checks, and echo suppression all
+  # happen in WebhooksController BEFORE this job is enqueued. By the time we run,
+  # the payload is trusted.
+  #
+  # The heavy lifting lives in CollavreLinear::InboundApplier (Task 10). Until
+  # that constant exists, this job no-ops gracefully so the webhook pipeline can
+  # ship and be validated independently.
+  class InboundApplyJob < ApplicationJob
+    # Inbound webhooks MUST apply in receipt order: a Comment can arrive before
+    # its issue's Create, and an Update before its Create. Running these on a
+    # multi-threaded queue lets workers apply them out of order — the comment
+    # then finds no IssueLink and is dropped. `linear_inbound` is served by a
+    # single-thread, single-process worker (config/queue.yml), making it a
+    # sequential FIFO queue that preserves enqueue (receipt) order.
+    queue_as :linear_inbound
+
+    def perform(payload)
+      unless CollavreLinear.const_defined?(:InboundApplier)
+        Rails.logger.info(
+          "[CollavreLinear::InboundApplyJob] InboundApplier not defined yet; skipping"
+        )
+        return
+      end
+
+      CollavreLinear::InboundApplier.new(payload).apply!
+    end
+  end
+end

data/app/jobs/collavre_linear/outbound_archive_job.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module CollavreLinear
+  # Archives (soft-deletes) a Linear issue when the corresponding Collavre
+  # Creative is destroyed.
+  #
+  # Usage:
+  #   CollavreLinear::OutboundArchiveJob.perform_later(linear_issue_id, account_id)
+  #
+  # The linear_issue_id and account_id are captured BEFORE the creative row is
+  # deleted (in CreativeSyncObserver#before_destroy) because after_commit on
+  # destroy runs after the row — and its dependent IssueLink — are gone.
+  class OutboundArchiveJob < ApplicationJob
+    queue_as :default
+
+    # Retries on transient Linear API errors.
+    retry_on CollavreLinear::Client::Error, wait: :polynomially_longer, attempts: 5
+
+    def perform(linear_issue_id, account_id)
+      account = CollavreLinear::Account.find(account_id)
+      client  = CollavreLinear::Client.new(account)
+      client.archive_issue(linear_issue_id)
+    rescue ActiveRecord::RecordNotFound
+      Rails.logger.info(
+        "[CollavreLinear::OutboundArchiveJob] Account #{account_id} not found; skipping archive for issue #{linear_issue_id}"
+      )
+    end
+  end
+end

data/app/jobs/collavre_linear/outbound_comment_delete_job.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module CollavreLinear
+  # Deletes the mirrored Linear comment when a Collavre::Comment is destroyed.
+  #
+  #   CollavreLinear::OutboundCommentDeleteJob.perform_later(comment_link.id)
+  #
+  # Keyed on the CommentLink id (not the comment id): the local comment is already
+  # hard-deleted by the time this runs, so the link is the only surviving handle
+  # on the Linear comment id. Idempotent: a re-run after the link is torn down
+  # finds nothing and does nothing.
+  class OutboundCommentDeleteJob < ApplicationJob
+    queue_as :default
+
+    retry_on CollavreLinear::Client::Error, wait: :polynomially_longer, attempts: 5
+
+    def perform(comment_link_id)
+      comment_link = CollavreLinear::CommentLink.find_by(id: comment_link_id)
+      return unless comment_link
+
+      account = comment_link.issue_link.project_link.account
+      return unless account
+
+      comment_link.with_lock do
+        # This delete was enqueued because the comment went private / left Main.
+        # If it became visible again before the job ran, its CommentLink still
+        # exists and the observer's update path enqueues NO recreate (only
+        # private/topic_id changed, not content), so tearing the mirror down now
+        # would strand the re-visible comment off Linear until its next edit.
+        # Re-check under the lock (mirrors the update job): keep the mirror when
+        # the comment is syncable again. A hard-deleted comment is gone → not
+        # syncable → teardown proceeds as before.
+        comment = ::Collavre::Comment.find_by(id: comment_link.comment_id)
+        return if comment && CollavreLinear::CommentSyncability.syncable?(comment)
+
+        CollavreLinear::Client.new(account).delete_comment(comment_link.linear_comment_id)
+        comment_link.destroy
+      end
+    end
+  end
+end

data/app/jobs/collavre_linear/outbound_comment_sync_job.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module CollavreLinear
+  # Pushes a single Collavre::Comment to its linked Linear issue as a comment.
+  #
+  #   CollavreLinear::OutboundCommentSyncJob.perform_later(comment.id)
+  #
+  # Idempotent: the IssueLink row is locked and the CommentLink existence is
+  # re-checked inside the lock, so concurrent performs (or a duplicate enqueue)
+  # never post the same chat message to Linear twice.
+  class OutboundCommentSyncJob < ApplicationJob
+    queue_as :default
+
+    retry_on CollavreLinear::Client::Error, wait: :polynomially_longer, attempts: 5
+
+    def perform(comment_id)
+      comment = ::Collavre::Comment.find(comment_id)
+
+      issue_link = comment.creative&.linear_issue_links&.first
+      return if issue_link&.linear_issue_id.blank?
+
+      account = issue_link.project_link.account
+      return unless account
+
+      # Captured inside the lock so the self-echo rescue can reconcile AFTER the
+      # lock's transaction rolls back — rescuing the unique violation inside the
+      # `with_lock` transaction would poison it (Postgres aborts the whole tx).
+      posted = nil
+
+      begin
+        issue_link.with_lock do
+          # Re-check under the lock: an inbound mirror or a prior run may have
+          # linked this comment already. One Collavre comment -> one Linear comment.
+          return if CollavreLinear::CommentLink.exists?(comment_id: comment.id)
+
+          # Re-check visibility at run time: the comment was public/Main when the
+          # observer enqueued this create, but may have been made private or moved
+          # out of Main since. No CommentLink exists yet, so the observer cannot
+          # enqueue a delete for that change — posting the now-hidden body would
+          # leak it. Same predicate the update job re-runs; here it must no-op.
+          return unless CollavreLinear::CommentSyncability.syncable?(comment)
+
+          posted = CollavreLinear::Client.new(account).create_comment(
+            issue_id: issue_link.linear_issue_id,
+            body:     CollavreLinear::CommentFormatter.outbound_body(comment)
+          )
+          return if posted[:id].blank?
+
+          # Record Linear's updatedAt for this version so the inbound applier can
+          # recognise the create webhook (and any stale echo of it) as our own by
+          # timestamp rather than by comparing against the mutable local body.
+          CollavreLinear::CommentLink.create!(
+            comment_id:        comment.id,
+            linear_comment_id: posted[:id],
+            issue_link:        issue_link,
+            remote_updated_at: posted[:updatedAt]
+          )
+        end
+      rescue ActiveRecord::RecordNotUnique, ActiveRecord::RecordInvalid => e
+        # Self-echo race: the inbound create webhook for the comment we just posted
+        # landed first (app_actor_id is nil, so EchoGuard can't drop it), mirrored
+        # it locally, and grabbed the unique linear_comment_id. Adopt that link onto
+        # our original comment and drop the duplicate mirror — otherwise the comment
+        # is double-represented and our original stays unlinked, so a later edit
+        # re-posts it. Mirrors CreativeExporter#reconcile_self_echo!. Any other
+        # validation error must still surface.
+        raise if e.is_a?(ActiveRecord::RecordInvalid) && !duplicate_comment_link_error?(e)
+
+        reconcile_comment_self_echo!(comment, issue_link, posted)
+      end
+    rescue ActiveRecord::RecordNotFound
+      Rails.logger.info(
+        "[CollavreLinear::OutboundCommentSyncJob] Comment #{comment_id} not found; skipping"
+      )
+    end
+
+    private
+
+    # True when the failure is exactly the CommentLink linear_comment_id
+    # uniqueness collision (the self-echo race), not some other invalid record.
+    def duplicate_comment_link_error?(error)
+      record = error.record
+      record.is_a?(CollavreLinear::CommentLink) &&
+        record.errors.of_kind?(:linear_comment_id, :taken)
+    end
+
+    def reconcile_comment_self_echo!(comment, issue_link, posted)
+      linear_comment_id = posted && posted[:id]
+      return if linear_comment_id.blank?
+
+      existing = CollavreLinear::CommentLink.find_by(linear_comment_id: linear_comment_id)
+      return unless existing
+
+      mirror = ::Collavre::Comment.find_by(id: existing.comment_id)
+      CollavreLinear::CommentLink.transaction do
+        existing.update!(
+          comment_id:        comment.id,
+          issue_link:        issue_link,
+          remote_updated_at: posted[:updatedAt]
+        )
+
+        # Remove the echo duplicate. The link was reassigned above, so the mirror
+        # no longer owns it; skip_linear_sync stops the destroy observer from
+        # posting a Linear delete for the comment we just created.
+        if mirror && mirror.id != comment.id
+          mirror.skip_linear_sync = true
+          mirror.destroy!
+        end
+      end
+    end
+  end
+end

data/app/jobs/collavre_linear/outbound_comment_update_job.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module CollavreLinear
+  # Pushes a local edit of a Collavre::Comment to its mirrored Linear comment.
+  #
+  #   CollavreLinear::OutboundCommentUpdateJob.perform_later(comment.id)
+  #
+  # No-op when the comment (or its CommentLink) is gone: a delete may have raced
+  # ahead, and the delete job owns tearing down the Linear comment.
+  class OutboundCommentUpdateJob < ApplicationJob
+    queue_as :default
+
+    retry_on CollavreLinear::Client::Error, wait: :polynomially_longer, attempts: 5
+
+    def perform(comment_id)
+      comment = ::Collavre::Comment.find(comment_id)
+
+      comment_link = CollavreLinear::CommentLink.find_by(comment_id: comment.id)
+      return unless comment_link
+
+      # Serialize edits of the same mirrored comment. Two quick edits enqueue two
+      # jobs; without the lock one can read body A, the other body B, and if B's
+      # Linear call completes first the older job overwrites Linear back to A while
+      # advancing the baseline — leaving Linear stale until the next edit. Locking
+      # the CommentLink and reloading the comment inside the lock means every run
+      # pushes the current committed body in enqueue order, so the last write wins.
+      comment_link.with_lock do
+        comment.reload
+
+        # Re-check visibility under the lock: the comment may have been made
+        # private or moved out of Main between enqueue and now. The observer
+        # enqueues a delete for that change, but with multiple workers this update
+        # could run first and leak the now-hidden body. The delete job owns
+        # teardown; no-op.
+        return unless CollavreLinear::CommentSyncability.syncable?(comment)
+
+        account = comment_link.issue_link.project_link.account
+        return unless account
+
+        result = CollavreLinear::Client.new(account).update_comment(
+          id:   comment_link.linear_comment_id,
+          body: CollavreLinear::CommentFormatter.outbound_body(comment)
+        )
+
+        # Advance the synced baseline so the echo of this edit (and any stale echo
+        # of an earlier body) is recognised as ours by the inbound applier.
+        comment_link.update!(remote_updated_at: result[:updatedAt]) if result[:updatedAt].present?
+      end
+    rescue ActiveRecord::RecordNotFound
+      Rails.logger.info(
+        "[CollavreLinear::OutboundCommentUpdateJob] Comment #{comment_id} not found; skipping"
+      )
+    end
+  end
+end

data/app/jobs/collavre_linear/outbound_sync_job.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module CollavreLinear
+  # Enqueues an outbound sync for a single Creative to Linear.
+  #
+  # Usage:
+  #   CollavreLinear::OutboundSyncJob.perform_later(creative.id)
+  #
+  # The critical section is guarded with a row-level lock on the IssueLink (or
+  # the ProjectLink's creative row when no IssueLink exists yet) so concurrent
+  # performs cannot double-create issues.
+  class OutboundSyncJob < ApplicationJob
+    queue_as :default
+
+    # Retries on transient Linear API errors.
+    retry_on CollavreLinear::Client::Error, wait: :polynomially_longer, attempts: 5
+
+    # Re-enqueue a child whose parent's Linear issue does not exist yet, so the
+    # child lands AFTER its parent and nests correctly. Independent per-creative
+    # jobs can otherwise run out of order under multiple workers and flatten the
+    # tree. Generous attempts so a slow/retrying parent export still resolves.
+    retry_on CollavreLinear::CreativeExporter::ParentNotExportedError,
+             wait: :polynomially_longer, attempts: 25
+
+    def perform(creative_id)
+      creative = ::Collavre::Creative.find(creative_id)
+
+      # Resolve an existing IssueLink (or the creative itself) to lock on.
+      # We lock the creative row so concurrent jobs serialize without racing to
+      # create duplicate IssueLinks.
+      creative.with_lock do
+        CollavreLinear::CreativeExporter.new(creative).sync!
+      end
+    rescue ActiveRecord::RecordNotFound
+      # Creative was deleted — nothing to sync.
+      Rails.logger.info("[CollavreLinear::OutboundSyncJob] Creative #{creative_id} not found; skipping")
+    end
+  end
+end

data/app/models/collavre_linear/account.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module CollavreLinear
+  class Account < ApplicationRecord
+    self.table_name = "linear_accounts"
+
+    belongs_to :user, class_name: "::User"
+
+    # account_id carries a RESTRICT foreign key, so a user delete (which cascades
+    # here via has_one :linear_account, dependent: :destroy) would hit a FK
+    # violation unless we tear the links down first. Cascades on to issue/comment
+    # links via ProjectLink's own dependent chain.
+    has_many :project_links, class_name: "CollavreLinear::ProjectLink", dependent: :destroy
+
+    encrypts :access_token, deterministic: false
+    encrypts :refresh_token, deterministic: false
+
+    validates :linear_uid, presence: true, uniqueness: true
+    validates :access_token, presence: true
+
+    def token_expired?
+      token_expires_at.present? && token_expires_at < Time.current
+    end
+
+    def token_expiring_soon?(within: 5.minutes)
+      token_expires_at.present? && token_expires_at < Time.current + within
+    end
+  end
+end

data/app/models/collavre_linear/application_record.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module CollavreLinear
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/collavre_linear/comment_link.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module CollavreLinear
+  class CommentLink < ApplicationRecord
+    self.table_name = "linear_comment_links"
+
+    belongs_to :issue_link, class_name: "CollavreLinear::IssueLink"
+
+    validates :comment_id, presence: true
+    validates :linear_comment_id, presence: true, uniqueness: true
+  end
+end

data/app/models/collavre_linear/issue_link.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module CollavreLinear
+  class IssueLink < ApplicationRecord
+    self.table_name = "linear_issue_links"
+
+    belongs_to :creative, class_name: "::Collavre::Creative"
+    belongs_to :project_link, class_name: "CollavreLinear::ProjectLink"
+
+    # linear_comment_links.issue_link_id has an FK to this row; cascade so the
+    # ProjectLink -> IssueLink -> CommentLink chain cleans up fully on unlink.
+    has_many :comment_links, class_name: "CollavreLinear::CommentLink", dependent: :destroy
+
+    enum :sync_state, { synced: 0, dirty: 1, syncing: 2, conflict: 3 }, prefix: false
+
+    validates :linear_issue_id, presence: true, uniqueness: true
+    validates :creative_id, uniqueness: true
+    validates :project_link, presence: true
+  end
+end

data/app/models/collavre_linear/project_link.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module CollavreLinear
+  class ProjectLink < ApplicationRecord
+    self.table_name = "linear_project_links"
+
+    belongs_to :creative, class_name: "::Collavre::Creative"
+    belongs_to :account, class_name: "CollavreLinear::Account"
+
+    # linear_issue_links.project_link_id has an FK to this row; unlinking must
+    # cascade so link.destroy! does not 500 once issues have synced.
+    has_many :issue_links, class_name: "CollavreLinear::IssueLink", dependent: :destroy
+
+    # The HMAC secret Linear signs webhook deliveries with. Linear GENERATES this
+    # when the webhook is created — it can't be forced to a value we pick — so the
+    # admin pastes Linear's secret in (we never mint our own; app actors also lack
+    # the admin scope to auto-provision). Blank until pasted, which is fine: inbound
+    # deliveries just 401 until then (WebhooksController). Encrypted at rest so a
+    # DB/backup leak can't forge webhooks (mirrors Account tokens).
+    encrypts :webhook_secret, deterministic: false
+
+    enum :sync_state, { synced: 0, dirty: 1, syncing: 2, conflict: 3 }, prefix: false
+
+    validates :linear_project_id, presence: true
+    validates :team_id, presence: true
+
+    # A team's single Linear webhook signs every delivery with one secret, so a
+    # second project of an already-configured team inherits that secret rather
+    # than asking the admin to paste it again (no-op for a brand-new team).
+    before_create :adopt_team_webhook_secret
+
+    scope :auto_syncable, -> { where(sync_state: %i[synced dirty]) }
+
+    # Store the signing secret the admin copied from Linear's webhook settings,
+    # propagating it to every sibling ProjectLink of the team. Linear signs all of
+    # a team's deliveries with the one secret its single webhook carries, and
+    # find_project_link resolves a delivery to an arbitrary team sibling, so all
+    # must hold the same value or a sibling 401s. update_column applies encryption
+    # (a raw write would leak plaintext); assign self last so its in-memory
+    # attribute reflects the pasted value.
+    def update_webhook_secret!(secret)
+      self.class.where(team_id: team_id).where.not(id: id).find_each do |sibling|
+        sibling.update_column(:webhook_secret, secret)
+      end
+      update_column(:webhook_secret, secret)
+      secret
+    end
+
+    # The one signing secret a team's single Linear webhook uses, denormalized
+    # across the team's sibling ProjectLinks. Returns any non-blank sibling's
+    # value: a row created concurrently with the admin's paste can commit blank
+    # (adopt ran before the paste was visible), and webhook verification may
+    # resolve a delivery to that blank row — so the TEAM's secret, not one
+    # arbitrary row's column, is the authority. Reads the decrypted attribute
+    # (a raw pick would be ciphertext). Nil when the team has no secret yet.
+    def self.team_webhook_secret(team_id)
+      return if team_id.blank?
+
+      where(team_id: team_id).filter_map { |link| link.webhook_secret.presence }.first
+    end
+
+    private
+
+    # Inherit an existing team sibling's pasted secret so the admin configures one
+    # webhook per team, not per project. webhook_secret is encrypted
+    # (non-deterministic), so a raw column pick would return ciphertext that
+    # re-encrypts into a double-wrapped value → HMAC mismatch; read the DECRYPTED
+    # attribute off loaded siblings instead. Any sibling secret is valid since a
+    # team shares one. Skips when already set or the team has no secret yet.
+    def adopt_team_webhook_secret
+      return if webhook_secret.present? || team_id.blank?
+
+      self.webhook_secret = self.class.team_webhook_secret(team_id)
+    end
+  end
+end