pi-skill-stacks 0.4.2 → 0.5.1

package/README.md

@@ -1,13 +1,6 @@
 # pi-skill-stacks
 
-A [pi](https://github.com/earendil-works/pi-mono) package that groups your skills into named stacks you can toggle on and off, so an agent session only pays for the skills it needs. `/stacks` opens an overlay; disabled skills vanish from the system prompt, `/skill:` commands, and discovery.
-
-## What it does
-
-- `/stacks` opens a two-pane overlay. Left: stacks with on/off state, create (`n`), delete (`d`), and `a` to add skills that aren't in any stack yet. Right: the selected stack's members; `space` removes one, `enter` opens the skill's full markdown in a viewer pane. So you can build and edit stacks without touching JSON. Changes persist as you make them; pi reloads once when you close the overlay, and only if a toggle actually changed `settings.json`.
-- `/stacks on <stack>` / `/stacks off <stack>` toggle a single stack (with argument completion); `/stacks list` prints state without changing anything. Bare `/stacks` outside the TUI (RPC/print mode) prints the list too.
-- Toggling off writes `!skills/<dir>/SKILL.md` exclusion patterns into the global settings `skills` array — pi's own override mechanism — so disabled skills are excluded everywhere, not just from the prompt. The extension only ever removes patterns it wrote itself (tracked in `managedExclusions`); hand-written `pi config` entries are left alone.
-- The bundled header extension replaces pi's startup `[Skills]` listing with a compact line like `matt-pocock (28), firecrawl (28) · 76/76 skills active` (with `off: <name> (n)` segments for disabled stacks) and hides the `[Themes]` section.
+A [pi](https://github.com/earendil-works/pi-mono) package that groups skills into named stacks you can toggle on and off. Disabled skills leave the system prompt, `/skill:` commands, and discovery.
 
 ## Install
 
@@ -15,27 +8,23 @@ A [pi](https://github.com/earendil-works/pi-mono) package that groups your skill
 pi install npm:pi-skill-stacks
 ```
 
-or from git:
-
-```bash
-pi install git:github.com/oscabriel/pi-skill-stacks
-```
+## Use
 
-Or from a local checkout:
+`/stacks` opens an overlay. Left pane: stacks with on/off state. Right pane: the selected stack's members. `enter` on a member shows its markdown.
 
-```bash
-pi install /path/to/pi-skill-stacks
-```
+| Pane | Keys |
+| --- | --- |
+| stacks | `↑`/`↓` select · `space` on/off · `→` members · `a` add skills · `n` new stack · `d` delete · `esc` close |
+| members | `↑`/`↓` move · `space` remove · `→` view · `a` add skills · `←` back |
+| viewer | `↑`/`↓` scroll (mouse wheel in fullscreen) · `←` back |
 
-Use `-l` to install project-local instead of global. Try it without installing:
+`a` lists skills not yet in any stack. To move a skill between stacks, `space` it out of one and `a` it into the other.
 
-```bash
-pi -e git:github.com/oscabriel/pi-skill-stacks
-```
+From the command line: `/stacks on <stack>`, `/stacks off <stack>`, `/stacks list`.
 
-## Configure stacks
+## How it works
 
-The package ships with no stacks. Open `/stacks` and press `n` to create one, or write `~/.pi/agent/skill-stacks.json` (or `<agentDir>/skill-stacks.json`; `PI_CODING_AGENT_DIR` is honoured like pi does) by hand:
+Stacks live in `~/.pi/agent/skill-stacks.json` (`PI_CODING_AGENT_DIR` is honoured). You can edit it by hand:
 
 ```json
 {
@@ -46,66 +35,16 @@ The package ships with no stacks. Open `/stacks` and press `n` to create one, or
 }
 ```
 
-Each stack maps a name to skill names. Skills are discovered the way pi discovers them: every `SKILL.md` under `~/.agents/skills/` and `<agentDir>/skills/`, recursing into subdirectories (skipping dot-directories and `node_modules`), named by the frontmatter `name` or, failing that, the directory name. Nested skills get full-path exclusion patterns such as `!skills/group/nested/SKILL.md`.
-
-A project can add or override stack definitions in `<project>/.pi/skill-stacks.json`. Project stacks contribute definitions only; on/off state is global. In the overlay they can be toggled but not edited or deleted — edit the project file instead.
-
-The config file is validated on every load. A malformed entry (a stack that isn't an array, invalid JSON, and so on) aborts the command with an error and nothing is written, rather than defaulting to an empty config and saving that back.
-
-## Overlay keys
-
-Navigation is consistent across panes: `←`/`esc` always goes back a pane, `→`/`tab` (or `enter` on a member) always goes forward. `←` in the leftmost pane and `→` in the viewer do nothing.
-
-| Pane | Keys |
-| --- | --- |
-| stacks | `↑`/`↓` (or `k`/`j`) select · `space` on/off · `→`/`l`/`tab`/`enter` into members · `a` add skills · `n` new stack · `d` delete · `esc`/`q` close |
-| members | `↑`/`↓` (or `k`/`j`) move · `space` remove the skill · `enter`/`→`/`tab` view skill · `a` add skills · `←`/`h`/`esc` back to stacks |
-| skill viewer | `↑`/`↓` (or `k`/`j`) scroll · `enter`/`←`/`h`/`esc` back to members |
-| add skills dialog | `↑`/`↓` move · `space` mark · `enter` add the marked skills (or the highlighted one) · `esc` cancel |
-| new stack / delete dialogs | `enter` confirm · `esc` cancel |
-
-The `a`, `n` and `d` dialogs open as small overlays on top of `/stacks`. `a` lists only skills that no stack holds yet. To move a skill between stacks, `space` it out of one and `a` it into the other.
-
-In fullscreen TUI mode the mouse wheel scrolls the skill viewer when the pointer is over the overlay. In regular mode the terminal owns the mouse and wheel input goes to its own scrollback.
-
-`enter` in the members pane opens the skill's full markdown in a viewer pane inside the overlay: frontmatter dim, headings bold, bullets and indented code rendered, links shown as their text.
-
-The title bar shows `reload pending` once a change has touched `settings.json`; the reload runs when you close the overlay.
-
-## Rules
-
-- **Overlap:** a skill is excluded only when it appears in at least one stack and no enabled stack contains it. Skills in no stack are never touched. So disabling a stack whose members all also belong to an enabled stack excludes nothing.
-- **Stacks, not skills:** `on`/`off` take stack names only. To exclude a single skill regardless of stacks, use `pi config` (its `!` entries are respected and never claimed).
-- **Persist-then-reload:** `on`/`off` commands write immediately and reload if `settings.json` changed. In the overlay every change is written as you make it and a single reload runs on close, again only if `settings.json` changed; re-stacking alone doesn't need one (the header line catches up on the next reload).
-- **Other projects' stacks:** a project stack you disabled from inside its project stays disabled when you toggle things elsewhere. Its `disabledStacks` entry and the exclusions written for its skills are preserved, because from another directory those skills are "in no stack" and so left alone.
-
-## Header
-
-The header extension swaps pi's full skills listing for a compact summary and hides `[Themes]`. It also replaces the stock header banner with a minimal one-line directory label. If you run your own header extension (custom art, dashboard, and so on), disable this one and keep yours — add a filter to the package entry in `settings.json`:
-
-```json
-{
-  "packages": [
-    {
-      "source": "git:github.com/oscabriel/pi-skill-stacks",
-      "extensions": ["!extensions/header.ts"]
-    }
-  ]
-}
-```
-
-Your header extension can import the section machinery from this package's `extensions/header.ts` to render the same compact line itself: `buildSkillsSection(cwd, theme)` builds the node, `replaceSkillsSection(root, node)` and `hideThemesSection(root)` splice pi's sections, `isOurSection`, `firstLineOf`, and `renderedText` are the matchers, and `SectionTheme`/`RenderableNode` are the structural types they take.
+Skills are discovered like pi does: every `SKILL.md` under `~/.agents/skills/` and `<agentDir>/skills/`, named by frontmatter `name` or the directory name. A project can add stack definitions in `<project>/.pi/skill-stacks.json`; those can be toggled but not edited from the overlay.
 
-## Notes
+Turning a stack off writes `!skills/<dir>/SKILL.md` patterns into the `skills` array of `~/.pi/agent/settings.json`, pi's own exclusion mechanism. The package only removes patterns it wrote itself; hand-written entries stay. A skill is excluded only when no enabled stack contains it, and skills in no stack are never touched. pi reloads once when the overlay closes, only if `settings.json` changed.
 
-- If a stack references skill names that don't resolve to a discovered skill, every `/stacks` invocation warns with the missing names, and the overlay flags them inline as `missing`.
-- Counts in the overlay and header only include discovered skills, so a stale name doesn't inflate the numbers.
-- `settings.json` is rewritten without a trailing newline to match pi's own formatting; `skill-stacks.json` ends with one.
+Stack names that don't match a discovered skill are flagged `missing` and not counted.
 
 ## Develop
 
 ```bash
-npm install        # dev-only: pi's type declarations for tsc
-npm run check      # typecheck
-npm test           # node --test
+npm install
+npm run check
+npm test
 ```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-skill-stacks",
-  "version": "0.4.2",
-  "description": "Pi package that groups skills into named stacks you can manage from a /stacks overlay — toggle stacks on/off and re-stack skills without editing JSON. Exclusions are written through pi's own settings override mechanism, and a compact [Skills] header line replaces the per-scope listing.",
+  "version": "0.5.1",
+  "description": "Pi package that groups skills into named stacks you can manage from a /stacks overlay — toggle stacks on/off and re-stack skills without editing JSON. Exclusions are written through pi's own settings override mechanism.",
   "keywords": [
     "pi-package",
     "pi",
@@ -27,8 +27,7 @@
   },
   "pi": {
     "extensions": [
-      "./extensions/index.ts",
-      "./extensions/header.ts"
+      "./extensions/index.ts"
     ]
   },
   "devDependencies": {

package/src/core.ts

@@ -36,7 +36,7 @@ export interface StacksSummary {
   offStacks: string[];
   totalCount: number;
   activeCount: number;
-  /** Per-stack status in definition order, for the header section body. */
+  /** Per-stack status in definition order. */
   stacks: StackStatus[];
 }
 
@@ -161,7 +161,7 @@ export function nextDisabledStacks(
   return sortNames(new Set([...unseen, ...visibleDisabled]));
 }
 
-/** Counts for the compact `[Skills]` header line. Only discovered skills are counted. */
+/** Stack and active-skill counts. Only discovered skills are counted. */
 export function summarizeStacks(
   stacks: StackMap,
   disabledStacks: string[],

package/src/store.ts

@@ -246,9 +246,10 @@ export function updateSettingsSkills(path: string, skills: string[]) {
 }
 
 /**
- * Fresh-from-disk summary for the compact `[Skills]` header line.
- * Returns undefined when no stacks are configured (leave pi's section alone).
- * Throws ConfigError on malformed config; the header catches and falls back.
+ * Fresh-from-disk stacks summary for external consumers (e.g. a user's own
+ * header extension). Not used by the package itself.
+ * Returns undefined when no stacks are configured. Throws ConfigError on
+ * malformed config; callers decide whether to fall back.
  */
 export function loadStacksSummary(cwd: string) {
   const global = loadStacksConfig();

package/extensions/header.ts

@@ -1,262 +0,0 @@
-/**
- * pi-skill-stacks header extension: replaces pi's startup `[Skills]` section
- * with a compact one-line summary (e.g. `matt-pocock (28), firecrawl (28) ·
- * 76/76 skills active`), hides the `[Themes]` section, and renders a minimal
- * one-line banner in place of pi's stock header.
- *
- * Disable this file (settings.json package filter `!extensions/header.ts`) to
- * keep your own header extension; the /stacks command extension is unaffected.
- * The section-building helpers are exported so a custom header can reuse them.
- *
- * Mechanism notes:
- * - pi's startup sections are childless leaves inside one container. The
- *   container's first rendered line can itself be "[Skills]" (when no
- *   [Context] section precedes it), so matchers require !hasChildren.
- * - showLoadedResources runs after extension session_start handlers, so
- *   post-paint sweeps alone flash the full listing for a frame. addChild
- *   wrapping swaps our node in at insertion time instead. Timed sweeps stay
- *   as fallback for late installs; resources_discover re-runs the walk.
- */
-import { homedir } from "node:os";
-import { isAbsolute, relative } from "node:path";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { Text, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
-import { loadStacksSummary } from "../src/store.ts";
-
-export interface RenderableNode {
-  children?: RenderableNode[];
-  addChild?(component: RenderableNode): void;
-  invalidate(): void;
-  render(width: number): string[];
-}
-
-/** Subset of pi's Theme we use; the real Theme is assignable to it. */
-export interface SectionTheme {
-  fg(color: "mdHeading" | "dim", text: string): string;
-}
-
-export interface DashboardTui extends RenderableNode {
-  requestRender(force?: boolean): void;
-}
-
-const RESET = "\x1b[0m";
-const BOLD = "\x1b[1m";
-const DIM = "\x1b[2m";
-const ANSI_PATTERN =
-  /[\u001B\u009B][[\]()#;?]*(?:(?:(?:[a-zA-Z\d]*(?:;[a-zA-Z\d]*)*)?\u0007)|(?:(?:\d{1,4}(?:;\d{0,4})*)?[\dA-PR-TZcf-nq-uy=><~]))/g;
-
-const hasChildren = (
-  component: RenderableNode,
-): component is RenderableNode & { children: RenderableNode[] } => Array.isArray(component.children);
-
-export function renderedText(component: RenderableNode) {
-  try {
-    return component.render(200).join("\n").replace(ANSI_PATTERN, "");
-  } catch {
-    return "";
-  }
-}
-
-export function firstLineOf(component: RenderableNode) {
-  return renderedText(component)
-    .split("\n")
-    .find((line) => line.trim())
-    ?.trim();
-}
-
-// Marks the section nodes we build, so the addChild interceptor and the sweep
-// never re-match them (their first rendered line is also exactly "[Skills]").
-const ourSections = new WeakSet<object>();
-
-export const isOurSection = (component: object) => ourSections.has(component);
-
-/** A pi section leaf we should act on: exact header line, childless, not one of ours. */
-const isPiSection = (child: RenderableNode, header: string) =>
-  firstLineOf(child) === header && !hasChildren(child) && !isOurSection(child);
-
-export function hideThemesSection(component: RenderableNode): boolean {
-  if (!hasChildren(component)) return false;
-
-  for (let index = 0; index < component.children.length; index += 1) {
-    const child = component.children[index]!;
-    // Leaf check: pi's section components are childless ExpandableText nodes.
-    // The parent resources container can render the same first line when it's
-    // the first section, and matching it would splice out every section.
-    if (isPiSection(child, "[Themes]")) {
-      const next = component.children[index + 1];
-      const removeCount = next && renderedText(next).trim() === "" ? 2 : 1;
-      component.children.splice(index, removeCount);
-      component.invalidate();
-      return true;
-    }
-    if (hideThemesSection(child)) return true;
-  }
-  return false;
-}
-
-/**
- * Build a replacement [Skills] section styled like pi's own sections:
- * mdHeading header line, dim indented body listing each stack with its size,
- * disabled stacks separately, plus the active-skill count. Data is read fresh
- * from disk so it stays correct across /reload. Returns undefined when no
- * stacks are configured or the config is unreadable (pi's section is left alone).
- */
-export function buildSkillsSection(cwd: string, theme: SectionTheme | undefined) {
-  let summary;
-  try {
-    summary = loadStacksSummary(cwd);
-  } catch {
-    return undefined;
-  }
-  if (!summary) return undefined;
-  const heading = (text: string) => (theme ? theme.fg("mdHeading", text) : `${BOLD}${text}${RESET}`);
-  const dim = (text: string) => (theme ? theme.fg("dim", text) : `${DIM}${text}${RESET}`);
-  const label = (stack: { name: string; size: number }) => `${stack.name} (${stack.size})`;
-  const on = summary.stacks.filter((stack) => stack.enabled).map(label).join(", ");
-  const off = summary.stacks.filter((stack) => !stack.enabled).map(label).join(", ");
-  const parts: string[] = [];
-  if (on) parts.push(on);
-  if (off) parts.push(`off: ${off}`);
-  parts.push(`${summary.activeCount}/${summary.totalCount} skills active`);
-  const section = new Text(`${heading("[Skills]")}\n${dim(`  ${parts.join(" · ")}`)}`, 0, 0);
-  ourSections.add(section);
-  return section;
-}
-
-export function replaceSkillsSection(component: RenderableNode, section: Text): boolean {
-  if (!hasChildren(component)) return false;
-
-  for (let index = 0; index < component.children.length; index += 1) {
-    const child = component.children[index]!;
-    if (isPiSection(child, "[Skills]")) {
-      component.children.splice(index, 1, section);
-      component.invalidate();
-      return true;
-    }
-    if (replaceSkillsSection(child, section)) return true;
-  }
-  return false;
-}
-
-function formatDirectory(cwd: string) {
-  const home = homedir();
-  if (cwd === home) return "~";
-  const rel = relative(home, cwd);
-  return rel.startsWith("..") || isAbsolute(rel) ? cwd : `~/${rel}`;
-}
-
-export default function skillStacksHeader(pi: ExtensionAPI) {
-  let cwd = process.cwd();
-  let activeTui: DashboardTui | undefined;
-  let sectionTheme: SectionTheme | undefined;
-  let banner: string[] = [];
-  let fixupTimers: Array<ReturnType<typeof setTimeout>> = [];
-  const interceptedContainers = new WeakSet<object>();
-
-  // One disk read per fixup cycle: the interceptor and every sweep in the
-  // cycle share the same section instead of re-scanning the skill roots.
-  let cachedSection: { cwd: string; section: Text | undefined } | undefined;
-  function skillsSection() {
-    if (!cachedSection || cachedSection.cwd !== cwd) {
-      cachedSection = { cwd, section: buildSkillsSection(cwd, sectionTheme) };
-    }
-    return cachedSection.section;
-  }
-
-  // Wrap addChild on every container reachable from the TUI root so pi's
-  // [Skills] section is swapped (and [Themes] dropped) at insertion time,
-  // before the first paint.
-  function interceptContainers(node: RenderableNode) {
-    if (hasChildren(node) && typeof node.addChild === "function" && !interceptedContainers.has(node)) {
-      interceptedContainers.add(node);
-      const original = node.addChild.bind(node);
-      let dropNextBlank = false;
-      node.addChild = (child: RenderableNode) => {
-        if (dropNextBlank) {
-          dropNextBlank = false;
-          // The spacer pi adds right after the section it belongs to.
-          if (!renderedText(child).trim()) return;
-        }
-        if (!isOurSection(child)) {
-          const firstLine = firstLineOf(child);
-          if (firstLine === "[Themes]") {
-            dropNextBlank = true;
-            return;
-          }
-          if (firstLine === "[Skills]") {
-            const section = skillsSection();
-            if (section) {
-              original(section);
-              return;
-            }
-          }
-        }
-        original(child);
-      };
-    }
-    if (hasChildren(node)) {
-      for (const child of node.children) interceptContainers(child);
-    }
-  }
-
-  // Fallback for sections that were inserted before we wrapped their
-  // container (e.g. this extension loading into an already-painted session).
-  function sweepHeader(tui: DashboardTui) {
-    let changed = hideThemesSection(tui);
-    const section = skillsSection();
-    if (section && replaceSkillsSection(tui, section)) changed = true;
-    if (changed) tui.requestRender(true);
-  }
-
-  function clearFixupTimers() {
-    for (const timer of fixupTimers) clearTimeout(timer);
-    fixupTimers = [];
-  }
-
-  function scheduleHeaderFixups(tui: DashboardTui) {
-    clearFixupTimers();
-    cachedSection = undefined;
-    interceptContainers(tui);
-    sweepHeader(tui);
-    for (const delay of [0, 50, 250, 1_000]) {
-      fixupTimers.push(setTimeout(() => sweepHeader(tui), delay));
-    }
-  }
-
-  pi.on("session_start", (_event, ctx) => {
-    cwd = ctx.cwd;
-    if (ctx.mode !== "tui") return;
-
-    ctx.ui.setHeader((tui, theme) => {
-      activeTui = tui;
-      sectionTheme = theme;
-      const label = theme.fg("muted", formatDirectory(cwd));
-      banner = [];
-      scheduleHeaderFixups(tui);
-
-      return {
-        render(width: number) {
-          // One dim centered line: the working directory.
-          if (banner.length === 0) {
-            const padding = Math.max(0, Math.floor((width - visibleWidth(label)) / 2));
-            banner = [truncateToWidth(`${" ".repeat(padding)}${label}`, width)];
-          }
-          return banner;
-        },
-        invalidate() {
-          banner = [];
-        },
-      };
-    });
-  });
-
-  pi.on("resources_discover", () => {
-    if (activeTui) scheduleHeaderFixups(activeTui);
-  });
-
-  pi.on("session_shutdown", (_event, ctx) => {
-    clearFixupTimers();
-    activeTui = undefined;
-    if (ctx.mode === "tui") ctx.ui.setHeader(undefined);
-  });
-}