nsaspy/zara-plugins
1
0
Fork 0
Code Issues 10 Pull requests 297 Projects Releases Packages Wiki Activity Actions

Add root-confined structured zara-files service #503

Open
nsaspy wants to merge 8 commits from rage/15-files into main
pull from: rage/15-files
merge into: nsaspy:main
Conversation 0 Commits 8 Files changed 8 +612 -1
nsaspy commented 2026-09-08 02:20:14 +00:00
Owner
Copy link

Implements #15.

TDD starts at 9f168daecf7d16df57093d7b6e4115339c222f24, which defines the root-confinement and mutation contract before implementation. The branch then merged canonical main after #60 so this candidate validates against the current browser-inclusive catalog.

zara-files exposes typed filename search, metadata, bounded UTF-8 reads, explicit create/copy/move/rename/delete, and an optional semantic-index boundary. No configured roots means file-roots-not-configured; there is no ambient home/filesystem fallback.

Adversarial filesystem behavior is explicit: absolute paths and .. traversal reject; configured roots may not be symlinks; existing path components and destination parents may not be symlinks; search never follows symlink directories/files; mutations never overwrite; directory deletion is absent from v1; binary/non-UTF-8 files stay metadata-first; root paths are represented by opaque root IDs in normal tool output.

Compatibility hardening found and fixed a real API bug: the initial files.metadata handler method shadowed Zara's required PluginMetadata class attribute. The handler is now file_metadata internally while the public tool remains files.metadata; the compatibility gate was strengthened to print expected/observed metadata type identity on future failures.

The domain library is stdlib-only so deterministic temporary-directory tests do not acquire Zara/LangChain dependencies. Zara Core remains authoritative for normal tool authorization/approval policy.

Candidate head: 7da26116bc5e88dd8580551f04ec5d7020e2bf86. Merge only after exact-head registry, unit, compatibility, Nix/package/runtime-layout gates and review/thread state are green.

Implements #15. TDD starts at `9f168daecf7d16df57093d7b6e4115339c222f24`, which defines the root-confinement and mutation contract before implementation. The branch then merged canonical main after #60 so this candidate validates against the current browser-inclusive catalog. `zara-files` exposes typed filename search, metadata, bounded UTF-8 reads, explicit create/copy/move/rename/delete, and an optional semantic-index boundary. No configured roots means `file-roots-not-configured`; there is no ambient home/filesystem fallback. Adversarial filesystem behavior is explicit: absolute paths and `..` traversal reject; configured roots may not be symlinks; existing path components and destination parents may not be symlinks; search never follows symlink directories/files; mutations never overwrite; directory deletion is absent from v1; binary/non-UTF-8 files stay metadata-first; root paths are represented by opaque root IDs in normal tool output. Compatibility hardening found and fixed a real API bug: the initial `files.metadata` handler method shadowed Zara's required `PluginMetadata` class attribute. The handler is now `file_metadata` internally while the public tool remains `files.metadata`; the compatibility gate was strengthened to print expected/observed metadata type identity on future failures. The domain library is stdlib-only so deterministic temporary-directory tests do not acquire Zara/LangChain dependencies. Zara Core remains authoritative for normal tool authorization/approval policy. Candidate head: `7da26116bc5e88dd8580551f04ec5d7020e2bf86`. Merge only after exact-head registry, unit, compatibility, Nix/package/runtime-layout gates and review/thread state are green.
refactor(files): expose opaque root ids
Some checks failed
CI / test (pull_request) Failing after 18s
Details
7da26116bc
Some checks failed
CI / test (pull_request) Failing after 18s
Details
This pull request has changes conflicting with the target branch.
  • plugins.json
  • plugins/zara-files/lib/zara_files/files.py
  • plugins/zara-files/lib/zara_files/plugin.py
  • scripts/zara_compat.py
View command line instructions

Manual merge helper

Use this merge commit message when completing the merge manually.

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u origin rage/15-files:rage/15-files
git switch rage/15-files

Merge

Merge the changes and update on Forgejo.

Warning: The "Autodetect manual merge" setting is not enabled for this repository, you will have to mark this pull request as manually merged afterwards.

git switch main
git merge --no-ff rage/15-files
git switch rage/15-files
git rebase main
git switch main
git merge --ff-only rage/15-files
git switch rage/15-files
git rebase main
git switch main
git merge --no-ff rage/15-files
git switch main
git merge --squash rage/15-files
git switch main
git merge --ff-only rage/15-files
git switch main
git merge rage/15-files
git push origin main
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels   
accessibility
Barrier affecting people with disabilities

  
bug
Something isn't working

  
documentation
Improvements or additions to documentation

  
duplicate
This issue or pull request already exists

  
enhancement
New feature or request

  
good first issue
Good for newcomers

  
help wanted
Extra attention is needed

  
invalid
This doesn't seem right

  
question
Further information is requested

  
security

   
wontfix
This will not be worked on

No labels
accessibility
bug
documentation
duplicate
enhancement
good first issue
help wanted
invalid
question
security
wontfix
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
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
nsaspy/zara-plugins!503
No description provided.