@cad0p/pi-napkin 0.7.0 → 0.7.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 +52 -36
- package/dist/steering/index.d.ts +88 -0
- package/dist/steering/index.d.ts.map +1 -0
- package/dist/steering/index.js +74 -0
- package/dist/steering/index.js.map +1 -0
- package/dist/steering/predicates.d.ts +41 -0
- package/dist/steering/predicates.d.ts.map +1 -0
- package/dist/steering/predicates.js +48 -0
- package/dist/steering/predicates.js.map +1 -0
- package/extensions/distill/auto-setup.ts +13 -78
- package/extensions/distill/distill-workspace.ts +4 -5
- package/extensions/distill/index.ts +160 -130
- package/extensions/steering/index.ts +90 -0
- package/extensions/steering/predicates.ts +52 -0
- package/package.json +12 -2
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# pi-napkin
|
|
2
2
|
|
|
3
|
-
📜 [Napkin](https://github.com/cad0p/napkin) integration for [pi](https://github.com/
|
|
3
|
+
📜 [Napkin](https://github.com/cad0p/napkin) integration for [pi](https://github.com/earendil-works/pi).
|
|
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
|
|
|
@@ -83,13 +83,11 @@ my-vault/
|
|
|
83
83
|
```
|
|
84
84
|
|
|
85
85
|
`napkin init` creates this layout by default, so freshly created vaults work out
|
|
86
|
-
of the box.
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
napkin CLI commands generally — only auto-distill requires the subdir
|
|
92
|
-
layout.
|
|
86
|
+
of the box. Vaults still on the embedded layout (config at `<vault>/config.json`
|
|
87
|
+
with no `.napkin/` subdir) are refused by napkin >= 0.14 with
|
|
88
|
+
`VaultNotFoundError` — napkin's own error message carries the migration
|
|
89
|
+
guidance. Distill supports exactly what napkin resolves: a refused vault is
|
|
90
|
+
treated as no vault and silently skipped.
|
|
93
91
|
|
|
94
92
|
### Why
|
|
95
93
|
|
|
@@ -98,12 +96,7 @@ subdir post-checkout, so the wrapper's `git add -A` + `git commit` +
|
|
|
98
96
|
`git merge --squash` operations on the worktree see the isolated
|
|
99
97
|
vault layout. On a subdir-layout vault, the branch tracks
|
|
100
98
|
`.napkin/config.json`, so every checked-out worktree has the
|
|
101
|
-
`.napkin/` subdir.
|
|
102
|
-
`.napkin/` subdir at all (`.napkin/` IS the vault), so the worktree
|
|
103
|
-
has nothing to operate on — the wrapper would silently produce empty
|
|
104
|
-
commits, and the per-distill napkin shim's `--vault $WORKTREE` would
|
|
105
|
-
point at a directory napkin doesn't recognize as a vault. The
|
|
106
|
-
concurrency guarantee silently degrades to nothing.
|
|
99
|
+
`.napkin/` subdir.
|
|
107
100
|
|
|
108
101
|
### Where worktrees live
|
|
109
102
|
|
|
@@ -130,21 +123,6 @@ rm -rf ~/.cache/napkin-distill/<hash>/
|
|
|
130
123
|
Safe — anything valuable is either already committed to main or was
|
|
131
124
|
never going to commit.
|
|
132
125
|
|
|
133
|
-
### Migration from legacy layout
|
|
134
|
-
|
|
135
|
-
```bash
|
|
136
|
-
# From your vault directory (e.g. ~/.napkin or wherever configPath == contentPath)
|
|
137
|
-
mkdir .napkin
|
|
138
|
-
mv config.json .napkin/config.json
|
|
139
|
-
# Edit .napkin/config.json and add at the top level:
|
|
140
|
-
# "vault": { "root": ".." }
|
|
141
|
-
# After editing, reload pi (or /quit and restart).
|
|
142
|
-
```
|
|
143
|
-
|
|
144
|
-
Verify with `napkin vault --json` — the `path` field should point at
|
|
145
|
-
`<vault>/.napkin/` (that's the new configPath) and napkin should still
|
|
146
|
-
find all your notes.
|
|
147
|
-
|
|
148
126
|
## Vault resolution
|
|
149
127
|
|
|
150
128
|
Both extensions use napkin's built-in vault resolution. The resolution order is:
|
|
@@ -162,6 +140,47 @@ Both extensions use napkin's built-in vault resolution. The resolution order is:
|
|
|
162
140
|
|
|
163
141
|
Local project vaults take priority when present. No vault yet? Run `napkin init` in the directory you want as the vault root (see `napkin init --list` for templates) — the napkin-context extension surfaces a no-vault guidance message on session start when no vault resolves (no local project vault and no global fallback), so a fresh setup is self-documenting.
|
|
164
142
|
|
|
143
|
+
## Steering integration
|
|
144
|
+
|
|
145
|
+
[pi-steering](https://github.com/cad0p/pi-steering) blocks direct commits to protected branches by default (`no-main-commit` / `no-main-commit-github` from the git plugin). The napkin workflow legitimately commits + pushes to `main` inside vaults — note edits and the distill pipeline's scratch worktrees — so pi-napkin ships a **steering plugin** that carves those guards out for napkin vaults:
|
|
146
|
+
|
|
147
|
+
```bash
|
|
148
|
+
pi install npm:@cad0p/pi-napkin
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
Then make `@cad0p/pi-napkin` resolvable from your steering config. For the global config (`~/.pi/agent/steering/`, or wherever `<agentDir>/steering/` lives):
|
|
152
|
+
|
|
153
|
+
```bash
|
|
154
|
+
cd ~/.pi/agent/steering
|
|
155
|
+
pnpm add -D @cad0p/pi-napkin # or: npm i -D @cad0p/pi-napkin
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
And declare the plugin next to the git plugin:
|
|
159
|
+
|
|
160
|
+
```ts
|
|
161
|
+
// <agentDir>/steering/index.ts (global layer)
|
|
162
|
+
import { defineConfig } from "@cad0p/pi-steering";
|
|
163
|
+
import gitPlugin from "@cad0p/pi-steering/plugins/git";
|
|
164
|
+
import napkinSteeringPlugin from "@cad0p/pi-napkin/steering";
|
|
165
|
+
|
|
166
|
+
export default defineConfig({
|
|
167
|
+
plugins: [gitPlugin, napkinSteeringPlugin],
|
|
168
|
+
});
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
The `@cad0p/pi-napkin/steering` subpath ships compiled JS (`dist/steering`), so plain-node consumers (native type stripping, `node --test --experimental-strip-types`) need no jiti or loader. pi's own extension loader still resolves raw `.ts` paths via jiti, so the napkin extensions are unaffected.
|
|
172
|
+
|
|
173
|
+
Requirements and semantics:
|
|
174
|
+
|
|
175
|
+
- **pi-steering ≥ 0.2.0-20260812.0** — the exemption registry landed in the 20260812 prerelease; stable 0.2.0 predates it.
|
|
176
|
+
- **`gitPlugin` MUST stay listed** — the exemptions target the git plugin's rule names; a missing target produces `exemption-orphan` warnings with no carve-out.
|
|
177
|
+
- **Zero path config** — a read-only walk-up from the command's effective cwd detects the vault by its `.napkin/` (or `.obsidian/.napkin/`) marker, delegating to napkin's canonical `findAncestorVault`. Goldmine, distill scratch worktrees under `~/.cache/napkin-distill/`, and future vaults are all covered automatically — no `VAULT_DIRS` to maintain.
|
|
178
|
+
- **napkin ≥ 0.14.0-20260814.0** — the compiled subpath imports `findAncestorVault` from `@cad0p/napkin` at runtime (stable 0.14.0 predates the export; `@cad0p/pi-napkin` declares the range, and the global steering config must resolve it).
|
|
179
|
+
- **Read-only** — the predicate never creates anything (no bare-vault fallback, no global-config fallback), and unknown walker cwd never exempts: the guard still fires (strict fail-closed).
|
|
180
|
+
- **Accumulates** — exemptions union across plugins and config layers, so other tools can carve the same guards for other repo types without touching this config.
|
|
181
|
+
|
|
182
|
+
If you previously hand-rolled the carve-out (spread-and-extend rule copies with `not: { cwd: VAULT_DIRS }`, or config-layer `exemptions` with path patterns), delete those and keep only `plugins: [gitPlugin, napkinSteeringPlugin]`.
|
|
183
|
+
|
|
165
184
|
### Migrating from `~/.pi/agent/napkin.json`
|
|
166
185
|
|
|
167
186
|
If you previously configured your vault in `~/.pi/agent/napkin.json`, move it to the new location:
|
|
@@ -388,7 +407,7 @@ The block style is the same Ansible-style sentinel pattern Ansible's `blockinfil
|
|
|
388
407
|
|
|
389
408
|
| Cadence | When | What it covers | Typical cost |
|
|
390
409
|
|---|---|---|---|
|
|
391
|
-
| Fast-level | Every `session_start` (every pi launch in the vault) |
|
|
410
|
+
| Fast-level | Every `session_start` (every pi launch in the vault) | 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) |
|
|
392
411
|
| 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 |
|
|
393
412
|
|
|
394
413
|
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).
|
|
@@ -407,8 +426,6 @@ These are recoverable drift the health check fixes in place. Each emits a single
|
|
|
407
426
|
|
|
408
427
|
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:
|
|
409
428
|
|
|
410
|
-
- **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).
|
|
411
|
-
- **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.
|
|
412
429
|
- **`.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.
|
|
413
430
|
- **`.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.
|
|
414
431
|
- **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.
|
|
@@ -451,14 +468,13 @@ See the [Outcome classes](#outcome-classes) table for what each `<reason>` means
|
|
|
451
468
|
- `agent-exit-nonzero` → check the model provider (rate limits, auth refresh, network). The agent's stderr is in the `.log` file.
|
|
452
469
|
- `divergent-history` → a teammate likely landed a commit on `origin/<default>` while the agent's distill ran. `git pull --no-rebase` to integrate.
|
|
453
470
|
|
|
454
|
-
### "vault not a git repo"
|
|
471
|
+
### "vault not a git repo"
|
|
455
472
|
|
|
456
|
-
Auto-distill requires **git
|
|
473
|
+
Auto-distill requires **git**. If you see:
|
|
457
474
|
|
|
458
475
|
- `vault not a git repo` — either set `distill.enabled: true` and let pi-napkin auto-init git for you on next session, run `git init` in the vault root manually, or disable auto-distill with `distill.enabled: false`.
|
|
459
|
-
- `legacy embedded layout` — follow the [migration steps](#migration-from-legacy-layout). Auto-distill stays off for this session; manual `/distill` works regardless.
|
|
460
476
|
|
|
461
|
-
Manual `/distill` works without git
|
|
477
|
+
Manual `/distill` works without git.
|
|
462
478
|
|
|
463
479
|
### Testing hooks
|
|
464
480
|
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
import type { PredicateShape } from "@cad0p/pi-steering";
|
|
2
|
+
import { isNapkinVault, isNapkinVaultDir } from "./predicates.ts";
|
|
3
|
+
declare global {
|
|
4
|
+
/**
|
|
5
|
+
* `when.isNapkinVault` — true when the effective cwd is inside a
|
|
6
|
+
* napkin vault (read-only `.napkin/`-marker walk-up). Registered
|
|
7
|
+
* by the napkin steering plugin; usable by any config that lists
|
|
8
|
+
* the plugin. Fail-closed: unknown cwd → `"unknown"` sentinel.
|
|
9
|
+
*/
|
|
10
|
+
interface PiSteeringPredicates {
|
|
11
|
+
isNapkinVault: PredicateShape<boolean>;
|
|
12
|
+
}
|
|
13
|
+
}
|
|
14
|
+
/**
|
|
15
|
+
* The napkin steering plugin for `@cad0p/pi-steering`.
|
|
16
|
+
*
|
|
17
|
+
* Subpath import: `@cad0p/pi-napkin/steering`.
|
|
18
|
+
*
|
|
19
|
+
* Registers (in the terms of `Plugin`):
|
|
20
|
+
*
|
|
21
|
+
* - `predicates` - `isNapkinVault` (see `./predicates.ts` for
|
|
22
|
+
* the fail-closed contract).
|
|
23
|
+
* - `exemptions` - carve-outs of the shipped git-plugin rules
|
|
24
|
+
* `no-main-commit` / `no-main-commit-github`
|
|
25
|
+
* when `when.isNapkinVault` matches. The
|
|
26
|
+
* napkin workflow legitimately commits +
|
|
27
|
+
* pushes to `main` inside vaults (note edits,
|
|
28
|
+
* the distill pipeline's scratch worktrees),
|
|
29
|
+
* so the guards stay ACTIVE everywhere else.
|
|
30
|
+
*
|
|
31
|
+
* This is the clean replacement for the hand-rolled global
|
|
32
|
+
* carve-out pattern (`...rule, not: { cwd: VAULT_DIRS }` copies +
|
|
33
|
+
* `disabledRules`), which did NOT compose across plugins: exemptions
|
|
34
|
+
* ACCUMULATE (union) across plugins and config layers, and target
|
|
35
|
+
* the shipped rule names — a stable public contract — so other tools
|
|
36
|
+
* can carve the same guards for other repo types without touching
|
|
37
|
+
* this plugin.
|
|
38
|
+
*
|
|
39
|
+
* Exemption clauses are STRICTLY fail-closed: `onUnknown` cannot be
|
|
40
|
+
* written anywhere inside them (type-level ban + load-time
|
|
41
|
+
* rejection), and unknown walker cwd never exempts — the target
|
|
42
|
+
* rule's own `onUnknown:` policy decides, so the guard still fires
|
|
43
|
+
* on an unresolvable cwd.
|
|
44
|
+
*
|
|
45
|
+
* No pi extension runtime involved: this module is a plain library
|
|
46
|
+
* with a single non-builtin runtime import (`@cad0p/napkin`, itself
|
|
47
|
+
* a plain library shipping compiled dist JS — all pi-steering
|
|
48
|
+
* imports are type-only and erased by node's type stripping), so
|
|
49
|
+
* the steering global config can import it without pi being
|
|
50
|
+
* involved.
|
|
51
|
+
*
|
|
52
|
+
* Opt-in: nothing happens until the user lists this plugin next to
|
|
53
|
+
* the git plugin:
|
|
54
|
+
*
|
|
55
|
+
* ```ts
|
|
56
|
+
* import { defineConfig } from "@cad0p/pi-steering";
|
|
57
|
+
* import gitPlugin from "@cad0p/pi-steering/plugins/git";
|
|
58
|
+
* import napkinSteeringPlugin from "@cad0p/pi-napkin/steering";
|
|
59
|
+
*
|
|
60
|
+
* export default defineConfig({
|
|
61
|
+
* plugins: [gitPlugin, napkinSteeringPlugin],
|
|
62
|
+
* });
|
|
63
|
+
* ```
|
|
64
|
+
*
|
|
65
|
+
* `gitPlugin` MUST be listed alongside: the exemptions target its
|
|
66
|
+
* rule names, and a missing target surfaces `exemption-orphan`
|
|
67
|
+
* warnings with no carve-out.
|
|
68
|
+
*/
|
|
69
|
+
declare const napkinSteeringPlugin: {
|
|
70
|
+
readonly name: "napkin";
|
|
71
|
+
readonly predicates: {
|
|
72
|
+
readonly isNapkinVault: typeof isNapkinVault;
|
|
73
|
+
};
|
|
74
|
+
readonly exemptions: readonly [{
|
|
75
|
+
readonly rule: "no-main-commit";
|
|
76
|
+
readonly when: {
|
|
77
|
+
readonly isNapkinVault: true;
|
|
78
|
+
};
|
|
79
|
+
}, {
|
|
80
|
+
readonly rule: "no-main-commit-github";
|
|
81
|
+
readonly when: {
|
|
82
|
+
readonly isNapkinVault: true;
|
|
83
|
+
};
|
|
84
|
+
}];
|
|
85
|
+
};
|
|
86
|
+
export default napkinSteeringPlugin;
|
|
87
|
+
export { isNapkinVault, isNapkinVaultDir, napkinSteeringPlugin };
|
|
88
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../extensions/steering/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAU,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACjE,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAElE,OAAO,CAAC,MAAM,CAAC;IACb;;;;;OAKG;IACH,UAAU,oBAAoB;QAC5B,aAAa,EAAE,cAAc,CAAC,OAAO,CAAC,CAAC;KACxC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,QAAA,MAAM,oBAAoB;;;;;;;;;;;;;;;;CASC,CAAC;AAE5B,eAAe,oBAAoB,CAAC;AAKpC,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,CAAC"}
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
// SPDX-License-Identifier: MIT
|
|
2
|
+
// Part of pi-napkin.
|
|
3
|
+
import { isNapkinVault, isNapkinVaultDir } from "./predicates.js";
|
|
4
|
+
/**
|
|
5
|
+
* The napkin steering plugin for `@cad0p/pi-steering`.
|
|
6
|
+
*
|
|
7
|
+
* Subpath import: `@cad0p/pi-napkin/steering`.
|
|
8
|
+
*
|
|
9
|
+
* Registers (in the terms of `Plugin`):
|
|
10
|
+
*
|
|
11
|
+
* - `predicates` - `isNapkinVault` (see `./predicates.ts` for
|
|
12
|
+
* the fail-closed contract).
|
|
13
|
+
* - `exemptions` - carve-outs of the shipped git-plugin rules
|
|
14
|
+
* `no-main-commit` / `no-main-commit-github`
|
|
15
|
+
* when `when.isNapkinVault` matches. The
|
|
16
|
+
* napkin workflow legitimately commits +
|
|
17
|
+
* pushes to `main` inside vaults (note edits,
|
|
18
|
+
* the distill pipeline's scratch worktrees),
|
|
19
|
+
* so the guards stay ACTIVE everywhere else.
|
|
20
|
+
*
|
|
21
|
+
* This is the clean replacement for the hand-rolled global
|
|
22
|
+
* carve-out pattern (`...rule, not: { cwd: VAULT_DIRS }` copies +
|
|
23
|
+
* `disabledRules`), which did NOT compose across plugins: exemptions
|
|
24
|
+
* ACCUMULATE (union) across plugins and config layers, and target
|
|
25
|
+
* the shipped rule names — a stable public contract — so other tools
|
|
26
|
+
* can carve the same guards for other repo types without touching
|
|
27
|
+
* this plugin.
|
|
28
|
+
*
|
|
29
|
+
* Exemption clauses are STRICTLY fail-closed: `onUnknown` cannot be
|
|
30
|
+
* written anywhere inside them (type-level ban + load-time
|
|
31
|
+
* rejection), and unknown walker cwd never exempts — the target
|
|
32
|
+
* rule's own `onUnknown:` policy decides, so the guard still fires
|
|
33
|
+
* on an unresolvable cwd.
|
|
34
|
+
*
|
|
35
|
+
* No pi extension runtime involved: this module is a plain library
|
|
36
|
+
* with a single non-builtin runtime import (`@cad0p/napkin`, itself
|
|
37
|
+
* a plain library shipping compiled dist JS — all pi-steering
|
|
38
|
+
* imports are type-only and erased by node's type stripping), so
|
|
39
|
+
* the steering global config can import it without pi being
|
|
40
|
+
* involved.
|
|
41
|
+
*
|
|
42
|
+
* Opt-in: nothing happens until the user lists this plugin next to
|
|
43
|
+
* the git plugin:
|
|
44
|
+
*
|
|
45
|
+
* ```ts
|
|
46
|
+
* import { defineConfig } from "@cad0p/pi-steering";
|
|
47
|
+
* import gitPlugin from "@cad0p/pi-steering/plugins/git";
|
|
48
|
+
* import napkinSteeringPlugin from "@cad0p/pi-napkin/steering";
|
|
49
|
+
*
|
|
50
|
+
* export default defineConfig({
|
|
51
|
+
* plugins: [gitPlugin, napkinSteeringPlugin],
|
|
52
|
+
* });
|
|
53
|
+
* ```
|
|
54
|
+
*
|
|
55
|
+
* `gitPlugin` MUST be listed alongside: the exemptions target its
|
|
56
|
+
* rule names, and a missing target surfaces `exemption-orphan`
|
|
57
|
+
* warnings with no carve-out.
|
|
58
|
+
*/
|
|
59
|
+
const napkinSteeringPlugin = {
|
|
60
|
+
name: "napkin",
|
|
61
|
+
predicates: {
|
|
62
|
+
isNapkinVault,
|
|
63
|
+
},
|
|
64
|
+
exemptions: [
|
|
65
|
+
{ rule: "no-main-commit", when: { isNapkinVault: true } },
|
|
66
|
+
{ rule: "no-main-commit-github", when: { isNapkinVault: true } },
|
|
67
|
+
],
|
|
68
|
+
};
|
|
69
|
+
export default napkinSteeringPlugin;
|
|
70
|
+
// Named re-exports for consumers that want to pick pieces (e.g. a
|
|
71
|
+
// test harness constructing a minimal config that uses only the
|
|
72
|
+
// predicate without the shipped exemptions).
|
|
73
|
+
export { isNapkinVault, isNapkinVaultDir, napkinSteeringPlugin };
|
|
74
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../extensions/steering/index.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,qBAAqB;AAGrB,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAclE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,MAAM,oBAAoB,GAAG;IAC3B,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE;QACV,aAAa;KACd;IACD,UAAU,EAAE;QACV,EAAE,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,EAAE;QACzD,EAAE,IAAI,EAAE,uBAAuB,EAAE,IAAI,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,EAAE;KACjE;CACwB,CAAC;AAE5B,eAAe,oBAAoB,CAAC;AAEpC,kEAAkE;AAClE,gEAAgE;AAChE,6CAA6C;AAC7C,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,CAAC"}
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
import { findAncestorVault } from "@cad0p/napkin";
|
|
2
|
+
import type { PredicateContext } from "@cad0p/pi-steering";
|
|
3
|
+
/**
|
|
4
|
+
* Back-compat alias for napkin's canonical vault walk.
|
|
5
|
+
*
|
|
6
|
+
* The canonical implementation lives in napkin (`findAncestorVault`):
|
|
7
|
+
* a purely structural walk-up looking for the `.napkin/` marker (or
|
|
8
|
+
* `.obsidian/.napkin/` for the nested layout) at any level — no
|
|
9
|
+
* global-config fallback, no writes. Identical semantics to the
|
|
10
|
+
* mirror this package previously shipped, so the steering plugin's
|
|
11
|
+
* fail-closed posture is unchanged (a read-only probe that can
|
|
12
|
+
* never make an arbitrary cwd look like a vault). The alias
|
|
13
|
+
* preserves the public export name the global steering config
|
|
14
|
+
* imports (`isNapkinVaultDir` from `@cad0p/pi-napkin/steering`).
|
|
15
|
+
*/
|
|
16
|
+
export declare const isNapkinVaultDir: typeof findAncestorVault;
|
|
17
|
+
/**
|
|
18
|
+
* `isNapkinVault` predicate handler — registered by the napkin
|
|
19
|
+
* steering plugin under the `when.isNapkinVault` slot
|
|
20
|
+
* (`PredicateShape<boolean>` bare form).
|
|
21
|
+
*
|
|
22
|
+
* Fail-closed contract:
|
|
23
|
+
*
|
|
24
|
+
* - `args !== true` → `false` (only the bare `true` form asks for
|
|
25
|
+
* the check; the spread `{ value: ... }` form is not meaningful
|
|
26
|
+
* for this boolean probe).
|
|
27
|
+
* - `ctx.cwd === "unknown"` (walker couldn't statically resolve
|
|
28
|
+
* the effective cwd) → returns the `"unknown"` sentinel, NOT
|
|
29
|
+
* `false`. Unknown cwd is not the same as "not a vault", and the
|
|
30
|
+
* trinary composes with the rule's own `onUnknown:` policy when
|
|
31
|
+
* the predicate is used as a public `when` leaf. Inside an
|
|
32
|
+
* exemption clause both verdicts behave identically — exemption
|
|
33
|
+
* clauses are STRICTLY fail-closed (anything non-true = no
|
|
34
|
+
* exemption = the guard still fires), so this can never weaken
|
|
35
|
+
* `no-main-commit` / `no-main-commit-github`.
|
|
36
|
+
* - Known cwd → read-only walk-up for the `.napkin/` marker
|
|
37
|
+
* (see {@link isNapkinVaultDir}). No writes, no global-config
|
|
38
|
+
* fallback.
|
|
39
|
+
*/
|
|
40
|
+
export declare function isNapkinVault(args: unknown, ctx: PredicateContext): boolean | "unknown";
|
|
41
|
+
//# sourceMappingURL=predicates.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"predicates.d.ts","sourceRoot":"","sources":["../../extensions/steering/predicates.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB,0BAAoB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,OAAO,EACb,GAAG,EAAE,gBAAgB,GACpB,OAAO,GAAG,SAAS,CAIrB"}
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
// SPDX-License-Identifier: MIT
|
|
2
|
+
// Part of pi-napkin.
|
|
3
|
+
import { findAncestorVault } from "@cad0p/napkin";
|
|
4
|
+
/**
|
|
5
|
+
* Back-compat alias for napkin's canonical vault walk.
|
|
6
|
+
*
|
|
7
|
+
* The canonical implementation lives in napkin (`findAncestorVault`):
|
|
8
|
+
* a purely structural walk-up looking for the `.napkin/` marker (or
|
|
9
|
+
* `.obsidian/.napkin/` for the nested layout) at any level — no
|
|
10
|
+
* global-config fallback, no writes. Identical semantics to the
|
|
11
|
+
* mirror this package previously shipped, so the steering plugin's
|
|
12
|
+
* fail-closed posture is unchanged (a read-only probe that can
|
|
13
|
+
* never make an arbitrary cwd look like a vault). The alias
|
|
14
|
+
* preserves the public export name the global steering config
|
|
15
|
+
* imports (`isNapkinVaultDir` from `@cad0p/pi-napkin/steering`).
|
|
16
|
+
*/
|
|
17
|
+
export const isNapkinVaultDir = findAncestorVault;
|
|
18
|
+
/**
|
|
19
|
+
* `isNapkinVault` predicate handler — registered by the napkin
|
|
20
|
+
* steering plugin under the `when.isNapkinVault` slot
|
|
21
|
+
* (`PredicateShape<boolean>` bare form).
|
|
22
|
+
*
|
|
23
|
+
* Fail-closed contract:
|
|
24
|
+
*
|
|
25
|
+
* - `args !== true` → `false` (only the bare `true` form asks for
|
|
26
|
+
* the check; the spread `{ value: ... }` form is not meaningful
|
|
27
|
+
* for this boolean probe).
|
|
28
|
+
* - `ctx.cwd === "unknown"` (walker couldn't statically resolve
|
|
29
|
+
* the effective cwd) → returns the `"unknown"` sentinel, NOT
|
|
30
|
+
* `false`. Unknown cwd is not the same as "not a vault", and the
|
|
31
|
+
* trinary composes with the rule's own `onUnknown:` policy when
|
|
32
|
+
* the predicate is used as a public `when` leaf. Inside an
|
|
33
|
+
* exemption clause both verdicts behave identically — exemption
|
|
34
|
+
* clauses are STRICTLY fail-closed (anything non-true = no
|
|
35
|
+
* exemption = the guard still fires), so this can never weaken
|
|
36
|
+
* `no-main-commit` / `no-main-commit-github`.
|
|
37
|
+
* - Known cwd → read-only walk-up for the `.napkin/` marker
|
|
38
|
+
* (see {@link isNapkinVaultDir}). No writes, no global-config
|
|
39
|
+
* fallback.
|
|
40
|
+
*/
|
|
41
|
+
export function isNapkinVault(args, ctx) {
|
|
42
|
+
if (args !== true)
|
|
43
|
+
return false;
|
|
44
|
+
if (ctx.cwd === "unknown")
|
|
45
|
+
return "unknown";
|
|
46
|
+
return isNapkinVaultDir(ctx.cwd) !== null;
|
|
47
|
+
}
|
|
48
|
+
//# sourceMappingURL=predicates.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"predicates.js","sourceRoot":"","sources":["../../extensions/steering/predicates.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,qBAAqB;AAErB,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAGlD;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,iBAAiB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,aAAa,CAC3B,IAAa,EACb,GAAqB;IAErB,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAChC,IAAI,GAAG,CAAC,GAAG,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC5C,OAAO,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC;AAC5C,CAAC"}
|
|
@@ -40,8 +40,7 @@
|
|
|
40
40
|
* alive. Structured per-invariant findings live in `findings`;
|
|
41
41
|
* `error` is reserved for the fail-soft generic-failure channel
|
|
42
42
|
* that has no corresponding finding (e.g. `git init` / `git add`
|
|
43
|
-
* / `git commit` failures, EISDIR on `.gitignore` write
|
|
44
|
-
* {@link LEGACY_EMBEDDED_LAYOUT_ERROR} sentinel).
|
|
43
|
+
* / `git commit` failures, EISDIR on `.gitignore` write).
|
|
45
44
|
*/
|
|
46
45
|
|
|
47
46
|
import { spawnSync } from "node:child_process";
|
|
@@ -192,7 +191,7 @@ export type HealthLevel = "fast" | "full";
|
|
|
192
191
|
* restored the expected state in place. Surface as an info notify; the
|
|
193
192
|
* caller proceeds with the distill spawn.
|
|
194
193
|
* - `kind: "error"`: the invariant was violated and recovery is owned by
|
|
195
|
-
* the user (e.g.
|
|
194
|
+
* the user (e.g. malformed JSON). Surface as
|
|
196
195
|
* an error notify; the caller aborts the distill spawn.
|
|
197
196
|
* - `invariant`: stable identifier for the check. One ID per check; the
|
|
198
197
|
* per-flavor recovery messaging lives in `recovery`.
|
|
@@ -215,18 +214,10 @@ export interface HealthFinding {
|
|
|
215
214
|
* - `scaffolded`: files whose contents were created or modified. Callers use
|
|
216
215
|
* this to decide whether to surface a first-run notify to the user.
|
|
217
216
|
* - `error`: populated on fail-soft paths (git init failed, filesystem
|
|
218
|
-
* errors writing the scaffolding
|
|
219
|
-
*
|
|
220
|
-
*
|
|
221
|
-
*
|
|
222
|
-
* path additionally compares against {@link LEGACY_EMBEDDED_LAYOUT_ERROR}.
|
|
223
|
-
* - `legacyLayout`: populated when auto-setup refused to scaffold because
|
|
224
|
-
* the vault is using napkin's legacy embedded layout (`configPath ===
|
|
225
|
-
* contentPath`). The worktree-based concurrency architecture relies on
|
|
226
|
-
* napkin's findVault resolving cwd=worktree to the worktree itself —
|
|
227
|
-
* which only works for subdir-layout vaults (those that track a
|
|
228
|
-
* `.napkin/config.json`). `error` is set to `"legacy-embedded-layout"`
|
|
229
|
-
* so callers can branch on it.
|
|
217
|
+
* errors writing the scaffolding). If set, other fields reflect partial
|
|
218
|
+
* progress. Consumed at all extension call sites (session_start,
|
|
219
|
+
* runDistill, runAutoDistill, session_shutdown handler) to surface a
|
|
220
|
+
* `notify("error")` and abort the spawn.
|
|
230
221
|
* - `findings`: structured per-invariant outcomes. Always present (empty
|
|
231
222
|
* array means "all invariants passed"). Callers iterate to surface
|
|
232
223
|
* notifications and decide whether to abort spawning.
|
|
@@ -235,10 +226,6 @@ export interface SetupResult {
|
|
|
235
226
|
initialized: boolean;
|
|
236
227
|
scaffolded: string[];
|
|
237
228
|
error?: string;
|
|
238
|
-
legacyLayout?: {
|
|
239
|
-
/** Absolute path to the vault's `.napkin/` (= contentPath for legacy). */
|
|
240
|
-
configPath: string;
|
|
241
|
-
};
|
|
242
229
|
/**
|
|
243
230
|
* Set to `true` when the vault had a `.git/` but no commits (HEAD
|
|
244
231
|
* unresolvable) and auto-setup synthesized an empty initial commit to
|
|
@@ -253,23 +240,14 @@ export interface SetupResult {
|
|
|
253
240
|
findings: readonly HealthFinding[];
|
|
254
241
|
}
|
|
255
242
|
|
|
256
|
-
/**
|
|
257
|
-
* Sentinel value set in `SetupResult.error` when auto-setup refuses to
|
|
258
|
-
* scaffold because the vault is using napkin's legacy embedded layout.
|
|
259
|
-
* Exported so callers (session_start handler, tests) can branch on the
|
|
260
|
-
* exact sentinel instead of pattern-matching on the free-form message.
|
|
261
|
-
*/
|
|
262
|
-
export const LEGACY_EMBEDDED_LAYOUT_ERROR = "legacy-embedded-layout";
|
|
263
|
-
|
|
264
243
|
/**
|
|
265
244
|
* Minimal vault handle this module accepts. Mirrors
|
|
266
245
|
* `StaleCleanupVault` in `distill-workspace.ts` — keeps the callsite
|
|
267
246
|
* symmetric: both setup and cleanup take the same vault shape and
|
|
268
247
|
* neither forces the caller to construct a full Napkin instance.
|
|
269
248
|
*
|
|
270
|
-
* Both paths are required:
|
|
271
|
-
*
|
|
272
|
-
* them equal; subdir vaults have them distinct).
|
|
249
|
+
* Both paths are required: `configPath` anchors the config-file
|
|
250
|
+
* invariants, `contentPath` anchors the git operations.
|
|
273
251
|
*/
|
|
274
252
|
export interface SetupVault {
|
|
275
253
|
contentPath: string;
|
|
@@ -344,12 +322,6 @@ function runGit(
|
|
|
344
322
|
*/
|
|
345
323
|
const INVARIANT_GITIGNORE_BLOCK = "gitignore-block-correct";
|
|
346
324
|
|
|
347
|
-
/**
|
|
348
|
-
* Stable invariant ID for the layout check. Loud-error finding only;
|
|
349
|
-
* legacy-embedded vaults require manual migration to the subdir layout.
|
|
350
|
-
*/
|
|
351
|
-
const INVARIANT_SUBDIR_LAYOUT = "subdir-layout";
|
|
352
|
-
|
|
353
325
|
/**
|
|
354
326
|
* Stable invariant ID for the git-repo presence check. Auto-recovered
|
|
355
327
|
* via `git init -q -b main` when `.git/` is absent.
|
|
@@ -363,7 +335,8 @@ const INVARIANT_VAULT_IS_GIT_REPO = "vault-is-git-repo";
|
|
|
363
335
|
* pass. Untracked config.json is the root cause of Issue #14: distill
|
|
364
336
|
* worktrees are checked out via `git worktree add HEAD`, which copies
|
|
365
337
|
* only tracked files, so untracked config.json never reaches the
|
|
366
|
-
* worktree and napkin
|
|
338
|
+
* worktree and napkin inside the worktree resolves the real vault
|
|
339
|
+
* instead.
|
|
367
340
|
*/
|
|
368
341
|
const INVARIANT_CONFIG_JSON_TRACKED = "config.json-tracked";
|
|
369
342
|
|
|
@@ -920,12 +893,6 @@ function mergeManagedBlock(
|
|
|
920
893
|
* worktree-based spawn (`level: "full"`).
|
|
921
894
|
*
|
|
922
895
|
* Lifecycle (in execution order; per-step level scope noted):
|
|
923
|
-
* 0. fast + full: refuse if the vault uses napkin's legacy embedded
|
|
924
|
-
* layout (`configPath === contentPath`). Worktree-based concurrency
|
|
925
|
-
* doesn't work on legacy layouts because the branch can't track a
|
|
926
|
-
* `.napkin/` subdir that findVault could resolve to. Returns
|
|
927
|
-
* `{ error: "legacy-embedded-layout", legacyLayout, findings:
|
|
928
|
-
* [subdir-layout error] }` without touching git.
|
|
929
896
|
* 1. fast + full: if `.git/` is missing, run `git init -q -b main`
|
|
930
897
|
* (`vault-is-git-repo`, auto-recovered). Failure here aborts with
|
|
931
898
|
* `error`. (JSON validity is checked earlier by
|
|
@@ -990,38 +957,6 @@ export function ensureVaultReadyForDistill(
|
|
|
990
957
|
const vaultPath = vault.contentPath;
|
|
991
958
|
const findings: HealthFinding[] = [];
|
|
992
959
|
|
|
993
|
-
// Legacy-embedded layout is incompatible with the worktree-based
|
|
994
|
-
// concurrency architecture. In a legacy vault (`~/.napkin/`), the
|
|
995
|
-
// vault IS the `.napkin/` directory — `configPath === contentPath`.
|
|
996
|
-
// When a distill subprocess runs with `cwd = worktree` (a checkout of
|
|
997
|
-
// a `distill/*` branch that does NOT track a `.napkin/` subdir),
|
|
998
|
-
// napkin's `findVault` walks past the worktree and resolves to the
|
|
999
|
-
// user's REAL vault via the global config fallback. Writes bypass the
|
|
1000
|
-
// worktree entirely, making the concurrency guarantee a no-op.
|
|
1001
|
-
//
|
|
1002
|
-
// Refuse to scaffold here so session_start can surface a migration
|
|
1003
|
-
// notify. Manual `/distill` still works on any layout (it doesn't go
|
|
1004
|
-
// through this path).
|
|
1005
|
-
//
|
|
1006
|
-
// Detection mirrors napkin's own `resolveVaultLayout` semantics: subdir
|
|
1007
|
-
// layout sets `contentPath` via `vault.root` (distinct from `configPath`),
|
|
1008
|
-
// while legacy embedded layout has no `vault.root` and defaults both to
|
|
1009
|
-
// the `.napkin/` dir. See `@cad0p/napkin` `dist/utils/vault.js`.
|
|
1010
|
-
if (vault.configPath === vault.contentPath) {
|
|
1011
|
-
findings.push({
|
|
1012
|
-
kind: "error",
|
|
1013
|
-
invariant: INVARIANT_SUBDIR_LAYOUT,
|
|
1014
|
-
message: `Vault at ${vaultPath} uses the legacy embedded layout (configPath === contentPath); auto-distill requires the subdir layout.`,
|
|
1015
|
-
});
|
|
1016
|
-
return {
|
|
1017
|
-
initialized: false,
|
|
1018
|
-
scaffolded: [],
|
|
1019
|
-
error: LEGACY_EMBEDDED_LAYOUT_ERROR,
|
|
1020
|
-
legacyLayout: { configPath: vault.configPath },
|
|
1021
|
-
findings,
|
|
1022
|
-
};
|
|
1023
|
-
}
|
|
1024
|
-
|
|
1025
960
|
const gitDir = path.join(vaultPath, ".git");
|
|
1026
961
|
let initialized = false;
|
|
1027
962
|
|
|
@@ -1072,9 +1007,9 @@ export function ensureVaultReadyForDistill(
|
|
|
1072
1007
|
// Full-level only: confirm `<configPath>/config.json` is tracked by
|
|
1073
1008
|
// git. Distill worktrees are checked out via `git worktree add HEAD`
|
|
1074
1009
|
// which only copies tracked files — an untracked config.json never
|
|
1075
|
-
// reaches the worktree and napkin
|
|
1076
|
-
//
|
|
1077
|
-
// to scaffolded[] so the existing-repo branch below stages and
|
|
1010
|
+
// reaches the worktree and napkin inside the worktree resolves the
|
|
1011
|
+
// real vault instead. Closes Issue #14. Auto-recovers by adding the
|
|
1012
|
+
// file to scaffolded[] so the existing-repo branch below stages and
|
|
1078
1013
|
// commits it on the same pass.
|
|
1079
1014
|
//
|
|
1080
1015
|
// The auto-recovered finding is held back as `pending` and only
|
|
@@ -30,7 +30,7 @@ import * as fs from "node:fs";
|
|
|
30
30
|
import * as os from "node:os";
|
|
31
31
|
import * as path from "node:path";
|
|
32
32
|
|
|
33
|
-
import { Napkin } from "@cad0p/napkin";
|
|
33
|
+
import { NAPKIN_MARKER, Napkin } from "@cad0p/napkin";
|
|
34
34
|
import {
|
|
35
35
|
parseSessionEntries,
|
|
36
36
|
SessionManager,
|
|
@@ -149,7 +149,7 @@ export function generateDistillBranchName(
|
|
|
149
149
|
/**
|
|
150
150
|
* Relative path (from worktree root) of the distill `.napkin/distill/` dir.
|
|
151
151
|
*/
|
|
152
|
-
export const DISTILL_SUBDIR = path.join(
|
|
152
|
+
export const DISTILL_SUBDIR = path.join(NAPKIN_MARKER, "distill");
|
|
153
153
|
|
|
154
154
|
export const DISTILL_PROMPT_CACHE_KEY_ENV = "NAPKIN_DISTILL_PROMPT_CACHE_KEY";
|
|
155
155
|
|
|
@@ -725,7 +725,7 @@ export function resolveDistillErrorDir(vault: string): string {
|
|
|
725
725
|
try {
|
|
726
726
|
return path.join(new Napkin(vault).vault.configPath, "distill", "errors");
|
|
727
727
|
} catch {
|
|
728
|
-
return path.join(vault,
|
|
728
|
+
return path.join(vault, NAPKIN_MARKER, "distill", "errors");
|
|
729
729
|
}
|
|
730
730
|
}
|
|
731
731
|
|
|
@@ -970,8 +970,7 @@ export function spawnDistillInWorktree(
|
|
|
970
970
|
|
|
971
971
|
// Error dir lives on the MAIN vault (not in the worktree — worktrees are
|
|
972
972
|
// removed on cleanup, which would lose the logs). Resolve via Napkin's
|
|
973
|
-
// configPath
|
|
974
|
-
// both work.
|
|
973
|
+
// configPath (wherever it lives).
|
|
975
974
|
const errorDir = resolveDistillErrorDir(vault);
|
|
976
975
|
fs.mkdirSync(errorDir, { recursive: true });
|
|
977
976
|
|