@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.
- package/README.md +73 -5
- package/extensions/distill/auto-setup.ts +1123 -111
- package/extensions/distill/health-notify.ts +121 -0
- package/extensions/distill/index.ts +277 -75
- package/extensions/napkin-context/index.ts +2 -2
- package/package.json +2 -2
|
@@ -1,41 +1,91 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
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`
|
|
5
|
-
* excludes its ephemeral state (distill worktrees, Obsidian
|
|
6
|
-
* caches)
|
|
7
|
-
*
|
|
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
|
|
10
|
-
* `*.md merge=napkin-distill-merge` rule in `.gitattributes` to
|
|
11
|
-
* concurrent-distill conflicts through an LLM merge driver. PR
|
|
12
|
-
* that driver — the distill agent now resolves merges
|
|
13
|
-
* worktree, so the rule is no longer needed. New vaults
|
|
14
|
-
* installed. Existing vaults that already have it
|
|
15
|
-
* cleanup; the rule becomes inert once the
|
|
16
|
-
* silently falls back to its built-in
|
|
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
|
|
21
|
-
* `{ initialized: false, scaffolded: [] }`
|
|
22
|
-
*
|
|
23
|
-
*
|
|
24
|
-
*
|
|
25
|
-
*
|
|
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 {
|
|
51
|
+
import {
|
|
52
|
+
GIT_SUBCOMMAND_TIMEOUT_MS,
|
|
53
|
+
resolveCacheRoot,
|
|
54
|
+
} from "./distill-workspace";
|
|
33
55
|
|
|
34
56
|
/**
|
|
35
|
-
*
|
|
36
|
-
*
|
|
37
|
-
*
|
|
38
|
-
*
|
|
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
|
-
*
|
|
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
|
-
*
|
|
158
|
-
*
|
|
159
|
-
*
|
|
160
|
-
*
|
|
161
|
-
* the
|
|
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
|
-
*
|
|
164
|
-
*
|
|
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
|
|
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
|
-
|
|
170
|
-
|
|
171
|
-
|
|
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
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
if
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
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
|
-
|
|
188
|
-
|
|
189
|
-
|
|
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
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
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
|
-
|
|
200
|
-
|
|
201
|
-
|
|
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
|
|
207
|
-
|
|
208
|
-
|
|
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
|
-
*
|
|
214
|
-
* `
|
|
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.
|
|
218
|
-
* (`configPath === contentPath`). Worktree-based concurrency
|
|
219
|
-
* work on legacy layouts because the branch can't track a
|
|
220
|
-
* subdir that findVault could resolve to. Returns
|
|
221
|
-
* "legacy-embedded-layout", legacyLayout
|
|
222
|
-
*
|
|
223
|
-
*
|
|
224
|
-
*
|
|
225
|
-
*
|
|
226
|
-
*
|
|
227
|
-
*
|
|
228
|
-
*
|
|
229
|
-
*
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
350
|
-
// to a commit. The paths above (fresh init OR existing repo
|
|
351
|
-
// files) produce a commit; the idempotent path
|
|
352
|
-
// to scaffold) does NOT — so a vault where
|
|
353
|
-
// hand and never committed leaves HEAD
|
|
354
|
-
// initial commit so `git worktree add
|
|
355
|
-
//
|
|
356
|
-
//
|
|
357
|
-
//
|
|
358
|
-
//
|
|
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
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
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
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
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
|
/**
|