@mrclrchtr/supi-insights 4.7.0 → 4.8.0

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.8.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.8.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;

package/src/html.ts

@@ -26,14 +26,7 @@ function generateReportJs(hourCountsJson: string): string {
 }
 
 function renderAtAGlanceHtml(insights: InsightResults): string {
-  const atAGlance = insights.atAGlance as
-    | {
-        whatsWorking?: string;
-        whatsHindering?: string;
-        quickWins?: string;
-        ambitiousWorkflows?: string;
-      }
-    | undefined;
+  const atAGlance = insights.atAGlance;
 
   if (!atAGlance) return "";
 
@@ -51,12 +44,7 @@ function renderAtAGlanceHtml(insights: InsightResults): string {
 }
 
 function renderProjectAreasHtml(insights: InsightResults): string {
-  const projectAreas =
-    (
-      insights.projectAreas as
-        | { areas?: Array<{ name: string; sessionCount: number; description: string }> }
-        | undefined
-    )?.areas ?? [];
+  const projectAreas = insights.projectAreas?.areas ?? [];
 
   if (projectAreas.length === 0) return "";
 
@@ -81,9 +69,7 @@ function renderProjectAreasHtml(insights: InsightResults): string {
 }
 
 function renderInteractionHtml(insights: InsightResults): string {
-  const interactionStyle = insights.interactionStyle as
-    | { narrative?: string; keyPattern?: string }
-    | undefined;
+  const interactionStyle = insights.interactionStyle;
 
   if (!interactionStyle?.narrative) return "";
 
@@ -97,9 +83,7 @@ function renderInteractionHtml(insights: InsightResults): string {
 }
 
 function renderWhatWorksHtml(insights: InsightResults): string {
-  const whatWorks = insights.whatWorks as
-    | { intro?: string; impressiveWorkflows?: Array<{ title: string; description: string }> }
-    | undefined;
+  const whatWorks = insights.whatWorks;
 
   if (!whatWorks?.impressiveWorkflows?.length) return "";
 
@@ -122,12 +106,7 @@ function renderWhatWorksHtml(insights: InsightResults): string {
 }
 
 function renderFrictionHtml(insights: InsightResults): string {
-  const frictionAnalysis = insights.frictionAnalysis as
-    | {
-        intro?: string;
-        categories?: Array<{ category: string; description: string; examples?: string[] }>;
-      }
-    | undefined;
+  const frictionAnalysis = insights.frictionAnalysis;
 
   if (!frictionAnalysis?.categories?.length) return "";
 
@@ -151,23 +130,7 @@ function renderFrictionHtml(insights: InsightResults): string {
 }
 
 function renderSuggestionsHtml(insights: InsightResults): string {
-  const suggestions = insights.suggestions as
-    | {
-        claudeMdAdditions?: Array<{ addition: string; why: string; promptScaffold?: string }>;
-        featuresToTry?: Array<{
-          feature: string;
-          oneLiner: string;
-          whyForYou: string;
-          exampleCode?: string;
-        }>;
-        usagePatterns?: Array<{
-          title: string;
-          suggestion: string;
-          detail?: string;
-          copyablePrompt?: string;
-        }>;
-      }
-    | undefined;
+  const suggestions = insights.suggestions;
 
   if (!suggestions) return "";
 
@@ -237,17 +200,7 @@ function renderSuggestionsHtml(insights: InsightResults): string {
 }
 
 function renderHorizonHtml(insights: InsightResults): string {
-  const horizonData = insights.onTheHorizon as
-    | {
-        intro?: string;
-        opportunities?: Array<{
-          title: string;
-          whatsPossible: string;
-          howToTry?: string;
-          copyablePrompt?: string;
-        }>;
-      }
-    | undefined;
+  const horizonData = insights.onTheHorizon;
 
   if (!horizonData?.opportunities?.length) return "";
 
@@ -272,7 +225,7 @@ function renderHorizonHtml(insights: InsightResults): string {
 }
 
 function renderFunEndingHtml(insights: InsightResults): string {
-  const funEnding = insights.funEnding as { headline?: string; detail?: string } | undefined;
+  const funEnding = insights.funEnding;
 
   if (!funEnding?.headline) return "";
 

package/src/insight-schemas.ts

@@ -0,0 +1,91 @@
+import { type Static, Type } from "typebox";
+
+/** Validated result schemas for each generated insight section. */
+export const INSIGHT_SCHEMAS = {
+  projectAreas: Type.Object({
+    areas: Type.Array(
+      Type.Object({
+        name: Type.String(),
+        sessionCount: Type.Number(),
+        description: Type.String(),
+      }),
+    ),
+  }),
+  interactionStyle: Type.Object({
+    narrative: Type.String(),
+    keyPattern: Type.String(),
+  }),
+  whatWorks: Type.Object({
+    intro: Type.String(),
+    impressiveWorkflows: Type.Array(
+      Type.Object({
+        title: Type.String(),
+        description: Type.String(),
+      }),
+    ),
+  }),
+  frictionAnalysis: Type.Object({
+    intro: Type.String(),
+    categories: Type.Array(
+      Type.Object({
+        category: Type.String(),
+        description: Type.String(),
+        examples: Type.Array(Type.String()),
+      }),
+    ),
+  }),
+  suggestions: 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(),
+      }),
+    ),
+  }),
+  onTheHorizon: Type.Object({
+    intro: Type.String(),
+    opportunities: Type.Array(
+      Type.Object({
+        title: Type.String(),
+        whatsPossible: Type.String(),
+        howToTry: Type.String(),
+        copyablePrompt: Type.String(),
+      }),
+    ),
+  }),
+  atAGlance: Type.Object({
+    whatsWorking: Type.String(),
+    whatsHindering: Type.String(),
+    quickWins: Type.String(),
+    ambitiousWorkflows: Type.String(),
+  }),
+  funEnding: Type.Object({
+    headline: Type.String(),
+    detail: Type.String(),
+  }),
+} as const;
+
+/** Schema type map keyed by insight section name. */
+export type InsightSchemaMap = typeof INSIGHT_SCHEMAS;
+
+/** Result types derived from the schemas used to validate model output. */
+export type InsightResultMap = {
+  -readonly [Name in keyof InsightSchemaMap]: Static<InsightSchemaMap[Name]>;
+};

package/src/insights.ts

@@ -13,7 +13,7 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { loadSupiConfig } from "@mrclrchtr/supi-core/config";
-import { registerDeclarativeSettings } from "@mrclrchtr/supi-core/settings";
+import { defineConfigSettings, registerSettings } from "@mrclrchtr/supi-core/settings";
 import { aggregateData } from "./aggregator.ts";
 import {
   loadCachedFacets,
@@ -77,35 +77,38 @@ function getConfig(cwd: string): InsightsConfig {
 
 export default function insightsExtension(pi: ExtensionAPI) {
   // Register config-backed settings for /supi-settings
-  registerDeclarativeSettings(pi, {
-    id: "insights",
-    label: "Insights",
-    section: "insights",
-    defaults: {
-      enabled: true,
-      maxSessions: MAX_SESSIONS_TO_ANALYZE,
-      maxFacets: MAX_FACET_EXTRACTIONS,
-    },
-    fields: [
-      {
-        kind: "boolean" as const,
-        key: "enabled",
-        label: "Enable insights",
-      },
-      {
-        kind: "number" as const,
-        key: "maxSessions",
-        label: "Max sessions to analyze",
-        values: ["50", "100", "200", "500"],
-      },
-      {
-        kind: "number" as const,
-        key: "maxFacets",
-        label: "Max facet extractions",
-        values: ["20", "50", "100"],
+  registerSettings(
+    pi,
+    defineConfigSettings({
+      id: "insights",
+      label: "Insights",
+      section: "insights",
+      defaults: {
+        enabled: true,
+        maxSessions: MAX_SESSIONS_TO_ANALYZE,
+        maxFacets: MAX_FACET_EXTRACTIONS,
       },
-    ],
-  });
+      fields: [
+        {
+          kind: "boolean" as const,
+          key: "enabled",
+          label: "Enable insights",
+        },
+        {
+          kind: "number" as const,
+          key: "maxSessions",
+          label: "Max sessions to analyze",
+          values: ["50", "100", "200", "500"],
+        },
+        {
+          kind: "number" as const,
+          key: "maxFacets",
+          label: "Max facet extractions",
+          values: ["20", "50", "100"],
+        },
+      ],
+    }),
+  );
 
   // ── /supi-insights command ──────────────────────────────────
 
@@ -155,9 +158,7 @@ export default function insightsExtension(pi: ExtensionAPI) {
 
         const header = `# PI Insights\n\n${stats}\n${report.data.dateRange.start} to ${report.data.dateRange.end}\n`;
 
-        const atAGlance = report.insights.atAGlance as
-          | { whatsWorking?: string; quickWins?: string }
-          | undefined;
+        const atAGlance = report.insights.atAGlance;
 
         const summaryText = atAGlance
           ? `## At a Glance\n\n${atAGlance.whatsWorking ? `**What's working:** ${atAGlance.whatsWorking}` : ""}\n\n${atAGlance.quickWins ? `**Quick wins:** ${atAGlance.quickWins}` : ""}`