@cad0p/pi-napkin 0.3.0 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,41 +1,91 @@
1
1
  /**
2
- * First-run auto-setup for auto-distill.
2
+ * Auto-distill health check + first-run setup for vaults.
3
3
  *
4
- * Auto-distill needs the vault to be a git repo with a `.gitignore` that
5
- * excludes its ephemeral state (distill worktrees, Obsidian workspace-local
6
- * caches). Vaults typically ship without any of this — we scaffold it at
7
- * `session_start` when `distill.enabled` is true.
4
+ * Auto-distill needs the vault to be a git repo with a `.gitignore`
5
+ * that excludes its ephemeral state (distill worktrees, Obsidian
6
+ * workspace-local caches) and (at full level) a `.napkin/config.json`
7
+ * that is parseable and tracked by git. The same function runs at
8
+ * `session_start` (`level: "fast"`) to enforce the cheap invariants
9
+ * once per session, and again before every worktree-based spawn
10
+ * (`level: "full"`) to enforce the full set including the slower
11
+ * git probes. See {@link ensureVaultReadyForDistill} for the per-level
12
+ * invariant matrix.
8
13
  *
9
- * PR #12 (agent-driven merge): pre-PR-12 auto-distill also installed an
10
- * `*.md merge=napkin-distill-merge` rule in `.gitattributes` to route
11
- * concurrent-distill conflicts through an LLM merge driver. PR #12 deleted
12
- * that driver — the distill agent now resolves merges itself in its
13
- * worktree, so the rule is no longer needed. New vaults never get the rule
14
- * installed. Existing vaults that already have it are left alone (manual
15
- * cleanup; the rule becomes inert once the driver script is gone — git
16
- * silently falls back to its built-in merge driver). See design.md
17
- * "Migration" for rationale.
14
+ * PR #12 (agent-driven merge): pre-PR-12 auto-distill also installed
15
+ * an `*.md merge=napkin-distill-merge` rule in `.gitattributes` to
16
+ * route concurrent-distill conflicts through an LLM merge driver. PR
17
+ * #12 deleted that driver — the distill agent now resolves merges
18
+ * itself in its worktree, so the rule is no longer needed. New vaults
19
+ * never get the rule installed. Existing vaults that already have it
20
+ * are left alone (manual cleanup; the rule becomes inert once the
21
+ * driver script is gone — git silently falls back to its built-in
22
+ * merge driver). See design.md "Migration" for rationale.
18
23
  *
19
24
  * Design contract:
20
- * - Idempotent: re-running on an already-set-up vault is a no-op (returns
21
- * `{ initialized: false, scaffolded: [] }`).
22
- * - Non-destructive: never clobbers existing `.gitignore` content; only
23
- * appends missing lines.
24
- * - Fail-soft: returns `{ error }` instead of throwing so the caller can
25
- * surface a notify() and keep the session alive.
25
+ * - Idempotent: re-running on a healthy vault returns
26
+ * `{ initialized: false, scaffolded: [], findings: [] }` and
27
+ * touches nothing on disk.
28
+ * - In-place block reconciliation: `.gitignore` is rewritten as a
29
+ * `# BEGIN NAPKIN-DISTILL MANAGED` / `# END NAPKIN-DISTILL
30
+ * MANAGED` block. User content outside the markers is preserved
31
+ * byte-identically. Drift inside the markers is auto-recovered
32
+ * with one of four recovery flavors (`installed` / `reset` /
33
+ * `migrated from line-by-line` / `reset and migrated from
34
+ * line-by-line` — see {@link mergeManagedBlock} for the case
35
+ * matrix). Malformed markers refuse auto-fix and emit a
36
+ * loud-error finding.
37
+ * - Fail-soft: returns `{ error }` instead of throwing on
38
+ * filesystem-write or git-subprocess failures so callers can
39
+ * surface a notify and abort the spawn while keeping the session
40
+ * alive. Structured per-invariant findings live in `findings`;
41
+ * `error` is reserved for the fail-soft generic-failure channel
42
+ * that has no corresponding finding (e.g. `git init` / `git add`
43
+ * / `git commit` failures, EISDIR on `.gitignore` write, and the
44
+ * {@link LEGACY_EMBEDDED_LAYOUT_ERROR} sentinel).
26
45
  */
27
46
 
28
47
  import { spawnSync } from "node:child_process";
29
48
  import * as fs from "node:fs";
30
49
  import * as path from "node:path";
31
50
 
32
- import { GIT_SUBCOMMAND_TIMEOUT_MS } from "./distill-workspace";
51
+ import {
52
+ GIT_SUBCOMMAND_TIMEOUT_MS,
53
+ resolveCacheRoot,
54
+ } from "./distill-workspace";
33
55
 
34
56
  /**
35
- * Lines appended to `<vault>/.gitignore` when scaffolding. Order is stable so
36
- * diff noise stays minimal on re-runs. Each group has a section-comment
37
- * header — we match on the non-comment lines for idempotence, the comments
38
- * are cosmetic.
57
+ * Grace period before a stale distill branch is auto-deleted by the
58
+ * full-level health check. 24 hours is generous enough to cover the
59
+ * common "user runs another distill the next day" pattern: the user
60
+ * still has access to the branch tip via `git reflog` for content
61
+ * recovery if they need it. Tighter would race users who recovered
62
+ * overnight; looser would let dead branches accumulate without bound.
63
+ */
64
+ export const STALE_DISTILL_BRANCH_GRACE_MS = 24 * 60 * 60 * 1000;
65
+
66
+ /**
67
+ * Milliseconds per hour. Used to render branch ages in hours for
68
+ * human-readable notify messages (e.g. the stale-distill-branch
69
+ * deletion finding). Independent of
70
+ * {@link STALE_DISTILL_BRANCH_GRACE_MS} — the relationship between
71
+ * "24h grace" and "hours" is incidental, not a derived constant.
72
+ */
73
+ const MS_PER_HOUR = 60 * 60 * 1000;
74
+
75
+ /**
76
+ * Snapshot of the v0.3.0 line-by-line entries appended to
77
+ * `<vault>/.gitignore` (no markers) for vaults at v0.3.0 and earlier.
78
+ * At v0.3.1 sessions install the managed-block format and remove
79
+ * orphan lines matching this list; the canonical content lives in
80
+ * {@link BLOCK_CONTENT}, which is the source of truth for the
81
+ * managed block. This constant is retained as a migration shim for
82
+ * one release: it is pinned by test as a strict subset of
83
+ * {@link BLOCK_CONTENT} so a future edit that drops a v0.3.0 entry
84
+ * from the managed block surfaces as a test failure rather than a
85
+ * silent migration regression.
86
+ *
87
+ * @deprecated Replaced by {@link BLOCK_CONTENT}; will be removed in a
88
+ * future release once the migration window has lapsed.
39
89
  */
40
90
  export const GITIGNORE_LINES: readonly string[] = [
41
91
  "# napkin-distill ephemeral state",
@@ -67,14 +117,108 @@ export const GITIGNORE_LINES: readonly string[] = [
67
117
  ];
68
118
 
69
119
  /**
70
- * Result of {@link ensureVaultReadyForAutoDistill}.
120
+ * Begin marker for the napkin-distill managed block in `<vault>/.gitignore`.
121
+ * Ansible-style markers bracket the lines that auto-setup owns; everything
122
+ * outside the markers is user territory and is never touched. The exact
123
+ * suffix `NAPKIN-DISTILL MANAGED` is required so unrelated `# BEGIN ...`
124
+ * comments in the user's file don't collide with our detection.
125
+ */
126
+ export const BLOCK_MARKER_BEGIN = "# BEGIN NAPKIN-DISTILL MANAGED";
127
+
128
+ /**
129
+ * End marker matching {@link BLOCK_MARKER_BEGIN}. See that constant for
130
+ * the rationale on the exact suffix.
131
+ */
132
+ export const BLOCK_MARKER_END = "# END NAPKIN-DISTILL MANAGED";
133
+
134
+ /**
135
+ * Canonical content of the napkin-distill managed block. Auto-setup
136
+ * rewrites the bracketed region to match this verbatim whenever drift
137
+ * is detected (lines added, removed, reordered, or modified).
138
+ *
139
+ * Strict superset of {@link GITIGNORE_LINES}: every non-blank,
140
+ * non-comment entry in `GITIGNORE_LINES` is present here. Test
141
+ * coverage pins the relationship so future edits to either constant
142
+ * surface as a test failure.
143
+ */
144
+ export const BLOCK_CONTENT: readonly string[] = [
145
+ "# napkin-distill ephemeral state",
146
+ ".napkin/distill/",
147
+ "",
148
+ "# Obsidian workspace-local state",
149
+ ".obsidian/workspace*.json",
150
+ ".obsidian/cache",
151
+ ".obsidian/.trash/",
152
+ "",
153
+ "# Local tmp/cache",
154
+ "search-cache.json",
155
+ ".DS_Store",
156
+ "",
157
+ "# Common secrets — belt-and-braces for vaults that end up alongside dev",
158
+ "# work. Auto-distill commits 'git add .' on first run; these patterns",
159
+ "# keep credentials out of the initial commit even if a user's vault",
160
+ "# happens to contain them.",
161
+ ".env",
162
+ ".env.local",
163
+ ".env.*.local",
164
+ "*.pem",
165
+ "*.key",
166
+ "id_rsa",
167
+ "id_ecdsa",
168
+ "id_ed25519",
169
+ "secrets.json",
170
+ ".aws/credentials",
171
+ ];
172
+
173
+ /**
174
+ * Depth of the health check run. Each call site explicitly chooses one;
175
+ * there is no default.
176
+ *
177
+ * - `"fast"`: file-only invariants and the cheapest necessary git
178
+ * invocations. Suitable for `session_start`, where added latency is
179
+ * user-visible. Target ~10 ms.
180
+ * - `"full"`: superset of `"fast"` plus git-state probes, filesystem
181
+ * probes, and orphan cleanup. Suitable for the moments immediately
182
+ * before a worktree-based distill is spawned, where the LLM prelude
183
+ * masks tens of milliseconds. Target ~50–100 ms.
184
+ */
185
+ export type HealthLevel = "fast" | "full";
186
+
187
+ /**
188
+ * Outcome of a single named health-check invariant.
189
+ *
190
+ * - `kind: "auto-recovered"`: the invariant was violated but `auto-setup`
191
+ * restored the expected state in place. Surface as an info notify; the
192
+ * caller proceeds with the distill spawn.
193
+ * - `kind: "error"`: the invariant was violated and recovery is owned by
194
+ * the user (e.g. legacy layout migration, malformed JSON). Surface as
195
+ * an error notify; the caller aborts the distill spawn.
196
+ * - `invariant`: stable identifier for the check. One ID per check; the
197
+ * per-flavor recovery messaging lives in `recovery`.
198
+ * - `message`: human-readable description, suitable for notify text.
199
+ * - `recovery`: populated for `auto-recovered` findings; describes what
200
+ * was done (e.g. `"git add .napkin/config.json"`,
201
+ * `"installed managed gitignore block"`).
202
+ */
203
+ export interface HealthFinding {
204
+ kind: "auto-recovered" | "error";
205
+ invariant: string;
206
+ message: string;
207
+ recovery?: string;
208
+ }
209
+
210
+ /**
211
+ * Result of {@link ensureVaultReadyForDistill}.
71
212
  *
72
213
  * - `initialized`: a brand-new `git init` ran (vault had no `.git/` before).
73
214
  * - `scaffolded`: files whose contents were created or modified. Callers use
74
215
  * this to decide whether to surface a first-run notify to the user.
75
216
  * - `error`: populated on fail-soft paths (git init failed, filesystem
76
217
  * errors writing the scaffolding, legacy-layout refusal). If set, other
77
- * fields reflect partial progress.
218
+ * fields reflect partial progress. Consumed at all extension call sites
219
+ * (session_start, runDistill, runAutoDistill, session_shutdown handler)
220
+ * to surface a `notify("error")` and abort the spawn; the legacy-embedded
221
+ * path additionally compares against {@link LEGACY_EMBEDDED_LAYOUT_ERROR}.
78
222
  * - `legacyLayout`: populated when auto-setup refused to scaffold because
79
223
  * the vault is using napkin's legacy embedded layout (`configPath ===
80
224
  * contentPath`). The worktree-based concurrency architecture relies on
@@ -82,6 +226,9 @@ export const GITIGNORE_LINES: readonly string[] = [
82
226
  * which only works for subdir-layout vaults (those that track a
83
227
  * `.napkin/config.json`). `error` is set to `"legacy-embedded-layout"`
84
228
  * so callers can branch on it.
229
+ * - `findings`: structured per-invariant outcomes. Always present (empty
230
+ * array means "all invariants passed"). Callers iterate to surface
231
+ * notifications and decide whether to abort spawning.
85
232
  */
86
233
  export interface SetupResult {
87
234
  initialized: boolean;
@@ -102,6 +249,7 @@ export interface SetupResult {
102
249
  * motivated FB-2.
103
250
  */
104
251
  seededCommit?: boolean;
252
+ findings: readonly HealthFinding[];
105
253
  }
106
254
 
107
255
  /**
@@ -127,6 +275,37 @@ export interface SetupVault {
127
275
  configPath: string;
128
276
  }
129
277
 
278
+ /**
279
+ * Optional dependency-injection seam for {@link
280
+ * ensureVaultReadyForDistill}. All fields are optional; production
281
+ * call sites pass `undefined` (or omit the argument) and get the
282
+ * default behavior. Tests inject stubs to exercise paths that are
283
+ * impractical to reproduce on real filesystems (notably an unwritable
284
+ * cache root: `chmod 0500` would false-pass under root in CI, and a
285
+ * read-only mount is platform-specific).
286
+ */
287
+ export interface SetupOptions {
288
+ /**
289
+ * Probe whether `dir` is writable. Defaults to {@link probeWritable},
290
+ * which writes and removes a temporary file. Tests substitute a
291
+ * stub that returns `{ writable: false, error }` to exercise the
292
+ * `cache-root-writable` loud-error path without touching the real
293
+ * filesystem.
294
+ */
295
+ probeWritable?: (dir: string) => WritableProbeResult;
296
+ /**
297
+ * Read the current wall-clock time in milliseconds since the
298
+ * epoch. Defaults to `Date.now`. Tests inject a deterministic
299
+ * clock to pin boundary cases on the
300
+ * `no-stale-distill-branches-over-grace` invariant: branches
301
+ * exactly at {@link STALE_DISTILL_BRANCH_GRACE_MS} age are not
302
+ * deleted (strict `>` comparison), branches one millisecond past
303
+ * the boundary are. Without an injectable clock the test would
304
+ * race the real `Date.now()`.
305
+ */
306
+ now?: () => number;
307
+ }
308
+
130
309
  /**
131
310
  * Run `git` in `cwd` and return `{ status, stdout, stderr }`. Does not throw
132
311
  * on non-zero exit — we translate failures to `SetupResult.error`.
@@ -154,85 +333,661 @@ function runGit(
154
333
  }
155
334
 
156
335
  /**
157
- * Merge `newLines` into the file at `filePath`, appending only the
158
- * non-comment, non-blank lines that aren't already present. A line is
159
- * considered "present" if it appears verbatim anywhere in the existing file
160
- * (leading/trailing whitespace trimmed for comparison). Returns `true` if
161
- * the file was created or modified.
336
+ * Stable invariant ID for the managed-block check. Auto-recovered
337
+ * findings carry recovery text describing which flavor fired
338
+ * (`installed`, `reset`, `migrated from line-by-line`, or the compound
339
+ * `reset and migrated from line-by-line` when both drift and orphan
340
+ * lines fire on the same pass — see {@link mergeManagedBlock} for the
341
+ * case matrix); error findings indicate the markers are malformed and
342
+ * require manual resolution.
343
+ */
344
+ const INVARIANT_GITIGNORE_BLOCK = "gitignore-block-correct";
345
+
346
+ /**
347
+ * Stable invariant ID for the layout check. Loud-error finding only;
348
+ * legacy-embedded vaults require manual migration to the subdir layout.
349
+ */
350
+ const INVARIANT_SUBDIR_LAYOUT = "subdir-layout";
351
+
352
+ /**
353
+ * Stable invariant ID for the git-repo presence check. Auto-recovered
354
+ * via `git init -q -b main` when `.git/` is absent.
355
+ */
356
+ const INVARIANT_VAULT_IS_GIT_REPO = "vault-is-git-repo";
357
+
358
+ /**
359
+ * Stable invariant ID for `<configPath>/config.json` being tracked by
360
+ * git. Auto-recovered via `git add <configRel>`; the existing
361
+ * scaffolded[] consumption stages and commits the file on the same
362
+ * pass. Untracked config.json is the root cause of Issue #14: distill
363
+ * worktrees are checked out via `git worktree add HEAD`, which copies
364
+ * only tracked files, so untracked config.json never reaches the
365
+ * worktree and napkin's findVault falls back to legacy embedded layout.
366
+ */
367
+ const INVARIANT_CONFIG_JSON_TRACKED = "config.json-tracked";
368
+
369
+ /**
370
+ * Stable invariant ID for `<configPath>/config.json` NOT being
371
+ * gitignored by a rule that lives outside the napkin-distill managed
372
+ * block. Loud-error finding only — the user added the rule explicitly
373
+ * and we cannot guess whether removing it would lose track of an
374
+ * intentional choice. The inside-block flavor is a no-op for this
375
+ * invariant: the canonical {@link BLOCK_CONTENT} does NOT gitignore
376
+ * `config.json`, and the {@link INVARIANT_GITIGNORE_BLOCK} reset
377
+ * automatically removes any drift inside the markers on the next
378
+ * pass.
379
+ */
380
+ const INVARIANT_CONFIG_JSON_NOT_GITIGNORED_OUTSIDE_BLOCK =
381
+ "config.json-not-gitignored-outside-block";
382
+
383
+ /**
384
+ * Stable invariant ID for `<configPath>/distill/` NOT containing tracked
385
+ * files. Loud-error finding only — auto-untrack via `git rm --cached -r`
386
+ * could lose user data the user staged on purpose. The user resolves
387
+ * manually after we've surfaced the offending paths.
388
+ *
389
+ * `<configPath>/distill/` is napkin-distill's ephemeral worktree-fork
390
+ * registry; the canonical {@link BLOCK_CONTENT} gitignores it so it
391
+ * should never be tracked. A tracked entry typically means a stale
392
+ * commit from before the gitignore block was installed, OR a user
393
+ * who explicitly ran `git add -f` on the directory.
394
+ */
395
+ const INVARIANT_NAPKIN_DISTILL_NOT_TRACKED = "napkin-distill-not-tracked";
396
+
397
+ /**
398
+ * Stable invariant ID for the cache root being writable. Loud-error
399
+ * finding only — a read-only home directory or misconfigured
400
+ * `XDG_CACHE_HOME` is the user's environment problem; auto-recovery
401
+ * (e.g. fall back to a different cache home) would mask the real
402
+ * cause and produce surprising state.
403
+ *
404
+ * The probe walks UP from `resolveCacheRoot(vault.contentPath)`'s
405
+ * parent to the first existing ancestor (so a fresh box where
406
+ * `~/.cache/napkin-distill/` does not yet exist does not
407
+ * false-error — the probe lands on `~/.cache` instead).
408
+ */
409
+ const INVARIANT_CACHE_ROOT_WRITABLE = "cache-root-writable";
410
+
411
+ /**
412
+ * Stable invariant ID for the vault HEAD pointing at a real commit.
413
+ * Auto-recovered by seeding an empty initial commit when the vault
414
+ * has a `.git/` but no commits (e.g. a user who ran `git init` by
415
+ * hand and never committed). Without this seed, `git worktree add
416
+ * HEAD` in `createDistillWorktree` would fail with
417
+ * `fatal: invalid reference: HEAD`. Full-level only — fast-level
418
+ * skips so a session_start on a fresh-init-but-uncommitted vault
419
+ * does not seed an unsolicited commit; the seed fires lazily on
420
+ * the next worktree-based spawn.
421
+ */
422
+ const INVARIANT_VAULT_HEAD_ON_BRANCH = "vault-head-on-branch";
423
+
424
+ /**
425
+ * Stable invariant ID for orphaned distill worktree-registry
426
+ * entries. Auto-recovered via `git worktree prune --verbose
427
+ * --expire=now`, which removes registry entries whose worktree
428
+ * directories have been deleted (typically a crashed pi session).
429
+ * Safe: prune only touches entries pointing at missing dirs. The
430
+ * `--expire=now` flag is required because git's default 3-month
431
+ * grace would skip recently-orphaned entries; see the call site for
432
+ * full rationale.
433
+ */
434
+ const INVARIANT_NO_ORPHANED_DISTILL_WORKTREES = "no-orphaned-distill-worktrees";
435
+
436
+ /**
437
+ * Stable invariant ID for stale distill branches with no live
438
+ * worktree. Auto-recovered via `git branch -D <branch>` for any
439
+ * `distill/*` branch whose committerdate is older than
440
+ * {@link STALE_DISTILL_BRANCH_GRACE_MS} AND has no live worktree
441
+ * pointing at it. The reflog grace gives users a recovery window
442
+ * for content from a failed distill before the branch tip is
443
+ * unreachable.
444
+ */
445
+ const INVARIANT_NO_STALE_DISTILL_BRANCHES_OVER_GRACE =
446
+ "no-stale-distill-branches-over-grace";
447
+
448
+ /**
449
+ * Pure parser for `git worktree list --porcelain` output. Extracted
450
+ * from {@link parseLiveWorktreeBranches} so synthetic-input unit tests
451
+ * can pin the strict-parser behavior (skip unrecognised ref shapes
452
+ * rather than adding the wrong key) independent of git's runtime
453
+ * output. Exported for direct test consumption.
454
+ *
455
+ * Porcelain output is a sequence of records separated by blank
456
+ * lines; each record has lines of the form `<key> <value>`. The
457
+ * branch line is `branch refs/heads/<short-name>`; we strip the
458
+ * `refs/heads/` prefix to match the form returned by `git
459
+ * for-each-ref --format=%(refname:short)`. Detached / bare records
460
+ * have no `branch` line and contribute nothing to the set.
461
+ */
462
+ export function parsePorcelainWorktreeBranches(stdout: string): Set<string> {
463
+ const branches = new Set<string>();
464
+ for (const line of stdout.split("\n")) {
465
+ if (line.startsWith("branch ")) {
466
+ const ref = line.slice("branch ".length).trim();
467
+ // `git worktree list --porcelain` documents `branch` lines as
468
+ // always emitting fully-qualified `refs/heads/<name>` refs.
469
+ // Anything else would be a future git format change; skip
470
+ // unrecognised shapes rather than adding the wrong key (which
471
+ // would mismatch the short-name set the stale-branch check
472
+ // compares against).
473
+ if (ref.startsWith("refs/heads/")) {
474
+ branches.add(ref.slice("refs/heads/".length));
475
+ }
476
+ }
477
+ }
478
+ return branches;
479
+ }
480
+
481
+ /**
482
+ * Run `git worktree list --porcelain` against `vaultPath` and return
483
+ * the set of branch names checked out in live worktrees. Used by the
484
+ * {@link INVARIANT_NO_STALE_DISTILL_BRANCHES_OVER_GRACE} check to
485
+ * avoid deleting branches that are still in use.
486
+ *
487
+ * Returns an empty set when `git worktree list` fails or the vault
488
+ * has no worktrees — conservative, since the worst case is that we
489
+ * attempt to delete a branch that has a live worktree, which
490
+ * `git branch -D` will refuse with a clear error.
491
+ */
492
+ export function parseLiveWorktreeBranches(vaultPath: string): Set<string> {
493
+ const r = spawnSync("git", ["worktree", "list", "--porcelain"], {
494
+ cwd: vaultPath,
495
+ encoding: "utf-8",
496
+ timeout: GIT_SUBCOMMAND_TIMEOUT_MS,
497
+ env: process.env,
498
+ });
499
+ if (r.status !== 0) return new Set();
500
+ return parsePorcelainWorktreeBranches(r.stdout || "");
501
+ }
502
+
503
+ /**
504
+ * Range of the napkin-distill managed block within `<vault>/.gitignore`,
505
+ * in 1-indexed line numbers (matching `git check-ignore -v` output).
506
+ * `beginLine` points at the BEGIN marker; `endLine` at the END marker;
507
+ * the canonical-content lines live STRICTLY between them.
508
+ *
509
+ * `null` when the file is missing or the markers are absent / malformed
510
+ * — the gitignore-block invariant handles the recovery for those
511
+ * cases on the next pass.
512
+ */
513
+ interface ManagedBlockRange {
514
+ beginLine: number;
515
+ endLine: number;
516
+ }
517
+
518
+ /**
519
+ * Read `<giPath>` and locate the napkin-distill managed-block markers.
520
+ * Returns `null` if the file is missing, the markers are absent, or
521
+ * the markers are malformed (multiple BEGINs, BEGIN without matching
522
+ * END, END before BEGIN). The malformed cases are handled by
523
+ * {@link mergeManagedBlock}'s loud-error finding on the same pass; this
524
+ * helper's `null` return signals the caller to skip the inside-block
525
+ * test (treating the line as outside the block, which is the
526
+ * conservative default).
527
+ *
528
+ * Marker matching mirrors {@link mergeManagedBlock}: right-trimmed
529
+ * exact match against {@link BLOCK_MARKER_BEGIN} / {@link
530
+ * BLOCK_MARKER_END}, leading whitespace not tolerated.
531
+ */
532
+ export function parseManagedBlockRange(
533
+ giPath: string,
534
+ ): ManagedBlockRange | null {
535
+ if (!fs.existsSync(giPath)) return null;
536
+ const content = fs.readFileSync(giPath, "utf-8");
537
+ const eol = content.includes("\r\n") ? "\r\n" : "\n";
538
+ const lines = content.length > 0 ? content.split(eol) : [];
539
+ let begin = -1;
540
+ let end = -1;
541
+ let beginCount = 0;
542
+ let endCount = 0;
543
+ for (let i = 0; i < lines.length; i++) {
544
+ const rtrimmed = lines[i].replace(/\s+$/, "");
545
+ if (rtrimmed === BLOCK_MARKER_BEGIN) {
546
+ begin = i;
547
+ beginCount++;
548
+ } else if (rtrimmed === BLOCK_MARKER_END) {
549
+ end = i;
550
+ endCount++;
551
+ }
552
+ }
553
+ if (beginCount !== 1 || endCount !== 1 || begin >= end) return null;
554
+ // Convert to 1-indexed (matches `git check-ignore -v` line numbers).
555
+ return { beginLine: begin + 1, endLine: end + 1 };
556
+ }
557
+
558
+ /**
559
+ * Test whether the gitignore rule at `<source>:<line>` lives strictly
560
+ * inside the managed block defined by `range`. The block markers
561
+ * themselves are gitignore comments (no-op as patterns) so they will
562
+ * not appear in `git check-ignore -v` output; only lines strictly
563
+ * between the markers can be inside the block.
564
+ *
565
+ * `source` is the gitignore source path reported by `git check-ignore
566
+ * -v`; only matches `.gitignore` (the file the managed block lives
567
+ * in) are eligible to be inside the block. Other sources — a global
568
+ * `~/.config/git/ignore`, a parent-directory `.gitignore`, an info/
569
+ * exclude — are by definition outside our managed block, so we
570
+ * report them as outside.
571
+ *
572
+ * Caller passes `null` for `range` when the markers are missing or
573
+ * malformed; in that case every gitignore rule is treated as outside
574
+ * the block (conservative default; the gitignore-block invariant
575
+ * handles the recovery for those cases on the next pass).
576
+ */
577
+ export function isLineInsideBlock(
578
+ source: string,
579
+ line: number,
580
+ range: ManagedBlockRange | null,
581
+ ): boolean {
582
+ if (range === null) return false;
583
+ if (source !== ".gitignore") return false;
584
+ return line > range.beginLine && line < range.endLine;
585
+ }
586
+
587
+ /**
588
+ * Parsed output of `git check-ignore -v`. Format documented in `man
589
+ * git-check-ignore`: `<source> <COLON> <linenum> <COLON> <pattern> <HT>
590
+ * <pathname>`. The first separator before the pathname is a TAB; the
591
+ * source-side fields are colon-separated, with the line number in the
592
+ * middle anchoring the parse (`source` may itself contain colons on
593
+ * absolute Windows paths or when sourced from absolute global ignore
594
+ * files).
595
+ *
596
+ * Returns `null` when the line does not match the expected `-v` shape
597
+ * — conservative, since `git check-ignore` exited 0 so the path IS
598
+ * ignored; we just can't determine where the rule lives. Caller
599
+ * should treat as outside-block in that case (loud error).
600
+ */
601
+ export function parseCheckIgnoreVerbose(
602
+ stdoutLine: string,
603
+ ): { source: string; line: number; pattern: string; pathname: string } | null {
604
+ const tabIdx = stdoutLine.indexOf("\t");
605
+ if (tabIdx < 0) return null;
606
+ const matchInfo = stdoutLine.slice(0, tabIdx);
607
+ const pathname = stdoutLine.slice(tabIdx + 1);
608
+ // Greedy `.+` on source so absolute paths with colons match;
609
+ // anchored on the line-number `\d+` in the middle so the parse
610
+ // remains unambiguous when source/pattern themselves contain
611
+ // colons.
612
+ const m = matchInfo.match(/^(.+):(\d+):(.*)$/);
613
+ if (!m) return null;
614
+ return {
615
+ source: m[1],
616
+ line: parseInt(m[2], 10),
617
+ pattern: m[3],
618
+ pathname,
619
+ };
620
+ }
621
+
622
+ /**
623
+ * Walk upward from `dir` until we find an existing ancestor. The
624
+ * `cache-root-writable` probe fires on a fresh box where
625
+ * `~/.cache/napkin-distill/` doesn't exist yet, so a literal probe
626
+ * against the cache root would always fail with ENOENT — a false
627
+ * positive. Walking up to the first existing ancestor (typically
628
+ * `~/.cache`, occasionally `~`) probes a directory that's actually
629
+ * present and reflects the real writability state.
630
+ *
631
+ * Stops at the filesystem root (`path.dirname("/") === "/"`).
632
+ * Returns `"/"` if every path component along the way is missing,
633
+ * which is impossible in practice (root always exists) but the
634
+ * deterministic shape keeps the helper's contract total.
635
+ */
636
+ export function walkToFirstExistingAncestor(dir: string): string {
637
+ let current = dir;
638
+ while (!fs.existsSync(current)) {
639
+ const parent = path.dirname(current);
640
+ if (parent === current) return current;
641
+ current = parent;
642
+ }
643
+ return current;
644
+ }
645
+
646
+ /**
647
+ * Result of {@link probeWritable}. `writable: true` is the healthy
648
+ * path; `writable: false` carries the underlying error message so
649
+ * the loud-error finding can include the platform-specific reason
650
+ * (EACCES, EROFS, ENOSPC, etc.).
651
+ */
652
+ export interface WritableProbeResult {
653
+ writable: boolean;
654
+ error?: string;
655
+ }
656
+
657
+ /**
658
+ * Probe whether `dir` is writable by writing and removing a
659
+ * temporary file. The filename embeds `Date.now()` plus a random
660
+ * suffix so concurrent probes from parallel pi sessions or test
661
+ * workers on the same directory don't collide.
662
+ *
663
+ * Failures are translated to `{ writable: false, error }` rather than
664
+ * thrown so callers can surface the message in a structured
665
+ * finding. Cleanup of the probe file is best-effort: if writeFileSync
666
+ * succeeds but unlink fails, we still report `writable: true` (the
667
+ * write proves the directory is writable) but the temp file leaks.
668
+ * The leak window is bounded — a subsequent probe on the same path
669
+ * would overwrite if the random suffixes collide; otherwise the OS's
670
+ * tmp-cleanup or a manual `rm` resolves it. We accept that trade-
671
+ * off rather than reporting a false-negative on writability.
672
+ */
673
+ export function probeWritable(dir: string): WritableProbeResult {
674
+ // Filename embeds Date.now() AND a random suffix so concurrent
675
+ // probes from parallel pi sessions or test workers on the same
676
+ // vault don't collide. The suffix is large enough that a same-ms
677
+ // collision across realistic concurrency is statistically
678
+ // negligible.
679
+ const probePath = path.join(
680
+ dir,
681
+ `.napkin-write-probe-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`,
682
+ );
683
+ try {
684
+ fs.writeFileSync(probePath, "");
685
+ } catch (err) {
686
+ return {
687
+ writable: false,
688
+ error: err instanceof Error ? err.message : String(err),
689
+ };
690
+ }
691
+ try {
692
+ fs.unlinkSync(probePath);
693
+ } catch {
694
+ // ignore — see JSDoc.
695
+ }
696
+ return { writable: true };
697
+ }
698
+
699
+ /**
700
+ * Internal result of {@link mergeManagedBlock}.
701
+ *
702
+ * - `changed`: whether the file was created or modified. Callers append
703
+ * `.gitignore` to `scaffolded` when this is `true` so the existing-repo
704
+ * commit branch picks up the change.
705
+ * - `finding`: the structured outcome to surface to the user (auto-
706
+ * recovered for any successful rewrite; error for malformed markers).
707
+ * Absent on the idempotent no-op path.
708
+ */
709
+ interface BlockMergeResult {
710
+ changed: boolean;
711
+ finding?: HealthFinding;
712
+ }
713
+
714
+ /**
715
+ * Reconcile `<filePath>` with a `BEGIN/END`-bracketed canonical block. The
716
+ * file is split into three regions: lines before BEGIN, the bracketed
717
+ * block, and lines after END. Only the bracketed region is rewritten;
718
+ * everything outside is user territory and is preserved byte-identically.
719
+ *
720
+ * Modes (single pass):
721
+ * - Markers absent + no orphan canonical lines elsewhere: install the
722
+ * block at the end of the file (`installed`).
723
+ * - Markers absent + orphan lines in the file matching canonical content:
724
+ * remove orphans + install the block (`migrated from line-by-line`).
725
+ * Covers the v0.3.0 → v0.3.1 line-by-line-to-managed-block migration.
726
+ * - One BEGIN before one END + content matches canonical + no orphans
727
+ * outside: idempotent no-op.
728
+ * - One BEGIN before one END + content drifts (added / removed / reordered
729
+ * entries) + no orphans outside: rewrite the bracketed region in
730
+ * place (`reset`).
731
+ * - One BEGIN before one END + content matches canonical + orphan
732
+ * canonical lines outside: strip the orphans, leave the bracketed
733
+ * region untouched (`migrated from line-by-line`). Covers the
734
+ * partial-migration shape where a previous run installed the block
735
+ * and a later edit re-introduced duplicates above it.
736
+ * - One BEGIN before one END + content drifts + orphan canonical lines
737
+ * outside: rewrite the bracketed region AND strip the orphans on
738
+ * the same pass (`reset and migrated from line-by-line`). Compound
739
+ * case for vaults that drifted inside the block while also keeping
740
+ * stray duplicates outside.
741
+ * - Multiple BEGIN markers, one without a matching END, or END before
742
+ * BEGIN: malformed. Emit a loud-error finding and leave the file
743
+ * untouched so the user can resolve manually.
162
744
  *
163
- * Creates the file if it doesn't exist. Preserves the existing content
164
- * verbatim otherwise — we never rewrite or re-order user lines.
745
+ * Marker matching requires the exact suffix (configured via the
746
+ * `beginMarker` / `endMarker` arguments) so unrelated `# BEGIN ...`-style
747
+ * markers in user content do not collide with our detection.
165
748
  */
166
- function mergeLines(filePath: string, newLines: readonly string[]): boolean {
749
+ function mergeManagedBlock(
750
+ filePath: string,
751
+ beginMarker: string,
752
+ endMarker: string,
753
+ blockContent: readonly string[],
754
+ ): BlockMergeResult {
167
755
  const existed = fs.existsSync(filePath);
168
756
  const existing = existed ? fs.readFileSync(filePath, "utf-8") : "";
169
- const existingSet = new Set(
170
- existing
171
- .split("\n")
757
+ // Detect the existing file's line-ending convention so we can
758
+ // round-trip it on write. Windows-checkout vaults often store
759
+ // `.gitignore` with CRLF; rewriting with bare LF would silently
760
+ // strip the `\r` from every line and look like spurious churn in
761
+ // git diffs. Default to LF for new files (matches the rest of the
762
+ // repo's TS-code conventions).
763
+ const eol: "\n" | "\r\n" = existing.includes("\r\n") ? "\r\n" : "\n";
764
+ // Split into lines while preserving the trailing-newline shape: a
765
+ // file ending in EOL produces a trailing empty element from `split`,
766
+ // which `join` reproduces faithfully on write. Empty file (no bytes
767
+ // OR no trailing newline) is normalised to an empty array.
768
+ const lines = existing.length > 0 ? existing.split(eol) : [];
769
+ const hadTrailingNewline = existing.endsWith(eol);
770
+ // Drop the trailing empty produced by `split` on `...EOL`; we'll restore
771
+ // the newline at write time. Keeps `lines` a clean array of content lines.
772
+ if (hadTrailingNewline && lines.length > 0 && lines[lines.length - 1] === "")
773
+ lines.pop();
774
+
775
+ // Locate markers (compare on right-trimmed content to tolerate trailing
776
+ // whitespace, but reject leading whitespace — indented markers are not
777
+ // ours and shouldn't match).
778
+ const beginIndices: number[] = [];
779
+ const endIndices: number[] = [];
780
+ for (let i = 0; i < lines.length; i++) {
781
+ const rtrimmed = lines[i].replace(/\s+$/, "");
782
+ if (rtrimmed === beginMarker) beginIndices.push(i);
783
+ else if (rtrimmed === endMarker) endIndices.push(i);
784
+ }
785
+
786
+ const wellFormed =
787
+ beginIndices.length === 1 &&
788
+ endIndices.length === 1 &&
789
+ beginIndices[0] < endIndices[0];
790
+ const markersAbsent = beginIndices.length === 0 && endIndices.length === 0;
791
+
792
+ if (!wellFormed && !markersAbsent) {
793
+ // Multiple BEGINs, BEGIN without END, or END before BEGIN. Refuse to
794
+ // touch the file — a heuristic auto-fix risks shredding user content.
795
+ return {
796
+ changed: false,
797
+ finding: {
798
+ kind: "error",
799
+ invariant: INVARIANT_GITIGNORE_BLOCK,
800
+ message: `${filePath} contains malformed napkin-distill managed-block markers; resolve manually before distill can proceed.`,
801
+ },
802
+ };
803
+ }
804
+
805
+ // Set of canonical non-blank, non-comment entries. Used to detect
806
+ // orphan lines anywhere outside the managed block (line-by-line
807
+ // residue from v0.3.0).
808
+ const canonicalNonComment = new Set(
809
+ blockContent
172
810
  .map((l) => l.trim())
173
811
  .filter((l) => l.length > 0 && !l.startsWith("#")),
174
812
  );
175
813
 
176
- const toAppend: string[] = [];
177
- let sawMeaningful = false;
178
- for (const line of newLines) {
179
- const trimmed = line.trim();
180
- if (trimmed.length === 0 || trimmed.startsWith("#")) {
181
- // Only keep headers/spacers if there's at least one real line to append
182
- // below them. We can't decide that until we've scanned the whole block,
183
- // so buffer optimistically and trim at the end.
184
- toAppend.push(line);
185
- continue;
814
+ const writeFile = (out: string[]): void => {
815
+ const body = out.join(eol);
816
+ // POSIX convention: gitignore ends with a newline. Always emit one
817
+ // (in the file's detected EOL) when we're rewriting; it's harmless
818
+ // if the original already had one and a fix-up if it didn't.
819
+ fs.writeFileSync(filePath, body.endsWith(eol) ? body : `${body}${eol}`);
820
+ };
821
+
822
+ if (markersAbsent) {
823
+ // Identify orphan canonical lines anywhere in the file and drop
824
+ // them; then append the block.
825
+ const orphanIndices = new Set<number>();
826
+ for (let i = 0; i < lines.length; i++) {
827
+ const trimmed = lines[i].trim();
828
+ if (canonicalNonComment.has(trimmed)) orphanIndices.add(i);
186
829
  }
187
- if (!existingSet.has(trimmed)) {
188
- toAppend.push(line);
189
- sawMeaningful = true;
830
+
831
+ const out: string[] = [];
832
+ for (let i = 0; i < lines.length; i++) {
833
+ if (!orphanIndices.has(i)) out.push(lines[i]);
190
834
  }
835
+ // Visual separator between user content and the appended block:
836
+ // ensure a single blank line precedes BEGIN if the file had any
837
+ // content left.
838
+ if (out.length > 0 && out[out.length - 1].trim() !== "") out.push("");
839
+ out.push(beginMarker, ...blockContent, endMarker);
840
+ writeFile(out);
841
+
842
+ const flavor =
843
+ orphanIndices.size > 0 ? "migrated from line-by-line" : "installed";
844
+ return {
845
+ changed: true,
846
+ finding: {
847
+ kind: "auto-recovered",
848
+ invariant: INVARIANT_GITIGNORE_BLOCK,
849
+ message:
850
+ flavor === "migrated from line-by-line"
851
+ ? `${filePath} had unmanaged napkin-distill entries; migrated to managed block.`
852
+ : `${filePath} did not contain a napkin-distill managed block; installed.`,
853
+ recovery: flavor,
854
+ },
855
+ };
191
856
  }
192
857
 
193
- if (!sawMeaningful) {
194
- // File already has everything meaningful — no change needed even if we
195
- // accumulated section headers in `toAppend`.
196
- return false;
858
+ // Markers well-formed: compare bracketed content vs canonical, and
859
+ // sweep for orphans outside the block.
860
+ const beginIdx = beginIndices[0];
861
+ const endIdx = endIndices[0];
862
+ const blockLines = lines.slice(beginIdx + 1, endIdx);
863
+ const blockMatches =
864
+ blockLines.length === blockContent.length &&
865
+ blockLines.every(
866
+ (l, i) => l.replace(/\s+$/, "") === blockContent[i].replace(/\s+$/, ""),
867
+ );
868
+
869
+ const orphanOutside = new Set<number>();
870
+ for (let i = 0; i < lines.length; i++) {
871
+ if (i >= beginIdx && i <= endIdx) continue;
872
+ const trimmed = lines[i].trim();
873
+ if (canonicalNonComment.has(trimmed)) orphanOutside.add(i);
197
874
  }
198
875
 
199
- // Prefix with a blank line if the existing file doesn't end with one, so
200
- // appended sections are visually separated.
201
- let prefix = "";
202
- if (existed && existing.length > 0 && !existing.endsWith("\n")) prefix = "\n";
203
- else if (existed && existing.length > 0 && !existing.endsWith("\n\n"))
204
- prefix = "\n";
876
+ if (blockMatches && orphanOutside.size === 0) {
877
+ return { changed: false };
878
+ }
205
879
 
206
- const body = `${toAppend.join("\n")}\n`;
207
- fs.writeFileSync(filePath, existing + prefix + body);
208
- return true;
880
+ const out: string[] = [];
881
+ for (let i = 0; i < lines.length; i++) {
882
+ if (i === beginIdx) {
883
+ out.push(beginMarker, ...blockContent, endMarker);
884
+ i = endIdx;
885
+ continue;
886
+ }
887
+ if (orphanOutside.has(i)) continue;
888
+ out.push(lines[i]);
889
+ }
890
+ writeFile(out);
891
+
892
+ let recovery: string;
893
+ let message: string;
894
+ if (!blockMatches && orphanOutside.size > 0) {
895
+ recovery = "reset and migrated from line-by-line";
896
+ message = `${filePath} managed block drifted and orphan canonical lines were present outside it; reset block and removed orphans.`;
897
+ } else if (!blockMatches) {
898
+ recovery = "reset";
899
+ message = `${filePath} managed block content drifted from canonical; reset in place.`;
900
+ } else {
901
+ recovery = "migrated from line-by-line";
902
+ message = `${filePath} had orphan canonical lines outside the managed block; removed.`;
903
+ }
904
+ return {
905
+ changed: true,
906
+ finding: {
907
+ kind: "auto-recovered",
908
+ invariant: INVARIANT_GITIGNORE_BLOCK,
909
+ message,
910
+ recovery,
911
+ },
912
+ };
209
913
  }
210
914
 
211
915
  /**
212
916
  * Ensure `<vaultPath>` is a git repo with a `.gitignore` that covers
213
- * auto-distill's needs. Called once per `session_start` when
214
- * `distill.enabled` is true.
917
+ * distill's needs and (at full level) tracks `<configPath>/config.json`.
918
+ * Called at `session_start` (`level: "fast"`) and again before every
919
+ * worktree-based spawn (`level: "full"`).
215
920
  *
216
- * Lifecycle:
217
- * 0. Refuse if the vault uses napkin's legacy embedded layout
218
- * (`configPath === contentPath`). Worktree-based concurrency doesn't
219
- * work on legacy layouts because the branch can't track a `.napkin/`
220
- * subdir that findVault could resolve to. Returns `{ error:
221
- * "legacy-embedded-layout", legacyLayout }` without touching git.
222
- * 1. If `.git/` is missing → `git init`. Failure here aborts with `error`.
223
- * 2. Merge scaffolding lines into `.gitignore` (idempotent; no-op if
224
- * already present).
225
- * 3. If anything changed:
226
- * - fresh init → `git add .` + commit `"napkin: initial vault commit
227
- * (auto-distill setup)"`
228
- * - existing repo → `git add .gitignore` + commit
229
- * `"napkin: scaffold auto-distill git config"`
921
+ * Lifecycle (in execution order; per-step level scope noted):
922
+ * 0. fast + full: refuse if the vault uses napkin's legacy embedded
923
+ * layout (`configPath === contentPath`). Worktree-based concurrency
924
+ * doesn't work on legacy layouts because the branch can't track a
925
+ * `.napkin/` subdir that findVault could resolve to. Returns
926
+ * `{ error: "legacy-embedded-layout", legacyLayout, findings:
927
+ * [subdir-layout error] }` without touching git.
928
+ * 1. fast + full: if `.git/` is missing, run `git init -q -b main`
929
+ * (`vault-is-git-repo`, auto-recovered). Failure here aborts with
930
+ * `error`. (JSON validity is checked earlier by
931
+ * {@link loadVaultConfig} and is not re-checked here.)
932
+ * 2. fast + full: reconcile `.gitignore` against the canonical managed
933
+ * block (`gitignore-block-correct`). Auto-recovered for
934
+ * install / reset / migration; loud-error for malformed markers.
935
+ * 3. full only: if `<configPath>/config.json` is untracked, stage it
936
+ * (`config.json-tracked`, auto-recovered) so the next
937
+ * `git worktree add HEAD` copies it into the worktree. Closes
938
+ * Issue #14. Skipped at fast level to keep session_start latency
939
+ * under the ~10 ms target.
940
+ * 4. full only: refuse to spawn if `<configPath>/config.json` is
941
+ * gitignored by a rule outside the managed block
942
+ * (`config.json-not-gitignored-outside-block`, loud-error).
943
+ * User-territory ignore rules are explicit user choices that we
944
+ * can't auto-rewrite without losing intent.
945
+ * 5. full only: refuse to spawn if `<configPath>/distill/` contains
946
+ * tracked files (`napkin-distill-not-tracked`, loud-error). The
947
+ * canonical {@link BLOCK_CONTENT} gitignores the directory; a
948
+ * tracked entry is either a stale pre-block commit or an
949
+ * explicit `git add -f`, both of which we surface for the user
950
+ * to resolve manually.
951
+ * 6. full only: probe the cache root parent for write access via
952
+ * {@link probeWritable} (`cache-root-writable`, loud-error). A
953
+ * read-only cache root would fail the worktree spawn at
954
+ * `mkdir -p`; surfacing here gives the user a fixable error
955
+ * before any git work commits to a worktree.
956
+ * 7. fast + full: if anything in steps 1–3 changed:
957
+ * - fresh init -> `git add .` + commit `"napkin: initial vault
958
+ * commit (auto-distill setup)"`
959
+ * - existing repo with scaffolded changes -> `git add ...scaffolded`
960
+ * + commit `"napkin: scaffold auto-distill git config"`
961
+ * 8. full only: ensure HEAD resolves to a commit; seed an empty
962
+ * initial commit when an existing-but-empty repo would leave
963
+ * `git worktree add HEAD` unable to pin a ref
964
+ * (`vault-head-on-branch`, auto-recovered). Fast-level skips
965
+ * so a `session_start` on a hand-bootstrapped repo doesn't
966
+ * seed an unsolicited commit; the next full-level call (tick,
967
+ * shutdown, or manual `/distill`) seeds lazily when a worktree
968
+ * spawn is imminent.
969
+ * 9. full only: prune orphaned distill worktree registry entries
970
+ * via `git worktree prune --expire=now`
971
+ * (`no-orphaned-distill-worktrees`, auto-recovered). Cleans up
972
+ * registry entries whose worktree directories were removed
973
+ * (typically a crashed pi session) so they don't accumulate.
974
+ * 10. full only: delete `distill/*` branches whose committerdate is
975
+ * older than {@link STALE_DISTILL_BRANCH_GRACE_MS} AND have no
976
+ * live worktree (`no-stale-distill-branches-over-grace`,
977
+ * auto-recovered). The grace gives the user a `git reflog`
978
+ * window to recover content from a failed distill before the
979
+ * branch tip is collected.
230
980
  *
231
- * Returned `scaffolded` always uses vault-relative paths so notify messages
232
- * are compact and portable.
981
+ * Returned `scaffolded` always uses vault-relative paths so notify
982
+ * messages are compact and portable.
233
983
  */
234
- export function ensureVaultReadyForAutoDistill(vault: SetupVault): SetupResult {
984
+ export function ensureVaultReadyForDistill(
985
+ vault: SetupVault,
986
+ level: HealthLevel,
987
+ options: SetupOptions = {},
988
+ ): SetupResult {
235
989
  const vaultPath = vault.contentPath;
990
+ const findings: HealthFinding[] = [];
236
991
 
237
992
  // Legacy-embedded layout is incompatible with the worktree-based
238
993
  // concurrency architecture. In a legacy vault (`~/.napkin/`), the
@@ -252,11 +1007,17 @@ export function ensureVaultReadyForAutoDistill(vault: SetupVault): SetupResult {
252
1007
  // while legacy embedded layout has no `vault.root` and defaults both to
253
1008
  // the `.napkin/` dir. See `@cad0p/napkin` `dist/utils/vault.js`.
254
1009
  if (vault.configPath === vault.contentPath) {
1010
+ findings.push({
1011
+ kind: "error",
1012
+ invariant: INVARIANT_SUBDIR_LAYOUT,
1013
+ message: `Vault at ${vaultPath} uses the legacy embedded layout (configPath === contentPath); auto-distill requires the subdir layout.`,
1014
+ });
255
1015
  return {
256
1016
  initialized: false,
257
1017
  scaffolded: [],
258
1018
  error: LEGACY_EMBEDDED_LAYOUT_ERROR,
259
1019
  legacyLayout: { configPath: vault.configPath },
1020
+ findings,
260
1021
  };
261
1022
  }
262
1023
 
@@ -270,16 +1031,30 @@ export function ensureVaultReadyForAutoDistill(vault: SetupVault): SetupResult {
270
1031
  initialized: false,
271
1032
  scaffolded: [],
272
1033
  error: `git init failed: ${init.stderr.trim() || "unknown error"}`,
1034
+ findings,
273
1035
  };
274
1036
  }
275
1037
  initialized = true;
1038
+ findings.push({
1039
+ kind: "auto-recovered",
1040
+ invariant: INVARIANT_VAULT_IS_GIT_REPO,
1041
+ message: `Initialized git repo at ${vaultPath}.`,
1042
+ recovery: "ran git init",
1043
+ });
276
1044
  }
277
1045
 
278
1046
  const scaffolded: string[] = [];
279
1047
 
280
1048
  try {
281
1049
  const giPath = path.join(vaultPath, ".gitignore");
282
- if (mergeLines(giPath, GITIGNORE_LINES)) scaffolded.push(".gitignore");
1050
+ const blockResult = mergeManagedBlock(
1051
+ giPath,
1052
+ BLOCK_MARKER_BEGIN,
1053
+ BLOCK_MARKER_END,
1054
+ BLOCK_CONTENT,
1055
+ );
1056
+ if (blockResult.changed) scaffolded.push(".gitignore");
1057
+ if (blockResult.finding) findings.push(blockResult.finding);
283
1058
  // PR #12: no `.gitattributes` scaffolding. Pre-PR-12 we wrote an
284
1059
  // `*.md merge=napkin-distill-merge` line; the agent-driven merge
285
1060
  // architecture has no driver to register.
@@ -289,14 +1064,153 @@ export function ensureVaultReadyForAutoDistill(vault: SetupVault): SetupResult {
289
1064
  initialized,
290
1065
  scaffolded,
291
1066
  error: `failed to write scaffolding: ${msg}`,
1067
+ findings,
292
1068
  };
293
1069
  }
294
1070
 
1071
+ // Full-level only: confirm `<configPath>/config.json` is tracked by
1072
+ // git. Distill worktrees are checked out via `git worktree add HEAD`
1073
+ // which only copies tracked files — an untracked config.json never
1074
+ // reaches the worktree and napkin's findVault falls back to legacy
1075
+ // embedded layout. Closes Issue #14. Auto-recovers by adding the file
1076
+ // to scaffolded[] so the existing-repo branch below stages and
1077
+ // commits it on the same pass.
1078
+ //
1079
+ // The auto-recovered finding is held back as `pending` and only
1080
+ // pushed onto `findings[]` after the eventual `git add` succeeds.
1081
+ // In the cumulative scenario where the file is also gitignored
1082
+ // outside the managed block (loud-error finding emitted just
1083
+ // below), `git add` will refuse to stage the file and the
1084
+ // existing-repo branch returns with `setup.error`. Pushing the
1085
+ // recovery finding eagerly would produce a false info notify
1086
+ // ("staged for commit") alongside the error notify.
1087
+ let pendingConfigJsonTrackedFinding: HealthFinding | undefined;
1088
+ if (level === "full") {
1089
+ const configRel = path.relative(
1090
+ vaultPath,
1091
+ path.join(vault.configPath, "config.json"),
1092
+ );
1093
+ if (fs.existsSync(path.join(vaultPath, configRel))) {
1094
+ const tracked = runGit(vaultPath, [
1095
+ "ls-files",
1096
+ "--error-unmatch",
1097
+ configRel,
1098
+ ]);
1099
+ if (tracked.status !== 0) {
1100
+ scaffolded.push(configRel);
1101
+ pendingConfigJsonTrackedFinding = {
1102
+ kind: "auto-recovered",
1103
+ invariant: INVARIANT_CONFIG_JSON_TRACKED,
1104
+ message: `${configRel} was untracked; staged for commit.`,
1105
+ recovery: `git add ${configRel}`,
1106
+ };
1107
+ }
1108
+
1109
+ // Refuse to spawn if the user gitignored `config.json` outside
1110
+ // the napkin-distill managed block. Inside-block drift is
1111
+ // handled automatically by the gitignore-block reset (the
1112
+ // canonical block does not gitignore `config.json`); outside-
1113
+ // block rules are explicit user choices, so we surface a loud
1114
+ // error and let the user decide. The check fires regardless of
1115
+ // whether the file is currently tracked: a user-added rule is
1116
+ // a hazard either way (a future `git rm --cached` would
1117
+ // silently re-untrack the file and the worktree-copy path
1118
+ // breaks).
1119
+ // `--no-index` is load-bearing: without it `git check-ignore`
1120
+ // skips paths already in the index, which would silently disable
1121
+ // this finding the moment the auto-recover stages `config.json`
1122
+ // (i.e. on every healthy second-and-later run). The check must
1123
+ // fire regardless of tracked-state — see the comment above.
1124
+ const ignored = runGit(vaultPath, [
1125
+ "check-ignore",
1126
+ "-v",
1127
+ "--no-index",
1128
+ configRel,
1129
+ ]);
1130
+ if (ignored.status === 0) {
1131
+ const giPathFull = path.join(vaultPath, ".gitignore");
1132
+ const blockRange = parseManagedBlockRange(giPathFull);
1133
+ // `check-ignore -v` may emit one rule per line for paths matched
1134
+ // by multiple ignores (rare; only the last one wins as the
1135
+ // effective rule, but earlier matches are still reported).
1136
+ // Walk every line; if ANY rule is outside the managed block
1137
+ // we surface the error — a user-territory rule is a hazard
1138
+ // even if a managed-block rule also matches.
1139
+ for (const line of ignored.stdout.split("\n")) {
1140
+ if (line.length === 0) continue;
1141
+ const parsed = parseCheckIgnoreVerbose(line);
1142
+ if (!parsed) continue;
1143
+ if (!isLineInsideBlock(parsed.source, parsed.line, blockRange)) {
1144
+ findings.push({
1145
+ kind: "error",
1146
+ invariant: INVARIANT_CONFIG_JSON_NOT_GITIGNORED_OUTSIDE_BLOCK,
1147
+ message: `${configRel} is gitignored at ${parsed.source}:${parsed.line} (outside the napkin-distill managed block); auto-distill cannot track it. Remove the rule from ${parsed.source} or restart pi after fixing it.`,
1148
+ });
1149
+ break;
1150
+ }
1151
+ }
1152
+ }
1153
+ }
1154
+
1155
+ // Refuse to spawn if `<configPath>/distill/` contains tracked
1156
+ // files. The canonical {@link BLOCK_CONTENT} gitignores this
1157
+ // directory — a tracked entry typically means a stale commit
1158
+ // from before the gitignore block was installed, OR a user who
1159
+ // explicitly ran `git add -f`. Auto-untracking via `git rm
1160
+ // --cached -r` could discard staged changes, so we surface a
1161
+ // loud error and let the user resolve manually.
1162
+ const distillRel = path.relative(
1163
+ vaultPath,
1164
+ path.join(vault.configPath, "distill"),
1165
+ );
1166
+ const distillTracked = runGit(vaultPath, [
1167
+ "ls-files",
1168
+ "--",
1169
+ `${distillRel}/`,
1170
+ ]);
1171
+ const trackedDistillPaths = distillTracked.stdout
1172
+ .split("\n")
1173
+ .filter((l) => l.length > 0);
1174
+ if (trackedDistillPaths.length > 0) {
1175
+ // Cap the list embedded in the message so a runaway commit
1176
+ // doesn't bloat the notify text. Three is enough to be
1177
+ // diagnostic; the rest are summarised by count.
1178
+ const sample = trackedDistillPaths.slice(0, 3);
1179
+ const remainder = trackedDistillPaths.length - sample.length;
1180
+ const tail = remainder > 0 ? ` (+${remainder} more)` : "";
1181
+ findings.push({
1182
+ kind: "error",
1183
+ invariant: INVARIANT_NAPKIN_DISTILL_NOT_TRACKED,
1184
+ message: `${distillRel}/ contains tracked files [${sample.join(", ")}]${tail}; auto-untrack would risk data loss. Run \`git rm --cached -r ${distillRel}/\` manually.`,
1185
+ });
1186
+ }
1187
+
1188
+ // Probe writability of the cache root's first existing ancestor.
1189
+ // Walking up handles the fresh-box case where
1190
+ // `~/.cache/napkin-distill/` does not yet exist; the probe lands
1191
+ // on `~/.cache` (typically) and reflects the real writability
1192
+ // state. The probe is injectable via `options.probeWritable` so
1193
+ // tests can exercise the unwritable path without touching
1194
+ // `chmod 0500` (which false-passes under root in CI) or
1195
+ // platform-specific read-only mounts.
1196
+ const probe = options.probeWritable ?? probeWritable;
1197
+ const cacheRoot = resolveCacheRoot(vault.contentPath);
1198
+ const probeDir = walkToFirstExistingAncestor(path.dirname(cacheRoot));
1199
+ const probeResult = probe(probeDir);
1200
+ if (!probeResult.writable) {
1201
+ findings.push({
1202
+ kind: "error",
1203
+ invariant: INVARIANT_CACHE_ROOT_WRITABLE,
1204
+ message: `Cache root parent ${probeDir} is not writable: ${probeResult.error ?? "unknown error"}. Set XDG_CACHE_HOME to a writable directory or fix the permissions.`,
1205
+ });
1206
+ }
1207
+ }
1208
+
295
1209
  if (initialized) {
296
1210
  // Fresh init: commit the entire vault so auto-distill has a HEAD to
297
1211
  // branch from. `git add .` respects the just-written .gitignore so we
298
1212
  // don't accidentally stage `.napkin/distill/` (the per-worktree
299
- // session fork) or common secret files (see GITIGNORE_LINES). Distill
1213
+ // session fork) or common secret files (see BLOCK_CONTENT). Distill
300
1214
  // worktrees themselves live OUTSIDE the vault now (XDG cache), so
301
1215
  // there's no in-vault worktrees/ path to exclude.
302
1216
  const add = runGit(vaultPath, ["add", "."]);
@@ -305,6 +1219,7 @@ export function ensureVaultReadyForAutoDistill(vault: SetupVault): SetupResult {
305
1219
  initialized,
306
1220
  scaffolded,
307
1221
  error: `git add failed: ${add.stderr.trim() || "unknown error"}`,
1222
+ findings,
308
1223
  };
309
1224
  }
310
1225
  const commit = runGit(vaultPath, [
@@ -318,8 +1233,12 @@ export function ensureVaultReadyForAutoDistill(vault: SetupVault): SetupResult {
318
1233
  initialized,
319
1234
  scaffolded,
320
1235
  error: `git commit failed: ${commit.stderr.trim() || "unknown error"}`,
1236
+ findings,
321
1237
  };
322
1238
  }
1239
+ if (pendingConfigJsonTrackedFinding) {
1240
+ findings.push(pendingConfigJsonTrackedFinding);
1241
+ }
323
1242
  } else if (scaffolded.length > 0) {
324
1243
  // Existing repo: only stage the scaffolding files so we don't sweep in
325
1244
  // the user's unrelated working changes.
@@ -329,6 +1248,7 @@ export function ensureVaultReadyForAutoDistill(vault: SetupVault): SetupResult {
329
1248
  initialized,
330
1249
  scaffolded,
331
1250
  error: `git add failed: ${add.stderr.trim() || "unknown error"}`,
1251
+ findings,
332
1252
  };
333
1253
  }
334
1254
  const commit = runGit(vaultPath, [
@@ -342,41 +1262,133 @@ export function ensureVaultReadyForAutoDistill(vault: SetupVault): SetupResult {
342
1262
  initialized,
343
1263
  scaffolded,
344
1264
  error: `git commit failed: ${commit.stderr.trim() || "unknown error"}`,
1265
+ findings,
345
1266
  };
346
1267
  }
1268
+ if (pendingConfigJsonTrackedFinding) {
1269
+ findings.push(pendingConfigJsonTrackedFinding);
1270
+ }
347
1271
  }
348
1272
 
349
- // HEAD-valid invariant: createDistillWorktree requires HEAD to resolve
350
- // to a commit. The paths above (fresh init OR existing repo + scaffolded
351
- // files) produce a commit; the idempotent path (existing repo, nothing
352
- // to scaffold) does NOT — so a vault where someone ran `git init` by
353
- // hand and never committed leaves HEAD unresolvable. Seed an empty
354
- // initial commit so `git worktree add ... HEAD` has something to pin to.
355
- // This also covers the narrow window where `git init` succeeded above
356
- // (we set `initialized = true`) but scaffolding wrote zero lines
357
- // (`.gitignore` already present with our exact content) — that would
358
- // fall into neither branch and leave a commit-less repo.
1273
+ // HEAD-valid invariant: createDistillWorktree requires HEAD to
1274
+ // resolve to a commit. The paths above (fresh init OR existing repo
1275
+ // + scaffolded files) produce a commit; the idempotent path
1276
+ // (existing repo, nothing to scaffold) does NOT — so a vault where
1277
+ // someone ran `git init` by hand and never committed leaves HEAD
1278
+ // unresolvable. Seed an empty initial commit so `git worktree add
1279
+ // ... HEAD` has something to pin to. This also covers the narrow
1280
+ // window where `git init` succeeded above (we set
1281
+ // `initialized = true`) but scaffolding wrote zero lines
1282
+ // (`.gitignore` already present with our exact content) — that
1283
+ // would fall into neither branch and leave a commit-less repo.
1284
+ //
1285
+ // Full-level only: a session_start fast-level call on a vault
1286
+ // whose HEAD is currently unresolvable returns clean (no seed,
1287
+ // empty findings). The seed fires lazily on the next full-level
1288
+ // call (auto-distill tick, session_shutdown, or manual /distill
1289
+ // on subdir-layout) where a worktree-based spawn is imminent.
1290
+ // Avoids seeding an unsolicited commit at session_start on
1291
+ // vaults the user is still bootstrapping by hand.
359
1292
  let seededCommit: SetupResult["seededCommit"];
360
- const headAfter = runGit(vaultPath, ["rev-parse", "--verify", "HEAD"]);
361
- if (headAfter.status !== 0) {
362
- const seed = runGit(vaultPath, [
363
- "commit",
364
- "--allow-empty",
365
- "-q",
366
- "-m",
367
- "napkin: initial vault commit (auto-distill setup)",
1293
+ if (level === "full") {
1294
+ const headAfter = runGit(vaultPath, ["rev-parse", "--verify", "HEAD"]);
1295
+ if (headAfter.status !== 0) {
1296
+ const seed = runGit(vaultPath, [
1297
+ "commit",
1298
+ "--allow-empty",
1299
+ "-q",
1300
+ "-m",
1301
+ "napkin: initial vault commit (auto-distill setup)",
1302
+ ]);
1303
+ if (seed.status !== 0) {
1304
+ return {
1305
+ initialized,
1306
+ scaffolded,
1307
+ error: `git seed commit failed: ${seed.stderr.trim() || "unknown error"}`,
1308
+ findings,
1309
+ };
1310
+ }
1311
+ seededCommit = true;
1312
+ findings.push({
1313
+ kind: "auto-recovered",
1314
+ invariant: INVARIANT_VAULT_HEAD_ON_BRANCH,
1315
+ message: `${vaultPath} had a git repo with no commits; seeded empty initial commit so worktree spawn can pin HEAD.`,
1316
+ recovery: "git commit --allow-empty",
1317
+ });
1318
+ }
1319
+
1320
+ // Orphaned distill worktree-registry entries: `git worktree prune
1321
+ // --verbose --expire=now` removes entries whose worktree
1322
+ // directories have been deleted (typically a crashed pi session).
1323
+ // Prune is safe — it only touches entries pointing at missing
1324
+ // dirs. `--expire=now` overrides git's default 3-month grace
1325
+ // (`gc.worktreePruneExpire`) so freshly-orphaned entries are
1326
+ // cleaned up on the next health check rather than lingering for
1327
+ // months.
1328
+ const prune = runGit(vaultPath, [
1329
+ "worktree",
1330
+ "prune",
1331
+ "--verbose",
1332
+ "--expire=now",
368
1333
  ]);
369
- if (seed.status !== 0) {
370
- return {
371
- initialized,
372
- scaffolded,
373
- error: `git seed commit failed: ${seed.stderr.trim() || "unknown error"}`,
374
- };
1334
+ // `git worktree prune --verbose` emits its progress to stderr,
1335
+ // not stdout. Combine both streams so the recovery text reflects
1336
+ // every removed registry entry regardless of git's output
1337
+ // routing.
1338
+ const pruneOut = `${prune.stdout}\n${prune.stderr}`.trim();
1339
+ if (pruneOut.length > 0) {
1340
+ findings.push({
1341
+ kind: "auto-recovered",
1342
+ invariant: INVARIANT_NO_ORPHANED_DISTILL_WORKTREES,
1343
+ message: `Pruned orphaned distill worktree registry entries.`,
1344
+ recovery: pruneOut,
1345
+ });
1346
+ }
1347
+
1348
+ // Stale distill branches: any `distill/*` branch with
1349
+ // committerdate older than STALE_DISTILL_BRANCH_GRACE_MS AND no
1350
+ // live worktree pointing at it gets deleted. Reflog grace gives
1351
+ // users a recovery window for content from a failed distill.
1352
+ // Boundary: branches AT exactly the grace age are NOT deleted
1353
+ // (strict `>` comparison) so the boundary tests can pin the
1354
+ // "just under threshold" case deterministically.
1355
+ const branches = runGit(vaultPath, [
1356
+ "for-each-ref",
1357
+ "refs/heads/distill/",
1358
+ "--format=%(refname:short) %(committerdate:unix)",
1359
+ ]);
1360
+ const liveWorktreeBranches = parseLiveWorktreeBranches(vaultPath);
1361
+ const now = (options.now ?? Date.now)();
1362
+ for (const line of branches.stdout.split("\n")) {
1363
+ if (line.length === 0) continue;
1364
+ const spaceIdx = line.lastIndexOf(" ");
1365
+ if (spaceIdx < 0) continue;
1366
+ const refname = line.slice(0, spaceIdx).trim();
1367
+ const tsStr = line.slice(spaceIdx + 1).trim();
1368
+ const tsSec = parseInt(tsStr, 10);
1369
+ if (!refname || !Number.isFinite(tsSec)) continue;
1370
+ const ageMs = now - tsSec * 1000;
1371
+ if (
1372
+ ageMs > STALE_DISTILL_BRANCH_GRACE_MS &&
1373
+ !liveWorktreeBranches.has(refname)
1374
+ ) {
1375
+ const del = runGit(vaultPath, ["branch", "-D", refname]);
1376
+ if (del.status === 0) {
1377
+ findings.push({
1378
+ kind: "auto-recovered",
1379
+ invariant: INVARIANT_NO_STALE_DISTILL_BRANCHES_OVER_GRACE,
1380
+ message: `Deleted stale distill branch ${refname} (${Math.round(ageMs / MS_PER_HOUR)}h old, no live worktree).`,
1381
+ recovery: `git branch -D ${refname}`,
1382
+ });
1383
+ }
1384
+ // If `git branch -D` fails (e.g. the branch is checked out
1385
+ // somewhere we couldn't detect), skip the finding rather
1386
+ // than emit a confusing "deleted" message.
1387
+ }
375
1388
  }
376
- seededCommit = true;
377
1389
  }
378
1390
 
379
- return { initialized, scaffolded, seededCommit };
1391
+ return { initialized, scaffolded, seededCommit, findings };
380
1392
  }
381
1393
 
382
1394
  /**