@mrclrchtr/supi-code-intelligence 2.0.6 → 2.1.0

package/README.md

@@ -24,6 +24,76 @@ pi install ./packages/supi-code-intelligence
 
 ![Code brief in action](https://raw.githubusercontent.com/mrclrchtr/supi/main/screenshots/supi-code-intelligence.png)
 
+## Quickstart
+
+### 1. Install the extension
+
+```bash
+pi install npm:@mrclrchtr/supi-code-intelligence
+```
+
+### 2. Install the language server for your project
+
+The extension auto-detects your project's language and tries to start the matching LSP server automatically. **You must install the server binary yourself** and ensure it is on your `PATH`.
+
+| Language | Binary to install |
+|---|---|
+| TypeScript / JavaScript | `typescript-language-server` (npm) |
+| Python | `pyright-langserver` (npm) |
+| Rust | `rust-analyzer` (rustup) |
+| Go | `gopls` (go install) |
+| C / C++ | `clangd` (system package manager) |
+| Bash | `bash-language-server` (npm) |
+| HTML | `vscode-html-language-server` (npm) |
+| SQL | `sql-language-server` (npm) |
+| Ruby | `ruby-lsp` (gem) |
+| Java | `jdtls` (system package manager) |
+| Kotlin | `kotlin-lsp` (Kotlin tooling) |
+| R | `R` with `languageserver` package installed |
+
+If a server binary is missing, the extension emits a warning at session start telling you exactly which command was not found and which file types are affected.
+
+### 3. Verify the stack is healthy
+
+You can check status interactively with the overlay command:
+
+```
+/supi-ci-status
+```
+
+This shows which language servers are active, which are missing, and any degraded coverage warnings in a TUI overlay.
+
+Alternatively, ask the pi agent to check for you:
+
+> *"Check the status of code intelligence servers."*
+
+The agent will run `code_health(include=["servers"])` and report back which servers are active. Semantic tools like `code_resolve` and `code_graph` need an active server for your project's language.
+
+### 4. Optional: tune or disable servers
+
+By default every detected language server starts concurrently. In polyglot repos this can spike CPU. To disable servers you do not need, run:
+
+```
+/supi-settings
+```
+
+Navigate to **LSP → Disabled Servers** and toggle off any languages you are not using. This writes per-language opt-outs into `.pi/supi/config.json` (project) or `~/.pi/agent/supi/config.json` (global).
+
+You can also edit the config file directly:
+
+```json
+{
+  "lsp": {
+    "servers": {
+      "python": { "enabled": false },
+      "rust": { "enabled": false }
+    }
+  }
+}
+```
+
+> **Note:** The global `lsp.enabled` switch and `lsp.active` allowlist are deprecated since v0.7.0 and have no effect.
+
 ## What you get
 
 After install, pi gets:
@@ -331,7 +401,7 @@ Unified ranked search tool with a strict evidence contract.
 - AST `call` mode matches call-site identifiers by name, not by symbol identity; use `code_graph` with `relations: ["references"]` on a resolved target for identity-aware callers
 - unsupported mode/kind combinations fail explicitly instead of being broadened into best-effort search
 
-Supports `query` (required), `scope`, `mode`, `kind`, `contextLines`, and `maxResults`.
+Supports `query` (required), `scope` (one path or an array of paths), `mode`, `kind`, `contextLines`, and `maxResults`.
 
 ### `code_health`
 Health/status summary for the current workspace or a scoped path.

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

@@ -39,10 +39,9 @@ Config file locations:
 
 ### 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
+- `registerConfigSettings(pi, options)` — contribute a config-backed settings section with scoped persistence helpers
+- `registerSettingsCommand(pi)` — register `/supi-settings` (used by `@mrclrchtr/supi-settings`)
+- `openSettingsOverlay(pi, ctx)` — open the shared settings UI directly
 - `createInputSubmenu()` — helper for simple text-entry submenus
 
 The built-in settings UI supports:
@@ -83,25 +82,34 @@ The built-in settings UI supports:
 ## Example
 
 ```ts
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 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,
-});
+export default function myExtension(pi: ExtensionAPI) {
+  const defaults = { enabled: true };
+  const config = loadSupiConfig("my-extension", process.cwd(), defaults);
+
+  registerConfigSettings(pi, {
+    id: "my-extension",
+    label: "My Extension",
+    section: "my-extension",
+    defaults,
+    buildItems: (settings) => [
+      {
+        id: "enabled",
+        label: "Enabled",
+        currentValue: settings.enabled ? "on" : "off",
+        values: ["on", "off"],
+        configType: "boolean" as const,
+      },
+    ],
+  });
+
+  const message = wrapExtensionContext("my-extension", "hello", {
+    enabled: config.enabled,
+  });
+  void message;
+}
 ```
 
 ## Source

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

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "2.0.6",
+  "version": "2.1.0",
   "description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
   "license": "MIT",
   "repository": {
@@ -70,6 +70,7 @@
     "./status-spinner": "./src/status-spinner.ts",
     "./terminal": "./src/terminal.ts",
     "./tool-framework": "./src/tool-framework.ts",
+    "./prompt-surface": "./src/prompt-surface.ts",
     "./types": "./src/types.ts"
   }
 }

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

@@ -1,14 +1,17 @@
-// Config-aware settings helper for SuPi config-backed settings sections.
-// Wraps registerSettings() and centralizes selected-scope loading + scoped persistence.
+// Config-aware settings contribution helper for SuPi packages.
 //
-// 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.
+// Registers config-backed settings sections through PI's shared event bus so
+// /supi-settings can collect contributions from all loaded extensions without
+// relying on a shared supi-core module instance.
 
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { SettingItem } from "@earendil-works/pi-tui";
-import type { SettingsScope } from "../settings/settings-registry.ts";
-import { registerSettings } from "../settings/settings-registry.ts";
+import {
+  isSettingsContributionCollector,
+  type SettingsScope,
+  type SettingsSection,
+  SUPI_SETTINGS_COLLECT_EVENT,
+} from "../settings/settings-registry.ts";
 import { loadSupiConfigForScope, removeSupiConfigKey, writeSupiConfig } from "./config.ts";
 
 // ── Types ──────────────────────────────────────────────────────────────────
@@ -22,22 +25,13 @@ import { loadSupiConfigForScope, removeSupiConfigKey, writeSupiConfig } from "./
  */
 export type ConfigSettingType = "boolean" | "number" | "stringList";
 
-/**
- * Extended setting item that can declare its config type for auto-generated
- * persistence handling.
- */
+/** Extended setting item that can declare its config type for persistence. */
 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.
-   */
+  /** Config value type used for auto-generated persistence. */
   configType?: ConfigSettingType;
 }
 
-/**
- * Helpers provided to the persistChange callback for writing or removing
- * scoped config values.
- */
+/** Helpers provided to persistChange for scoped SuPi config writes. */
 export interface ConfigSettingsHelpers {
   /** Write a key to the selected scope's config section. */
   set(key: string, value: unknown): void;
@@ -45,22 +39,23 @@ export interface ConfigSettingsHelpers {
   unset(key: string): void;
 }
 
+export interface ConfigSettingsPersistedChange {
+  scope: SettingsScope;
+  cwd: string;
+  settingId: string;
+  value: string;
+}
+
 export interface ConfigSettingsOptions<T> {
-  /** Extension identifier — e.g. "lsp", "claude-md" */
+  /** Settings contribution identifier — e.g. "lsp", "claude-md". */
   id: string;
-  /** Human-readable label shown in the UI */
+  /** Human-readable label shown in the UI. */
   label: string;
-  /** SuPi config section name — e.g. "lsp", "claude-md" */
+  /** SuPi config section name — e.g. "lsp", "claude-md". */
   section: string;
-  /** Default config values */
+  /** 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.
-   */
+  /** Build SettingItem[] from scoped config. */
   buildItems: (
     settings: T,
     scope: SettingsScope,
@@ -68,10 +63,10 @@ export interface ConfigSettingsOptions<T> {
     ctx?: ExtensionContext,
   ) => ConfigSettingItem[];
   /**
-   * Handle a settings change with scoped persistence helpers.
+   * Convert a UI value into scoped SuPi config writes.
    *
-   * Optional when all items returned by `buildItems` declare a `configType`.
-   * Required when any item lacks a `configType`.
+   * Optional when every item returned by `buildItems` declares `configType`.
+   * Required when any item lacks `configType`.
    */
   persistChange?: (
     scope: SettingsScope,
@@ -80,6 +75,8 @@ export interface ConfigSettingsOptions<T> {
     value: string,
     helpers: ConfigSettingsHelpers,
   ) => void;
+  /** Optional live runtime sync after successful persistence. */
+  afterPersist?: (change: ConfigSettingsPersistedChange) => void;
   /** Optional home directory for config resolution (testing). */
   homeDir?: string;
 }
@@ -128,23 +125,27 @@ function areAllItemsDeclarative(items: ConfigSettingItem[]): boolean {
   return items.length > 0 && items.every((i) => i.configType !== undefined);
 }
 
-// ── Registration ───────────────────────────────────────────────────────────
+function createHelpers<T>(options: ConfigSettingsOptions<T>, scope: SettingsScope, cwd: string) {
+  return {
+    set: (key: string, val: unknown) => {
+      writeSupiConfig(
+        { section: options.section, scope, cwd },
+        { [key]: val },
+        { homeDir: options.homeDir },
+      );
+    },
+    unset: (key: string) => {
+      removeSupiConfigKey({ section: options.section, scope, cwd }, key, {
+        homeDir: options.homeDir,
+      });
+    },
+  } satisfies ConfigSettingsHelpers;
+}
 
-/**
- * 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 {
+function toSettingsSection<T>(options: ConfigSettingsOptions<T>): SettingsSection {
   let cachedItems: ConfigSettingItem[] | undefined;
 
-  registerSettings({
+  return {
     id: options.id,
     label: options.label,
     loadValues: (scope, cwd, ctx) => {
@@ -157,32 +158,50 @@ export function registerConfigSettings<T>(options: ConfigSettingsOptions<T>): vo
       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
+      const helpers = createHelpers(options, scope, cwd);
+
       if (options.persistChange) {
         options.persistChange(scope, cwd, settingId, value, helpers);
-        return;
+      } else {
+        const items = cachedItems ?? options.buildItems(options.defaults, scope, cwd, undefined);
+        if (!areAllItemsDeclarative(items)) {
+          throw new Error(
+            `Settings contribution "${options.id}" needs persistChange or configType on every item.`,
+          );
+        }
+        autoPersistChange(settingId, value, helpers, items);
       }
 
-      // Auto-generate when all items are declarative
-      const items = cachedItems ?? options.buildItems(options.defaults, scope, cwd, undefined);
-      if (areAllItemsDeclarative(items)) {
-        autoPersistChange(settingId, value, helpers, items);
+      try {
+        options.afterPersist?.({ scope, cwd, settingId, value });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Saved setting, but live sync failed: ${message}`, { cause: error });
       }
     },
+  };
+}
+
+// ── Registration ───────────────────────────────────────────────────────────
+
+/**
+ * Register a config-backed 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 registerConfigSettings<T>(
+  pi: ExtensionAPI,
+  options: ConfigSettingsOptions<T>,
+): void {
+  const section = toSettingsSection(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-code-runtime/node_modules/@mrclrchtr/supi-core/src/config/config.ts

@@ -21,6 +21,15 @@ function getProjectConfigPath(cwd: string): string {
   return path.join(cwd, PROJECT_CONFIG_DIR, CONFIG_FILE);
 }
 
+/** Return the SuPi config file path for one scope. */
+export function getSupiConfigPath(
+  scope: "global" | "project",
+  cwd: string,
+  options?: SupiConfigOptions,
+): string {
+  return scope === "global" ? getGlobalConfigPath(options?.homeDir) : getProjectConfigPath(cwd);
+}
+
 export function readJsonFile(filePath: string): Record<string, unknown> | null {
   let content: string;
   try {
@@ -95,15 +104,22 @@ export function loadSupiConfigForScope<T>(
   defaults: T,
   options: { scope: "global" | "project" } & SupiConfigOptions,
 ): T {
-  const config =
-    options.scope === "global"
-      ? readJsonFile(getGlobalConfigPath(options.homeDir))
-      : readJsonFile(getProjectConfigPath(cwd));
+  const config = readJsonFile(getSupiConfigPath(options.scope, cwd, { homeDir: options.homeDir }));
 
   const scopedSection = extractSection(config, section);
   return shallowMerge(defaults, scopedSection);
 }
 
+/** Load the raw object for one config section and one scope. */
+export function loadSupiConfigSectionForScope(
+  section: string,
+  cwd: string,
+  options: { scope: "global" | "project" } & SupiConfigOptions,
+): Record<string, unknown> | null {
+  const config = readJsonFile(getSupiConfigPath(options.scope, cwd, { homeDir: options.homeDir }));
+  return extractSection(config, section);
+}
+
 export interface SupiConfigLocation {
   section: string;
   scope: "global" | "project";
@@ -118,8 +134,7 @@ export function writeSupiConfig(
   value: Record<string, unknown>,
   options?: SupiConfigOptions,
 ): void {
-  const configPath =
-    loc.scope === "global" ? getGlobalConfigPath(options?.homeDir) : getProjectConfigPath(loc.cwd);
+  const configPath = getSupiConfigPath(loc.scope, loc.cwd, options);
 
   const dir = path.dirname(configPath);
   fs.mkdirSync(dir, { recursive: true });
@@ -142,8 +157,7 @@ export function removeSupiConfigKey(
   key: string,
   options?: SupiConfigOptions,
 ): void {
-  const configPath =
-    loc.scope === "global" ? getGlobalConfigPath(options?.homeDir) : getProjectConfigPath(loc.cwd);
+  const configPath = getSupiConfigPath(loc.scope, loc.cwd, options);
 
   const existing = readJsonFile(configPath);
   if (!existing) return;