@mrclrchtr/supi-insights 0.1.0

package/README.md

@@ -0,0 +1,234 @@
+# @mrclrchtr/supi-insights
+
+> Usage insights and analytics for [pi](https://pi.dev) sessions. Inspired by Claude Code's `/insights` command, rebuilt for pi's extension architecture.
+
+Generate rich, shareable HTML reports analyzing your PI coding sessions — what you work on, how you interact with the agent, what works well, where friction happens, and what to try next.
+
+## What you get
+
+Running `/supi-insights` produces a report with:
+
+- **At a Glance** — high-level summary of what's working, what's hindering you, quick wins, and ambitious workflows for future models
+- **What You Work On** — project areas with session counts and descriptions
+- **How You Use PI** — narrative analysis of your interaction style and key patterns
+- **Impressive Things You Did** — notable workflows and accomplishments
+- **Where Things Go Wrong** — friction categories with concrete examples
+- **Charts & Stats** — tool usage, languages, session types, outcomes, satisfaction, response times, time-of-day patterns, tool errors, multi-session usage
+- **Suggestions** — CLAUDE.md additions, features to try, new usage patterns
+- **On the Horizon** — ambitious workflows to prepare for as models improve
+
+Reports are saved as self-contained HTML files you can open in any browser.
+
+## Installation
+
+```bash
+pi install npm:@mrclrchtr/supi-insights
+```
+
+> **🧪 Beta package** — not included in the `@mrclrchtr/supi` meta-package.
+> Install directly when you need session analytics.
+
+Or install from a local checkout with `pi install /path/to/packages/supi-insights`.
+
+## Usage
+
+Type `/supi-insights` in the pi editor and press Enter.
+
+```
+/supi-insights
+```
+
+The extension will:
+
+1. **Scan** all historical pi sessions across projects
+2. **Extract metadata** — tool counts, languages, git activity, lines changed, response times, errors (cached for future runs)
+3. **Extract qualitative facets** — goals, outcomes, satisfaction, friction via LLM analysis (cached)
+4. **Generate narrative insights** — coaching-style analysis in 7 parallel sections
+5. **Render an HTML report** — saved to `~/.pi/agent/supi/insights/report-{timestamp}.html`
+6. **Show a summary** — in the PI chat with a link to the full report
+
+### First run
+
+The first run may take a minute or two if you have many sessions, because it:
+- Parses all session JSONL files
+- Extracts metadata for each session
+- Runs ~50 LLM facet extractions (batched, 50 concurrent)
+- Generates ~8 LLM insight sections
+
+Subsequent runs are fast — cached metadata and facets are reused.
+
+## Configuration
+
+If your install surface includes `/supi-settings` (for example when also installing the `@mrclrchtr/supi` meta-package), this package contributes an **Insights** section there. You can also edit `~/.pi/agent/supi/config.json` directly:
+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| `enabled` | Enable or disable insights generation | `on` |
+| `maxSessions` | Maximum sessions to fully parse and analyze | `200` |
+| `maxFacets` | Maximum per-session LLM facet extractions | `50` |
+
+Example config:
+
+```json
+{
+  "insights": {
+    "enabled": true,
+    "maxSessions": 200,
+    "maxFacets": 50
+  }
+}
+```
+
+## Architecture
+
+```
+packages/supi-insights/src/
+├── insights.ts       # Extension factory — registers /supi-insights and settings
+├── scanner.ts        # Session discovery via SessionManager.listAll()
+├── parser.ts         # JSONL parsing, transcript extraction, tool stat aggregation
+├── extractor.ts      # LLM facet extraction via @earendil-works/pi-ai/complete()
+├── aggregator.ts     # Pure data aggregation + multi-clauding detection
+├── generator.ts      # Parallel narrative insight generation (7 sections)
+├── html.ts           # HTML report renderer with CSS bar charts
+├── cache.ts          # Facet and metadata caching
+├── utils.ts          # Chart helpers, label mappings, text utilities
+└── types.ts          # Shared TypeScript types
+```
+
+### Data flow
+
+```
+SessionManager.listAll()
+       │
+       ▼
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│  scanner    │────▶│   parser    │────▶│   cache     │
+└─────────────┘     └─────────────┘     └─────────────┘
+       │                                    │
+       │         ┌─────────────┐            │
+       └────────▶│  extractor  │◀───────────┘
+                 │ (LLM facets)│
+                 └─────────────┘
+                        │
+                        ▼
+               ┌─────────────┐
+               │  aggregator │
+               └─────────────┘
+                        │
+                        ▼
+               ┌─────────────┐
+               │  generator  │
+               │ (insights)  │
+               └─────────────┘
+                        │
+                        ▼
+               ┌─────────────┐
+               │    html     │
+               │   report    │
+               └─────────────┘
+```
+
+### Key design decisions
+
+**Direct LLM access** — Uses `@earendil-works/pi-ai/complete()` and `ctx.modelRegistry.getApiKeyAndHeaders()` to make API calls with the user's already-configured keys. No external SDK needed.
+
+**Aggressive caching** — Session metadata and LLM-extracted facets are cached in `~/.pi/agent/supi/insights/`. Cache keys include the session file path and modified timestamp, so branch files do not collide and resumed sessions are reprocessed.
+
+**Branch deduplication** — pi session files are append-only trees. The extension analyzes the active branch path, then keeps only the branch/file with the most user messages per session ID to avoid double-counting.
+
+**Substantive filtering** — Sessions with fewer than 2 user messages or lasting under 1 minute are skipped, as are sessions where the only goal is `warmup_minimal`.
+
+**Parallel processing** — Facet extractions run in batches of 50 concurrent LLM calls. Insight sections run in parallel too, with `atAGlance` generated last (it consumes outputs from all other sections).
+
+## Caching
+
+Cached data lives in `~/.pi/agent/supi/insights/`:
+
+```
+~/.pi/agent/supi/insights/
+├── meta/
+│   ├── {session-id}_{path-hash}_{modified-hash}.json    # Extracted metadata
+│   └── ...
+├── facets/
+│   ├── {session-id}_{path-hash}_{modified-hash}.json    # LLM-extracted facets
+│   └── ...
+└── report-{timestamp}.html    # Generated HTML reports
+```
+
+- **Metadata cache** includes: tool counts, languages, git activity, tokens, lines changed, response times, errors, feature flags
+- **Facet cache** includes: goals, outcomes, satisfaction, friction, success factors, brief summaries
+
+To force a full re-analysis, delete the cache directory:
+
+```bash
+rm -rf ~/.pi/agent/supi/insights/meta ~/.pi/agent/supi/insights/facets
+```
+
+## Multi-session detection
+
+The extension detects when you run multiple pi sessions simultaneously ("multi-clauding") using a sliding-window algorithm:
+
+- Collects all user message timestamps across sessions
+- Looks for the pattern `sessionA → sessionB → sessionA` within a 30-minute window
+- Reports overlap events, sessions involved, and percentage of messages during overlaps
+
+## Statistics tracked
+
+### Per-session
+- Tool usage counts
+- Programming languages used (from file paths in edit/write tool calls)
+- Git commits and pushes
+- Input/output tokens
+- Lines added/removed (via diff)
+- Files modified
+- User response times (time between assistant message and next user message)
+- Tool errors with categorization (Command Failed, Edit Failed, User Rejected, etc.)
+- User interruptions
+- Feature usage (task agents, MCP, web search, web fetch)
+- Message timestamps for time-of-day analysis
+
+### Aggregated
+- Total sessions, messages, duration, tokens
+- Days active, messages per day
+- Top tools, languages, goals, outcomes
+- Satisfaction and helpfulness distributions
+- Friction types and success factors
+- Response time histograms
+- Time-of-day patterns
+- Multi-session overlap events
+
+## Compared to Claude Code `/insights`
+
+| Feature | Claude Code | /supi-insights |
+|---------|-------------|---------------|
+| Session discovery | Manual filesystem scan | `SessionManager.listAll()` |
+| LLM access | Internal `queryWithModel()` | `@earendil-works/pi-ai/complete()` |
+| Output | HTML report + browser | HTML report + browser |
+| Caching | Custom `~/.claude/usage-data/` | `~/.pi/agent/supi/insights/` |
+| Multi-clauding | ✅ | ✅ |
+| Remote host collection | ✅ (ant-only, SCP) | ❌ (not applicable) |
+| Team feedback (ant-only) | ✅ | ❌ |
+| TUI dashboard | ❌ | Planned |
+| Live tracking | ❌ | Planned |
+
+## Development
+
+```bash
+# Typecheck
+pnpm exec tsc --noEmit -p packages/supi-insights/tsconfig.json
+
+# Test
+pnpm vitest run packages/supi-insights/
+```
+
+## Roadmap
+
+- [ ] **Live tracking** — accumulate stats via `tool_call`, `turn_end`, `model_select` events instead of only scanning historical sessions
+- [ ] **TUI overlay dashboard** — native PI terminal UI with ASCII bar charts, keyboard-navigable sections
+- [ ] **Export formats** — Markdown, JSON, CSV
+- [ ] **Trend comparison** — compare current report with previous reports
+- [ ] **Session drill-down** — `/supi-insights --session <id>` to analyze a specific session
+
+## License
+
+MIT

package/node_modules/@mrclrchtr/supi-core/README.md

@@ -0,0 +1,90 @@
+# @mrclrchtr/supi-core
+
+Shared infrastructure for SuPi packages.
+
+## Install
+
+Use it as a dependency in another extension package:
+
+```bash
+pnpm add @mrclrchtr/supi-core
+```
+
+## Package role
+
+`@mrclrchtr/supi-core` is a library package. It does **not** register a pi extension and is not meant to be installed as a standalone pi package.
+
+## What it provides
+
+Current exports cover:
+
+- shared config loading, scoped reads, writes, and key removal
+- config-backed settings registration helpers for `/supi-settings`
+- the shared settings registry, overlay UI, and `registerSettingsCommand()` helper
+- XML `<extension-context>` wrapping plus context-message utilities
+- context-provider and debug-event registries reused across SuPi packages
+- project root and path helpers reused by packages such as `supi-lsp`
+
+## Config system
+
+Config resolution order:
+
+```text
+defaults <- global <- project
+```
+
+Config file locations:
+
+- global: `~/.pi/agent/supi/config.json`
+- project: `.pi/supi/config.json`
+
+Main helpers:
+
+- `loadSupiConfig()` — effective merged config (`defaults <- global <- project`)
+- `loadSupiConfigForScope()` — raw single-scope config for settings UIs (`defaults <- selected scope`)
+- `writeSupiConfig()`
+- `removeSupiConfigKey()`
+- `registerConfigSettings()`
+
+## Context and settings helpers
+
+- `wrapExtensionContext()`
+- `findLastUserMessageIndex()`
+- `getContextToken()`
+- `pruneAndReorderContextMessages()`
+- `registerSettings()`
+- `registerSettingsCommand()`
+- `openSettingsOverlay()`
+
+## Example
+
+```ts
+import { loadSupiConfig, registerConfigSettings, wrapExtensionContext } from "@mrclrchtr/supi-core";
+
+const config = loadSupiConfig("my-extension", process.cwd(), {
+  enabled: true,
+});
+
+registerConfigSettings({
+  id: "my-extension",
+  label: "My Extension",
+  section: "my-extension",
+  defaults: { enabled: true },
+  buildItems: () => [],
+  persistChange: () => {},
+});
+
+const message = wrapExtensionContext("my-extension", "hello", {
+  turn: 1,
+  file: "CLAUDE.md",
+});
+```
+
+## Requirements
+
+- `@earendil-works/pi-coding-agent`
+- `@earendil-works/pi-tui`
+
+## Source
+
+- Main exports: `src/index.ts`

package/node_modules/@mrclrchtr/supi-core/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@mrclrchtr/supi-core",
+  "version": "0.1.0",
+  "description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mrclrchtr/supi.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "pi",
+    "pi-coding-agent"
+  ],
+  "files": [
+    "src/**/*.ts",
+    "!__tests__"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "vitest": "^4.1.4"
+  },
+  "main": "src/index.ts"
+}

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

@@ -0,0 +1,76 @@
+// Config-aware settings helper for SuPi config-backed settings sections.
+// Wraps registerSettings() and centralizes selected-scope loading + scoped persistence.
+
+import type { SettingItem } from "@earendil-works/pi-tui";
+import { loadSupiConfigForScope, removeSupiConfigKey, writeSupiConfig } from "./config.ts";
+import type { SettingsScope } from "./settings-registry.ts";
+import { registerSettings } from "./settings-registry.ts";
+
+export interface ConfigSettingsHelpers {
+  /** Write a key to the selected scope's config section. */
+  set(key: string, value: unknown): void;
+  /** Remove a key from the selected scope's config section. */
+  unset(key: string): void;
+}
+
+export interface ConfigSettingsOptions<T> {
+  /** Extension identifier — e.g. "lsp", "claude-md" */
+  id: string;
+  /** Human-readable label shown in the UI */
+  label: string;
+  /** SuPi config section name — e.g. "lsp", "claude-md" */
+  section: string;
+  /** Default config values */
+  defaults: T;
+  /** Build SettingItem[] from scoped config. Called by loadValues. */
+  buildItems: (settings: T, scope: SettingsScope, cwd: string) => SettingItem[];
+  /** Handle a settings change with scoped persistence helpers. */
+  persistChange: (
+    scope: SettingsScope,
+    cwd: string,
+    settingId: string,
+    value: string,
+    helpers: ConfigSettingsHelpers,
+  ) => void;
+  /** Optional home directory for config resolution (testing). */
+  homeDir?: string;
+}
+
+/**
+ * Register a config-backed settings section.
+ *
+ * Loads display values from the selected scope only (`defaults <- selected scope`)
+ * instead of merged effective runtime config. Provides scoped `set` / `unset`
+ * persistence helpers so extensions don't need to wire `writeSupiConfig` /
+ * `removeSupiConfigKey` by hand.
+ */
+export function registerConfigSettings<T>(options: ConfigSettingsOptions<T>): void {
+  registerSettings({
+    id: options.id,
+    label: options.label,
+    loadValues: (scope, cwd) => {
+      const settings = loadSupiConfigForScope(options.section, cwd, options.defaults, {
+        scope,
+        homeDir: options.homeDir,
+      });
+      return options.buildItems(settings, scope, cwd);
+    },
+    persistChange: (scope, cwd, settingId, value) => {
+      const helpers: ConfigSettingsHelpers = {
+        set: (key, val) => {
+          writeSupiConfig(
+            { section: options.section, scope, cwd },
+            { [key]: val },
+            { homeDir: options.homeDir },
+          );
+        },
+        unset: (key) => {
+          removeSupiConfigKey({ section: options.section, scope, cwd }, key, {
+            homeDir: options.homeDir,
+          });
+        },
+      };
+      options.persistChange(scope, cwd, settingId, value, helpers);
+    },
+  });
+}

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

@@ -0,0 +1,186 @@
+// Shared config system for SuPi extensions.
+//
+// Global config: ~/.pi/agent/supi/config.json
+// Project config: .pi/supi/config.json (relative to cwd)
+// Resolution: hardcoded defaults ← global ← project
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+const GLOBAL_CONFIG_DIR = ".pi/agent/supi";
+const PROJECT_CONFIG_DIR = ".pi/supi";
+const CONFIG_FILE = "config.json";
+
+function getGlobalConfigPath(homeDir?: string): string {
+  return path.join(homeDir ?? os.homedir(), GLOBAL_CONFIG_DIR, CONFIG_FILE);
+}
+
+function getProjectConfigPath(cwd: string): string {
+  return path.join(cwd, PROJECT_CONFIG_DIR, CONFIG_FILE);
+}
+
+function readJsonFile(filePath: string): Record<string, unknown> | null {
+  let content: string;
+  try {
+    content = fs.readFileSync(filePath, "utf-8");
+  } catch {
+    // ENOENT or permission error — silent, file may not exist
+    return null;
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    // biome-ignore lint/suspicious/noConsole: deliberate config parse warning
+    console.warn(`[supi-core] Failed to parse config file, ignoring: ${filePath}`);
+    return null;
+  }
+
+  if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+    return parsed as Record<string, unknown>;
+  }
+
+  // biome-ignore lint/suspicious/noConsole: deliberate config parse warning
+  console.warn(`[supi-core] Config file root is not an object, ignoring: ${filePath}`);
+  return null;
+}
+
+function shallowMerge<T>(base: T, ...overrides: Array<Record<string, unknown> | null>): T {
+  let result = { ...base };
+  for (const override of overrides) {
+    if (!override) continue;
+    result = { ...result, ...override };
+  }
+  return result;
+}
+
+export interface SupiConfigOptions {
+  homeDir?: string;
+}
+
+/**
+ * Load and merge config for a given extension section.
+ *
+ * Resolution order: defaults ← global ← project
+ */
+export function loadSupiConfig<T>(
+  section: string,
+  cwd: string,
+  defaults: T,
+  options?: SupiConfigOptions,
+): T {
+  const globalConfig = readJsonFile(getGlobalConfigPath(options?.homeDir));
+  const projectConfig = readJsonFile(getProjectConfigPath(cwd));
+
+  const globalSection = extractSection(globalConfig, section);
+  const projectSection = extractSection(projectConfig, section);
+
+  return shallowMerge(defaults, globalSection, projectSection);
+}
+
+/**
+ * Load config for a single scope only.
+ *
+ * Resolution order: defaults ← selected scope
+ *
+ * This is useful for settings UIs that need to show the raw values stored in
+ * one scope, rather than the effective merged config.
+ */
+export function loadSupiConfigForScope<T>(
+  section: string,
+  cwd: string,
+  defaults: T,
+  options: { scope: "global" | "project" } & SupiConfigOptions,
+): T {
+  const config =
+    options.scope === "global"
+      ? readJsonFile(getGlobalConfigPath(options.homeDir))
+      : readJsonFile(getProjectConfigPath(cwd));
+
+  const scopedSection = extractSection(config, section);
+  return shallowMerge(defaults, scopedSection);
+}
+
+export interface SupiConfigLocation {
+  section: string;
+  scope: "global" | "project";
+  cwd: string;
+}
+
+/**
+ * Write config values for a given extension section.
+ */
+export function writeSupiConfig(
+  loc: SupiConfigLocation,
+  value: Record<string, unknown>,
+  options?: SupiConfigOptions,
+): void {
+  const configPath =
+    loc.scope === "global" ? getGlobalConfigPath(options?.homeDir) : getProjectConfigPath(loc.cwd);
+
+  const dir = path.dirname(configPath);
+  fs.mkdirSync(dir, { recursive: true });
+
+  const existing = readJsonFile(configPath) ?? {};
+  existing[loc.section] = {
+    ...((existing[loc.section] as Record<string, unknown>) ?? {}),
+    ...value,
+  };
+
+  fs.writeFileSync(configPath, `${JSON.stringify(existing, null, 2)}\n`, "utf-8");
+}
+
+/**
+ * Remove a key from a config section.
+ * Used by `interval default` to remove the project override.
+ */
+export function removeSupiConfigKey(
+  loc: SupiConfigLocation,
+  key: string,
+  options?: SupiConfigOptions,
+): void {
+  const configPath =
+    loc.scope === "global" ? getGlobalConfigPath(options?.homeDir) : getProjectConfigPath(loc.cwd);
+
+  const existing = readJsonFile(configPath);
+  if (!existing) return;
+
+  const sectionData = existing[loc.section] as Record<string, unknown> | undefined;
+  if (!sectionData) return;
+
+  delete sectionData[key];
+
+  if (Object.keys(sectionData).length === 0) {
+    delete existing[loc.section];
+  }
+
+  const dir = path.dirname(configPath);
+  fs.mkdirSync(dir, { recursive: true });
+
+  const content = Object.keys(existing).length > 0 ? `${JSON.stringify(existing, null, 2)}\n` : "";
+
+  if (content) {
+    // Directory guaranteed to exist since we just read from it
+    fs.writeFileSync(configPath, content, "utf-8");
+  } else {
+    try {
+      fs.unlinkSync(configPath);
+    } catch {
+      // File may not exist
+    }
+  }
+}
+
+function extractSection(
+  config: Record<string, unknown> | null,
+  section: string,
+): Record<string, unknown> | null {
+  if (!config) return null;
+  const data = config[section];
+  if (typeof data === "object" && data !== null && !Array.isArray(data)) {
+    return data as Record<string, unknown>;
+  }
+  return null;
+}