pi-skill-stacks 0.4.1

package/src/core.ts

@@ -0,0 +1,188 @@
+// Pure logic for skill stacks: merging stack definitions, deciding which
+// skills get excluded, and diffing the settings.json `skills` array without
+// touching entries the user wrote by hand.
+//
+// Mechanism (pi core, dist/core/package-manager.js `isEnabledByOverrides`):
+// entries in the settings `skills` array that start with `!` exclude
+// auto-discovered skills. Patterns are matched relative to the discovery
+// baseDir, so `!skills/<dir>/SKILL.md` excludes `~/.agents/skills/<dir>/`
+// (baseDir `~/.agents`) and `~/.pi/agent/skills/<dir>/` (baseDir
+// `~/.pi/agent`) alike. Nested skills get their full relative path.
+
+export type StackMap = Record<string, string[]>;
+
+/**
+ * Skill name → SKILL.md path relative to the discovery baseDir, e.g.
+ * `skills/firecrawl-map/SKILL.md` or `skills/group/nested/SKILL.md`.
+ */
+export type DiscoveredSkills = ReadonlyMap<string, string>;
+
+export interface SkillsSettingPlan {
+  /** The new value for the settings.json `skills` array. */
+  skills: string[];
+  /** The exclusion patterns this extension now owns (subset of `skills`). */
+  managed: string[];
+}
+
+export interface StackStatus {
+  name: string;
+  /** Discovered members only; names that resolve to no skill dir are not counted. */
+  size: number;
+  enabled: boolean;
+}
+
+export interface StacksSummary {
+  stackCount: number;
+  offStacks: string[];
+  totalCount: number;
+  activeCount: number;
+  /** Per-stack status in definition order, for the header section body. */
+  stacks: StackStatus[];
+}
+
+export const sortNames = (names: Iterable<string>) =>
+  [...names].sort((a, b) => a.localeCompare(b));
+
+/** Project stacks add to the global set; a same-named project stack replaces the global one. */
+export const mergeStacks = (global: StackMap, project: StackMap | undefined): StackMap => ({
+  ...global,
+  ...(project ?? {}),
+});
+
+/** Stack members that don't resolve to a discovered skill, keyed by stack. Empty stacks are omitted. */
+export function missingSkillNames(stacks: StackMap, discovered: DiscoveredSkills) {
+  const missing: Record<string, string[]> = {};
+  for (const [stack, skills] of Object.entries(stacks)) {
+    const absent = skills.filter((name) => !discovered.has(name));
+    if (absent.length > 0) missing[stack] = absent;
+  }
+  return missing;
+}
+
+/**
+ * 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.
+ */
+export function computeExcludedSkills(stacks: StackMap, disabledStacks: string[]) {
+  const disabled = new Set(disabledStacks);
+  const keptByEnabledStack = new Set<string>();
+  const inSomeStack = new Set<string>();
+  for (const [stack, skills] of Object.entries(stacks)) {
+    for (const name of skills) {
+      inSomeStack.add(name);
+      if (!disabled.has(stack)) keptByEnabledStack.add(name);
+    }
+  }
+  const excluded = new Set<string>();
+  for (const name of inSomeStack) {
+    if (!keptByEnabledStack.has(name)) excluded.add(name);
+  }
+  return excluded;
+}
+
+/** `!skills/<...>/SKILL.md` for a baseDir-relative skill path. */
+export const exclusionPatternFor = (relativeSkillPath: string) => `!${relativeSkillPath}`;
+
+/** Exclusion patterns for the excluded skills we can resolve on disk, sorted for stable output. */
+export function desiredExclusions(
+  stacks: StackMap,
+  disabledStacks: string[],
+  discovered: DiscoveredSkills,
+) {
+  const patterns: string[] = [];
+  for (const name of computeExcludedSkills(stacks, disabledStacks)) {
+    const path = discovered.get(name);
+    if (path) patterns.push(exclusionPatternFor(path));
+  }
+  return patterns.sort((a, b) => a.localeCompare(b));
+}
+
+/**
+ * Split previously managed exclusions into the ones this persist may rewrite
+ * and the ones it must leave alone. An exclusion is out of scope when its
+ * skill is on disk but in none of the stacks visible here: it belongs to a
+ * stack we can't see (a project stack from another cwd), and "skills in no
+ * stack are never touched" applies. Patterns for skills that no longer exist
+ * stay in scope so they get cleaned up.
+ */
+export function scopeManagedExclusions(
+  managed: string[],
+  stacks: StackMap,
+  discovered: DiscoveredSkills,
+) {
+  const visibleSkills = new Set(Object.values(stacks).flat());
+  const nameByPattern = new Map<string, string>();
+  for (const [name, path] of discovered) nameByPattern.set(exclusionPatternFor(path), name);
+  const inScope: string[] = [];
+  const retained: string[] = [];
+  for (const pattern of managed) {
+    const name = nameByPattern.get(pattern);
+    if (name !== undefined && !visibleSkills.has(name)) retained.push(pattern);
+    else inScope.push(pattern);
+  }
+  return { inScope, retained };
+}
+
+/**
+ * Diff the settings `skills` array: drop the exclusions we wrote previously,
+ * append the desired ones, and never touch or claim user-written entries.
+ */
+export function planSkillsSetting(
+  currentSkills: string[],
+  managedExclusions: string[],
+  desired: string[],
+): SkillsSettingPlan {
+  const previouslyManaged = new Set(managedExclusions);
+  const kept = currentSkills.filter((entry) => !previouslyManaged.has(entry));
+  const keptSet = new Set(kept);
+  const skills = [...kept];
+  const managed: string[] = [];
+  for (const pattern of desired) {
+    if (keptSet.has(pattern)) continue; // user wrote it by hand; not ours
+    skills.push(pattern);
+    managed.push(pattern);
+  }
+  return { skills, managed };
+}
+
+/**
+ * The global `disabledStacks` list after a persist. Entries for stacks that
+ * were visible here are replaced by `visibleDisabled`; entries for stacks we
+ * can't see (project stacks from another cwd) are preserved so their on/off
+ * state survives toggling from elsewhere.
+ */
+export function nextDisabledStacks(
+  globalDisabled: string[],
+  visibleStackNames: Iterable<string>,
+  visibleDisabled: string[],
+) {
+  const visible = new Set(visibleStackNames);
+  const unseen = globalDisabled.filter((name) => !visible.has(name));
+  return sortNames(new Set([...unseen, ...visibleDisabled]));
+}
+
+/** Counts for the compact `[Skills]` header line. Only discovered skills are counted. */
+export function summarizeStacks(
+  stacks: StackMap,
+  disabledStacks: string[],
+  discovered: DiscoveredSkills,
+): StacksSummary {
+  const stackNames = Object.keys(stacks);
+  const excluded = computeExcludedSkills(stacks, disabledStacks);
+  let activeCount = 0;
+  for (const name of discovered.keys()) {
+    if (!excluded.has(name)) activeCount += 1;
+  }
+  const disabled = new Set(disabledStacks);
+  return {
+    stackCount: stackNames.length,
+    offStacks: disabledStacks.filter((name) => stackNames.includes(name)),
+    totalCount: discovered.size,
+    activeCount,
+    stacks: Object.entries(stacks).map(([name, skills]) => ({
+      name,
+      size: skills.filter((skill) => discovered.has(skill)).length,
+      enabled: !disabled.has(name),
+    })),
+  };
+}

package/src/markdown.ts

@@ -0,0 +1,229 @@
+// Minimal markdown → styled-plain-text renderer for the overlay's skill
+// viewer. Covers the subset skill files actually use — ATX headings, lists,
+// fenced code, blockquotes, thematic breaks, frontmatter, and inline
+// `code` / **bold** / [links] — and falls through to plain text for anything
+// else. Output lines are ANSI-styled and wrapped ANSI-aware, so callers can
+// pad/truncate them with the usual pi-tui helpers.
+
+import type { ThemeColor } from "@earendil-works/pi-coding-agent";
+import { visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+
+/** The slice of pi's Theme the renderer needs (OverlayTheme satisfies this). */
+export interface MarkdownStyler {
+  fg(color: ThemeColor, text: string): string;
+  bold(text: string): string;
+}
+
+const HEADING = /^(#{1,6})\s+(.*)$/;
+const LIST = /^(\s*)(?:([-*+])|(\d+[.)]))\s+(.*)$/;
+const QUOTE = /^>\s?(.*)$/;
+const HR = /^\s*(?:-{3,}|\*{3,}|_{3,})\s*$/;
+const FENCE = /^\s*(```|~~~)/;
+const INLINE = /(`[^`\n]+`)|(\*\*[^*\n]+\*\*)|(\[[^\]\n]*\]\([^)\n]*\))/g;
+/** A line that starts a table row (GFM). Escaped `\|` is not supported. */
+const TABLE_ROW = /^\s*\|/;
+
+export function renderMarkdown(text: string, width: number, styler: MarkdownStyler): string[] {
+  if (text === "") return [];
+  const w = Math.max(1, Math.floor(width));
+  const lines: string[] = [];
+  const source = text.replace(/\r\n?/g, "\n").split("\n");
+
+  let start = 0;
+  if (source[0]?.trimEnd() === "---") {
+    let end = 1;
+    while (end < source.length && source[end]!.trimEnd() !== "---") end += 1;
+    if (end < source.length) {
+      for (let k = 0; k <= end; k += 1) pushDim(lines, source[k]!, w, styler);
+      start = end + 1;
+    }
+  }
+
+  let inFence = false;
+  for (let i = start; i < source.length; i += 1) {
+    const raw = source[i]!;
+    if (inFence) {
+      if (FENCE.test(raw)) inFence = false;
+      else pushDim(lines, raw, w, styler);
+      continue;
+    }
+    if (FENCE.test(raw)) {
+      inFence = true;
+      continue;
+    }
+    if (raw.trim() === "") {
+      pushBlank(lines);
+      continue;
+    }
+    const heading = HEADING.exec(raw);
+    if (heading) {
+      pushBlank(lines);
+      pushWrapped(lines, styler.fg("accent", styler.bold(heading[2]!)), w);
+      pushBlank(lines);
+      continue;
+    }
+    if (TABLE_ROW.test(raw) && isDivider(source[i + 1] ?? "")) {
+      let end = i + 2;
+      while (end < source.length && TABLE_ROW.test(source[end]!)) end += 1;
+      renderTable(
+        lines,
+        parseCells(raw),
+        source.slice(i + 2, end).map(parseCells),
+        w,
+        styler,
+      );
+      i = end - 1;
+      continue;
+    }
+    if (HR.test(raw)) {
+      pushBlank(lines);
+      lines.push(styler.fg("dim", "─".repeat(w)));
+      continue;
+    }
+    const list = LIST.exec(raw);
+    if (list) {
+      const indent = list[1] ?? "";
+      const marker = list[2] ? "• " : `${list[3]} `;
+      pushWrapped(lines, `${indent}${marker}${inline(list[4]!, styler)}`, w, indent.length + marker.length);
+      continue;
+    }
+    const quote = QUOTE.exec(raw);
+    if (quote) {
+      pushWrapped(lines, styler.fg("muted", `> ${quote[1]}`), w, 2);
+      continue;
+    }
+    pushWrapped(lines, inline(raw, styler), w);
+  }
+  while (lines.length > 0 && lines.at(-1) === "") lines.pop();
+  return lines;
+}
+
+/** `` `code` `` → accent, `**bold**` → bold, `[text](url)` → accent text without the url. */
+function inline(text: string, styler: MarkdownStyler): string {
+  let out = "";
+  let last = 0;
+  for (const match of text.matchAll(INLINE)) {
+    out += text.slice(last, match.index);
+    if (match[1]) out += styler.fg("accent", match[1].slice(1, -1));
+    else if (match[2]) out += styler.bold(match[2]!.slice(2, -2));
+    else {
+      const label = /^\[([^\]]*)\]/.exec(match[0])?.[1] ?? "";
+      if (label) out += styler.fg("accent", label);
+    }
+    last = match.index + match[0].length;
+  }
+  return out + text.slice(last);
+}
+
+function pushBlank(lines: string[]) {
+  if (lines.length > 0 && lines.at(-1) !== "") lines.push("");
+}
+
+/** Wrap `text`, indenting continuation lines by `hangIndent` columns. */
+function pushWrapped(lines: string[], text: string, width: number, hangIndent = 0) {
+  const parts = wrapTextWithAnsi(text, Math.max(1, width - hangIndent));
+  lines.push(parts[0] ?? "");
+  for (const part of parts.slice(1)) lines.push(" ".repeat(hangIndent) + part);
+}
+
+/** Style each already-wrapped part so styling survives across continuation lines. */
+function pushDim(lines: string[], text: string, width: number, styler: MarkdownStyler) {
+  for (const part of wrapTextWithAnsi(text, width)) lines.push(styler.fg("dim", part));
+}
+
+// ---- tables ----
+
+/** GFM delimiter row: every `|`-separated cell is just dashes with optional colons. */
+const isDivider = (line: string) => {
+  const cells = line.trim().replace(/^\|/, "").replace(/\|$/, "").split("|");
+  return cells.length > 0 && cells.every((cell) => /^\s*:?-+:?\s*$/.test(cell));
+};
+
+/** Split a table row into trimmed cells, dropping the edge pipes. */
+const parseCells = (line: string) => {
+  const trimmed = line.trim().replace(/^\|/, "").replace(/\|$/, "");
+  return trimmed.split("|").map((cell) => cell.trim());
+};
+
+/** Render a table as aligned columns: bold header, dim rule, cells wrap in-column. */
+function renderTable(
+  lines: string[],
+  header: string[],
+  body: string[][],
+  width: number,
+  styler: MarkdownStyler,
+) {
+  const cols = Math.max(header.length, ...body.map((row) => row.length), 1);
+  const cell = (row: string[], c: number) => row[c] ?? "";
+  const widths: number[] = [];
+  for (let c = 0; c < cols; c += 1) {
+    widths.push(Math.max(3, visibleWidth(cell(header, c)), ...body.map((row) => visibleWidth(cell(row, c)))));
+  }
+  const gap = " │ ".length * (cols - 1);
+  const avail = Math.max(0, width - gap);
+  const floors: number[] = [];
+  for (let c = 0; c < cols; c += 1) {
+    // a column is never squeezed below its longest word (words would break mid-word)
+    floors.push(Math.min(12, Math.max(3, longestWord([cell(header, c), ...body.map((row) => cell(row, c))]))));
+  }
+  const final = fitColumns(widths, floors, avail);
+
+  const row = (cells: string[], styled: boolean) => {
+    const wrapped = cells.map((text, c) =>
+      wrapTextWithAnsi(styled ? styler.bold(inline(text, styler)) : inline(text, styler), final[c]!),
+    );
+    const height = Math.max(...wrapped.map((parts) => parts.length), 1);
+    for (let line = 0; line < height; line += 1) {
+      const parts = wrapped.map((column, c) => {
+        const text = column[line] ?? "";
+        return text + " ".repeat(Math.max(0, final[c]! - visibleWidth(text)));
+      });
+      lines.push(parts.join(" │ ").trimEnd());
+    }
+  };
+
+  pushBlank(lines);
+  row(header, true);
+  lines.push(styler.fg("dim", final.map((w) => "─".repeat(w)).join("─┼─")));
+  for (const entry of body) row(entry, false);
+  pushBlank(lines);
+}
+
+/** Width of the longest word across a column's cells. */
+const longestWord = (texts: string[]) =>
+  Math.max(...texts.flatMap((text) => text.split(/\s+/).map((word) => word.length)), 1);
+
+/**
+ * Fit column widths into `avail`: every column keeps its longest word intact,
+ * leftover space is shared out in proportion to how much each column wanted.
+ */
+function fitColumns(natural: number[], floors: number[], avail: number): number[] {
+  const total = natural.reduce((sum, w) => sum + w, 0);
+  if (total <= avail) return natural;
+  const floorTotal = floors.reduce((sum, w) => sum + w, 0);
+  if (floorTotal >= avail) {
+    // nothing to distribute; squeeze the floors so lines still fit (words will break)
+    const shrunk = [...floors];
+    let sum = floorTotal;
+    while (sum > avail && shrunk.some((w) => w > 1)) {
+      const widest = Math.max(...shrunk);
+      shrunk[shrunk.indexOf(widest)] = widest - 1;
+      sum -= 1;
+    }
+    return shrunk;
+  }
+  const spare = avail - floorTotal;
+  const demand = natural.map((w, i) => w - floors[i]!);
+  const demandTotal = demand.reduce((sum, d) => sum + d, 0);
+  const widths = natural.map((_, i) => floors[i]! + Math.floor((demand[i]! * spare) / demandTotal));
+  let sum = widths.reduce((sum, w) => sum + w, 0);
+  const order = natural.map((_, i) => i).sort((a, b) => natural[b]! - natural[a]!);
+  for (let i = 0; sum < avail; i += 1) {
+    const j = order[i % widths.length]!;
+    if (widths[j]! < natural[j]!) {
+      widths[j]! += 1;
+      sum += 1;
+    }
+  }
+  return widths;
+}