@mrclrchtr/supi-code-intelligence 1.3.1 → 1.4.0

package/README.md

@@ -1,59 +1,91 @@
 # @mrclrchtr/supi-code-intelligence
 
-Project understanding for PI — your agent knows your codebase before you ask.
+Adds a `code_intel` tool to the [pi coding agent](https://github.com/earendil-works/pi) for higher-level codebase analysis.
 
-The first thing an agent does in a new project is read files to figure out what's there. Code Intelligence skips that — it auto-injects a compact project map on turn one, so the agent is already oriented.
+## Install
+
+```bash
+pi install npm:@mrclrchtr/supi-code-intelligence
+```
 
-Beyond the overview, it gives the agent high-level analysis: architecture briefs, impact assessment, call tracing, and smart search that knows when to use LSP vs. tree-sitter vs. text search.
+For local development:
+
+```bash
+pi install ./packages/supi-code-intelligence
+```
+
+After editing the source, run `/reload`.
 
 ## What you get
 
-### Instant orientation
+After install, pi gets:
 
-Every session starts with a project map in the agent's context: what packages exist, how they depend on each other, which files matter. The agent walks in knowing your codebase instead of discovering it file by file.
+- `code_intel` — one tool with several analysis actions
+- a lightweight hidden architecture overview injected near the start of a session when a project model can be built
+- bundled support from `@mrclrchtr/supi-lsp`, `@mrclrchtr/supi-tree-sitter`, and `@mrclrchtr/supi-core`
 
-### Architecture-level questions
+This package is for questions like:
 
-Ask "what's in this package?" or "what depends on this module?" The agent gets a structural answer, not a file listing.
+- what is in this package or directory?
+- who calls this symbol?
+- what does this function call?
+- what is the likely blast radius of a change?
+- where is this pattern defined, imported, or exported?
 
-### Impact analysis
+## `code_intel` actions
 
-Before a change: "show me everything that would break." The agent sees direct callers, downstream dependents, and risk level — before touching code.
+| Action | What it is for |
+| --- | --- |
+| `brief` | Generate a project, package, directory, file, or symbol-focused brief |
+| `callers` | Find call sites for a symbol, or inspect a file's exported surface |
+| `callees` | Show outgoing calls from a symbol using structural analysis |
+| `implementations` | Find concrete implementations of an interface or abstract type |
+| `affected` | Estimate blast radius, affected files/modules, downstream dependents, and risk |
+| `pattern` | Run bounded text search with optional regex mode and structured `kind` filters |
+| `index` | Build a factual project map: counts, top-level tree, and landmark files |
 
-### Smarter search
+## Input shape
 
-`code_intel pattern` is text search that knows about code structure. Search for definitions (not just any text match), group by directory, or filter by import/export. Falls back from LSP to tree-sitter to ripgrep automatically.
+The tool accepts a shared parameter set across actions. The main fields are:
 
-## Install
+- `action`
+- `path`
+- `file`
+- `line`
+- `character`
+- `symbol`
+- `pattern`
+- `regex`
+- `kind`
+- `exportedOnly`
+- `maxResults`
+- `contextLines`
+- `summary`
 
-```bash
-pi install npm:@mrclrchtr/supi-code-intelligence
-```
+Notes from the current implementation:
 
-## Quick look
+- line and character positions are **1-based**
+- `line` and `character` require `file`, not `path`
+- `pattern` action `kind` must be `definition`, `export`, or `import`
+- a leading `@` is stripped from `path` and `file`
 
-| Action | What the agent can ask |
-|--------|----------------------|
-| `brief` | "Summarize this package / file / project" |
-| `callers` | "Who calls this function?" |
-| `callees` | "What does this function call?" |
-| `affected` | "What breaks if I change this?" |
-| `pattern` | "Find this text / pattern" |
-| `index` | "What's in this project?" |
-| `implementations` | "What implements this interface?" |
+## Result style
 
-Every result includes a confidence label (semantic / structural / heuristic) so the agent knows how much to trust the answer.
+Depending on the action and what supporting services are available, results report different confidence modes such as:
 
-## Package surfaces
+- `semantic`
+- `structural`
+- `heuristic`
+- `unavailable`
 
-- `@mrclrchtr/supi-code-intelligence/api` — reusable architecture/brief helpers
-- `@mrclrchtr/supi-code-intelligence/extension` — pi extension entrypoint
+That lets the model tell the difference between LSP-backed answers, tree-sitter-backed answers, and weaker text-search fallbacks.
 
-`pi.extensions` still points at the real file path `./src/extension.ts` inside the package. The `/api` and `/extension` paths are consumer-facing package exports, not manifest aliases.
+## Package surfaces
 
-## For extension developers
+- `@mrclrchtr/supi-code-intelligence/api` — reusable architecture, brief, and target-resolution helpers
+- `@mrclrchtr/supi-code-intelligence/extension` — pi extension entrypoint
 
-The architecture model and brief generator are exported for reuse:
+Example:
 
 ```ts
 import { buildArchitectureModel, generateOverview } from "@mrclrchtr/supi-code-intelligence/api";
@@ -61,3 +93,9 @@ import { buildArchitectureModel, generateOverview } from "@mrclrchtr/supi-code-i
 const model = await buildArchitectureModel("/project");
 const overview = generateOverview(model);
 ```
+
+## Source
+
+- `src/code-intelligence.ts` — tool registration and session overview injection
+- `src/tool-actions.ts` — action routing and parameter validation
+- `src/actions/*.ts` — per-action implementations

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

@@ -1,65 +1,78 @@
 # @mrclrchtr/supi-core
 
-Shared infrastructure for SuPi packages.
+Shared infrastructure for SuPi extensions.
+
+This package is mainly for extension authors. It gives you a common config system, settings plumbing, context helpers, registries, and a small extension surface that registers `/supi-settings`.
 
 ## Install
 
-Use it as a dependency in another extension package:
+### As a dependency for another extension
 
 ```bash
 pnpm add @mrclrchtr/supi-core
 ```
 
-## Package role
-
-`@mrclrchtr/supi-core` now has two explicit surfaces:
+### As a pi package
 
-- `@mrclrchtr/supi-core/api` — shared library helpers for other SuPi packages
-- `@mrclrchtr/supi-core/extension` — a minimal pi extension that registers `/supi-settings`
-
-`pi.extensions` still points at the real file path `./src/extension.ts` inside the package. The `/api` and `/extension` paths are consumer-facing package exports, not manifest aliases.
+```bash
+pi install npm:@mrclrchtr/supi-core
+```
 
-## What it provides
+Installing it as a pi package adds the minimal `/supi-settings` extension surface.
 
-Current exports cover:
+## Package surfaces
 
-- 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`
+- `@mrclrchtr/supi-core/api` — reusable helpers for other packages and extensions
+- `@mrclrchtr/supi-core/extension` — minimal pi extension that registers `/supi-settings`
 
-## Config system
+## What you get from the API
 
-Config resolution order:
+### Config helpers
 
-```text
-defaults <- global <- project
-```
+- `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`
 
-Main helpers:
+### 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:
 
-- `loadSupiConfig()` — effective merged config (`defaults <- global <- project`)
-- `loadSupiConfigForScope()` — raw single-scope config for settings UIs (`defaults <- selected scope`)
-- `writeSupiConfig()`
-- `removeSupiConfigKey()`
-- `registerConfigSettings()`
+- project/global scope toggle
+- grouped extension sections
+- searchable setting lists
 
-## Context and settings helpers
+### Context helpers
 
-- `wrapExtensionContext()`
+- `wrapExtensionContext()` — wrap injected text in SuPi's `<extension-context>` tag
 - `findLastUserMessageIndex()`
 - `getContextToken()`
+- `getPromptContent()`
 - `pruneAndReorderContextMessages()`
-- `registerSettings()`
-- `registerSettingsCommand()`
-- `openSettingsOverlay()`
+- `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
 
@@ -80,17 +93,15 @@ registerConfigSettings({
 });
 
 const message = wrapExtensionContext("my-extension", "hello", {
-  turn: 1,
   file: "CLAUDE.md",
+  turn: 1,
 });
 ```
 
-## Requirements
-
-- `@earendil-works/pi-coding-agent`
-- `@earendil-works/pi-tui`
-
 ## Source
 
-- Library surface: `src/api.ts`
-- Extension surface: `src/extension.ts`
+- `src/api.ts` — exported library surface
+- `src/extension.ts` — minimal `/supi-settings` entrypoint
+- `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

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
   "license": "MIT",
   "repository": {

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

@@ -2,30 +2,30 @@
 // Provides XML context tag wrapping, unified config system, context-message utilities,
 // and settings registry for supi-wide TUI settings.
 
-export type { SupiConfigLocation, SupiConfigOptions } from "./config.ts";
+export type { SupiConfigLocation, SupiConfigOptions } from "./config/config.ts";
 export {
   loadSupiConfig,
   loadSupiConfigForScope,
   removeSupiConfigKey,
   writeSupiConfig,
-} from "./config.ts";
-export type { ConfigSettingsHelpers, ConfigSettingsOptions } from "./config-settings.ts";
-export { registerConfigSettings } from "./config-settings.ts";
-export type { ContextMessageLike } from "./context-messages.ts";
+} from "./config/config.ts";
+export type { ConfigSettingsHelpers, ConfigSettingsOptions } from "./config/config-settings.ts";
+export { registerConfigSettings } from "./config/config-settings.ts";
+export type { ContextMessageLike } from "./context/context-messages.ts";
 export {
   findLastUserMessageIndex,
   getContextToken,
   getPromptContent,
   pruneAndReorderContextMessages,
   restorePromptContent,
-} from "./context-messages.ts";
-export type { ContextProvider } from "./context-provider-registry.ts";
+} from "./context/context-messages.ts";
+export type { ContextProvider } from "./context/context-provider-registry.ts";
 export {
   clearRegisteredContextProviders,
   getRegisteredContextProviders,
   registerContextProvider,
-} from "./context-provider-registry.ts";
-export { wrapExtensionContext } from "./context-tag.ts";
+} from "./context/context-provider-registry.ts";
+export { wrapExtensionContext } from "./context/context-tag.ts";
 export type {
   DebugAgentAccess,
   DebugEvent,
@@ -64,14 +64,14 @@ export {
   walkProject,
 } from "./project-roots.ts";
 export { getActiveBranchEntries } from "./session-utils.ts";
-export { registerSettingsCommand } from "./settings-command.ts";
-export type { SettingsScope, SettingsSection } from "./settings-registry.ts";
+export { registerSettingsCommand } from "./settings/settings-command.ts";
+export type { SettingsScope, SettingsSection } from "./settings/settings-registry.ts";
 export {
   clearRegisteredSettings,
   getRegisteredSettings,
   registerSettings,
-} from "./settings-registry.ts";
-export { createInputSubmenu, openSettingsOverlay } from "./settings-ui.ts";
+} from "./settings/settings-registry.ts";
+export { createInputSubmenu, openSettingsOverlay } from "./settings/settings-ui.ts";
 export type { TitleTarget } from "./terminal.ts";
 export {
   DONE_SYMBOL,

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

@@ -2,9 +2,9 @@
 // Wraps registerSettings() and centralizes selected-scope loading + scoped persistence.
 
 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";
-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. */

package/node_modules/@mrclrchtr/{supi-lsp/node_modules/@mrclrchtr/supi-core/src → supi-core/src/context}/context-provider-registry.ts

@@ -3,7 +3,7 @@
 // Extensions declare context data providers via `registerContextProvider()` during their
 // factory function. The `/supi-context` command reads them via `getRegisteredContextProviders()`.
 
-import { createRegistry } from "./registry-utils.ts";
+import { createRegistry } from "../registry-utils.ts";
 
 export interface ContextProvider {
   /** Unique identifier — e.g. "rtk" */

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

@@ -1 +1 @@
-export { registerSettingsCommand as default } from "./settings-command.ts";
+export { registerSettingsCommand as default } from "./settings/settings-command.ts";

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

@@ -2,30 +2,30 @@
 // Provides XML context tag wrapping, unified config system, context-message utilities,
 // and settings registry for supi-wide TUI settings.
 
-export type { SupiConfigLocation, SupiConfigOptions } from "./config.ts";
+export type { SupiConfigLocation, SupiConfigOptions } from "./config/config.ts";
 export {
   loadSupiConfig,
   loadSupiConfigForScope,
   removeSupiConfigKey,
   writeSupiConfig,
-} from "./config.ts";
-export type { ConfigSettingsHelpers, ConfigSettingsOptions } from "./config-settings.ts";
-export { registerConfigSettings } from "./config-settings.ts";
-export type { ContextMessageLike } from "./context-messages.ts";
+} from "./config/config.ts";
+export type { ConfigSettingsHelpers, ConfigSettingsOptions } from "./config/config-settings.ts";
+export { registerConfigSettings } from "./config/config-settings.ts";
+export type { ContextMessageLike } from "./context/context-messages.ts";
 export {
   findLastUserMessageIndex,
   getContextToken,
   getPromptContent,
   pruneAndReorderContextMessages,
   restorePromptContent,
-} from "./context-messages.ts";
-export type { ContextProvider } from "./context-provider-registry.ts";
+} from "./context/context-messages.ts";
+export type { ContextProvider } from "./context/context-provider-registry.ts";
 export {
   clearRegisteredContextProviders,
   getRegisteredContextProviders,
   registerContextProvider,
-} from "./context-provider-registry.ts";
-export { wrapExtensionContext } from "./context-tag.ts";
+} from "./context/context-provider-registry.ts";
+export { wrapExtensionContext } from "./context/context-tag.ts";
 export type {
   DebugAgentAccess,
   DebugEvent,
@@ -64,14 +64,14 @@ export {
   walkProject,
 } from "./project-roots.ts";
 export { getActiveBranchEntries } from "./session-utils.ts";
-export { registerSettingsCommand } from "./settings-command.ts";
-export type { SettingsScope, SettingsSection } from "./settings-registry.ts";
+export { registerSettingsCommand } from "./settings/settings-command.ts";
+export type { SettingsScope, SettingsSection } from "./settings/settings-registry.ts";
 export {
   clearRegisteredSettings,
   getRegisteredSettings,
   registerSettings,
-} from "./settings-registry.ts";
-export { createInputSubmenu, openSettingsOverlay } from "./settings-ui.ts";
+} from "./settings/settings-registry.ts";
+export { createInputSubmenu, openSettingsOverlay } from "./settings/settings-ui.ts";
 export type { TitleTarget } from "./terminal.ts";
 export {
   DONE_SYMBOL,

package/node_modules/@mrclrchtr/{supi-lsp/node_modules/@mrclrchtr/supi-core/src → supi-core/src/settings}/settings-registry.ts

@@ -4,7 +4,7 @@
 // factory function. The generic settings UI reads them via `getRegisteredSettings()`.
 
 import type { SettingItem } from "@earendil-works/pi-tui";
-import { createRegistry } from "./registry-utils.ts";
+import { createRegistry } from "../registry-utils.ts";
 
 export type SettingsScope = "project" | "global";
 

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

@@ -1,71 +1,90 @@
 # @mrclrchtr/supi-lsp
 
-Language Server Protocol for PI — your agent navigates code like an IDE.
+Adds Language Server Protocol support to the [pi coding agent](https://github.com/earendil-works/pi).
 
-Without LSP, agents grep and guess. With it, they jump to definitions, find every reference, rename across files, and catch type errors inline. The same precision you get from an editor, available to your agent.
+## Install
 
-## What you get
+```bash
+pi install npm:@mrclrchtr/supi-lsp
+```
 
-### Navigate with precision
+For local development:
 
-Go-to-definition, find-references, rename, hover types. The agent stops guessing and starts navigating your codebase with IDE-level accuracy.
+```bash
+pi install ./packages/supi-lsp
+```
 
-### Catch problems immediately
+After editing the source, run `/reload`.
 
-Type errors, warnings, and hints surface inline after every edit. The agent sees mistakes as it makes them — not 10 turns later when tests fail.
+## What you get
 
-### Always ready
+After install, pi gets:
 
-Servers start automatically for your project. The agent gets language-aware guidance at session start and stale diagnostics are refreshed when dependencies change.
+- `lsp_lookup` — semantic hover, definition, references, and implementation at a known position
+- `lsp_document_symbols` — semantic declarations for one supported file
+- `lsp_workspace_symbols` — semantic symbol-name lookup across the project
+- `lsp_diagnostics` — current diagnostics for one file or a workspace summary
+- `lsp_refactor` — semantic rename planning and code actions at a known position
+- `lsp_recover` — refresh stale diagnostics after workspace changes
+- `/lsp-status` — inspect detected servers, roots, open files, and diagnostics
+- automatic LSP-aware diagnostic surfacing around edits and agent turns
 
-## Install
+Coordinates use **1-based** line and character positions.
 
-```bash
-pi install npm:@mrclrchtr/supi-lsp
-```
+## Automatic behavior
 
-## Quick look
+This package does more than register a tool:
 
-The agent gets an `lsp` tool. The most-used actions:
+- starts detected language servers for the current project
+- rebuilds project-specific prompt guidance based on active servers
+- injects outstanding diagnostics into context before agent turns when issues exist
+- adds inline diagnostics after `write` and `edit` results
+- watches for workspace changes such as `package.json`, lockfile, `tsconfig`, generated types, and source-file edits so recovery can happen when diagnostics go stale
+- warns when configured language-server commands are missing
 
-| Action | What the agent can do |
-|--------|----------------------|
-| `hover` | See the type of any symbol |
-| `definition` | Jump to where something is defined |
-| `references` | Find every usage across the project |
-| `diagnostics` | See errors, warnings, and hints |
-| `rename` | Rename across the entire project |
+## Settings
 
-Full action reference: the agent's system prompt includes complete guidelines for all 11 actions (hover, definition, references, diagnostics, symbols, rename, code_actions, workspace_symbol, search, symbol_hover, recover). All positions are 1-based.
+This package registers an **LSP** section in `/supi-settings`.
 
-## Settings
+Available settings:
 
-Configure via `/supi-settings` (LSP panel):
+- `enabled` — turn all LSP behavior on or off
+- `severity` — inline diagnostic threshold: `1` errors, `2` warnings, `3` info, `4` hints
+- `active` — choose which configured language servers are active; empty means all
+- `exclude` — gitignore-style patterns that suppress diagnostics for matching files
 
-- Enable or disable LSP per project
-- Set diagnostic severity threshold (errors only, or include warnings/hints)
-- Choose which language servers to activate
-- Add file exclusion patterns (gitignore-style globs)
+Config lives in the standard SuPi config files:
 
-Settings are stored in `~/.pi/agent/supi/config.json` (global) or `.pi/supi/config.json` (project). The `/lsp-status` command shows active servers and outstanding diagnostics.
+- global: `~/.pi/agent/supi/config.json`
+- project: `.pi/supi/config.json`
 
 ## Package surfaces
 
-- `@mrclrchtr/supi-lsp/api` — reusable library surface for peer extensions
+- `@mrclrchtr/supi-lsp/api` — reusable session-scoped LSP service and related types
 - `@mrclrchtr/supi-lsp/extension` — pi extension entrypoint
 
-`pi.extensions` still points at the real file path `./src/extension.ts` inside the package. The `/api` and `/extension` paths are consumer-facing package exports, not manifest aliases.
-
-## For extension developers
-
-This package exports a reusable session-scoped LSP service. Peer extensions can query the same LSP runtime without starting duplicate servers:
+Example:
 
 ```ts
-import { getSessionLspService, SessionLspService } from "@mrclrchtr/supi-lsp/api";
+import { getSessionLspService, toLspPosition } from "@mrclrchtr/supi-lsp/api";
 
 const state = getSessionLspService("/project");
 if (state.kind === "ready") {
-  const defs = await state.service.definition("src/index.ts", { line: 5, character: 10 });
-  const refs = await state.service.references("src/index.ts", { line: 5, character: 10 });
+  const defs = await state.service.definition("src/index.ts", toLspPosition(6, 11));
 }
 ```
+
+`SessionLspService` methods use raw **0-based LSP positions**. The expert tools (`lsp_lookup`, `lsp_refactor`, etc.) keep the public 1-based coordinate UX.
+
+## Source
+
+- `src/lsp.ts` — extension wiring, session lifecycle, and `/lsp-status`
+- `src/config/` — server config, defaults, capabilities, and exported LSP protocol types
+- `src/session/` — session state, scanning, settings registration, tree persistence, and shared service registry
+- `src/tool/register-tools.ts` — expert tool registration for the split LSP toolset
+- `src/tool/service-actions.ts` — service-backed tool execution and formatting
+- `src/tool/guidance.ts` / `src/tool/names.ts` — prompt surfaces and stable tool names
+- `src/tool/overrides.ts` — read/write/edit overrides for inline diagnostics
+- `src/ui/` — custom diagnostic message rendering and the status overlay
+- `src/client/`, `src/manager/`, `src/diagnostics/` — runtime engine subsystems
+- `src/api.ts` — reusable developer-facing surface