@cad0p/pi-napkin 0.7.0-20260812.0 → 0.7.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 +0 -38
- package/package.json +1 -8
- package/extensions/steering/index.ts +0 -88
- package/extensions/steering/predicates.ts +0 -85
package/README.md
CHANGED
|
@@ -162,44 +162,6 @@ Both extensions use napkin's built-in vault resolution. The resolution order is:
|
|
|
162
162
|
|
|
163
163
|
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
164
|
|
|
165
|
-
## Steering integration
|
|
166
|
-
|
|
167
|
-
[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:
|
|
168
|
-
|
|
169
|
-
```bash
|
|
170
|
-
pi install npm:@cad0p/pi-napkin
|
|
171
|
-
```
|
|
172
|
-
|
|
173
|
-
Then make `@cad0p/pi-napkin` resolvable from your steering config. For the global config (`~/.pi/agent/steering/`, or wherever `<agentDir>/steering/` lives):
|
|
174
|
-
|
|
175
|
-
```bash
|
|
176
|
-
cd ~/.pi/agent/steering
|
|
177
|
-
pnpm add -D @cad0p/pi-napkin # or: npm i -D @cad0p/pi-napkin
|
|
178
|
-
```
|
|
179
|
-
|
|
180
|
-
And declare the plugin next to the git plugin:
|
|
181
|
-
|
|
182
|
-
```ts
|
|
183
|
-
// <agentDir>/steering/index.ts (global layer)
|
|
184
|
-
import { defineConfig } from "@cad0p/pi-steering";
|
|
185
|
-
import gitPlugin from "@cad0p/pi-steering/plugins/git";
|
|
186
|
-
import napkinSteeringPlugin from "@cad0p/pi-napkin/steering";
|
|
187
|
-
|
|
188
|
-
export default defineConfig({
|
|
189
|
-
plugins: [gitPlugin, napkinSteeringPlugin],
|
|
190
|
-
});
|
|
191
|
-
```
|
|
192
|
-
|
|
193
|
-
Requirements and semantics:
|
|
194
|
-
|
|
195
|
-
- **pi-steering ≥ 0.2.0-20260812.0** — the exemption registry landed in the 20260812 prerelease; stable 0.2.0 predates it.
|
|
196
|
-
- **`gitPlugin` MUST stay listed** — the exemptions target the git plugin's rule names; a missing target produces `exemption-orphan` warnings with no carve-out.
|
|
197
|
-
- **Zero path config** — a read-only walk-up from the command's effective cwd detects the vault by its `.napkin/` (or `.obsidian/.napkin/`) marker, mirroring napkin's own vault resolution. Goldmine, distill scratch worktrees under `~/.cache/napkin-distill/`, and future vaults are all covered automatically — no `VAULT_DIRS` to maintain.
|
|
198
|
-
- **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).
|
|
199
|
-
- **Accumulates** — exemptions union across plugins and config layers, so other tools can carve the same guards for other repo types without touching this config.
|
|
200
|
-
|
|
201
|
-
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]`.
|
|
202
|
-
|
|
203
165
|
### Migrating from `~/.pi/agent/napkin.json`
|
|
204
166
|
|
|
205
167
|
If you previously configured your vault in `~/.pi/agent/napkin.json`, move it to the new location:
|
package/package.json
CHANGED
|
@@ -1,14 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@cad0p/pi-napkin",
|
|
3
|
-
"version": "0.7.0
|
|
3
|
+
"version": "0.7.0",
|
|
4
4
|
"description": "📜 Napkin integration for pi — vault context, knowledge tools, and automatic distillation with git-worktree concurrency safety",
|
|
5
5
|
"type": "module",
|
|
6
|
-
"exports": {
|
|
7
|
-
"./steering": {
|
|
8
|
-
"types": "./extensions/steering/index.ts",
|
|
9
|
-
"import": "./extensions/steering/index.ts"
|
|
10
|
-
}
|
|
11
|
-
},
|
|
12
6
|
"publishConfig": {
|
|
13
7
|
"access": "public",
|
|
14
8
|
"registry": "https://registry.npmjs.org"
|
|
@@ -64,7 +58,6 @@
|
|
|
64
58
|
},
|
|
65
59
|
"devDependencies": {
|
|
66
60
|
"@biomejs/biome": "^2.3.14",
|
|
67
|
-
"@cad0p/pi-steering": "0.2.0-20260812.0",
|
|
68
61
|
"@types/node": "^22.0.0",
|
|
69
62
|
"tsx": "^4.19.0",
|
|
70
63
|
"typescript": "^5.8.0",
|
|
@@ -1,88 +0,0 @@
|
|
|
1
|
-
// SPDX-License-Identifier: MIT
|
|
2
|
-
// Part of pi-napkin.
|
|
3
|
-
|
|
4
|
-
import type { Plugin, PredicateShape } from "@cad0p/pi-steering";
|
|
5
|
-
import { isNapkinVault, isNapkinVaultDir } from "./predicates.ts";
|
|
6
|
-
|
|
7
|
-
declare global {
|
|
8
|
-
/**
|
|
9
|
-
* `when.isNapkinVault` — true when the effective cwd is inside a
|
|
10
|
-
* napkin vault (read-only `.napkin/`-marker walk-up). Registered
|
|
11
|
-
* by the napkin steering plugin; usable by any config that lists
|
|
12
|
-
* the plugin. Fail-closed: unknown cwd → `"unknown"` sentinel.
|
|
13
|
-
*/
|
|
14
|
-
interface PiSteeringPredicates {
|
|
15
|
-
isNapkinVault: PredicateShape<boolean>;
|
|
16
|
-
}
|
|
17
|
-
}
|
|
18
|
-
|
|
19
|
-
/**
|
|
20
|
-
* The napkin steering plugin for `@cad0p/pi-steering`.
|
|
21
|
-
*
|
|
22
|
-
* Subpath import: `@cad0p/pi-napkin/steering`.
|
|
23
|
-
*
|
|
24
|
-
* Registers (in the terms of `Plugin`):
|
|
25
|
-
*
|
|
26
|
-
* - `predicates` - `isNapkinVault` (see `./predicates.ts` for
|
|
27
|
-
* the fail-closed contract).
|
|
28
|
-
* - `exemptions` - carve-outs of the shipped git-plugin rules
|
|
29
|
-
* `no-main-commit` / `no-main-commit-github`
|
|
30
|
-
* when `when.isNapkinVault` matches. The
|
|
31
|
-
* napkin workflow legitimately commits +
|
|
32
|
-
* pushes to `main` inside vaults (note edits,
|
|
33
|
-
* the distill pipeline's scratch worktrees),
|
|
34
|
-
* so the guards stay ACTIVE everywhere else.
|
|
35
|
-
*
|
|
36
|
-
* This is the clean replacement for the hand-rolled global
|
|
37
|
-
* carve-out pattern (`...rule, not: { cwd: VAULT_DIRS }` copies +
|
|
38
|
-
* `disabledRules`), which did NOT compose across plugins: exemptions
|
|
39
|
-
* ACCUMULATE (union) across plugins and config layers, and target
|
|
40
|
-
* the shipped rule names — a stable public contract — so other tools
|
|
41
|
-
* can carve the same guards for other repo types without touching
|
|
42
|
-
* this plugin.
|
|
43
|
-
*
|
|
44
|
-
* Exemption clauses are STRICTLY fail-closed: `onUnknown` cannot be
|
|
45
|
-
* written anywhere inside them (type-level ban + load-time
|
|
46
|
-
* rejection), and unknown walker cwd never exempts — the target
|
|
47
|
-
* rule's own `onUnknown:` policy decides, so the guard still fires
|
|
48
|
-
* on an unresolvable cwd.
|
|
49
|
-
*
|
|
50
|
-
* No pi extension runtime involved: this module is a plain library
|
|
51
|
-
* (only node builtins at runtime — all pi-steering imports are
|
|
52
|
-
* type-only and erased by node's type stripping), so the steering
|
|
53
|
-
* global config can import it without pi being involved.
|
|
54
|
-
*
|
|
55
|
-
* Opt-in: nothing happens until the user lists this plugin next to
|
|
56
|
-
* the git plugin:
|
|
57
|
-
*
|
|
58
|
-
* ```ts
|
|
59
|
-
* import { defineConfig } from "@cad0p/pi-steering";
|
|
60
|
-
* import gitPlugin from "@cad0p/pi-steering/plugins/git";
|
|
61
|
-
* import napkinSteeringPlugin from "@cad0p/pi-napkin/steering";
|
|
62
|
-
*
|
|
63
|
-
* export default defineConfig({
|
|
64
|
-
* plugins: [gitPlugin, napkinSteeringPlugin],
|
|
65
|
-
* });
|
|
66
|
-
* ```
|
|
67
|
-
*
|
|
68
|
-
* `gitPlugin` MUST be listed alongside: the exemptions target its
|
|
69
|
-
* rule names, and a missing target surfaces `exemption-orphan`
|
|
70
|
-
* warnings with no carve-out.
|
|
71
|
-
*/
|
|
72
|
-
const napkinSteeringPlugin = {
|
|
73
|
-
name: "napkin",
|
|
74
|
-
predicates: {
|
|
75
|
-
isNapkinVault,
|
|
76
|
-
},
|
|
77
|
-
exemptions: [
|
|
78
|
-
{ rule: "no-main-commit", when: { isNapkinVault: true } },
|
|
79
|
-
{ rule: "no-main-commit-github", when: { isNapkinVault: true } },
|
|
80
|
-
],
|
|
81
|
-
} as const satisfies Plugin;
|
|
82
|
-
|
|
83
|
-
export default napkinSteeringPlugin;
|
|
84
|
-
|
|
85
|
-
// Named re-exports for consumers that want to pick pieces (e.g. a
|
|
86
|
-
// test harness constructing a minimal config that uses only the
|
|
87
|
-
// predicate without the shipped exemptions).
|
|
88
|
-
export { isNapkinVault, isNapkinVaultDir, napkinSteeringPlugin };
|
|
@@ -1,85 +0,0 @@
|
|
|
1
|
-
// SPDX-License-Identifier: MIT
|
|
2
|
-
// Part of pi-napkin.
|
|
3
|
-
|
|
4
|
-
import { existsSync, statSync } from "node:fs";
|
|
5
|
-
import * as path from "node:path";
|
|
6
|
-
import type { PredicateContext } from "@cad0p/pi-steering";
|
|
7
|
-
|
|
8
|
-
/**
|
|
9
|
-
* Directory marker that identifies a napkin vault (napkin's
|
|
10
|
-
* `findAncestorVault` / `findVault` walk looks for the same name).
|
|
11
|
-
*/
|
|
12
|
-
export const NAPKIN_MARKER = ".napkin";
|
|
13
|
-
|
|
14
|
-
/**
|
|
15
|
-
* Walk up from `startDir` looking for an existing vault's `.napkin/`
|
|
16
|
-
* (or `.obsidian/.napkin/` for the nested layout) at any level.
|
|
17
|
-
* Read-only structural mirror of napkin's `findAncestorVault`
|
|
18
|
-
* (`@cad0p/napkin/src/utils/vault.ts`) — deliberately NOT imported
|
|
19
|
-
* from `@cad0p/napkin`:
|
|
20
|
-
*
|
|
21
|
-
* - napkin's exports map is `"." → ./src/index.ts` only, so a deep
|
|
22
|
-
* import is blocked, and `findAncestorVault` isn't re-exported
|
|
23
|
-
* from the root.
|
|
24
|
-
* - a steering predicate must NEVER touch the filesystem beyond
|
|
25
|
-
* read probes: no `createBareVault` fallback and no global-vault
|
|
26
|
-
* fallback (`$XDG_CONFIG_HOME/napkin/config.json`). A global
|
|
27
|
-
* fallback would make every cwd a "vault" and exempt the
|
|
28
|
-
* no-main-commit guards everywhere.
|
|
29
|
-
*
|
|
30
|
-
* Returns the directory that contains the marker, or null.
|
|
31
|
-
*/
|
|
32
|
-
export function isNapkinVaultDir(startDir?: string): string | null {
|
|
33
|
-
let dir = path.resolve(startDir || process.cwd());
|
|
34
|
-
const root = path.parse(dir).root;
|
|
35
|
-
|
|
36
|
-
while (true) {
|
|
37
|
-
const napkinDir = path.join(dir, NAPKIN_MARKER);
|
|
38
|
-
if (existsSync(napkinDir) && statSync(napkinDir).isDirectory()) {
|
|
39
|
-
return dir;
|
|
40
|
-
}
|
|
41
|
-
|
|
42
|
-
const nestedNapkin = path.join(dir, ".obsidian", NAPKIN_MARKER);
|
|
43
|
-
if (existsSync(nestedNapkin) && statSync(nestedNapkin).isDirectory()) {
|
|
44
|
-
return dir;
|
|
45
|
-
}
|
|
46
|
-
|
|
47
|
-
const parent = path.dirname(dir);
|
|
48
|
-
if (parent === dir || dir === root) {
|
|
49
|
-
return null;
|
|
50
|
-
}
|
|
51
|
-
dir = parent;
|
|
52
|
-
}
|
|
53
|
-
}
|
|
54
|
-
|
|
55
|
-
/**
|
|
56
|
-
* `isNapkinVault` predicate handler — registered by the napkin
|
|
57
|
-
* steering plugin under the `when.isNapkinVault` slot
|
|
58
|
-
* (`PredicateShape<boolean>` bare form).
|
|
59
|
-
*
|
|
60
|
-
* Fail-closed contract:
|
|
61
|
-
*
|
|
62
|
-
* - `args !== true` → `false` (only the bare `true` form asks for
|
|
63
|
-
* the check; the spread `{ value: ... }` form is not meaningful
|
|
64
|
-
* for this boolean probe).
|
|
65
|
-
* - `ctx.cwd === "unknown"` (walker couldn't statically resolve
|
|
66
|
-
* the effective cwd) → returns the `"unknown"` sentinel, NOT
|
|
67
|
-
* `false`. Unknown cwd is not the same as "not a vault", and the
|
|
68
|
-
* trinary composes with the rule's own `onUnknown:` policy when
|
|
69
|
-
* the predicate is used as a public `when` leaf. Inside an
|
|
70
|
-
* exemption clause both verdicts behave identically — exemption
|
|
71
|
-
* clauses are STRICTLY fail-closed (anything non-true = no
|
|
72
|
-
* exemption = the guard still fires), so this can never weaken
|
|
73
|
-
* `no-main-commit` / `no-main-commit-github`.
|
|
74
|
-
* - Known cwd → read-only walk-up for the `.napkin/` marker
|
|
75
|
-
* (see {@link isNapkinVaultDir}). No writes, no global-config
|
|
76
|
-
* fallback.
|
|
77
|
-
*/
|
|
78
|
-
export function isNapkinVault(
|
|
79
|
-
args: unknown,
|
|
80
|
-
ctx: PredicateContext,
|
|
81
|
-
): boolean | "unknown" {
|
|
82
|
-
if (args !== true) return false;
|
|
83
|
-
if (ctx.cwd === "unknown") return "unknown";
|
|
84
|
-
return isNapkinVaultDir(ctx.cwd) !== null;
|
|
85
|
-
}
|