collavre_linear 0.1.0

data/app/services/collavre_linear/o_auth_token_service.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module CollavreLinear
+  # Handles Linear OAuth 2.0 flows:
+  #   - authorize_url  : build the URL that sends the user to Linear's OAuth screen
+  #   - exchange       : trade an authorization code for tokens (authorization_code grant)
+  #   - refresh        : silently refresh tokens when they are expiring soon (refresh_token grant)
+  #
+  # Secret resolution order: DB Resolver > ENV > Rails.application.credentials
+  # (consistent with CollavreLinear::Client and other engine services in this codebase)
+  class OAuthTokenService
+    LINEAR_AUTH_ENDPOINT  = "https://linear.app/oauth/authorize"
+    LINEAR_TOKEN_ENDPOINT = "https://api.linear.app/oauth/token"
+    # NOTE: `admin` is intentionally NOT requested. Linear rejects it for app
+    # actors ("App users can't request admin scopes"), which is how we authorize
+    # (actor: "app"). `admin` is only needed to auto-create webhooks via the API,
+    # so inbound sync is wired up MANUALLY instead — the integration modal shows a
+    # one-time setup guide (URL + events) after linking, and the admin pastes back
+    # the signing secret Linear generates for the webhook.
+    OAUTH_SCOPES          = "read,write,issues:create,comments:create"
+
+    class Error < StandardError; end
+
+    class << self
+      # Names of any OAuth secrets that are unset/blank. When non-empty we must
+      # NOT start the flow: a blank redirect_uri produces an authorize URL like
+      # `...&redirect_uri&scope=...` that Linear accepts but can never redirect
+      # back from, so the callback never fires and the account is never created
+      # (Linear just shows the app as "already installed"). client_secret is
+      # checked too: it isn't in the authorize URL, but a blank one would let the
+      # user complete Linear authorization only to fail at token exchange in the
+      # callback — surface the misconfiguration before leaving the app instead.
+      def missing_config
+        { LINEAR_CLIENT_ID: client_id,
+          LINEAR_CLIENT_SECRET: client_secret,
+          LINEAR_OAUTH_REDIRECT_URI: redirect_uri }.select { |_, v| v.blank? }.keys
+      end
+
+      # Build the URL that redirects the user to Linear for authorization.
+      #
+      # @param state [String] CSRF token / opaque value passed through the OAuth flow
+      # @param creative_id [Integer] stored in session before redirect; not sent to Linear
+      # @return [String] full URL including query params
+      def authorize_url(state:, creative_id:)
+        params = {
+          response_type: "code",
+          client_id:     client_id,
+          redirect_uri:  redirect_uri,
+          scope:         OAUTH_SCOPES,
+          actor:         "app",
+          state:         state
+        }
+        "#{LINEAR_AUTH_ENDPOINT}?#{URI.encode_www_form(params)}"
+      end
+
+      # Exchange an authorization code for access + refresh tokens.
+      #
+      # @param code [String] authorization code from Linear callback
+      # @return [Hash] with symbolized keys :access_token, :refresh_token, :expires_in
+      def exchange(code)
+        params = {
+          grant_type:    "authorization_code",
+          code:          code,
+          redirect_uri:  redirect_uri,
+          client_id:     client_id,
+          client_secret: client_secret
+        }
+        post_token!(params)
+      end
+
+      # Refresh tokens if the account is expiring soon.
+      # Persists new token values to the account and returns it.
+      # No-ops (returns account unchanged) if not expiring soon.
+      #
+      # @param account [CollavreLinear::Account]
+      # @return [CollavreLinear::Account]
+      def refresh(account)
+        return account unless account.token_expiring_soon?
+
+        params = {
+          grant_type:    "refresh_token",
+          refresh_token: account.refresh_token,
+          client_id:     client_id,
+          client_secret: client_secret
+        }
+
+        tokens = post_token!(params)
+
+        attrs = {
+          access_token:     tokens[:access_token],
+          token_expires_at: Time.current + tokens[:expires_in].to_i.seconds
+        }
+        attrs[:refresh_token] = tokens[:refresh_token] if tokens[:refresh_token].present?
+        account.update!(attrs)
+        account
+      end
+
+      private
+
+      # Post form-encoded body to the Linear token endpoint.
+      # @return [Hash] symbolized response body
+      def post_token!(params)
+        uri  = URI.parse(LINEAR_TOKEN_ENDPOINT)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = true
+        http.open_timeout = 10
+        http.read_timeout = 15
+
+        request = Net::HTTP::Post.new(uri.path)
+        request["Content-Type"]  = "application/x-www-form-urlencoded"
+        request["Accept"]        = "application/json"
+        request.body             = URI.encode_www_form(params)
+
+        response = http.request(request)
+
+        parsed = begin
+          JSON.parse(response.body)
+        rescue JSON::ParserError
+          raise Error, "Linear returned non-JSON token response (HTTP #{response.code})"
+        end
+
+        unless response.is_a?(Net::HTTPSuccess)
+          error_detail = parsed["error"] || parsed["error_description"] || "(no error field)"
+          raise Error, "Linear token request failed (HTTP #{response.code}): #{error_detail}"
+        end
+
+        parsed.transform_keys(&:to_sym)
+      end
+
+      # Secret resolution: DB Resolver > ENV > Rails credentials
+      def client_id
+        resolve_secret(:linear_client_id) ||
+          Rails.application.credentials.dig(:linear, :client_id)
+      end
+
+      def client_secret
+        resolve_secret(:linear_client_secret) ||
+          Rails.application.credentials.dig(:linear, :client_secret)
+      end
+
+      def redirect_uri
+        resolve_secret(:linear_oauth_redirect_uri) ||
+          Rails.application.credentials.dig(:linear, :oauth_redirect_uri)
+      end
+
+      def resolve_secret(key)
+        return unless defined?(Collavre::IntegrationSettings::Resolver)
+
+        Collavre::IntegrationSettings::Resolver.get(key)
+      rescue Collavre::IntegrationSettings::Resolver::UnknownKeyError
+        ENV[key.to_s.upcase]
+      rescue ActiveRecord::StatementInvalid,
+             ActiveRecord::NoDatabaseError,
+             ActiveRecord::ConnectionNotEstablished
+        ENV[key.to_s.upcase]
+      end
+    end
+  end
+end

data/app/views/collavre_linear/auth/setup.html.erb

@@ -0,0 +1,63 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta name="csrf-token" content="<%= form_authenticity_token %>">
+  <title><%= t('collavre_linear.integration.label', default: 'Linear') %> <%= t('collavre_linear.integration.setup', default: 'Setup') %></title>
+  <style>
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+      background: #f5f5f5;
+      color: #333;
+      padding: 2em;
+      line-height: 1.5;
+    }
+    .wizard-container {
+      max-width: 520px;
+      margin: 0 auto;
+      background: #fff;
+      border-radius: 12px;
+      box-shadow: 0 2px 12px rgba(0,0,0,0.1);
+      padding: 2em;
+    }
+    h2 { margin-bottom: 0.5em; font-size: 1.3em; }
+    .success-msg { color: #16a34a; font-weight: 600; margin: 0.5em 0; text-align: center; }
+    .btn {
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      padding: 0.6em 1.2em;
+      border-radius: 6px;
+      border: 1px solid #ccc;
+      background: #fff;
+      cursor: pointer;
+      font-size: 0.95em;
+    }
+    .btn-primary { background: #5b40cc; color: #fff; border-color: #5b40cc; }
+    .close-btn { margin-top: 1em; width: 100%; }
+  </style>
+</head>
+<body>
+  <div class="wizard-container" id="linear-wizard"
+       data-creative-id="<%= @creative_id %>">
+    <h2><%= t('collavre_linear.integration.label', default: 'Linear') %></h2>
+    <p class="success-msg"><%= t('collavre_linear.auth.connected', default: 'Linear connected successfully.') %></p>
+    <button type="button" id="close-btn" class="btn btn-primary close-btn">
+      <%= t('app.close', default: 'Close') %>
+    </button>
+  </div>
+
+  <script>
+    document.getElementById('close-btn').addEventListener('click', function() {
+      try {
+        if (window.opener) {
+          window.opener.postMessage({ type: 'linearConnected' }, window.location.origin);
+        }
+      } catch (e) {}
+      window.close();
+    });
+  </script>
+</body>
+</html>

data/app/views/collavre_linear/integrations/_modal.html.erb

@@ -0,0 +1,200 @@
+<%#
+  Linear integration modal partial.
+
+  Locals (optional – callers may pass creative):
+    creative:  the Collavre::Creative being configured
+    connected: boolean – whether Current.user has a CollavreLinear::Account
+
+  Rendered by callers with:
+    render "collavre_linear/integrations/modal", creative: @creative
+  (an example with literal ERB tags is omitted here: a nested "%"+">" would
+   terminate this comment early and leak the trailing marker into the page).
+%>
+
+<% connected    = local_assigns.fetch(:connected, Current.user&.linear_account.present?) %>
+<% creative     = local_assigns[:creative] %>
+<% creative_id  = creative&.id %>
+<% project_link = connected && creative &&
+                  creative.effective_origin&.linear_project_links
+                    &.find_by(account: Current.user&.linear_account) %>
+
+<div id="linear-integration-modal"
+     data-creative-id="<%= creative_id %>"
+     data-error-generic="<%= t('collavre_linear.integration.request_failed') %>"
+     style="display:none;position:fixed;top:0;left:0;width:100vw;height:100vh;z-index:10000;
+            align-items:center;justify-content:center;background:rgba(0,0,0,0.4);">
+  <div class="popup-box" style="min-width:340px;max-width:90vw;">
+    <button type="button" id="close-linear-modal" class="popup-close-btn"
+            onclick="document.getElementById('linear-integration-modal').style.display='none'">&times;</button>
+
+    <h2><%= t("collavre_linear.integration.label") %></h2>
+    <p style="margin-bottom:1em;color:var(--text-muted);">
+      <%= t("collavre_linear.integration.description") %>
+    </p>
+
+    <% if connected %>
+      <% if project_link %>
+        <%# --- Already linked --- %>
+        <p style="color:var(--color-success,#16a34a);margin-bottom:0.75em;">
+          <%= t("collavre_linear.integration.linked",
+                project: project_link.linear_project_id,
+                team:    project_link.team_id) %>
+        </p>
+
+        <%# --- Manual webhook setup guide ---
+            Linear GENERATES the signing secret when the webhook is created and
+            won't let us force it to a value we pick, and app actors can't request
+            the `admin` scope to auto-provision — so the admin creates the webhook
+            by hand, then pastes Linear's generated secret back into the form below.
+            Shown until that secret is stored (blank => inbound not yet wired). %>
+        <% secret_set = project_link.webhook_secret.present? %>
+        <%# Use defined semantic tokens (not phantom --color-*-secondary names,
+            whose light hex fallbacks forced a near-white box + invisible text
+            in dark mode). Explicit --text-primary guards inherited contrast. %>
+        <details class="linear-webhook-guide" <%= "open" unless secret_set %>
+                 style="margin-bottom:1em;padding:0.75em;border:1px solid var(--border-color);border-radius:6px;background:var(--surface-secondary);color:var(--text-primary);">
+          <summary style="font-weight:600;cursor:pointer;"><%= t("collavre_linear.integration.webhook_guide_title") %></summary>
+          <p style="margin:0.5em 0;color:var(--text-muted);font-size:0.9em;">
+            <%= t("collavre_linear.integration.webhook_guide_intro") %>
+          </p>
+          <ol style="margin:0 0 0 1.2em;font-size:0.9em;line-height:1.6;">
+            <li>
+              <%= t("collavre_linear.integration.webhook_guide_open_settings_html",
+                    link: link_to("linear.app/settings/api", "https://linear.app/settings/api",
+                                  target: "_blank", rel: "noopener")) %>
+            </li>
+            <li>
+              <%= t("collavre_linear.integration.webhook_guide_url_label") %>
+              <br>
+              <code style="user-select:all;word-break:break-all;background:var(--color-code-bg);color:var(--color-code-text);padding:0.1em 0.3em;border-radius:3px;"><%= "#{request.base_url}/linear/webhook" %></code>
+            </li>
+            <li>
+              <%= t("collavre_linear.integration.webhook_guide_events_label") %>
+              <strong>Issue, Project, Comment</strong>
+            </li>
+            <li>
+              <%= t("collavre_linear.integration.webhook_guide_secret_label") %>
+              <%# Paste Linear's generated secret; the controller stores it and
+                  propagates it to every sibling link of the team. We never render
+                  the stored secret back — it's Linear's to show, not ours. %>
+              <%= form_with url: main_app.respond_to?(:linear_creative_integration_secret_path) ?
+                                 main_app.linear_creative_integration_secret_path(creative_id: creative_id) :
+                                 "/linear/creatives/#{creative_id}/integration/secret",
+                            method: :post, local: false,
+                            html: { style: "margin-top:0.4em;display:flex;gap:0.4em;align-items:center;flex-wrap:wrap;" } do |f| %>
+                <%= f.password_field :webhook_secret, autocomplete: "off",
+                                     placeholder: t("collavre_linear.integration.webhook_secret_placeholder"),
+                                     "aria-label": t("collavre_linear.integration.webhook_secret_input_label"),
+                                     style: "flex:1;min-width:180px;padding:0.35em 0.5em;border:1px solid var(--color-border);border-radius:4px;" %>
+                <%= f.submit t("collavre_linear.integration.webhook_secret_save_button"),
+                             class: "btn btn-primary btn-sm" %>
+              <% end %>
+              <p style="margin:0.4em 0 0;font-size:0.85em;color:<%= secret_set ? "var(--color-success,#16a34a)" : "var(--text-muted)" %>;">
+                <%= secret_set ? t("collavre_linear.integration.webhook_secret_saved") :
+                                 t("collavre_linear.integration.webhook_secret_unset") %>
+              </p>
+            </li>
+          </ol>
+        </details>
+
+        <%# Resync form %>
+        <%= form_with url: main_app.respond_to?(:linear_creative_integration_resync_path) ?
+                           main_app.linear_creative_integration_resync_path(creative_id: creative_id) :
+                           "/linear/creatives/#{creative_id}/integration/resync",
+                      method: :post, local: false,
+                      html: { style: "display:inline;margin-right:0.5em;" } do |f| %>
+          <%= f.submit t("collavre_linear.integration.resync_button"),
+                       class: "btn btn-secondary btn-sm" %>
+        <% end %>
+
+        <%# Unlink form %>
+        <%= form_with url: main_app.respond_to?(:linear_creative_integration_path) ?
+                           main_app.linear_creative_integration_path(creative_id: creative_id) :
+                           "/linear/creatives/#{creative_id}/integration",
+                      method: :delete, local: false,
+                      data: { confirm: t("collavre_linear.integration.unlink_confirm") } do |f| %>
+          <%= f.submit t("collavre_linear.integration.unlink_button"),
+                       class: "btn btn-danger btn-sm" %>
+        <% end %>
+
+      <% else %>
+        <%# --- Connected but not yet linked to a project ---
+            Dropdowns are populated by JS from data-options-url so users pick a
+            project/team by name instead of typing raw Linear IDs. Selecting a
+            project scopes the team dropdown to that project's owning team(s). %>
+        <p style="margin-bottom:0.75em;">
+          <%= t("collavre_linear.integration.link_prompt") %>
+        </p>
+
+        <%= form_with url: main_app.respond_to?(:linear_creative_integration_path) ?
+                           main_app.linear_creative_integration_path(creative_id: creative_id) :
+                           "/linear/creatives/#{creative_id}/integration",
+                      method: :post, local: false,
+                      html: { id: "linear-link-form",
+                              data: { options_url: "/linear/creatives/#{creative_id}/integration/options",
+                                      options_failed: t("collavre_linear.integration.options_failed"),
+                                      no_projects: t("collavre_linear.integration.no_projects") } } do |f| %>
+          <p class="linear-options-status"
+             style="margin-bottom:0.75em;color:var(--text-muted);font-size:0.9em;">
+            <%= t("collavre_linear.integration.options_loading") %>
+          </p>
+
+          <div style="margin-bottom:0.75em;">
+            <%= f.label :linear_project_id, t("collavre_linear.integration.project_id_label"),
+                        style: "display:block;margin-bottom:0.25em;font-weight:600;" %>
+            <%= f.select :linear_project_id,
+                         [],
+                         { include_blank: t("collavre_linear.integration.project_select_placeholder") },
+                         required: true, disabled: true,
+                         style: "width:100%;padding:0.4em 0.6em;border:1px solid var(--color-border);border-radius:4px;" %>
+          </div>
+
+          <div style="margin-bottom:1em;">
+            <%= f.label :team_id, t("collavre_linear.integration.team_id_label"),
+                        style: "display:block;margin-bottom:0.25em;font-weight:600;" %>
+            <%= f.select :team_id,
+                         [],
+                         { include_blank: t("collavre_linear.integration.team_select_placeholder") },
+                         required: true, disabled: true,
+                         style: "width:100%;padding:0.4em 0.6em;border:1px solid var(--color-border);border-radius:4px;" %>
+          </div>
+
+          <%= f.submit t("collavre_linear.integration.link_button"),
+                       class: "btn btn-primary", disabled: true %>
+        <% end %>
+      <% end %>
+
+    <% else %>
+      <%# --- Not connected — show OAuth connect button --- %>
+      <p style="margin-bottom:0.75em;">
+        <%= t("collavre_linear.integration.connect_prompt") %>
+      </p>
+
+      <%#
+        Hidden form + separate button, mirroring collavre_github. The JS opener
+        calls the native form.submit() (not a submit-button click), which Turbo
+        does NOT intercept — so the popup does a real top-level navigation and
+        follows the 302 to Linear's authorize URL. A submit-button click lets
+        Turbo turn it into a fetch(), which auto-follows the cross-origin
+        redirect and is blocked by CORS.
+      %>
+      <form id="linear-connect-form"
+            action="/linear/auth/store_creative"
+            method="post"
+            target="linear-auth-window"
+            style="display:none;">
+        <input type="hidden" name="authenticity_token" value="<%= form_authenticity_token %>">
+        <input type="hidden" name="creative_id" value="<%= creative_id %>">
+      </form>
+      <%# Wrap in a block element: .popup-box is flex-column, so a bare button
+          child stretches to full width. The block wrapper lets the button keep
+          its natural (auto) width, matching the other modal buttons. %>
+      <div>
+        <button type="button" id="linear-connect-btn" class="btn btn-primary"
+                data-window-width="620" data-window-height="720">
+          <%= t("collavre_linear.integration.connect_button") %>
+        </button>
+      </div>
+    <% end %>
+  </div>
+</div>

data/config/initializers/integration_settings.rb

@@ -0,0 +1,8 @@
+# Register collavre_linear integration setting keys with the central registry.
+if defined?(Collavre::IntegrationSettings::Registry)
+  registry = Collavre::IntegrationSettings::Registry.instance
+  registry.register(:linear_api_endpoint,       category: "linear", sensitive: false, requires_restart: false)
+  registry.register(:linear_client_id,          category: "linear", sensitive: false, requires_restart: true)
+  registry.register(:linear_client_secret,      category: "linear", sensitive: true,  requires_restart: true)
+  registry.register(:linear_oauth_redirect_uri, category: "linear", sensitive: false, requires_restart: false)
+end

data/config/locales/en.yml

@@ -0,0 +1,49 @@
+en:
+  collavre_linear:
+    auth:
+      connected: "Linear connected successfully."
+      invalid_state: "Invalid OAuth state. Please try connecting again."
+      login_first: "Please log in first."
+      already_linked_other: "This Linear account is already connected to a different Collavre user."
+      oauth_config_missing: "Linear OAuth is not configured (%{keys}). Set these before connecting."
+    integration:
+      label: "Linear"
+      description: "Two-way sync of projects, issues and comments"
+      setup: "Setup"
+      connect_prompt: "Connect your Linear account to start syncing."
+      connect_button: "Connect Linear"
+      link_prompt: "Select a Linear project and team to link this creative."
+      team_id_label: "Team"
+      project_id_label: "Project"
+      project_select_placeholder: "Select a project…"
+      team_select_placeholder: "Select a team…"
+      options_loading: "Loading projects and teams…"
+      options_failed: "Couldn't load your Linear projects and teams. Please try again."
+      no_projects: "No projects found in your Linear workspace."
+      link_button: "Link Project"
+      linked: "Linked to project %{project} (team %{team})"
+      unlink_button: "Unlink"
+      unlink_confirm: "Remove Linear integration from this creative?"
+      resync_button: "Re-sync now"
+      resync_started: "Re-sync started. Issues will update shortly."
+      missing_creative: "creative_id is required"
+      webhook_guide_title: "Enable inbound sync (one-time webhook setup)"
+      webhook_guide_intro: "Outbound sync (Collavre → Linear) works now. To also receive changes from Linear, a workspace admin creates one webhook:"
+      webhook_guide_open_settings_html: "Open %{link} → Webhooks → New webhook."
+      webhook_guide_url_label: "Set the URL to:"
+      webhook_guide_events_label: "Subscribe to these events:"
+      webhook_guide_secret_label: "Create the webhook, then copy the signing secret Linear generated and paste it below:"
+      webhook_secret_input_label: "Linear signing secret"
+      webhook_secret_placeholder: "lin_wh_…"
+      webhook_secret_save_button: "Save secret"
+      webhook_secret_saved: "✓ Signing secret saved — inbound sync is active. Paste again to update it if you roll it in Linear."
+      webhook_secret_unset: "Inbound sync stays inactive until you paste the signing secret from Linear."
+      request_failed: "Linear request failed. Please try again."
+      conflict_notice: "⚠️ Linear sync conflict: this item was edited both locally and in Linear. The remote change was NOT applied to avoid overwriting local edits. Resolve manually and re-sync."
+    errors:
+      not_connected: "Linear account not connected."
+      missing_params: "team_id and linear_project_id are required."
+      not_found: "Linear project link not found."
+      forbidden: "Access denied."
+      overlapping_link: "A parent or child of this item is already linked to Linear. Unlink it first, or link a non-overlapping item."
+      missing_secret: "Paste the signing secret Linear generated for the webhook."

data/config/locales/ko.yml

@@ -0,0 +1,49 @@
+ko:
+  collavre_linear:
+    auth:
+      connected: "Linear 연결 성공."
+      invalid_state: "OAuth 상태가 유효하지 않습니다. 다시 연결해 주세요."
+      login_first: "먼저 로그인해 주세요."
+      already_linked_other: "이 Linear 계정은 이미 다른 Collavre 사용자에 연결되어 있습니다."
+      oauth_config_missing: "Linear OAuth가 설정되지 않았습니다 (%{keys}). 연결 전에 설정해 주세요."
+    integration:
+      label: "Linear"
+      description: "프로젝트, 이슈, 댓글 양방향 동기화"
+      setup: "설정"
+      connect_prompt: "Linear 계정을 연결하여 동기화를 시작하세요."
+      connect_button: "Linear 연결"
+      link_prompt: "이 크리에이티브에 연결할 Linear 프로젝트와 팀을 선택하세요."
+      team_id_label: "팀"
+      project_id_label: "프로젝트"
+      project_select_placeholder: "프로젝트 선택…"
+      team_select_placeholder: "팀 선택…"
+      options_loading: "프로젝트와 팀을 불러오는 중…"
+      options_failed: "Linear 프로젝트와 팀을 불러오지 못했습니다. 다시 시도해 주세요."
+      no_projects: "Linear 워크스페이스에 프로젝트가 없습니다."
+      link_button: "프로젝트 연결"
+      linked: "프로젝트 %{project} 연결됨 (팀 %{team})"
+      unlink_button: "연결 해제"
+      unlink_confirm: "이 크리에이티브에서 Linear 연동을 제거하시겠습니까?"
+      resync_button: "지금 재동기화"
+      resync_started: "재동기화 시작됨. 이슈가 곧 업데이트됩니다."
+      missing_creative: "creative_id가 필요합니다"
+      webhook_guide_title: "인바운드 동기화 활성화 (1회성 웹훅 설정)"
+      webhook_guide_intro: "아웃바운드 동기화(Collavre → Linear)는 이미 동작합니다. Linear의 변경 사항도 받으려면 워크스페이스 관리자가 웹훅 하나를 생성해야 합니다:"
+      webhook_guide_open_settings_html: "%{link} → Webhooks → New webhook 을 엽니다."
+      webhook_guide_url_label: "URL 을 다음으로 설정합니다:"
+      webhook_guide_events_label: "다음 이벤트를 구독합니다:"
+      webhook_guide_secret_label: "웹훅을 생성한 뒤, Linear가 생성한 서명 시크릿(signing secret)을 복사해 아래에 붙여넣습니다:"
+      webhook_secret_input_label: "Linear 서명 시크릿"
+      webhook_secret_placeholder: "lin_wh_…"
+      webhook_secret_save_button: "시크릿 저장"
+      webhook_secret_saved: "✓ 서명 시크릿이 저장되었습니다 — 인바운드 동기화가 활성화되었습니다. Linear에서 시크릿을 갱신하면 다시 붙여넣어 업데이트하세요."
+      webhook_secret_unset: "Linear의 서명 시크릿을 붙여넣기 전까지 인바운드 동기화는 비활성 상태입니다."
+      request_failed: "Linear 요청에 실패했습니다. 다시 시도해 주세요."
+      conflict_notice: "⚠️ Linear 동기화 충돌: 이 항목이 로컬과 Linear 양쪽에서 수정되었습니다. 로컬 변경을 덮어쓰지 않기 위해 원격 변경은 적용되지 않았습니다. 수동으로 해결한 후 다시 동기화해 주세요."
+    errors:
+      not_connected: "Linear 계정이 연결되지 않았습니다."
+      missing_params: "team_id와 linear_project_id가 필요합니다."
+      not_found: "Linear 프로젝트 링크를 찾을 수 없습니다."
+      forbidden: "접근이 거부되었습니다."
+      overlapping_link: "이 항목의 상위 또는 하위 항목이 이미 Linear에 연결되어 있습니다. 먼저 연결을 해제하거나 겹치지 않는 항목을 연결하세요."
+      missing_secret: "Linear가 웹훅에 대해 생성한 서명 시크릿을 붙여넣으세요."

data/config/routes.rb

@@ -0,0 +1,22 @@
+CollavreLinear::Engine.routes.draw do
+  # OAuth callback from Linear
+  get  "auth/callback",      to: "auth#callback",       as: :auth_callback
+  # Setup wizard after OAuth succeeds
+  get  "auth/setup",         to: "auth#setup",          as: :setup_auth
+  # Store creative_id in session before redirecting to Linear
+  post "auth/store_creative", to: "auth#store_creative", as: :store_creative_auth
+
+  # Inbound webhook from Linear (HMAC-signed, machine-to-machine, no user session)
+  post "webhook", to: "webhooks#create", as: :webhook
+
+  # Creative integration endpoints (link / unlink / resync)
+  resources :creatives, only: [] do
+    resource :integration, module: :creatives, only: [ :create, :destroy ] do
+      post :resync, on: :member
+      # Store the signing secret the admin pasted from Linear's webhook settings.
+      post :secret, on: :member, action: :update_secret
+      # Teams/projects for the link picker (populated as dropdowns in the modal).
+      get :options, on: :member
+    end
+  end
+end

data/db/migrate/20260701000000_create_linear_accounts.rb

@@ -0,0 +1,20 @@
+class CreateLinearAccounts < ActiveRecord::Migration[8.0]
+  def change
+    create_table :linear_accounts do |t|
+      t.references :user, null: false, foreign_key: true, index: { unique: true }
+      t.string :linear_uid, null: false
+      t.string :app_actor_id
+      # OAuth tokens are stored via ActiveRecord encryption; the encrypted
+      # envelope of a real Linear access/refresh token exceeds the 255-byte
+      # `string` limit in PostgreSQL, so use `text` to avoid save failures.
+      t.text :access_token, null: false
+      t.text :refresh_token
+      t.datetime :token_expires_at
+      t.string :workspace_id
+      t.string :workspace_name
+      t.timestamps
+    end
+
+    add_index :linear_accounts, :linear_uid, unique: true
+  end
+end

data/db/migrate/20260701000001_create_collavre_linear_project_links.rb

@@ -0,0 +1,18 @@
+class CreateCollavreLinearProjectLinks < ActiveRecord::Migration[8.0]
+  def change
+    create_table :linear_project_links do |t|
+      t.references :creative, null: false, foreign_key: { to_table: :creatives }
+      t.references :account, null: false, foreign_key: { to_table: :linear_accounts }
+      t.string :linear_project_id, null: false
+      t.string :team_id, null: false
+      # Encrypted at rest (ActiveRecord encryption); the envelope can exceed the
+      # 255-byte `string` limit in PostgreSQL, so store it in a `text` column.
+      t.text :webhook_secret, null: false
+      t.integer :sync_state, null: false, default: 0
+      t.datetime :last_synced_at
+      t.timestamps
+    end
+
+    add_index :linear_project_links, [ :creative_id, :linear_project_id ], unique: true, name: "index_linear_project_links_on_creative_and_project"
+  end
+end

data/db/migrate/20260701000002_create_collavre_linear_issue_links.rb

@@ -0,0 +1,22 @@
+class CreateCollavreLinearIssueLinks < ActiveRecord::Migration[8.0]
+  def change
+    create_table :linear_issue_links do |t|
+      # One IssueLink per Creative — enforce with a single unique index. Pass
+      # index: { unique: true } to t.references rather than a separate
+      # `add_index :creative_id, unique: true`: the latter collides with the
+      # non-unique index t.references creates by default (same generated name),
+      # which raises "index already exists" on a fresh migrate.
+      t.references :creative, null: false, foreign_key: { to_table: :creatives }, index: { unique: true }
+      t.references :project_link, null: false, foreign_key: { to_table: :linear_project_links }
+      t.string :linear_issue_id, null: false
+      t.string :parent_issue_id
+      t.integer :local_version, null: false, default: 0
+      t.datetime :remote_updated_at
+      t.string :content_hash
+      t.integer :sync_state, null: false, default: 0
+      t.timestamps
+    end
+
+    add_index :linear_issue_links, :linear_issue_id, unique: true
+  end
+end

data/db/migrate/20260701000003_create_collavre_linear_comment_links.rb

@@ -0,0 +1,17 @@
+class CreateCollavreLinearCommentLinks < ActiveRecord::Migration[8.0]
+  def change
+    create_table :linear_comment_links do |t|
+      t.integer :comment_id, null: false
+      t.string :linear_comment_id, null: false
+      t.references :issue_link, null: false, foreign_key: { to_table: :linear_issue_links }
+      # Linear-side `updatedAt` of the comment version we last synced. Lets the
+      # inbound applier ignore our own (possibly stale) echoes by timestamp
+      # instead of comparing against the mutable local body.
+      t.datetime :remote_updated_at
+      t.timestamps
+    end
+
+    add_index :linear_comment_links, :comment_id, unique: true
+    add_index :linear_comment_links, :linear_comment_id, unique: true
+  end
+end

data/db/migrate/20260701000004_add_last_outbound_at_to_linear_links.rb

@@ -0,0 +1,6 @@
+class AddLastOutboundAtToLinearLinks < ActiveRecord::Migration[8.0]
+  def change
+    add_column :linear_project_links, :last_outbound_at, :datetime
+    add_column :linear_issue_links, :last_outbound_at, :datetime
+  end
+end

data/db/migrate/20260701000005_add_webhook_id_to_linear_project_links.rb

@@ -0,0 +1,5 @@
+class AddWebhookIdToLinearProjectLinks < ActiveRecord::Migration[8.0]
+  def change
+    add_column :linear_project_links, :webhook_id, :string
+  end
+end