feat: XDG directory layout via VpDirs by forehalo · Pull Request #2346 · voidzero-dev/vite-plus

forehalo · 2026-08-05T13:06:23Z

Close #827

Summary

Centralize on-disk paths in vp_shared::VpDirs and default fresh installs to the split XDG/platform layout. Existing default installs under ~/.vite-plus remain on the legacy monolithic root for now (grandfathered via existence-gated resolution). Automatic layout migration is out of scope here and tracked as follow-up work.

Resolution (high level)

Ordered sources (per category): deprecated VP_HOME (custom full-root pin) → existing ~/.vite-plus / ./.vite-plus (exist-gated legacy mapping) → VP_BIN_DIR / VP_DATA_DIR / VP_CACHE_DIR → XDG_* → platform defaults.

Category	Split default (Unix)	Legacy (`~/.vite-plus`)
bin	`~/.local/bin`	`<root>/bin`
data	`~/.local/share/vite-plus`	`<root>`
cache	`~/.cache/vite-plus`	`<root>/cache`
config	`~/.config/vite-plus`	`<root>`
state	`~/.local/state/vite-plus`	`<root>`

Windows split uses %LOCALAPPDATA%\vite-plus\{bin,data,cache,state} and %APPDATA%\vite-plus for config. Relative VP_* / XDG_* values are treated as unset.

Commits (review order)

docs(rfc): document split directory layout via VpDirs
- Adds rfcs/directory-layout.md describing the resolution chain, grandfathering, installer alignment, and follow-ups (VP_HOME cleanup, migrate-on-upgrade).
- Historical RFCs (e.g. env-command.md) are left unchanged.
feat(shared): introduce VpDirs with strategy-gated path resolution
- Replaces get_vp_home / home.rs with VpDirs + dirs/resolution.rs strategy chain.
- Category roots and first-level data subdirs only; deeper paths stay with owning features.
- Wires EnvConfig / env vars so tests isolate layout via test_guard / for_test_with_home without process-env leaks.
- Updates AGENTS.md pointer to the central path API.
refactor: migrate call sites from get_vp_home to VpDirs
- Migrates global CLI, shims, js_runtime, package manager, implode, env setup/doctor, and related helpers onto VpDirs.
- Under the split layout, injects VP_BIN_DIR / VP_DATA_DIR / VP_CACHE_DIR into JS children when unset; hooks / org-tarball honor those roots.
- Snapshot runner and fixtures provision a full legacy on-disk shape and pin install roots explicitly (no binary PATH self-location in VpDirs).
- CI bootstrap seeds ~/.vite-plus before bootstrap-cli so existing snapshot/e2e paths keep finding the global binary until layout cleanup lands.
feat(install): default installers to the split XDG layout
- install.sh / install.ps1 / vp-setup / trampoline / Dockerfile / install-global-cli share the same resolution chain as the CLI.
- Fresh install → split; existing ~/.vite-plus or explicit VP_HOME / --install-dir → legacy monolithic root.
- Installer env docs (VP_HOME deprecated) and standalone-install CI coverage for split + legacy upgrade/implode.

User impact

Install	Impact
Existing `~/.vite-plus`	Unchanged path (grandfathered until migrate follow-up)
Custom `VP_HOME`	Still works (deprecated pin)
Fresh	Split layout; typically only `~/.local/bin` needs to be on PATH

Follow-up

chore: remove remaining VP_HOME usage (especially snapshot tests) #2371 — Clean remaining VP_HOME usage in the repo (especially PTY snapshot tests); prefer VP_*_DIR / XDG
feat: migrate ~/.vite-plus into split VP_*/XDG dirs on vp upgrade #2372 — On vp upgrade, migrate default ~/.vite-plus contents into split VP_*_DIR / XDG_* / platform dirs and remove the legacy root

Test plan

cargo check / unit tests for dirs resolution and layout helpers
Snapshot fixtures adapted for layout isolation (pin VP_HOME / disable shared seed where fakes are used)
Installer unification (single install.sh / install.ps1)
Formatting for RFC + install-global-cli
Windows unit test: uninstall removes shims under for_test_with_home bin mapping
CI: test-standalone-install (released + local split/legacy-upgrade jobs)
Manual: fresh install lands on split paths; existing ~/.vite-plus still works without moving

netlify · 2026-08-05T13:06:29Z

✅ Deploy Preview for viteplus-preview canceled.

Name	Link
🔨 Latest commit	`5cc3b6c`
🔍 Latest deploy log	https://app.netlify.com/projects/viteplus-preview/deploys/6a796abcd9307e0008349cdb

fengmk2 · 2026-08-07T03:13:54Z

@liangmiQwQ Your refactor needs to wait until this merge is completed first, as the changes are expected to be quite significant.

socket-security · 2026-08-07T09:30:52Z

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	cargo/temp-env@0.3.6

View full report

fengmk2 · 2026-08-07T12:35:38Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ca9dcca689

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

liangmiQwQ · 2026-08-07T12:53:56Z

IMO, I would be a little bit curious about the benefit for this move. The current VP_HOME layout has been working well, the similar single-root approaches are also used by tools like Cargo, Bun, and Volta. Moving to a new layout is not a low-cost change: it affects existing installations, upgrade paths, user workflows, and debugging. For a released tool, I think we should carefully evaluate the trade-offs.

For example, I help maintain the Vite+'s global package installations in several, I'm concerned that using ~/.local/bin may introduce heavier binary conflicts and overlapping issues. I'm not sure if ~/.local/bin, a public bin location, should be managed (even partially) by Vite+.

I'm not against this direction, I just want to understand the motivation and the problem it solves. If it does help Vite+ improve, then now is really a good time to implement it (before RC).

fengmk2 · 2026-08-10T01:12:05Z

@liangmiQwQ Following the XDG directory convention will allow Vite+ to be more widely accepted, and many mature developer tools follow this convention, such as Claude Code and uv astral-sh/uv#8420

Capture the resolution design, grandfathering of existing ~/.vite-plus installs, installer alignment, and follow-ups for VP_HOME cleanup and migrate-on-upgrade.

Replace get_vp_home / the monolithic home module with VpDirs: category roots (bin, data, cache, config, state) come from an ordered resolution chain in dirs/resolution.rs (legacy Exist-gated grandfathering, VP_* and XDG Set overrides, then platform defaults), and first-level data subdirs (current, js_runtime, package_manager, packages, bins) are pure joins. Files and deeper trees stay with their features. Wire EnvConfig so test_guard/for_test_with_home isolate install roots without process-env leaks. Groundwork for voidzero-dev#827.

Switch global CLI, shims, js_runtime, package_manager, and related helpers off the old home path helpers onto VpDirs. Inject VP_BIN_DIR/VP_DATA_DIR/ VP_CACHE_DIR into JS children under the split layout; teach hooks and org-tarball to honor those roots. implode, env setup/doctor, and snapshot fixtures understand split vs legacy layouts without binary self-location (pin VP_HOME / isolated roots explicitly in tests).

Fresh installs land versions under the data dir and shims under the bin dir (XDG/platform defaults via VpDirs). install.sh, install.ps1, vp-setup, Dockerfile, trampoline, and install-global-cli follow the same resolution chain as the CLI; an existing ~/.vite-plus or explicit VP_HOME/--install-dir keeps the legacy monolithic root. Document the installer env surface (VP_HOME deprecated) and cover split plus legacy upgrade/implode paths in standalone install CI.

Production viteplus.dev deploys on every push to main today. Docs for unreleased features go live at merge time, and install-script rewrites (for example #2346) would be served behind https://vite.plus before a release with matching binaries exists. This PR adds `rfcs/deploy-docs-on-release.md` and implements it: - New `.github/actions/deploy-docs` composite action holds the shared build and deploy steps (setup-vp, Vite Task cache, `vp run build`, `vpx void deploy`), with `void-project` / `void-token` inputs and optional cache-key inputs. - `deploy-docs.yml` loses its push trigger and becomes the manual (`workflow_dispatch`) production deploy, the escape hatch for urgent updates. - `release.yml` gains a `deploy-docs` job that deploys production from the release commit after the Release job publishes npm and the GitHub release. Prereleases skip it. `discord-notify` now waits for it (success, or the prerelease skip) before announcing. - `deploy-docs-main.yml` (new) takes over the push trigger and deploys main to main.viteplus.dev (the `viteplus-main` void.app project), a standing preview of the latest docs on main. - `deploy-docs-preview.yml` keeps its trigger, staging target, and PR comment step, and now runs the same composite with per-PR cache keys. Setup needed before merge, outside this repo: - Create the `viteplus-main` project on the void platform (same `VOID_TOKEN`). - Add DNS CNAME `main.viteplus.dev` -> `viteplus-main.void.app` and attach the custom domain to the project. Not included: `noindex` for the preview sites, which needs theme or platform support.

forehalo force-pushed the feat/dirs-path-resolution branch 4 times, most recently from b8069a5 to 2f8be03 Compare August 5, 2026 17:13

forehalo mentioned this pull request Aug 5, 2026

feat: remove VP_HOME and default installers to the split XDG layout #2349

Closed

forehalo changed the title ~~feat: introduce Dirs for unified XDG-aware path resolution~~ feat: XDG-compliant directory layout via unified Dirs resolution Aug 6, 2026

forehalo force-pushed the feat/dirs-path-resolution branch 2 times, most recently from 08b7589 to 4e2abdf Compare August 6, 2026 17:25

forehalo changed the title ~~feat: XDG-compliant directory layout via unified Dirs resolution~~ feat: XDG directory layout via VpDirs Aug 6, 2026

This was referenced Aug 7, 2026

chore: remove remaining VP_HOME usage (especially snapshot tests) #2371

Open

feat: migrate ~/.vite-plus into split VP_*/XDG dirs on vp upgrade #2372

Open

forehalo force-pushed the feat/dirs-path-resolution branch from 78a23b6 to a433ed4 Compare August 7, 2026 09:29

forehalo marked this pull request as ready for review August 7, 2026 09:29

forehalo force-pushed the feat/dirs-path-resolution branch 3 times, most recently from 6b26e69 to ca9dcca Compare August 7, 2026 12:17

fengmk2 self-assigned this Aug 7, 2026

chatgpt-codex-connector Bot reviewed Aug 7, 2026

View reviewed changes

fengmk2 reviewed Aug 7, 2026

View reviewed changes

Comment thread rfcs/directory-layout.md Outdated

fengmk2 mentioned this pull request Aug 9, 2026

ci: deploy production docs on release, main preview on push #2389

Merged

forehalo force-pushed the feat/dirs-path-resolution branch from ca9dcca to ad9d7dd Compare August 10, 2026 05:35

forehalo added 3 commits August 10, 2026 14:05

docs(rfc): document split directory layout via VpDirs

3e57fac

Capture the resolution design, grandfathering of existing ~/.vite-plus installs, installer alignment, and follow-ups for VP_HOME cleanup and migrate-on-upgrade.

forehalo force-pushed the feat/dirs-path-resolution branch from ad9d7dd to 5cc3b6c Compare August 10, 2026 06:07

fengmk2 added the preview-build Publish this PR's commits to the registry bridge as preview builds label Aug 10, 2026

forehalo marked this pull request as draft August 10, 2026 06:33

Navigation Menu

Uh oh!

feat: XDG directory layout via VpDirs - #2346

feat: XDG directory layout via VpDirs#2346
forehalo wants to merge 4 commits into
voidzero-dev:mainfrom
forehalo:feat/dirs-path-resolution

forehalo commented Aug 5, 2026 •

edited

Loading

Uh oh!

netlify Bot commented Aug 5, 2026 •

edited

Loading

Uh oh!

fengmk2 commented Aug 7, 2026

Uh oh!

socket-security Bot commented Aug 7, 2026 •

edited

Loading

Uh oh!

fengmk2 commented Aug 7, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

liangmiQwQ commented Aug 7, 2026 •

edited

Loading

Uh oh!

Uh oh!

fengmk2 commented Aug 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

forehalo commented Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Resolution (high level)

Commits (review order)

User impact

Follow-up

Test plan

Uh oh!

netlify Bot commented Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for viteplus-preview canceled.

Uh oh!

fengmk2 commented Aug 7, 2026

Uh oh!

socket-security Bot commented Aug 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

fengmk2 commented Aug 7, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

liangmiQwQ commented Aug 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

fengmk2 commented Aug 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

forehalo commented Aug 5, 2026 •

edited

Loading

netlify Bot commented Aug 5, 2026 •

edited

Loading

socket-security Bot commented Aug 7, 2026 •

edited

Loading

liangmiQwQ commented Aug 7, 2026 •

edited

Loading