fix: properly encode file URLs with special characters

[yudgnahk]

Summary

Fixes critical bug where filenames containing special characters (#, ?, %, spaces) caused ENOENT errors and path truncation throughout the application.

Root Cause

Using string interpolation `file://${path}` instead of proper URL encoding. The # character is treated as a URL fragment identifier, causing paths like /path/to/file#name.txt to be truncated to /path/to/file.

Solution

• Backend (Node.js/Bun): Use pathToFileURL() and fileURLToPath() built-in APIs
• Frontend (Browser): Custom encoding/decoding helpers (Bun APIs not available in browser)
• Special characters are now properly encoded: # → %23, ? → %3F, etc.

Changes

Backend Files (10 files)

• packages/opencode/src/session/prompt.ts - Fixed 2 occurrences using pathToFileURL()
• packages/opencode/src/cli/cmd/run.ts - Fixed 1 occurrence using pathToFileURL()
• packages/opencode/src/acp/agent.ts - Fixed 3 occurrences using pathToFileURL()
• packages/opencode/src/lsp/index.ts - Fixed decoding with fileURLToPath()
• packages/opencode/src/cli/cmd/tui/component/dialog-status.tsx - Fixed 1 occurrence using fileURLToPath()
• packages/opencode/src/cli/cmd/tui/component/prompt/autocomplete.tsx - Fixed 1 occurrence using pathToFileURL()
• packages/opencode/test/session/prompt-special-chars.test.ts - Added comprehensive test case for # character
• packages/sdk/js/example/example.ts - Fixed SDK example code using pathToFileURL()
• script/duplicate-pr.ts - Fixed duplicate-pr script using pathToFileURL()

Frontend Files (3 files)

• packages/app/src/components/prompt-input/build-request-parts.ts - Added encodeFilePath() helper, fixed file attachments and context files (2 locations)
• packages/app/src/context/file/path.ts - Added encodeFilePath() and decodeFilePath() helpers, fixed normalize() and tab() functions
• packages/app/src/components/file-tree.tsx - Added pathToFileUrl() helper, fixed drag-and-drop encoding

Testing

✅ All tests pass: bun test - 891 pass, 1 skip, 0 fail
✅ TypeScript clean: All 17 packages typecheck successfully
✅ Special chars test: Verifies # character handling end-to-end with file read/write
✅ Backward compatible: Normal paths produce identical output
✅ Comprehensive coverage: All instances of file://${...} pattern fixed across the codebase

Impact

Fixes:

• File tagging with @file#name.txt
• Diff/Review view loading for files with special characters
• Drag-and-drop operations from file tree
• SDK file operations with special characters
• Write tool operations for files with special characters
• Script utilities that process file paths

12 files changed, 114 insertions(+), 22 deletions(-)

Related Issues

Fixes#11790
Partially fixes#9804
May improve #9173, #8172, #8759, #11630

[github-actions]

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

I found 1 potentially related PR:

Related PR:

• fix(tui): Handle file paths with hashtags #11870 - fix(tui): Handle file paths with hashtags
  • Related because it addresses handling file paths with special characters (hashtags), which overlaps with the core issue in PR fix: properly encode file URLs with special characters #12424 about encoding file URLs with special characters like #. This appears to be a more targeted fix for the TUI component, whereas fix: properly encode file URLs with special characters #12424 is a comprehensive fix across multiple backend and frontend files.

The other match (#10049 about Windows drive letter case) is less directly related to special character encoding.

[alexyaroshuk]

I cannot mention files after this commit:
(latest app version, windows 10)

1. Use "@" in prompt input
2. select a file to mention, and send prompt
3. agent does not respond. terminal error:

938 | })
939 | }
940 |
941 | return pieces
942 | }
943 | const url = new URL(part.url)
^
TypeError: "file://D%3A%5Cdev%5Cprojects%5Copencode/README.bs.md" cannot be parsed as a URL.
code: "ERR_INVALID_URL"

 at <anonymous> (src\session\prompt.ts:943:23)
at map (1:11)
at createUserMessage (src\session\prompt.ts:869:19)

@yudgnahk Could you confirm this on your end and fix this ?

[yudgnahk]

Hi @alexyaroshuk, let me check.

[yudgnahk]

Hi @alexyaroshuk, please help me check the PR #12601