@mrclrchtr/supi-skills 4.7.0

package/node_modules/@mrclrchtr/supi-core/src/model-selection.ts

@@ -0,0 +1,134 @@
+/**
+ * Shared model-selection helpers for SuPi extensions.
+ *
+ * Provides scoped-model listing using PI's `enabledModels` configuration,
+ * matching the same semantics as the `@mrclrchtr/supi-review` model picker.
+ *
+ * @module
+ */
+
+import type { Model } from "@earendil-works/pi-ai/compat";
+import { type ExtensionContext, SettingsManager } from "@earendil-works/pi-coding-agent";
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+/** A selectable model entry with display metadata. */
+export interface ModelSelection {
+  /** Canonical `provider/model-id` string. */
+  canonicalId: string;
+  /** Provider name, e.g. `"anthropic"`. */
+  provider: string;
+  /** Model id, e.g. `"claude-sonnet-4-5"`. */
+  id: string;
+  // biome-ignore lint/suspicious/noExplicitAny: Model<any> is pi's canonical type
+  model: Model<any>;
+  /** Human-readable label (model name or canonicalId). */
+  label: string;
+  /** Optional description (canonicalId when different from label). */
+  description?: string;
+  /** Whether this model is the current session model. */
+  isCurrent: boolean;
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+/** Build the canonical `provider/model-id` string. */
+export function toCanonicalModelId(
+  model: Pick<NonNullable<ExtensionContext["model"]>, "provider" | "id">,
+): string {
+  return `${model.provider}/${model.id}`;
+}
+
+/**
+ * List selectable models from PI's scoped model configuration.
+ *
+ * Only models that match the configured `enabledModels` patterns are offered.
+ * The current session model is included only when it is inside that scoped set.
+ * Returns an empty array when no scoped model patterns are configured.
+ */
+export function getSelectableModels(
+  ctx: Pick<ExtensionContext, "cwd" | "modelRegistry" | "model">,
+  enabledModelPatterns = SettingsManager.create(ctx.cwd).getEnabledModels(),
+): ModelSelection[] {
+  if (!enabledModelPatterns || enabledModelPatterns.length === 0) {
+    return [];
+  }
+
+  const byCanonicalId = new Map<string, ModelSelection>();
+  const availableModels = filterByEnabledModels(
+    enabledModelPatterns,
+    ctx.modelRegistry.getAvailable(),
+  );
+
+  const addModel = (
+    // biome-ignore lint/suspicious/noExplicitAny: Model<any> is pi's canonical type
+    model: Model<any>,
+    isCurrent: boolean,
+  ) => {
+    const canonicalId = toCanonicalModelId(model);
+    const existing = byCanonicalId.get(canonicalId);
+    if (existing) {
+      if (isCurrent) existing.isCurrent = true;
+      return;
+    }
+
+    byCanonicalId.set(canonicalId, {
+      canonicalId,
+      provider: model.provider,
+      id: model.id,
+      model,
+      label: model.name ?? canonicalId,
+      description: canonicalId,
+      isCurrent,
+    });
+  };
+
+  if (ctx.model && matchModelPatterns(ctx.model, enabledModelPatterns)) {
+    addModel(ctx.model, true);
+  }
+
+  for (const model of availableModels) {
+    addModel(
+      model,
+      ctx.model ? toCanonicalModelId(model) === toCanonicalModelId(ctx.model) : false,
+    );
+  }
+
+  return Array.from(byCanonicalId.values()).sort((a, b) => {
+    if (a.isCurrent !== b.isCurrent) return a.isCurrent ? -1 : 1;
+    return a.canonicalId.localeCompare(b.canonicalId);
+  });
+}
+
+// ── Private helpers ────────────────────────────────────────────────────────
+
+function filterByEnabledModels<T extends { provider: string; id: string }>(
+  patterns: string[],
+  models: T[],
+): T[] {
+  return models.filter((model) => matchModelPatterns(model, patterns));
+}
+
+function matchModelPatterns(model: { provider: string; id: string }, patterns: string[]): boolean {
+  return patterns.some((pattern) => matchModelPattern(model, pattern));
+}
+
+function matchModelPattern(model: { provider: string; id: string }, pattern: string): boolean {
+  const canonicalId = `${model.provider}/${model.id}`;
+  if (pattern.includes("/")) {
+    return simpleGlobMatch(canonicalId, pattern);
+  }
+  return simpleGlobMatch(model.id, pattern) || simpleGlobMatch(canonicalId, pattern);
+}
+
+function simpleGlobMatch(text: string, pattern: string): boolean {
+  if (!pattern.includes("*") && !pattern.includes("?")) {
+    return text.toLowerCase() === pattern.toLowerCase();
+  }
+
+  const regex = pattern
+    .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+    .replace(/\*/g, ".*")
+    .replace(/\?/g, ".");
+  return new RegExp(`^${regex}$`, "i").test(text);
+}

package/node_modules/@mrclrchtr/supi-core/src/path-utils.ts

@@ -0,0 +1,44 @@
+import * as path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+/** Strip pi's optional leading `@` file-path prefix from a tool input. */
+export function stripToolPathPrefix(target: string): string {
+  return target.startsWith("@") ? target.slice(1) : target;
+}
+
+/**
+ * Resolve a tool-style file path from a session cwd.
+ *
+ * Built-in pi file tools accept a leading `@` prefix in path arguments, so
+ * shared SuPi path helpers normalize that prefix before resolving relative
+ * paths.
+ */
+export function resolveToolPath(cwd: string, target: string): string {
+  return path.resolve(cwd, stripToolPathPrefix(target));
+}
+
+/**
+ * Convert a file path to a file:// URI.
+ *
+ * Uses Node's `pathToFileURL` to produce a standards-compliant URI with
+ * proper percent-encoding of spaces, hashes, and other special characters.
+ */
+export function fileToUri(filePath: string): string {
+  return pathToFileURL(filePath).href;
+}
+
+/**
+ * Convert a file:// URI to a file path.
+ *
+ * Uses Node's `fileURLToPath` for standards-compliant decoding. Non-file
+ * URIs are passed through unchanged so consumers (such as LSP diagnostic
+ * handling) remain compatible with non-file URI schemes.
+ */
+export function uriToFile(uri: string): string {
+  if (!uri.startsWith("file://")) return uri;
+  try {
+    return fileURLToPath(uri);
+  } catch {
+    return uri;
+  }
+}

package/node_modules/@mrclrchtr/supi-core/src/path.ts

@@ -0,0 +1,2 @@
+// supi-core path domain — file and URI path utilities.
+export { fileToUri, resolveToolPath, stripToolPathPrefix, uriToFile } from "./path-utils.ts";

package/node_modules/@mrclrchtr/supi-core/src/project-roots.ts

@@ -0,0 +1,170 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+const IGNORED_DIRECTORIES = new Set(["node_modules", ".git", ".pnpm"]);
+
+/**
+ * Walk a project directory tree, calling `onDirectory` for each directory.
+ * Skips `node_modules`, `.git`, and `.pnpm`.
+ * Stops at depth 0.
+ */
+export function walkProject(
+  directory: string,
+  depth: number,
+  onDirectory: (directory: string, entryNames: Set<string>) => void,
+): void {
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(directory, { withFileTypes: true });
+  } catch {
+    return;
+  }
+
+  const entryNames = new Set(entries.map((entry) => entry.name));
+  onDirectory(directory, entryNames);
+
+  if (depth <= 0) return;
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (IGNORED_DIRECTORIES.has(entry.name)) continue;
+    walkProject(path.join(directory, entry.name), depth - 1, onDirectory);
+  }
+}
+
+/**
+ * Search upward from `startDir` for any of the `markers` files/dirs.
+ * Returns the directory containing the first found marker, or `fallback`.
+ */
+export function findProjectRoot(startDir: string, markers: string[], fallback: string): string {
+  let dir = path.resolve(startDir);
+  const root = path.parse(dir).root;
+
+  while (dir !== root) {
+    for (const marker of markers) {
+      if (fs.existsSync(path.join(dir, marker))) {
+        return dir;
+      }
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  return fallback;
+}
+
+/**
+ * Deduplicate overlapping roots, keeping only the topmost (shortest path) roots.
+ */
+export function dedupeTopmostRoots(roots: string[]): string[] {
+  const accepted: string[] = [];
+
+  for (const root of [...new Set(roots.map((entry) => path.resolve(entry)))].sort(byPathDepth)) {
+    const isChild = accepted.some((parent) => root !== parent && isWithin(parent, root));
+    if (!isChild) {
+      accepted.push(root);
+    }
+  }
+
+  return accepted;
+}
+
+/**
+ * Minimal shape accepted by `buildKnownRootsMap`.
+ * Structurally compatible with `DetectedProjectServer` and similar
+ * `{ name, root }` records — callers may pass a wider type safely.
+ */
+export type KnownRootEntry = { name: string; root: string };
+
+/**
+ * Build a map of language/server name to sorted, deduplicated root paths.
+ *
+ * Accepts an array of detected project entries (e.g. from LSP project discovery)
+ * and groups them by name with roots sorted by specificity.
+ */
+export function buildKnownRootsMap(detected: KnownRootEntry[]): Map<string, string[]> {
+  const next = new Map<string, string[]>();
+
+  for (const entry of detected) {
+    const roots = next.get(entry.name) ?? [];
+    if (!roots.includes(entry.root)) roots.push(entry.root);
+    next.set(entry.name, sortRootsBySpecificity(roots));
+  }
+
+  return next;
+}
+
+/**
+ * Merge a new root into an existing list, deduplicating and sorting.
+ *
+ * Returns the original reference when the root is already present.
+ */
+export function mergeKnownRoots(roots: string[], root: string): string[] {
+  if (roots.includes(root)) return roots;
+  return sortRootsBySpecificity([...roots, root]);
+}
+
+/**
+ * Resolve the most specific known root that contains `filePath`.
+ *
+ * Searches the given roots list (presumed sorted by specificity) and returns
+ * the first root that contains or equals `filePath`.
+ *
+ * @returns The matching root string, or `null` when none match.
+ */
+export function resolveKnownRoot(filePath: string, roots: string[]): string | null {
+  const resolvedPath = path.resolve(filePath);
+  return roots.find((root) => isWithinOrEqual(root, resolvedPath)) ?? null;
+}
+
+/**
+ * Sort roots by specificity (deepest/longest first), then alphabetically.
+ *
+ * Deduplicates by resolved path before sorting.
+ */
+export function sortRootsBySpecificity(roots: string[]): string[] {
+  return [...new Set(roots.map((root) => path.resolve(root)))].sort(
+    (a, b) => b.length - a.length || a.localeCompare(b),
+  );
+}
+
+/**
+ * Check if `child` is strictly inside `parent`.
+ *
+ * Returns `true` when `child` is a subdirectory of `parent`.
+ * Returns `false` for the same path.
+ */
+export function isWithin(parent: string, child: string): boolean {
+  const relative = path.relative(parent, child);
+  return relative !== "" && !relative.startsWith(`..${path.sep}`) && relative !== "..";
+}
+
+/**
+ * Check if `filePath` is inside `root` or is the same path.
+ *
+ * Combines exact-path equality with `isWithin` semantics.
+ */
+export function isWithinOrEqual(root: string, filePath: string): boolean {
+  const relative = path.relative(root, filePath);
+  return relative === "" || isWithin(root, filePath);
+}
+
+/**
+ * Comparator for sorting paths by depth (shallowest first), then alphabetically.
+ *
+ * Useful with `.sort()` on arrays of path strings.
+ */
+export function byPathDepth(a: string, b: string): number {
+  const depthDiff = segmentCount(a) - segmentCount(b);
+  return depthDiff !== 0 ? depthDiff : a.localeCompare(b);
+}
+
+/**
+ * Count path segments in a resolved absolute path.
+ *
+ * @example segmentCount("/a/b/c") // 3
+ */
+export function segmentCount(target: string): number {
+  return path.resolve(target).split(path.sep).filter(Boolean).length;
+}

package/node_modules/@mrclrchtr/supi-core/src/project.ts

@@ -0,0 +1,15 @@
+// supi-core project domain — project root discovery and traversal.
+export type { KnownRootEntry } from "./project-roots.ts";
+export {
+  buildKnownRootsMap,
+  byPathDepth,
+  dedupeTopmostRoots,
+  findProjectRoot,
+  isWithin,
+  isWithinOrEqual,
+  mergeKnownRoots,
+  resolveKnownRoot,
+  segmentCount,
+  sortRootsBySpecificity,
+  walkProject,
+} from "./project-roots.ts";

package/node_modules/@mrclrchtr/supi-core/src/prompt-surface.ts

@@ -0,0 +1,4 @@
+// supi-core prompt-surface — configurable tool prompt-surface resolver (package boundary for @mrclrchtr/supi-core/prompt-surface).
+
+// biome-ignore lint/performance/noReExportAll: intentional barrel
+export * from "./config/prompt-surface.ts";

package/node_modules/@mrclrchtr/supi-core/src/registry-utils.ts

@@ -0,0 +1,93 @@
+// Shared registry utility for SuPi extensions.
+//
+// Provides a globalThis-backed registry pattern so that all jiti module instances
+// (resolved through different node_modules symlinks) share the same Map.
+// Without this, each symlink path gets its own module copy and its own Map,
+// so registrations from one instance are invisible to consumers in another.
+
+import * as path from "node:path";
+
+const SYMBOL_PREFIX = "@mrclrchtr/supi-core/";
+
+function getGlobalRegistryMap<T>(name: string): Map<string, T> {
+  const key = Symbol.for(SYMBOL_PREFIX + name);
+  let map = (globalThis as Record<symbol, unknown>)[key] as Map<string, T> | undefined;
+  if (!map) {
+    map = new Map<string, T>();
+    (globalThis as Record<symbol, unknown>)[key] = map;
+  }
+  return map;
+}
+
+/**
+ * Create a named registry backed by `globalThis` + `Symbol.for`.
+ *
+ * The registry is lazily initialized on first access and shared across all
+ * jiti module instances via the global symbol namespace.
+ *
+ * @typeParam T - The value type stored in the registry.
+ * @param name - Unique registry name (used to construct the `Symbol.for` key).
+ * @returns An object with `register`, `unregister`, `getAll`, and `clear` functions.
+ */
+export function createRegistry<T>(name: string) {
+  const getMap = (): Map<string, T> => getGlobalRegistryMap<T>(name);
+
+  return {
+    /**
+     * Register a value by id. Duplicate ids silently replace the previous registration.
+     */
+    register: (id: string, value: T): void => {
+      getMap().set(id, value);
+    },
+
+    /**
+     * Remove a registration by id. No-op if not registered.
+     */
+    unregister: (id: string): void => {
+      getMap().delete(id);
+    },
+
+    /**
+     * Get all registered values in registration order.
+     */
+    getAll: (): T[] => {
+      return Array.from(getMap().values());
+    },
+
+    /**
+     * Clear all entries from the registry (primarily for tests).
+     */
+    clear: (): void => {
+      getMap().clear();
+    },
+  };
+}
+
+/**
+ * Create a named session-state registry keyed by normalized cwd.
+ *
+ * This helper is intended for session-scoped runtime services that should be
+ * shared across duplicate jiti module instances while keeping package-specific
+ * state unions and convenience wrappers local to the calling package.
+ */
+export function createSessionStateRegistry<TState>(name: string) {
+  const getMap = (): Map<string, TState> => getGlobalRegistryMap<TState>(name);
+  const normalizeCwd = (cwd: string): string => path.resolve(cwd);
+
+  return {
+    /** Get the current state for one session cwd. */
+    get: (cwd: string): TState | undefined => {
+      return getMap().get(normalizeCwd(cwd));
+    },
+
+    /** Store the current state for one session cwd. */
+    set: (cwd: string, state: TState): void => {
+      getMap().set(normalizeCwd(cwd), state);
+    },
+
+    /** Clear the current state for one session cwd. */
+    clear: (cwd: string): void => {
+      getMap().delete(normalizeCwd(cwd));
+    },
+  };
+}

package/node_modules/@mrclrchtr/supi-core/src/report.ts

@@ -0,0 +1,121 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+
+/** Minimal theme surface required by the shared report helpers. */
+export type ReportTheme = Pick<Theme, "fg">;
+
+/** Color keys accepted by the report helpers. */
+export type ReportColor = Parameters<Theme["fg"]>[0];
+
+/** Options for rendering a themed key/value report row. */
+export interface KeyValueLineOptions {
+  /** The label shown on the left. */
+  label: string;
+  /** The value shown on the right. */
+  value: string;
+  /** Theme used for color formatting. */
+  theme: ReportTheme;
+  /** Maximum rendered width. */
+  width: number;
+  /** Left indentation in spaces. */
+  indent?: number;
+  /** Theme color applied to the label. Defaults to `"text"`. */
+  labelColor?: ReportColor;
+  /** Theme color applied to the value. Defaults to `"dim"`. */
+  valueColor?: ReportColor;
+  /** Separator placed between label and value. Defaults to `": "`. */
+  separator?: string;
+}
+
+/** Options for rendering a preview-overflow hint. */
+export interface OverflowHintOptions {
+  /** Optional follow-up hint such as `run /supi-context full`. */
+  hint?: string | null;
+  /** Left indentation in spaces. Defaults to `2`. */
+  indent?: number;
+}
+
+/** Ensure a report width never drops below the minimum readable width. */
+export function clampReportWidth(width: number, minWidth = 24): number {
+  return Math.max(minWidth, width);
+}
+
+/** Render a top-level report title line with theme color and truncation. */
+export function formatReportTitle(
+  title: string,
+  theme: ReportTheme,
+  width: number,
+  color: ReportColor = "accent",
+): string {
+  return truncateToWidth(theme.fg(color, title), width);
+}
+
+/**
+ * Render a section header with optional dimmed metadata.
+ *
+ * Example: `Usage by category  42.3k tokens`
+ */
+export function formatSectionHeader(
+  title: string,
+  meta: string | null,
+  theme: ReportTheme,
+  width: number,
+): string {
+  const left = theme.fg("text", title);
+  const content = meta ? `${left}${theme.fg("dim", `  ${meta}`)}` : left;
+  return truncateToWidth(content, width);
+}
+
+/** Render a single dimmed report line with optional left indentation. */
+export function formatDimLine(text: string, theme: ReportTheme, width: number, indent = 0): string {
+  const safeIndent = Math.max(0, indent);
+  return truncateToWidth(`${" ".repeat(safeIndent)}${theme.fg("dim", text)}`, width);
+}
+
+/** Render a dimmed preview-overflow hint such as `… and 3 more — run /foo full`. */
+export function formatOverflowHint(
+  hiddenCount: number,
+  theme: ReportTheme,
+  width: number,
+  options: OverflowHintOptions = {},
+): string {
+  const { hint = null, indent = 2 } = options;
+  const suffix = hint ? ` — ${hint}` : "";
+  return formatDimLine(`… and ${hiddenCount} more${suffix}`, theme, width, indent);
+}
+
+/** Render a single themed `label: value` row with truncation. */
+export function formatKeyValueLine(options: KeyValueLineOptions): string {
+  const {
+    label,
+    value,
+    theme,
+    width,
+    indent = 2,
+    labelColor = "text",
+    valueColor = "dim",
+    separator = ": ",
+  } = options;
+  const safeIndent = Math.max(0, indent);
+
+  return truncateToWidth(
+    `${" ".repeat(safeIndent)}${theme.fg(labelColor, label)}${separator}${theme.fg(valueColor, value)}`,
+    width,
+  );
+}
+
+/**
+ * Wrap a report text block to the available width and optionally prefix each line.
+ *
+ * This is useful for wrapped bullets or explanatory notes that should align
+ * under an existing report indent.
+ */
+export function wrapReportText(
+  text: string,
+  width: number,
+  options: { indent?: string } = {},
+): string[] {
+  const indent = options.indent ?? "";
+  const wrapped = wrapTextWithAnsi(text, Math.max(1, width - indent.length));
+  return indent ? wrapped.map((line) => `${indent}${line}`) : wrapped;
+}

package/node_modules/@mrclrchtr/supi-core/src/session-utils.ts

@@ -0,0 +1,71 @@
+// Generic session-file tree-walking utilities.
+
+import type { FileEntry, SessionEntry } from "@earendil-works/pi-coding-agent";
+
+/**
+ * Minimal pi API surface needed to track the current session display name reactively.
+ * Accept `ExtensionAPI` or any object satisfying this shape.
+ */
+export interface SessionNameTrackerHost {
+  on(event: string, handler: (...args: unknown[]) => unknown): void;
+  getSessionName(): string | undefined;
+}
+
+/**
+ * Create a reactive session-name tracker that stays consistent across
+ * session starts, renames, and shutdowns without polling.
+ *
+ * Subscribes to `session_start` (initial name), `session_info_changed`
+ * (renames via `/name`, `pi.setSessionName()`, or RPC), and
+ * `session_shutdown` (reset to `undefined`).
+ *
+ * @returns a zero-arg getter that always returns the current session name
+ *
+ * @example
+ * ```ts
+ * const getSessionName = createSessionNameTracker(pi);
+ * // …later, during tool execute or spinner rendering:
+ * const name = getSessionName();
+ * ```
+ */
+export function createSessionNameTracker(pi: SessionNameTrackerHost): () => string | undefined {
+  let name: string | undefined;
+
+  pi.on("session_start", () => {
+    name = pi.getSessionName();
+  });
+  pi.on("session_info_changed", (event) => {
+    name = (event as { name?: string }).name;
+  });
+  pi.on("session_shutdown", () => {
+    name = undefined;
+  });
+
+  return () => name;
+}
+
+/**
+ * Resolve the active branch path using PI's append-only tree semantics.
+ *
+ * The active branch is the path from the **last entry** (current leaf)
+ * back to the root via `parentId`. This follows PI's tree structure where
+ * entries are append-only and the last entry in the file is always the
+ * current leaf of the active branch.
+ */
+export function getActiveBranchEntries(entries: FileEntry[]): SessionEntry[] {
+  const sessionEntries = entries.filter((e): e is SessionEntry => e.type !== "session");
+  const byId = new Map(sessionEntries.map((entry) => [entry.id, entry]));
+  const leaf = sessionEntries.at(-1);
+  if (!leaf) return [];
+
+  const path: SessionEntry[] = [];
+  const visited = new Set<string>();
+  let current: SessionEntry | undefined = leaf;
+  while (current) {
+    if (visited.has(current.id)) break;
+    visited.add(current.id);
+    path.unshift(current);
+    current = current.parentId ? byId.get(current.parentId) : undefined;
+  }
+  return path;
+}

package/node_modules/@mrclrchtr/supi-core/src/session.ts

@@ -0,0 +1,8 @@
+// supi-core session domain — session utilities and registries.
+
+export { createRegistry, createSessionStateRegistry } from "./registry-utils.ts";
+export type { SessionNameTrackerHost } from "./session-utils.ts";
+export {
+  createSessionNameTracker,
+  getActiveBranchEntries,
+} from "./session-utils.ts";