@mrclrchtr/supi-insights 4.7.0 → 4.9.0

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}` : ""}`

package/src/parser.ts

@@ -1,6 +1,7 @@
 // Session parser — extract metadata and transcripts from PI session entries.
 
 import { readFile } from "node:fs/promises";
+import { diff } from "node:util";
 import type {
   AssistantMessage,
   Message,
@@ -10,7 +11,6 @@ import type {
 import type { FileEntry, SessionEntry, SessionHeader } from "@earendil-works/pi-coding-agent";
 import { migrateSessionEntries, parseSessionEntries } from "@earendil-works/pi-coding-agent";
 import { getActiveBranchEntries } from "@mrclrchtr/supi-core/session";
-import { diffLines } from "diff";
 import type { SessionMeta } from "./types.ts";
 import { getLanguageFromPath } from "./utils.ts";
 
@@ -41,6 +41,26 @@ const MCP_PREFIX = "mcp__";
 const WEB_SEARCH_TOOL = "web_search";
 const WEB_FETCH_TOOL = "web_fetch";
 
+/** Count added and removed lines while preserving final-newline changes. */
+export function countChangedLines(
+  oldText: string,
+  newText: string,
+): { added: number; removed: number } {
+  if (oldText === newText) return { added: 0, removed: 0 };
+
+  let added = 0;
+  let removed = 0;
+  for (const [operation] of diff(splitLines(oldText), splitLines(newText))) {
+    if (operation === -1) added++;
+    if (operation === 1) removed++;
+  }
+  return { added, removed };
+}
+
+function splitLines(text: string): string[] {
+  return text.match(/[^\n]*\n|[^\n]+$/g) ?? [];
+}
+
 export async function parseSessionFile(path: string): Promise<FileEntry[]> {
   const content = await readFile(path, { encoding: "utf-8" });
   const entries = parseSessionEntries(content);
@@ -191,10 +211,9 @@ function extractToolStats(entries: SessionEntry[]) {
                 typeof input.old_string === "string" &&
                 typeof input.new_string === "string"
               ) {
-                for (const change of diffLines(input.old_string, input.new_string)) {
-                  if (change.added) linesAdded += change.count || 0;
-                  if (change.removed) linesRemoved += change.count || 0;
-                }
+                const changedLines = countChangedLines(input.old_string, input.new_string);
+                linesAdded += changedLines.added;
+                linesRemoved += changedLines.removed;
               }
 
               if (toolName === "write" && typeof input.content === "string") {

package/src/types.ts

@@ -1,5 +1,7 @@
 // Shared types for supi-insights
 
+import type { InsightResultMap } from "./insight-schemas.ts";
+
 export type SessionMeta = {
   sessionId: string;
   projectPath: string;
@@ -101,14 +103,6 @@ export type AggregatedData = {
   insightSectionsFailed: string[];
 };
 
-export type InsightSectionName =
-  | "projectAreas"
-  | "interactionStyle"
-  | "whatWorks"
-  | "frictionAnalysis"
-  | "suggestions"
-  | "onTheHorizon"
-  | "atAGlance"
-  | "funEnding";
+export type InsightSectionName = keyof InsightResultMap;
 
-export type InsightResults = Partial<Record<InsightSectionName, unknown>>;
+export type InsightResults = Partial<InsightResultMap>;

package/node_modules/@mrclrchtr/supi-core/src/context/context-messages.ts

@@ -1,119 +0,0 @@
-// Shared context-message utilities for SuPi extensions.
-//
-// Provides a generic prune-and-reorder pattern for extensions that inject
-// managed context messages (via `before_agent_start` with a `customType` and
-// `contextToken`) and maintain them via the `context` event.
-
-/**
- * Minimal message shape needed for context-message operations.
- * Extensions cast their event.messages entries to this type.
- */
-export type ContextMessageLike = {
-  role?: string;
-  customType?: string;
-  content?: unknown;
-  details?: unknown;
-};
-
-/**
- * Extract the `contextToken` string from a message's `details` object.
- * Returns `null` when the token is absent or not a string.
- */
-export function getContextToken(details: unknown): string | null {
-  if (!details || typeof details !== "object") return null;
-  const token = (details as { contextToken?: unknown }).contextToken;
-  return typeof token === "string" ? token : null;
-}
-
-/**
- * Find the index of the last message with `role: "user"`.
- * Returns `-1` when no user message exists.
- */
-export function findLastUserMessageIndex<T extends ContextMessageLike>(messages: T[]): number {
-  for (let index = messages.length - 1; index >= 0; index--) {
-    if (messages[index]?.role === "user") return index;
-  }
-  return -1;
-}
-
-/**
- * Filter stale context messages and reorder the active one before the last user message.
- *
- * - Removes all messages matching `customType` whose token differs from `activeToken`.
- * - When `activeToken` is `null`, removes **all** messages of that `customType`.
- * - If the active context message is after the last user message, moves it before.
- *
- * Returns the modified array, or the original reference when no changes were needed.
- */
-export function pruneAndReorderContextMessages<T extends ContextMessageLike>(
-  messages: T[],
-  customType: string,
-  activeToken: string | null,
-): T[] {
-  // Remove stale messages of the target customType
-  const filtered = messages.filter((message) => {
-    if (message.customType !== customType) return true;
-    if (!activeToken) return false;
-    return getContextToken(message.details) === activeToken;
-  });
-
-  if (!activeToken) return filtered;
-
-  // Find the active context message
-  const contextIndex = filtered.findIndex(
-    (message) =>
-      message.customType === customType && getContextToken(message.details) === activeToken,
-  );
-  if (contextIndex === -1) return filtered;
-
-  // Find the last user message
-  const userIndex = findLastUserMessageIndex(filtered);
-  if (userIndex === -1 || contextIndex < userIndex) return filtered;
-
-  // Move context message before last user message
-  const next = [...filtered];
-  const [contextMessage] = next.splice(contextIndex, 1);
-  if (!contextMessage) return filtered;
-  next.splice(userIndex, 0, contextMessage);
-  return next;
-}
-
-/**
- * Restore the raw prompt content on a context message that was swapped for display text.
- *
- * Extensions using `registerMessageRenderer` store their LLM-facing content in
- * `details.promptContent` and put a human-readable summary in `content`. This function
- * reverses the swap so the model sees the original prompt content.
- *
- * Returns the original array reference when no change is needed.
- */
-export function restorePromptContent<T extends ContextMessageLike>(
-  messages: T[],
-  customType: string,
-  activeToken: string | null,
-): T[] {
-  if (!activeToken) return messages;
-
-  const index = messages.findIndex(
-    (message) =>
-      message.customType === customType && getContextToken(message.details) === activeToken,
-  );
-  if (index === -1) return messages;
-
-  const promptContent = getPromptContent(messages[index]?.details);
-  if (!promptContent || messages[index]?.content === promptContent) return messages;
-
-  const next = [...messages];
-  next[index] = { ...next[index], content: promptContent };
-  return next;
-}
-
-/**
- * Extract the `promptContent` string from a message's `details` object.
- * Returns `null` when absent or not a string.
- */
-export function getPromptContent(details: unknown): string | null {
-  if (!details || typeof details !== "object") return null;
-  const promptContent = (details as { promptContent?: unknown }).promptContent;
-  return typeof promptContent === "string" ? promptContent : null;
-}

package/node_modules/@mrclrchtr/supi-core/src/progress-widget.ts

@@ -1,189 +0,0 @@
-// Generic progress widget for SuPi long-running operations.
-//
-// Provides a TUI-based progress display with animated loader, turn counts,
-// tool usage, and activity descriptions.
-
-import type { Theme } from "@earendil-works/pi-coding-agent";
-import { CancellableLoader, Container, Text } from "@earendil-works/pi-tui";
-
-// ── Types ──────────────────────────────────────────────────────────────────
-
-/** What the reviewer is currently doing and on what. */
-export interface CurrentFocus {
-  /** Display label for the active tool (e.g. "Reading", "Searching", "Finding"). */
-  label: string;
-  /** Context detail (e.g. file path, search pattern, directory). */
-  detail: string;
-}
-
-/** Progress state for widget display, compatible with child-session updates. */
-export interface WidgetProgress {
-  /** Number of agent turns completed. */
-  turns: number;
-  /** Number of tool executions started. */
-  toolUses: number;
-  /** Token usage stats, if available. */
-  tokens?: {
-    input: number;
-    output: number;
-    total: number;
-    cacheRead?: number;
-    cacheWrite?: number;
-  };
-  /** Per-tool execution counts keyed by short display label (e.g. "diffs", "reads", "greps"). */
-  toolCounts?: Record<string, number>;
-  /** Number of distinct files inspected so far (via read_snapshot_diff / read_snapshot_file). */
-  filesInspected?: number;
-  /** Total files in the review snapshot. */
-  filesTotal?: number;
-  /** Current tool + context for the progress narrative line. */
-  currentFocus?: CurrentFocus;
-  /** Elapsed time in milliseconds since the operation started. */
-  elapsedMs?: number;
-}
-
-// ── Widget ─────────────────────────────────────────────────────────────────
-
-/**
- * TUI progress widget for long-running operations.
- *
- * Two-line layout: top line shows the narrative (current focus + file progress),
- * bottom line shows stats (tokens, elapsed time, turns, tool counts).
- */
-export class ProgressWidget extends Container {
-  private message: string;
-  private progress: WidgetProgress = { turns: 0, toolUses: 0 };
-  private loader: CancellableLoader;
-  private tui: { requestRender(): void };
-  private theme: Theme;
-
-  constructor(tui: { requestRender(): void }, theme: Theme, message: string) {
-    super();
-    this.tui = tui;
-    this.theme = theme;
-    this.message = message;
-    this.loader = new CancellableLoader(
-      tui as ConstructorParameters<typeof CancellableLoader>[0],
-      (text: string) => theme.fg("accent", text),
-      (text: string) => theme.fg("muted", text),
-      message,
-    );
-
-    this.renderContent();
-  }
-
-  /** AbortSignal that fires when the user presses Escape. */
-  get signal(): AbortSignal {
-    return this.loader.signal;
-  }
-
-  /** Callback invoked when the user presses Escape. */
-  set onAbort(fn: (() => void) | undefined) {
-    this.loader.onAbort = fn;
-  }
-
-  /** Delegate keyboard input to the loader. */
-  handleInput(data: string): void {
-    this.loader.handleInput(data);
-  }
-
-  /** Update progress state and request a re-render. */
-  updateProgress(progress: WidgetProgress): void {
-    this.progress = progress;
-    this.renderContent();
-    this.tui.requestRender();
-  }
-
-  /** Clean up the widget. */
-  dispose(): void {
-    this.loader.dispose();
-  }
-
-  private renderContent(): void {
-    this.clear();
-    this.renderTopLine();
-    this.renderBottomLine();
-  }
-
-  private renderTopLine(): void {
-    const topParts: string[] = [];
-
-    if (this.progress.currentFocus) {
-      const { label, detail } = this.progress.currentFocus;
-      topParts.push(detail ? `${label}: ${detail}` : label);
-    }
-
-    if (this.progress.filesTotal && this.progress.filesTotal > 0) {
-      const inspected = this.progress.filesInspected ?? 0;
-      topParts.push(`${inspected}/${this.progress.filesTotal} files`);
-    }
-
-    const loaderMessage =
-      topParts.length > 0 ? `${this.message} · ${topParts.join(" · ")}` : this.message;
-    this.loader.setMessage(loaderMessage);
-    this.addChild(this.loader);
-  }
-
-  private renderBottomLine(): void {
-    const stats: string[] = [];
-
-    this.appendTokenStats(stats);
-
-    if (this.progress.elapsedMs !== undefined && this.progress.elapsedMs >= 1000) {
-      stats.push(formatElapsed(this.progress.elapsedMs));
-    }
-
-    if (this.progress.turns > 0) {
-      stats.push(`⟳ ${this.progress.turns}`);
-    }
-
-    if (this.progress.toolCounts) {
-      const parts = Object.entries(this.progress.toolCounts)
-        .filter(([, count]) => count > 0)
-        .sort(([, a], [, b]) => b - a)
-        .map(([label, count]) => `${count} ${label}`);
-      if (parts.length > 0) stats.push(parts.join(" · "));
-    }
-
-    if (stats.length > 0) {
-      this.addChild(new Text(this.theme.fg("dim", `  ${stats.join(" · ")}`), 1, 0));
-    }
-  }
-
-  private appendTokenStats(stats: string[]): void {
-    const tokens = this.progress.tokens;
-    if (!tokens) return;
-
-    stats.push(`↑ ${formatTokens(tokens.input)}`);
-    if (tokens.cacheRead !== undefined && tokens.cacheRead > 0) {
-      stats.push(`↲ ${formatTokens(tokens.cacheRead)}`);
-    }
-    if (tokens.cacheWrite !== undefined && tokens.cacheWrite > 0) {
-      stats.push(`↱ ${formatTokens(tokens.cacheWrite)}`);
-    }
-    stats.push(`↓ ${formatTokens(tokens.output)}`);
-  }
-}
-
-// ── Helpers ────────────────────────────────────────────────────────────────
-
-export function formatTokens(count: number): string {
-  if (count >= 1_000_000) return `${(count / 1_000_000).toFixed(1)}M`;
-  if (count >= 1_000) return `${(count / 1_000).toFixed(1)}k`;
-  return String(count);
-}
-
-export function formatElapsed(ms: number): string {
-  const totalSec = Math.floor(ms / 1000);
-  const hours = Math.floor(totalSec / 3600);
-  const minutes = Math.floor((totalSec % 3600) / 60);
-  const seconds = totalSec % 60;
-
-  if (hours > 0) {
-    return `${hours}h ${minutes}m ${seconds}s`;
-  }
-  if (minutes > 0) {
-    return `${minutes}m ${seconds}s`;
-  }
-  return `${seconds}s`;
-}