pi-skill-stacks 0.5.1 → 0.6.0

package/README.md

@@ -18,7 +18,9 @@ pi install npm:pi-skill-stacks
 | members | `↑`/`↓` move · `space` remove · `→` view · `a` add skills · `←` back |
 | viewer | `↑`/`↓` scroll (mouse wheel in fullscreen) · `←` back |
 
-`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.
+`a` opens a picker of skills not yet in any stack. Type to filter it, `space` to mark several, `enter` to add. To move a skill between stacks, `space` it out of one and `a` it into the other.
+
+With no stacks defined, `enter` (or `n`) creates the first one and opens the picker right after.
 
 From the command line: `/stacks on <stack>`, `/stacks off <stack>`, `/stacks list`.
 
@@ -41,6 +43,8 @@ Turning a stack off writes `!skills/<dir>/SKILL.md` patterns into the `skills` a
 
 Stack names that don't match a discovered skill are flagged `missing` and not counted.
 
+For other extensions, `loadStacksSummary()` in `src/store.ts` returns stack names, on/off state, and counts (`totalCount`, `activeCount`, `unstackedCount`).
+
 ## Develop
 
 ```bash

package/extensions/dialogs.ts

@@ -7,10 +7,30 @@
 import { type Component, type Focusable, Input, Key, matchesKey } from "@earendil-works/pi-tui";
 import { frameEdge, frameInnerWidth, frameRow, type OverlayTheme, padToWidth } from "./frame.ts";
 
-/** Single-line text prompt. Resolves with the trimmed value, or undefined on escape. */
-export class PromptDialog implements Component, Focusable {
-  private readonly input = new Input();
+/**
+ * A dialog built around one pi-tui Input. Focus is forwarded to the Input so it
+ * emits the hardware-cursor marker (IME placement) while the dialog is open.
+ */
+abstract class InputDialog implements Component, Focusable {
+  protected readonly input = new Input();
   private _focused = false;
+
+  get focused() {
+    return this._focused;
+  }
+
+  set focused(value: boolean) {
+    this._focused = value;
+    this.input.focused = value;
+  }
+
+  abstract handleInput(data: string): void;
+  abstract render(width: number): string[];
+  invalidate() {}
+}
+
+/** Single-line text prompt. Resolves with the trimmed value, or undefined on escape. */
+export class PromptDialog extends InputDialog {
   private readonly theme: OverlayTheme;
   private readonly title: string;
   private readonly placeholder: string | undefined;
@@ -22,22 +42,13 @@ export class PromptDialog implements Component, Focusable {
     placeholder: string | undefined,
     done: (value: string | undefined) => void,
   ) {
+    super();
     this.theme = theme;
     this.title = title;
     this.placeholder = placeholder;
     this.done = done;
   }
 
-  /** Propagate focus to the Input so it emits the hardware-cursor marker (IME placement). */
-  get focused() {
-    return this._focused;
-  }
-
-  set focused(value: boolean) {
-    this._focused = value;
-    this.input.focused = value;
-  }
-
   handleInput(data: string) {
     if (matchesKey(data, Key.enter) || data === "\n") {
       this.done(this.input.getValue().trim());
@@ -48,8 +59,6 @@ export class PromptDialog implements Component, Focusable {
     }
   }
 
-  invalidate() {}
-
   render(width: number) {
     const inner = frameInnerWidth(width);
     const [inputLine = ""] = this.input.render(inner);
@@ -100,11 +109,12 @@ export class ConfirmDialog implements Component {
 }
 
 /**
- * Pick one or more skills from a list. `space` marks, `enter` resolves with the
- * marked set (or just the highlighted skill when nothing is marked), `esc`
- * resolves undefined.
+ * Pick one or more skills from a searchable list. Typing filters (case-insensitive
+ * substring); `space` marks, `enter` resolves with the marked set (or just the
+ * highlighted skill when nothing is marked — marks survive refiltering), `esc`
+ * resolves undefined. Arrows move; plain letters go to the filter, so no j/k here.
  */
-export class PickDialog implements Component {
+export class PickDialog extends InputDialog {
   static readonly MAX_ROWS = 16;
 
   private readonly theme: OverlayTheme;
@@ -114,6 +124,8 @@ export class PickDialog implements Component {
   private readonly marked = new Set<string>();
   private cursor = 0;
   private offset = 0;
+  /** Filtered view of `items`, recomputed only when the query changes. */
+  private matchCache: { query: string; items: string[] } | undefined;
 
   constructor(
     theme: OverlayTheme,
@@ -121,6 +133,7 @@ export class PickDialog implements Component {
     items: readonly string[],
     done: (picked: string[] | undefined) => void,
   ) {
+    super();
     this.theme = theme;
     this.title = title;
     this.items = items;
@@ -129,45 +142,74 @@ export class PickDialog implements Component {
 
   handleInput(data: string) {
     if (matchesKey(data, Key.enter) || data === "\n") {
-      const highlighted = this.items[this.cursor];
+      const matches = this.matches();
+      const highlighted = matches[this.cursor];
       const picked = this.marked.size > 0 ? this.items.filter((s) => this.marked.has(s)) : highlighted ? [highlighted] : [];
       this.done(picked);
     } else if (matchesKey(data, Key.escape)) {
       this.done(undefined);
-    } else if (matchesKey(data, Key.down) || data === "j") {
+    } else if (matchesKey(data, Key.down)) {
       this.move(1);
-    } else if (matchesKey(data, Key.up) || data === "k") {
+    } else if (matchesKey(data, Key.up)) {
       this.move(-1);
     } else if (data === " ") {
-      const skill = this.items[this.cursor];
+      const skill = this.matches()[this.cursor];
       if (!skill) return;
       if (this.marked.has(skill)) this.marked.delete(skill);
       else this.marked.add(skill);
+    } else {
+      this.input.handleInput(data);
+      this.clampToMatches();
     }
   }
 
-  invalidate() {}
-
   render(width: number) {
+    const inner = frameInnerWidth(width);
     const rows = this.visibleRows();
+    const matches = this.matches();
     const lines = [frameEdge(this.theme, width, this.title, true)];
+    const query = this.input.getValue();
+    const [inputLine = ""] = this.input.render(inner);
+    lines.push(frameRow(this.theme, width, query === "" ? this.theme.fg("dim", "type to filter") : inputLine));
     for (let row = 0; row < rows; row += 1) {
       const index = this.offset + row;
-      const skill = this.items[index];
-      lines.push(frameRow(this.theme, width, skill ? this.cell(skill, index, frameInnerWidth(width)) : ""));
+      const skill = matches[index];
+      lines.push(frameRow(this.theme, width, skill ? this.cell(skill, index, inner) : ""));
     }
     const marked = this.marked.size > 0 ? ` · ${this.marked.size} marked` : "";
-    lines.push(frameEdge(this.theme, width, `↑↓ move · space mark · enter add${marked} · esc cancel`, false));
+    const filtered = query === "" ? "" : ` · ${matches.length}/${this.items.length}`;
+    lines.push(frameEdge(this.theme, width, `type filter · ↑↓ move · space mark · enter add${marked}${filtered} · esc cancel`, false));
     return lines;
   }
 
   private visibleRows() {
-    return Math.max(1, Math.min(PickDialog.MAX_ROWS, this.items.length));
+    return Math.max(1, Math.min(PickDialog.MAX_ROWS, this.matches().length));
+  }
+
+  /** Items that match the current filter, in list order. Cached per query; callers must not mutate it. */
+  private matches(): readonly string[] {
+    const query = this.input.getValue().trim().toLowerCase();
+    if (this.matchCache?.query !== query) {
+      this.matchCache = {
+        query,
+        items: query === "" ? [...this.items] : this.items.filter((item) => item.toLowerCase().includes(query)),
+      };
+    }
+    return this.matchCache.items;
+  }
+
+  /** Keep cursor and scroll window inside the filtered list after a query change. */
+  private clampToMatches() {
+    const total = this.matches().length;
+    this.cursor = Math.max(0, Math.min(total - 1, this.cursor));
+    const rows = this.visibleRows();
+    this.offset = Math.max(0, Math.min(this.offset, Math.max(0, total - rows)));
   }
 
   private move(delta: number) {
-    if (this.items.length === 0) return;
-    this.cursor = Math.max(0, Math.min(this.items.length - 1, this.cursor + delta));
+    const total = this.matches().length;
+    if (total === 0) return;
+    this.cursor = Math.max(0, Math.min(total - 1, this.cursor + delta));
     const rows = this.visibleRows();
     if (this.cursor < this.offset) this.offset = this.cursor;
     else if (this.cursor >= this.offset + rows) this.offset = this.cursor - rows + 1;

package/extensions/frame.ts

@@ -37,3 +37,33 @@ export function frameRow(theme: OverlayTheme, width: number, content: string) {
 
 /** Width available to content inside `frameRow`. */
 export const frameInnerWidth = (width: number) => Math.max(0, width - 4);
+
+/** Word-wrap plain text to `width` display columns; over-long words are hard-split. */
+export function wrapText(text: string, width: number): string[] {
+  const out: string[] = [];
+  for (const paragraph of text.split("\n")) {
+    if (paragraph === "") {
+      out.push("");
+      continue;
+    }
+    let line = "";
+    for (const word of paragraph.split(" ")) {
+      const candidate = line ? `${line} ${word}` : word;
+      if (visibleWidth(candidate) <= width) {
+        line = candidate;
+        continue;
+      }
+      if (line) out.push(line);
+      let rest = word;
+      while (visibleWidth(rest) > width) {
+        let cut = width;
+        while (cut > 1 && visibleWidth(rest.slice(0, cut)) > width) cut -= 1;
+        out.push(rest.slice(0, cut));
+        rest = rest.slice(cut);
+      }
+      line = rest;
+    }
+    if (line) out.push(line);
+  }
+  return out;
+}

package/extensions/overlay.ts

@@ -19,8 +19,10 @@ import {
   visibleWidth,
 } from "@earendil-works/pi-tui";
 import { ConfirmDialog, PickDialog, PromptDialog } from "./dialogs.ts";
-import { frameEdge, type OverlayTheme, padToWidth } from "./frame.ts";
+import { frameEdge, type OverlayTheme, padToWidth, wrapText } from "./frame.ts";
+import { homedir } from "node:os";
 import type { StackMap, StacksSummary } from "../src/core.ts";
+import { defaultSkillRoots } from "../src/store.ts";
 import {
   StacksOverlayModel,
   type MemberRow,
@@ -72,6 +74,24 @@ const CELL_PREFIX_WIDTH = CURSOR.length + 3 + 1;
 const projectStackNotice = (stack: string) =>
   `"${stack}" is defined in .pi/skill-stacks.json; edit it there`;
 
+/** The directories skills are discovered from, with $HOME shortened to `~`. */
+function skillRootsNotice() {
+  const home = homedir();
+  const shown = defaultSkillRoots().map(({ dir }) => (dir.startsWith(home) ? `~${dir.slice(home.length)}` : dir));
+  return `No skills discovered (looked in ${shown.join(" and ")})`;
+}
+
+// Paragraphs only — wrapText reflows each to the members pane's width.
+const EMPTY_INTRO = [
+  "No stacks yet",
+  "",
+  "A stack is a named group of skills you can switch on and off together. Skills that are off leave the system prompt, /skill: commands, and discovery.",
+  "",
+  "Press n (or enter) to create one. You'll pick its skills right after.",
+  "",
+  "Later, a adds skills to the selected stack and space switches it on or off.",
+].join("\n");
+
 /**
  * Wheel direction from a terminal mouse report: -1 up, +1 down, 0 not a wheel
  * event. Matches pi-tui's parseWheelEvent — in fullscreen mode pi captures the
@@ -141,9 +161,14 @@ export class StacksOverlay {
       matchesKey(data, Key.tab) ||
       data === "l"
     ) {
-      this.model.setFocus("members");
-      this.model.moveMember(0, this.memberRows());
-      this.tui.requestRender();
+      if (this.model.stackCount === 0) {
+        // first-run shortcut: enter on an empty list starts the create flow
+        this.openNewStackDialog();
+      } else {
+        this.model.setFocus("members");
+        this.model.moveMember(0, this.memberRows());
+        this.tui.requestRender();
+      }
     } else if (data === "n") {
       this.openNewStackDialog();
     } else if (data === "d") {
@@ -247,7 +272,15 @@ export class StacksOverlay {
 
       let members: string;
       if (!stack) {
-        members = row === 0 ? hint(" no stacks · n creates one", membersW) : blank(membersW);
+        const intro = wrapText(EMPTY_INTRO, Math.max(10, membersW - 1));
+        const text = intro[row];
+        if (text === undefined) {
+          members = blank(membersW);
+        } else if (row === 0) {
+          members = padToWidth(this.theme.fg("accent", this.theme.bold(` ${text}`)), membersW);
+        } else {
+          members = padToWidth(this.theme.fg("text", ` ${text}`), membersW);
+        }
       } else if (row === 0) {
         members = this.renderStackHeader(stack, membersW);
       } else if (row === 1) {
@@ -287,22 +320,27 @@ export class StacksOverlay {
           ["↑↓", "scroll"],
           ["←", "back"],
         ])
-      : this.model.focus === "stacks"
+      : this.model.stackCount === 0
         ? this.hintBar([
-            ["↑↓", "select"],
-            ["space", "on/off"],
-            ["→", "members"],
-            ["a", "add skills"],
-            ["n", "new stack"],
-            ["d", "delete"],
+            ["n/enter", "new stack"],
             ["esc", "close"],
           ])
-        : this.hintBar([
-            ["↑↓", "move"],
-            ["space", "remove"],
-            ["←/→", "back/view"],
-            ["a", "add skills"],
-          ]);
+        : this.model.focus === "stacks"
+          ? this.hintBar([
+              ["↑↓", "select"],
+              ["space", "on/off"],
+              ["→", "members"],
+              ["a", "add skills"],
+              ["n", "new stack"],
+              ["d", "delete"],
+              ["esc", "close"],
+            ])
+          : this.hintBar([
+              ["↑↓", "move"],
+              ["space", "remove"],
+              ["←/→", "back/view"],
+              ["a", "add skills"],
+            ]);
     lines.push(this.border(width, help, false));
     return lines;
   }
@@ -333,6 +371,7 @@ export class StacksOverlay {
 
   private openNewStackDialog() {
     void this.withDialog(async () => {
+      const wasEmpty = this.model.stackCount === 0;
       const name = (await this.callbacks.input("New stack name", "e.g. writing"))?.trim();
       if (!name) return;
       if (!this.model.createStack(name)) {
@@ -340,9 +379,30 @@ export class StacksOverlay {
         return;
       }
       this.apply();
+      if (wasEmpty) await this.pickSkillsForSelectedStack();
     });
   }
 
+  /** The add-skills picker for the selected stack, shared by `a` and the first-run create flow. */
+  private async pickSkillsForSelectedStack() {
+    const name = this.model.selectedStack;
+    if (!name) return;
+    if (this.model.isProjectStack(name)) {
+      this.callbacks.notify(projectStackNotice(name), "warning");
+      return;
+    }
+    const unstacked = this.model.unstackedSkills();
+    if (unstacked.length === 0) {
+      this.callbacks.notify(
+        this.model.discoveredCount === 0 ? skillRootsNotice() : "Every discovered skill is already in a stack",
+        "info",
+      );
+      return;
+    }
+    const picked = await this.callbacks.pick(`Add to ${name} · ${unstacked.length} unstacked`, unstacked);
+    if (picked && this.model.addSkills(picked) === "added") this.apply();
+  }
+
   private openDeleteDialog() {
     const name = this.model.selectedStack;
     if (!name) return;
@@ -362,21 +422,8 @@ export class StacksOverlay {
 
   /** `a`: pick from the skills no stack holds yet and add them to the selected stack. */
   private openAddDialog() {
-    const name = this.model.selectedStack;
-    if (!name) return;
-    if (this.model.isProjectStack(name)) {
-      this.callbacks.notify(projectStackNotice(name), "warning");
-      return;
-    }
-    const unstacked = this.model.unstackedSkills();
-    if (unstacked.length === 0) {
-      this.callbacks.notify("Every discovered skill is already in a stack", "info");
-      return;
-    }
-    void this.withDialog(async () => {
-      const picked = await this.callbacks.pick(`Add to ${name} · ${unstacked.length} unstacked`, unstacked);
-      if (picked && this.model.addSkills(picked) === "added") this.apply();
-    });
+    if (!this.model.selectedStack) return;
+    void this.withDialog(() => this.pickSkillsForSelectedStack());
   }
 
   private bodyRows() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-skill-stacks",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "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",

package/src/core.ts

@@ -36,6 +36,8 @@ export interface StacksSummary {
   offStacks: string[];
   totalCount: number;
   activeCount: number;
+  /** Discovered skills that no stack contains. */
+  unstackedCount: number;
   /** Per-stack status in definition order. */
   stacks: StackStatus[];
 }
@@ -59,6 +61,9 @@ export function missingSkillNames(stacks: StackMap, discovered: DiscoveredSkills
   return missing;
 }
 
+/** Every skill name any stack references, discovered or not. */
+export const stackedSkills = (stacks: StackMap) => new Set(Object.values(stacks).flat());
+
 /**
  * A skill is excluded iff it appears in at least one stack and no enabled
  * stack contains it. Skills in no stack are never excluded.
@@ -161,7 +166,7 @@ export function nextDisabledStacks(
   return sortNames(new Set([...unseen, ...visibleDisabled]));
 }
 
-/** Stack and active-skill counts. Only discovered skills are counted. */
+/** Stack, active-skill, and unstacked-skill counts. Only discovered skills are counted. */
 export function summarizeStacks(
   stacks: StackMap,
   disabledStacks: string[],
@@ -169,9 +174,12 @@ export function summarizeStacks(
 ): StacksSummary {
   const stackNames = Object.keys(stacks);
   const excluded = computeExcludedSkills(stacks, disabledStacks);
+  const stacked = stackedSkills(stacks);
   let activeCount = 0;
+  let unstackedCount = 0;
   for (const name of discovered.keys()) {
     if (!excluded.has(name)) activeCount += 1;
+    if (!stacked.has(name)) unstackedCount += 1;
   }
   const disabled = new Set(disabledStacks);
   return {
@@ -179,6 +187,7 @@ export function summarizeStacks(
     offStacks: disabledStacks.filter((name) => stackNames.includes(name)),
     totalCount: discovered.size,
     activeCount,
+    unstackedCount,
     stacks: Object.entries(stacks).map(([name, skills]) => ({
       name,
       size: skills.filter((skill) => discovered.has(skill)).length,

package/src/overlay-model.ts

@@ -8,7 +8,13 @@
 // to them would be shadowed by the project config on the next merge.
 
 import { renderMarkdown, type MarkdownStyler } from "./markdown.ts";
-import { computeExcludedSkills, sortNames, type DiscoveredSkills, type StackMap } from "./core.ts";
+import {
+  computeExcludedSkills,
+  sortNames,
+  stackedSkills,
+  type DiscoveredSkills,
+  type StackMap,
+} from "./core.ts";
 
 export type OverlayFocus = "stacks" | "members" | "viewer";
 
@@ -130,7 +136,7 @@ export class StacksOverlayModel {
 
   /** Discovered skills that no stack (enabled or not) contains, sorted. */
   unstackedSkills() {
-    const stacked = new Set(Object.values(this.stackMap).flat());
+    const stacked = stackedSkills(this.stackMap);
     return sortNames([...this.discovered.keys()].filter((skill) => !stacked.has(skill)));
   }