pi-lean-dimension 0.3.2 → 0.4.0

package/node_modules/pi-tool-masking/README.md

@@ -2,7 +2,7 @@
 
 A library for pi plugin developers that groups tools into toggleable **toolsets** with persistent state and cross-extension events — eliminating the boilerplate every pi extension repeats when it wants to let users disable tools cleanly.
 
-`pi-tool-masking` is **not** a pi extension itself. It is a peer dependency that your extension imports. It owns the toggle logic, the session-restore path, and the event bus. Your extension owns the commands, the status bar, and the user-facing surfaces.
+`pi-tool-masking` is **not** a pi extension itself. It is a dependency that your extension imports. It owns the toggle logic, the session-restore path, and the event bus. Your extension owns the commands, the status bar, and the user-facing surfaces.
 
 ---
 
@@ -16,7 +16,7 @@ Without `pi-tool-masking`, every pi extension that toggles tools reimplements th
 4. On `session_start` / `session_tree`, walk the branch for persisted entries and re-apply state.
 5. Emit events so side-effect owners (status bars, pickers) can re-render.
 
-`pi-tool-masking` does all of that in one call: `defineToolset(pi, spec)`. It also adds dependency cascading (enabling a toolset auto-enables its dependencies) and reverse cascading (disabling a toolset auto-disables dependents).
+`pi-tool-masking` does all of that in one call: `defineToolset(pi, spec)`. It also adds dependency cascading (enabling a toolset auto-enables its dependencies) and reverse cascading (disabling a toolset auto-disables dependents), plus a settings tier for per-scope defaults and allowlist mode for reliable focus across reloads.
 
 ---
 
@@ -89,19 +89,24 @@ Register a toolset and receive a `Toolset` handle (`enable`, `disable`, `isEnabl
 
 **Idempotent re-registration:** calling `defineToolset` with the same `spec.id` and an unchanged spec returns the existing toolset. This is safe across `/reload`.
 
-### `setDefaultResolutionMode(pi, mode)`
+### `setDefaultResolutionMode(pi, mode, allowlist?)`
 
-Switch how toolsets with no persisted state resolve on restore. Two modes:
+Switch how toolsets with no persisted state resolve on restore. Three modes:
 
 | Mode | Behavior on restore (no persisted entry) |
 |---|---|
 | `"exclusion"` (default) | Toolsets default **on** if `defaultEnabled` is true, **off** otherwise |
-| `"inclusion"` | All unknown toolsets default **off** — useful for focus-mode "only these tools" workflows |
+| `"inclusion"` (@deprecated since 1.2.0) | All unknown toolsets default **off** — a weaker, unbounded floor. Use `"allowlist"` instead for focus-style "only these tools" suppression |
+| `"allowlist"` | Only the listed toolset ids are **on**, everything else **off** — a finite, branch-persisted set whose complement is computed at restore, resilient to toolsets installed later. Pass the array as the third argument: `setDefaultResolutionMode(pi, "allowlist", ["my-plugin.web"])` |
 
 ### `getDefaultResolutionMode()`
 
 Read the current default resolution mode. Returns `"exclusion"` until a session restore loads the persisted mode.
 
+### `getActiveAllowlist()`
+
+Read the live allowlist array from module state. Returns the `string[]` when the active mode is `"allowlist"`, otherwise `undefined`. Parameterless (like `getDefaultResolutionMode`) — the downstream call site receives `ExtensionAPI`, which doesn't expose `sessionManager`, so the branch can't be read there. The branch remains the source of truth; module state is the live mirror, snapped from the last mode branch entry by `doRestore` (and by `setDefaultResolutionMode` when it appends the entry). A consumer consults this to keep toolsets registered *after* focus was entered off.
+
 ### `getRegisteredToolsets()`
 
 Return a read-only snapshot of every registered toolset (`{ spec, toolset }`). No `pi` argument needed — pure registry read.
@@ -121,10 +126,59 @@ Return a read-only snapshot of every registered toolset (`{ spec, toolset }`). N
 | `Toolset` | Handle returned by `defineToolset` |
 | `ToolsetChangedEvent` | Shape of events emitted by `TOOLSET_EVENTS` |
 | `RegistryEntry` | `{ spec: ToolsetSpec; toolset: Toolset }` — a single registered toolset |
-| `DefaultResolutionMode` | `"exclusion" \| "inclusion"` |
+| `DefaultResolutionMode` | `"exclusion" \| "inclusion" \| "allowlist"` |
+| `MalformedSettingsError` | Thrown by `writeToolsetDefaults` / `clearToolsetDefaults` when settings.json is corrupt or non-object (never silently overwritten). Catch with `instanceof`. |
 
 ---
 
+## Toolset defaults (settings tier)
+
+A toolset's fresh-session default is no longer locked to its packaged `spec.defaultEnabled`. Users can pin `{ enabled: boolean }` under a reserved `toolsetDefaults` key in pi-core settings, keyed by the toolset's full `persistKey` — without toggling (which writes a session-scoped chat-branch entry). The library reads both files itself inside `doRestore`, fresh on each `/reload`, so downstream consumers no longer need to reinvent a settings reader to inject values into `spec.defaultEnabled` before `defineToolset`.
+
+Restore resolves each toolset's default in this order (first hit wins):
+
+1. **Chat-branch entry** — the last `appendEntry(persistKey, …)` on this branch. A `null` tombstone (see [`clearToolsetEntry`](#tombstone-helpers)) falls through to tier 2.
+2. **Settings pin** — `toolsetDefaults[persistKey].enabled`, merged global → project (project wins per entry). Mode-agnostic.
+3. **Packaged default** — `spec.defaultEnabled ?? true`, filtered by resolution mode for unpinned toolsets only.
+
+Settings pins are honored in all three modes, mirroring how chat-branch entries are honored — only unpinned toolsets consult mode for the floor.
+
+### `readMergedToolsetDefaults()`
+
+Read and merge `toolsetDefaults` from global (`~/.pi/agent/settings.json`, or `$PI_CODING_AGENT_DIR/settings.json`) and project (`<cwd>/.pi/settings.json`) settings. Project overrides global per entry. Missing/unreadable/malformed files contribute `{}`. Never throws. Returns `Record<persistKey, { enabled: boolean }>`. Read once per loop and pass the snapshot to `getEffectiveDefault` to avoid re-reading disk per toolset.
+
+### `readToolsetDefaults(scope)`
+
+Read one scope's raw `toolsetDefaults` block (no merge). `scope` is `"global"` or `"project"`. Same never-throw policy. Use for `defaults show`-style commands that need per-scope attribution.
+
+### `writeToolsetDefaults(entries, scope)`
+
+Merge a batch of `{ [persistKey]: { enabled } }` entries into one scope's `toolsetDefaults`, preserving every other top-level key and every existing entry not in `entries`. A write where every entry already matches its on-disk value is a no-op (no reformat, no mtime bump). Returns the settings file path. **Throws `MalformedSettingsError`** if the file exists but parses to a non-object or is unparsable — a corrupt file is never silently overwritten.
+
+### `clearToolsetDefaults(scope)`
+
+Remove the `toolsetDefaults` wrapper key entirely from one scope, preserving every other top-level key. Returns the path removed from, or `null` if the key was already absent (or the file missing). No per-entry clear by design — write an `entries` map without the unwanted keys via `writeToolsetDefaults`. Same `MalformedSettingsError` guard.
+
+### `getEffectiveDefault(spec, snapshot?)`
+
+Resolve a toolset's effective fresh-session default: settings tier (2) then packaged `spec.defaultEnabled ?? true` (3). **Ignores resolution mode** — callers needing mode-aware behavior must consult `getDefaultResolutionMode()` themselves. Pass an explicit `snapshot` (from `readMergedToolsetDefaults()`) when looping over multiple toolsets; omit it for a one-off (it performs its own read).
+
+## Tombstone helpers
+
+Within pi-core's append-only `SessionManager`, a toolset's chat-branch entry can't be deleted — but a `null` tombstone appended after the last entry makes `doRestore` fall through to the settings tier so settings re-assert. Tombstones are dedup'd (no-op when the last entry is already cleared) and never written for never-toggled toolsets. A later manual toggle appends after the tombstone and supersedes it.
+
+### `clearToolsetEntry(pi, persistKey, branch)`
+
+Append a `null` tombstone for one toolset's branch entry (dedup'd). `branch` is the caller's `ctx.sessionManager.getBranch()` snapshot — `ExtensionAPI` exposes `appendEntry` but not `sessionManager`, so the dedup read comes from the caller.
+
+### `clearAllToolsetEntries(pi, branch)`
+
+Tombstone every registered toolset's branch entry (dedup'd per toolset). Covers exactly the toolsets in the global registry.
+
+### `applyToolsetEnabled(pi, spec, enabled)`
+
+Apply a toolset's enabled state via `setActiveTools` and emit `TOOLSET_EVENTS.changed` **without** writing a branch entry — the live-apply half of a settings restore (pull a toolset to its settings/packaged default without persisting a chat-branch pin).
+
 ## ToolsetSpec fields
 
 ```ts
@@ -206,15 +260,18 @@ pi.events.on(TOOLSET_EVENTS.restored, (event) => {
 });
 ```
 
-### Focus mode (inclusion resolution)
+### Focus mode (allowlist resolution)
 
 ```ts
 import { setDefaultResolutionMode, getRegisteredToolsets } from "pi-tool-masking";
 
-// Enter focus: set inclusion mode so unknown toolsets stay off
-setDefaultResolutionMode(pi, "inclusion");
+// Enter focus: allowlist mode keeps only the listed toolsets on — restore
+// applies it on the next /reload, and the loop below applies it live.
+// "inclusion" (deprecated) cannot guarantee this: a toolset installed after
+// focus leaks on, because the set of "on" toolsets was never recorded.
+setDefaultResolutionMode(pi, "allowlist", ["my-plugin.web"]);
 
-// Enable only the allowlisted toolsets
+// Apply live: enable only the allowlisted toolsets
 const allowlist = new Set(["my-plugin.web"]);
 for (const entry of getRegisteredToolsets()) {
  if (allowlist.has(entry.spec.id)) {
@@ -228,8 +285,8 @@ for (const entry of getRegisteredToolsets()) {
 ### Dependent toolsets
 
 ```ts
-// Portal tools are on by default; learn tools depend on portal
-const portalSpec: ToolsetSpec = {
+// Web tools are on by default; learn tools depend on web
+const webSpec: ToolsetSpec = {
  id: "my-plugin.web",
  names: new Set(["web-fetch", "web-snapshot"]),
  persistKey: "toolset-state:my-plugin.web",
@@ -247,11 +304,44 @@ const learnSpec: ToolsetSpec = {
 
 ---
 
+## Toolset naming
+
+`defineToolset` can't tell which extension is calling it — pi's `ExtensionAPI`
+doesn't expose the caller — so error messages can't name the responsible
+extension directly. The toolset id is the only traceability signal, which is
+why a stable, attributable id convention matters.
+
+### Convention (recommended, not enforced)
+
+Prefix toolset ids with a stable namespace: `<product-family>.<subset>`, e.g.
+`my-plugin.web`. The family may span multiple npm packages, and nothing checks
+that the prefix matches a real package — it's for human traceability in
+`/tbox list` and collision errors, not verification.
+
+### Enforcement floor
+
+`defineToolset` enforces one naming invariant: **no two toolsets may claim the
+same tool name.** Overlap is essentially always an authoring mistake and throws
+at load time:
+
+```
+[pi-tool-masking] name overlap: toolset "foo.search" claims tools already
+owned by another toolset:
+  - tool "x" already claimed by toolset "bar.web" (registered from
+    /home/u/.pi/.../bar/index.ts, source: bar)
+Each tool may belong to only one toolset. Naming convention: prefix toolset
+ids with a stable namespace (<product-family>.<subset>, e.g. "foo.web").
+```
+
+---
+
 ## How it works (for the curious)
 
 - **Registration:** `defineToolset` stores the spec and handle in a global registry (shared across module instances, so multiple extensions see the same toolsets).
 - **Persistence:** each toolset writes `{ enabled }` entries under its `persistKey` on the session branch. On `session_start` or `session_tree`, the library re-reads the branch and applies the last persisted state.
-- **Default resolution:** a single `toolset-resolution-mode` entry on the branch controls whether unknown toolsets default on or off. This is set by `setDefaultResolutionMode` and persists across reloads.
+- **Default resolution:** a `toolset-resolution-mode` entry on the branch controls how toolsets with no persisted state resolve on restore — `exclusion` (on/off by `defaultEnabled`), `inclusion` (deprecated unbounded floor), or `allowlist` (a finite branch-persisted array whose complement is computed at restore). Set by `setDefaultResolutionMode`, persists across reloads.
+- **Defaults tiers:** each toolset's restore default resolves chat-branch entry → `toolsetDefaults` settings pin → packaged `spec.defaultEnabled`, filtered by resolution mode for unpinned toolsets only. Settings pins are read fresh from disk on each restore.
+- **Null-tombstone-aware restore:** a `null` last branch entry (written by `clearToolsetEntry`) falls through to the settings tier instead of any stale prior entry; mode resolution is likewise null-tombstone-aware (`branchMode ?? "exclusion"`). Tombstones aren't sticky — a later toggle supersedes them.
 - **Events:** a live toggle emits only when state actually changes (no-op toggles are suppressed); restore always emits, so side-effect owners stay in sync across reloads and tree navigations.
 
 ---
@@ -267,4 +357,4 @@ This package is used by:
 
 ## License
 
-GNU Affero General Public License v3.0 (AGPL-3.0). See [LICENSE](./LICENSE).
+MIT. See [LICENSE](./LICENSE).