@mrclrchtr/supi-review 1.10.0 → 1.11.0

package/README.md

@@ -33,7 +33,7 @@ After install, pi gets one command:
 The reviewer runs in managed child agent sessions:
 
 - a **brief synthesizer** creates a structured review brief from the active session branch
-- a **read-only reviewer** inspects the selected snapshot (without receiving bulk inline diffs) and submits structured findings
+- a **read-only reviewer** inspects the selected snapshot (without receiving bulk inline diffs) and submits structured review items
 
 ![Review target selection](https://raw.githubusercontent.com/mrclrchtr/supi/main/screenshots/supi-review-1.png)
 
@@ -52,10 +52,10 @@ The reviewer runs in managed child agent sessions:
 3. optionally add a short note
 4. resolve the snapshot
 5. synthesize a review brief from the current session history
-6. preview the synthesized brief + compact prompt preview
+6. preview the synthesized brief + compact prompt preview, then press `v` for an in-app inspector (Overview first, Raw Prompt via `tab`, export via `e`)
 7. the reviewer fetches per-file diffs on demand via snapshot-aware tools; live progress widget shows activity
-8. show the structured result as a custom message
-9. if findings exist, hand off to the main agent so it can ask what to do next
+8. normalize the submitted review items into a host-derived verdict + structured result
+9. if review items exist, hand off to the main agent so it can ask what to do next with fixed options (`Fix all`, `Fix selected`, `Verify findings`, `Skip`)
 
 ## Review targets
 
@@ -81,13 +81,27 @@ Before the actual review starts, the package:
   - focus areas
   - risky files
   - unresolved questions
+  - `reviewInstructionBlockIds` selected from a fixed host-owned catalog
 
 The synthesizer also receives a bounded diff excerpt from the snapshot so it can reason about actual code changes, not just filenames.
 
-That synthesized brief is then combined with the git snapshot into a compact reviewer prompt. The prompt contains the brief, file manifest, and per-file overview, but no large inline diffs. Instead, the reviewer session gets snapshot-aware tools (`read_snapshot_diff`, `read_snapshot_file`) to fetch exact per-file diffs and before/after file contents on demand.
+That synthesized brief is then combined with the git snapshot into a compact reviewer prompt. The host owns a fixed catalog of review instruction blocks, and the brief selects zero or more block IDs from that catalog when extra review guidance is warranted. The resulting prompt contains the brief, file manifest, per-file overview, and any brief-selected **mandatory review instructions**, but no large inline diffs. Instead, the reviewer session gets snapshot-aware tools (`read_snapshot_diff`, `read_snapshot_file`) to fetch exact per-file diffs and before/after file contents on demand.
 
 The session-transcript approach mirrors how Pi summarizes context for compaction: the entire resolved conversation is rendered in a readable label format and sent to the model as a whole, rather than relying on heuristic excerpt ranking.
 
+## Review-plan inspector
+
+Before the reviewer runs, the plan preview stays inside Pi:
+
+- `v` opens an in-app inspector instead of spawning an external pager
+- the inspector opens in **Overview** mode first
+- `tab` toggles between **Overview** and **Raw Prompt**
+- `↑↓` or `j` / `k` scroll long content in the inspector
+- `q` or `esc` returns to the summary preview without canceling the review
+- `e` exports the raw prompt to a temp file as a debugging fallback
+
+The Overview mode uses the same structured packet data that feeds the reviewer prompt: mandatory review instructions, file overview rows, and truncated snapshot notes all come from shared packet derivation rather than re-parsing the raw prompt text.
+
 ## Model selection
 
 Every `/supi-review` run asks you to choose the reviewer model.
@@ -101,20 +115,35 @@ Every `/supi-review` run asks you to choose the reviewer model.
 
 A successful review includes:
 
-- overall correctness verdict
+- a host-derived binary verdict:
+  - `PATCH IS CORRECT`
+  - `PATCH HAS ISSUES`
 - overall explanation
 - overall confidence score
-- structured findings with title, body, priority, confidence score, and code location
+- normalized action/category summary counts
+- structured review items with:
+  - title
+  - body
+  - category
+  - impact
+  - effort
+  - recommended action
+  - confidence score
+  - suggested fix
+  - verification hint
+  - optional code location
 - the synthesized brief that drove the review
 
 The renderer also handles failed, canceled, and timed-out reviews.
 
-When a successful review contains findings, `supi-review` also injects an agent-visible hidden follow-up message that asks the main agent to decide the next step with the user. If `ask_user` is available, the main agent is instructed to use it and offer:
+The reviewer model does **not** decide the final binary verdict directly. It submits review items plus overall explanation/confidence, then the host derives the verdict from the normalized items (`must-fix` items => `PATCH HAS ISSUES`).
+
+When a successful review contains review items, `supi-review` also injects an agent-visible hidden follow-up message that asks the main agent to decide the next step with the user. If `ask_user` is available, the main agent is instructed to use it and offer:
 
-- Done
 - Fix all
 - Fix selected
 - Verify findings
+- Skip
 
 ## Source
 
@@ -123,8 +152,11 @@ When a successful review contains findings, `supi-review` also injects an agent-
 - `src/git.ts` — git snapshot resolution
 - `src/history/collect.ts` — compaction-style session-context serialization
 - `src/history/synthesize.ts` — brief synthesis orchestration
-- `src/target/packet.ts` — final reviewer packet builder
+- `src/review-result.ts` — review-item normalization, verdict derivation, and summary counts
+- `src/target/review-instruction-blocks.ts` — fixed catalog of host-owned review instruction blocks
+- `src/target/packet.ts` — final reviewer packet builder + shared preview-data derivation for the inspector
 - `src/tool/brief-runner.ts` — brief synthesis child session
 - `src/tool/review-runner.ts` — read-only reviewer child session with snapshot-aware tools
 - `src/tool/snapshot-tools.ts` — per-file diff and before/after content tools scoped to the selected snapshot
+- `src/ui/review-plan-inspector.ts` — in-app summary/inspector preview with Overview + Raw Prompt modes and export fallback
 - `src/ui/renderer.ts` — structured result rendering

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

@@ -0,0 +1,103 @@
+<div align="center">
+  <a href="https://github.com/mrclrchtr/supi/tree/main/packages/supi-core">
+    <picture>
+      <img src="https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-core/assets/logo.png" alt="SuPi" width="50%">
+    </picture>
+  </a>
+</div>
+
+# @mrclrchtr/supi-core
+
+Shared infrastructure for SuPi extensions.
+
+This is a **pure library** — it does not register any pi commands or tools. The `/supi-settings` command is now available through `@mrclrchtr/supi-settings`.
+
+## Install
+
+```bash
+pnpm add @mrclrchtr/supi-core
+```
+
+## Package surfaces
+
+- `@mrclrchtr/supi-core/api` — reusable helpers for other packages and extensions
+
+## What you get from the API
+
+### Config helpers
+
+- `loadSupiConfig()` — merged config with resolution order `defaults <- global <- project`
+- `loadSupiConfigForScope()` — load one scope at a time for settings UIs
+- `writeSupiConfig()` — persist values
+- `removeSupiConfigKey()` — remove a key or override
+
+Config file locations:
+
+- global: `~/.pi/agent/supi/config.json`
+- project: `.pi/supi/config.json`
+
+### Settings helpers
+
+- `registerSettings()` — register an arbitrary settings section
+- `registerConfigSettings()` — register a config-backed settings section with scoped persistence helpers
+- `registerSettingsCommand()` — register `/supi-settings`
+- `openSettingsOverlay()` — open the shared settings UI directly
+- `createInputSubmenu()` — helper for simple text-entry submenus
+
+The built-in settings UI supports:
+
+- project/global scope toggle
+- grouped extension sections
+- searchable setting lists
+
+### Context helpers
+
+- `wrapExtensionContext()` — wrap injected text in SuPi's `<extension-context>` tag
+- `findLastUserMessageIndex()`
+- `getContextToken()`
+- `getPromptContent()`
+- `pruneAndReorderContextMessages()`
+- `restorePromptContent()`
+
+### Shared registries
+
+- context-provider registry for `/supi-context`
+- debug-event registry for producers that want shared debug capture
+- settings registry used by `/supi-settings`
+
+### Project and session helpers
+
+- project-root detection and directory walking helpers such as `findProjectRoot()` and `walkProject()`
+- active-branch session helper: `getActiveBranchEntries()`
+- terminal helpers such as `formatTitle()`, `signalWaiting()`, and `signalDone()`
+
+## Example
+
+```ts
+import { loadSupiConfig, registerConfigSettings, wrapExtensionContext } from "@mrclrchtr/supi-core/api";
+
+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", {
+  file: "CLAUDE.md",
+  turn: 1,
+});
+```
+
+## Source
+
+- `src/api.ts` — exported library surface
+- `src/config.ts` — shared config loading and writing
+- `src/config-settings.ts` — config-backed settings registration helper
+- `src/settings-ui.ts` — shared settings overlay

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

@@ -0,0 +1,59 @@
+{
+  "name": "@mrclrchtr/supi-core",
+  "version": "1.11.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-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  },
+  "main": "src/api.ts",
+  "exports": {
+    "./api": "./src/api.ts",
+    "./config": "./src/config.ts",
+    "./context": "./src/context.ts",
+    "./debug": "./src/debug-registry.ts",
+    "./llm": "./src/llm.ts",
+    "./package.json": "./package.json",
+    "./path": "./src/path.ts",
+    "./progress-widget": "./src/progress-widget.ts",
+    "./project": "./src/project.ts",
+    "./session": "./src/session.ts",
+    "./settings": "./src/settings.ts",
+    "./settings-ui": "./src/settings-ui.ts",
+    "./terminal": "./src/terminal.ts",
+    "./tool-framework": "./src/tool-framework.ts",
+    "./types": "./src/types.ts"
+  }
+}

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

@@ -0,0 +1,32 @@
+// supi-core — shared infrastructure for SuPi extensions.
+// Provides XML context tag wrapping, unified config system, context-message utilities,
+// settings registry for supi-wide TUI settings, and a shared tool-spec/registration framework.
+//
+// Convenience barrel — re-exports all domain entry points.
+// For lighter imports, use one of the domain subpaths directly
+// (e.g. @mrclrchtr/supi-core/config, @mrclrchtr/supi-core/context).
+
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./config.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./context.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./debug-registry.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./llm.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./path.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./project.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./session.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./settings.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./settings-ui.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./terminal.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./tool-framework.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./types.ts";

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

@@ -0,0 +1,182 @@
+// Config-aware settings helper for SuPi config-backed settings sections.
+// Wraps registerSettings() and centralizes selected-scope loading + scoped persistence.
+//
+// Setting items can declare a `configType` ("boolean" | "number" | "stringList")
+// to enable auto-generated persistChange. When all items have a configType,
+// the persistChange callback can be omitted.
+
+import type { SettingItem } from "@earendil-works/pi-tui";
+import type { SettingsScope } from "../settings/settings-registry.ts";
+import { registerSettings } from "../settings/settings-registry.ts";
+import { loadSupiConfigForScope, removeSupiConfigKey, writeSupiConfig } from "./config.ts";
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+/**
+ * Supported config value types for declarative persistChange.
+ *
+ * - `"boolean"`: maps "on" → true, "off" → false
+ * - `"number"`: parses integer via Number.parseInt, falls back to unset on invalid
+ * - `"stringList"`: splits on comma, trims whitespace, unsets on empty
+ */
+export type ConfigSettingType = "boolean" | "number" | "stringList";
+
+/**
+ * Extended setting item that can declare its config type for auto-generated
+ * persistence handling.
+ */
+export interface ConfigSettingItem extends SettingItem {
+  /**
+   * When set, persistChange for this item is auto-generated.
+   * All items must declare a configType for auto-generation to activate.
+   */
+  configType?: ConfigSettingType;
+}
+
+/**
+ * Helpers provided to the persistChange callback for writing or removing
+ * scoped config values.
+ */
+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.
+   *
+   * Items can include a `configType` property for auto-generated
+   * persistChange handling. When ALL items declare a configType,
+   * the `persistChange` callback can be omitted.
+   */
+  buildItems: (settings: T, scope: SettingsScope, cwd: string) => ConfigSettingItem[];
+  /**
+   * Handle a settings change with scoped persistence helpers.
+   *
+   * Optional when all items returned by `buildItems` declare a `configType`.
+   * Required when any item lacks a `configType`.
+   */
+  persistChange?: (
+    scope: SettingsScope,
+    cwd: string,
+    settingId: string,
+    value: string,
+    helpers: ConfigSettingsHelpers,
+  ) => void;
+  /** Optional home directory for config resolution (testing). */
+  homeDir?: string;
+}
+
+// ── Auto-generated persistChange ───────────────────────────────────────────
+
+function autoPersistChange(
+  settingId: string,
+  value: string,
+  helpers: ConfigSettingsHelpers,
+  items: ConfigSettingItem[],
+): void {
+  const item = items.find((i) => i.id === settingId);
+  if (!item?.configType) return;
+
+  switch (item.configType) {
+    case "boolean": {
+      helpers.set(settingId, value === "on");
+      break;
+    }
+    case "number": {
+      const num = Number.parseInt(value, 10);
+      if (Number.isFinite(num) && num > 0) {
+        helpers.set(settingId, num);
+      } else {
+        helpers.unset(settingId);
+      }
+      break;
+    }
+    case "stringList": {
+      const names = value
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+      if (names.length > 0) {
+        helpers.set(settingId, names);
+      } else {
+        helpers.unset(settingId);
+      }
+      break;
+    }
+  }
+}
+
+function areAllItemsDeclarative(items: ConfigSettingItem[]): boolean {
+  return items.length > 0 && items.every((i) => i.configType !== undefined);
+}
+
+// ── Registration ───────────────────────────────────────────────────────────
+
+/**
+ * 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.
+ *
+ * When every item returned by `buildItems` declares a `configType`, the
+ * `persistChange` callback is optional and will be auto-generated.
+ */
+export function registerConfigSettings<T>(options: ConfigSettingsOptions<T>): void {
+  let cachedItems: ConfigSettingItem[] | undefined;
+
+  registerSettings({
+    id: options.id,
+    label: options.label,
+    loadValues: (scope, cwd) => {
+      const settings = loadSupiConfigForScope(options.section, cwd, options.defaults, {
+        scope,
+        homeDir: options.homeDir,
+      });
+      const items = options.buildItems(settings, scope, cwd);
+      cachedItems = items;
+      return items;
+    },
+    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,
+          });
+        },
+      };
+
+      // Use manual persistChange when provided
+      if (options.persistChange) {
+        options.persistChange(scope, cwd, settingId, value, helpers);
+        return;
+      }
+
+      // Auto-generate when all items are declarative
+      const items = cachedItems ?? options.buildItems(options.defaults, scope, cwd);
+      if (areAllItemsDeclarative(items)) {
+        autoPersistChange(settingId, value, helpers, items);
+      }
+    },
+  });
+}

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

@@ -0,0 +1,206 @@
+// 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);
+}
+
+export 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;
+}
+
+/**
+ * Shorthand for {@link loadSupiConfig} that infers the return type from defaults.
+ *
+ * Reduces boilerplate when a package only needs the merged runtime config.
+ *
+ * @example
+ * ```ts
+ * const config = loadSectionConfig("my-ext", cwd, { enabled: true, timeout: 30 });
+ * // config is typed as { enabled: boolean; timeout: number }
+ * ```
+ */
+export function loadSectionConfig<T extends Record<string, unknown>>(
+  section: string,
+  cwd: string,
+  defaults: T,
+  options?: SupiConfigOptions,
+): T {
+  return loadSupiConfig(section, cwd, defaults, options);
+}