@cad0p/pi-napkin 0.3.0 β 0.3.1-20260618.0
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/distill-workspace.ts +16 -1
- package/extensions/distill/health-notify.ts +121 -0
- package/extensions/distill/index.ts +305 -75
- package/extensions/napkin-context/index.ts +2 -2
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# pi-napkin
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
π [Napkin](https://github.com/cad0p/napkin) integration for [pi](https://github.com/badlogic/pi-mono).
|
|
4
4
|
|
|
5
5
|
Gives a pi agent first-class access to an Obsidian-compatible knowledge vault, with automatic knowledge distillation that safely captures conversation context into notes as you work.
|
|
6
6
|
|
|
@@ -213,7 +213,7 @@ Or edit `<vault>/.napkin/config.json` directly:
|
|
|
213
213
|
|
|
214
214
|
When enabled, on session start the extension:
|
|
215
215
|
|
|
216
|
-
1. Runs `
|
|
216
|
+
1. Runs `ensureVaultReadyForDistill` on the vault (see below) β git-inits if needed and scaffolds `.gitignore`.
|
|
217
217
|
2. Sweeps stale distill worktrees left by crashed pi instances (`cleanupStaleWorktrees`).
|
|
218
218
|
3. Arms a timer (`intervalMinutes`) that spawns a detached `pi -p` subprocess on tick.
|
|
219
219
|
4. On shutdown (unless `distill.onShutdown` is false or the session file is already captured), spawns one final distill.
|
|
@@ -233,7 +233,7 @@ The distill subprocess runs a prompt that asks the model to:
|
|
|
233
233
|
When you enable `distill.enabled: true` on a vault that isn't a git repo, pi-napkin auto-initializes it on the next session start:
|
|
234
234
|
|
|
235
235
|
1. Runs `git init`.
|
|
236
|
-
2.
|
|
236
|
+
2. Installs the [managed `.gitignore` block](#auto-distill-setup) (excludes `.napkin/distill/` β the per-worktree session fork). Distill worktrees themselves live outside the vault (see [Where worktrees live](#where-worktrees-live)), so `.gitignore` doesn't need to exclude them. No `.gitattributes` is written β the agent-driven merge architecture has no driver to register.
|
|
237
237
|
3. Commits everything as `napkin: initial vault commit (auto-distill setup)`.
|
|
238
238
|
4. Notifies you once, with instructions to undo (`rm -rf <vault>/.git`) or opt out (`distill.enabled: false`).
|
|
239
239
|
|
|
@@ -353,7 +353,71 @@ If you want auto-distill on an existing Obsidian vault:
|
|
|
353
353
|
2. Start a pi session in the vault.
|
|
354
354
|
3. On session start, pi-napkin prompts to auto-init git if the vault isn't already one.
|
|
355
355
|
|
|
356
|
-
If your vault IS already a git repo (common for "vault as project"), pi-napkin just
|
|
356
|
+
If your vault IS already a git repo (common for "vault as project"), pi-napkin just installs the [managed `.gitignore` block](#auto-distill-setup) and moves on.
|
|
357
|
+
|
|
358
|
+
## Auto-distill setup
|
|
359
|
+
|
|
360
|
+
Every time pi starts a session in an auto-distill-enabled vault, pi-napkin runs a **health check** that confirms the vault is in a state the worktree-based distill can actually run against. The check is layered into two cadences so the cost of routine checks stays near-zero while the rare expensive checks only fire on the manual `/distill` path.
|
|
361
|
+
|
|
362
|
+
### The managed `.gitignore` block
|
|
363
|
+
|
|
364
|
+
pi-napkin owns a single contiguous block in the vault's `.gitignore`, delimited by these exact marker lines:
|
|
365
|
+
|
|
366
|
+
```gitignore
|
|
367
|
+
# BEGIN NAPKIN-DISTILL MANAGED
|
|
368
|
+
# napkin-distill ephemeral state
|
|
369
|
+
.napkin/distill/
|
|
370
|
+
|
|
371
|
+
# Obsidian workspace-local state
|
|
372
|
+
.obsidian/workspace*.json
|
|
373
|
+
.obsidian/cache
|
|
374
|
+
.obsidian/.trash/
|
|
375
|
+
|
|
376
|
+
# Local tmp/cache + common secrets (belt-and-braces; auto-init's
|
|
377
|
+
# `git add .` would otherwise capture them in the initial commit
|
|
378
|
+
# even on vaults that happen to contain dev work).
|
|
379
|
+
# (full canonical body in extensions/distill/auto-setup.ts:BLOCK_CONTENT)
|
|
380
|
+
# END NAPKIN-DISTILL MANAGED
|
|
381
|
+
```
|
|
382
|
+
|
|
383
|
+
**Inside the markers:** pi-napkin owns the content. Hand-edits between the markers are reset on the next session start β the auto-init / health-check pass rewrites the block to its canonical content if it has drifted.
|
|
384
|
+
|
|
385
|
+
**Outside the markers:** user territory. pi-napkin's only edit outside the block is removing lines that match canonical block content (a one-time migration cleanup from the 0.3.0 line-by-line format, kept on every run as a self-heal). User-written lines that don't match canonical content are never touched. You can add, remove, or reorder anything else in `.gitignore` and pi-napkin will leave it alone.
|
|
386
|
+
|
|
387
|
+
The block style is the same Ansible-style sentinel pattern Ansible's `blockinfile` module uses (and Homebrew, oh-my-zsh, etc.) so the boundary between managed and unmanaged content is visually obvious.
|
|
388
|
+
|
|
389
|
+
### Fast-level vs full-level checks
|
|
390
|
+
|
|
391
|
+
| Cadence | When | What it covers | Typical cost |
|
|
392
|
+
|---|---|---|---|
|
|
393
|
+
| Fast-level | Every `session_start` (every pi launch in the vault) | Subdir vs legacy-embedded layout, managed gitignore block matches canonical (auto-recover if drift), auto-init `git init` + initial commit if `.git/` is missing | Sub-second (a handful of git probes) |
|
|
394
|
+
| Full-level | On `/distill` (manual) and at each interval-driven auto-distill spawn | Everything fast-level covers, plus: `.napkin/config.json` is git-tracked, vault HEAD resolves to a commit (seed an empty initial commit if a hand-`git init`-ed vault has no commits yet), `.napkin/config.json` not gitignored outside the managed block, `.napkin/distill/` not tracked, cache root writable, no orphaned distill worktree registry entries, no stale `distill/*` branches past the grace period | A few extra git probes; runs only when a worktree is about to be spawned anyway |
|
|
395
|
+
|
|
396
|
+
Fast-level findings surface as one-shot notifications at session start; the session continues regardless. Full-level findings are gated separately depending on category (below).
|
|
397
|
+
|
|
398
|
+
### Auto-recover findings (info; distill proceeds)
|
|
399
|
+
|
|
400
|
+
These are recoverable drift the health check fixes in place. Each emits a single info notification of the form `Auto-distill recovered: <message>` and `/distill` proceeds normally afterward:
|
|
401
|
+
|
|
402
|
+
- **Managed-block drift** β markers got reordered, content drifted, or canonical lines leaked outside the block. Resolution: rewrite the bracketed region back to canonical and strip any leaked lines from user territory.
|
|
403
|
+
- **Untracked `.napkin/config.json`** (full-level only) β config file exists but isn't yet in git's index. Resolution: stage and commit it (so worktrees can see it).
|
|
404
|
+
- **Vault HEAD resolves to a commit** (full-level only) β the vault is a `git init`-ed repo with zero commits, so `git rev-parse --verify HEAD` fails and `git worktree add HEAD` would have no ref to pin to. Resolution: `git commit --allow-empty` to seed an empty initial commit. (Detached-HEAD-after-distill is a separate post-distill concern surfaced as the `head-not-on-default` outcome reason in the wrapper-side table above; it requires manual recovery.)
|
|
405
|
+
- **Orphaned distill worktrees** (full-level only) β a previous distill crashed and left a `git worktree list` registry entry pointing at a directory that no longer exists. Resolution: `git worktree prune --expire=now`.
|
|
406
|
+
- **Stale `distill/*` branches** (full-level only) β a `distill/*` branch with a committerdate older than the grace period (24h) AND no live worktree pointing at it. Resolution: `git branch -D <branch>`. The reflog grace gives you a recovery window for content from a failed distill.
|
|
407
|
+
|
|
408
|
+
### Loud-error findings (error; distill aborts)
|
|
409
|
+
|
|
410
|
+
These are conditions where auto-distill cannot safely proceed. Each emits an error notification of the form `Auto-distill cannot proceed: <message>` and `/distill` aborts before spawning a wrapper:
|
|
411
|
+
|
|
412
|
+
- **Subdir-layout violation** β vault uses napkin's legacy embedded layout (config at `<vault>/config.json`, no `.napkin/` subdir). Auto-distill needs the subdir layout for worktree-based concurrency to work; see [Migration from legacy layout](#migration-from-legacy-layout).
|
|
413
|
+
- **Malformed `.napkin/config.json`** β file exists but doesn't parse as JSON. Detected by `loadVaultConfig` upstream of the health check itself; auto-distill refuses to guess; fix the file and reload.
|
|
414
|
+
- **`.napkin/config.json` gitignored outside the managed block** (full-level only) β a user-territory rule in `.gitignore` (or a parent `.gitignore` / global ignore) excludes the config file. Worktrees would have no config to read; remove the rule or move it inside the managed block.
|
|
415
|
+
- **`.napkin/distill/` tracked in git** (full-level only) β the per-worktree session fork directory got committed at some point. Untrack it (`git rm --cached -r .napkin/distill/`) before re-running.
|
|
416
|
+
- **Cache root unwritable** (full-level only) β `$XDG_CACHE_HOME/napkin-distill/<hash>/` can't be created or written. Check disk space and permissions on the cache root.
|
|
417
|
+
|
|
418
|
+
### Opt out
|
|
419
|
+
|
|
420
|
+
Set `distill.enabled = false` in `.napkin/config.json` (or run `napkin --vault <path> config set --key distill.enabled --value false`). With auto-distill disabled, pi-napkin runs no health checks, installs no managed block, and never touches `.gitignore`. Manual `/distill` still works β it has no concurrency-safety prerequisites.
|
|
357
421
|
|
|
358
422
|
## Troubleshooting
|
|
359
423
|
|
|
@@ -438,7 +502,11 @@ CI uses bash-stub fixtures (`extensions/distill/test-fixtures/agent-stubs/`) to
|
|
|
438
502
|
bun run verify:e2e
|
|
439
503
|
```
|
|
440
504
|
|
|
441
|
-
The script (`scripts/verify-e2e.ts`) creates a tmpdir vault
|
|
505
|
+
The script (`scripts/verify-e2e.ts`) creates a tmpdir vault by invoking the real `napkin init` CLI, then drives the production session_start handler so auto-init's `git init` + managed `.gitignore` block + initial commit run end-to-end, then triggers the `/distill` command handler so the production `runDistillWith` path runs (real wrapper subprocess, real 2-second `setInterval` poller). It asserts on the dispatched UI notification's severity + message together with filesystem post-conditions: no conflict markers, HEAD on default branch, agent's squash commit landed, distill branch removed, worktree removed, outcome sidecar with class `merged-content`, and origin advanced.
|
|
506
|
+
|
|
507
|
+
The gate also accepts `--variant <name>` (or `--all`) to exercise the full-level health-check decision points end-to-end β a loud-error path (`config-outside-block`, which aborts before LLM dispatch and costs $0) and an auto-recover path (`orphaned-worktree`, which prunes the orphan and then runs the full distill). The default `healthy` variant is the original gate.
|
|
508
|
+
|
|
509
|
+
Exits 0 on PASS, 1 on FAIL. Manual-only β not in CI; cost is roughly $0.50 per LLM-driven variant.
|
|
442
510
|
|
|
443
511
|
This replaces the earlier prompt-only gate. The strict superset matters because the wrapperβJS-poller seam β where worktree-teardown and outcome-write race β is invisible to a prompt-only harness.
|
|
444
512
|
|