@mrclrchtr/supi-consulting 0.0.0-stage → 9.0.0

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-capabilities.ts

@@ -0,0 +1,242 @@
+import {
+  decodeSessionCapabilityProfileSnapshot,
+  type SessionCapabilityProfile,
+  type SessionCapabilityProfileSnapshot,
+} from "./session-capability-profiles.ts";
+
+/** 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[];
+  /** Original profile identity and exclusions. Later configuration changes do not affect this copy. */
+  profileSnapshot?: SessionCapabilityProfileSnapshot;
+}
+
+/** 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);
+  const denied = new Set(toolDenylist);
+  const profileSnapshot = decodeSessionCapabilityProfileSnapshot(record.profileSnapshot);
+
+  return {
+    version: 1,
+    eligibleToolNames,
+    initiallyInactiveToolNames,
+    toolDenylist,
+    toolEnabledNames: stringList(record.toolEnabledNames).filter(
+      (name) => eligible.has(name) && !denied.has(name),
+    ),
+    hiddenSkillNames: stringList(record.hiddenSkillNames),
+    ...(profileSnapshot ? { profileSnapshot } : {}),
+  };
+}
+
+/** Copy current exclusion sets for saving. Do not use inventory to remove names. */
+export function captureSessionCapabilityExclusions(
+  state: SessionCapabilityState,
+): SessionCapabilityProfile {
+  return {
+    excludedTools: [...new Set(state.toolDenylist)],
+    hiddenSkills: [...new Set(state.hiddenSkillNames)],
+  };
+}
+
+/**
+ * Replace exclusions and capture a profile copy. Return undefined for an invalid profile.
+ * Do not mutate the input state or activate tools. The caller owns runtime restoration.
+ */
+export function applySessionCapabilityProfile(
+  state: SessionCapabilityState,
+  profile: unknown,
+): SessionCapabilityState | undefined {
+  const profileSnapshot = decodeSessionCapabilityProfileSnapshot(profile);
+  if (!profileSnapshot) return undefined;
+  return decodeSessionCapabilities({
+    ...state,
+    toolDenylist: profileSnapshot.excludedTools,
+    hiddenSkillNames: profileSnapshot.hiddenSkills,
+    profileSnapshot,
+  });
+}
+
+function equalNameSets(left: readonly string[], right: readonly string[]): boolean {
+  const leftSet = new Set(left);
+  const rightSet = new Set(right);
+  return leftSet.size === rightSet.size && [...leftSet].every((name) => rightSet.has(name));
+}
+
+/** Compare current exclusions with the applied copy. No profile means no Modified marker. */
+export function isSessionCapabilityProfileModified(state: SessionCapabilityState): boolean {
+  const snapshot = state.profileSnapshot;
+  return (
+    snapshot !== undefined &&
+    (!equalNameSets(state.toolDenylist, snapshot.excludedTools) ||
+      !equalNameSets(state.hiddenSkillNames, snapshot.hiddenSkills))
+  );
+}
+
+/** 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();
+}