[brennanb2025]

Summary

• Replaces the flat Connect integrations accordion with a progressive two-step setup flow: first connect a review provider (GitHub, GitLab, Bitbucket, Azure DevOps, Gitea) for review status, then connect a task tracker (Linear, Jira) or explicitly use GitHub/GitLab issues for tasks.
• Makes the Settings -> Integrations cards the single source of truth: both Settings and the Connect flow now render the same extracted provider-card components, so the two surfaces stay aligned.
• Gives Jira a first-class Settings -> Integrations connect card alongside Linear. Previously Jira could only be authenticated from the onboarding Connect flow; Settings had a Linear card but no Jira equivalent.
• Centralizes gated integration readiness so stale host/WSL/runtime preflight context, current preflight errors, stale Linear/Jira runtime contexts, and runtime switches do not overclaim completion or hide usable task sources.

Shared Integration Cards

• integration-card-shell.tsx - the common card chrome (icon, name, description, status pill, action slot, expandable details).
• cli-source-control-integration-cards.tsx - GitHub/GitLab cards driven by gh/glab preflight status.
• token-source-control-integration-cards.tsx - Bitbucket/Azure DevOps/Gitea cards driven by env-var token configuration.
• source-control-integration-cards.tsx - barrel re-exporting the five review-provider cards.
• task-tracker-integration-cards.tsx - Linear and Jira connect/manage cards (Add access, per-workspace/site Test, disconnect).
• source-control-preflight-card-status.ts and use-integration-provider-status-refresh.ts - shared status derivation and the mount-time refresh both surfaces use.

Connect Flow

• ConnectIntegrationsList.tsx orchestrates the two-step flow (review -> tasks), Change/reopen behavior, code-host issue acknowledgement, and step gating. It renders the shared cards rather than bespoke rows.
• The progressive flow matches the Settings card UX: the inline gh auth login terminal and the standalone "You're set up" completion banner were removed in favor of consistent card instructions and step summaries/progress dots.
• Review completion can be satisfied by any current rendered review provider: GitHub, GitLab, Bitbucket, Azure DevOps, or Gitea. Only GitHub/GitLab can be accepted as task sources without a dedicated tracker, because those are the code hosts that expose issues in this flow.
• Code-host task acknowledgement is scoped to both provider and preflight context, so switching provider/runtime requires a fresh acknowledgement.

Readiness Derivation

• use-integration-connection-status.ts derives current provider readiness and flow state, distinguishing unresolved stale/loading checks from settled provider errors so summaries never flash for an unconnected user.
• Setup guide, settings progress, task-source presentation, TaskPage, SidebarNav, and the smart workspace source picker consume current-context provider facts instead of raw cached booleans.
• Desktop preflight refresh routes through runtime RPC when an active runtime environment is selected; local/WSL contexts continue to use the preload preflight API with WSL args.

Notes / Follow-ups

• INTEGRATIONS_PANE_SEARCH_ENTRIES does not yet include a Jira entry, so Settings search won't surface the new Jira card. Intentionally left for a follow-up.
• The Settings -> Tasks "Jira"/"Linear" entries remain visibility toggles for the Tasks source picker - a separate concern from authentication, unchanged here.

Tests

• pnpm run typecheck
• pnpm run lint (passes; unrelated pre-existing hook warnings in ChecksPanel.tsx, StatusBar.tsx, and Settings.tsx)
• git diff --check
• pnpm exec vitest run --config config/vitest.config.ts src/renderer/src/components/feature-wall/*.test.ts src/renderer/src/components/feature-wall/*.test.tsx src/renderer/src/store/slices/preflight.test.ts src/renderer/src/lib/local-preflight-context.test.ts src/renderer/src/components/sidebar/SidebarNav.test.tsx (14 files, 105 tests)
• pnpm build:relay
• brennan-yolo-lite review-fix: design review clean, implementation completeness check clean, two-agent code review loops run until final reviewer reported no actionable findings.
• Electron manual validation from this PR worktree (window.api.app.getIdentity() -> /Users/thebr/orca/workspaces/orca/chromis, branch brennanb2025/revamp-connect-integrations) using demo-project.
• Setup Guide -> Connect integrations: selected the real row, expanded review/tasks steps, verified two-step structure and progress summaries, review cards for GitHub/GitLab/Bitbucket/Azure DevOps/Gitea, task cards for Linear/Jira, and no inline auth terminal.
• Settings -> Integrations: verified the same seven provider cards render in the Settings surface.
• Console/log inspection: no relevant integration/preflight/runtime errors. Observed unrelated dev/profile warnings/errors for Google favicon DNS, React Grab version check, and a saved PTY with no live transport.

Residual Gaps / Accepted Risks

• No live GitLab auth command was run; installed/unauthenticated and missing-CLI behavior is covered by derived-state tests and visible card states.
• No paired runtime environment was available in this profile (runtimeEnvironments.list() returned []), so the active-runtime preflight.check live path was not exercised manually. The runtime dispatch contract is covered by focused preflight.test.ts, and local Electron validated the host preflight path.
• Full Vitest suite was not run end-to-end; focused suites cover the changed integration, setup-guide, and preflight surfaces.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds runtime-context keys and generation tracking, routes preflight through runtime RPC, and hardens Linear/Jira store slices against stale mid-flight results. Introduces pure derivation helpers and a hook to compute integration readiness/flow, new integration-card UI (CLI/token/task-tracker), a two-step ConnectIntegrationsList flow, and wiring to refresh/check provider status only when status is current. TaskPage, setup guide, sidebar, and settings UI were updated to use the new context-aware signals and to close/abort provider flows when the runtime context changes.

[coderabbitai]

Actionable comments posted: 7

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/renderer/src/components/TaskPage.tsx (1)

6272-6308: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Don't clear the selected Linear issue until the current-context check is ready.

Line 6277 currently treats “still checking this runtime context” the same as “disconnected”. That breaks direct-open/resume flows: pageData.openLinearIssue can populate selectedLinearIssue, then this effect clears it before checkLinearConnection() finishes, so the detail view never comes back. Wait for linearStatusReady before clearing, and gate the selected-issue render path the same way.

Suggested fix

   useEffect(() => {
     if (!taskResumeApplied || taskSource !== 'linear') {
       return
     }

-    if (!linearConnected) {
+    if (!linearStatusReady) {
+      return
+    }
+
+    if (!linearConnected) {
       clearSelectedLinearIssue()
       return
     }
@@
   }, [
     clearSelectedLinearIssue,
     filteredLinearIssues,
     linearConnected,
+    linearStatusReady,
     selectedLinearIssueCanFloat,
     selectedLinearIssueId,
     taskResumeApplied,
     taskSource
   ])

🧹 Nitpick comments (4)

src/renderer/src/components/feature-wall/use-integration-connection-status.ts (1)

119-137: 💤 Low value

Consider adding a clarifying comment for the Azure DevOps vs Gitea auth check asymmetry.

isAzureDevOpsReviewConfigured only enforces authentication when tokenConfigured && baseUrl are both truthy (line 123), whereas isGiteaReviewConfigured enforces authentication whenever tokenConfigured is true (line 133), regardless of baseUrl.

If this difference is intentional (e.g., Azure DevOps supports non-token configs where baseUrl is absent), a brief comment would help future readers. Otherwise, if Azure DevOps token configs always require a baseUrl, the logic is correct but the asymmetry is worth documenting.

src/renderer/src/components/TaskPage.tsx (1)

2502-2511: ⚡ Quick win

Add a short Why: comment for the context-key-derived readiness flags.

This block encodes the PR’s non-obvious stale-context contract, but nothing here explains why *_Connected is intentionally stricter than raw status.connected. A 1-2 line note would make future edits much less likely to collapse this back to the old behavior.

Suggested comment

+  // Why: provider/preflight status is only trustworthy when it was computed for
+  // the current runtime context; otherwise we stay in a loading state.
   const providerRuntimeContextKey = getProviderRuntimeContextKey(settings)
   const providerRuntimeContextKeyRef = useRef(providerRuntimeContextKey)
   providerRuntimeContextKeyRef.current = providerRuntimeContextKey
   const linearStatusCurrent = linearStatusContextKey === providerRuntimeContextKey
   const jiraStatusCurrent = jiraStatusContextKey === providerRuntimeContextKey

As per coding guidelines, **/*.{ts,tsx,js,jsx}: When writing or modifying code driven by a design doc or non-obvious constraint, add a comment explaining why the code behaves the way it does.

Source: Coding guidelines

src/renderer/src/lib/local-preflight-context.ts (1)

29-35: ⚡ Quick win

Consider caching runtime context objects for consistency.

Lines 30-32 create a fresh object on every call, whereas WSL contexts are explicitly cached (lines 16-27) with the comment "React/Zustand selectors must return a cached snapshot" to prevent useSyncExternalStore loops. Although current usage only selects the derived string key, future code selecting the context object directly could trigger unnecessary re-renders.

A similar caching strategy keyed by runtimeContextKey would maintain consistency with the established pattern and future-proof the selector behavior.

♻️ Suggested caching approach

+const runtimePreflightContextsByKey = new Map<string, NonNullable<LocalPreflightContext>>()
+
+function getRuntimePreflightContext(key: string): NonNullable<LocalPreflightContext> {
+  const cached = runtimePreflightContextsByKey.get(key)
+  if (cached) {
+    return cached
+  }
+  const context = Object.freeze({ runtimeContextKey: key })
+  runtimePreflightContextsByKey.set(key, context)
+  return context
+}
+
 export function getLocalPreflightContext(state: AppState): LocalPreflightContext {
   if (state.settings?.activeRuntimeEnvironmentId?.trim()) {
-    return { runtimeContextKey: getProviderRuntimeContextKey(state.settings) }
+    return getRuntimePreflightContext(getProviderRuntimeContextKey(state.settings))
   }
   const wslDistro = getLocalPreflightWslDistro(state)
   return wslDistro ? getWslPreflightContext(wslDistro) : undefined
 }

src/renderer/src/components/settings/use-integration-provider-status-refresh.ts (1)

25-34: ⚡ Quick win

Add a short “why” comment for the context-staleness refresh effect.

This runtime-context mismatch behavior is non-obvious; add a 1–2 line rationale above the effect so future edits don’t regress staleness handling.

Suggested minimal diff

-  useEffect(() => {
+  // Re-check provider status whenever stored status is missing or belongs to a stale runtime/preflight context.
+  // This keeps settings cards aligned with the currently selected execution context.
+  useEffect(() => {

As per coding guidelines, "When writing or modifying code driven by a design doc or non-obvious constraint, add a comment explaining why the code behaves the way it does."

Source: Coding guidelines

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 121288aa-87af-4114-9899-41100c6ec19c

📥 Commits

Reviewing files that changed from the base of the PR and between 24f8eaa and 940a8be.

📒 Files selected for processing (40)

• src/renderer/src/components/TaskPage.tsx
• src/renderer/src/components/feature-wall/ConnectIntegrationsList.test.tsx
• src/renderer/src/components/feature-wall/ConnectIntegrationsList.tsx
• src/renderer/src/components/feature-wall/FeatureWallSetupChecklist.tsx
• src/renderer/src/components/feature-wall/connect-integration-step.tsx
• src/renderer/src/components/feature-wall/feature-wall-setup-progress.test.ts
• src/renderer/src/components/feature-wall/use-feature-wall-task-source-presentation.ts
• src/renderer/src/components/feature-wall/use-integration-connection-status.test.ts
• src/renderer/src/components/feature-wall/use-integration-connection-status.ts
• src/renderer/src/components/jira-connect-dialog.tsx
• src/renderer/src/components/new-workspace/SmartWorkspaceNameField.tsx
• src/renderer/src/components/settings/IntegrationsPane.tsx
• src/renderer/src/components/settings/cli-source-control-integration-cards.tsx
• src/renderer/src/components/settings/integration-card-shell.tsx
• src/renderer/src/components/settings/jira-integration-card.tsx
• src/renderer/src/components/settings/source-control-integration-cards.tsx
• src/renderer/src/components/settings/source-control-preflight-card-status.ts
• src/renderer/src/components/settings/task-tracker-integration-cards.tsx
• src/renderer/src/components/settings/token-source-control-integration-cards.tsx
• src/renderer/src/components/settings/use-integration-provider-status-refresh.ts
• src/renderer/src/components/setup-guide/setup-guide-progress-readiness.ts
• src/renderer/src/components/setup-guide/setup-script-probe-cache.ts
• src/renderer/src/components/setup-guide/use-setup-guide-progress.test.ts
• src/renderer/src/components/setup-guide/use-setup-guide-progress.ts
• src/renderer/src/components/sidebar/SidebarNav.tsx
• src/renderer/src/i18n/locales/en.json
• src/renderer/src/i18n/locales/es.json
• src/renderer/src/i18n/locales/ja.json
• src/renderer/src/i18n/locales/ko.json
• src/renderer/src/i18n/locales/zh.json
• src/renderer/src/lib/local-preflight-context.test.ts
• src/renderer/src/lib/local-preflight-context.ts
• src/renderer/src/lib/provider-runtime-context.ts
• src/renderer/src/store/slices/jira.test.ts
• src/renderer/src/store/slices/jira.ts
• src/renderer/src/store/slices/linear.test.ts
• src/renderer/src/store/slices/linear.ts
• src/renderer/src/store/slices/preflight.test.ts
• src/renderer/src/store/slices/preflight.ts
• src/renderer/src/store/slices/settings.ts

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Use translate() for credential storage messaging.

Lines 59-61 define credentialStorageCopy with hardcoded English strings. This breaks i18n consistency—every other user-facing string in this file uses translate(). These credential storage messages must be localized for non-English users.

🌐 Proposed fix to add localization

  const credentialStorageCopy = hasRemoteProviderRuntime(settings)
-    ? 'Your token is sent to the selected remote runtime and stored there with runtime-supported encryption.'
-    : 'Your token is stored locally and encrypted when local runtime storage supports it.'
+    ? translate(
+        'auto.components.jira.connect.dialog.credential_storage_remote',
+        'Your token is sent to the selected remote runtime and stored there with runtime-supported encryption.'
+      )
+    : translate(
+        'auto.components.jira.connect.dialog.credential_storage_local',
+        'Your token is stored locally and encrypted when local runtime storage supports it.'
+      )

Note: These keys will need to be added to all locale files (en.json, es.json, ja.json, ko.json, zh.json).

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	const credentialStorageCopy = hasRemoteProviderRuntime(settings)
	? 'Your token is sent to the selected remote runtime and stored there with runtime-supported encryption.'
	: 'Your token is stored locally and encrypted when local runtime storage supports it.'
	const credentialStorageCopy = hasRemoteProviderRuntime(settings)
	? translate(
	'auto.components.jira.connect.dialog.credential_storage_remote',
	'Your token is sent to the selected remote runtime and stored there with runtime-supported encryption.'
	)
	: translate(
	'auto.components.jira.connect.dialog.credential_storage_local',
	'Your token is stored locally and encrypted when local runtime storage supports it.'
	)

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Use translate() for credential messaging.

Lines 36-38 define credentialCopy with hardcoded English strings. This is the same localization issue as in jira-connect-dialog.tsx. All user-facing text must use translate() for i18n support.

🌐 Proposed fix to add localization

  const credentialCopy = hasRemoteProviderRuntime(settings)
-    ? 'Connect a Jira Cloud site with your Atlassian email and an API token. Credentials are sent to the selected remote runtime and stored there with runtime-supported encryption.'
-    : 'Connect a Jira Cloud site with your Atlassian email and an API token. Credentials are stored locally and encrypted when local runtime storage supports it.'
+    ? translate(
+        'auto.components.settings.jira.integration.card.credential_copy_remote',
+        'Connect a Jira Cloud site with your Atlassian email and an API token. Credentials are sent to the selected remote runtime and stored there with runtime-supported encryption.'
+      )
+    : translate(
+        'auto.components.settings.jira.integration.card.credential_copy_local',
+        'Connect a Jira Cloud site with your Atlassian email and an API token. Credentials are stored locally and encrypted when local runtime storage supports it.'
+      )

Note: These keys will need to be added to all locale files.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	const credentialCopy = hasRemoteProviderRuntime(settings)
	? 'Connect a Jira Cloud site with your Atlassian email and an API token. Credentials are sent to the selected remote runtime and stored there with runtime-supported encryption.'
	: 'Connect a Jira Cloud site with your Atlassian email and an API token. Credentials are stored locally and encrypted when local runtime storage supports it.'
	const credentialCopy = hasRemoteProviderRuntime(settings)
	? translate(
	'auto.components.settings.jira.integration.card.credential_copy_remote',
	'Connect a Jira Cloud site with your Atlassian email and an API token. Credentials are sent to the selected remote runtime and stored there with runtime-supported encryption.'
	)
	: translate(
	'auto.components.settings.jira.integration.card.credential_copy_local',
	'Connect a Jira Cloud site with your Atlassian email and an API token. Credentials are stored locally and encrypted when local runtime storage supports it.'
	)

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Check if z-index values are documented or if other dialogs use standard tokens

echo "=== Checking for z-index documentation in STYLEGUIDE.md ==="
if [ -f docs/STYLEGUIDE.md ]; then
  rg -i 'z-index|layer|overlay' docs/STYLEGUIDE.md -C 2
else
  echo "STYLEGUIDE.md not found"
fi

echo -e "\n=== Checking other dialog z-index usage patterns ==="
rg 'z-\[1[0-9]{2}\]|z-\[2[0-9]{2}\]' src/renderer/src/components/ -n --type tsx -C 1

Repository: stablyai/orca

Length of output: 2509

---

Document or token-ize the modal z-index used by LinearApiKeyDialog.

src/renderer/src/components/settings/task-tracker-integration-cards.tsx lines 205-206 hardcode overlayClassName="z-[110]" and contentClassName="z-[120]". docs/STYLEGUIDE.md includes general guidance for dialogs/overlays, but it doesn’t document any z-index/layer tiers or tokens—so these values should be replaced with a semantic/documented layer or have a short “why these layers” comment at the call site to prevent overlay/modals stacking conflicts.

Source: Coding guidelines

[coderabbitai]

⚠️ Potential issue | 🟠 Major | 🏗️ Heavy lift

Translate new es.json entries; English strings are leaking into Spanish UI

Multiple newly added locale values are still in English (integrations cards, Connect flow copy, and Jira connect dialog), so Spanish users will see mixed-language screens in core setup flows.

Also applies to: 4548-4551, 7282-7378, 8933-8953, 10158-10176

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Localize the newly added ja strings; English copy is currently shipping in the Japanese locale.

Several newly added entries are still English in ja.json (integration cards, connect-flow steps, and Jira connect dialog). This will surface mixed-language UI for Japanese users in the new setup flow.

Also applies to: 4569-4572, 7287-7304, 7313-7333, 7342-7373, 8934-8950, 10161-10173

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Localize newly added Korean locale strings instead of shipping English copy.

These new ko.json entries are still English (for example, Line 237, Line 4533, Line 7287, Line 8934, Line 10161), so Korean users will see mixed-language UI in the new integrations flow. Please translate these values to Korean (or intentionally route them to fallback locale if that is the intended behavior).

Also applies to: 4533-4536, 7287-7303, 7313-7332, 7342-7373, 8933-8950, 10161-10173

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Localize newly added zh strings instead of shipping English copy.

These newly added values are in English inside zh.json, so Simplified Chinese users will see mixed-language UI across integration cards, connect flow copy, Jira dialog, and superseded-request messages. Please translate these entries for the zh locale (or deliberately move them to fallback-only behavior if that’s intended).

Also applies to: 4533-4536, 7287-7374, 8934-8950, 10161-10174

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/renderer/src/components/feature-wall/connect-integration-step.tsx (1)

52-53: ⚠️ Potential issue | 🟡 Minor

Status-success tokens exist in the CSS token source

• status-success, status-success-border, and status-success-background are defined in src/renderer/src/assets/main.css (mapped from --status-success*).
• docs/STYLEGUIDE.md has no occurrences of status-success, so the style guide may be missing documentation for these tokens.

Source: Coding guidelines

🧹 Nitpick comments (1)

src/renderer/src/components/feature-wall/use-integration-connection-status.ts (1)

188-193: 💤 Low value

Optional refactor: redundant as const assertions.

The as const assertions on lines 189-192 create readonly tuples that are immediately spread into the parent array. Since taskSourceNames is already explicitly typed as IntegrationConnectionStatus['taskSourceNames'], these assertions are redundant.

♻️ Simplified version without redundant assertions

  const taskSourceNames: IntegrationConnectionStatus['taskSourceNames'] = [
-    ...(linearConnected ? (['Linear'] as const) : []),
-    ...(jiraConnected ? (['Jira'] as const) : []),
-    ...(githubConnected ? (['GitHub'] as const) : []),
-    ...(gitlabConnected ? (['GitLab'] as const) : [])
+    ...(linearConnected ? ['Linear'] : []),
+    ...(jiraConnected ? ['Jira'] : []),
+    ...(githubConnected ? ['GitHub'] : []),
+    ...(gitlabConnected ? ['GitLab'] : [])
  ]

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 247daa58-065d-4a8c-b783-5951b7618653

📥 Commits

Reviewing files that changed from the base of the PR and between 940a8be and 136a736.

📒 Files selected for processing (10)

• src/renderer/src/components/feature-wall/ConnectIntegrationsList.test.tsx
• src/renderer/src/components/feature-wall/ConnectIntegrationsList.tsx
• src/renderer/src/components/feature-wall/connect-integration-step.tsx
• src/renderer/src/components/feature-wall/use-integration-connection-status.test.ts
• src/renderer/src/components/feature-wall/use-integration-connection-status.ts
• src/renderer/src/i18n/locales/en.json
• src/renderer/src/i18n/locales/es.json
• src/renderer/src/i18n/locales/ja.json
• src/renderer/src/i18n/locales/ko.json
• src/renderer/src/i18n/locales/zh.json

✅ Files skipped from review due to trivial changes (2)

• src/renderer/src/i18n/locales/ja.json
• src/renderer/src/i18n/locales/es.json

🚧 Files skipped from review as they are similar to previous changes (4)

• src/renderer/src/components/feature-wall/use-integration-connection-status.test.ts
• src/renderer/src/i18n/locales/ko.json
• src/renderer/src/i18n/locales/en.json
• src/renderer/src/i18n/locales/zh.json