@cad0p/pi-napkin 0.2.4

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.
@@ -0,0 +1,480 @@
1
+ /**
2
+ * First-run auto-setup for auto-distill.
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) and a `.gitattributes` that registers the LLM merge driver for
7
+ * concurrent distill runs. Vaults typically ship without any of this — we
8
+ * scaffold it at `session_start` when `distill.enabled` is true.
9
+ *
10
+ * Design contract:
11
+ * - Idempotent: re-running on an already-set-up vault is a no-op (returns
12
+ * `{ initialized: false, scaffolded: [] }`).
13
+ * - Non-destructive: never clobbers existing `.gitignore` /
14
+ * `.gitattributes` content; only appends missing lines.
15
+ * - Fail-soft: returns `{ error }` instead of throwing so the caller can
16
+ * surface a notify() and keep the session alive.
17
+ */
18
+
19
+ import { spawnSync } from "node:child_process";
20
+ import * as fs from "node:fs";
21
+ import * as path from "node:path";
22
+
23
+ /**
24
+ * Lines appended to `<vault>/.gitignore` when scaffolding. Order is stable so
25
+ * diff noise stays minimal on re-runs. Each group has a section-comment
26
+ * header — we match on the non-comment lines for idempotence, the comments
27
+ * are cosmetic.
28
+ */
29
+ export const GITIGNORE_LINES: readonly string[] = [
30
+ "# napkin-distill ephemeral state",
31
+ ".napkin/distill/",
32
+ "",
33
+ "# Obsidian workspace-local state",
34
+ ".obsidian/workspace*.json",
35
+ ".obsidian/cache",
36
+ ".obsidian/.trash/",
37
+ "",
38
+ "# Local tmp/cache",
39
+ "search-cache.json",
40
+ ".DS_Store",
41
+ "",
42
+ "# Common secrets — belt-and-braces for vaults that end up alongside dev",
43
+ "# work. Auto-distill commits 'git add .' on first run; these patterns",
44
+ "# keep credentials out of the initial commit even if a user's vault",
45
+ "# happens to contain them.",
46
+ ".env",
47
+ ".env.local",
48
+ ".env.*.local",
49
+ "*.pem",
50
+ "*.key",
51
+ "id_rsa",
52
+ "id_ecdsa",
53
+ "id_ed25519",
54
+ "secrets.json",
55
+ ".aws/credentials",
56
+ ];
57
+
58
+ /**
59
+ * Lines appended to `<vault>/.gitattributes` when scaffolding. Registers the
60
+ * `napkin-distill-merge` driver for every `.md` file so parallel distill
61
+ * runs hit the LLM merge path on conflict.
62
+ */
63
+ export const GITATTRIBUTES_LINES: readonly string[] = [
64
+ "# napkin-distill: LLM merge driver for concurrent auto-distill",
65
+ "*.md merge=napkin-distill-merge",
66
+ ];
67
+
68
+ /**
69
+ * Result of {@link ensureVaultReadyForAutoDistill}.
70
+ *
71
+ * - `initialized`: a brand-new `git init` ran (vault had no `.git/` before).
72
+ * - `scaffolded`: files whose contents were created or modified. Callers use
73
+ * this to decide whether to surface a first-run notify to the user.
74
+ * - `error`: populated on fail-soft paths (git init failed, filesystem
75
+ * errors writing the scaffolding, legacy-layout refusal). If set, other
76
+ * fields reflect partial progress.
77
+ * - `conflict`: populated when auto-setup refused to scaffold because the
78
+ * existing `.gitattributes` already claims `*.md merge=<something-else>`.
79
+ * `error` is also set with a short `"conflicting merge rule…"` message so
80
+ * existing fail-soft callers keep working; `conflict` carries the
81
+ * diagnostic details (rule text, file path) for a precise notify.
82
+ * - `legacyLayout`: populated when auto-setup refused to scaffold because
83
+ * the vault is using napkin's legacy embedded layout (`configPath ===
84
+ * contentPath`). The worktree-based concurrency architecture relies on
85
+ * napkin's findVault resolving cwd=worktree to the worktree itself —
86
+ * which only works for subdir-layout vaults (those that track a
87
+ * `.napkin/config.json`). `error` is set to `"legacy-embedded-layout"`
88
+ * so callers can branch on it.
89
+ */
90
+ export interface SetupResult {
91
+ initialized: boolean;
92
+ scaffolded: string[];
93
+ error?: string;
94
+ conflict?: {
95
+ /** The full offending line as it appears in `.gitattributes`. */
96
+ rule: string;
97
+ /** Absolute path to the `.gitattributes` that contains the conflict. */
98
+ file: string;
99
+ /** Just the `<driver>` captured from `*.md merge=<driver>`. */
100
+ driver: string;
101
+ };
102
+ legacyLayout?: {
103
+ /** Absolute path to the vault's `.napkin/` (= contentPath for legacy). */
104
+ configPath: string;
105
+ };
106
+ /**
107
+ * Set to `true` when the vault had a `.git/` but no commits (HEAD
108
+ * unresolvable) and auto-setup synthesized an empty initial commit to
109
+ * make HEAD valid. Distinct from `initialized` (which is "we ran
110
+ * `git init`"): this path fires on an existing-but-empty repo where
111
+ * someone ran `git init` by hand and never committed. Without the
112
+ * seed, `git worktree add ... HEAD` in createDistillWorktree would
113
+ * fail with `fatal: invalid reference: HEAD` — the bug that
114
+ * motivated FB-2.
115
+ */
116
+ seededCommit?: boolean;
117
+ }
118
+
119
+ /**
120
+ * Sentinel value set in `SetupResult.error` when auto-setup refuses to
121
+ * scaffold because the vault is using napkin's legacy embedded layout.
122
+ * Exported so callers (session_start handler, tests) can branch on the
123
+ * exact sentinel instead of pattern-matching on the free-form message.
124
+ */
125
+ export const LEGACY_EMBEDDED_LAYOUT_ERROR = "legacy-embedded-layout";
126
+
127
+ /**
128
+ * Minimal vault handle this module accepts. Mirrors
129
+ * `StaleCleanupVault` in `distill-workspace.ts` — keeps the callsite
130
+ * symmetric: both setup and cleanup take the same vault shape and
131
+ * neither forces the caller to construct a full Napkin instance.
132
+ *
133
+ * Both paths are required: legacy-embedded-layout detection needs to
134
+ * compare `configPath` and `contentPath` directly (legacy vaults have
135
+ * them equal; subdir vaults have them distinct).
136
+ */
137
+ export interface SetupVault {
138
+ contentPath: string;
139
+ configPath: string;
140
+ }
141
+
142
+ /**
143
+ * Run `git` in `cwd` and return `{ status, stdout, stderr }`. Does not throw
144
+ * on non-zero exit — we translate failures to `SetupResult.error`.
145
+ */
146
+ function runGit(
147
+ cwd: string,
148
+ args: string[],
149
+ ): { status: number | null; stdout: string; stderr: string } {
150
+ // `env: process.env` is required for Bun: unlike Node, Bun's spawnSync
151
+ // does NOT propagate mutations to `process.env` to the child unless
152
+ // `env` is passed explicitly (it snapshots env at runtime startup).
153
+ // Passing process.env here is a no-op on Node and restores Node-compat
154
+ // semantics on Bun so tests can control git identity via env vars.
155
+ const r = spawnSync("git", args, {
156
+ cwd,
157
+ encoding: "utf-8",
158
+ timeout: 30_000,
159
+ env: process.env,
160
+ });
161
+ return {
162
+ status: r.status,
163
+ stdout: r.stdout || "",
164
+ stderr: r.stderr || r.error?.message || "",
165
+ };
166
+ }
167
+
168
+ /**
169
+ * Merge `newLines` into the file at `filePath`, appending only the
170
+ * non-comment, non-blank lines that aren't already present. A line is
171
+ * considered "present" if it appears verbatim anywhere in the existing file
172
+ * (leading/trailing whitespace trimmed for comparison). Returns `true` if
173
+ * the file was created or modified.
174
+ *
175
+ * Creates the file if it doesn't exist. Preserves the existing content
176
+ * verbatim otherwise — we never rewrite or re-order user lines.
177
+ */
178
+ function mergeLines(filePath: string, newLines: readonly string[]): boolean {
179
+ const existed = fs.existsSync(filePath);
180
+ const existing = existed ? fs.readFileSync(filePath, "utf-8") : "";
181
+ const existingSet = new Set(
182
+ existing
183
+ .split("\n")
184
+ .map((l) => l.trim())
185
+ .filter((l) => l.length > 0 && !l.startsWith("#")),
186
+ );
187
+
188
+ const toAppend: string[] = [];
189
+ let sawMeaningful = false;
190
+ for (const line of newLines) {
191
+ const trimmed = line.trim();
192
+ if (trimmed.length === 0 || trimmed.startsWith("#")) {
193
+ // Only keep headers/spacers if there's at least one real line to append
194
+ // below them. We can't decide that until we've scanned the whole block,
195
+ // so buffer optimistically and trim at the end.
196
+ toAppend.push(line);
197
+ continue;
198
+ }
199
+ if (!existingSet.has(trimmed)) {
200
+ toAppend.push(line);
201
+ sawMeaningful = true;
202
+ }
203
+ }
204
+
205
+ if (!sawMeaningful) {
206
+ // File already has everything meaningful — no change needed even if we
207
+ // accumulated section headers in `toAppend`.
208
+ return false;
209
+ }
210
+
211
+ // Prefix with a blank line if the existing file doesn't end with one, so
212
+ // appended sections are visually separated.
213
+ let prefix = "";
214
+ if (existed && existing.length > 0 && !existing.endsWith("\n")) prefix = "\n";
215
+ else if (existed && existing.length > 0 && !existing.endsWith("\n\n"))
216
+ prefix = "\n";
217
+
218
+ const body = `${toAppend.join("\n")}\n`;
219
+ fs.writeFileSync(filePath, existing + prefix + body);
220
+ return true;
221
+ }
222
+
223
+ /**
224
+ * Expected driver name set by {@link GITATTRIBUTES_LINES}. Exported so tests
225
+ * can assert the symmetric pair without re-parsing the scaffold string.
226
+ */
227
+ export const NAPKIN_MERGE_DRIVER = "napkin-distill-merge";
228
+
229
+ /**
230
+ * If the vault's `.gitattributes` already contains an `*.md merge=<driver>`
231
+ * rule whose driver is NOT our `napkin-distill-merge`, return its details.
232
+ * Returns `null` when there's no conflict (no rule, or the existing rule is
233
+ * already ours).
234
+ *
235
+ * Scope: deliberately narrow. We only check for the EXACT pattern `*.md`
236
+ * with a `merge=` attribute — pattern-overlap cases (e.g. `notes/** merge=
237
+ * union` + our `*.md merge=napkin-distill-merge` both matching
238
+ * `notes/x.md`) are not flagged. Those would need a full gitattributes
239
+ * parser and are rare enough in practice that the noise of false positives
240
+ * outweighs the value of catching them. The common case is a user who has
241
+ * `*.md merge=union` globally and would silently get our driver layered on
242
+ * top via last-match-wins; that case is what this catches.
243
+ *
244
+ * Pattern matching is case-insensitive (`*.MD` is detected too). On macOS
245
+ * (APFS default) and Windows (NTFS default) filesystems, git's pattern
246
+ * matching respects `core.ignorecase=true`, so `*.MD merge=union` DOES
247
+ * apply to `foo.md` files — silently overriding our driver via
248
+ * last-match-wins is exactly the scenario this detector exists to
249
+ * prevent.
250
+ *
251
+ * The returned `rule` preserves the full original line (for accurate error
252
+ * messages) and `driver` is just the captured driver name.
253
+ */
254
+ export function detectConflictingMdMergeRule(
255
+ gaPath: string,
256
+ ): { rule: string; driver: string } | null {
257
+ if (!fs.existsSync(gaPath)) return null;
258
+ const contents = fs.readFileSync(gaPath, "utf-8");
259
+ for (const rawLine of contents.split("\n")) {
260
+ const line = rawLine.trim();
261
+ if (line.length === 0 || line.startsWith("#")) continue;
262
+ // Match: `*.md` (exactly) followed by whitespace, with a `merge=<name>`
263
+ // attribute somewhere on the line. Other attributes on the same line
264
+ // (diff=..., text, etc.) are ignored — only the merge driver conflicts
265
+ // with ours. Case-insensitive to honor `core.ignorecase=true` on
266
+ // APFS/NTFS (default on macOS and Windows).
267
+ const m = line.match(/^\*\.md\s+(?:.*\s+)?merge=([A-Za-z0-9_.-]+)/i);
268
+ if (!m) continue;
269
+ const driver = m[1];
270
+ if (driver === NAPKIN_MERGE_DRIVER) continue; // Our own rule, idempotent.
271
+ return { rule: line, driver };
272
+ }
273
+ return null;
274
+ }
275
+
276
+ /**
277
+ * Ensure `<vaultPath>` is a git repo with a `.gitignore` / `.gitattributes`
278
+ * that cover auto-distill's needs. Called once per `session_start` when
279
+ * `distill.enabled` is true.
280
+ *
281
+ * Lifecycle:
282
+ * 0. Refuse if the vault uses napkin's legacy embedded layout
283
+ * (`configPath === contentPath`). Worktree-based concurrency doesn't
284
+ * work on legacy layouts because the branch can't track a `.napkin/`
285
+ * subdir that findVault could resolve to. Returns `{ error:
286
+ * "legacy-embedded-layout", legacyLayout }` without touching git.
287
+ * 1. If `.git/` is missing → `git init`. Failure here aborts with `error`.
288
+ * 2. Detect a conflicting `*.md merge=<other>` in an existing
289
+ * `.gitattributes`. If present, return `{ error, conflict }` WITHOUT
290
+ * writing our rule — gitattributes is last-match-wins and silently
291
+ * layering our driver on top would override the user's chosen one.
292
+ * 3. Merge scaffolding lines into `.gitignore` and `.gitattributes`
293
+ * (idempotent; no-op if already present).
294
+ * 4. If anything changed:
295
+ * - fresh init → `git add .` + commit `"napkin: initial vault commit
296
+ * (auto-distill setup)"`
297
+ * - existing repo → `git add .gitignore .gitattributes` + commit
298
+ * `"napkin: scaffold auto-distill git config"`
299
+ *
300
+ * Returned `scaffolded` always uses vault-relative paths so notify messages
301
+ * are compact and portable.
302
+ */
303
+ export function ensureVaultReadyForAutoDistill(vault: SetupVault): SetupResult {
304
+ const vaultPath = vault.contentPath;
305
+
306
+ // Legacy-embedded layout is incompatible with the worktree-based
307
+ // concurrency architecture. In a legacy vault (`~/.napkin/`), the
308
+ // vault IS the `.napkin/` directory — `configPath === contentPath`.
309
+ // When a distill subprocess runs with `cwd = worktree` (a checkout of
310
+ // a `distill/*` branch that does NOT track a `.napkin/` subdir),
311
+ // napkin's `findVault` walks past the worktree and resolves to the
312
+ // user's REAL vault via the global config fallback. Writes bypass the
313
+ // worktree entirely, making the concurrency guarantee a no-op.
314
+ //
315
+ // Refuse to scaffold here so session_start can surface a migration
316
+ // notify. Manual `/distill` still works on any layout (it doesn't go
317
+ // through this path).
318
+ //
319
+ // Detection mirrors napkin's own `resolveVaultLayout` semantics: subdir
320
+ // layout sets `contentPath` via `vault.root` (distinct from `configPath`),
321
+ // while legacy embedded layout has no `vault.root` and defaults both to
322
+ // the `.napkin/` dir. See `@cad0p/napkin` `dist/utils/vault.js`.
323
+ if (vault.configPath === vault.contentPath) {
324
+ return {
325
+ initialized: false,
326
+ scaffolded: [],
327
+ error: LEGACY_EMBEDDED_LAYOUT_ERROR,
328
+ legacyLayout: { configPath: vault.configPath },
329
+ };
330
+ }
331
+
332
+ const gitDir = path.join(vaultPath, ".git");
333
+ let initialized = false;
334
+
335
+ if (!fs.existsSync(gitDir)) {
336
+ const init = runGit(vaultPath, ["init", "-q", "-b", "main"]);
337
+ if (init.status !== 0) {
338
+ return {
339
+ initialized: false,
340
+ scaffolded: [],
341
+ error: `git init failed: ${init.stderr.trim() || "unknown error"}`,
342
+ };
343
+ }
344
+ initialized = true;
345
+ }
346
+
347
+ // Guard against silently overriding a user-chosen `*.md merge=...` rule.
348
+ // gitattributes is last-match-wins, so appending our driver without
349
+ // warning would bypass their choice the next time they edit a .md file.
350
+ // Refuse to scaffold and surface a `conflict` so the caller can prompt
351
+ // the user to resolve it explicitly.
352
+ const gaPath = path.join(vaultPath, ".gitattributes");
353
+ const conflict = detectConflictingMdMergeRule(gaPath);
354
+ if (conflict) {
355
+ return {
356
+ initialized,
357
+ scaffolded: [],
358
+ error: `conflicting merge rule in .gitattributes: '${conflict.rule}'`,
359
+ conflict: {
360
+ rule: conflict.rule,
361
+ file: gaPath,
362
+ driver: conflict.driver,
363
+ },
364
+ };
365
+ }
366
+
367
+ const scaffolded: string[] = [];
368
+
369
+ try {
370
+ const giPath = path.join(vaultPath, ".gitignore");
371
+ if (mergeLines(giPath, GITIGNORE_LINES)) scaffolded.push(".gitignore");
372
+ if (mergeLines(gaPath, GITATTRIBUTES_LINES))
373
+ scaffolded.push(".gitattributes");
374
+ } catch (err) {
375
+ const msg = err instanceof Error ? err.message : String(err);
376
+ return {
377
+ initialized,
378
+ scaffolded,
379
+ error: `failed to write scaffolding: ${msg}`,
380
+ };
381
+ }
382
+
383
+ if (initialized) {
384
+ // Fresh init: commit the entire vault so auto-distill has a HEAD to
385
+ // branch from. `git add .` respects the just-written .gitignore so we
386
+ // don't accidentally stage `.napkin/distill/` (the per-worktree
387
+ // session fork) or common secret files (see GITIGNORE_LINES). Distill
388
+ // worktrees themselves live OUTSIDE the vault now (XDG cache), so
389
+ // there's no in-vault worktrees/ path to exclude.
390
+ const add = runGit(vaultPath, ["add", "."]);
391
+ if (add.status !== 0) {
392
+ return {
393
+ initialized,
394
+ scaffolded,
395
+ error: `git add failed: ${add.stderr.trim() || "unknown error"}`,
396
+ };
397
+ }
398
+ const commit = runGit(vaultPath, [
399
+ "commit",
400
+ "-q",
401
+ "-m",
402
+ "napkin: initial vault commit (auto-distill setup)",
403
+ ]);
404
+ if (commit.status !== 0) {
405
+ return {
406
+ initialized,
407
+ scaffolded,
408
+ error: `git commit failed: ${commit.stderr.trim() || "unknown error"}`,
409
+ };
410
+ }
411
+ } else if (scaffolded.length > 0) {
412
+ // Existing repo: only stage the scaffolding files so we don't sweep in
413
+ // the user's unrelated working changes.
414
+ const add = runGit(vaultPath, ["add", ...scaffolded]);
415
+ if (add.status !== 0) {
416
+ return {
417
+ initialized,
418
+ scaffolded,
419
+ error: `git add failed: ${add.stderr.trim() || "unknown error"}`,
420
+ };
421
+ }
422
+ const commit = runGit(vaultPath, [
423
+ "commit",
424
+ "-q",
425
+ "-m",
426
+ "napkin: scaffold auto-distill git config",
427
+ ]);
428
+ if (commit.status !== 0) {
429
+ return {
430
+ initialized,
431
+ scaffolded,
432
+ error: `git commit failed: ${commit.stderr.trim() || "unknown error"}`,
433
+ };
434
+ }
435
+ }
436
+
437
+ // HEAD-valid invariant: createDistillWorktree requires HEAD to resolve
438
+ // to a commit. The paths above (fresh init OR existing repo + scaffolded
439
+ // files) produce a commit; the idempotent path (existing repo, nothing
440
+ // to scaffold) does NOT — so a vault where someone ran `git init` by
441
+ // hand and never committed leaves HEAD unresolvable. Seed an empty
442
+ // initial commit so `git worktree add ... HEAD` has something to pin to.
443
+ // This also covers the narrow window where `git init` succeeded above
444
+ // (we set `initialized = true`) but scaffolding wrote zero lines (both
445
+ // .gitignore and .gitattributes already present with our exact content)
446
+ // — that would fall into neither branch and leave a commit-less repo.
447
+ let seededCommit: SetupResult["seededCommit"];
448
+ const headAfter = runGit(vaultPath, ["rev-parse", "--verify", "HEAD"]);
449
+ if (headAfter.status !== 0) {
450
+ const seed = runGit(vaultPath, [
451
+ "commit",
452
+ "--allow-empty",
453
+ "-q",
454
+ "-m",
455
+ "napkin: initial vault commit (auto-distill setup)",
456
+ ]);
457
+ if (seed.status !== 0) {
458
+ return {
459
+ initialized,
460
+ scaffolded,
461
+ error: `git seed commit failed: ${seed.stderr.trim() || "unknown error"}`,
462
+ };
463
+ }
464
+ seededCommit = true;
465
+ }
466
+
467
+ return { initialized, scaffolded, seededCommit };
468
+ }
469
+
470
+ /**
471
+ * Count the files tracked in the vault's git index. Used by the first-run
472
+ * notify so the user sees a concrete scope ("42 files tracked") rather
473
+ * than the abstract scaffolding list. Returns `-1` if git fails or the
474
+ * vault isn't a repo; callers treat negative as "don't mention a count".
475
+ */
476
+ export function countTrackedFiles(vaultPath: string): number {
477
+ const res = runGit(vaultPath, ["ls-files"]);
478
+ if (res.status !== 0) return -1;
479
+ return res.stdout.split("\n").filter((l) => l.length > 0).length;
480
+ }