Skip to content

refactor(server): read skill and workspace previews through one function - #255

Merged
GoDiao merged 2 commits into
GoDiao:mainfrom
iruzen-dono:refactor/shared-file-preview
Nov 15, 2026
Merged

GoDiao merged 2 commits into
GoDiao:mainfrom
iruzen-dono:refactor/shared-file-preview

Conversation

@iruzen-dono

@iruzen-dono iruzen-dono commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Closes #247

What changed

src/server/services/filePreview.ts is now the only place a file is classified as text, image, binary, too large, missing or unreadable. readFilePreview(path, { maxBytes, oversize, inlineImage }) takes the caller's limit and what to do past it, so the two callers keep their own behaviour: the skill page keeps refusing above 100 KB (oversize: 'refuse'), the Files tab keeps reading its first 1 MB (oversize: 'truncate'). An image is not read at all unless the caller asks for the data URL, which is why the skill page still never loads image bytes for a page it renders on demand.

readSkillFile and WorkspaceService.readFile both delegate to it and lose their duplicated checks. readSkillFile is out of the route file's body count too — it only decides frontmatter and entry-ness now, which is what the route is for.

One result shape

state: 'text' | 'image' | 'binary' | 'too_large' | 'missing' | 'error'

previewType is gone from the API and everywhere it was read: state === 'image' already says it, and keeping both was the duplication this issue is about. Updated: src/server/api/skills.ts, src/server/services/workspaceService.ts, desktop/src/types/skill.ts, desktop/src/api/sessions.ts, desktop/src/stores/workspacePanelStore.ts, desktop/src/components/workspace/WorkspacePanel.tsx and desktop/src/components/skills/SkillDetail.tsx. SkillFileState is Exclude<FilePreviewState, 'missing' | 'error'> on both sides, so the four states a page can render are derived from the six a preview can report.

The store keeps its own kind: 'file' | 'diff' discriminator for the panel, which is a different axis — which is why the unified field is state and not kind, as the issue's list of names allowed.

The behaviour difference, as the issue asked

One, and it is a file that cannot be read at all: readSkillFile used to log the failure and drop the file. It now returns missing or error through the shared function, and the walk skips it — logging fullPath and preview.error on the error state so the reason survives, while missing stays quiet.

Everything else is preserved, including the two size limits, the zero-byte binary rule, the image short-circuit before the size check, truncated/readBytes, and the language each state reports.

Checks, with the numbers

  • bun test on the four server files this PR owns → 155 pass, 0 fail, 1 skipped (the unreadable-file case, skipped on Windows where chmod does not restrict)
  • cd desktop && bun run lint → exit 0 (tsc, tsc electron, oxlint)
  • cd desktop && bun run test -- --run → 2858 pass, 5 fail; those same 5 fail by name on a stashed tree, in pages.test, LocalSlashCommandPanel, MessageList and UpdateChecker, none of which this PR touches
  • bun test (whole server suite) → 2625 pass, 16 fail; the same failures reproduce on HEAD~1 (189 pass / 6 fail on the six affected files, on both commits), all Windows symlink fixtures and 5 s timeouts.

New spec: src/server/__tests__/file-preview.test.ts, eight cases — text, a zero byte, an oversized file in both modes, a file of exactly the limit in both modes, a missing file, a path stat refuses with something other than absence, and an image with and without the inline request.

Out of scope

No visible change on either page. The workspace panel's kind: 'file' | 'diff' and the tree/status results keep their own state vocabulary, which is a different object from a file preview.

Two functions decided whether a file is text, binary or too large, and returned different shapes for
the same answer: `readSkillFile` in a route file returned `kind`, and `WorkspaceService.readFile`
returned `state` plus a `previewType` that only ever restated it. `AGENTS.md` asks route handlers to
stay thin and call services, which the skill reader did not.

`readFilePreview` in `src/server/services/filePreview.ts` is now the only place that classification
happens. It takes the caller's size limit, whether an oversized file is refused or truncated, and
whether an image is inlined, so the skill page keeps refusing above 100 KB and the Files tab keeps
reading the first 1 MB. Both readers delegate and drop their duplicated checks.

One result shape, `state: 'text' | 'image' | 'binary' | 'too_large' | 'missing' | 'error'`, reaches the
server types, the desktop types (`types/skill.ts`, `api/sessions.ts`, `stores/workspacePanelStore.ts`,
`WorkspacePanel.tsx`) and `SkillDetail`. `previewType` is gone: `state === 'image'` says it.

The behaviour difference the issue asked to see: a skill file that cannot be read — it vanished between
the directory walk and the read — used to throw out of `readSkillFile` and be logged by the caller as a
read failure. It is now skipped through the shared `missing` / `error` state, which is the answer the
Files tab already gave for the same file.

Refs GoDiao#247
Copilot AI balanced review requested due to automatic review settings November 15, 2026 12:49

Copilot AI 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.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

@GoDiao GoDiao left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

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

Thanks, this is a clean refactor. The shared reader sits in the right place, both callers keep their limits, path containment still runs before the read, and previewType is gone everywhere. A few things to tidy before it goes in.

Should fix

1. An unreadable skill file is now skipped without a log. On main, a failed read threw out of readSkillFile, the catch at src/server/api/skills.ts:196 logged [Skills] Failed to read skill file, and the file was skipped. Now readFilePreview returns state: 'error', readSkillFile returns null (line 134), and buildFileTree hits if (!file) continue (line 191). Nothing reads preview.error. The file was skipped before and is skipped now, so the one real change is that the log is gone, which AGENTS.md's "Don't swallow errors" rule doesn't allow. Please log fullPath and preview.error when the state is error (missing can stay quiet), and add a test that an unreadable file is skipped.

2. WorkspacePanel.tsx still checks 'ok' on the file path. A file preview can no longer be 'ok'; only diff results are.

  • Line 594: state === 'text' || state === 'ok'. The 'ok' can't match, because a diff in state ok is handled at line 573 first.
  • Line 556: the 'ok' in isFileContent only makes contentMenu non-empty for a diff entry, and the diff branch doesn't use contentMenu.

Please drop 'ok' from both. While you're there, the copy-contents condition at line 773 can be entry?.content !== undefined, since only a text result carries content.

3. The desktop app still has two state unions. SkillFileState in desktop/src/types/skill.ts:24 is a hand-written subset of FilePreviewState in desktop/src/api/sessions.ts:245. Since this issue is about having one shape, please derive it instead, for example Exclude<FilePreviewState, 'missing' | 'error'>.

4. A design doc still names the old field. docs/features/ui-refresh/visual-refresh.zh.md:39 says the server marks each skill file with kind (text, image, binary, too_large). Please update it to state.

5. Two branches of readFilePreview aren't covered by the tests. I checked by changing the code and running bun test file-preview workspace-service skills:

  • Changing both stat.size > maxBytes to >= leaves all 64 tests passing, so the exact-limit boundary isn't tested. Please add a file of exactly maxBytes; it should come back as text with truncated: false in both modes.
  • Replacing the error message with a constant also leaves all 64 passing, so the error state isn't tested at all. Please add a case for it.

Notes

  • When stat itself fails with something other than ENOENT/ENOTDIR (e.g. EACCES), the Files tab error now starts with "Failed to read workspace file" instead of "Failed to stat workspace path". Nothing matches on the text, so this is fine.
  • The PR body's list of updated files leaves out src/server/api/skills.ts, which also changes its response field from kind to state.
  • No CHANGELOG entry is needed for this one; we'll add a line when it lands.

Log an unreadable skill file with its path before skipping it, drop the last 'ok'
comparisons from the workspace panel, derive SkillFileState from FilePreviewState on
both sides, name the state in the visual refresh document, and cover the exact-limit
and error branches.
@iruzen-dono

Copy link
Copy Markdown
Contributor Author

All five points are in 6b6be36, plus the two notes.

1. The log. readSkillFile now returns null on missing quietly and logs fullPath and preview.error on error before returning null, so the reason survives the skip. Test: skips a skill file it cannot read, and says so — creates a secret.txt, chmod 000, asserts it is absent from files and that console.error was called with the path. it.skipIf(platform === 'win32'), because chmod does not restrict reads there; CI runs it.

2. 'ok' in the panel. Gone from isFileContent and from the code branch. The copy-contents condition is now entry?.content !== undefined — state never entered that decision. Diff entries still carry content, but they take the isDiff branch, which does not build contentMenu at all, and isFileContent only gates isMarkdownFile/isCode, so nothing changes for them.

That change moved 10 fixtures: state: 'ok' became state: 'text' on every seeded preview entry and on the deferred file response. The 'ok' that remain are status and tree results, which keep their own vocabulary.

3. The type. SkillFileState = Exclude<FilePreviewState, 'missing' | 'error'>, in desktop/src/types/skill.ts and in the server's skills.ts — the latter narrows by the two early returns, so the assignment to state is checked rather than asserted.

4. Docs. visual-refresh.zh.md:39 says state now.

5. The two branches. Exact limit: a file of exactly maxBytes is text, truncated: false, in both refuse and truncate. Error: a path stat rejects with ERR_INVALID_ARG_VALUE (a NUL byte — cross-platform, unlike EACCES on Windows or an invalid name, which Linux reads as absence), returning state: 'error'.

PR body lists src/server/api/skills.ts now, and the checks section carries the current numbers: 155 pass / 0 fail / 1 skipped on the four server files, lint exit 0, desktop suite 2858 pass / 5 fail with those same 5 failing by name on a stashed tree (pages.test, LocalSlashCommandPanel, MessageList, UpdateChecker). No CHANGELOG entry, as you said.

@GoDiao GoDiao left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

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

Thanks @iruzen-dono, and welcome to DreamCoder! I should have said that on #250. All five points are in: the skipped skill file is logged again, the 'ok' checks are gone from the file path, SkillFileState is derived from FilePreviewState, the doc says state, and the limit and error cases are tested. I checked that the new skills test fails without the log and the limit test fails with >=, and ran the server and desktop suites for the touched files here. CI is green.

We'll add the CHANGELOG line on main after merging.

We'll be opening more features and issues soon, and you're very welcome to keep contributing. If you find DreamCoder useful, a star on the repo would be much appreciated.

@GoDiao
GoDiao merged commit 7600cfa into GoDiao:main Nov 15, 2026
4 checks passed
GoDiao added a commit that referenced this pull request Nov 15, 2026
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.

Share one file preview reader between the skill page and the Files tab

3 participants