@mrclrchtr/supi-insights 4.7.0 → 4.9.0

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

@@ -1,26 +1,19 @@
-// Declarative settings schema for SuPi extensions.
+// Fixed SuPi-config adapter for the canonical settings module interface.
 //
-// Replaces the imperative config-backed buildItems/persistChange contribution
-// with a declarative field descriptor model. The shared settings module owns
-// scope inheritance, source-state resolution, value rendering, persistence,
-// and Inherit/Reset-to-default actions.
+// Declarative field descriptors let the adapter own scope inheritance,
+// source-state resolution, value rendering, persistence, and Unset actions.
 //
 // Custom fields remain for nested or unusual config; they report the same
 // source state as declarative flat fields.
 
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { Component } from "@earendil-works/pi-tui";
 import {
   loadSupiConfigSectionForScope,
   removeSupiConfigKey,
   writeSupiConfig,
 } from "../config/config.ts";
-import {
-  isSettingsContributionCollector,
-  type SettingsScope,
-  type SettingsSection,
-  SUPI_SETTINGS_COLLECT_EVENT,
-} from "./settings-registry.ts";
+import type { SettingsApplyResult, SettingsModule, SettingsScope } from "./settings-registry.ts";
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
@@ -52,10 +45,7 @@ export interface ConfigHelpers {
 // ── Field actions ─────────────────────────────────────────────────────────
 
 /** A user-initiated action on a settings row. */
-export type SettingsFieldAction =
-  | { kind: "set"; value: string }
-  | { kind: "inherit" }
-  | { kind: "resetToDefault" };
+export type SettingsAction = { kind: "set"; value: string } | { kind: "unset" };
 
 // ── Field descriptors ─────────────────────────────────────────────────────
 
@@ -153,15 +143,15 @@ export interface CustomField extends BaseField {
     ctx?: ExtensionContext,
   ) => Component;
   /**
-   * Persist handler called on set/inherit/resetToDefault actions.
+   * Persist handler called on set or unset actions.
    * Required for custom fields so they can write their nested config.
    */
   persist: (
     scope: SettingsScope,
     cwd: string,
-    action: SettingsFieldAction,
+    action: SettingsAction,
     helpers: ConfigHelpers,
-  ) => void;
+  ) => void | Promise<void>;
 }
 
 /** Union of all supported field kinds. */
@@ -176,8 +166,8 @@ export type SettingsField =
 
 // ── Contribution options ──────────────────────────────────────────────────
 
-/** Options for registerDeclarativeSettings. */
-export interface DeclarativeSettingsOptions {
+/** Options for the fixed SuPi-config settings adapter. */
+export interface ConfigSettingsOptions {
   /** Stable contribution identifier — e.g. "lsp", "claude-md". */
   id: string;
   /** Human-readable label shown in the UI. */
@@ -194,7 +184,7 @@ export interface DeclarativeSettingsOptions {
   homeDir?: string;
 }
 
-// ── Scoped section interface ─────────────────────────────────────────────
+// ── Source-aware row interface ───────────────────────────────────────────
 
 /** Resolved value for one field in one scope. */
 export interface ScopedFieldValue {
@@ -305,14 +295,14 @@ function createConfigHelpers(
   };
 }
 
-// ── Scoped section factory ────────────────────────────────────────────────
+// ── Fixed config adapter ─────────────────────────────────────────────────
 
 interface NotifyAfterPersistInput {
-  options: DeclarativeSettingsOptions;
+  options: ConfigSettingsOptions;
   field: SettingsField;
   scope: SettingsScope;
   cwd: string;
-  action: SettingsFieldAction;
+  action: SettingsAction;
   storedValue: unknown;
   ctx?: ExtensionContext;
 }
@@ -354,86 +344,86 @@ function notifyAfterPersist(input: NotifyAfterPersistInput): void {
   options.afterPersist(change);
 }
 
-function toDeclarativeSection(options: DeclarativeSettingsOptions): SettingsSection {
+function resolveConfigRows(
+  options: ConfigSettingsOptions,
+  scope: SettingsScope,
+  cwd: string,
+  ctx?: ExtensionContext,
+): ScopedFieldValue[] {
   const defaults = options.defaults as Record<string, unknown>;
+  const projectRaw = loadSupiConfigSectionForScope(options.section, cwd, {
+    scope: "project",
+    homeDir: options.homeDir,
+  });
+  const globalRaw = loadSupiConfigSectionForScope(options.section, cwd, {
+    scope: "global",
+    homeDir: options.homeDir,
+  });
+
+  return options.fields.map((field) => {
+    if (field.kind === "custom") {
+      const resolved = field.resolve(scope, cwd, ctx);
+      return {
+        field,
+        displayValue: resolved.displayValue
+          ? sourceBadge(resolved.displayValue, resolved.source)
+          : "",
+        editValue: resolved.editValue ?? resolved.displayValue,
+        source: resolved.source,
+        inheritanceSource: resolved.inheritanceSource,
+      };
+    }
+
+    const { value, source } = resolveValue(field.key, defaults, projectRaw, globalRaw, scope);
+    const displayValue = formatValue(value, field);
+    const inheritanceSource =
+      scope === "project" && source === "project"
+        ? globalRaw && field.key in globalRaw
+          ? "global"
+          : "default"
+        : undefined;
+
+    return {
+      field,
+      displayValue: sourceBadge(displayValue, source),
+      editValue: formatEditValue(value, field),
+      source,
+      inheritanceSource,
+    };
+  });
+}
+
+async function applyConfigAction(
+  options: ConfigSettingsOptions,
+  request: Parameters<SettingsModule["apply"]>[0],
+): Promise<SettingsApplyResult> {
+  const { scope, cwd, fieldKey, action, ctx } = request;
+  const field = options.fields.find((candidate) => candidate.key === fieldKey);
+  if (!field) return {};
+
+  const helpers = createConfigHelpers(options.section, scope, cwd, options.homeDir);
+  let storedValue: unknown;
+  if (field.kind === "custom") {
+    await field.persist(scope, cwd, action, helpers);
+    storedValue = action.kind === "set" ? action.value : undefined;
+  } else if (action.kind === "set") {
+    storedValue = parseTypedValue(action.value, field);
+    helpers.set(field.key, storedValue);
+  } else {
+    helpers.unset(field.key);
+  }
+  notifyAfterPersist({ options, field, scope, cwd, action, storedValue, ctx });
+  return {};
+}
+
+/** Adapt one fixed SuPi config section to the canonical settings interface. */
+export function defineConfigSettings(options: ConfigSettingsOptions): SettingsModule {
   return {
     id: options.id,
     label: options.label,
-    loadValues: (scope, cwd, ctx) => {
-      // Load raw section data for both scopes (no defaults)
-      const projectRaw = loadSupiConfigSectionForScope(options.section, cwd, {
-        scope: "project",
-        homeDir: options.homeDir,
-      });
-      const globalRaw = loadSupiConfigSectionForScope(options.section, cwd, {
-        scope: "global",
-        homeDir: options.homeDir,
-      });
-
-      // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: natural discriminator on field kind and source
-      return options.fields.map((field) => {
-        if (field.kind === "custom") {
-          const resolved = field.resolve(scope, cwd, ctx);
-          return {
-            field,
-            displayValue: resolved.displayValue
-              ? sourceBadge(resolved.displayValue, resolved.source)
-              : "",
-            editValue: resolved.editValue ?? resolved.displayValue,
-            source: resolved.source,
-            inheritanceSource: resolved.inheritanceSource,
-          };
-        }
-
-        const { value, source } = resolveValue(field.key, defaults, projectRaw, globalRaw, scope);
-        const displayValue = formatValue(value, field);
-
-        // Compute inheritanceSource for project-scope overrides
-        let inheritanceSource: "global" | "default" | undefined;
-        if (scope === "project" && source === "project") {
-          inheritanceSource = globalRaw && field.key in globalRaw ? "global" : "default";
-        }
-
-        return {
-          field,
-          displayValue: sourceBadge(displayValue, source),
-          editValue: formatEditValue(value, field),
-          source,
-          inheritanceSource,
-        };
-      });
-    },
-    // biome-ignore lint/complexity/useMaxParams: SettingsSection action handlers receive scope, cwd, field, action, and optional context
-    handleAction: (scope, cwd, fieldKey, action, ctx) => {
-      const field = options.fields.find((f) => f.key === fieldKey);
-      if (!field) return;
-
-      const section = options.section;
-      const helpers = createConfigHelpers(section, scope, cwd, options.homeDir);
-      let storedValue: unknown;
-
-      if (field.kind === "custom") {
-        field.persist(scope, cwd, action, helpers);
-        storedValue = action.kind === "set" ? action.value : undefined;
-        notifyAfterPersist({ options, field, scope, cwd, action, storedValue, ctx });
-        return;
-      }
-
-      switch (action.kind) {
-        case "set": {
-          storedValue = parseTypedValue(action.value, field);
-          helpers.set(field.key, storedValue);
-          break;
-        }
-        case "inherit":
-        case "resetToDefault": {
-          helpers.unset(field.key);
-          break;
-        }
-      }
-
-      notifyAfterPersist({ options, field, scope, cwd, action, storedValue, ctx });
-    },
+    read: ({ scope, cwd, ctx }) =>
+      Promise.resolve({ rows: resolveConfigRows(options, scope, cwd, ctx) }),
+    apply: (request) => applyConfigAction(options, request),
   };
 }
 
@@ -461,27 +451,3 @@ export function parseTypedValue(value: string, field: SettingsField): unknown {
       return value;
   }
 }
-
-// ── Registration ──────────────────────────────────────────────────────────
-
-/**
- * Register a declarative settings contribution for `/supi-settings`.
- *
- * Contributions are collected through PI's process-local event bus. Call this
- * during the extension factory function, not in async session handlers.
- */
-export function registerDeclarativeSettings(
-  pi: ExtensionAPI,
-  options: DeclarativeSettingsOptions,
-): void {
-  const section = toDeclarativeSection(options);
-  const dispose = pi.events.on(SUPI_SETTINGS_COLLECT_EVENT, (collector) => {
-    if (isSettingsContributionCollector(collector)) {
-      collector.add(section);
-    }
-  });
-
-  pi.on("session_shutdown", () => {
-    dispose();
-  });
-}

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

@@ -1,33 +1,36 @@
-// supi-core settings domain — event-backed declarative settings contributions and command wiring.
-
-export { registerSettingsCommand } from "./settings/settings-command.ts";
+// supi-core settings domain — settings modules and fixed-config adapters.
 export type {
+  SettingsActionRequest,
+  SettingsApplyResult,
   SettingsCollectionDiagnostic,
   SettingsCollectionResult,
+  SettingsContext,
   SettingsContributionCollector,
+  SettingsModule,
   SettingsScope,
-  SettingsSection,
+  SettingsSnapshot,
 } from "./settings/settings-registry.ts";
 export {
   createSettingsContributionCollector,
   isSettingsContributionCollector,
+  registerSettings,
   SUPI_SETTINGS_COLLECT_EVENT,
 } from "./settings/settings-registry.ts";
 export type {
   BoolField,
   ConfigHelpers,
+  ConfigSettingsOptions,
   CustomField,
-  DeclarativeSettingsOptions,
   EnumField,
   ModelPickerField,
   ModelPickerStaticOption,
   NumberField,
   ScopedFieldValue,
+  SettingsAction,
   SettingsField,
-  SettingsFieldAction,
   SettingsPersistedChange,
   StringField,
   StringListField,
   ValueSource,
 } from "./settings/settings-schema.ts";
-export { registerDeclarativeSettings } from "./settings/settings-schema.ts";
+export { defineConfigSettings } from "./settings/settings-schema.ts";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-insights",
-  "version": "4.7.0",
+  "version": "4.9.0",
   "description": "Historical Pi-session reports and shareable HTML",
   "license": "MIT",
   "repository": {
@@ -34,8 +34,7 @@
     "README.md"
   ],
   "dependencies": {
-    "diff": "^9.0.0",
-    "@mrclrchtr/supi-core": "4.7.0"
+    "@mrclrchtr/supi-core": "4.9.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"
@@ -62,9 +61,7 @@
     ],
     "image": "https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-insights/assets/social-preview.png"
   },
-  "main": "src/api.ts",
   "exports": {
-    "./api": "./src/api.ts",
     "./extension": "./src/extension.ts",
     "./package.json": "./package.json"
   }

package/src/generator.ts

@@ -2,108 +2,29 @@
 
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { callWithJsonResponse } from "@mrclrchtr/supi-core/llm";
-import { Type } from "typebox";
+import {
+  INSIGHT_SCHEMAS,
+  type InsightResultMap,
+  type InsightSchemaMap,
+} from "./insight-schemas.ts";
 import type { AggregatedData, InsightResults, SessionFacets } from "./types.ts";
 
-// ── TypeBox schemas for each insight section ───────────────────────────────
-
-const ProjectAreasSchema = Type.Object({
-  areas: Type.Array(
-    Type.Object({
-      name: Type.String(),
-      sessionCount: Type.Number(),
-      description: Type.String(),
-    }),
-  ),
-});
-
-const InteractionStyleSchema = Type.Object({
-  narrative: Type.String(),
-  keyPattern: Type.String(),
-});
-
-const WhatWorksSchema = Type.Object({
-  intro: Type.String(),
-  impressiveWorkflows: Type.Array(
-    Type.Object({
-      title: Type.String(),
-      description: Type.String(),
-    }),
-  ),
-});
-
-const FrictionAnalysisSchema = Type.Object({
-  intro: Type.String(),
-  categories: Type.Array(
-    Type.Object({
-      category: Type.String(),
-      description: Type.String(),
-      examples: Type.Array(Type.String()),
-    }),
-  ),
-});
-
-const SuggestionsSchema = Type.Object({
-  claudeMdAdditions: Type.Array(
-    Type.Object({
-      addition: Type.String(),
-      why: Type.String(),
-      promptScaffold: Type.String(),
-    }),
-  ),
-  featuresToTry: Type.Array(
-    Type.Object({
-      feature: Type.String(),
-      oneLiner: Type.String(),
-      whyForYou: Type.String(),
-      exampleCode: Type.String(),
-    }),
-  ),
-  usagePatterns: Type.Array(
-    Type.Object({
-      title: Type.String(),
-      suggestion: Type.String(),
-      detail: Type.String(),
-      copyablePrompt: Type.String(),
-    }),
-  ),
-});
-
-const OnTheHorizonSchema = Type.Object({
-  intro: Type.String(),
-  opportunities: Type.Array(
-    Type.Object({
-      title: Type.String(),
-      whatsPossible: Type.String(),
-      howToTry: Type.String(),
-      copyablePrompt: Type.String(),
-    }),
-  ),
-});
-
-const FunEndingSchema = Type.Object({
-  headline: Type.String(),
-  detail: Type.String(),
-});
-
-const AtAGlanceSchema = Type.Object({
-  whatsWorking: Type.String(),
-  whatsHindering: Type.String(),
-  quickWins: Type.String(),
-  ambitiousWorkflows: Type.String(),
-});
-
 // ── Section definitions ──────────────────────────────────────────────────
 
-type InsightSection = {
-  name: keyof InsightResults;
+type ParallelInsightSectionName = Exclude<keyof InsightResultMap, "atAGlance">;
+
+type InsightSection<Name extends ParallelInsightSectionName> = {
+  name: Name;
   prompt: string;
-  // biome-ignore lint/suspicious/noExplicitAny: TypeBox schema union
-  schema: ReturnType<typeof Type.Object<any>>;
+  schema: InsightSchemaMap[Name];
   maxTokens: number;
 };
 
-const INSIGHT_SECTIONS: InsightSection[] = [
+type ParallelInsightSection = {
+  [Name in ParallelInsightSectionName]: InsightSection<Name>;
+}[ParallelInsightSectionName];
+
+const INSIGHT_SECTIONS = [
   {
     name: "projectAreas",
     prompt: `Analyze this PI usage data and identify project areas.
@@ -116,7 +37,7 @@ RESPOND WITH ONLY A VALID JSON OBJECT:
 }
 
 Include 4-5 areas.`,
-    schema: ProjectAreasSchema,
+    schema: INSIGHT_SCHEMAS.projectAreas,
     maxTokens: 4096,
   },
   {
@@ -128,7 +49,7 @@ RESPOND WITH ONLY A VALID JSON OBJECT:
   "narrative": "2-3 paragraphs analyzing HOW the user interacts with PI. Use second person 'you'. Describe patterns: iterate quickly vs detailed upfront specs? Interrupt often or let the agent run? Include specific examples. Use **bold** for key insights.",
   "keyPattern": "One sentence summary of most distinctive interaction style"
 }`,
-    schema: InteractionStyleSchema,
+    schema: INSIGHT_SCHEMAS.interactionStyle,
     maxTokens: 4096,
   },
   {
@@ -144,7 +65,7 @@ RESPOND WITH ONLY A VALID JSON OBJECT:
 }
 
 Include 3 impressive workflows.`,
-    schema: WhatWorksSchema,
+    schema: INSIGHT_SCHEMAS.whatWorks,
     maxTokens: 4096,
   },
   {
@@ -160,7 +81,7 @@ RESPOND WITH ONLY A VALID JSON OBJECT:
 }
 
 Include 3 friction categories with 2 examples each.`,
-    schema: FrictionAnalysisSchema,
+    schema: INSIGHT_SCHEMAS.frictionAnalysis,
     maxTokens: 4096,
   },
   {
@@ -181,7 +102,7 @@ RESPOND WITH ONLY A VALID JSON OBJECT:
 }
 
 IMPORTANT: PRIORITIZE instructions that appear MULTIPLE TIMES in the user data.`,
-    schema: SuggestionsSchema,
+    schema: INSIGHT_SCHEMAS.suggestions,
     maxTokens: 4096,
   },
   {
@@ -197,7 +118,7 @@ RESPOND WITH ONLY A VALID JSON OBJECT:
 }
 
 Include 3 opportunities. Think BIG - autonomous workflows, parallel agents, iterating against tests.`,
-    schema: OnTheHorizonSchema,
+    schema: INSIGHT_SCHEMAS.onTheHorizon,
     maxTokens: 4096,
   },
   {
@@ -211,10 +132,10 @@ RESPOND WITH ONLY A VALID JSON OBJECT:
 }
 
 Find something genuinely interesting or amusing from the session summaries.`,
-    schema: FunEndingSchema,
+    schema: INSIGHT_SCHEMAS.funEnding,
     maxTokens: 2048,
   },
-];
+] satisfies readonly ParallelInsightSection[];
 
 // ── Public API ─────────────────────────────────────────────────────────────
 
@@ -232,13 +153,11 @@ export async function generateInsights(
 
   const insights: InsightResults = {};
   for (const { name, result } of results) {
-    if (result) {
-      insights[name] = result;
-    }
+    if (result) Object.assign(insights, { [name]: result });
   }
 
   // Generate at_a_glance sequentially (needs other sections)
-  const atAGlance = await generateAtAGlance(data, insights, dataContext, ctx);
+  const atAGlance = await generateAtAGlance(insights, dataContext, ctx);
   if (atAGlance) {
     insights.atAGlance = atAGlance;
   }
@@ -248,11 +167,11 @@ export async function generateInsights(
 
 // ── Section generators ────────────────────────────────────────────────────
 
-async function generateSectionInsight(
-  section: InsightSection,
+async function generateSectionInsight<Name extends ParallelInsightSectionName>(
+  section: InsightSection<Name>,
   dataContext: string,
   ctx: ExtensionContext,
-): Promise<{ name: keyof InsightResults; result: unknown }> {
+) {
   const result = await callWithJsonResponse(
     ctx,
     {
@@ -268,55 +187,33 @@ async function generateSectionInsight(
 }
 
 async function generateAtAGlance(
-  _data: AggregatedData,
   insights: InsightResults,
   dataContext: string,
   ctx: ExtensionContext,
-): Promise<unknown> {
+): Promise<InsightResultMap["atAGlance"] | null> {
   const projectAreasText =
-    (
-      insights.projectAreas as {
-        areas?: Array<{ name: string; description: string }>;
-      }
-    )?.areas
-      ?.map((a) => `- ${a.name}: ${a.description}`)
-      .join("\n") || "";
+    insights.projectAreas?.areas.map((area) => `- ${area.name}: ${area.description}`).join("\n") ??
+    "";
 
   const bigWinsText =
-    (
-      insights.whatWorks as {
-        impressiveWorkflows?: Array<{ title: string; description: string }>;
-      }
-    )?.impressiveWorkflows
-      ?.map((w) => `- ${w.title}: ${w.description}`)
-      .join("\n") || "";
+    insights.whatWorks?.impressiveWorkflows
+      .map((workflow) => `- ${workflow.title}: ${workflow.description}`)
+      .join("\n") ?? "";
 
   const frictionText =
-    (
-      insights.frictionAnalysis as {
-        categories?: Array<{ category: string; description: string }>;
-      }
-    )?.categories
-      ?.map((c) => `- ${c.category}: ${c.description}`)
-      .join("\n") || "";
+    insights.frictionAnalysis?.categories
+      .map((category) => `- ${category.category}: ${category.description}`)
+      .join("\n") ?? "";
 
   const featuresText =
-    (
-      insights.suggestions as {
-        featuresToTry?: Array<{ feature: string; oneLiner: string }>;
-      }
-    )?.featuresToTry
-      ?.map((f) => `- ${f.feature}: ${f.oneLiner}`)
-      .join("\n") || "";
+    insights.suggestions?.featuresToTry
+      .map((feature) => `- ${feature.feature}: ${feature.oneLiner}`)
+      .join("\n") ?? "";
 
   const horizonText =
-    (
-      insights.onTheHorizon as {
-        opportunities?: Array<{ title: string; whatsPossible: string }>;
-      }
-    )?.opportunities
-      ?.map((o) => `- ${o.title}: ${o.whatsPossible}`)
-      .join("\n") || "";
+    insights.onTheHorizon?.opportunities
+      .map((opportunity) => `- ${opportunity.title}: ${opportunity.whatsPossible}`)
+      .join("\n") ?? "";
 
   const prompt = `You're writing an "At a Glance" summary for a PI usage insights report.
 
@@ -365,7 +262,7 @@ ${horizonText}`;
       maxTokens: 4096,
       retries: 2,
     },
-    AtAGlanceSchema,
+    INSIGHT_SCHEMAS.atAGlance,
   );
 
   return result?.parsed ?? null;