xonecas.io
8356
Wx

www-xonecas-io / files

www-xonecas-io / tickets / 1008-build-the-read-only-file-browser-with-syntax.md

3.9 KB
1---
2id: 1008
3title: Build the read-only file browser with syntax highlighting
4type: feature
5status: done
6priority: p2
7area: site
8created: 2026-11-07T19:30:00Z
9updated: 2026-11-08T04:02:06Z
10source: agent
11moves: 2026-11-07T19:30:00Z inbox todo agent; 2026-11-08T01:09:41Z todo doing drag; 2026-11-08T01:38:14Z doing blocked agent; 2026-11-08T01:42:28Z blocked todo note; 2026-11-08T01:42:31Z todo doing drag; 2026-11-08T02:08:13Z doing review agent; 2026-11-08T04:02:06Z review done drag
12---
13
14Browse directories and view files on the default branch, with syntax highlighting and line anchors.
15
16Binary and very large files show a placeholder and their size, not their content. Some repos carry big vendored trees: startsInvasion has 610 files, Zoea-Nova 534.
17
18Needs from xonecas: default branch only, or all branches and tags? I recommend default only to start, because static output grows with every ref.
19
20Done when: every file link in a repo resolves, and a binary file does not break the build.
21
22## Notes
23
24- 2026-11-08 01:38Z (agent): Blocked: one question before I start. Default branch only, or all branches and tags?
25  
26  - Default branch only (recommended): one tree per project. Measured: 81 projects have about 3,900 files on HEAD, so it stays small and fast.
27  - All branches and tags: every ref multiplies the output, and the URLs need a ref segment (/tree/<ref>/<path>). I can add that later without breaking default-branch URLs if I keep the default at /tree/<path>.
28  
29  The URLs are already set by 1007: /projects/<name>/tree/<path>/, /projects/<name>/blob/<path>/ and /projects/<name>/raw/<path>. Links from READMEs and the root tree already point there and 404 until this lands.
30
31- 2026-11-08 01:39Z (agent): Correction: I wrote 'about 3,900 files' before measuring. The 81 shown projects have 3,954 files on HEAD (from data/projects.json).
32
33- 2026-11-08 01:42Z (human): main branch only for now.
34
35- 2026-11-08 02:08Z (agent): Done, default branch only as you said: every folder has a page at /projects/<name>/tree/<path>/ and every file at /projects/<name>/blob/<path>/. Files are highlighted with line numbers, and each number links to itself (#L20 highlights line 20). Screenshots are attached.
36  
37  - Folders list contents with each entry's last commit, folders first, with a breadcrumb back up. One 'git log --name-only' per repo finds the last commit for every path, which also replaced the per-entry git calls on the project page.
38  - Files over 256 KB show 'Too big to show.' with their size: 57 files, mostly wasm, GIFs and generated parsers (tiny-c-agent's 8.7 MB parser.c). Binary files (a NUL byte or invalid UTF-8) show 'Binary file, not shown.' with their size. Nothing outside the default branch is built.
39  - Highlighting uses chroma's lexers, but only 10 token kinds get a colour (keywords, strings, numbers, comments, functions and similar), with my own line markup. That took the 3,996 file pages from 165 MB to 63 MB. Code sits in the dark block in both themes.
40  - Rebuilds: a project's file pages are rebuilt only when its HEAD or the site program changes. A rebuild starts that project's tree/ and blob/ over, so deleted files go too.
41  
42  NUMBERS: 3,951 files and 1,000+ folders across 81 projects. public/ is now 200 MB in all (file pages 63 MB, commit pages 109 MB). Full build 1m10s to 1m40s on the VM. Rebuild with nothing changed: 4.2s.
43  
44  CHECKED: go test (folder pages, a binary placeholder, line anchors). Every internal link on every page in public/: 76,982 links, all resolving. The only miss is a README's protocol-relative //xonecas.com link, which is external. Screenshots: light, dark, phone, the anchor, the too-big placeholder.
45  NOT CHECKED: highlighting quality per language. Lexers come from file names only, so odd extensions show as plain text. No raw download for files: the ticket asks for placeholders, and raw/ only holds README images (1007).
46
47- 2026-11-08 02:08Z (agent): Measured after writing: 1,023 folder pages.