📦 deps(thirdparty): update snapshots

2026-05-29 08:33:53 +00:00
parent fdb52f1e96
commit 06e0d13d57
1615 changed files with 232858 additions and 0 deletions
@@ -0,0 +1,117 @@
+# Stage 4: Paths
+
+**Status:** ⬜ Not Started
+**Blocked By:** None (can run parallel with Handlers)
+**Unlocks:** Documents
+
+## Objective
+
+Replace hardcoded paths with XDG-compliant paths and add path security.
+
+## XDG Directory Reference
+
+| Function | Path | Purpose |
+|----------|------|---------|
+| `getConfigDir(name)` | `~/.config/{name}` | Configuration files |
+| `getCacheDir(name)` | `~/.cache/{name}` | Cache files |
+| `getDataDir(name)` | `~/.local/share/{name}` | Persistent data |
+| `getStateDir(name)` | `~/.local/state/{name}` | Runtime state |
+
+## Files to Migrate
+
+{{#each PATH_FILES}}
+### {{this.file}}
+
+- **Line:** {{this.line}}
+- **Current:** `{{this.current}}`
+- **Pattern:** {{this.pattern}}
+
+#### Migration
+
+- [ ] Replace with XDG function
+- [ ] Add `securePath()` if user-provided
+- [ ] Update tests
+
+```typescript
+// Before
+{{this.beforeCode}}
+
+// After
+{{this.afterCode}}
+```
+
+---
+
+{{/each}}
+
+## Path Security
+
+For user-provided paths, use `securePath()`:
+
+```typescript
+import { securePath } from "@outfitter/file-ops";
+
+const validatePath = (userPath: string, baseDir: string) => {
+  const result = securePath(userPath, { base: baseDir });
+  if (result.isErr()) {
+    return Result.err(new ValidationError("Invalid path", { path: userPath }));
+  }
+  return Result.ok(result.value);
+};
+```
+
+**Security checks:**
+- Path traversal (`../`)
+- Symlink following
+- Base directory escape
+- Null bytes
+
+## Common Patterns
+
+### Config File
+
+```typescript
+// Before
+const configPath = path.join(os.homedir(), ".myapp", "config.json");
+
+// After
+import { getConfigDir } from "@outfitter/config";
+const configPath = path.join(getConfigDir("myapp"), "config.json");
+```
+
+### Cache Directory
+
+```typescript
+// Before
+const cacheDir = path.join(os.homedir(), ".cache", "myapp");
+
+// After
+import { getCacheDir } from "@outfitter/config";
+const cacheDir = getCacheDir("myapp");
+```
+
+### User-Provided Path
+
+```typescript
+// Before
+const filePath = args.file;
+await fs.readFile(filePath);
+
+// After
+import { securePath } from "@outfitter/file-ops";
+const pathResult = securePath(args.file, { base: process.cwd() });
+if (pathResult.isErr()) return pathResult;
+await fs.readFile(pathResult.value);
+```
+
+## Completion Checklist
+
+- [ ] All `os.homedir()` replaced with XDG functions
+- [ ] All `~/` literals replaced
+- [ ] User-provided paths validated with `securePath()`
+- [ ] Tests use `withTempDir()` fixture
+- [ ] No hardcoded absolute paths
+
+## Notes
+
+{{PATH_NOTES}}