Skip to content

Route terminal file URL links to the OS - #7122

Merged
austinywang merged 5 commits into
mainfrom
issue-7104-file-link-os
Jul 1, 2026
Merged

austinywang merged 5 commits into
mainfrom
issue-7104-file-link-os

Conversation

@austinywang

@austinywang austinywang commented Jul 1, 2026 •

Copy link
Copy Markdown
Contributor

Closes #7104

Summary

  • Add a terminal open-URL file-routing policy for the pre-browser cmux file-preview interception gate.
  • Keep bare absolute path cmd-clicks eligible for cmux file preview.
  • Ensure explicit URL schemes, including file://, bypass cmux file preview and continue to the external URL route.

Tests

  • git diff --check origin/main...HEAD
  • python3 scripts/swift_file_length_budget.py
  • python3 scripts/check-package-resolved-policy.py
  • ./scripts/lint-pbxproj-test-wiring.sh
  • /Users/austinwang/manaflow/cmuxterm-hq/skills/autoreview/scripts/cmux-policy-check --mode branch --base origin/main
  • Attempted: swift test --filter TerminalOpenURLFileRoutingPolicyTests from Packages/macOS/CmuxTerminalCore (blocked locally because GhosttyKit.xcframework is missing a binary artifact; did not run setup/build per no-build instruction).

Regression structure

  • Commit 1 adds the regression around the extracted policy while preserving the old interception behavior, so the new file:// assertion is red.
  • Commit 2 adds the scheme short-circuit so the regression goes green.
  • Commit 3 addresses the local cmux policy review by using private instance helpers instead of private static helpers.
  • Commit 4 addresses Greptile feedback by removing the unreachable localhost branch and unused test parameterization.
  • Commit 5 addresses CodeRabbit/Cubic coverage feedback for hosted file targets.

Summary by CodeRabbit

  • New Features
    • Improved open-link handling so local file paths are routed to the file viewer/editor more consistently.
    • Centralized routing decisions for open-URL handling to ensure consistent behavior across cases.
  • Bug Fixes
    • Refined “local file” detection and bypass rules, including clearer treatment of explicit URL schemes and file:// URL hosts.
    • Preserves support for absolute file paths and paths with fragments.
  • Tests
    • Added/expanded coverage for file vs non-file links, scheme-handling, and local vs non-local file routing behavior.

@vercel

vercel Bot commented Jul 1, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
cmux Ready Ready Preview, Comment Jul 1, 2026 2:21am
cmux-staging Building Building Preview, Comment Jul 1, 2026 2:21am

@coderabbitai

coderabbitai Bot commented Jul 1, 2026 •

Copy link
Copy Markdown

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: ccb0659a-9f93-480f-a17c-4f928f973392

📥 Commits

Reviewing files that changed from the base of the PR and between bac1e07 and c62a007.

📒 Files selected for processing (1)
  • Packages/macOS/CmuxTerminalCore/Tests/CmuxTerminalCoreTests/TerminalOpenURLFileRoutingPolicyTests.swift

📝 Walkthrough

Walkthrough

Adds a new TerminalOpenURLFileRoutingPolicy for cmux file-routing decisions, adds tests for URL and host handling, and updates GhosttyTerminalView to use the policy instead of inline checks.

Changes

File URL Routing Policy

Layer / File(s) Summary
Routing policy implementation and tests
Packages/macOS/CmuxTerminalCore/Sources/CmuxTerminalCore/LinkRouting/TerminalOpenURLFileRoutingPolicy.swift, Packages/macOS/CmuxTerminalCore/Tests/CmuxTerminalCoreTests/TerminalOpenURLFileRoutingPolicyTests.swift
New TerminalOpenURLFileRoutingPolicy struct with shouldAttemptCmuxFileRouting gating on explicit schemes, file-URL type, and local-host detection; five XCTest cases validate false/true outcomes for file, non-file, localhost, remote-host, and absolute-path inputs.
Terminal view integration
Sources/GhosttyTerminalView.swift
Replaces inline file:///host-based routing checks with a call to TerminalOpenURLFileRoutingPolicy().shouldAttemptCmuxFileRouting(rawOpenURLValue:target:).

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related issues

  • #1154 — The new file-routing policy and its GhosttyTerminalView integration address the same terminal link/file-path resolution path as this issue’s relative-file handling bug.

Poem

A rabbit saw a link go by,
Said “policy first” and gave a hop and sigh.
Bare paths to files, let cmux decide,
While browser tabs stay on the side. 🐰

🚥 Pre-merge checks | ✅ 24 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 11.11% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (24 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly matches the main change: routing terminal file links to the OS instead of cmux's embedded browser.
Description check ✅ Passed The description covers the summary and testing, but omits some template sections like Demo Video, Review Trigger, and Checklist.
Linked Issues check ✅ Passed The change addresses #7104 by bypassing cmux file-preview routing for explicit file:// links so they can go to the OS.
Out of Scope Changes check ✅ Passed The PR stays focused on the file-routing policy, test coverage, and the terminal open-URL call site with no clear unrelated changes.
Cmux Swift Actor Isolation ✅ Passed The new Sendable helper is a pure value-type utility, not MainActor-isolated, and it adds no shared mutable state or background-accessed UI store.
Cmux Swift Blocking Runtime ✅ Passed PASS: The PR adds a pure file-routing policy and tests; no new semaphores, sleeps, asyncAfter, locks, or waits were introduced, and existing main-sync helper usage was reused.
Cmux Browser Automation Off-Main ✅ Passed PR only changes terminal open-URL file routing and tests; no browser.* command, socket-worker router, or WebKit/AppKit wait path is modified.
Cmux Expensive Synchronous Load ✅ Passed No expensive agent-history load was added; the diff only adds lightweight URL/file-routing checks and no RestorableAgentSessionIndex/load or JSON/JSONL parsing.
Cmux Cache Substitution Correctness ✅ Passed The diff only adds URL-routing policy and tests; it doesn’t replace any fresh persistence/history/snapshot read with cached state or touch cache handling.
Cmux No Hacky Sleeps ✅ Passed The PR only touches Swift source/tests; no TS/JS/shell/runtime scripts or fixed waits are present for this rule to flag.
Cmux Algorithmic Complexity ✅ Passed New policy and call site are O(1) string/URL checks; no nested scans, repeated sorts/filters, or scalable collection work were added.
Cmux Swift Concurrency ✅ Passed The added policy and tests are synchronous, and the touched app-path Task is a MainActor callback/UI hop rather than a new legacy async pattern.
Cmux Swift @Concurrent ✅ Passed The new policy is synchronous, the call site stays UI-bound, and the diff adds no async/nonisolated/@Concurrent code to mis-annotate.
Cmux Swift File And Package Boundaries ✅ Passed New 36-line policy lives in CmuxTerminalCore with tests; GhosttyTerminalView only has small glue changes, so no boundary violation.
Cmux Swiftpm Lockfiles ✅ Passed PR only touches Swift source/tests; direct diff against origin/main shows no .gitignore, Package.resolved, workflow, or Xcode project changes.
Cmux Swift Logging ✅ Passed The diff adds no production logging; the new policy/tests contain no print/debugPrint/dump/NSLog/Logger, and the open-URL diagnostics are DEBUG-gated cmuxDebugLog calls.
Cmux User-Facing Error Privacy ✅ Passed Diff adds routing logic/tests only; no new user-facing errors, alerts, command output, or sensitive payloads were introduced.
Cmux Full Internationalization ✅ Passed Only routing logic/tests were added; no new user-facing Swift text, catalogs, plist, or web locale files were changed.
Cmux Swiftui State Layout ✅ Passed No new SwiftUI state/layout anti-patterns: the change is a pure routing policy plus an NSViewRepresentable bridge, with no new ObservableObject/@State/GeometryReader/lazy-row state.
Cmux Architecture Rethink ✅ Passed Stateless file-routing predicate + single call site; no sleeps, observers, locks, or split ownership. Explicit-scheme invariant is clear.
Cmux Swift Auxiliary Window Close Shortcuts ✅ Passed No standalone window/controller code was introduced; the PR only adds file-routing policy/tests and a GhosttyTerminalView call site, with no cmux.* close-shortcut wiring.
Cmux Source Artifacts ✅ Passed Changed paths are source/tests/rules plus intentional checked-in assets; no temp, build, cache, log, or scratch directories appear in the diff.
Cmux No Test Or Debug Seam In Production Source ✅ Passed The diff adds a runtime file-routing policy and a production call-site refactor only; no new DEBUG/test-only seam or debug accessor appears in Sources/.
Cmux No Ambient Global State ✅ Passed The new policy is an injectable instance struct with private helpers, and the touched files add no new top-level mutable state or singleton/static-only namespace.
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch issue-7104-file-link-os

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@greptile-apps

greptile-apps Bot commented Jul 1, 2026 •

Copy link
Copy Markdown
Contributor

Greptile Summary

This PR extracts the terminal open-URL file-routing gate from GhosttyTerminalView.swift into a new TerminalOpenURLFileRoutingPolicy struct and adds a scheme short-circuit so that explicit URL schemes (including file://) bypass cmux's file-preview interception and go directly to the OS.

  • TerminalOpenURLFileRoutingPolicy centralizes the shouldAttemptCmuxFileRouting decision with two guards: a scheme detector that passes bare paths through and a local-host check that blocks hosted file:// targets, then tests cover explicit file://, file://localhost, hosted file://, bare absolute path, and non-file URL cases.
  • GhosttyTerminalView.swift replaces the inline isFileURL/host checks with a single call to the new policy struct, and the previously dead host == "localhost" branch is removed.

Confidence Score: 5/5

Safe to merge — the change is a focused extraction of existing inline logic into a tested policy struct with a correct scheme short-circuit added.

The routing logic is straightforward: a scheme guard bypasses cmux for all explicit-scheme inputs, and the remaining isLocalFileURL check matches the previous behavior minus the now-confirmed-dead localhost branch. The five unit tests cover the meaningful distinct cases, and the previously flagged dead branch and unused parameterization were both addressed in earlier commits. No actor isolation, blocking primitive, global state, or test-seam concerns were introduced.

No files require special attention.

Important Files Changed

Filename Overview
Packages/macOS/CmuxTerminalCore/Sources/CmuxTerminalCore/LinkRouting/TerminalOpenURLFileRoutingPolicy.swift New policy struct with two instance-method guards (scheme detection, local-host check); stateless Sendable struct with proper init; no global state, no test seams, no blocking primitives.
Packages/macOS/CmuxTerminalCore/Tests/CmuxTerminalCoreTests/TerminalOpenURLFileRoutingPolicyTests.swift Five focused tests covering explicit file scheme, localhost file scheme, hosted file target without raw scheme, bare absolute path, and non-file target; previously flagged unused parameterization removed.
Sources/GhosttyTerminalView.swift Replaces inline isFileURL/host guard with a single policy call; previously dead localhost host branch removed; per-call struct instantiation is zero-cost for a stateless value type.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Terminal cmd-click\nrawOpenURLValue] --> B{hasExplicitURLScheme?\ne.g. file://, https://}
    B -- yes --> C[return false\nOS / URL route]
    B -- no --> D{target.url.isFileURL?}
    D -- no --> C
    D -- yes --> E{isLocalFileURL?\nhost nil or empty}
    E -- no\nremote host --> C
    E -- yes --> F[return true\ncmux file preview eligible]
    F --> G{Settings / file existence\n/ workspace locality\n/ split checks}
    G -- pass --> H[cmux file preview UI]
    G -- fail --> C
Loading
%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[Terminal cmd-click\nrawOpenURLValue] --> B{hasExplicitURLScheme?\ne.g. file://, https://}
    B -- yes --> C[return false\nOS / URL route]
    B -- no --> D{target.url.isFileURL?}
    D -- no --> C
    D -- yes --> E{isLocalFileURL?\nhost nil or empty}
    E -- no\nremote host --> C
    E -- yes --> F[return true\ncmux file preview eligible]
    F --> G{Settings / file existence\n/ workspace locality\n/ split checks}
    G -- pass --> H[cmux file preview UI]
    G -- fail --> C
Loading

Reviews (3): Last reviewed commit: "Cover hosted terminal file URL targets" | Re-trigger Greptile

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In
`@Packages/macOS/CmuxTerminalCore/Sources/CmuxTerminalCore/LinkRouting/TerminalOpenURLFileRoutingPolicy.swift`:
- Around line 22-25: Add coverage for the reachable host-based path in
TerminalOpenURLFileRoutingPolicy.isLocalFileURL by creating a test where
hasExplicitURLScheme(rawOpenURLValue) is false but target.url still has a
non-empty host, so the first guard in shouldRouteOpenURL does not short-circuit
the call. Verify the behavior of isLocalFileURL directly through the
TerminalOpenURLFileRoutingPolicy logic using a target.url that is file:// with
host data and a raw value without an explicit scheme, ensuring this branch is
actually exercised.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 4e86a190-0dce-44a6-b9ed-953692231cdc

📥 Commits

Reviewing files that changed from the base of the PR and between d1758fe and bac1e07.

📒 Files selected for processing (2)
  • Packages/macOS/CmuxTerminalCore/Sources/CmuxTerminalCore/LinkRouting/TerminalOpenURLFileRoutingPolicy.swift
  • Packages/macOS/CmuxTerminalCore/Tests/CmuxTerminalCoreTests/TerminalOpenURLFileRoutingPolicyTests.swift

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

1 issue found across 2 files (changes from recent commits).

Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic

This branch was successfully deployed

1 active deployment
Preview – cmux — c62a007c Deployed Jul 1, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Cmd/Ctrl-click on file:// links (Claude Code 2.1.196) opens cmux embedded browser instead of Finder / OS default app

1 participant