@symbiosis-lab/moss-plugin-matters 1.4.2

package/src/__tests__/auto-detect.test.ts

@@ -0,0 +1,412 @@
+/**
+ * Task 2.3 — auto-detect tests for waitForPublishOrClose.
+ *
+ * These tests verify that a `browser-url-changed` event to a published-looking
+ * URL triggers an immediate fetchDraft verify. The URL-triggered path resolves
+ * the wait (poll is the fallback) — with `sleep` mocked, both paths are instant.
+ *
+ * Also verifies the negative case: a URL that doesn't look like a published
+ * article (or an article URL the API does NOT confirm) must NOT resolve.
+ */
+// @vitest-environment node
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+// ── Mocks ────────────────────────────────────────────────────────────────────
+
+// Capture the listener registered by onEvent so tests can invoke it directly
+let capturedUrlListener: ((payload: { url: string }) => void) | null = null;
+
+// The mock returns an unlisten function (vi.fn). We capture the registered
+// callback so emitBrowserUrlChanged can invoke it in tests.
+const mockUnlistenUrl = vi.fn();
+
+const mockOnEvent = vi.fn().mockImplementation(
+  (eventName: string, cb: (payload: { url: string }) => void) => {
+    if (eventName === "browser-url-changed") {
+      capturedUrlListener = cb;
+    }
+    return Promise.resolve(mockUnlistenUrl);
+  }
+);
+
+vi.mock("@symbiosis-lab/moss-api", () => ({
+  getPluginCookie: vi.fn(),
+  httpPost: vi.fn(),
+  httpGet: vi.fn(),
+  fetchUrl: vi.fn(),
+  downloadAsset: vi.fn(),
+  readFile: vi.fn(),
+  writeFile: vi.fn(),
+  listFiles: vi.fn().mockResolvedValue([]),
+  showToast: vi.fn().mockResolvedValue(undefined),
+  dismissToast: vi.fn().mockResolvedValue(undefined),
+  // Never-resolving browser handle by default (poll-driven path)
+  openBrowser: vi.fn().mockResolvedValue({ closed: new Promise<void>(() => {}) }),
+  closeBrowser: vi.fn().mockResolvedValue(undefined),
+  readPluginFile: vi.fn().mockResolvedValue("{}"),
+  writePluginFile: vi.fn().mockResolvedValue(undefined),
+  pluginFileExists: vi.fn().mockResolvedValue(false),
+  getPluginEnvVar: vi.fn().mockResolvedValue(undefined),
+  startTask: vi.fn().mockResolvedValue({
+    id: "42",
+    progress: vi.fn().mockResolvedValue(undefined),
+    awaiting: vi.fn().mockResolvedValue(undefined),
+    advise: vi.fn().mockResolvedValue(undefined),
+    succeeded: vi.fn().mockResolvedValue(undefined),
+    failed: vi.fn().mockResolvedValue(undefined),
+    cancelled: vi.fn().mockResolvedValue(undefined),
+  }),
+  setMessageContext: vi.fn(),
+  sendMessage: vi.fn().mockResolvedValue(undefined),
+  reportProgress: vi.fn().mockResolvedValue(undefined),
+  reportError: vi.fn().mockResolvedValue(undefined),
+  reportComplete: vi.fn().mockResolvedValue(undefined),
+  emitEvent: vi.fn().mockResolvedValue(undefined),
+  // R7: onEvent mock that captures the callback for emitBrowserUrlChanged
+  onEvent: (...args: unknown[]) => mockOnEvent(...args),
+}));
+
+vi.mock("../config", () => ({
+  getConfig: vi.fn().mockResolvedValue({ userName: "guo" }),
+  saveConfig: vi.fn().mockResolvedValue(undefined),
+}));
+
+vi.mock("../credential", () => ({
+  clearTokenCache: vi.fn(),
+  loadStoredToken: vi.fn().mockResolvedValue(null),
+  saveStoredToken: vi.fn().mockResolvedValue(undefined),
+  clearStoredToken: vi.fn().mockResolvedValue(undefined),
+  getSessionState: vi.fn().mockResolvedValue("valid"),
+  shouldNudgeSessionExpired: vi.fn().mockResolvedValue(false),
+  markSessionInvalidated: vi.fn().mockResolvedValue(undefined),
+  authHeaderToken: vi.fn().mockResolvedValue("tok"),
+  captureLogin: vi.fn().mockResolvedValue("tok"),
+  prepareWebviewAuth: vi.fn().mockResolvedValue(undefined),
+  beginFreshLogin: vi.fn().mockResolvedValue(undefined),
+}));
+
+vi.mock("../api", () => ({
+  createDraft: vi.fn().mockResolvedValue({
+    id: "d1",
+    title: "Post",
+    content: "",
+    createdAt: "2026-01-01T00:00:00Z",
+    publishState: "unpublished",
+    article: null,
+  }),
+  fetchDraft: vi.fn().mockResolvedValue({
+    id: "d1",
+    title: "Post",
+    content: "",
+    createdAt: "2026-01-01T00:00:00Z",
+    publishState: "published",
+    article: { id: "a1", shortHash: "a1b2c3", slug: "post" },
+  }),
+  uploadCoverByUrl: vi.fn().mockResolvedValue("asset-1"),
+  uploadEmbedByUrl: vi.fn().mockResolvedValue("https://cdn/img.jpg"),
+  fetchUserProfile: vi.fn().mockResolvedValue({ userName: "guo", displayName: "Guo" }),
+  fetchAllArticlesSince: vi.fn().mockResolvedValue({ articles: [], userName: "guo" }),
+  fetchAllDraftsSince: vi.fn().mockResolvedValue([]),
+  fetchAllCollections: vi.fn().mockResolvedValue([]),
+  fetchArticleComments: vi.fn().mockResolvedValue({ comments: [], donations: [], appreciations: [] }),
+  fetchAllArticleCommentCounts: vi.fn().mockResolvedValue([]),
+  MattersAuthError: class MattersAuthError extends Error {},
+  apiConfig: { queryMode: "viewer", testUserName: "Matty", endpoint: "https://server.matters.town/graphql" },
+}));
+
+vi.mock("../domain", () => ({
+  initializeDomain: vi.fn().mockResolvedValue(undefined),
+  loginUrl: vi.fn().mockReturnValue("https://matters.town/login"),
+  draftUrl: vi.fn().mockImplementation((id: string) => `https://matters.town/drafts/${id}`),
+  articleUrl: vi.fn().mockImplementation((_u: string, slug: string, hash: string) => `https://matters.town/@guo/${slug}-${hash}`),
+  isMattersUrl: vi.fn().mockImplementation((url: string) => url.includes("matters.town")),
+}));
+
+vi.mock("../sync", () => ({
+  detectBoundUser: vi.fn().mockResolvedValue({ userName: "guo" }),
+  syncToLocalFiles: vi.fn().mockResolvedValue({ result: { created: 0, updated: 0, skipped: 0, errors: [] }, articlePathMap: new Map() }),
+  scanLocalArticles: vi.fn().mockResolvedValue([]),
+}));
+
+vi.mock("../utils", () => ({
+  reportError: vi.fn().mockResolvedValue(undefined),
+  setCurrentHookName: vi.fn(),
+  sleep: vi.fn().mockResolvedValue(undefined),
+}));
+
+vi.mock("../converter", () => ({
+  parseFrontmatter: vi.fn().mockReturnValue(null),
+  regenerateFrontmatter: vi.fn().mockReturnValue(""),
+}));
+
+vi.mock("../progress", () => ({
+  overallProgress: vi.fn().mockReturnValue(50),
+}));
+
+vi.mock("../social", () => ({
+  loadSocialData: vi.fn().mockResolvedValue({ articles: {} }),
+  saveSocialData: vi.fn().mockResolvedValue(undefined),
+  mergeSocialData: vi.fn().mockReturnValue({ articles: {} }),
+  reconcileLegacySocialData: vi.fn().mockResolvedValue(undefined),
+}));
+
+vi.mock("../downloader", () => ({
+  downloadMediaAndUpdate: vi.fn().mockResolvedValue(undefined),
+  rewriteAllInternalLinks: vi.fn().mockResolvedValue({ linksRewritten: 0 }),
+}));
+
+vi.mock("../auth-route", () => ({
+  resolveAuthRoute: vi.fn().mockResolvedValue({ kind: "skip" }),
+  isUserPresent: vi.fn().mockResolvedValue(true),
+}));
+
+// ── Test helper ───────────────────────────────────────────────────────────────
+
+/**
+ * Simulates a browser-url-changed event reaching the plugin listener.
+ * Invokes the captured callback and flushes microtasks so the async
+ * fetchDraft inside the listener has time to resolve.
+ */
+async function emitBrowserUrlChanged(url: string): Promise<void> {
+  if (!capturedUrlListener) {
+    throw new Error("No URL listener registered — is waitForPublishOrClose wired up?");
+  }
+  capturedUrlListener({ url });
+  // Flush pending microtasks (the fetchDraft await inside the listener)
+  await Promise.resolve();
+  await Promise.resolve();
+  await Promise.resolve();
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+import { waitForPublishOrClose } from "../main";
+import { fetchDraft } from "../api";
+import { emitEvent, closeBrowser } from "@symbiosis-lab/moss-api";
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  capturedUrlListener = null;
+  // Restore default onEvent implementation after clearAllMocks wipes it
+  mockOnEvent.mockImplementation(
+    (eventName: string, cb: (payload: { url: string }) => void) => {
+      if (eventName === "browser-url-changed") {
+        capturedUrlListener = cb;
+      }
+      return Promise.resolve(mockUnlistenUrl);
+    }
+  );
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe("waitForPublishOrClose — URL auto-detect (Task 2.3)", () => {
+  it("resolves with published article when browser-url-changed fires a published URL and API confirms", async () => {
+    // API confirms the article was published
+    vi.mocked(fetchDraft).mockResolvedValue({
+      id: "d1",
+      title: "Post",
+      content: "",
+      createdAt: "2026-01-01T00:00:00Z",
+      publishState: "published",
+      article: { id: "a1", shortHash: "a1b2c3", slug: "post" },
+    } as never);
+
+    // Start waiting. The URL-triggered path resolves the wait; the poll is the
+    // fallback (both instant here because sleep is mocked).
+    const browserHandle = { closed: new Promise<void>(() => {}) };
+    const p = waitForPublishOrClose("d1", browserHandle);
+
+    // Give the function time to register the onEvent listener
+    await Promise.resolve();
+    await Promise.resolve();
+
+    // Trigger the URL change event with a valid published-article URL
+    await emitBrowserUrlChanged("https://matters.town/@guo/post-a1b2c3");
+
+    // URL-triggered path resolves the wait (poll is the fallback)
+    await expect(p).resolves.toEqual({ shortHash: "a1b2c3", slug: "post" });
+  });
+
+  it("does NOT resolve when browser-url-changed fires a non-article URL", async () => {
+    // API returns null (publish not confirmed)
+    vi.mocked(fetchDraft).mockResolvedValue({
+      id: "d1",
+      title: "Post",
+      content: "",
+      createdAt: "2026-01-01T00:00:00Z",
+      publishState: "unpublished",
+      article: null,
+    } as never);
+
+    // Browser closes immediately, so the close branch resolves the wait → null.
+    const browserHandle = { closed: Promise.resolve() };
+    const p = waitForPublishOrClose("d1", browserHandle);
+
+    await Promise.resolve();
+    await Promise.resolve();
+
+    // Fire a non-article URL — should not resolve the promise
+    await emitBrowserUrlChanged("https://matters.town/@guo/followers");
+
+    // Resolves null (browser closed, URL didn't trigger a publish)
+    await expect(p).resolves.toBeNull();
+  });
+
+  it("does NOT resolve when the API returns null even if the URL looks like a published article", async () => {
+    // The URL LOOKS like an article but the API does NOT confirm it
+    vi.mocked(fetchDraft).mockResolvedValue({
+      id: "d1",
+      title: "Post",
+      content: "",
+      createdAt: "2026-01-01T00:00:00Z",
+      publishState: "unpublished",
+      article: null,
+    } as never);
+
+    // Browser closes immediately so we get a null (not stuck waiting)
+    const browserHandle = { closed: Promise.resolve() };
+    const p = waitForPublishOrClose("d1", browserHandle);
+
+    await Promise.resolve();
+    await Promise.resolve();
+
+    // URL looks valid but API doesn't confirm → must NOT resolve as published
+    await emitBrowserUrlChanged("https://matters.town/@guo/some-other-post-a1b2c3");
+
+    await expect(p).resolves.toBeNull();
+  });
+
+  it("cleans up the URL listener (unlisten called) after resolution", async () => {
+    vi.mocked(fetchDraft).mockResolvedValue({
+      id: "d1",
+      title: "Post",
+      content: "",
+      createdAt: "2026-01-01T00:00:00Z",
+      publishState: "published",
+      article: { id: "a1", shortHash: "a1b2c3", slug: "post" },
+    } as never);
+
+    const browserHandle = { closed: new Promise<void>(() => {}) };
+    const p = waitForPublishOrClose("d1", browserHandle);
+
+    await Promise.resolve();
+    await Promise.resolve();
+    await emitBrowserUrlChanged("https://matters.town/@guo/post-a1b2c3");
+    await p;
+
+    // The unlisten function returned by onEvent must have been called
+    expect(mockUnlistenUrl).toHaveBeenCalled();
+  });
+
+  it("leaked-listener race: URL event fired after close-before-unlisten does NOT call fetchDraft again", async () => {
+    // Arrange: API confirms unpublished (so only the close branch can settle null)
+    vi.mocked(fetchDraft).mockResolvedValue({
+      id: "d1",
+      title: "Post",
+      content: "",
+      createdAt: "2026-01-01T00:00:00Z",
+      publishState: "unpublished",
+      article: null,
+    } as never);
+
+    // browserHandle.closed is already-resolved → settle(null) fires synchronously
+    // in the next microtask, before the onEvent .then() storing unlistenUrl runs.
+    const browserHandle = { closed: Promise.resolve() };
+    const p = waitForPublishOrClose("d1", browserHandle);
+
+    // Drain microtasks so settle(null) fires (browser close branch)
+    await Promise.resolve();
+    await Promise.resolve();
+    await Promise.resolve();
+
+    // Wait should already be resolved as null
+    await expect(p).resolves.toBeNull();
+
+    // Record how many times fetchDraft was called up to this point
+    const callsBefore = vi.mocked(fetchDraft).mock.calls.length;
+
+    // Now simulate the leaked listener firing (as if unlisten hadn't run yet)
+    // capturedUrlListener may or may not be set depending on microtask ordering;
+    // if it is set, the callback must short-circuit on `settled` and not call fetchDraft.
+    if (capturedUrlListener) {
+      capturedUrlListener({ url: "https://matters.town/@guo/post-a1b2c3" });
+      await Promise.resolve();
+      await Promise.resolve();
+      await Promise.resolve();
+    }
+
+    // fetchDraft must NOT have been called an additional time
+    expect(vi.mocked(fetchDraft).mock.calls.length).toBe(callsBefore);
+  });
+});
+
+// ── R19 — Held confirmation beat ──────────────────────────────────────────────
+
+describe("R19 — matters-room-published emitted before closeBrowser on confirmed publish", () => {
+  it("emits matters-room-published before calling closeBrowser on the confirmed-publish path", async () => {
+    // API confirms the article was published
+    vi.mocked(fetchDraft).mockResolvedValue({
+      id: "d1",
+      title: "Post",
+      content: "",
+      createdAt: "2026-01-01T00:00:00Z",
+      publishState: "published",
+      article: { id: "a1", shortHash: "a1b2c3", slug: "post" },
+    } as never);
+
+    // Track call order via an explicit ordering array
+    const callOrder: string[] = [];
+    vi.mocked(emitEvent).mockImplementation(async (name: string) => {
+      callOrder.push(`emit:${name}`);
+    });
+    vi.mocked(closeBrowser).mockImplementation(async () => {
+      callOrder.push("closeBrowser");
+    });
+
+    const browserHandle = { closed: new Promise<void>(() => {}) };
+    const p = waitForPublishOrClose("d1", browserHandle);
+
+    await Promise.resolve();
+    await Promise.resolve();
+
+    // Trigger the URL change — the settle(published) path fires
+    await emitBrowserUrlChanged("https://matters.town/@guo/post-a1b2c3");
+
+    // Wait for resolution (sleep is mocked to no-op so the 800ms is instant)
+    await p;
+
+    // matters-room-published MUST appear before closeBrowser in the call order
+    expect(callOrder).toContain("emit:matters-room-published");
+    expect(callOrder).toContain("closeBrowser");
+    const publishedIdx = callOrder.indexOf("emit:matters-room-published");
+    const closeIdx = callOrder.indexOf("closeBrowser");
+    expect(publishedIdx).toBeLessThan(closeIdx);
+  });
+
+  it("does NOT emit matters-room-published on the close (null) path", async () => {
+    // API never confirms → browser closes → settle(null)
+    vi.mocked(fetchDraft).mockResolvedValue({
+      id: "d1",
+      title: "Post",
+      content: "",
+      createdAt: "2026-01-01T00:00:00Z",
+      publishState: "unpublished",
+      article: null,
+    } as never);
+
+    const browserHandle = { closed: Promise.resolve() };
+    const p = waitForPublishOrClose("d1", browserHandle);
+
+    await Promise.resolve();
+    await Promise.resolve();
+    await Promise.resolve();
+    await p;
+
+    // matters-room-published must NOT be emitted on the skip/close path
+    const emittedNames = vi.mocked(emitEvent).mock.calls.map((c) => c[0]);
+    expect(emittedNames).not.toContain("matters-room-published");
+  });
+});

package/src/__tests__/binding-guard.test.ts

@@ -0,0 +1,256 @@
+/**
+ * Tests for the process hook binding guard.
+ *
+ * The binding guard prevents the Matters plugin from syncing articles
+ * into projects that haven't been explicitly connected to a Matters account.
+ */
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+// ============================================================================
+// Mocks
+// ============================================================================
+
+const mockGetConfig = vi.fn();
+const mockSaveConfig = vi.fn().mockResolvedValue(undefined);
+const mockDetectBoundUser = vi.fn();
+const mockGetAccessToken = vi.fn();
+const mockFetchUserProfile = vi.fn();
+const mockOpenBrowser = vi.fn();
+const mockCloseBrowser = vi.fn().mockResolvedValue(undefined);
+// vi.hoisted: the ../api factory passes this object through by VALUE
+// (`apiConfig: mockApiConfig`), which evaluates at factory time — a plain
+// top-level const would hit the vi.mock hoisting TDZ. Shared and MUTATED
+// across tests (public_fallback flips it), so beforeEach resets it.
+const mockApiConfig = vi.hoisted(() => ({
+  queryMode: "viewer",
+  testUserName: "Matty",
+  endpoint: "https://server.matters.town/graphql",
+}));
+
+vi.mock("@symbiosis-lab/moss-api", () => ({
+  getPluginCookie: vi.fn(),
+  httpPost: vi.fn(),
+  readFile: vi.fn(),
+  writeFile: vi.fn(),
+  listFiles: vi.fn().mockResolvedValue([]),
+  showToast: vi.fn().mockResolvedValue(undefined),
+  openBrowser: (...args: unknown[]) => mockOpenBrowser(...args),
+  closeBrowser: (...args: unknown[]) => mockCloseBrowser(...args),
+  returnToEditor: vi.fn().mockResolvedValue(undefined),
+  readPluginFile: vi.fn(),
+  writePluginFile: vi.fn().mockResolvedValue(undefined),
+  pluginFileExists: vi.fn(),
+  // T8a escape hatch — undefined return = no test profile = production
+  // path (which is what these binding-guard tests exercise).
+  getPluginEnvVar: vi.fn().mockResolvedValue(undefined),
+  // clearPluginCookies — called by promptLogin() before opening the browser.
+  clearPluginCookies: vi.fn().mockResolvedValue(undefined),
+  // startTask mock — returns a no-op TaskHandle so process hook can drive
+  // the PanelTask lifecycle without a real Tauri context.
+  startTask: vi.fn().mockResolvedValue({
+    id: "0",
+    progress: vi.fn().mockResolvedValue(undefined),
+    awaiting: vi.fn().mockResolvedValue(undefined),
+    succeeded: vi.fn().mockResolvedValue(undefined),
+    failed: vi.fn().mockResolvedValue(undefined),
+    cancelled: vi.fn().mockResolvedValue(undefined),
+  }),
+}));
+
+vi.mock("../config", () => ({
+  getConfig: (...args: unknown[]) => mockGetConfig(...args),
+  saveConfig: (...args: unknown[]) => mockSaveConfig(...args),
+}));
+
+vi.mock("../sync", () => ({
+  detectBoundUser: (...args: unknown[]) => mockDetectBoundUser(...args),
+  syncToLocalFiles: vi.fn().mockResolvedValue({ result: { created: 0, updated: 0, skipped: 0 }, articlePathMap: new Map() }),
+  scanLocalArticles: vi.fn().mockResolvedValue([]),
+}));
+
+vi.mock("../credential", () => ({
+  clearTokenCache: vi.fn(),
+  loadStoredToken: vi.fn().mockResolvedValue(null),
+  saveStoredToken: vi.fn().mockResolvedValue(undefined),
+  clearStoredToken: vi.fn().mockResolvedValue(undefined),
+  getSessionState: vi.fn().mockResolvedValue("none"),
+  shouldNudgeSessionExpired: vi.fn().mockResolvedValue(false),
+  markSessionInvalidated: vi.fn().mockResolvedValue(undefined),
+  authHeaderToken: vi.fn(),
+  captureLogin: (...args: unknown[]) => mockGetAccessToken(...args),
+  prepareWebviewAuth: vi.fn().mockResolvedValue(undefined),
+  beginFreshLogin: vi.fn().mockResolvedValue(undefined),
+}));
+
+vi.mock("../api", () => ({
+  fetchAllArticlesSince: vi.fn().mockResolvedValue({ articles: [], userName: "testuser" }),
+  fetchAllDraftsSince: vi.fn().mockResolvedValue([]),
+  fetchAllCollections: vi.fn().mockResolvedValue([]),
+  fetchUserProfile: (...args: unknown[]) => mockFetchUserProfile(...args),
+  fetchArticleComments: vi.fn().mockResolvedValue({ comments: [], donations: [], appreciations: [] }),
+  fetchAllArticleCommentCounts: vi.fn().mockResolvedValue(new Map()),
+  apiConfig: mockApiConfig,
+  MattersAuthError: class MattersAuthError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string) {
+      super(message);
+      this.name = "MattersAuthError";
+      this.code = code;
+    }
+  },
+}));
+
+vi.mock("../domain", () => ({
+  initializeDomain: vi.fn().mockResolvedValue("matters.town"),
+  getDomain: vi.fn().mockReturnValue("matters.town"),
+  loginUrl: vi.fn().mockReturnValue("https://matters.town/login"),
+  articleUrl: vi.fn(),
+  isMattersUrl: vi.fn(),
+}));
+
+vi.mock("../utils", () => ({
+  reportError: vi.fn().mockResolvedValue(undefined),
+  setCurrentHookName: vi.fn(),
+  sleep: vi.fn().mockResolvedValue(undefined),
+}));
+
+vi.mock("../progress", () => ({
+  overallProgress: vi.fn().mockReturnValue(0),
+}));
+
+vi.mock("../converter", () => ({
+  parseFrontmatter: vi.fn(),
+  regenerateFrontmatter: vi.fn(),
+}));
+
+vi.mock("../downloader", () => ({
+  downloadMediaAndUpdate: vi.fn().mockResolvedValue(undefined),
+  rewriteAllInternalLinks: vi.fn().mockResolvedValue(undefined),
+}));
+
+vi.mock("../social", () => ({
+  loadSocialData: vi.fn().mockResolvedValue({}),
+  saveSocialData: vi.fn().mockResolvedValue(undefined),
+  mergeSocialData: vi.fn().mockReturnValue({}),
+}));
+
+import { process } from "../main";
+
+// ============================================================================
+// Tests
+// ============================================================================
+
+describe("process hook binding guard", () => {
+  // sync_on_build: false so process() returns early after auth, letting us test
+  // only the binding guard logic without needing full sync mocking
+  const baseContext = {
+    project_path: "/test-project",
+    moss_dir: "/test-project/.moss",
+    config: { sync_on_build: false },
+    project_info: { homepage_file: null, lang: "en" },
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockApiConfig.queryMode = "viewer";
+    mockApiConfig.testUserName = "Matty";
+  });
+
+  it("proceeds normally when boundUserName is already set", async () => {
+    mockGetConfig.mockResolvedValue({ boundUserName: "alice", userName: "alice" });
+    mockGetAccessToken.mockResolvedValue("test-token");
+    mockFetchUserProfile.mockResolvedValue({
+      userName: "alice",
+      displayName: "Alice",
+      language: "en",
+    });
+
+    const result = await process(baseContext);
+
+    expect(result.success).toBe(true);
+    // detectBoundUser should NOT be called — boundUserName was already in config
+    expect(mockDetectBoundUser).not.toHaveBeenCalled();
+  });
+
+  it("auto-binds when existing Matters articles are found", async () => {
+    // First call: no boundUserName. Second call (after save): with boundUserName
+    mockGetConfig
+      .mockResolvedValueOnce({}) // binding guard check
+      .mockResolvedValue({ boundUserName: "bob", userName: "bob" }); // subsequent calls
+    mockDetectBoundUser.mockResolvedValue("bob");
+    mockGetAccessToken.mockResolvedValue("test-token");
+    mockFetchUserProfile.mockResolvedValue({
+      userName: "bob",
+      displayName: "Bob",
+      language: "en",
+    });
+
+    const result = await process(baseContext);
+
+    expect(result.success).toBe(true);
+    // Should have saved both boundUserName and userName
+    expect(mockSaveConfig).toHaveBeenCalledWith(
+      expect.objectContaining({ boundUserName: "bob", userName: "bob" })
+    );
+    // Should NOT have opened the login browser
+    expect(mockOpenBrowser).not.toHaveBeenCalled();
+  });
+
+  it("skips sync gracefully when user closes login window on unbound project", async () => {
+    mockGetConfig.mockResolvedValue({}); // no boundUserName
+    mockDetectBoundUser.mockResolvedValue(null); // no existing articles
+    // openBrowser returns a handle whose .closed resolves immediately (user closed window)
+    mockOpenBrowser.mockResolvedValue({
+      closed: Promise.resolve(),
+    });
+    mockGetAccessToken.mockResolvedValue(null); // no token
+
+    // A present-user trigger is required to reach promptLogin at all — the
+    // background gate exits before it (spec §3.3). Without this trigger the
+    // window-close mocks above are dead setup and the path is uncovered.
+    const result = await process({ ...baseContext, trigger: "onboarding_flow" });
+
+    expect(result.success).toBe(true);
+    expect(result.message).toContain("No Matters account bound");
+    // The login window must actually have been opened (guards against the
+    // trigger gate silently short-circuiting this test again).
+    expect(mockOpenBrowser).toHaveBeenCalled();
+    // Should NOT have saved any config
+    expect(mockSaveConfig).not.toHaveBeenCalled();
+  });
+
+  it("binds after successful login on fresh project", async () => {
+    mockGetConfig
+      .mockResolvedValueOnce({}) // binding guard check
+      .mockResolvedValueOnce({}) // affirmBindingFromProfile inside promptLogin
+      .mockResolvedValue({ boundUserName: "carol", userName: "carol" }); // after binding
+    mockDetectBoundUser.mockResolvedValue(null); // no existing articles
+    // openBrowser returns handle; token appears after login
+    mockOpenBrowser.mockResolvedValue({
+      closed: new Promise(() => {}), // never closes
+    });
+    // First getAccessToken call returns null (pre-login), then returns token
+    mockGetAccessToken
+      .mockResolvedValueOnce(null) // initial check in waitForToken
+      .mockResolvedValueOnce("new-token") // found after login
+      .mockResolvedValue("new-token"); // subsequent checks
+    mockFetchUserProfile.mockResolvedValue({
+      userName: "carol",
+      displayName: "Carol",
+      language: "en",
+    });
+
+    // Login-to-bind requires a present user since the trigger gate (spec
+    // §3.3): background/absent triggers exit quietly instead of prompting.
+    const result = await process({ ...baseContext, trigger: "onboarding_flow" });
+
+    expect(result.success).toBe(true);
+    // affirmBindingFromProfile (called from promptLogin) saves the binding.
+    // The condition fires because getConfig returns {} (no boundUserName yet)
+    // while fetchUserProfile returns "carol".
+    expect(mockSaveConfig).toHaveBeenCalledWith(
+      expect.objectContaining({ boundUserName: "carol" })
+    );
+  });
+});