1. 1//! Canonical install/data layout (docs/design/32-release-engineering.md,
2. 2//! "Canonical layout" section). THE single source of truth for where
3. 3//! vak puts binaries, data, caches, and logs on each platform.
4. 4//!
5. 5//! Every crate resolves paths through these functions — never by hand-
6. 6//! rolling `HOME/.vak` again. The 0.7 drift incident (services kept
7. 7//! executing an old image while five call sites disagreed about home)
8. 8//! is the standing reason this module exists.
9. 9//!
10. 10//! macOS (Apple File System Programming Guide):
11. 11//! data ~/Library/Application Support/vak
12. 12//! cache ~/Library/Caches/vak
13. 13//! logs ~/Library/Logs/vak
14. 14//! Linux (XDG Base Directory Specification):
15. 15//! data $XDG_DATA_HOME/vak (~/.local/share/vak)
16. 16//! cache $XDG_CACHE_HOME/vak (~/.cache/vak)
17. 17//! logs $XDG_STATE_HOME/vak/logs (~/.local/state/vak/logs)
18. 18//!
19. 19//! `VAK_HOME` overrides the DATA home everywhere — an explicit override
20. 20//! is the user's layout choice and yields a self-contained tree.
21. 21
22. 22use std::path::PathBuf;
23. 23
24. 24use crate::get_var;
25. 25
26. 26/// The user data home: sessions, memory, tasks, config state, audit logs.
27. 27pub fn data_home() -> PathBuf {
28. 28 resolve(get_var("VAK_HOME").as_deref()).data
29. 29}
30. 30
31. 31/// Rebuildable artifacts only (the SQLite FTS index and WAL sidecars).
32. 32/// Deleting this directory must always be safe; it is rebuilt from JSONL.
33. 33pub fn cache_home() -> PathBuf {
34. 34 resolve(get_var("VAK_HOME").as_deref()).cache
35. 35}
36. 36
37. 37/// Service + CLI log files (Console.app-visible on macOS).
38. 38pub fn logs_dir() -> PathBuf {
39. 39 resolve(get_var("VAK_HOME").as_deref()).logs
40. 40}
41. 41
42. 42/// The canonical **project workspace** a fresh install brings up its
43. 43/// durable services against — `~/vak-home`, a plain directory a person
44. 44/// can `cd` into, distinct from `data_home()` (which holds sessions,
45. 45/// config, and other application-managed state, not something a user
46. 46/// browses or edits directly).
47. 47///
48. 48/// This exists because nothing previously named a workspace at install
49. 49/// time: `self install` placed binaries, and `self services-sync`
50. 50/// captured whatever directory it happened to be run from as the
51. 51/// gateway's workspace (docs/design/32 invariant 3) — correct as a
52. 52/// mechanism, but with no answer to "which directory" until an operator
53. 53/// picked one. A real incident: services-sync was run from inside the
54. 54/// vak *source checkout* while developing it, silently binding an
55. 55/// always-on Telegram bridge to the tool's own dev repo. `self install`
56. 56/// now creates this directory and syncs services against it on a truly
57. 57/// fresh install (no prior units), so there is always a sane, isolated
58. 58/// default — never the workspace a person happened to be standing in.
59. 59pub fn default_workspace() -> PathBuf {
60. 60 resolve(get_var("VAK_HOME").as_deref()).workspace
61. 61}
62. 62
63. 63/// The gateway's persisted workspace selection. An absent or malformed
64. 64/// selection intentionally falls back to the canonical default workspace.
65. 65pub fn gateway_workspace() -> PathBuf {
66. 66 let homes = resolve(get_var("VAK_HOME").as_deref());
67. 67 gateway_workspace_at(&homes.data, &homes.workspace)
68. 68}
69. 69
70. 70/// Per-agent data home: sessions, memory, and agent-specific config.
71. 71/// Under data_home()/agents/<agent_id>/
72. 72pub fn agent_home(agent_id: &str) -> PathBuf {
73. 73 agent_home_at(&data_home(), agent_id)
74. 74}
75. 75
76. 76/// Per-agent data home resolved from an explicit data home root.
77. 77pub fn agent_home_at(data: &std::path::Path, agent_id: &str) -> PathBuf {
78. 78 data.join("agents").join(agent_id)
79. 79}
80. 80
81. 81/// Per-session collaboration records for shared Office drafts.
82. 82/// Session IDs are generated by Vak and callers must validate externally
83. 83/// supplied values before resolving them here.
84. 84pub fn office_workspaces_at(data: &std::path::Path, session_id: &str) -> PathBuf {
85. 85 data.join("office-workspaces").join(session_id)
86. 86}
87. 87
88. 88/// Per-agent project workspace (the directory file/shell tools operate in),
89. 89/// distinct from `agent_home` (which holds sessions/memory). The built-in
90. 90/// "vak" agent keeps using the base workspace so existing single-agent
91. 91/// installs see no path change; every other agent gets an isolated
92. 92/// subdirectory nested *under that same base workspace*, so agents never see
93. 93/// each other's files, while the same agent id opened against two different
94. 94/// base workspaces (e.g. two server instances, or a gateway channel pointed
95. 95/// at a different project) still resolves to two independently isolated
96. 96/// workspaces rather than one shared global directory keyed on agent id
97. 97/// alone.
98. 98pub fn agent_workspace(base: &std::path::Path, agent_id: &str) -> PathBuf {
99. 99 if agent_id == "vak" {
100. 100 base.to_path_buf()
101. 101 } else {
102. 102 base.join(".vak/agents").join(agent_id).join("workspace")
103. 103 }
104. 104}
105. 105
106. 106/// Resolve the gateway workspace from an explicit data home. This variant
107. 107/// keeps server tests isolated when a `Core` uses a temporary sessions home.
108. 108pub fn gateway_workspace_at(data: &std::path::Path, default: &std::path::Path) -> PathBuf {
109. 109 let path = data.join("gateway/default-workspace");
110. 110 std::fs::read_to_string(path)
111. 111 .ok()
112. 112 .map(|raw| PathBuf::from(raw.trim()))
113. 113 .filter(|workspace| workspace.is_absolute() && workspace.is_dir())
114. 114 .unwrap_or_else(|| default.to_path_buf())
115. 115}
116. 116
117. 117/// Persist or clear the user-selected gateway workspace atomically.
118. 118pub fn persist_gateway_workspace_at(
119. 119 data: &std::path::Path,
120. 120 workspace: Option<&std::path::Path>,
121. 121) -> Result<(), std::io::Error> {
122. 122 let dir = data.join("gateway");
123. 123 std::fs::create_dir_all(&dir)?;
124. 124 let path = dir.join("default-workspace");
125. 125 match workspace {
126. 126 Some(workspace) => {
127. 127 let temp = dir.join(format!(".default-workspace.{}.tmp", std::process::id()));
128. 128 std::fs::write(&temp, format!("{}\n", workspace.display()))?;
129. 129 std::fs::rename(temp, path)?;
130. 130 }
131. 131 None => match std::fs::remove_file(path) {
132. 132 Ok(()) => {}
133. 133 Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
134. 134 Err(error) => return Err(error),
135. 135 },
136. 136 }
137. 137 Ok(())
138. 138}
139. 139
140. 140/// Canonical toolchain search directories across standard locations (Homebrew, Cargo, Local, System, version managers).
141. 141/// Essential for macOS GUI app bundles and daemon/service processes where shell profile is not evaluated.
142. 142pub fn canonical_toolchain_paths() -> Vec<PathBuf> {
143. 143 let home = base_home();
144. 144 let mut dirs = Vec::new();
145. 145
146. 146 // Homebrew / standard system paths
147. 147 for dir in [
148. 148 "/opt/homebrew/bin",
149. 149 "/opt/homebrew/sbin",
150. 150 "/usr/local/bin",
151. 151 "/usr/local/sbin",
152. 152 "/usr/bin",
153. 153 "/bin",
154. 154 "/usr/sbin",
155. 155 "/sbin",
156. 156 ] {
157. 157 let p = PathBuf::from(dir);
158. 158 if p.is_dir() && !dirs.contains(&p) {
159. 159 dirs.push(p);
160. 160 }
161. 161 }
162. 162
163. 163 // User toolchains
164. 164 for sub in [
165. 165 ".cargo/bin",
166. 166 ".local/bin",
167. 167 "bin",
168. 168 ".local/share/pnpm",
169. 169 "Library/pnpm",
170. 170 ".local/share/fnm/current/bin",
171. 171 ".fnm/current/bin",
172. 172 ".asdf/shims",
173. 173 ".local/share/mise/shims",
174. 174 ".pyenv/shims",
175. 175 ] {
176. 176 let p = home.join(sub);
177. 177 if p.is_dir() && !dirs.contains(&p) {
178. 178 dirs.push(p);
179. 179 }
180. 180 }
181. 181
182. 182 // Scan active node versions in nvm
183. 183 let nvm_node = home.join(".nvm/versions/node");
184. 184 if nvm_node.is_dir()
185. 185 && let Ok(entries) = std::fs::read_dir(&nvm_node)
186. 186 {
187. 187 for entry in entries.flatten() {
188. 188 let bin = entry.path().join("bin");
189. 189 if bin.is_dir() && !dirs.contains(&bin) {
190. 190 dirs.push(bin);
191. 191 }
192. 192 }
193. 193 }
194. 194
195. 195 dirs
196. 196}
197. 197
198. 198/// Computes an augmented PATH value merging the current process PATH with canonical toolchain paths.
199. 199pub fn augmented_process_path() -> std::ffi::OsString {
200. 200 let mut parts: Vec<PathBuf> = Vec::new();
201. 201 if let Some(existing) = std::env::var_os("PATH") {
202. 202 parts.extend(std::env::split_paths(&existing).filter(|p| !p.as_os_str().is_empty()));
203. 203 }
204. 204 for toolchain_path in canonical_toolchain_paths() {
205. 205 if !parts.contains(&toolchain_path) {
206. 206 parts.push(toolchain_path);
207. 207 }
208. 208 }
209. 209 std::env::join_paths(parts).unwrap_or_default()
210. 210}
211. 211
212. 212/// Every home derived from one override decision. Pure so tests can
213. 213/// exercise both branches without touching process-global environment,
214. 214/// and so a caller needing two of them reads `VAK_HOME` once rather than
215. 215/// pairing values from before and after another thread changed it.
216. 216struct Homes {
217. 217 data: PathBuf,
218. 218 cache: PathBuf,
219. 219 logs: PathBuf,
220. 220 workspace: PathBuf,
221. 221}
222. 222
223. 223fn resolve(override_home: Option<&str>) -> Homes {
224. 224 let base = base_home();
225. 225 match override_home.filter(|s| !s.is_empty()) {
226. 226 // An explicit override is a self-contained sandbox: everything
227. 227 // nests under it so tests and portable installs stay one tree,
228. 228 // including the Shared config's workspace, which would otherwise
229. 229 // inherit the operator's real ~/vak-home state.
230. 230 Some(h) => {
231. 231 let data = PathBuf::from(h);
232. 232 Homes {
233. 233 cache: data.join("cache"),
234. 234 logs: data.join("logs"),
235. 235 workspace: data.join("vak-home"),
236. 236 data,
237. 237 }
238. 238 }
239. 239 None => Homes {
240. 240 workspace: base.join("vak-home"),
241. 241 #[cfg(target_os = "macos")]
242. 242 data: base
243. 243 .join("Library")
244. 244 .join("Application Support")
245. 245 .join(app_dir_name()),
246. 246 #[cfg(target_os = "macos")]
247. 247 cache: base.join("Library").join("Caches").join(app_dir_name()),
248. 248 #[cfg(target_os = "macos")]
249. 249 logs: base.join("Library").join("Logs").join(app_dir_name()),
250. 250 #[cfg(not(target_os = "macos"))]
251. 251 data: xdg(&base, "XDG_DATA_HOME", ".local/share"),
252. 252 #[cfg(not(target_os = "macos"))]
253. 253 cache: xdg(&base, "XDG_CACHE_HOME", ".cache"),
254. 254 #[cfg(not(target_os = "macos"))]
255. 255 logs: xdg(&base, "XDG_STATE_HOME", ".local/state").join("logs"),
256. 256 },
257. 257 }
258. 258}
259. 259
260. 260#[cfg(not(target_os = "macos"))]
261. 261fn xdg(base: &std::path::Path, env_key: &str, default_suffix: &str) -> PathBuf {
262. 262 if let Some(v) = std::env::var_os(env_key)
263. 263 && !v.is_empty()
264. 264 {
265. 265 return PathBuf::from(v).join(app_dir_name());
266. 266 }
267. 267 base.join(default_suffix).join(app_dir_name())
268. 268}
269. 269
270. 270fn app_dir_name() -> &'static str {
271. 271 "vak"
272. 272}
273. 273
274. 274fn base_home() -> PathBuf {
275. 275 let environment_home = std::env::var_os("HOME").or_else(|| std::env::var_os("USERPROFILE"));
276. 276 #[allow(deprecated)]
277. 277 let account_home = std::env::home_dir();
278. 278 resolve_base_home(environment_home.map(PathBuf::from), account_home)
279. 279}
280. 280
281. 281fn resolve_base_home(environment_home: Option<PathBuf>, account_home: Option<PathBuf>) -> PathBuf {
282. 282 environment_home
283. 283 .filter(|path| path.is_absolute())
284. 284 .or_else(|| account_home.filter(|path| path.is_absolute()))
285. 285 .unwrap_or_else(|| PathBuf::from("/"))
286. 286}
287. 287
288. 288/// Pin this process's installation home, at the highest precedence.
289. 289///
290. 290/// `VAK_HOME` is normally read from the environment, which makes it
291. 291/// awkward to set from inside a test: `std::env::set_var` is `unsafe`, and
292. 292/// `unsafe_code` is denied workspace-wide (AGENTS.md invariant 6). The
293. 293/// override map [`crate::set_override`] already sits above the real
294. 294/// environment in [`crate::get_var`]'s precedence, so pinning the home is
295. 295/// safe and needs no `unsafe` at all.
296. 296pub fn set_home_override(path: &std::path::Path) {
297. 297 crate::set_override("VAK_HOME", path.to_string_lossy().into_owned());
298. 298}
299. 299
300. 300/// Point this process at a private, empty home, and return it.
301. 301///
302. 302/// **Every test that builds a `Core` must call this.** Without it,
303. 303/// `load_with_trust` reads the operator's real Shared layer
304. 304/// (`~/vak-home/.vak/config.toml` and the real Shared secret scope), so a
305. 305/// personal setting silently changes what the test exercises — a real MCP server
306. 306/// gets advertised, `[memory] reflection = true` consumes a scripted
307. 307/// provider response, a real provider key makes an "unconfigured" case
308. 308/// pass. Tests were reading the developer's machine.
309. 309///
310. 310/// Idempotent per process: the first call wins and later ones return the
311. 311/// same directory, so tests sharing a binary share one home. That is the
312. 312/// isolation that matters — each test already scopes its own cwd and
313. 313/// sessions home. The directory is always a new one: pids are recycled, and
314. 314/// a home an earlier process left (seeded Shared skills and plugins, a
315. 315/// Shared config) would otherwise be this process's starting state.
316. 316///
317. 317/// Sharing holds only while no test in the binary writes the Shared layer,
318. 318/// which every `Core::new` reads. A test that must write it runs in a
319. 319/// binary of its own, on a private home per test — see
320. 320/// `crates/vak-server/tests/shared_config_layer.rs`.
321. 321pub fn isolate_home_for_tests() -> PathBuf {
322. 322 static ISOLATED: std::sync::OnceLock<PathBuf> = std::sync::OnceLock::new();
323. 323 ISOLATED
324. 324 .get_or_init(|| {
325. 325 let dir = fresh_test_home();
326. 326 set_home_override(&dir);
327. 327 dir
328. 328 })
329. 329 .clone()
330. 330}
331. 331
332. 332/// A directory under the temp dir that this call created, so nothing an
333. 333/// earlier process left can be in it.
334. 334fn fresh_test_home() -> PathBuf {
335. 335 let base = std::env::temp_dir();
336. 336 let _ = std::fs::create_dir_all(&base);
337. 337 let pid = std::process::id();
338. 338 let mut dir = base.join(format!("vak-test-home-{pid}"));
339. 339 let mut taken = 0u64;
340. 340 while std::fs::create_dir(&dir).is_err_and(|e| e.kind() == std::io::ErrorKind::AlreadyExists) {
341. 341 taken += 1;
342. 342 dir = base.join(format!("vak-test-home-{pid}-{taken}"));
343. 343 }
344. 344 dir
345. 345}
346. 346
347. 347#[cfg(test)]
348. 348mod tests {
349. 349 #![allow(clippy::unwrap_used, clippy::expect_used)]
350. 350
351. 351 use super::*;
352. 352
353. 353 /// The override must win everywhere and produce a self-contained
354. 354 /// tree (tests + portable installs depend on one-directory depth).
355. 355 #[test]
356. 356 fn override_pins_every_directory_to_one_tree() {
357. 357 let sandbox = tempfile::tempdir().unwrap();
358. 358 let h = resolve(Some(sandbox.path().to_str().unwrap()));
359. 359 assert_eq!(h.data, sandbox.path());
360. 360 assert_eq!(
361. 361 h.logs,
362. 362 h.data.join("logs"),
363. 363 "overridden homes are self-contained"
364. 364 );
365. 365 assert_eq!(h.cache, h.data.join("cache"));
366. 366 }
367. 367
368. 368 #[test]
369. 369 fn default_workspace_is_a_plain_dir_under_the_account_home_not_data_home() {
370. 370 let canonical = resolve(None);
371. 371 assert_eq!(canonical.workspace, base_home().join("vak-home"));
372. 372 assert_ne!(
373. 373 canonical.workspace, canonical.data,
374. 374 "the default workspace must never collide with the app's own data home"
375. 375 );
376. 376
377. 377 let sandbox = tempfile::tempdir().unwrap();
378. 378 let overridden = resolve(Some(sandbox.path().to_str().unwrap()));
379. 379 assert_eq!(overridden.workspace, overridden.data.join("vak-home"));
380. 380 }
381. 381
382. 382 #[test]
383. 383 fn canonical_homes_follow_platform_convention() {
384. 384 let h = resolve(None);
385. 385 let base = base_home();
386. 386 #[cfg(target_os = "macos")]
387. 387 {
388. 388 assert_eq!(h.data, base.join("Library/Application Support/vak"));
389. 389 assert_eq!(h.cache, base.join("Library/Caches/vak"));
390. 390 assert_eq!(h.logs, base.join("Library/Logs/vak"));
391. 391 }
392. 392 // Invariants that hold on every platform:
393. 393 assert!(
394. 394 !h.cache.starts_with(&h.data),
395. 395 "cache must not nest inside data"
396. 396 );
397. 397 for p in [&h.data, &h.cache, &h.logs] {
398. 398 assert!(
399. 399 !p.to_string_lossy().contains("/.vak"),
400. 400 "canonical layout must not use the legacy dotdir: {}",
401. 401 p.display()
402. 402 );
403. 403 }
404. 404 }
405. 405
406. 406 #[test]
407. 407 fn empty_override_is_not_an_override() {
408. 408 let h = resolve(Some(""));
409. 409 assert!(
410. 410 !h.data.to_string_lossy().contains("/cache"),
411. 411 "empty string must fall through to the platform layout"
412. 412 );
413. 413 assert_eq!(h.workspace, base_home().join("vak-home"));
414. 414 }
415. 415
416. 416 #[test]
417. 417 fn missing_environment_home_uses_absolute_account_home() {
418. 418 assert_eq!(
419. 419 resolve_base_home(None, Some(PathBuf::from("/Users/example"))),
420. 420 PathBuf::from("/Users/example")
421. 421 );
422. 422 assert_eq!(
423. 423 resolve_base_home(Some(PathBuf::from("relative")), None),
424. 424 PathBuf::from("/")
425. 425 );
426. 426 }
427. 427
428. 428 /// The home used to be named by pid alone and reused whenever a pid
429. 429 /// came round again, so a test process could start inside the home of
430. 430 /// a finished one, Shared skills and all.
431. 431 #[test]
432. 432 fn a_test_home_is_never_a_directory_that_already_existed() {
433. 433 let first = fresh_test_home();
434. 434 std::fs::write(first.join("left-behind"), "stale").unwrap();
435. 435 let second = fresh_test_home();
436. 436 assert_ne!(first, second);
437. 437 assert_eq!(
438. 438 std::fs::read_dir(&second).unwrap().count(),
439. 439 0,
440. 440 "a new home starts empty"
441. 441 );
442. 442 let _ = std::fs::remove_dir_all(&first);
443. 443 let _ = std::fs::remove_dir_all(&second);
444. 444 }
445. 445
446. 446 #[test]
447. 447 fn gateway_workspace_sidecar_defaults_and_round_trips() {
448. 448 let data = tempfile::tempdir().unwrap();
449. 449 let default = PathBuf::from("/Users/example/vak-home");
450. 450 assert_eq!(gateway_workspace_at(data.path(), &default), default);
451. 451 let selected = tempfile::tempdir().unwrap();
452. 452 persist_gateway_workspace_at(data.path(), Some(selected.path())).unwrap();
453. 453 assert_eq!(gateway_workspace_at(data.path(), &default), selected.path());
454. 454 persist_gateway_workspace_at(data.path(), None).unwrap();
455. 455 assert_eq!(gateway_workspace_at(data.path(), &default), default);
456. 456 }
457. 457
458. 458 #[test]
459. 459 fn gateway_workspace_ignores_relative_or_missing_sidecars() {
460. 460 let data = tempfile::tempdir().unwrap();
461. 461 let path = data.path().join("gateway/default-workspace");
462. 462 std::fs::create_dir_all(path.parent().unwrap()).unwrap();
463. 463 std::fs::write(&path, "relative\n").unwrap();
464. 464 let default = PathBuf::from("/Users/example/vak-home");
465. 465 assert_eq!(gateway_workspace_at(data.path(), &default), default);
466. 466 }
467. 467
468. 468 #[test]
469. 469 fn agent_home_at_resolves_scoped_subdirectory() {
470. 470 let data = PathBuf::from("/tmp/vak-test-home");
471. 471 assert_eq!(agent_home_at(&data, "vak"), data.join("agents/vak"));
472. 472 assert_eq!(
473. 473 agent_home_at(&data, "agent-123"),
474. 474 data.join("agents/agent-123")
475. 475 );
476. 476 }
477. 477
478. 478 #[test]
479. 479 fn agent_workspace_isolates_user_created_agents_from_each_other() {
480. 480 let base = PathBuf::from("/Users/example/vak-home");
481. 481 // The built-in agent keeps the process's own base workspace, so
482. 482 // existing single-agent installs see no path change.
483. 483 assert_eq!(agent_workspace(&base, "vak"), base);
484. 484 // Every other agent gets its own isolated directory nested under
485. 485 // that same base, distinct from the base itself and each other.
486. 486 let a = agent_workspace(&base, "agent-a");
487. 487 let b = agent_workspace(&base, "agent-b");
488. 488 assert_ne!(a, base);
489. 489 assert_ne!(b, base);
490. 490 assert_ne!(a, b);
491. 491 assert_eq!(a, base.join(".vak/agents/agent-a/workspace"));
492. 492 }
493. 493
494. 494 #[test]
495. 495 fn agent_workspace_isolates_the_same_agent_id_across_different_base_workspaces() {
496. 496 let base_a = PathBuf::from("/Users/example/project-a");
497. 497 let base_b = PathBuf::from("/Users/example/project-b");
498. 498 assert_ne!(
499. 499 agent_workspace(&base_a, "newsy"),
500. 500 agent_workspace(&base_b, "newsy"),
501. 501 "the same agent id under two different base workspaces must not collide"
502. 502 );
503. 503 }
504. 504}
505. 505