@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 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-20260812.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
- }