Skip to content

feat(mount): add _index.json everywhere + LAYOUT.md (issue #106 PR 1)#116

Merged
khaliqgant merged 1 commit intomainfrom
feat/106-mount-indexes-and-layout
May 9, 2026
Merged

feat(mount): add _index.json everywhere + LAYOUT.md (issue #106 PR 1)#116
khaliqgant merged 1 commit intomainfrom
feat/106-mount-indexes-and-layout

Conversation

@khaliqgant
Copy link
Copy Markdown
Member

Part 1 of 3 from #106. Additive, low-risk.

Adds:

  • _index.json in every materialized mount directory containing a
    compact list of { id, title|name, updated } rows so agents can
    do "find by title" in two reads instead of N.
  • LAYOUT.md (a.k.a. SKILL.md) at the mount root teaching agents
    the structure on first look.

No existing files are renamed or moved. Symlinks / by-title / by-id
aliases land in PR 2 (#106). State-grouped views + lazy GH land in PR 3.

See #106 for benchmark motivation.

Repo scope

This PR is the relayfile part of wave wave1-indexes. The
companion PRs in the other repos are linked from issue #106.

Test plan

Generated by an overnight agent run. See
/tmp/106-wave1-indexes-status.md on the host for triage notes.

Refs #106

@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented May 9, 2026

Review Change Stack
No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 94f07412-6c52-46c9-9a90-3b88ce25c1ae

📥 Commits

Reviewing files that changed from the base of the PR and between 4481a13 and 602744c.

📒 Files selected for processing (6)
  • internal/mountfuse/fs.go
  • internal/mountfuse/fuse_test.go
  • internal/mountfuse/layout.go
  • internal/mountfuse/layout_test.go
  • internal/mountsync/syncer.go
  • internal/mountsync/syncer_test.go
✅ Files skipped from review due to trivial changes (2)
  • internal/mountsync/syncer.go
  • internal/mountfuse/fuse_test.go
🚧 Files skipped from review as they are similar to previous changes (4)
  • internal/mountfuse/layout.go
  • internal/mountfuse/layout_test.go
  • internal/mountfuse/fs.go
  • internal/mountsync/syncer_test.go

📝 Walkthrough

Walkthrough

This PR introduces a virtual LAYOUT.md file synthesized at the FUSE filesystem root. The change includes embedded markdown content, path detection helpers, FUSE integration to serve the virtual file, comprehensive FUSE tests, syncer documentation clarifying file preservation, and syncer-level integration tests.

Changes

Virtual LAYOUT.md Feature

Layer / File(s) Summary
Layout Content & Constants
internal/mountfuse/layout.go
Defines embedded LayoutMarkdown constant and helpers: layoutRemotePath() computes the path, isVirtualLayoutPath() detects requests for it, virtualLayoutMeta() generates read-only file metadata, and readVirtualLayout() returns a RemoteFile with markdown content.
FUSE Filesystem Integration
internal/mountfuse/fs.go
listDirectory appends a virtual layout entry when at root; lookupMetadata and readFile short-circuit on virtual layout paths, returning virtual metadata/content directly and bypassing remote FS operations.
FUSE Layout Tests
internal/mountfuse/layout_test.go
Introduces layoutRemoteClient test double; validates LayoutMarkdown contains required anchors; verifies root directory synthesis, lookup/read attributes, and that virtual content is returned without triggering remote reads; confirms virtual content takes precedence over colliding remote files.
Test Signature Update
internal/mountfuse/fuse_test.go
Existing FUSE test expectation updated to include "LAYOUT.md" in root directory listing.
Syncer Clarification
internal/mountsync/syncer.go
Inline comment in applyRemoteFile clarifies that _index.json and nested .layout.md dotfiles are first-class remote payloads not subject to normalization filters.
Syncer Index & Layout Tests
internal/mountsync/syncer_test.go
Four tests validate: applyRemoteFile writes index and layout files with correct content/hashes; applyRemoteSnapshot preserves nested layout dotfiles alongside index files; applyWebSocketEvent updates layout files with exactly one remote read.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related issues

Possibly related PRs

Poem

🐰 A layout file springs to life,
Virtual as dreams, without strife,
FUSE roots sing with markdown grace,
While syncers guard each nested place. ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed The title accurately describes the main changes: adding _index.json files and LAYOUT.md to the mount system, with clear reference to issue #106.
Description check ✅ Passed The description clearly explains the purpose, scope, and test plan for the PR, relating directly to the changeset covering _index.json and LAYOUT.md additions.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feat/106-mount-indexes-and-layout

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Copy Markdown

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

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

Actionable comments posted: 2

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
.trajectories/index.json (1)

9-136: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Avoid absolute local paths in committed trajectory registry.

These /Users/khaliqgant/... paths are machine-specific and leak a local identifier. Prefer repository-relative paths (for portability and privacy hygiene).

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.trajectories/index.json around lines 9 - 136, The committed .trajectories
index contains absolute local file paths (e.g., the "path" values under entries
like "traj_7x9nltybo08h", "traj_82lywlk9dcnc", etc.) which leak machine-specific
info; update each trajectory object's "path" field to a repository-relative path
(for example ".trajectories/completed/2026-04/traj_7x9nltybo08h.json") and
ensure any code that reads/writes these values uses path joining (not hardcoded
absolute paths) so the registry is portable and free of local user identifiers.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.trajectories/completed/2026-05/traj_pfjtlq9sb0ps.json:
- Line 19: The committed metadata contains a machine-specific absolute path in
the JSON key "projectId"; replace that value in the file entry where "projectId"
is set so it no longer contains a local absolute path (e.g.,
"/Users/khaliqgant/..."). Update the "projectId" value to a portable identifier
such as a relative path, repository name, project slug, or a canonical UUID
(whatever the project convention uses) and commit the change so no username or
local filesystem paths are stored.

In @.trajectories/index.json:
- Around line 5-10: Update the registry entry for traj_rbaf01z4kt7g: change
"status" from "active" to "completed", add a "completedAt" timestamp (use the
completed report's timestamp or the commit time), and update the "path" value to
the completed report path ".trajectories/completed/2026-05/traj_rbaf01z4kt7g.md"
so index consumers see the run as finished.

---

Outside diff comments:
In @.trajectories/index.json:
- Around line 9-136: The committed .trajectories index contains absolute local
file paths (e.g., the "path" values under entries like "traj_7x9nltybo08h",
"traj_82lywlk9dcnc", etc.) which leak machine-specific info; update each
trajectory object's "path" field to a repository-relative path (for example
".trajectories/completed/2026-04/traj_7x9nltybo08h.json") and ensure any code
that reads/writes these values uses path joining (not hardcoded absolute paths)
so the registry is portable and free of local user identifiers.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 28019845-e3e6-4473-96c4-e51d8a3fcf9c

📥 Commits

Reviewing files that changed from the base of the PR and between c8ef4d5 and 97ab087.

📒 Files selected for processing (12)
  • .trajectories/active/traj_rbaf01z4kt7g.json
  • .trajectories/completed/2026-05/traj_pfjtlq9sb0ps.json
  • .trajectories/completed/2026-05/traj_pfjtlq9sb0ps.md
  • .trajectories/completed/2026-05/traj_rbaf01z4kt7g.json
  • .trajectories/completed/2026-05/traj_rbaf01z4kt7g.md
  • .trajectories/index.json
  • internal/mountfuse/fs.go
  • internal/mountfuse/fuse_test.go
  • internal/mountfuse/layout.go
  • internal/mountfuse/layout_test.go
  • internal/mountsync/syncer.go
  • internal/mountsync/syncer_test.go

},
"commits": [],
"filesChanged": [],
"projectId": "/Users/khaliqgant/Projects/AgentWorkforce/relayfile",
Copy link
Copy Markdown

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Remove machine-specific absolute path from committed metadata.

projectId currently exposes a local absolute path (including username), which leaks workstation-specific information and makes the artifact non-portable.

🔧 Proposed fix
-  "projectId": "/Users/khaliqgant/Projects/AgentWorkforce/relayfile",
+  "projectId": "AgentWorkforce/relayfile",
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
"projectId": "/Users/khaliqgant/Projects/AgentWorkforce/relayfile",
"projectId": "AgentWorkforce/relayfile",
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.trajectories/completed/2026-05/traj_pfjtlq9sb0ps.json at line 19, The
committed metadata contains a machine-specific absolute path in the JSON key
"projectId"; replace that value in the file entry where "projectId" is set so it
no longer contains a local absolute path (e.g., "/Users/khaliqgant/..."). Update
the "projectId" value to a portable identifier such as a relative path,
repository name, project slug, or a canonical UUID (whatever the project
convention uses) and commit the change so no username or local filesystem paths
are stored.

Comment thread .trajectories/index.json Outdated
Comment on lines +5 to +10
"traj_rbaf01z4kt7g": {
"title": "106-mount-layout-improvements-workflow",
"status": "active",
"startedAt": "2026-04-30T16:53:07.629Z",
"path": "/Users/khaliqgant/Projects/AgentWorkforce/relayfile/.trajectories/active/traj_mfyus7zfgxt2.json"
"startedAt": "2026-05-08T22:58:04.332Z",
"path": "/Users/khaliqgant/Projects/AgentWorkforce/relayfile/.trajectories/active/traj_rbaf01z4kt7g.json"
},
Copy link
Copy Markdown

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

traj_rbaf01z4kt7g registry state is inconsistent with completed artifact.

Line 7 marks this trajectory as active, but the PR adds a completed report at .trajectories/completed/2026-05/traj_rbaf01z4kt7g.md. Please finalize this entry (status, completedAt, and completed-path target) so index consumers don’t treat a finished run as in-progress.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.trajectories/index.json around lines 5 - 10, Update the registry entry for
traj_rbaf01z4kt7g: change "status" from "active" to "completed", add a
"completedAt" timestamp (use the completed report's timestamp or the commit
time), and update the "path" value to the completed report path
".trajectories/completed/2026-05/traj_rbaf01z4kt7g.md" so index consumers see
the run as finished.

Copy link
Copy Markdown
Contributor

@devin-ai-integration devin-ai-integration Bot left a comment

Choose a reason for hiding this comment

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

Devin Review found 1 potential issue.

View 4 additional findings in Devin Review.

Open in Devin Review

return nodeMeta{
path: layoutRemotePath(remoteRoot),
name: layoutFilename,
mode: syscall.S_IFREG | defaultFileMode,
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🟡 Virtual LAYOUT.md is writable (0o644) but all write/delete operations will fail with confusing errors

The virtual LAYOUT.md file is created with defaultFileMode (0o644) at internal/mountfuse/layout.go:53, making it appear writable to the kernel and user. However, no guards exist in the Unlink (internal/mountfuse/dir.go:133-158) or flush (internal/mountfuse/file.go:209-247) paths to reject mutations on the virtual file. When a user or agent tries to delete (rm LAYOUT.md) or write to the file, the operation proceeds to call DeleteFile/WriteFile on the remote server with the fake revision "virtual-layout", which will fail with a confusing EIO or EPERM errno. In the write case, a user's edits appear to succeed (buffer writes work) but are silently lost when flush fails on close. The file should use read-only mode (0o444) so the FUSE kernel rejects writes/deletes before they reach the handlers.

Suggested change
mode: syscall.S_IFREG | defaultFileMode,
mode: syscall.S_IFREG | 0o444,
Open in Devin Review

Was this helpful? React with 👍 or 👎 to provide feedback.

@khaliqgant khaliqgant force-pushed the feat/106-mount-indexes-and-layout branch from 97ab087 to 4481a13 Compare May 9, 2026 09:04
@khaliqgant khaliqgant force-pushed the feat/106-mount-indexes-and-layout branch from 4481a13 to 054a40a Compare May 9, 2026 09:35
Adds the virtual LAYOUT.md file at mount root (read-only 0o444) with
LayoutMarkdown anchor coverage, plumbs isVirtualLayoutPath through
listDirectory/lookupMetadata/readFile so the synthesized entry bypasses
remote calls. Documents that _index.json files and per-integration
.layout.md dotfiles are first-class remote payloads in mountsync, and
covers the apply path in TestApplyRemoteFile_IndexAndLayoutFiles.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@khaliqgant khaliqgant force-pushed the feat/106-mount-indexes-and-layout branch from 054a40a to 602744c Compare May 9, 2026 09:43
@khaliqgant khaliqgant merged commit eb03c44 into main May 9, 2026
7 checks passed
@khaliqgant khaliqgant deleted the feat/106-mount-indexes-and-layout branch May 9, 2026 09:47
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.

1 participant