pi-skill-stacks 0.4.1

package/src/overlay-model.ts

@@ -0,0 +1,330 @@
+// Pure state machine behind the /stacks overlay: selection, scrolling, and
+// the mutation operations (toggle stack on/off, add/remove members,
+// create/delete stacks). No I/O and no TUI here — extensions/overlay.ts
+// renders it and persists each mutation through a callback.
+//
+// The model holds the MERGED stack map (global + project). Project-defined
+// stacks are visible and toggleable but their membership is read-only; edits
+// 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";
+
+export type OverlayFocus = "stacks" | "members" | "viewer";
+
+export interface StacksOverlayInit {
+  stacks: StackMap;
+  disabledStacks: string[];
+  discovered: DiscoveredSkills;
+  projectStackNames?: ReadonlySet<string>;
+  /** Skill name → full SKILL.md text (frontmatter included); powers the viewer pane. */
+  skillContents?: ReadonlyMap<string, string>;
+  /** How viewer text is styled; defaults to plain. */
+  styler?: MarkdownStyler;
+}
+
+export interface StackRow {
+  name: string;
+  enabled: boolean;
+  project: boolean;
+  /** Discovered members only. */
+  found: number;
+  total: number;
+}
+
+export interface MemberRow {
+  name: string;
+  /** In the stack definition but not on disk. */
+  missing: boolean;
+  /** False when the skill is currently excluded (no enabled stack has it). */
+  active: boolean;
+}
+
+export interface Window<T> {
+  start: number;
+  items: T[];
+}
+
+export type MembershipChange = "added" | "removed" | "blocked";
+export type DeleteResult = "deleted" | "blocked" | "none";
+
+const clamp = (value: number, min: number, max: number) => Math.max(min, Math.min(max, value));
+
+/** Scroll offset that keeps `index` inside a window of `rows` starting at `offset`. */
+function followIndex(offset: number, index: number, rows: number) {
+  const visible = Math.max(1, rows);
+  if (index < offset) return index;
+  if (index >= offset + visible) return index - visible + 1;
+  return offset;
+}
+
+export class StacksOverlayModel {
+  focus: OverlayFocus = "stacks";
+  stackIndex = 0;
+  private stackOffset = 0;
+  memberIndex = 0;
+  private memberOffset = 0;
+  private viewerOffset = 0;
+
+  private readonly discovered: DiscoveredSkills;
+  private readonly projectStackNames: ReadonlySet<string>;
+  private readonly skillContents: ReadonlyMap<string, string>;
+  private readonly styler: MarkdownStyler;
+  private stackMap: StackMap;
+  private names: string[];
+  private disabled: Set<string>;
+  private excluded: Set<string>;
+  private viewerCache: { width: number; skill: string; lines: string[] } | undefined;
+
+  constructor(init: StacksOverlayInit) {
+    this.discovered = init.discovered;
+    this.projectStackNames = init.projectStackNames ?? new Set();
+    this.skillContents = init.skillContents ?? new Map();
+    this.styler = init.styler ?? { fg: (_color, text) => text, bold: (text) => text };
+    this.stackMap = copyStacks(init.stacks);
+    this.names = sortNames(Object.keys(this.stackMap));
+    this.disabled = new Set(init.disabledStacks.filter((name) => this.names.includes(name)));
+    this.excluded = computeExcludedSkills(this.stackMap, [...this.disabled]);
+  }
+
+  // ---- state accessors ----
+
+  get stackCount() {
+    return this.names.length;
+  }
+
+  get selectedStack(): string | undefined {
+    return this.names[this.stackIndex];
+  }
+
+  /** Discovered skills that are not excluded right now. */
+  get activeSkillCount() {
+    let count = 0;
+    for (const name of this.discovered.keys()) if (!this.excluded.has(name)) count += 1;
+    return count;
+  }
+
+  get discoveredCount() {
+    return this.discovered.size;
+  }
+
+  stackList() {
+    return [...this.names];
+  }
+
+  isDisabled(name: string) {
+    return this.disabled.has(name);
+  }
+
+  isProjectStack(name: string) {
+    return this.projectStackNames.has(name);
+  }
+
+  membersOf(name: string) {
+    return sortNames(this.stackMap[name] ?? []);
+  }
+
+  isActiveSkill(name: string) {
+    return !this.excluded.has(name);
+  }
+
+  /** Discovered skills that no stack (enabled or not) contains, sorted. */
+  unstackedSkills() {
+    const stacked = new Set(Object.values(this.stackMap).flat());
+    return sortNames([...this.discovered.keys()].filter((skill) => !stacked.has(skill)));
+  }
+
+  /** Deep copy for persistence; disabled list sorted for stable config output. */
+  snapshot() {
+    return { stacks: copyStacks(this.stackMap), disabledStacks: sortNames(this.disabled) };
+  }
+
+  // ---- navigation ----
+
+  setFocus(focus: OverlayFocus) {
+    this.focus = focus;
+  }
+
+  moveStack(delta: number, rows: number) {
+    if (this.names.length === 0) return;
+    this.stackIndex = clamp(this.stackIndex + delta, 0, this.names.length - 1);
+    this.stackOffset = followIndex(this.stackOffset, this.stackIndex, rows);
+  }
+
+  moveMember(delta: number, rows: number) {
+    const total = this.selectedMembers.length;
+    if (total === 0) return;
+    this.memberIndex = clamp(this.memberIndex + delta, 0, total - 1);
+    this.memberOffset = followIndex(this.memberOffset, this.memberIndex, rows);
+  }
+
+  // ---- windows for rendering ----
+
+  stackWindow(rows: number): Window<StackRow> {
+    const visible = Math.max(1, rows);
+    const start = clamp(this.stackOffset, 0, Math.max(0, this.names.length - visible));
+    return {
+      start,
+      items: this.names.slice(start, start + visible).map((name) => this.stackRow(name)),
+    };
+  }
+
+  stackRow(name: string): StackRow {
+    const members = this.stackMap[name] ?? [];
+    return {
+      name,
+      enabled: !this.disabled.has(name),
+      project: this.projectStackNames.has(name),
+      found: members.filter((skill) => this.discovered.has(skill)).length,
+      total: members.length,
+    };
+  }
+
+  memberWindow(rows: number): Window<MemberRow> {
+    const visible = Math.max(1, rows);
+    const start = clamp(this.memberOffset, 0, Math.max(0, this.selectedMembers.length - visible));
+    return {
+      start,
+      items: this.selectedMembers.slice(start, start + visible).map((name) => ({
+        name,
+        missing: !this.discovered.has(name),
+        active: this.isActiveSkill(name),
+      })),
+    };
+  }
+
+  /** The member under the cursor, or undefined for an empty pane. */
+  get selectedMember(): string | undefined {
+    return this.selectedMembers[this.memberIndex];
+  }
+
+  /** True while the viewer pane is open (it is visible exactly when focused). */
+  get viewerOpen() {
+    return this.focus === "viewer";
+  }
+
+  /** Open the viewer on the selected member. False when nothing viewable is selected. */
+  openViewer(): boolean {
+    const skill = this.selectedMember;
+    if (!skill || !this.discovered.has(skill)) return false;
+    this.focus = "viewer";
+    this.viewerOffset = 0;
+    return true;
+  }
+
+  closeViewer() {
+    this.focus = "members";
+  }
+
+  /** The selected member's SKILL.md, rendered to styled lines at `width` columns (cached). */
+  viewerLines(width: number): string[] {
+    const w = Math.max(1, Math.floor(width));
+    const skill = this.selectedMember ?? "";
+    if (!this.viewerCache || this.viewerCache.width !== w || this.viewerCache.skill !== skill) {
+      this.viewerCache = {
+        width: w,
+        skill,
+        lines: renderMarkdown(this.skillContents.get(skill) ?? "", w, this.styler),
+      };
+    }
+    return this.viewerCache.lines;
+  }
+
+  moveViewer(delta: number, width: number, rows: number) {
+    const total = this.viewerLines(width).length;
+    const maxStart = Math.max(0, total - Math.max(1, rows));
+    this.viewerOffset = clamp(this.viewerOffset + delta, 0, maxStart);
+  }
+
+  viewerWindow(width: number, rows: number): Window<string> {
+    const visible = Math.max(1, rows);
+    const lines = this.viewerLines(width);
+    const start = clamp(this.viewerOffset, 0, Math.max(0, lines.length - visible));
+    return { start, items: lines.slice(start, start + visible) };
+  }
+
+  // ---- mutations (each leaves the model consistent; caller persists) ----
+
+  /** Flip the selected stack on/off. Always changes state. */
+  toggleStack() {
+    const name = this.selectedStack;
+    if (!name) return false;
+    if (this.disabled.has(name)) this.disabled.delete(name);
+    else this.disabled.add(name);
+    this.recomputeExcluded();
+    return true;
+  }
+
+  /** Remove the member under the cursor from the selected stack. Blocked for project-defined stacks. */
+  removeMember(): MembershipChange {
+    const stack = this.selectedStack;
+    if (!stack || this.projectStackNames.has(stack)) return "blocked";
+    const skill = this.selectedMembers[this.memberIndex];
+    if (!skill) return "blocked";
+    this.stackMap[stack] = (this.stackMap[stack] ?? []).filter((entry) => entry !== skill);
+    this.afterMembershipChange();
+    return "removed";
+  }
+
+  /** Add skills to the selected stack (duplicates ignored). Blocked for project stacks or an empty list. */
+  addSkills(names: readonly string[]): MembershipChange {
+    const stack = this.selectedStack;
+    if (!stack || this.projectStackNames.has(stack)) return "blocked";
+    const current = this.stackMap[stack] ?? [];
+    const fresh = [...new Set(names)].filter((name) => !current.includes(name));
+    if (fresh.length === 0) return "blocked";
+    this.stackMap[stack] = [...current, ...fresh];
+    this.afterMembershipChange();
+    return "added";
+  }
+
+  /** Create an empty stack and select it. False when the name is taken. */
+  createStack(name: string) {
+    const trimmed = name.trim();
+    if (!trimmed || trimmed in this.stackMap) return false;
+    this.stackMap[trimmed] = [];
+    this.names = sortNames(Object.keys(this.stackMap));
+    this.stackIndex = this.names.indexOf(trimmed);
+    this.stackOffset = followIndex(this.stackOffset, this.stackIndex, 1);
+    this.resetMemberCursor();
+    return true;
+  }
+
+  /** Remove the selected stack's definition (and any disabled entry). */
+  deleteSelectedStack(): DeleteResult {
+    const name = this.selectedStack;
+    if (!name) return "none";
+    if (this.projectStackNames.has(name)) return "blocked";
+    delete this.stackMap[name];
+    this.names = sortNames(Object.keys(this.stackMap));
+    this.disabled.delete(name);
+    this.stackIndex = clamp(this.stackIndex, 0, Math.max(0, this.names.length - 1));
+    this.resetMemberCursor();
+    this.recomputeExcluded();
+    return "deleted";
+  }
+
+  // ---- internals ----
+
+  private get selectedMembers() {
+    const stack = this.selectedStack;
+    return stack ? this.membersOf(stack) : [];
+  }
+
+  private recomputeExcluded() {
+    this.excluded = computeExcludedSkills(this.stackMap, [...this.disabled]);
+  }
+
+  private afterMembershipChange() {
+    this.recomputeExcluded();
+    this.memberIndex = clamp(this.memberIndex, 0, Math.max(0, this.selectedMembers.length - 1));
+  }
+
+  private resetMemberCursor() {
+    this.memberIndex = 0;
+    this.memberOffset = 0;
+  }
+}
+
+const copyStacks = (stacks: StackMap): StackMap =>
+  Object.fromEntries(Object.entries(stacks).map(([name, skills]) => [name, [...skills]]));

package/src/store.ts

@@ -0,0 +1,258 @@
+// File I/O for skill stacks: the extension's own config, skill discovery on
+// disk, and surgical edits to the settings.json `skills` array.
+//
+// Global config lives at <agentDir>/skill-stacks.json. A project may add or
+// override stack definitions in <cwd>/.pi/skill-stacks.json (stacks only;
+// on/off state and managed exclusions stay global).
+//
+// Malformed files throw a ConfigError rather than degrading to an empty
+// config: every load here sits in front of a write, and defaulting would let
+// one bad entry erase the user's stacks or settings.
+//
+// Editing settings.json directly is safe alongside pi: SettingsManager
+// persists with a read-modify-write that only touches fields modified through
+// its own setters, so an external `skills` change survives unless the user
+// also edits skills via `pi config` in the same session.
+
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join, relative, sep } from "node:path";
+import {
+  mergeStacks,
+  summarizeStacks,
+  type DiscoveredSkills,
+  type StackMap,
+} from "./core.ts";
+
+export interface StacksConfig {
+  stacks: StackMap;
+  disabledStacks: string[];
+  managedExclusions: string[];
+}
+
+/** A skill root plus the baseDir pi matches exclusion patterns against (its parent). */
+export interface SkillRoot {
+  dir: string;
+  baseDir: string;
+}
+
+export class ConfigError extends Error {
+  constructor(path: string, detail: string) {
+    super(`${path}: ${detail}`);
+    this.name = "ConfigError";
+  }
+}
+
+/** Same lookup as pi's getAgentDir(): PI_CODING_AGENT_DIR override, else ~/.pi/agent. */
+export function agentDir() {
+  const override = process.env.PI_CODING_AGENT_DIR;
+  if (override) return override.startsWith("~") ? join(homedir(), override.slice(1)) : override;
+  return join(homedir(), ".pi", "agent");
+}
+
+export const globalConfigPath = () => join(agentDir(), "skill-stacks.json");
+export const globalSettingsPath = () => join(agentDir(), "settings.json");
+export const projectConfigPath = (cwd: string) => join(cwd, ".pi", "skill-stacks.json");
+
+/** The skill roots this extension manages, with the baseDir patterns are relative to. */
+export function defaultSkillRoots(): SkillRoot[] {
+  const agents = join(homedir(), ".agents");
+  return [
+    { dir: join(agents, "skills"), baseDir: agents },
+    { dir: join(agentDir(), "skills"), baseDir: agentDir() },
+  ];
+}
+
+const isStringArray = (value: unknown): value is string[] =>
+  Array.isArray(value) && value.every((item) => typeof item === "string");
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+function parseStackMap(path: string, value: unknown): StackMap {
+  if (value === undefined) return {};
+  if (!isRecord(value)) throw new ConfigError(path, "`stacks` must be an object of name → skill names");
+  const stacks: StackMap = {};
+  for (const [name, skills] of Object.entries(value)) {
+    if (!isStringArray(skills)) {
+      throw new ConfigError(path, `stack "${name}" must be an array of skill names`);
+    }
+    stacks[name] = skills;
+  }
+  return stacks;
+}
+
+function parseNameList(path: string, key: string, value: unknown) {
+  if (value === undefined) return [];
+  if (!isStringArray(value)) throw new ConfigError(path, `\`${key}\` must be an array of strings`);
+  return value;
+}
+
+/** Parsed JSON, undefined when the file is absent. Throws ConfigError on unreadable JSON. */
+function readJson(path: string): unknown {
+  if (!existsSync(path)) return undefined;
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch (error) {
+    throw new ConfigError(path, `not valid JSON (${error instanceof Error ? error.message : error})`);
+  }
+}
+
+function readJsonObject(path: string) {
+  const raw = readJson(path);
+  if (raw === undefined) return undefined;
+  if (!isRecord(raw)) throw new ConfigError(path, "top level must be a JSON object");
+  return raw;
+}
+
+export function loadStacksConfig(path = globalConfigPath()): StacksConfig {
+  const record = readJsonObject(path);
+  if (!record) return { stacks: {}, disabledStacks: [], managedExclusions: [] };
+  // disabledStacks/managedExclusions are kept even when stacks is empty: the
+  // user may run only project-defined stacks, and their on/off state lives here.
+  return {
+    stacks: parseStackMap(path, record.stacks),
+    disabledStacks: parseNameList(path, "disabledStacks", record.disabledStacks),
+    managedExclusions: parseNameList(path, "managedExclusions", record.managedExclusions),
+  };
+}
+
+export function saveStacksConfig(path: string, config: StacksConfig) {
+  writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`, "utf-8");
+}
+
+/** Stack definitions from <cwd>/.pi/skill-stacks.json, or undefined when absent or empty. */
+export function loadProjectStacks(cwd: string) {
+  const path = projectConfigPath(cwd);
+  const record = readJsonObject(path);
+  if (!record) return undefined;
+  const stacks = parseStackMap(path, record.stacks);
+  return Object.keys(stacks).length > 0 ? stacks : undefined;
+}
+
+const toPosix = (path: string) => (sep === "/" ? path : path.split(sep).join("/"));
+
+/** `name:` from YAML frontmatter, if present; pi falls back to the directory name. */
+function frontmatterName(skillFile: string) {
+  try {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(readFileSync(skillFile, "utf-8"));
+    const nameLine = match?.[1].split(/\r?\n/).find((line) => /^name\s*:/.test(line));
+    const name = nameLine?.replace(/^name\s*:\s*/, "").trim().replace(/^["']|["']$/g, "");
+    return name || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+// Mirrors pi's loadSkillsFromDir: a directory with SKILL.md is a skill and is
+// not recursed into; otherwise recurse, skipping dot-dirs and node_modules and
+// following symlinks. Broken symlinks are skipped.
+function collectSkills(dir: string, baseDir: string, into: Map<string, string>) {
+  const entries = readDirEntries(dir);
+  const skillFile = join(dir, "SKILL.md");
+  if (entries.some((entry) => entry.name === "SKILL.md") && isFile(skillFile)) {
+    const name = frontmatterName(skillFile) ?? basename(dir);
+    if (!into.has(name)) into.set(name, toPosix(relative(baseDir, skillFile)));
+    return;
+  }
+  for (const entry of entries) {
+    if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
+    const full = join(dir, entry.name);
+    if (entry.isDirectory() || (entry.isSymbolicLink() && isDirectory(full))) {
+      collectSkills(full, baseDir, into);
+    }
+  }
+}
+
+function readDirEntries(dir: string) {
+  try {
+    return readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+}
+
+function isFile(path: string) {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function isDirectory(path: string) {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Every skill pi would discover under the given roots, as name → baseDir-relative
+ * SKILL.md path (the form exclusion patterns take). First root wins on a name
+ * clash, matching pi's "keep the first one found" rule. Missing roots are skipped.
+ */
+export function discoverSkills(roots: SkillRoot[] = defaultSkillRoots()): DiscoveredSkills {
+  const skills = new Map<string, string>();
+  for (const root of roots) {
+    if (existsSync(root.dir)) collectSkills(root.dir, root.baseDir, skills);
+  }
+  return skills;
+}
+
+/**
+ * Full SKILL.md text per discovered skill, for the overlay's viewer pane.
+ * Roots are tried in discovery order, so a name clash resolves the same way
+ * discovery did. Unreadable skills map to "".
+ */
+export function readSkillContents(
+  discovered: DiscoveredSkills,
+  roots: SkillRoot[] = defaultSkillRoots(),
+): Map<string, string> {
+  const contents = new Map<string, string>();
+  const done = new Set<string>();
+  for (const root of roots) {
+    for (const [name, relativePath] of discovered) {
+      if (done.has(name)) continue;
+      const full = join(root.baseDir, relativePath);
+      if (isFile(full)) {
+        contents.set(name, readFileSync(full, "utf-8"));
+        done.add(name);
+      }
+    }
+  }
+  return contents;
+}
+
+export function readSettingsSkills(path = globalSettingsPath()) {
+  const record = readJsonObject(path);
+  const skills = record?.skills;
+  if (skills !== undefined && !isStringArray(skills)) {
+    throw new ConfigError(path, "`skills` must be an array of strings");
+  }
+  return skills ?? [];
+}
+
+/**
+ * Replace the `skills` array in settings.json, leaving every other key as-is.
+ * Written without a trailing newline to match pi's own SettingsManager output,
+ * so a subsequent pi save doesn't produce a spurious diff.
+ */
+export function updateSettingsSkills(path: string, skills: string[]) {
+  const settings = readJsonObject(path) ?? {};
+  settings.skills = skills;
+  writeFileSync(path, JSON.stringify(settings, null, 2), "utf-8");
+}
+
+/**
+ * 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.
+ */
+export function loadStacksSummary(cwd: string) {
+  const global = loadStacksConfig();
+  const stacks = mergeStacks(global.stacks, loadProjectStacks(cwd));
+  if (Object.keys(stacks).length === 0) return undefined;
+  return summarizeStacks(stacks, global.disabledStacks, discoverSkills());
+}