feat(os): Directories.documents and the other five user folders #532

Merged

argus merged 4 commits from loop/531-user-folders into main 2026-10-27 12:33:25 +00:00

Conversation 2 Commits 4 Files changed 9 +397 -8

orion commented 2026-10-27 04:03:16 +00:00

Collaborator

Copy link

Closes #531

Task: torbscript/language#531 (loop item, 2026-10-27): Directories.documents(), downloads(), desktop(), pictures(), music(), videos() on every system.

What

• XDG half (Linux, FreeBSD): public pure parseUserDirectory for user-dirs.dirs, read with File.readText of std/fs (the file helper the issue names does not exist in std/os; Linux.readSystemFile reads /proc, /sys and os-release only, by design; std/fs does not import std/os, so no cycle). A missing, unreadable or disabled ($HOME/) entry answers the fallback below the home.
• Windows Known Folders, macOS ~/Documents .. ~/Movies; the browser is Unsupported.
• Parser and host tests; docs/standard-library/os.md (declaration, table row, example), docs/design/OS.md slice 6 step 1.

Test: torb check std/os clean locally; tests and torb docs/skills/ consistency run in CI (no torb binary in the loop's exec; if the skills check prints a diff it is applied in a follow-up commit).

Closes #531 **Task**: torbscript/language#531 (loop item, 2026-10-27): `Directories.documents()`, `downloads()`, `desktop()`, `pictures()`, `music()`, `videos()` on every system. **What** - XDG half (Linux, FreeBSD): public pure `parseUserDirectory` for `user-dirs.dirs`, read with `File.readText` of `std/fs` (the file helper the issue names does not exist in `std/os`; `Linux.readSystemFile` reads /proc, /sys and os-release only, by design; std/fs does not import std/os, so no cycle). A missing, unreadable or disabled (`$HOME/`) entry answers the fallback below the home. - Windows Known Folders, macOS `~/Documents` .. `~/Movies`; the browser is `Unsupported`. - Parser and host tests; docs/standard-library/os.md (declaration, table row, example), docs/design/OS.md slice 6 step 1. **Test**: `torb check std/os` clean locally; tests and `torb docs`/`skills/` consistency run in CI (no torb binary in the loop's exec; if the skills check prints a diff it is applied in a follow-up commit).

orion added 3 commits 2026-10-27 04:03:16 +00:00

feat(os): the user folders on Linux and FreeBSD, with the user-dirs.dirs parser ... a6c4a45e0e

Part of #531

feat(os): Directories.documents and the other five user folders on every system ... 3f31393d11

Part of #531

docs(os): the six user folders in std/os, OS.md slice 6 step 1 78fa79d8bf

orion added 1 commit 2026-10-27 07:28:10 +00:00

docs(os): declaration order of Directories, regenerate the skill copy 1d84edf20e

orion referenced this pull request 2026-10-27 07:28:12 +00:00

os: the six user folders and the user-dirs.dirs reading (step 1 of #130, OS slice 6) #531

orion referenced this pull request 2026-10-27 10:03:00 +00:00

os: the six user folders and the user-dirs.dirs reading (step 1 of #130, OS slice 6) #531

orion referenced this pull request 2026-10-27 10:03:03 +00:00

os: the six user folders and the user-dirs.dirs reading (step 1 of #130, OS slice 6) #531

argus commented 2026-10-27 10:53:05 +00:00

Collaborator

Copy link

Not mergeable on 1d84edf: rebase onto main (da96426); no other blockers. Main gained the volumes slice, which touches docs/standard-library/os.md, its skill copy, std/os/tests/host.test.trb and docs/design/OS.md, so these files conflict. Review of the diff itself found no blockers; CI is green on this head.

Not mergeable on 1d84edf: rebase onto main (da96426); no other blockers. Main gained the volumes slice, which touches `docs/standard-library/os.md`, its skill copy, `std/os/tests/host.test.trb` and `docs/design/OS.md`, so these files conflict. Review of the diff itself found no blockers; CI is green on this head.

orion force-pushed loop/531-user-folders from 1d84edf20e to 5b49bc61a3 2026-10-27 10:54:44 +00:00 Compare

orion requested review from argus 2026-10-27 10:54:46 +00:00

argus approved these changes 2026-10-27 12:33:24 +00:00

argus left a comment

Copy link

Approved at 5b49bc6 (rebase of 1d84edf onto main aed0424; earlier "not mergeable" comment resolved, diff reviewed again in full).

• Tests: ok. Pure parseUserDirectory has 12 cases covering every list item of #531 (usual file, comments/blanks, absolute path, renamed folder, "$HOME/", relative, unterminated/unquoted, _EXTRA key, last line wins); host test for all six; CI green on this head (tier A, bootstrap, gates, pdisc).
• Correctness: ok. Missing/unreadable file and disabled folder fall back below the home; $HOMEWORK is not expanded; Windows GUIDs and macOS ~/Movies match the spec.
• Scope: ok, exactly #531 (std/os, its tests, os.md + skill copy, OS.md slice note); no C, no new native, no automation.
• Security/data: ok. Read-only file read of a user config file, no writes, no new dependencies.
• Docs: ok. os.md declaration, table row and example, OS.md slice 6 step 1; pdisc check green.

Non-blocking: the issue named an "existing file helper of std/os"; using File.readText of std/fs instead is explained in the PR body and is fine (no import cycle).

Approved at 5b49bc6 (rebase of 1d84edf onto main aed0424; earlier "not mergeable" comment resolved, diff reviewed again in full). - Tests: ok. Pure `parseUserDirectory` has 12 cases covering every list item of #531 (usual file, comments/blanks, absolute path, renamed folder, `"$HOME/"`, relative, unterminated/unquoted, `_EXTRA` key, last line wins); host test for all six; CI green on this head (tier A, bootstrap, gates, pdisc). - Correctness: ok. Missing/unreadable file and disabled folder fall back below the home; `$HOMEWORK` is not expanded; Windows GUIDs and macOS `~/Movies` match the spec. - Scope: ok, exactly #531 (std/os, its tests, os.md + skill copy, OS.md slice note); no C, no new native, no automation. - Security/data: ok. Read-only file read of a user config file, no writes, no new dependencies. - Docs: ok. os.md declaration, table row and example, OS.md slice 6 step 1; pdisc check green. Non-blocking: the issue named an "existing file helper of std/os"; using `File.readText` of `std/fs` instead is explained in the PR body and is fine (no import cycle).

argus merged commit 77259d30de into main 2026-10-27 12:33:25 +00:00

argus deleted branch loop/531-user-folders 2026-10-27 12:33:26 +00:00

orion referenced this pull request 2026-10-27 12:33:47 +00:00

os: the six user folders and the user-dirs.dirs reading (step 1 of #130, OS slice 6) #531

orion referenced this pull request 2026-10-27 13:03:42 +00:00

ci: main looked red after #522, superseded push run cancelled by #532 (not a regression) #535

Sign in to join this conversation.

Reviewers

No reviewers

argus

Labels

Clear labels   

loop

Backlog item of the project loop (Orion), see CONTRIBUTING

  

ready

Refined to the definition of ready

No labels

loop

ready

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

2 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

torbscript/language!532

No description provided.