fix: clean up ~/.devsy on-disk schema drift

[skevetter]

Summary

Fixes six correctness bugs and one documentation gap in devsy's on-disk state directory (~/.devsy, aka DEVSY_HOME) that let files accumulate without cleanup and let paths drift from the central PathManager abstraction:

• Routes the provider-version cache through PathManager.CacheDir() instead of a hand-rolled path that landed it in the wrong root.
• devsy machine delete and devsy context delete now actually remove their on-disk directories (previously only provider delete and pro logout did this correctly).
• Adds an orphan sweep for the contents/ tree, alongside the existing sweep for workspaces/.
• Makes candidateAgentDirs() honor $DEVSY_HOME instead of always probing the raw OS home directory.
• Stamps a SchemaVersion into config.yaml and documents the canonical on-disk layout on PathManager, giving future layout changes a baseline to migrate from.

Each task was implemented and reviewed independently (spec compliance + code quality), followed by a whole-branch review and a comment-accuracy pass. One whole-branch finding is worth calling out explicitly: the candidateAgentDirs() fix (commit 10d5a892) is correct and defensive, but turned out to be unreachable from both production callers today — findDir already short-circuits on $DEVSY_HOME before ever reaching that function. It hardens against a future caller that bypasses findDir, but does not change current observable behavior.

A CodeRabbit pass on the branch surfaced two findings; both were verified against the code and are false positives (details in the review thread if useful, not included here since neither required a change).

Not in scope (documented as follow-up)

• Full agent-side/host-side directory tree unification (only the $DEVSY_HOME-blindness half is fixed here).
• Cache TTL/eviction (no prune/gc command exists yet to build on).
• A migration for the provider-version cache file's old (pre-fix) location — low-harm, regenerable with a 6h TTL.

Summary by CodeRabbit

• New Features

  • Added automatic cleanup of local context and machine files after deletion.
  • Removed orphaned workspace content during workspace deletion.
  • Added configuration schema version tracking for safer future upgrades.
  • Respected the configured Devsy home for agent workspace locations.

• Bug Fixes

  • Standardized provider version cache placement.
  • Improved handling of missing directories during cleanup.

• Documentation

  • Documented the managed filesystem layout.

[netlify]

✅ Deploy Preview for images-devsy-sh canceled.

Name	Link
🔨 Latest commit	bfce560
🔍 Latest deploy log	https://app.netlify.com/projects/images-devsy-sh/deploys/6a73f776e1c4b900080d235e

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR versions on-disk configuration, centralizes provider cache paths, updates agent directory resolution, and removes stale context, machine, and workspace content directories after deletion operations.

Changes

Filesystem layout and cleanup

Layer / File(s)	Summary
Configuration and path contracts pkg/config/config.go, pkg/config/config_test.go, pkg/config/pathmanager.go, pkg/provider/version_cache.go, pkg/provider/version_cache_test.go	Configurations now store SchemaVersion. Legacy zero versions are normalized. Provider caches use PathManager.CacheDir().
Agent home resolution pkg/agent/workspace.go, pkg/agent/workspace_test.go	Agent discovery uses $DEVYS_HOME/agent when DEVYS_HOME is set.
Context and machine directory cleanup cmd/context/delete.go, cmd/context/delete_test.go, cmd/machine/delete.go, cmd/machine/delete_test.go	Context deletion removes the context directory. Machine deletion removes the local machine directory after remote deletion succeeds.
Workspace orphan cleanup pkg/workspace/delete.go, pkg/workspace/delete_test.go	Workspace deletion removes content directories without matching workspace directories and preserves matching content.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related PRs

• devsy-org/devsy#74: Both changes use PathManager for centralized filesystem paths.
• devsy-org/devsy#830: Both changes update workspace deletion cleanup for orphaned content directories.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 11.11% 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
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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the pull request's main goal of correcting on-disk state cleanup and schema drift under ~/.devsy.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[netlify]

✅ Deploy Preview for devsydev canceled.

Name	Link
🔨 Latest commit	bfce560
🔍 Latest deploy log	https://app.netlify.com/projects/devsydev/deploys/6a73f77634f1b900082d5452

[coderabbitai]

🧹 Nitpick comments (1)

pkg/provider/version_cache_test.go (1)

34-38: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Reset the path manager in this test.

SaveProviderVersionCache initializes config.DefaultPathManager() with this temporary DEVSY_HOME. The singleton remains bound to that directory after t.Setenv restores the environment. Reset it before setup and during cleanup.

Proposed change

 func TestCacheRoundtrip(t *testing.T) {
+	config.ResetPathManager()
+	t.Cleanup(config.ResetPathManager)
 	dir := t.TempDir()
 	t.Setenv("DEVSY_HOME", dir)

🤖 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 `@pkg/provider/version_cache_test.go` around lines 34 - 38, Reset the singleton
returned by config.DefaultPathManager() before setting up the temporary
DEVSY_HOME and again during test cleanup, so SaveProviderVersionCache binds to
the test directory and does not leak state across tests. Update the test
containing the wantPath assertion and use the path-manager reset mechanism
already provided by the config package.

🤖 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.

Nitpick comments:
In `@pkg/provider/version_cache_test.go`:
- Around line 34-38: Reset the singleton returned by config.DefaultPathManager()
before setting up the temporary DEVSY_HOME and again during test cleanup, so
SaveProviderVersionCache binds to the test directory and does not leak state
across tests. Update the test containing the wantPath assertion and use the
path-manager reset mechanism already provided by the config package.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: c625ac10-50e0-4420-8f72-ea644171073a

📥 Commits

Reviewing files that changed from the base of the PR and between 9934342 and d45fa8d.

📒 Files selected for processing (13)

• cmd/context/delete.go
• cmd/context/delete_test.go
• cmd/machine/delete.go
• cmd/machine/delete_test.go
• pkg/agent/workspace.go
• pkg/agent/workspace_test.go
• pkg/config/config.go
• pkg/config/config_test.go
• pkg/config/pathmanager.go
• pkg/provider/version_cache.go
• pkg/provider/version_cache_test.go
• pkg/workspace/delete.go
• pkg/workspace/delete_test.go