@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.
@@ -0,0 +1,121 @@
1
+ /**
2
+ * Two helpers that surface the dual-channel output of
3
+ * {@link ensureVaultReadyForDistill} as user-facing notifications:
4
+ *
5
+ * - {@link surfaceHealthFindings} renders the structured `findings`
6
+ * channel. Auto-recovered findings collapse into one info notify;
7
+ * error findings collapse into one error notify. Returns
8
+ * `{ hasErrors }` so callers can abort a worktree-based spawn.
9
+ * - {@link surfaceSetupError} renders the free-form `setup.error`
10
+ * channel for fail-soft IO failures (`git init` / `git add` /
11
+ * `git commit` / scaffolding-write) that have no corresponding
12
+ * structured finding. Single error notify; void return.
13
+ *
14
+ * Both helpers are `hasUI`-safe: when `ctx.hasUI === false`
15
+ * (subprocess, detached test contexts), no notifications are emitted.
16
+ * `surfaceHealthFindings` still returns the error-finding signal so
17
+ * the caller's abort logic continues to work in the non-UI path.
18
+ */
19
+
20
+ import type { ensureVaultReadyForDistill, HealthFinding } from "./auto-setup";
21
+
22
+ /**
23
+ * Subset of `ExtensionContext` the helper needs: a `hasUI` flag plus a
24
+ * minimal `ui.notify` surface. Kept narrow so test stubs don't have to
25
+ * implement the full pi UI contract. Internal to this module — no
26
+ * out-of-file consumer; tests use structural typing on the helper's
27
+ * parameter rather than importing the interface.
28
+ */
29
+ interface HealthNotifyCtx {
30
+ hasUI: boolean;
31
+ ui: {
32
+ notify: (message: string, severity: "info" | "warning" | "error") => void;
33
+ };
34
+ }
35
+
36
+ /**
37
+ * Render `findings` to the user via `ctx.ui.notify`. Auto-recovered
38
+ * findings collapse into a single info notify; error findings collapse
39
+ * into a single error notify. Returns `{ hasErrors }` so the caller can
40
+ * skip the worktree-based spawn when the vault is not in a usable state.
41
+ *
42
+ * Empty `findings` is the healthy-vault path: no notifications, no
43
+ * errors. The caller proceeds normally.
44
+ */
45
+ export function surfaceHealthFindings(
46
+ ctx: HealthNotifyCtx,
47
+ findings: readonly HealthFinding[],
48
+ ): { hasErrors: boolean } {
49
+ const recovered: HealthFinding[] = [];
50
+ const errors: HealthFinding[] = [];
51
+ for (const finding of findings) {
52
+ switch (finding.kind) {
53
+ case "auto-recovered":
54
+ recovered.push(finding);
55
+ break;
56
+ case "error":
57
+ errors.push(finding);
58
+ break;
59
+ default: {
60
+ // A future third `HealthFinding.kind` would silently produce
61
+ // no notify under the previous filter-based shape. The
62
+ // exhaustiveness assertion forces a tsc error at the
63
+ // partitioning site so a maintainer adding a new variant
64
+ // updates the renderer at the same time. Mirrors the
65
+ // `_exhaustive: never` pattern used by the verify-e2e variant
66
+ // switches.
67
+ const _exhaustive: never = finding.kind;
68
+ throw new Error(
69
+ `surfaceHealthFindings: unhandled HealthFinding.kind ${String(_exhaustive)}`,
70
+ );
71
+ }
72
+ }
73
+ }
74
+
75
+ if (ctx.hasUI && recovered.length > 0) {
76
+ const lines = recovered.map((f) =>
77
+ f.recovery ? `${f.message} (${f.recovery})` : f.message,
78
+ );
79
+ ctx.ui.notify(
80
+ lines.length === 1
81
+ ? `Auto-distill recovered: ${lines[0]}`
82
+ : `Auto-distill recovered:\n${lines.map((l) => `- ${l}`).join("\n")}`,
83
+ "info",
84
+ );
85
+ }
86
+
87
+ if (ctx.hasUI && errors.length > 0) {
88
+ const lines = errors.map((f) => f.message);
89
+ ctx.ui.notify(
90
+ lines.length === 1
91
+ ? `Auto-distill cannot proceed: ${lines[0]}`
92
+ : `Auto-distill cannot proceed:\n${lines.map((l) => `- ${l}`).join("\n")}`,
93
+ "error",
94
+ );
95
+ }
96
+
97
+ return { hasErrors: errors.length > 0 };
98
+ }
99
+
100
+ /**
101
+ * Render the fail-soft `setup.error` channel from
102
+ * {@link ensureVaultReadyForDistill} as a single user-facing error
103
+ * notify. `setup.error` is populated for generic IO failures (`git
104
+ * init` / `git add` / `git commit` / scaffolding-write) that have no
105
+ * corresponding structured finding; the structured `findings` channel
106
+ * is rendered separately by {@link surfaceHealthFindings}.
107
+ *
108
+ * Canonical message format: `Auto-distill setup failed: <error>.`
109
+ * (note the trailing period — callers depend on this for grep-friendly
110
+ * log scraping). When `setupError` is `undefined` the helper is a
111
+ * no-op. `hasUI`-safe: subprocess and detached test contexts skip the
112
+ * notify entirely.
113
+ */
114
+ export function surfaceSetupError(
115
+ ctx: HealthNotifyCtx,
116
+ setupError: string | undefined,
117
+ ): void {
118
+ if (setupError && ctx.hasUI) {
119
+ ctx.ui.notify(`Auto-distill setup failed: ${setupError}.`, "error");
120
+ }
121
+ }
@@ -15,7 +15,7 @@ import type { AutocompleteItem } from "@earendil-works/pi-tui";
15
15
  import { Type } from "@sinclair/typebox";
16
16
  import {
17
17
  countTrackedFiles,
18
- ensureVaultReadyForAutoDistill,
18
+ ensureVaultReadyForDistill,
19
19
  LEGACY_EMBEDDED_LAYOUT_ERROR,
20
20
  } from "./auto-setup";
21
21
  import {
@@ -31,6 +31,7 @@ import {
31
31
  resolveDistillErrorDir,
32
32
  spawnDistillInWorktree,
33
33
  } from "./distill-workspace";
34
+ import { surfaceHealthFindings, surfaceSetupError } from "./health-notify";
34
35
  import { getSessionTouchedFiles } from "./session-touched-files";
35
36
  import { shouldDistillOnShutdown } from "./should-distill-on-shutdown";
36
37
 
@@ -171,20 +172,98 @@ export const DEFAULT_DISTILL: DistillConfig = {
171
172
  onShutdown: true,
172
173
  };
173
174
 
175
+ /**
176
+ * Maximum number of characters from a {@link MalformedVaultConfigError}'s
177
+ * `parseError` to embed in user-facing notify text.
178
+ *
179
+ * `JSON.parse` error messages are usually short (e.g. `Unexpected token
180
+ * } in JSON at position 42`), but a malformed multi-MB `config.json`
181
+ * can produce a parse error long enough to overflow the notify
182
+ * surface. Cap to a value that comfortably fits a single notify line
183
+ * while leaving the unbounded value on the error object for callers
184
+ * that want to log it for diagnostics.
185
+ */
186
+ const MALFORMED_CONFIG_PARSE_ERROR_DISPLAY_MAX_LEN = 200;
187
+
188
+ /**
189
+ * Bound a {@link MalformedVaultConfigError}'s `parseError` to
190
+ * {@link MALFORMED_CONFIG_PARSE_ERROR_DISPLAY_MAX_LEN} characters.
191
+ * Long inputs are truncated and suffixed with an ellipsis so the
192
+ * notify line stays readable; short inputs are returned unchanged.
193
+ *
194
+ * Exported for direct use by tests pinning the cap regression.
195
+ * Every `MalformedVaultConfigError` notify site in this file routes
196
+ * through this helper so a multi-MB parse error never overflows the
197
+ * notify surface, regardless of which entry point caught it
198
+ * (session_start, runDistillWith's pre-flight, or runDistillWith's
199
+ * setup-failed catch handler).
200
+ */
201
+ export function formatVaultConfigParseError(parseError: string): string {
202
+ if (parseError.length <= MALFORMED_CONFIG_PARSE_ERROR_DISPLAY_MAX_LEN) {
203
+ return parseError;
204
+ }
205
+ return `${parseError.slice(0, MALFORMED_CONFIG_PARSE_ERROR_DISPLAY_MAX_LEN)}… (truncated; full error in console)`;
206
+ }
207
+
208
+ /**
209
+ * Thrown by {@link loadVaultConfig} when `<configPath>/config.json` exists
210
+ * but is not parseable as JSON. Distinct from the missing-file path, which
211
+ * still returns {@link DEFAULT_DISTILL} (a fresh-vault user has not yet
212
+ * created the file).
213
+ *
214
+ * Callers that own a UI (`session_start`, manual `/distill`) should catch
215
+ * this and surface a user-actionable error notify so the user knows the
216
+ * file needs a hand-fix; the file is the user's source of truth and we
217
+ * cannot guess the intended content. Previously this path failed open
218
+ * (returned defaults) and short-circuited at the `if (!config.enabled)
219
+ * return;` line in `session_start` before the user could see any
220
+ * indication that the config was malformed.
221
+ */
222
+ export class MalformedVaultConfigError extends Error {
223
+ readonly configPath: string;
224
+ readonly parseError: string;
225
+ constructor(configPath: string, parseError: string) {
226
+ super(`${configPath} is not valid JSON: ${parseError}`);
227
+ this.name = "MalformedVaultConfigError";
228
+ this.configPath = configPath;
229
+ this.parseError = parseError;
230
+ }
231
+ }
232
+
233
+ /**
234
+ * Read `<vaultPath>/config.json` and return the merged {@link VaultConfig}.
235
+ *
236
+ * Two failure modes:
237
+ * - File absent: returns {@link DEFAULT_DISTILL} with `showStatus: true`.
238
+ * A fresh-vault user has not yet created the file; treating absence
239
+ * as defaults keeps `pi` usable on a vault before `napkin init`.
240
+ * - File present but malformed JSON: throws {@link
241
+ * MalformedVaultConfigError}. Callers with a UI should catch and
242
+ * surface a notify so the user knows the file needs a hand-fix.
243
+ * Previously this path failed open (returned defaults), which
244
+ * masked the parse error as `enabled: false` and short-circuited
245
+ * `session_start` before any user-visible signal could fire.
246
+ */
174
247
  export function loadVaultConfig(vaultPath: string): VaultConfig {
175
248
  const configPath = path.join(vaultPath, "config.json");
176
249
  if (!fs.existsSync(configPath)) {
177
250
  return { showStatus: true, distill: DEFAULT_DISTILL };
178
251
  }
252
+ let raw: unknown;
179
253
  try {
180
- const raw = JSON.parse(fs.readFileSync(configPath, "utf-8"));
181
- return {
182
- showStatus: raw.showStatus !== false,
183
- distill: { ...DEFAULT_DISTILL, ...(raw.distill || {}) },
184
- };
185
- } catch {
186
- return { showStatus: true, distill: DEFAULT_DISTILL };
254
+ raw = JSON.parse(fs.readFileSync(configPath, "utf-8"));
255
+ } catch (err) {
256
+ throw new MalformedVaultConfigError(
257
+ configPath,
258
+ err instanceof Error ? err.message : String(err),
259
+ );
187
260
  }
261
+ // biome-ignore lint/suspicious/noExplicitAny: raw shape is user-controlled
262
+ const r = raw as any;
263
+ return {
264
+ showStatus: r?.showStatus !== false,
265
+ distill: { ...DEFAULT_DISTILL, ...(r?.distill || {}) },
266
+ };
188
267
  }
189
268
 
190
269
  /**
@@ -406,7 +485,30 @@ export default function (pi: ExtensionAPI) {
406
485
  }
407
486
  const vaultConfigPath = napkinVault.configPath;
408
487
 
409
- const { showStatus, distill: config } = loadVaultConfig(vaultConfigPath);
488
+ let showStatus: boolean;
489
+ let config: DistillConfig;
490
+ try {
491
+ ({ showStatus, distill: config } = loadVaultConfig(vaultConfigPath));
492
+ } catch (err) {
493
+ if (err instanceof MalformedVaultConfigError) {
494
+ // Malformed `config.json` is the user's hand-edit; we cannot
495
+ // guess the intended shape. Surface a notify so the user can
496
+ // fix the file and re-launch; skip the rest of session_start
497
+ // (no health check, no auto-distill arming) because the
498
+ // session-wide flags downstream depend on a parseable config.
499
+ // The previous fail-open behavior of `loadVaultConfig` masked
500
+ // the parse error as `enabled: false` and short-circuited
501
+ // before any user-visible signal could fire.
502
+ if (ctx.hasUI) {
503
+ ctx.ui.notify(
504
+ `Auto-distill cannot proceed: ${err.configPath} is not valid JSON (${formatVaultConfigParseError(err.parseError)}). Fix the file by hand and restart pi.`,
505
+ "error",
506
+ );
507
+ }
508
+ return;
509
+ }
510
+ throw err;
511
+ }
410
512
  if (!config.enabled) {
411
513
  if (ctx.hasUI && showStatus) {
412
514
  ctx.ui.setStatus(
@@ -420,8 +522,8 @@ export default function (pi: ExtensionAPI) {
420
522
  // Skip if this is a distill subprocess
421
523
  if (process.env.NAPKIN_DISTILL_NO_RECURSE) return;
422
524
 
423
- // Auto-init git + scaffold .gitignore/.gitattributes so subsequent
424
- // worktree operations have the invariants they need. Idempotent and
525
+ // Auto-init git + scaffold .gitignore so subsequent worktree
526
+ // operations have the invariants they need. Idempotent and
425
527
  // non-throwing — on failure we notify once and disable auto-distill for
426
528
  // this session rather than retrying on every interval fire.
427
529
  //
@@ -441,57 +543,73 @@ export default function (pi: ExtensionAPI) {
441
543
  const vaultContentPath = napkinVault.contentPath;
442
544
  let setupFailed = false;
443
545
  try {
444
- const setup = ensureVaultReadyForAutoDistill({
445
- contentPath: vaultContentPath,
446
- configPath: napkinVault.configPath,
447
- });
448
- if (setup.error) {
546
+ const setup = ensureVaultReadyForDistill(
547
+ {
548
+ contentPath: vaultContentPath,
549
+ configPath: napkinVault.configPath,
550
+ },
551
+ "fast",
552
+ );
553
+ if (setup.error === LEGACY_EMBEDDED_LAYOUT_ERROR) {
554
+ // Legacy embedded layout (`~/.napkin/` with `config.json`
555
+ // alongside notes, no `.napkin/` subdir). Worktree-based
556
+ // concurrency requires the subdir layout so napkin's
557
+ // `findVault` resolves cwd=worktree to the worktree itself.
558
+ // README has the migration steps; point there instead of
559
+ // duplicating them in the notify (keeps the notification
560
+ // short enough to render cleanly in every UI surface). Skip
561
+ // the structured per-finding render below so the same
562
+ // condition doesn't fire two error notifies.
449
563
  setupFailed = true;
450
- if (ctx.hasUI) {
451
- if (setup.error === LEGACY_EMBEDDED_LAYOUT_ERROR) {
452
- // Legacy embedded layout (`~/.napkin/` with `config.json`
453
- // alongside notes, no `.napkin/` subdir). Worktree-based
454
- // concurrency requires the subdir layout so napkin's
455
- // `findVault` resolves cwd=worktree to the worktree itself.
456
- // README has the migration steps; point there instead of
457
- // duplicating them in the notify (keeps the notification
458
- // short enough to render cleanly in every UI surface).
459
- ctx.ui.notify(
460
- "Auto-distill requires the subdir vault layout. See README for migration, or set distill.enabled: false in vault config.json.",
461
- "error",
462
- );
463
- } else {
464
- ctx.ui.notify(
465
- `Auto-distill setup failed: ${setup.error}. Disabling auto-distill for this session.`,
466
- "error",
467
- );
468
- }
469
- }
470
- } else if (setup.initialized) {
471
- const tracked = countTrackedFiles(vaultContentPath);
472
- const files = tracked >= 0 ? tracked : setup.scaffolded.length;
473
564
  if (ctx.hasUI) {
474
565
  ctx.ui.notify(
475
- [
476
- "Initialized git repo in your vault for auto-distill.",
477
- `Commit: 'napkin: initial vault commit (auto-distill setup)'`,
478
- `Files tracked: ${files}`,
479
- `To undo: rm -rf ${path.join(vaultContentPath, ".git")} (removes history, keeps files)`,
480
- "To opt out: set distill.enabled: false in vault config.json",
481
- ].join("\n"),
482
- "info",
566
+ "Auto-distill requires the subdir vault layout. See README for migration, or set distill.enabled: false in vault config.json.",
567
+ "error",
483
568
  );
484
569
  }
485
- } else if (setup.scaffolded.length > 0) {
486
- if (ctx.hasUI) {
570
+ } else {
571
+ // Surface every non-legacy finding through the structured
572
+ // helper so fast-level error invariants (malformed gitignore
573
+ // markers, invalid `config.json`) get the same notify
574
+ // treatment as the full-level call sites and so auto-recovered
575
+ // findings (gitignore install / migrate / reset) reach the user
576
+ // here at session_start instead of at the first interval tick.
577
+ const { hasErrors } = surfaceHealthFindings(ctx, setup.findings);
578
+ setupFailed = !!setup.error || hasErrors;
579
+
580
+ // Generic fail-soft errors (git init / add / commit /
581
+ // scaffolding-write failures) populate `setup.error` but not
582
+ // `findings`; surface the underlying message so the user knows
583
+ // why setup aborted on this session.
584
+ if (setup.error && ctx.hasUI) {
487
585
  ctx.ui.notify(
488
- `Added ${setup.scaffolded.join(", ")} for auto-distill.`,
489
- "info",
586
+ `Auto-distill setup failed: ${setup.error}. Disabling auto-distill for this session.`,
587
+ "error",
490
588
  );
491
589
  }
492
590
  }
591
+
592
+ // Initial-run onboarding notify carries scope context (file
593
+ // count, undo command, opt-out hint) that the structured
594
+ // per-finding render can't. Fires alongside
595
+ // `surfaceHealthFindings`'s info notify on the first session in a
596
+ // fresh vault.
597
+ if (setup.initialized && ctx.hasUI) {
598
+ const tracked = countTrackedFiles(vaultContentPath);
599
+ const files = tracked >= 0 ? tracked : setup.scaffolded.length;
600
+ ctx.ui.notify(
601
+ [
602
+ "Initialized git repo in your vault for auto-distill.",
603
+ `Commit: 'napkin: initial vault commit (auto-distill setup)'`,
604
+ `Files tracked: ${files}`,
605
+ `To undo: rm -rf ${path.join(vaultContentPath, ".git")} (removes history, keeps files)`,
606
+ "To opt out: set distill.enabled: false in vault config.json",
607
+ ].join("\n"),
608
+ "info",
609
+ );
610
+ }
493
611
  } catch (err) {
494
- // Truly unexpected (ensureVaultReadyForAutoDistill is supposed to not
612
+ // Truly unexpected (ensureVaultReadyForDistill is supposed to not
495
613
  // throw). Log + continue, worst case later operations fail gracefully.
496
614
  console.error("[napkin-distill] auto-setup threw:", err);
497
615
  }
@@ -641,21 +759,39 @@ export default function (pi: ExtensionAPI) {
641
759
  fs.existsSync(path.join(vaultInfo.contentPath, ".git")) &&
642
760
  sessionFile
643
761
  ) {
644
- const modelStr = config.model
645
- ? `${config.model.provider}/${config.model.id}`
646
- : undefined;
647
- spawnDistillInWorktree({
648
- vault: vaultInfo.contentPath,
649
- sessionFile,
650
- parentCwd: ctx.cwd,
651
- maxDurationSecs: Math.round(
652
- getMaxDistillDurationMs(config) / 1000,
653
- ),
654
- model: modelStr,
655
- });
656
- // Mark this size as "spawned" so if the parent re-enters shutdown
657
- // (unlikely but possible with session switch), we don't duplicate.
658
- lastSpawnedSize = currentSize;
762
+ // Full health-check before the shutdown distill spawns. The
763
+ // shutdown handler is the last chance to surface a notify
764
+ // before the session ends; an error finding aborts the
765
+ // spawn (corrupt config, malformed markers, etc.) so the
766
+ // wrapper doesn't get handed an unusable vault.
767
+ const setup = ensureVaultReadyForDistill(
768
+ {
769
+ contentPath: vaultInfo.contentPath,
770
+ configPath: vaultInfo.configPath,
771
+ },
772
+ "full",
773
+ );
774
+ const { hasErrors } = surfaceHealthFindings(ctx, setup.findings);
775
+ surfaceSetupError(ctx, setup.error);
776
+ if (!hasErrors && !setup.error) {
777
+ const modelStr = config.model
778
+ ? `${config.model.provider}/${config.model.id}`
779
+ : undefined;
780
+ spawnDistillInWorktree({
781
+ vault: vaultInfo.contentPath,
782
+ sessionFile,
783
+ parentCwd: ctx.cwd,
784
+ maxDurationSecs: Math.round(
785
+ getMaxDistillDurationMs(config) / 1000,
786
+ ),
787
+ model: modelStr,
788
+ });
789
+ // Mark this size as "spawned" so if the parent re-enters shutdown
790
+ // (unlikely but possible with session switch), we don't duplicate.
791
+ lastSpawnedSize = currentSize;
792
+ }
793
+ // On error: do not advance lastSpawnedSize so a subsequent
794
+ // recovery attempt can re-fire.
659
795
  }
660
796
  }
661
797
  }
@@ -900,9 +1036,28 @@ export default function (pi: ExtensionAPI) {
900
1036
  }
901
1037
  const vaultContentPath = vaultInfo.contentPath;
902
1038
 
903
- const { showStatus, distill: config } = loadVaultConfig(
904
- vaultInfo.configPath,
905
- );
1039
+ let showStatus: boolean;
1040
+ let config: DistillConfig;
1041
+ try {
1042
+ ({ showStatus, distill: config } = loadVaultConfig(vaultInfo.configPath));
1043
+ } catch (err) {
1044
+ if (err instanceof MalformedVaultConfigError) {
1045
+ // Manual `/distill` and the auto-distill tick both flow through
1046
+ // here. A malformed `config.json` means we can't determine
1047
+ // whether distill is enabled or how to parameterise the spawn;
1048
+ // notify the user and skip this run rather than crashing the
1049
+ // command handler / timer callback. The session keeps running
1050
+ // so the user can fix the file and retry.
1051
+ if (ctx.hasUI) {
1052
+ ctx.ui.notify(
1053
+ `Auto-distill cannot proceed: ${err.configPath} is not valid JSON (${formatVaultConfigParseError(err.parseError)}). Fix the file by hand and retry.`,
1054
+ "error",
1055
+ );
1056
+ }
1057
+ return;
1058
+ }
1059
+ throw err;
1060
+ }
906
1061
  const sessionFile = ctx.sessionManager.getSessionFile?.();
907
1062
  if (!sessionFile) return;
908
1063
 
@@ -1132,9 +1287,24 @@ export default function (pi: ExtensionAPI) {
1132
1287
  path.join(args.vaultContentPath, ".git"),
1133
1288
  );
1134
1289
  // Legacy-embedded detection matches the predicate in
1135
- // `ensureVaultReadyForAutoDistill` (keep the two gates in lockstep).
1290
+ // `ensureVaultReadyForDistill` (keep the two gates in lockstep).
1136
1291
  const isLegacyEmbedded = args.vaultConfigPath === args.vaultContentPath;
1137
1292
  if (gitPresent && args.config.enabled && !isLegacyEmbedded) {
1293
+ // Full health-check before the worktree-based spawn. Surfaces
1294
+ // auto-recovered findings as info notifies; aborts the spawn
1295
+ // when any error finding fires (corrupt config, malformed
1296
+ // gitignore markers, etc.). Legacy-embedded routing skips this
1297
+ // entirely — those vaults are untouched by auto-distill.
1298
+ const setup = ensureVaultReadyForDistill(
1299
+ {
1300
+ contentPath: args.vaultContentPath,
1301
+ configPath: args.vaultConfigPath,
1302
+ },
1303
+ "full",
1304
+ );
1305
+ const { hasErrors } = surfaceHealthFindings(args.ctx, setup.findings);
1306
+ surfaceSetupError(args.ctx, setup.error);
1307
+ if (hasErrors || setup.error) return null;
1138
1308
  return worktreeSpawnFn(args);
1139
1309
  }
1140
1310
  return legacySpawnFn(args);
@@ -1162,7 +1332,24 @@ export default function (pi: ExtensionAPI) {
1162
1332
  }
1163
1333
  return { ok: true };
1164
1334
  },
1165
- spawnFn: worktreeSpawnFn,
1335
+ spawnFn: (args) => {
1336
+ // Full health-check before each tick: rewires drift in the
1337
+ // managed gitignore block, re-emits structured findings, aborts
1338
+ // the spawn on any error finding (corrupt config, malformed
1339
+ // markers). Auto-distill always uses the worktree path; the
1340
+ // legacy-embedded route only exists for manual `/distill`.
1341
+ const setup = ensureVaultReadyForDistill(
1342
+ {
1343
+ contentPath: args.vaultContentPath,
1344
+ configPath: args.vaultConfigPath,
1345
+ },
1346
+ "full",
1347
+ );
1348
+ const { hasErrors } = surfaceHealthFindings(args.ctx, setup.findings);
1349
+ surfaceSetupError(args.ctx, setup.error);
1350
+ if (hasErrors || setup.error) return null;
1351
+ return worktreeSpawnFn(args);
1352
+ },
1166
1353
  });
1167
1354
  }
1168
1355
 
@@ -1263,9 +1450,24 @@ export default function (pi: ExtensionAPI) {
1263
1450
  };
1264
1451
  } catch (err) {
1265
1452
  const theme = c.hasUI ? c.ui.theme : null;
1266
- const { showStatus } = loadVaultConfig(
1267
- new Napkin(c.cwd).vault.configPath,
1268
- );
1453
+ // Defensive: a malformed `config.json` here cannot prevent the
1454
+ // status repaint (we're already in a setup-failed catch handler
1455
+ // and need to surface SOME signal to the user). Default
1456
+ // `showStatus` to `true` if `loadVaultConfig` itself errors, and
1457
+ // surface the underlying error via notify so the user knows the
1458
+ // file needs a hand-fix rather than seeing only the status
1459
+ // repaint.
1460
+ let showStatus = true;
1461
+ try {
1462
+ ({ showStatus } = loadVaultConfig(new Napkin(c.cwd).vault.configPath));
1463
+ } catch (cfgErr) {
1464
+ if (cfgErr instanceof MalformedVaultConfigError && c.hasUI) {
1465
+ c.ui.notify(
1466
+ `Auto-distill cannot proceed: ${cfgErr.configPath} is not valid JSON (${formatVaultConfigParseError(cfgErr.parseError)}). Fix the file by hand and retry.`,
1467
+ "error",
1468
+ );
1469
+ }
1470
+ }
1269
1471
  if (c.hasUI && theme && showStatus) {
1270
1472
  const msg =
1271
1473
  err instanceof DistillError
@@ -78,7 +78,7 @@ export default function (pi: ExtensionAPI) {
78
78
  "napkin-context",
79
79
  (message, { expanded }, theme) => {
80
80
  if (!expanded) {
81
- const label = theme.fg("customMessageLabel", "🧻 napkin vault context");
81
+ const label = theme.fg("customMessageLabel", "📜 napkin vault context");
82
82
  const hint = theme.fg("dim", " — Ctrl+O to expand");
83
83
  return new Text(label + hint, 1, 0);
84
84
  }
@@ -181,7 +181,7 @@ export default function (pi: ExtensionAPI) {
181
181
  if (ctx.hasUI && loadShowStatus(n.vault.configPath)) {
182
182
  const theme = ctx.ui.theme;
183
183
  if (hasVault) {
184
- ctx.ui.setStatus("napkin", `🧻${theme.fg("dim", " napkin")}`);
184
+ ctx.ui.setStatus("napkin", `📜${theme.fg("dim", " napkin")}`);
185
185
  } else {
186
186
  ctx.ui.setStatus("napkin", theme.fg("dim", "napkin: no NAPKIN.md"));
187
187
  }
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@cad0p/pi-napkin",
3
- "version": "0.3.0",
4
- "description": "🧻 Napkin integration for pi — vault context, knowledge tools, and automatic distillation with git-worktree concurrency safety",
3
+ "version": "0.3.1",
4
+ "description": "📜 Napkin integration for pi — vault context, knowledge tools, and automatic distillation with git-worktree concurrency safety",
5
5
  "publishConfig": {
6
6
  "access": "public",
7
7
  "registry": "https://registry.npmjs.org"