Skip to content

fix(tui): open local file links with the OS handler - #55769

Open
YidaWeng wants to merge 13 commits into
anomalyco:devfrom
YidaWeng:local-file-links
Open

YidaWeng wants to merge 13 commits into
anomalyco:devfrom
YidaWeng:local-file-links

Conversation

@YidaWeng

@YidaWeng YidaWeng commented Oct 15, 2026 •

Copy link
Copy Markdown

Issue for this PR

Fixes #54816

Type of change

  • Bug fix
  • New feature
  • Refactor / code improvement
  • Documentation

What does this PR do?

Clicking a local file Markdown link in the TUI always went through the HTTP-only opener, so absolute paths and file:// links showed an error toast.

This adds openHref / resolveOpenTarget so http(s) still opens in the browser, while absolute paths, Windows drive paths (C:\ / C:/), local file:// URLs, and session-relative paths open with the OS handler. Remote file://host/... and other schemes stay rejected. Modified clicks (Cmd/Ctrl/etc.) are left to the terminal.

Relative links also resolved against the launch directory while the session's Location metadata was still loading. linkBase now uses the route's location.ref before paths.cwd, so a click during that window still resolves against the session directory.

How did you verify your code works?

  • bun test src/open.test.ts in packages/util (absolute paths, both Windows slash styles, file://, https, relative paths, unsafe schemes)
  • bun test test/app-links.test.ts in packages/tui — 2 passed (loaded and pending Location metadata); --rerun-each 5 — 10/10 passed
  • bun test test/ui/link.test.tsx in packages/tui — 2 passed (modifier guard)
  • Reproduced tui: local Markdown file links are sent to the HTTP-only browser opener #54816: before, absolute local-file clicks toasted; after, no toast and the path is handed to open
  • bun run check from the repository root — 35/35 tasks passed
  • Typecheck for util / tui on the change set

Screenshots / recordings

Covered in the earlier review thread on this PR (before toast / after no toast).

Checklist

  • I have tested my changes locally
  • I have not included unrelated changes in this PR

Added by the opencode bot (AI-generated).

Related: #51756, #47765

@github-actions

Copy link
Copy Markdown
Contributor

The following comment was made by an LLM, it may be inaccurate:

@opencode-agent opencode-agent Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

The link routing works, but as submitted this PR stops the TUI from starting.

App() in packages/tui/src/app.tsx already declares const paths = useTuiPaths() further down (line 697), so the new declaration at line 461 is a redeclaration. Running OpenCode from this branch fails with SyntaxError: Identifier 'paths' has already been declared, and bun run typecheck in packages/tui fails with TS2451. The branch is up to date with dev, so this isn't caused by an out-of-date base.

How I checked: I ran the reproduction from #54816 with an absolute link (/tmp/example.md) and a relative one (plan/example.md). On dev both clicks show the "Only http and https links" error notice. On this branch the TUI wouldn't start. With the duplicate line removed locally, neither click shows an error notice, and both paths reach the system opener, the relative one resolved against the session directory. The open.test.ts and link.test.tsx tests pass.

Public API: unchanged. The new openHref and resolveOpenTarget are internal to @opencode/util.

Related: #51756, #47765

Before

After

Comment thread packages/tui/src/app.tsx Resolved
@HootRock

Copy link
Copy Markdown

AI-assisted independent resolver check of 70857a25, native Windows / Bun 1.4.2 with existing dependencies.

The seven owning open.test.ts tests pass. Three additional real-file regressions fail: with an existing plan notes.md, relative Markdown hrefs plan%20notes.md, ./plan%20notes.md and plan%20notes.md#section resolve to literal %20/#section filenames that do not exist. The absolute path, unencoded relative path, canonical file: URL and file: URL with fragment controls resolve to the existing file.

Please cover encoded relative hrefs and fragments before treating session-relative Markdown routing as complete. The relative branch currently calls path.resolve on the URI spelling. Any decoding change should preserve literal filenames containing % or # through their encoded forms.

These checks import the actual utility source; they do not exercise renderer normalization, launch an OS handler, or establish a full TUI/typecheck/suite pass. No production code was changed.

reviewed and tested locally.

Transcript clicks always went through the HTTP-only browser opener, so
absolute paths and file:// links showed an error toast. Route those
targets through openHref while keeping openUrl strict for auth and docs.
Address review feedback on anomalyco#54838: resolve project-relative Markdown
paths before opening, skip any modified click so the terminal can handle
Cmd-click, and avoid toasting when a link cannot be opened.
URL.canParse treats C:\ and C:/ paths as scheme "c:", so resolveOpenTarget
returned undefined before path.isAbsolute. Check native absolute and
drive-qualified paths first, and cover both slash styles in tests.
App already calls useTuiPaths later; the second binding broke startup with
a redeclaration SyntaxError / TS2451. Keep one paths and define linkBase
next to it.
Percent-escaped session-relative Markdown links and #fragments were
passed through path.resolve as literal filenames. Decode URI spelling
and strip fragment/query so plan%20notes.md#section opens plan notes.md,
while literal % and # stay reachable via %25 and %23.

@pedro757 pedro757 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.

Reviewed fb6fe74 on Linux with Bun 1.4.4. I recommend fixing the absolute-href normalization bug below before merging; confirmed through a real OpenTUI click, an existing-file check, and four added utility regression cases. No production code was changed.

Web compatibility: production build and app typecheck pass; built Chromium E2Es for artifact-link reopening and image preview/zoom/pan/reset both pass. The GUI file-link resolver (32 tests), shared Markdown image/session-link/inline-code helpers (71 tests), and desktop URL policy (2 tests) also pass. The web/desktop opening paths are unchanged and do not import this utility; none of the 1,460 generated web JavaScript source maps includes it or TUI sources. Existing HTTP-only openUrl behavior is unchanged.

The PR's original 9 utility tests and original TUI click test pass (the latter also passed 10 consecutive runs). Full verification is not green: an existing photon-node patch blocks a full install/TUI dependency check, and broader Bun GUI suites hit missing solid-js jsxDEV exports. No Windows/macOS runtime verification.

Comment thread packages/util/src/open.ts Resolved
Absolute Markdown hrefs early-returned before decodeHrefPath, so
/tmp/mobile%20menu.png and /tmp/plan.md#section were passed to the OS
literally. Apply the same URI decode and fragment stripping used for
relative hrefs; leave openPath and openUrl unchanged.
@YidaWeng

Copy link
Copy Markdown
Author

Thanks @pedro757 — addressed the P2 in a follow-up commit.

Absolute Markdown hrefs (including drive-qualified ones) now go through `decodeHrefPath` the same way relatives do, so `/tmp/mobile%20menu.png` and `/tmp/plan.md#section` open as `/tmp/mobile menu.png` / `/tmp/plan.md`. `openPath` and `openUrl` are unchanged. Added regression coverage in `packages/util/src/open.test.ts`.

@opencode-agent opencode-agent Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

The earlier blocker is fixed: the duplicate paths declaration is gone and the TUI starts again.

I re-ran the #54816 reproduction against the current base, adding a relative link with an escaped space and a fragment (plan/my%20plan.md#top). On dev, clicking either link shows the "Only http and https links" error notice. With this PR there's no error notice, and the system opener receives /tmp/example.md and <project>/plan/my plan.md, so the new decoding works as intended. open.test.ts (10 tests) and link.test.tsx pass. tsgo shows no errors in the changed files.

Public API: unchanged. openHref and resolveOpenTarget are internal to @opencode/util.

No new concerns.

Before

After

@moritzWa

moritzWa commented Nov 2, 2026

Copy link
Copy Markdown

Tried this and the Markdown-link case works well for me. One gap I hit: agents mostly print bare paths in plain text (no link behind them), e.g. /Users/me/My\ Files/report.xlsx, and those still don't open. They also break when the path wraps across rows, since the click only sees one row.

I have this working on a fork (resolves plain-text paths, joins wrapped rows, only opens if the file exists, and refuses .app/scripts/executables). Happy to send it as a follow-up PR once this lands, so this one stays small.

@YidaWeng

YidaWeng commented Nov 3, 2026

Copy link
Copy Markdown
Author

@moritzWa Thanks!

@moritzWa

moritzWa commented Nov 3, 2026

Copy link
Copy Markdown

@rekram1-node could you take a look at this when you get a chance? Checks are green, the author addressed both rounds of review feedback on Oct 27, and the bot review says no new concerns. It's been waiting on a maintainer review since. It fixes #54816.

@pedro757 pedro757 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.

Reviewed 99248fe. Found a remote-path policy gap and an ineffective Meta-click regression test; details are inline.

Verification: bun test src/open.test.ts in packages/util passes all 10 tests, and bun test --timeout 30000 test/ui/link.test.tsx in packages/tui passes its test. A targeted UNC-rejection regression fails. Additional real OpenTUI renderer probes confirm that the UNC Markdown href reaches the resolver unchanged and that the mock mouse discards Meta. Windows path classification was checked with Node's path.win32; no native Windows/macOS opener or full-workspace verification was performed. No production code was changed.

Comment thread packages/util/src/open.ts Resolved
Comment thread packages/tui/test/ui/link.test.tsx Resolved
Reject //server/share and \\server\share targets, including percent-encoded
spellings, before they reach the OS handler. file URL paths that decode to a
UNC target are rejected the same way.
The OpenTUI mouse mock only reports shift/alt/ctrl, so a meta option was
silently dropped and the guard went untested. Cover every modifier directly,
including meta, and drop the ineffective mock option.
# Conflicts:
#	packages/tui/src/ui/link.tsx
@YidaWeng

Copy link
Copy Markdown
Author

Follow-up pushed in d2850d1 (also merged current dev; the branch is mergeable again).

  • P2 (UNC): ae2a31d rejects //server/share and \\server\share targets in resolveOpenTarget before the absolute-path shortcut, and re-checks the policy after URI decoding, fileURLToPath, and path.resolve. Covers encoded spellings (%2F%2F..., %5C%5C...) and file:////server/share/....
  • P3 (meta test): c18c1c2 drops the mock option that silently discarded meta and adds a direct clickedLink boundary test with shift, alt, ctrl, and a runtime meta flag.

Verification:

  • packages/util: bun test src/open.test.ts — 11 pass.
  • packages/tui: bun test --timeout 30000 test/ui/link.test.tsx — 2 pass, and 10 consecutive reruns pass (20/20).
  • Typecheck: packages/util and packages/tui clean; pre-push workspace typecheck 35/35 tasks successful.
  • Prettier and oxlint clean on the changed files.

Public API is unchanged; the new policy only applies to resolveOpenTarget / openHref in @opencode/util.

@YidaWeng

Copy link
Copy Markdown
Author

Folded in the follow-up from YidaWeng#1 (andy-takker) and merged current dev (d5ea1ee67).

  • linkBase now uses location.ref?.directory before paths.cwd, so a relative link clicked while the session Location metadata is still loading resolves against the session directory instead of the launch directory.
  • Added packages/tui/test/app-links.test.ts, which clicks a rendered relative Markdown link with loaded and pending Location metadata and asserts exactly one OS launch for the session path, plus an HTTPS control.
  • The launcher assertion covers WSL too: open uses PowerShell with a wslpath-converted target there.

Verification:

  • bun test test/app-links.test.ts (tui) — 2 passed; --rerun-each 5 — 10/10 passed.
  • bun test test/ui/link.test.tsx (tui) — 2 passed.
  • bun test src/open.test.ts (util) — 11 passed.
  • bun run check from the repository root — 35/35 tasks passed.

This branch has not been deployed

No deployments
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.

tui: local Markdown file links are sent to the HTTP-only browser opener

5 participants