@mrclrchtr/supi-consulting 0.0.0-stage → 8.0.1

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

@@ -0,0 +1,240 @@
+/** Exact names to exclude. Omitted configuration lists mean empty sets. */
+export interface SessionCapabilityProfileDefinition {
+  excludedTools?: string[];
+  hiddenSkills?: string[];
+}
+
+/** Validated exclusion sets. Names need not match the current inventory. */
+export interface SessionCapabilityProfile {
+  excludedTools: string[];
+  hiddenSkills: string[];
+}
+
+/** A profile is available only when validation has no errors. */
+export interface SessionCapabilityProfileValidation {
+  profile?: SessionCapabilityProfile;
+  errors: string[];
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function readNames(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const names: unknown[] = [...new Set(value)];
+  return names.every((name): name is string => typeof name === "string") ? names : undefined;
+}
+
+/** Validate and copy a complete definition. Do not check inventory or expand patterns. */
+export function validateSessionCapabilityProfile(
+  value: unknown,
+): SessionCapabilityProfileValidation {
+  if (!isRecord(value)) return { errors: ["Profile must be an object."] };
+  const excludedTools = Object.hasOwn(value, "excludedTools") ? readNames(value.excludedTools) : [];
+  const hiddenSkills = Object.hasOwn(value, "hiddenSkills") ? readNames(value.hiddenSkills) : [];
+  const errors = Object.keys(value)
+    .filter((key) => key !== "excludedTools" && key !== "hiddenSkills")
+    .map((key) => `Unknown profile field: ${key}.`);
+  if (!excludedTools) errors.push("excludedTools must be an array of strings.");
+  if (!hiddenSkills) errors.push("hiddenSkills must be an array of strings.");
+  if (errors.length || !excludedTools || !hiddenSkills) return { errors };
+  return { profile: { excludedTools, hiddenSkills }, errors };
+}
+
+/** Configuration scope that supplied a profile or default. */
+export type SessionCapabilityProfileScope = "global" | "project";
+
+/** Configuration values for the sessionCapabilities section. */
+export interface SessionCapabilityProfilesSection {
+  profiles?: Record<string, SessionCapabilityProfileDefinition>;
+  defaultProfile?: string | null;
+}
+
+/** Session-owned identity and original exclusion sets, independent of configuration. */
+export interface SessionCapabilityProfileSnapshot extends SessionCapabilityProfile {
+  id: string;
+  source: SessionCapabilityProfileScope;
+}
+
+/** A configuration error with a scope and field path for display. */
+export interface SessionCapabilityProfileDiagnostic {
+  scope: SessionCapabilityProfileScope;
+  path: string;
+  message: string;
+}
+
+/** A scoped definition, including invalid definitions and hidden global definitions. */
+export interface SessionCapabilityProfileEntry {
+  id: string;
+  source: SessionCapabilityProfileScope;
+  shadowed: boolean;
+  profile?: SessionCapabilityProfile;
+  errors: SessionCapabilityProfileDiagnostic[];
+}
+
+/** Default selection source can differ from the effective profile source. */
+export type SessionCapabilityProfileDefault =
+  | { status: "none"; source?: SessionCapabilityProfileScope }
+  | {
+      status: "resolved";
+      source: SessionCapabilityProfileScope;
+      id: string;
+      profile: SessionCapabilityProfileSnapshot;
+    }
+  | { status: "invalid"; source: SessionCapabilityProfileScope; id?: string };
+
+/** Raw sections, not merged configuration. Callers must check trust before project reads. */
+export interface ResolveSessionCapabilityProfilesOptions {
+  global?: unknown;
+  project?: unknown;
+  projectTrusted: boolean;
+}
+
+/** Data for profile rows, scoped actions, and default warnings. No I/O is performed. */
+export interface SessionCapabilityProfilesResolution {
+  entries: SessionCapabilityProfileEntry[];
+  effectiveProfiles: SessionCapabilityProfileSnapshot[];
+  default: SessionCapabilityProfileDefault;
+  errors: SessionCapabilityProfileDiagnostic[];
+}
+
+/** IDs contain lowercase ASCII words separated by single hyphens. */
+export function isSessionCapabilityProfileId(value: unknown): value is string {
+  return typeof value === "string" && /^[a-z]+(?:-[a-z]+)*$/.test(value);
+}
+
+/** Validate and copy stored identity and original lists. Invalid metadata has no identity. */
+export function decodeSessionCapabilityProfileSnapshot(
+  value: unknown,
+): SessionCapabilityProfileSnapshot | undefined {
+  if (!isRecord(value) || !isSessionCapabilityProfileId(value.id)) return undefined;
+  if (value.source !== "global" && value.source !== "project") return undefined;
+  const { id, source, ...definition } = value;
+  if (!Object.hasOwn(definition, "excludedTools") || !Object.hasOwn(definition, "hiddenSkills"))
+    return undefined;
+  const result = validateSessionCapabilityProfile(definition);
+  return result.profile ? { id, source, ...result.profile } : undefined;
+}
+
+function readEntries(
+  value: unknown,
+  source: SessionCapabilityProfileScope,
+): SessionCapabilityProfileEntry[] {
+  if (!isRecord(value) || !isRecord(value.profiles)) return [];
+  return Object.entries(value.profiles).map(([id, definition]) => {
+    const result = validateSessionCapabilityProfile(definition);
+    if (!isSessionCapabilityProfileId(id))
+      result.errors.push("Invalid profile ID: use lowercase words with single hyphens.");
+    return {
+      id,
+      source,
+      shadowed: false,
+      profile: result.errors.length ? undefined : result.profile,
+      errors: result.errors.map((message) => ({ scope: source, path: `profiles.${id}`, message })),
+    };
+  });
+}
+
+type DefaultReference =
+  | SessionCapabilityProfileDefault
+  | { status: "pending"; source: SessionCapabilityProfileScope; id: string };
+
+function readDefault(
+  value: unknown,
+  source: SessionCapabilityProfileScope,
+  errors: SessionCapabilityProfileDiagnostic[],
+): DefaultReference | undefined {
+  if (!isRecord(value) || !Object.hasOwn(value, "defaultProfile")) return undefined;
+  if (value.defaultProfile === null) return { status: "none", source };
+  if (isSessionCapabilityProfileId(value.defaultProfile)) {
+    return { status: "pending", source, id: value.defaultProfile };
+  }
+  errors.push({
+    scope: source,
+    path: "defaultProfile",
+    message: "defaultProfile must be null or a valid profile ID.",
+  });
+  return { status: "invalid", source };
+}
+
+function resolveDefault(
+  selected: DefaultReference | undefined,
+  profiles: SessionCapabilityProfileSnapshot[],
+  errors: SessionCapabilityProfileDiagnostic[],
+): SessionCapabilityProfileDefault {
+  if (!selected) return { status: "none" };
+  if (selected.status !== "pending") return selected;
+  const { source, id } = selected;
+  const profile = profiles.find((entry) => entry.id === id);
+  if (profile) return { status: "resolved", source, id, profile };
+  errors.push({
+    scope: source,
+    path: "defaultProfile",
+    message: `Default profile ${id} is missing or invalid. No profile will be applied.`,
+  });
+  return { status: "invalid", source, id };
+}
+
+interface ScopedProfiles {
+  entries: SessionCapabilityProfileEntry[];
+  errors: SessionCapabilityProfileDiagnostic[];
+  default?: DefaultReference;
+}
+
+/** Reject malformed sections, but retain known IDs to prevent global fallback. */
+function readSection(value: unknown, scope: SessionCapabilityProfileScope): ScopedProfiles {
+  if (value === undefined) return { entries: [], errors: [] };
+  if (!isRecord(value)) {
+    return {
+      entries: [],
+      default: { status: "invalid", source: scope },
+      errors: [
+        { scope, path: "sessionCapabilities", message: "sessionCapabilities must be an object." },
+      ],
+    };
+  }
+  const sectionErrors = Object.keys(value)
+    .filter((key) => key !== "profiles" && key !== "defaultProfile")
+    .map((key) => ({ scope, path: key, message: `Unknown section field: ${key}.` }));
+  if (Object.hasOwn(value, "profiles") && !isRecord(value.profiles)) {
+    sectionErrors.push({ scope, path: "profiles", message: "profiles must be an object." });
+  }
+  const entries = readEntries(value, scope);
+  const errors = [...sectionErrors, ...entries.flatMap((entry) => entry.errors)];
+  const selection = readDefault(value, scope, errors);
+  if (sectionErrors.length) {
+    for (const entry of entries) {
+      entry.profile = undefined;
+      entry.errors.push(...sectionErrors);
+    }
+    return { entries, errors, default: { status: "invalid", source: scope } };
+  }
+  return { entries, errors, default: selection };
+}
+
+/**
+ * Resolve whole profiles by ID. Ignore project data unless projectTrusted is true.
+ * An absent section is undefined. Malformed sections cannot supply profiles or a default.
+ */
+export function resolveSessionCapabilityProfiles(
+  options: ResolveSessionCapabilityProfilesOptions,
+): SessionCapabilityProfilesResolution {
+  const global = readSection(options.global, "global");
+  const project = readSection(options.projectTrusted ? options.project : undefined, "project");
+  const entries = [...global.entries, ...project.entries];
+  const errors = [...global.errors, ...project.errors];
+  const selected = new Map(entries.map((entry) => [entry.id, entry]));
+  for (const entry of entries) entry.shadowed = selected.get(entry.id) !== entry;
+  const effectiveProfiles = [...selected.values()].flatMap((entry) =>
+    entry.profile ? [{ id: entry.id, source: entry.source, ...entry.profile }] : [],
+  );
+  return {
+    entries,
+    effectiveProfiles,
+    default: resolveDefault(project.default ?? global.default, effectiveProfiles, errors),
+    errors,
+  };
+}

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,47 @@
+// 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 {
+  applySessionCapabilityProfile,
+  captureSessionCapabilityExclusions,
+  clearPendingSessionCapabilityForks,
+  createEmptySessionCapabilityState,
+  decodeSessionCapabilities,
+  findSessionCapabilities,
+  getSessionCapabilitySkillProvider,
+  isSessionCapabilityProfileModified,
+  readPendingSessionCapabilityFork,
+  registerSessionCapabilitySkillProvider,
+  SESSION_CAPABILITIES_ENTRY,
+  sessionCapabilityState,
+  setPendingSessionCapabilityFork,
+} from "./session-capabilities.ts";
+export type {
+  ResolveSessionCapabilityProfilesOptions,
+  SessionCapabilityProfile,
+  SessionCapabilityProfileDefault,
+  SessionCapabilityProfileDefinition,
+  SessionCapabilityProfileDiagnostic,
+  SessionCapabilityProfileEntry,
+  SessionCapabilityProfileScope,
+  SessionCapabilityProfileSnapshot,
+  SessionCapabilityProfilesResolution,
+  SessionCapabilityProfilesSection,
+  SessionCapabilityProfileValidation,
+} from "./session-capability-profiles.ts";
+export {
+  decodeSessionCapabilityProfileSnapshot,
+  isSessionCapabilityProfileId,
+  resolveSessionCapabilityProfiles,
+  validateSessionCapabilityProfile,
+} from "./session-capability-profiles.ts";
+export type { SessionNameTrackerHost } from "./session-utils.ts";
+export {
+  createSessionNameTracker,
+  getActiveBranchEntries,
+} from "./session-utils.ts";

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

@@ -0,0 +1,105 @@
+// Event-backed settings module registration and collection.
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ScopedFieldValue, SettingsAction } from "./settings-schema.ts";
+
+export const SUPI_SETTINGS_COLLECT_EVENT = "supi:settings:collect";
+
+export type SettingsScope = "project" | "global";
+
+/** Scope and PI runtime state supplied for each settings read. */
+export interface SettingsContext {
+  scope: SettingsScope;
+  cwd: string;
+  ctx?: ExtensionContext;
+}
+
+/** A resolved, source-aware settings view. */
+export interface SettingsSnapshot {
+  rows: ScopedFieldValue[];
+}
+
+/** One user action routed to its owning settings module. */
+export interface SettingsActionRequest extends SettingsContext {
+  fieldKey: string;
+  action: SettingsAction;
+}
+
+/** Optional user-facing result from a successful settings action. */
+export interface SettingsApplyResult {
+  notice?: {
+    message: string;
+    level: "info" | "warning" | "error";
+  };
+}
+
+/**
+ * Canonical settings interface consumed by `/supi-settings`.
+ *
+ * Reads are always asynchronous. Apply resolves only after durable writes and
+ * module-owned refresh work complete. Implementations throw on failed writes.
+ */
+export interface SettingsModule {
+  id: string;
+  /** Human-readable section label shown in the UI. */
+  label: string;
+  /** Optional label that groups this module within its section. */
+  subsection?: string;
+  read(context: SettingsContext): Promise<SettingsSnapshot>;
+  apply(request: SettingsActionRequest): Promise<SettingsApplyResult>;
+}
+
+export interface SettingsContributionCollector {
+  add(module: SettingsModule): void;
+}
+
+export interface SettingsCollectionDiagnostic {
+  kind: "warning";
+  message: string;
+}
+
+export interface SettingsCollectionResult {
+  modules: SettingsModule[];
+  diagnostics: SettingsCollectionDiagnostic[];
+}
+
+export function isSettingsContributionCollector(
+  value: unknown,
+): value is SettingsContributionCollector {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as { add?: unknown }).add === "function"
+  );
+}
+
+/** Create a collector with last-wins duplicate handling and warning diagnostics. */
+export function createSettingsContributionCollector(): SettingsContributionCollector & {
+  result(): SettingsCollectionResult;
+} {
+  const modules = new Map<string, SettingsModule>();
+  const diagnostics: SettingsCollectionDiagnostic[] = [];
+
+  return {
+    add(module: SettingsModule): void {
+      if (modules.has(module.id)) {
+        diagnostics.push({
+          kind: "warning",
+          message: `Duplicate SuPi settings contribution "${module.id}"; using the last contribution.`,
+        });
+      }
+      modules.set(module.id, module);
+    },
+    result(): SettingsCollectionResult {
+      return { modules: Array.from(modules.values()), diagnostics: [...diagnostics] };
+    },
+  };
+}
+
+/** Register one settings module during extension factory setup. */
+export function registerSettings(pi: ExtensionAPI, module: SettingsModule): void {
+  const dispose = pi.events.on(SUPI_SETTINGS_COLLECT_EVENT, (collector) => {
+    if (isSettingsContributionCollector(collector)) collector.add(module);
+  });
+  pi.on("session_shutdown", () => dispose());
+}