@mrclrchtr/supi-prompt-suggestions 7.2.1 → 7.3.0

package/node_modules/@mrclrchtr/supi-core/README.md

@@ -23,6 +23,7 @@ pnpm add @mrclrchtr/supi-core
 - `@mrclrchtr/supi-core/api` — reusable helpers for other packages and extensions
 - `@mrclrchtr/supi-core/llm` — PI-owned direct model requests and JSON helpers
 - `@mrclrchtr/supi-core/report` — shared text/report rendering helpers for TUI and plain-text summaries
+- `@mrclrchtr/supi-core/tui` — shared terminal UI helpers for list titles, rows, menus, and descriptions
 
 ## What you get from the API
 
@@ -70,6 +71,14 @@ Both completion helpers require a stable `affinityScope`. PI owns auth and endpo
 - active-branch session helper: `getActiveBranchEntries()`
 - terminal helpers such as `formatTitle()`, `signalWaiting()`, and `signalDone()`
 
+### TUI helpers
+
+- `formatTuiTitleLine()` — use the shared title style in terminal lists
+- `renderSelectableRow()` — render a selected row with an aligned value
+- `renderDescriptionViewport()` — show a fixed-height description preview
+- `renderTuiHintLine()` — render short key hints in one line
+- `createSelectListMenu()` — build an action menu with shared key hints
+
 ### Report helpers
 
 - `clampReportWidth()` — enforce a minimum readable report width
@@ -125,3 +134,4 @@ export default function myExtension(pi: ExtensionAPI) {
 - `src/debug-timing.ts` — monotonic total and phase timers for Debug Event Producers
 - `src/settings/` — settings registry, schema, scope resolution, and persistence
 - `src/report.ts` — shared text/report rendering helpers
+- `src/tui.ts` — shared terminal UI list and action-menu helpers

package/node_modules/@mrclrchtr/supi-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "7.2.1",
+  "version": "7.3.0",
   "description": "Shared settings, configuration, reporting, and session infrastructure",
   "license": "MIT",
   "repository": {
@@ -67,6 +67,7 @@
     "./settings": "./src/settings.ts",
     "./spinner-frames": "./src/spinner-frames.ts",
     "./status-spinner": "./src/status-spinner.ts",
-    "./terminal": "./src/terminal.ts"
+    "./terminal": "./src/terminal.ts",
+    "./tui": "./src/tui.ts"
   }
 }

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

@@ -38,3 +38,5 @@ export * from "./spinner-frames.ts";
 export * from "./status-spinner.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./terminal.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./tui.ts";

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

@@ -34,3 +34,5 @@ export * from "./settings.ts";
 export * from "./status-spinner.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./terminal.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./tui.ts";

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

@@ -0,0 +1,188 @@
+/** Session-only tool and skill visibility state. */
+export interface SessionCapabilityState {
+  version: 1;
+  eligibleToolNames: string[];
+  initiallyInactiveToolNames: string[];
+  toolDenylist: string[];
+  /** Tools that the user explicitly enabled for this session. */
+  toolEnabledNames?: string[];
+  hiddenSkillNames: string[];
+}
+
+/** A model-visible skill that a provider can offer to the selector. */
+export interface SessionCapabilitySkill {
+  name: string;
+  description: string;
+}
+
+/** Skill inventory provider registered by the skills extension. */
+export interface SessionCapabilitySkillProvider<TContext = unknown> {
+  listEligibleSkills(
+    context: TContext,
+  ): Promise<SessionCapabilitySkill[]> | SessionCapabilitySkill[];
+}
+
+/** Custom session-entry type used for hidden capability snapshots. */
+export const SESSION_CAPABILITIES_ENTRY = "supi-capabilities";
+
+const REGISTRY_PREFIX = "@mrclrchtr/supi-core/session-capabilities/";
+const STATE_KEY = Symbol.for(`${REGISTRY_PREFIX}state`);
+const PROVIDER_KEY = Symbol.for(`${REGISTRY_PREFIX}skill-providers`);
+const FORK_KEY = Symbol.for(`${REGISTRY_PREFIX}pending-forks`);
+
+type GlobalRegistry = typeof globalThis & Record<symbol, unknown>;
+
+type SkillProviderMap = Map<string, SessionCapabilitySkillProvider<unknown>>;
+type ForkStateMap = Map<string, SessionCapabilityState>;
+
+function getStateMap(): Map<string, SessionCapabilityState> {
+  const target = globalThis as GlobalRegistry;
+  let map = target[STATE_KEY] as Map<string, SessionCapabilityState> | undefined;
+  if (!map) {
+    map = new Map();
+    target[STATE_KEY] = map;
+  }
+  return map;
+}
+
+function getProviderMap(): SkillProviderMap {
+  const target = globalThis as GlobalRegistry;
+  let map = target[PROVIDER_KEY] as SkillProviderMap | undefined;
+  if (!map) {
+    map = new Map();
+    target[PROVIDER_KEY] = map;
+  }
+  return map;
+}
+
+function getForkMap(): ForkStateMap {
+  const target = globalThis as GlobalRegistry;
+  let map = target[FORK_KEY] as ForkStateMap | undefined;
+  if (!map) {
+    map = new Map();
+    target[FORK_KEY] = map;
+  }
+  return map;
+}
+
+function stringList(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return Array.from(new Set(value.filter((item): item is string => typeof item === "string")));
+}
+
+/** Create an empty state snapshot. */
+export function createEmptySessionCapabilityState(): SessionCapabilityState {
+  return {
+    version: 1,
+    eligibleToolNames: [],
+    initiallyInactiveToolNames: [],
+    toolDenylist: [],
+    toolEnabledNames: [],
+    hiddenSkillNames: [],
+  };
+}
+
+/** Validate and copy one stored snapshot. */
+export function decodeSessionCapabilities(value: unknown): SessionCapabilityState | undefined {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+  const record = value as Record<string, unknown>;
+  if (record.version !== 1) return undefined;
+
+  const initiallyInactiveToolNames = stringList(record.initiallyInactiveToolNames);
+  const initiallyInactive = new Set(initiallyInactiveToolNames);
+  const eligibleToolNames = stringList(record.eligibleToolNames).filter(
+    (name) => !initiallyInactive.has(name),
+  );
+  const eligible = new Set(eligibleToolNames);
+  const toolDenylist = stringList(record.toolDenylist).filter((name) => eligible.has(name));
+  const denied = new Set(toolDenylist);
+
+  return {
+    version: 1,
+    eligibleToolNames,
+    initiallyInactiveToolNames,
+    toolDenylist,
+    toolEnabledNames: stringList(record.toolEnabledNames).filter(
+      (name) => eligible.has(name) && !denied.has(name),
+    ),
+    hiddenSkillNames: stringList(record.hiddenSkillNames),
+  };
+}
+
+/** Return a safe copy of the latest valid snapshot in all session entries. */
+export function findSessionCapabilities(
+  entries: readonly unknown[],
+): SessionCapabilityState | undefined {
+  for (let index = entries.length - 1; index >= 0; index--) {
+    const entry = entries[index];
+    if (typeof entry !== "object" || entry === null) continue;
+    const record = entry as Record<string, unknown>;
+    if (record.type !== "custom" || record.customType !== SESSION_CAPABILITIES_ENTRY) continue;
+    const state = decodeSessionCapabilities(record.data);
+    if (state) return state;
+  }
+  return undefined;
+}
+
+/** Shared session state. Session IDs keep sessions in the same cwd separate. */
+export const sessionCapabilityState = {
+  get(sessionId: string): SessionCapabilityState | undefined {
+    const state = getStateMap().get(sessionId);
+    return state ? decodeSessionCapabilities(state) : undefined;
+  },
+  set(sessionId: string, state: SessionCapabilityState): void {
+    const decoded = decodeSessionCapabilities(state);
+    if (decoded) getStateMap().set(sessionId, decoded);
+  },
+  clear(sessionId: string): void {
+    getStateMap().delete(sessionId);
+  },
+};
+
+/** Register the current session's skill inventory provider. */
+export function registerSessionCapabilitySkillProvider<TContext>(
+  sessionId: string,
+  provider: SessionCapabilitySkillProvider<TContext>,
+): () => void {
+  const providers = getProviderMap();
+  providers.set(sessionId, provider as SessionCapabilitySkillProvider<unknown>);
+  return () => {
+    if (providers.get(sessionId) === provider) providers.delete(sessionId);
+  };
+}
+
+/** Get the current session's skill inventory provider, if one is loaded. */
+export function getSessionCapabilitySkillProvider<TContext = unknown>(
+  sessionId: string,
+): SessionCapabilitySkillProvider<TContext> | undefined {
+  return getProviderMap().get(sessionId) as SessionCapabilitySkillProvider<TContext> | undefined;
+}
+
+function forkKey(sourceSessionFile: string | undefined): string {
+  return sourceSessionFile ?? "<memory-session>";
+}
+
+/** Hold a state copy until PI starts the forked session. */
+export function setPendingSessionCapabilityFork(
+  sourceSessionFile: string | undefined,
+  state: SessionCapabilityState,
+): void {
+  const decoded = decodeSessionCapabilities(state);
+  if (decoded) getForkMap().set(forkKey(sourceSessionFile), decoded);
+}
+
+/** Take the state copy for one fork. The copy is used once. */
+export function readPendingSessionCapabilityFork(
+  sourceSessionFile: string | undefined,
+): SessionCapabilityState | undefined {
+  const forks = getForkMap();
+  const key = forkKey(sourceSessionFile);
+  const state = forks.get(key);
+  forks.delete(key);
+  return state ? decodeSessionCapabilities(state) : undefined;
+}
+
+/** Clear pending fork copies after a cancelled or unrelated transition. */
+export function clearPendingSessionCapabilityForks(): void {
+  getForkMap().clear();
+}

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

@@ -1,6 +1,23 @@
 // supi-core session domain — session utilities and registries.
 
 export { createRegistry, createSessionStateRegistry } from "./registry-utils.ts";
+export type {
+  SessionCapabilitySkill,
+  SessionCapabilitySkillProvider,
+  SessionCapabilityState,
+} from "./session-capabilities.ts";
+export {
+  clearPendingSessionCapabilityForks,
+  createEmptySessionCapabilityState,
+  decodeSessionCapabilities,
+  findSessionCapabilities,
+  getSessionCapabilitySkillProvider,
+  readPendingSessionCapabilityFork,
+  registerSessionCapabilitySkillProvider,
+  SESSION_CAPABILITIES_ENTRY,
+  sessionCapabilityState,
+  setPendingSessionCapabilityFork,
+} from "./session-capabilities.ts";
 export type { SessionNameTrackerHost } from "./session-utils.ts";
 export {
   createSessionNameTracker,

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

@@ -0,0 +1,141 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import {
+  type SelectItem,
+  SelectList,
+  type TuiMouseEvent,
+  type TuiMouseEventResult,
+  truncateToWidth,
+  visibleWidth,
+  wrapTextWithAnsi,
+} from "@earendil-works/pi-tui";
+
+/** The theme methods used by the shared TUI list renderers. */
+export type TuiTheme = Pick<Theme, "fg" | "bold">;
+
+/** Settings for one selectable row in a themed list. */
+export interface SelectableRowOptions {
+  /** The row label. */
+  label: string;
+  /** The value shown beside the label. */
+  value: string;
+  /** The row indent in terminal columns. */
+  indent: number;
+  /** The largest indent used by the list. */
+  maxIndent: number;
+  /** The label column width. */
+  maxLabelWidth: number;
+  /** The row width in terminal columns. */
+  width: number;
+  /** True when this row is selected. */
+  selected: boolean;
+  /** Theme used for row colors. */
+  theme: TuiTheme;
+}
+
+/** Settings for a shared action menu. */
+export interface SelectListMenuOptions {
+  /** The title shown above the choices. */
+  title: string;
+  /** The choices shown in the menu. */
+  items: SelectItem[];
+  /** Theme used for menu colors. */
+  theme: TuiTheme;
+  /** Called when the user selects a choice. */
+  onSelect: (item: SelectItem) => void;
+  /** Called when the user closes the menu without a choice. */
+  onCancel: () => void;
+}
+
+/** Component methods for a shared action menu. */
+export interface SelectListMenuComponent {
+  render(width: number): string[];
+  invalidate(): void;
+  handleInput(data: string): void;
+  handleMouse(event: TuiMouseEvent): TuiMouseEventResult | undefined;
+}
+
+/** Build a title line with optional right-side tabs in the shared TUI style. */
+export function formatTuiTitleLine(title: string, theme: TuiTheme, trailing = ""): string {
+  const titleText = theme.fg("accent", theme.bold(title));
+  return ` ${titleText}${trailing ? `  ${trailing}` : ""}`;
+}
+
+/** Render one row with a selected marker and an aligned value column. */
+export function renderSelectableRow(options: SelectableRowOptions): string {
+  const indent = Math.max(0, options.indent);
+  const maxIndent = Math.max(indent, options.maxIndent);
+  const maxLabelWidth = Math.max(0, options.maxLabelWidth);
+  const width = Math.max(0, options.width);
+  const label = truncateToWidth(options.label, maxLabelWidth, "");
+  const labelWidth = visibleWidth(label);
+  const prefix = options.selected
+    ? `${" ".repeat(Math.max(0, indent - 2))}${options.theme.fg("accent", "→ ")}`
+    : " ".repeat(indent);
+  const labelPadding = " ".repeat(maxIndent - indent + maxLabelWidth - labelWidth);
+  const valueWidth = Math.max(0, width - maxIndent - maxLabelWidth - 4);
+  const value = truncateToWidth(options.value, valueWidth, "");
+  const labelText = options.theme.fg(options.selected ? "accent" : "text", label + labelPadding);
+  const valueText = options.theme.fg(options.selected ? "accent" : "muted", value);
+
+  return truncateToWidth(`${prefix}${labelText}  ${valueText}`, width);
+}
+
+/** Render a fixed-height, four-line description preview for a selected row. */
+export function renderDescriptionViewport(
+  description: string | undefined,
+  width: number,
+): string[] {
+  const height = 4;
+  const indent = "  ";
+  const contentWidth = Math.max(1, width - 4);
+  const wrapped = description ? wrapTextWithAnsi(description, contentWidth) : [];
+  const visible = wrapped.slice(0, height);
+
+  if (wrapped.length > height) {
+    const lastIndex = height - 1;
+    visible[lastIndex] = truncateToWidth(`${visible[lastIndex] ?? ""}…`, contentWidth, "…");
+  }
+
+  while (visible.length < height) visible.push("");
+  return visible.map((line) => (line ? `${indent}${line}` : ""));
+}
+
+/** Render a dimmed hint line with the shared separator and truncation rules. */
+export function renderTuiHintLine(hints: string[], theme: TuiTheme, width: number): string {
+  return truncateToWidth(theme.fg("dim", hints.join(" · ")), width);
+}
+
+/** Build the shared title, choices, and key hints for an action menu. */
+export function createSelectListMenu(options: SelectListMenuOptions): SelectListMenuComponent {
+  const { items, onSelect, onCancel, theme, title } = options;
+  const selectList = new SelectList(items, Math.min(items.length + 2, 15), {
+    selectedPrefix: (text) => theme.fg("accent", text),
+    selectedText: (text) => theme.fg("accent", text),
+    description: (text) => theme.fg("muted", text),
+    scrollInfo: (text) => theme.fg("dim", text),
+    noMatch: (text) => theme.fg("warning", text),
+  });
+  selectList.onSelect = onSelect;
+  selectList.onCancel = onCancel;
+
+  return {
+    render(width) {
+      return [
+        truncateToWidth(theme.fg("accent", `  ${title}`), width),
+        ...selectList.render(width),
+        "",
+        renderTuiHintLine(["  ↑↓ navigate", "Enter select", "Esc cancel"], theme, width),
+      ];
+    },
+    invalidate() {
+      selectList.invalidate();
+    },
+    handleInput(data) {
+      selectList.handleInput(data);
+    },
+    handleMouse(event) {
+      if (event.y < 1) return undefined;
+      return selectList.handleMouse({ ...event, y: event.y - 1 });
+    },
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-prompt-suggestions",
-  "version": "7.2.1",
+  "version": "7.3.0",
   "description": "Optional model-powered ghost-text prompt suggestions",
   "license": "MIT",
   "repository": {
@@ -48,7 +48,7 @@
     "video": "https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-prompt-suggestions/assets/demo.mp4"
   },
   "dependencies": {
-    "@mrclrchtr/supi-core": "7.2.1"
+    "@mrclrchtr/supi-core": "7.3.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"