collavre_linear 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5cc482eb53e316ac259f9565368c50a59cbd1dce01be3b74100c41b239919731
-  data.tar.gz: cccca601d9c57cd0d45ee603d50b46663d6d3daac3373e93a4b4e3b9b59348b1
+  metadata.gz: d8004796cae3abe1389345fbd85959f2390e8d8930768c86045ba202ca94c5e1
+  data.tar.gz: 0e6f414178db0ee5513f238cac0fabf75a44b4eea80a1f7142ce94487bbff798
 SHA512:
-  metadata.gz: e4a88144150cd9d67ff55433fde009579709cb572cdc08a7cd5209c6d187394917a0efdcd8bbd6a73d60e85fc46ae5d21e8ac731b015b0a0973819e73b51cd61
-  data.tar.gz: 28ee1fc888af6a9a86fd2b18f30883668d273111ad01912a14cc73e0eb598ae412c0efd0733e850013e4da2e81bd4b888b564e74e0e654619df849457d13ec2c
+  metadata.gz: 258031f64f076de07891357445af346b6bc10c75d43fb802d2a749eb1c7069bc4d81ca64a66366b0875b2f971c8bd986c223fb133ca47dcbc0ed9c86d936cf37
+  data.tar.gz: 07b41024a06d0d5074a43685a2dfbab697f92990fb6100849fcf893c38159665c553254bdaca8f40f5ea209b632dc6b880d583a133047a80a47cb0e89d2c25c0

data/app/controllers/collavre_linear/creatives/integrations_controller.rb

@@ -88,6 +88,10 @@ module CollavreLinear
                 linear_project_id: linear_project_id
               )
               link.team_id = team_id
+              # The Linear workflow-state UUID the admin picked as "done" (combobox,
+              # default Completed). Blank when the team has no completed state or the
+              # picker was cleared — completion mapping then no-ops both directions.
+              link.done_state_id = params[:done_state_id].to_s.presence
               link.save!
             end
           end
@@ -224,7 +228,11 @@ module CollavreLinear
         end
 
         client = CollavreLinear::Client.new(account)
-        render json: { teams: client.list_teams, projects: client.list_projects }
+        render json: {
+          teams:    client.list_teams,
+          projects: client.list_projects,
+          states:   client.list_workflow_states
+        }
       rescue CollavreLinear::Client::Error => e
         # Surface the Linear-side failure (expired token, revoked scope) instead
         # of leaving the dropdowns silently empty.
@@ -262,6 +270,7 @@ module CollavreLinear
           id:                link.id,
           team_id:           link.team_id,
           linear_project_id: link.linear_project_id,
+          done_state_id:     link.done_state_id,
           sync_state:        link.sync_state,
           webhook_id:        link.webhook_id
         }

data/app/controllers/collavre_linear/webhooks_controller.rb

@@ -178,7 +178,7 @@ module CollavreLinear
       return false if ts.blank?
 
       ts_ms = Integer(ts)
-      now_ms = (Time.now.to_f * 1000).to_i
+      now_ms = (Time.current.to_f * 1000).to_i
       (now_ms - ts_ms).abs <= TIMESTAMP_WINDOW_MS
     rescue ArgumentError, TypeError
       false

data/app/javascript/__tests__/linear_modal_reopen.test.js

@@ -0,0 +1,178 @@
+import {
+  LINEAR_REOPEN_KEY,
+  markReopenAfterConnect,
+  consumeReopenAfterConnect,
+  safeSessionStorage,
+} from '../linear_modal_reopen.js';
+
+// Minimal in-memory Storage stand-in (jsdom's is fine too, but this keeps the
+// unit test free of environment setup and lets us model a throwing storage).
+function fakeStorage() {
+  const map = new Map();
+  return {
+    setItem: (k, v) => map.set(k, String(v)),
+    getItem: (k) => (map.has(k) ? map.get(k) : null),
+    removeItem: (k) => map.delete(k),
+    _size: () => map.size,
+  };
+}
+
+describe('safeSessionStorage', () => {
+  test('returns the storage object when Web Storage is available', () => {
+    // jsdom provides a working window.sessionStorage.
+    expect(safeSessionStorage()).toBe(window.sessionStorage);
+  });
+
+  test('returns null when the window.sessionStorage getter itself throws', () => {
+    // Web Storage disabled by policy (packaged WKWebView, storage-blocked
+    // browser) throws on the property *access*, before any value is passed to
+    // mark/consume. safeSessionStorage must absorb it so callers never throw.
+    const original = Object.getOwnPropertyDescriptor(window, 'sessionStorage');
+    Object.defineProperty(window, 'sessionStorage', {
+      configurable: true,
+      get() { throw new Error('SecurityError: storage disabled'); },
+    });
+    try {
+      expect(() => safeSessionStorage()).not.toThrow();
+      expect(safeSessionStorage()).toBeNull();
+    } finally {
+      if (original) Object.defineProperty(window, 'sessionStorage', original);
+    }
+  });
+});
+
+describe('markReopenAfterConnect', () => {
+  test('persists the unscoped sentinel when no creative id is given', () => {
+    const storage = fakeStorage();
+    markReopenAfterConnect(storage);
+    expect(storage.getItem(LINEAR_REOPEN_KEY)).toBe('*');
+  });
+
+  test('the unscoped sentinel cannot equal any serialized creative id', () => {
+    // Creative ids are positive integers → digit strings. The sentinel must be a
+    // non-digit so a real id never gets misread as "unscoped".
+    const storage = fakeStorage();
+    markReopenAfterConnect(storage);
+    expect(storage.getItem(LINEAR_REOPEN_KEY)).not.toMatch(/^\d+$/);
+  });
+
+  test('persists the creative id when given (scoped reopen)', () => {
+    const storage = fakeStorage();
+    markReopenAfterConnect(storage, 42);
+    expect(storage.getItem(LINEAR_REOPEN_KEY)).toBe('42');
+  });
+
+  test('falls back to the unscoped sentinel for an empty creative id', () => {
+    const storage = fakeStorage();
+    markReopenAfterConnect(storage, '');
+    expect(storage.getItem(LINEAR_REOPEN_KEY)).toBe('*');
+  });
+
+  test('tolerates a null storage without throwing', () => {
+    expect(() => markReopenAfterConnect(null)).not.toThrow();
+  });
+
+  test('swallows storage errors (private mode / WKWebView)', () => {
+    const throwing = { setItem: () => { throw new Error('QuotaExceeded'); } };
+    expect(() => markReopenAfterConnect(throwing)).not.toThrow();
+  });
+});
+
+describe('consumeReopenAfterConnect', () => {
+  test('returns true exactly once, then clears the flag (regression)', () => {
+    // Without the one-shot clear, every subsequent reload — including the one
+    // after a successful link — would reopen the modal. It must fire once.
+    const storage = fakeStorage();
+    markReopenAfterConnect(storage);
+
+    expect(consumeReopenAfterConnect(storage)).toBe(true);
+    expect(consumeReopenAfterConnect(storage)).toBe(false);
+    expect(storage.getItem(LINEAR_REOPEN_KEY)).toBeNull();
+  });
+
+  test('reopens only when the current creative matches the stored one', () => {
+    const storage = fakeStorage();
+    markReopenAfterConnect(storage, 42); // popup connected creative 42
+    // Opener is on the same creative → reopen.
+    expect(consumeReopenAfterConnect(storage, 42)).toBe(true);
+  });
+
+  test('does NOT reopen when the opener navigated to a different creative', () => {
+    // Codex P2: mid-flow navigation must not surface the wrong creative's modal.
+    const storage = fakeStorage();
+    markReopenAfterConnect(storage, 42); // popup connected creative 42
+    // Opener moved to creative 99 before the reload → no reopen, flag cleared.
+    expect(consumeReopenAfterConnect(storage, 99)).toBe(false);
+    expect(storage.getItem(LINEAR_REOPEN_KEY)).toBeNull();
+  });
+
+  test('creative id 1 stays scoped and does NOT reopen a different creative', () => {
+    // Regression: the sentinel used to be '1', colliding with creative id 1 — so
+    // OAuth from creative 1 was misread as unscoped and reopened whatever modal
+    // the opener had navigated to. It must behave like any other scoped id.
+    const storage = fakeStorage();
+    markReopenAfterConnect(storage, 1);           // popup connected creative 1
+    expect(consumeReopenAfterConnect(storage, 99)).toBe(false); // opener moved away
+  });
+
+  test('creative id 1 reopens when the opener is still on creative 1', () => {
+    const storage = fakeStorage();
+    markReopenAfterConnect(storage, 1);
+    expect(consumeReopenAfterConnect(storage, 1)).toBe(true);
+  });
+
+  test('clears a mismatched intent so it never fires on a later matching visit', () => {
+    const storage = fakeStorage();
+    markReopenAfterConnect(storage, 42);
+    consumeReopenAfterConnect(storage, 99); // mismatch on the reload
+    // Later navigation back to creative 42 must NOT auto-open — intent was spent.
+    expect(consumeReopenAfterConnect(storage, 42)).toBe(false);
+  });
+
+  test('matches across id string/number coercion', () => {
+    const storage = fakeStorage();
+    markReopenAfterConnect(storage, 42);        // stored as '42'
+    expect(consumeReopenAfterConnect(storage, '42')).toBe(true); // dataset is a string
+  });
+
+  test('unscoped sentinel reopens regardless of current creative (legacy)', () => {
+    const storage = fakeStorage();
+    markReopenAfterConnect(storage);            // no id → '1'
+    expect(consumeReopenAfterConnect(storage, 7)).toBe(true);
+  });
+
+  test('returns false when no reopen was pending', () => {
+    expect(consumeReopenAfterConnect(fakeStorage())).toBe(false);
+  });
+
+  test('tolerates a null storage', () => {
+    expect(consumeReopenAfterConnect(null)).toBe(false);
+  });
+
+  test('swallows storage errors and reports no pending reopen', () => {
+    const throwing = { getItem: () => { throw new Error('SecurityError'); } };
+    expect(consumeReopenAfterConnect(throwing)).toBe(false);
+  });
+
+  test('end-to-end via safeSessionStorage: mark on connect, consume once', () => {
+    // The call sites pass safeSessionStorage() rather than window.sessionStorage
+    // directly, so the whole flow must survive a storage-backed session.
+    const s = safeSessionStorage();
+    if (!s) return; // jsdom always provides it; guard just in case
+    s.removeItem(LINEAR_REOPEN_KEY);
+    markReopenAfterConnect(s);
+    expect(consumeReopenAfterConnect(s)).toBe(true);
+    expect(consumeReopenAfterConnect(s)).toBe(false);
+  });
+
+  test('end-to-end: mark on connect, consume on the next load', () => {
+    // Mirrors the real flow: the postMessage handler marks, the reload happens,
+    // then turbo:load consumes the flag and opens the modal exactly once.
+    const storage = fakeStorage();
+    markReopenAfterConnect(storage);          // linearConnected received
+    const reopenedFirstLoad = consumeReopenAfterConnect(storage);   // turbo:load
+    const reopenedSecondLoad = consumeReopenAfterConnect(storage);  // later nav
+    expect(reopenedFirstLoad).toBe(true);
+    expect(reopenedSecondLoad).toBe(false);
+  });
+});

data/app/javascript/collavre_linear.js

@@ -15,19 +15,38 @@
 // 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';
+import {
+  markReopenAfterConnect,
+  consumeReopenAfterConnect,
+  safeSessionStorage,
+} from './linear_modal_reopen.js';
 
 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.
+  // The OAuth popup posts `linearConnected` to the opener once the account is
+  // connected. Reload so the modal re-renders in the connected (link-a-project)
+  // state, then reopen it (see turbo:load) so the user lands directly on the
+  // project settings step instead of a closed modal.
   // 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') {
+      // Close the popup from here. window.close() inside the popup is unreliable
+      // after the cross-origin OAuth round trip and in the desktop WebView, so
+      // the popup's own "Close" button looked dead — closing the window we
+      // opened is the reliable path.
+      try {
+        if (event.source && !event.source.closed) event.source.close();
+      } catch (e) { /* cross-origin or already closed */ }
+      // Survive the reload: reopen the modal on the next load so the flow lands
+      // on the project-link step automatically. Scope it to the creative the
+      // popup was opened for (event.data.creativeId) so a mid-flow navigation to
+      // a different creative doesn't auto-open the wrong creative's link modal.
+      markReopenAfterConnect(safeSessionStorage(), event.data.creativeId);
       window.location.reload();
     }
   });
@@ -73,6 +92,7 @@ if (!linearIntegrationInitialized) {
     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 stateSelect = form.querySelector('select[name="done_state_id"]');
     const submitBtn = form.querySelector('input[type="submit"],button[type="submit"]');
     if (!projectSelect || !teamSelect) return;
 
@@ -88,6 +108,7 @@ if (!linearIntegrationInitialized) {
       .then(function (data) {
         const teams = data.teams || [];
         const projects = data.projects || [];
+        const states = data.states || [];
         const teamName = {};
         teams.forEach(function (t) { teamName[t.id] = t.name; });
 
@@ -119,15 +140,41 @@ if (!linearIntegrationInitialized) {
           // Auto-select when the project has exactly one team.
           teamSelect.value = ids.length === 1 ? ids[0] : '';
           teamSelect.disabled = !projectSelect.value;
+          syncStates();
           refreshSubmit();
         }
 
+        // Rebuild the done-state dropdown for the selected team and default to
+        // that team's Completed state. Optional field — no completed state (or no
+        // team chosen) leaves it blank and completion mapping stays off.
+        function syncStates() {
+          if (!stateSelect) return;
+          const teamId = teamSelect.value;
+          while (stateSelect.options.length > 1) stateSelect.remove(1);
+          const teamStates = states
+            .filter(function (s) { return s.team_id === teamId; })
+            .sort(function (a, b) { return (a.position || 0) - (b.position || 0); });
+          teamStates.forEach(function (s) {
+            const opt = document.createElement('option');
+            opt.value = s.id;
+            opt.textContent = s.name;
+            opt.dataset.type = s.type || '';
+            stateSelect.appendChild(opt);
+          });
+          const completed = teamStates.filter(function (s) { return s.type === 'completed'; });
+          const named = completed.find(function (s) {
+            return (s.name || '').toLowerCase() === 'completed';
+          });
+          stateSelect.value = named ? named.id : (completed[0] ? completed[0].id : '');
+          stateSelect.disabled = !teamId;
+        }
+
         function refreshSubmit() {
           if (submitBtn) submitBtn.disabled = !(projectSelect.value && teamSelect.value);
         }
 
         projectSelect.addEventListener('change', syncTeams);
-        teamSelect.addEventListener('change', refreshSubmit);
+        teamSelect.addEventListener('change', function () { syncStates(); refreshSubmit(); });
 
         projectSelect.disabled = false;
         if (status) status.style.display = 'none';
@@ -163,6 +210,15 @@ if (!linearIntegrationInitialized) {
       showModal();
     });
 
+    // Just returned from the OAuth popup: open the modal straight to the
+    // project-link step instead of leaving the (display:none) modal closed, so
+    // the user doesn't have to reopen the Linear menu by hand. Only reopen when
+    // this page's creative matches the one the popup connected for — otherwise a
+    // mid-flow navigation would surface the wrong creative's link modal.
+    if (consumeReopenAfterConnect(safeSessionStorage(), modal.dataset.creativeId)) {
+      showModal();
+    }
+
     closeBtn?.addEventListener('click', closeModal);
 
     modal.addEventListener('click', function (event) {

data/app/javascript/linear_modal_reopen.js

@@ -0,0 +1,74 @@
+// Reopen-after-connect intent for the Linear integration modal.
+//
+// When the OAuth popup finishes it posts `linearConnected` and the opener does a
+// full `window.location.reload()` so the server re-renders the modal in its
+// project-linking state (the account now exists). But the modal defaults to
+// `display:none` and nothing re-opens it after the reload — so the connect→link
+// step is invisible and the user has to click the Linear connect button again to
+// reach it.
+//
+// This module persists a one-shot "reopen the modal" flag across that reload.
+// Factored out of the side-effectful collavre_linear.js opener so the behavior
+// is unit-testable (that file is imported only for its window/turbo listeners).
+
+export const LINEAR_REOPEN_KEY = 'linearReopenModal';
+
+// Read window.sessionStorage defensively. When Web Storage is disabled by policy
+// (packaged WKWebView, a browser blocking storage for the site) the property
+// getter *itself* throws — before any value reaches mark/consume — so guarding
+// only inside those functions is not enough; the access site must be guarded
+// too. Returns null when unavailable so callers never take an uncaught throw.
+export function safeSessionStorage() {
+  try {
+    return window.sessionStorage;
+  } catch (e) {
+    return null;
+  }
+}
+
+// Unscoped sentinel. Stored when the OAuth creative id is unknown so the reopen
+// still fires (matches any page) — the scoped path stores the id instead. Must
+// be a value no serialized creative id can equal: ids are positive integers and
+// serialize to digit strings, so a non-digit marker never collides. (A previous
+// '1' sentinel collided with creative id 1 — that page's scoped reopen was
+// misread as unscoped and skipped the mismatch guard.)
+const UNSCOPED = '*';
+
+// Record that the modal should reopen after the next full-page reload, scoped to
+// the creative the OAuth popup was opened for. The popup posts its own
+// creativeId; storing it lets consume verify the reloaded page still shows that
+// same creative before reopening — otherwise, if the opener navigated to a
+// different creative while the popup was open, the reload would auto-open the
+// wrong creative's link modal and the user could link the project to it.
+// Tolerates a missing or throwing storage (private-mode Safari, packaged
+// WKWebView) — the reopen is a convenience and must never throw inside the
+// postMessage handler.
+export function markReopenAfterConnect(storage, creativeId) {
+  const value =
+    creativeId != null && String(creativeId) !== '' ? String(creativeId) : UNSCOPED;
+  try {
+    if (storage) storage.setItem(LINEAR_REOPEN_KEY, value);
+  } catch (e) {
+    /* storage unavailable — skip the reopen nicety */
+  }
+}
+
+// Consume the reopen intent: returns true at most once, then clears the flag so
+// a later unrelated reload (e.g. after linking succeeds) does not reopen it. The
+// flag is cleared on the first consume regardless of match, so a stale intent
+// (opener navigated elsewhere) never lingers to reopen the modal on some later
+// visit. Returns true only when the stored creative id matches the current page
+// (or when the legacy unscoped sentinel was stored).
+export function consumeReopenAfterConnect(storage, currentCreativeId) {
+  try {
+    if (!storage) return false;
+    const stored = storage.getItem(LINEAR_REOPEN_KEY);
+    if (!stored) return false;
+    storage.removeItem(LINEAR_REOPEN_KEY); // one-shot regardless of match
+    if (stored === UNSCOPED) return true;
+    return String(currentCreativeId == null ? '' : currentCreativeId) === stored;
+  } catch (e) {
+    /* storage unavailable — treat as no pending reopen */
+  }
+  return false;
+}

data/app/jobs/collavre_linear/inbound_apply_job.rb

@@ -22,6 +22,26 @@ module CollavreLinear
     # sequential FIFO queue that preserves enqueue (receipt) order.
     queue_as :linear_inbound
 
+    # Auto-recover from transient DB contention. WebhooksController acks Linear
+    # with 200 the instant it enqueues this job (ack-before-apply), so Linear
+    # never re-delivers a payload once accepted. Without a retry, a transient
+    # ActiveRecord::Deadlocked / LockWaitTimeout — which InboundApplier CAN hit,
+    # since it takes `with_lock`/`lock!` on the same Creative the OUTBOUND worker
+    # locks (see inbound_applier.rb's lock-order note) — would park the event as
+    # a failed execution and the local mirror would silently diverge from Linear
+    # with no resend to fix it. Retrying is safe: a deadlock/lock-timeout rolls
+    # the whole transaction back (no partial apply), and InboundApplier is
+    # idempotent (create no-ops on an existing link, unique indexes guard
+    # duplicates, disposition checks refuse to clobber newer local edits), so a
+    # re-run cannot double-apply. Scope is deliberately narrow — only transient
+    # contention retries; a real bug still raises and parks (loud, operator-
+    # visible) rather than looping. The wait is kept SHORT (much shorter than the
+    # outbound jobs' polynomially_longer) so a rescheduled retry disturbs this
+    # FIFO queue's receipt order as little as possible; the applier's own
+    # out-of-order tolerance covers the small residual reordering.
+    retry_on ActiveRecord::Deadlocked, ActiveRecord::LockWaitTimeout,
+             wait: 2.seconds, attempts: 5
+
     def perform(payload)
       unless CollavreLinear.const_defined?(:InboundApplier)
         Rails.logger.info(

data/app/observers/collavre_linear/creative_sync_observer.rb

@@ -67,8 +67,12 @@ module CollavreLinear
 
     # Columns whose change can alter the exported Linear issue (mirrors what
     # CreativeExporter hashes: description -> title/description, sequence ->
-    # priority, data -> state/labels) plus parent_id (re-parenting -> parentId).
-    LINEAR_RELEVANT_COLUMNS = %w[description sequence data parent_id].freeze
+    # priority, data -> state/labels) plus parent_id (re-parenting -> parentId)
+    # and progress (a leaf reaching 100% -> the project's "done" state, via
+    # CreativeExporter.apply_completion!). A non-leaf's rolled-up progress change
+    # enqueues a sync too, but apply_completion! no-ops for non-leaves so the
+    # content_hash is unchanged and the exporter makes no API call.
+    LINEAR_RELEVANT_COLUMNS = %w[description sequence data parent_id progress].freeze
 
     # Record — in after_save, where saved_changes is reliable — whether this
     # save touched a Linear-relevant column. A create always counts (its seeded

data/app/services/collavre_linear/client.rb

@@ -191,11 +191,59 @@ module CollavreLinear
       }
     GQL
 
+    # List workflow states with their owning team id and type so the link modal
+    # can offer a "done state" combobox scoped to the chosen team. `type` is
+    # Linear's state category (triage/backlog/unstarted/started/completed/
+    # canceled) — the picker defaults to the team's "completed" state.
+    WORKFLOW_STATES = <<~GQL.freeze
+      query WorkflowStates {
+        workflowStates(first: 250) {
+          nodes {
+            id
+            name
+            type
+            position
+            team {
+              id
+            }
+          }
+        }
+      }
+    GQL
+
+    # Fetch a single issue's current workflow state (for seeding the pre-done
+    # snapshot when a leaf is completed with no locally-known Linear state).
+    ISSUE_QUERY = <<~GQL.freeze
+      query Issue($id: String!) {
+        issue(id: $id) {
+          id
+          state {
+            id
+            name
+            type
+          }
+        }
+      }
+    GQL
+
     def initialize(account)
       @account = account
       @endpoint = resolve_endpoint
     end
 
+    # Fetch a single Linear issue's current workflow state.
+    # @param id [String] Linear issue UUID
+    # @return [Hash, nil] {"id" =>, "name" =>, "type" =>} (string keys, matching
+    #   the shape stored under data["linear"]["state"]), or nil when the issue or
+    #   its state is absent.
+    def fetch_issue_state(id)
+      data  = post!(ISSUE_QUERY, { id: id })
+      state = data.dig("issue", "state")
+      return nil if state.nil?
+
+      state.slice("id", "name", "type")
+    end
+
     # Create a Linear issue.
     # @return [Hash] with :id and :identifier
     def create_issue(team_id:, title:, description: nil, parent_id: nil,
@@ -315,6 +363,24 @@ module CollavreLinear
       end
     end
 
+    # List workflow states for the "done state" picker, each with its owning
+    # team id and category type so the UI can scope states to the selected team
+    # and default to the completed one.
+    # @return [Array<Hash>] each with :id, :name, :type, :position, :team_id
+    def list_workflow_states
+      data  = post!(WORKFLOW_STATES, {})
+      nodes = data.dig("workflowStates", "nodes") || []
+      nodes.map do |n|
+        {
+          id:       n["id"],
+          name:     n["name"],
+          type:     n["type"],
+          position: n["position"],
+          team_id:  n.dig("team", "id")
+        }
+      end
+    end
+
     # Register a webhook with Linear.
     # WebhookCreateInput fields: url, secret, teamId, resourceTypes
     # @return [Hash] with :id
@@ -332,22 +398,19 @@ module CollavreLinear
     # Execute a GraphQL operation and return the `data` hash.
     # Raises Client::Error if the response contains a top-level `errors` key.
     def post!(query, variables)
-      uri  = URI.parse(endpoint)
-      http = Net::HTTP.new(uri.host, uri.port)
-      http.use_ssl = uri.scheme == "https"
-      http.open_timeout = 10
-      http.read_timeout = 30
-
-      request = Net::HTTP::Post.new(uri.path.presence || "/")
-      request["Content-Type"] = "application/json"
-      request["Authorization"] = "Bearer #{fresh_access_token}"
-      request.body = { query: query, variables: variables }.to_json
+      token = fresh_access_token
 
       response =
         begin
-          http.request(request)
-        rescue SocketError, SystemCallError, Timeout::Error, IOError,
-               OpenSSL::SSL::SSLError => e
+          http_client.post(
+            endpoint,
+            body: { query: query, variables: variables }.to_json,
+            headers: {
+              "Content-Type" => "application/json",
+              "Authorization" => "Bearer #{token}"
+            }
+          )
+        rescue Collavre::HttpClient::ConnectionError => e
           # Transport-layer failures (connection refused/reset, DNS, TLS,
           # open/read timeouts) raise before any GraphQL response exists, so they
           # bypass the parsed-`errors` path below. Wrap them in Error so the
@@ -360,7 +423,7 @@ module CollavreLinear
       parsed = begin
         JSON.parse(response.body)
       rescue JSON::ParserError
-        raise Error, "Linear returned non-JSON response (HTTP #{response.code}): #{response.body.to_s[0, 200]}"
+        raise Error, "Linear returned non-JSON response (HTTP #{response.code}) from #{endpoint}: #{response.body.to_s[0, 200]}"
       end
 
       if parsed["errors"].present?
@@ -368,13 +431,19 @@ module CollavreLinear
         raise Error, "Linear GraphQL error(s): #{messages}"
       end
 
-      unless response.is_a?(Net::HTTPSuccess)
+      unless response.success?
         raise Error, "Linear HTTP error: #{response.code} #{response.message}"
       end
 
       parsed["data"]
     end
 
+    # Shared Net::HTTP wrapper preserving Linear's original 10s connect / 30s
+    # read timeouts.
+    def http_client
+      @http_client ||= Collavre::HttpClient.new(open_timeout: 10, read_timeout: 30)
+    end
+
     # Return a non-expired access token, refreshing via the refresh_token grant
     # when the current token is expiring soon.
     #
@@ -401,9 +470,32 @@ module CollavreLinear
     end
 
     def resolve_endpoint
-      if defined?(Collavre::IntegrationSettings::Resolver)
-        Collavre::IntegrationSettings::Resolver.get(:linear_api_endpoint).presence
-      end || DEFAULT_ENDPOINT
+      configured =
+        if defined?(Collavre::IntegrationSettings::Resolver)
+          Collavre::IntegrationSettings::Resolver.get(:linear_api_endpoint).presence
+        end
+
+      normalize_endpoint(configured) || DEFAULT_ENDPOINT
+    end
+
+    # Guard a misconfigured `linear_api_endpoint` override. Linear's GraphQL API
+    # lives at the `/graphql` path; an admin who pastes only a base URL
+    # (e.g. `https://host:port` or `.../`) would otherwise POST to `/`, which a
+    # non-Linear server answers with a 404 ("Cannot POST /"). When the configured
+    # value carries no meaningful path, point it at `/graphql`. A value that
+    # already specifies a non-root path is left untouched.
+    def normalize_endpoint(value)
+      return nil if value.blank?
+
+      uri = URI.parse(value.strip)
+      return value if uri.path.present? && uri.path != "/"
+
+      uri.path = "/graphql"
+      uri.to_s
+    rescue URI::InvalidURIError
+      # Not a parseable URI: return as-is and let the request surface the failure
+      # rather than silently rewriting an unrecognizable value.
+      value
     end
 
     # Convert symbol keys to camelCase strings for GraphQL variables.

data/app/services/collavre_linear/creative_exporter.rb

@@ -52,9 +52,70 @@ module CollavreLinear
           data:        creative.data
         )
       )
+      # Fold the completion→state override into the hash so inbound and outbound
+      # agree: after an inbound apply advances content_hash via this method, a
+      # later outbound sync of a completed leaf must see the SAME state_id it
+      # would push. Resolve the governing ProjectLink the same way sync! does.
+      apply_completion!(attrs, creative, resolve_project_link_for(creative))
       hash_attrs(attrs, parent_linear_issue_id_for(creative))
     end
 
+    # Walk self-and-ancestors (nearest first) for the governing ProjectLink.
+    # Class-level twin of the instance #resolve_project_link so content_hash_for
+    # can apply the same completion override.
+    def self.resolve_project_link_for(creative)
+      creative.self_and_ancestors.each do |ancestor|
+        link = CollavreLinear::ProjectLink.find_by(creative_id: ancestor.id)
+        return link if link
+      end
+      nil
+    end
+
+    # Completion mapping (Collavre → Linear): a LEAF creative at 100% progress
+    # exports with its project's configured "done" workflow state. Mutates and
+    # returns `attrs`.
+    #
+    # Guards, each a deliberate no-op:
+    #   * no project_link / no done_state_id — completion mapping not configured.
+    #   * creative has active children       — only leaves carry independent
+    #     progress (a parent's progress is a rollup average), so only leaves drive
+    #     the done state; a parent issue's state follows from its children.
+    #   * progress < 1.0                     — only 100% maps to done. We do NOT
+    #     blindly clobber the state here; instead, when our record shows the issue
+    #     still sitting in the done state, we RESTORE the state it held before it
+    #     was completed (the "un-done" case — see below). Otherwise the last-known
+    #     Linear state (from data["linear"]) echoes through unchanged.
+    #
+    # Un-done (Collavre 100% → below): the pre-done state is snapshotted into
+    # data["linear"]["state_before_done"] by #capture_state_before_done! at the
+    # moment the leaf is pushed to done. On a later drop below 100% we push that
+    # snapshot back — but only while data["linear"]["state"] still equals the done
+    # state (i.e. our push landed and nobody has since moved the issue). That
+    # done-state guard keeps us from fighting a human who moved the issue
+    # elsewhere in Linear, and bounds the loop: once the restore echoes back,
+    # data["linear"]["state"] is no longer done so this never re-fires.
+    #
+    # This method stays PURE (no I/O, no mutation) so CreativeExporter.content_hash_for
+    # and #sync! compute the SAME state_id — the capture that needs the network is
+    # done separately in the sync! path.
+    def self.apply_completion!(attrs, creative, project_link)
+      done_state_id = project_link&.done_state_id
+      return attrs if done_state_id.blank?
+      return attrs unless creative.children.active.empty?
+
+      if creative.progress.to_f >= 1.0
+        attrs[:state_id] = done_state_id
+      else
+        linear  = (creative.data || {})["linear"] || {}
+        before  = linear["state_before_done"]
+        current = linear["state"]
+        if before.present? && current.is_a?(Hash) && current["id"] == done_state_id
+          attrs[:state_id] = before["id"]
+        end
+      end
+      attrs
+    end
+
     # Resolve the parent Creative's linked linear_issue_id (or nil when the
     # parent is absent or not itself linked to a Linear issue).
     def self.parent_linear_issue_id_for(creative)
@@ -84,14 +145,23 @@ module CollavreLinear
       # (Its children export as the project's top-level issues; see class docs.)
       return if project_link.creative_id == @creative.id
 
-      account   = project_link.account
-      client    = Client.new(account)
+      account    = project_link.account
+      client     = Client.new(account)
+      issue_link = @creative.linear_issue_links.first
+
+      # Before a completed leaf's state is overridden to "done", remember the state
+      # it is leaving so a later drop below 100% can restore it (outbound un-done).
+      # This may query Linear once, so it lives here in the I/O path — NOT in the
+      # pure apply_completion!/content_hash_for.
+      capture_state_before_done!(client, project_link, issue_link)
+
       attrs     = FieldMapper.creative_to_issue_attrs(adapt(@creative))
+      # Completed leaf → push the project's "done" state; a leaf dropped below 100%
+      # → restore its pre-done state (mirrors content_hash_for).
+      self.class.apply_completion!(attrs, @creative, project_link)
       parent_id = parent_linear_issue_id
       hash      = compute_content_hash(attrs, parent_id)
 
-      issue_link = @creative.linear_issue_links.first
-
       # Cross-project move: the creative was reparented under a DIFFERENT linked
       # root than the one its existing issue belongs to. resolve_project_link now
       # returns the new project, so updating would push the OLD project's issue
@@ -125,6 +195,57 @@ module CollavreLinear
 
     private
 
+    # Snapshot the pre-done Linear workflow state onto
+    # data["linear"]["state_before_done"] so a later drop below 100% can restore
+    # the issue to it (see apply_completion!'s un-done branch).
+    #
+    # Acts only for a completed leaf (progress >= 1.0) whose project has a done
+    # state configured. Sources the snapshot from the last-known non-done state in
+    # data["linear"]["state"]; when none is known (e.g. the leaf reached 100%
+    # purely in Collavre before any inbound state sync), queries Linear ONCE to
+    # seed it — but only if no snapshot exists yet, so this never re-queries.
+    #
+    # No-op for: the create path (no Linear issue yet to query), non-leaves,
+    # completion mapping off, an already-done known state, and when the snapshot
+    # is unchanged. Persists via update_column to avoid the sync observer (this is
+    # bookkeeping, not a mapped-field change) and never touches state_id itself.
+    def capture_state_before_done!(client, project_link, issue_link)
+      done_state_id = project_link.done_state_id
+      return if done_state_id.blank?
+      return unless @creative.progress.to_f >= 1.0
+      return unless @creative.children.active.empty?
+
+      linear  = (@creative.data || {})["linear"] || {}
+      current = linear["state"]
+
+      candidate =
+        if current.is_a?(Hash) && current["id"].present? && current["id"] != done_state_id
+          current
+        elsif linear["state_before_done"].blank? && issue_link&.linear_issue_id.present?
+          fetched = client.fetch_issue_state(issue_link.linear_issue_id)
+          fetched if fetched.present? && fetched["id"] != done_state_id
+        end
+
+      return if candidate.blank?
+      return if candidate == linear["state_before_done"]
+
+      new_data = (@creative.data || {}).deep_dup
+      new_data["linear"] ||= {}
+      new_data["linear"]["state_before_done"] = candidate
+      # Record our OWN outbound completion into the local state mirror: we are
+      # about to push this issue to the done state, but Linear's echo of that push
+      # is EchoGuard-suppressed and never arrives, and nothing else writes
+      # data["linear"]["state"] outbound. Without this, apply_completion!'s un-done
+      # guard (data["linear"]["state"] == done) can NEVER be satisfied on a
+      # Collavre-driven completion, so a later drop below 100% would push no state
+      # and leave the issue stuck in done. This is the truth — the issue IS now in
+      # done because we put it there — and a genuine human move in Linear still
+      # overwrites it via the inbound applier, correctly halting the restore.
+      new_data["linear"]["state"] = { "id" => done_state_id }
+      @creative.data = new_data
+      @creative.update_column(:data, new_data)
+    end
+
     # True when this creative's parent is itself part of the exported subtree
     # (it resolves the governing ProjectLink) but has not yet been exported to
     # Linear (no linear_issue_id). The parent MUST land first so this child can

data/app/services/collavre_linear/inbound_applier.rb

@@ -97,6 +97,10 @@ module CollavreLinear
         creative.skip_linear_sync = true
         merge_linear_data!(creative, attrs[:data_linear])
         creative.sequence = attrs[:sequence]
+        # Completion mapping (Linear → Collavre): a freshly-imported issue that is
+        # already in the project's "done" state marks the (new, always-leaf)
+        # creative 100%.
+        reconcile_leaf_progress!(creative, project_link)
         creative.save!
 
         IssueLink.create!(
@@ -208,6 +212,17 @@ module CollavreLinear
         end
         merge_linear_data!(creative, attrs[:data_linear])
 
+        # Completion mapping (Linear → Collavre): only reconcile when the state
+        # field is actually part of this update (or updatedFrom is absent). A
+        # title-only edit must not touch the leaf's progress.
+        # Linear keys the state change in updatedFrom by its scalar FK column
+        # `stateId` (mirrors `parentId`/`projectId`/`priority` elsewhere), NOT a
+        # nested `state` object — matching "state" here never fired on real
+        # webhooks, silently disabling done→100% on the normal update path.
+        if changed.nil? || changed.include?("stateId")
+          reconcile_leaf_progress!(creative, link.project_link)
+        end
+
         # Reparent: when the payload's Linear parent differs from what the link
         # last recorded, move the Creative under the corresponding linked parent
         # and track the new parent_issue_id. Without this the tree stays under the
@@ -548,6 +563,37 @@ module CollavreLinear
       attrs[:title].presence || ""
     end
 
+    # Completion mapping (Linear → Collavre). Reflect whether the inbound issue
+    # is in the project's configured "done" workflow state onto the LEAF
+    # creative's progress. Sets progress in memory; the caller's save! persists
+    # it under skip_linear_sync (no echo back to Linear).
+    #
+    # Guards (deliberate no-ops):
+    #   * done_state_id blank         — completion mapping not configured.
+    #   * origin-linked creative      — its progress delegates to the origin and
+    #     a direct write is validation-forbidden; leave it alone.
+    #   * creative has active children — only leaves carry independent progress
+    #     (a parent's is a rollup average driven by its children).
+    #
+    # Transitions:
+    #   * state == done_state_id            → progress 1.0 (100%).
+    #   * state != done_state_id AND was 1.0 → progress 0.0 (un-complete). A
+    #     sub-100% local progress is PRESERVED — the done<->100% mapping is
+    #     binary, so a non-done state must not clobber partial Collavre progress.
+    def reconcile_leaf_progress!(creative, project_link)
+      done_state_id = project_link&.done_state_id
+      return if done_state_id.blank?
+      return if creative.respond_to?(:origin_id) && creative.origin_id.present?
+      return unless creative.children.active.empty?
+
+      state_id = @data.dig("state", "id")
+      if state_id.present? && state_id == done_state_id
+        creative.progress = 1.0 if creative.progress.to_f < 1.0
+      elsif creative.progress.to_f >= 1.0
+        creative.progress = 0.0
+      end
+    end
+
     def merge_linear_data!(creative, data_linear)
       return if data_linear.blank?
 

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

@@ -50,13 +50,33 @@
   </div>
 
   <script>
-    document.getElementById('close-btn').addEventListener('click', function() {
+    // Tell the opener the account is connected so it advances straight to the
+    // project-link step. The opener also closes this popup (window.close() below
+    // is unreliable after the cross-origin OAuth round trip and in the desktop
+    // WebView, which is why the "Close" button used to look dead).
+    function notifyOpener() {
       try {
-        if (window.opener) {
-          window.opener.postMessage({ type: 'linearConnected' }, window.location.origin);
+        if (window.opener && !window.opener.closed) {
+          // Include the creative this popup was opened for so the opener only
+          // reopens the modal when it's still showing that same creative — not
+          // whatever creative it may have navigated to while the popup was open.
+          var wizard = document.getElementById('linear-wizard');
+          var creativeId = wizard ? wizard.dataset.creativeId : '';
+          window.opener.postMessage(
+            { type: 'linearConnected', creativeId: creativeId },
+            window.location.origin
+          );
         }
       } catch (e) {}
-      window.close();
+    }
+
+    // Auto-advance on load: no click required — the opener reloads and jumps to
+    // the project settings ("link a project") step.
+    notifyOpener();
+
+    document.getElementById('close-btn').addEventListener('click', function() {
+      notifyOpener();
+      try { window.close(); } catch (e) {}
     });
   </script>
 </body>

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

@@ -159,6 +159,23 @@
                          style: "width:100%;padding:0.4em 0.6em;border:1px solid var(--color-border);border-radius:4px;" %>
           </div>
 
+          <%# Done-state combobox: which Linear workflow state marks an issue as
+              "완료". JS scopes the options to the chosen team and defaults to that
+              team's Completed state. Optional — a team with no completed state
+              leaves it blank and completion mapping stays off. %>
+          <div style="margin-bottom:1em;">
+            <%= f.label :done_state_id, t("collavre_linear.integration.done_state_label"),
+                        style: "display:block;margin-bottom:0.25em;font-weight:600;" %>
+            <%= f.select :done_state_id,
+                         [],
+                         { include_blank: t("collavre_linear.integration.done_state_placeholder") },
+                         disabled: true,
+                         style: "width:100%;padding:0.4em 0.6em;border:1px solid var(--color-border);border-radius:4px;" %>
+            <p style="margin:0.25em 0 0;color:var(--text-muted);font-size:0.85em;">
+              <%= t("collavre_linear.integration.done_state_help") %>
+            </p>
+          </div>
+
           <%= f.submit t("collavre_linear.integration.link_button"),
                        class: "btn btn-primary", disabled: true %>
         <% end %>

data/config/locales/en.yml

@@ -17,6 +17,9 @@ en:
       project_id_label: "Project"
       project_select_placeholder: "Select a project…"
       team_select_placeholder: "Select a team…"
+      done_state_label: "Done state"
+      done_state_placeholder: "Select a done state…"
+      done_state_help: "When a Linear issue reaches this state its matching leaf creative is marked 100% — and a leaf creative reaching 100% moves its Linear issue to this state."
       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."

data/config/locales/ko.yml

@@ -17,6 +17,9 @@ ko:
       project_id_label: "프로젝트"
       project_select_placeholder: "프로젝트 선택…"
       team_select_placeholder: "팀 선택…"
+      done_state_label: "완료 상태"
+      done_state_placeholder: "완료 상태 선택…"
+      done_state_help: "Linear 이슈가 이 상태가 되면 대응되는 leaf 크리에이티브가 100%로 처리되고, 반대로 leaf 크리에이티브가 100%가 되면 Linear 이슈가 이 상태로 이동합니다."
       options_loading: "프로젝트와 팀을 불러오는 중…"
       options_failed: "Linear 프로젝트와 팀을 불러오지 못했습니다. 다시 시도해 주세요."
       no_projects: "Linear 워크스페이스에 프로젝트가 없습니다."

data/db/migrate/20260704000000_add_done_state_id_to_linear_project_links.rb

@@ -0,0 +1,9 @@
+class AddDoneStateIdToLinearProjectLinks < ActiveRecord::Migration[8.0]
+  # The Linear workflow-state UUID that represents "done" for this linked
+  # project. Chosen by the admin (combobox, default "Completed") at link time.
+  # Nullable: links created before this feature — or teams with no completed
+  # state — simply have no completion mapping (the sync no-ops both ways).
+  def change
+    add_column :linear_project_links, :done_state_id, :string
+  end
+end

data/lib/collavre_linear/version.rb

@@ -1,3 +1,3 @@
 module CollavreLinear
-  VERSION = "0.1.0"
+  VERSION = "0.2.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: collavre_linear
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Collavre
@@ -49,7 +49,9 @@ files:
 - app/controllers/collavre_linear/auth_controller.rb
 - app/controllers/collavre_linear/creatives/integrations_controller.rb
 - app/controllers/collavre_linear/webhooks_controller.rb
+- app/javascript/__tests__/linear_modal_reopen.test.js
 - app/javascript/collavre_linear.js
+- app/javascript/linear_modal_reopen.js
 - app/jobs/collavre_linear/inbound_apply_job.rb
 - app/jobs/collavre_linear/outbound_archive_job.rb
 - app/jobs/collavre_linear/outbound_comment_delete_job.rb
@@ -86,6 +88,7 @@ files:
 - db/migrate/20260701000006_add_lookup_indexes_to_linear_project_links.rb
 - db/migrate/20260701000007_enforce_one_project_link_per_creative.rb
 - db/migrate/20260701000008_allow_null_webhook_secret_on_linear_project_links.rb
+- db/migrate/20260704000000_add_done_state_id_to_linear_project_links.rb
 - lib/collavre_linear.rb
 - lib/collavre_linear/engine.rb
 - lib/collavre_linear/version.rb