@mrclrchtr/supi-tree-sitter 1.7.0 → 1.8.0

package/README.md

@@ -1,6 +1,6 @@
 # @mrclrchtr/supi-tree-sitter
 
-Adds a `tree_sitter` tool to the [pi coding agent](https://github.com/earendil-works/pi) for parser-based structural code analysis.
+Adds focused structural code analysis tools to the [pi coding agent](https://github.com/earendil-works/pi) using Tree-sitter parsers.
 
 ## Install
 
@@ -18,27 +18,35 @@ After editing the source, run `/reload`.
 
 ## What you get
 
-After install, pi gets one tool:
+After install, pi gets **6 focused tools** for parser-based structural analysis:
 
-- `tree_sitter` — inspect code structure through Tree-sitter parsers instead of plain text search
+- `tree_sitter_outline` — shallow structural outline of declarations in JavaScript/TypeScript files
+- `tree_sitter_imports` — list imports in JavaScript/TypeScript files
+- `tree_sitter_exports` — list exports in JavaScript/TypeScript files
+- `tree_sitter_node_at` — find the exact syntax node and ancestry at a position (any supported grammar)
+- `tree_sitter_query` — run a custom Tree-sitter query against a file (any supported grammar)
+- `tree_sitter_callees` — find outgoing calls from the enclosing function or method at a position (most grammars)
 
-## `tree_sitter` actions
+### Outline, imports, exports
 
-| Action | What it is for | Current language coverage |
-| --- | --- | --- |
-| `outline` | List structural declarations such as functions, classes, interfaces, and methods | JavaScript / TypeScript only |
-| `imports` | List import statements | JavaScript / TypeScript only |
-| `exports` | List export declarations, re-exports, and export assignments | JavaScript / TypeScript only |
-| `node_at` | Show the syntax node at a position, including ancestry | Any supported grammar |
-| `query` | Run a custom Tree-sitter query against a file | Any supported grammar |
-| `callees` | Find outgoing calls from the enclosing function or method at a position | Supported for most grammars, but not all |
+These three tools work on JavaScript, TypeScript, JSX, and TSX files. They provide parser-level structural information without needing a language server:
+
+- `tree_sitter_outline` — top-level declarations plus class/interface/enum members
+- `tree_sitter_imports` — module specifiers and source locations for each import
+- `tree_sitter_exports` — kind, name, and module specifier (for re-exports) of each export
+
+### Node-at, query, callees
+
+These tools work across all or most supported grammars:
+
+- `tree_sitter_node_at` — exact syntax node type and ancestry at a given file position
+- `tree_sitter_query` — custom Tree-sitter query pattern matching on any supported grammar
+- `tree_sitter_callees` — outgoing calls from the enclosing function or method at a given position
 
 Coordinates use **1-based** line and character columns. Character positions use UTF-16 code units. Relative paths resolve from the session cwd, and a leading `@` on file paths is stripped.
 
 ## Supported file families
 
-The current tool description covers:
-
 - JavaScript / TypeScript (`.js`, `.jsx`, `.ts`, `.tsx`, `.mjs`, `.cjs`, `.mts`, `.cts`)
 - Python (`.py`, `.pyi`)
 - Rust (`.rs`)
@@ -84,7 +92,10 @@ if (state.kind === "ready") {
 
 ## Source
 
-- `src/tree-sitter.ts` — tool registration and action handling
+- `src/tool/tool-specs.ts` — single source of truth for the public tool surface
+- `src/tool/guidance.ts` — prompt surfaces derived from tool specs
+- `src/tool/register-tools.ts` — focused tool registration driven by tool specs
+- `src/tree-sitter.ts` — extension entrypoint (thin wire-up)
 - `src/session/runtime.ts` — parser and query runtime
 - `src/session/session.ts` — runtime-backed service helpers and owned session API
 - `src/session/service-registry.ts` — shared session-scoped structural service registry

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

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
   "license": "MIT",
   "repository": {
@@ -37,8 +37,19 @@
   "main": "src/api.ts",
   "exports": {
     "./api": "./src/api.ts",
+    "./config": "./src/config.ts",
+    "./context": "./src/context.ts",
+    "./debug": "./src/debug-registry.ts",
     "./extension": "./src/extension.ts",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./path": "./src/path.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"
   },
   "pi": {
     "extensions": [

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

@@ -1,96 +1,30 @@
 // 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).
 
-export type { SupiConfigLocation, SupiConfigOptions } from "./config/config.ts";
-export {
-  loadSupiConfig,
-  loadSupiConfigForScope,
-  readJsonFile,
-  removeSupiConfigKey,
-  writeSupiConfig,
-} 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/context-messages.ts";
-export type { ContextProvider } from "./context/context-provider-registry.ts";
-export {
-  clearRegisteredContextProviders,
-  getRegisteredContextProviders,
-  registerContextProvider,
-} from "./context/context-provider-registry.ts";
-export { wrapExtensionContext } from "./context/context-tag.ts";
-export type {
-  DebugAgentAccess,
-  DebugEvent,
-  DebugEventInput,
-  DebugEventQuery,
-  DebugEventQueryResult,
-  DebugEventView,
-  DebugLevel,
-  DebugNotifyLevel,
-  DebugRegistryConfig,
-  DebugSummary,
-} from "./debug-registry.ts";
-export {
-  clearDebugEvents,
-  configureDebugRegistry,
-  DEBUG_REGISTRY_DEFAULTS,
-  getDebugEvents,
-  getDebugRegistryConfig,
-  getDebugSummary,
-  recordDebugEvent,
-  redactDebugData,
-  resetDebugRegistry,
-} from "./debug-registry.ts";
-export { fileToUri, resolveToolPath, stripToolPathPrefix, uriToFile } from "./path-utils.ts";
-export type { KnownRootEntry } from "./project-roots.ts";
-export {
-  buildKnownRootsMap,
-  byPathDepth,
-  dedupeTopmostRoots,
-  findProjectRoot,
-  isWithin,
-  isWithinOrEqual,
-  mergeKnownRoots,
-  resolveKnownRoot,
-  segmentCount,
-  sortRootsBySpecificity,
-  walkProject,
-} from "./project-roots.ts";
-export { createRegistry, createSessionStateRegistry } from "./registry-utils.ts";
-export { getActiveBranchEntries } from "./session-utils.ts";
-export { registerSettingsCommand } from "./settings/settings-command.ts";
-export type { SettingsScope, SettingsSection } from "./settings/settings-registry.ts";
-export {
-  clearRegisteredSettings,
-  getRegisteredSettings,
-  registerSettings,
-} from "./settings/settings-registry.ts";
-export { createInputSubmenu, openSettingsOverlay } from "./settings/settings-ui.ts";
-export type { TitleTarget } from "./terminal.ts";
-export {
-  DONE_SYMBOL,
-  formatTitle,
-  signalBell,
-  signalDone,
-  signalWaiting,
-  WAITING_SYMBOL,
-} from "./terminal.ts";
-export type { SuiPiToolPromptSurface, SuiPiToolSpec, ToolExecuteFn } from "./tool-framework.ts";
-export {
-  CharacterParam,
-  derivePromptSurface,
-  FileParam,
-  LineParam,
-  MaxResultsParam,
-  registerSuiPiTools,
-  SymbolParam,
-} from "./tool-framework.ts";
+// 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 "./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.ts

@@ -0,0 +1,11 @@
+// supi-core config domain — config loading and config-settings helpers.
+export type { SupiConfigLocation, SupiConfigOptions } from "./config/config.ts";
+export {
+  loadSupiConfig,
+  loadSupiConfigForScope,
+  readJsonFile,
+  removeSupiConfigKey,
+  writeSupiConfig,
+} from "./config/config.ts";
+export type { ConfigSettingsHelpers, ConfigSettingsOptions } from "./config/config-settings.ts";
+export { registerConfigSettings } from "./config/config-settings.ts";

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

@@ -0,0 +1,16 @@
+// supi-core context domain — context messages, providers, and XML tags.
+export type { ContextMessageLike } from "./context/context-messages.ts";
+export {
+  findLastUserMessageIndex,
+  getContextToken,
+  getPromptContent,
+  pruneAndReorderContextMessages,
+  restorePromptContent,
+} from "./context/context-messages.ts";
+export type { ContextProvider } from "./context/context-provider-registry.ts";
+export {
+  clearRegisteredContextProviders,
+  getRegisteredContextProviders,
+  registerContextProvider,
+} from "./context/context-provider-registry.ts";
+export { wrapExtensionContext } from "./context/context-tag.ts";

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

@@ -1,96 +1,30 @@
 // 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).
 
-export type { SupiConfigLocation, SupiConfigOptions } from "./config/config.ts";
-export {
-  loadSupiConfig,
-  loadSupiConfigForScope,
-  readJsonFile,
-  removeSupiConfigKey,
-  writeSupiConfig,
-} 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/context-messages.ts";
-export type { ContextProvider } from "./context/context-provider-registry.ts";
-export {
-  clearRegisteredContextProviders,
-  getRegisteredContextProviders,
-  registerContextProvider,
-} from "./context/context-provider-registry.ts";
-export { wrapExtensionContext } from "./context/context-tag.ts";
-export type {
-  DebugAgentAccess,
-  DebugEvent,
-  DebugEventInput,
-  DebugEventQuery,
-  DebugEventQueryResult,
-  DebugEventView,
-  DebugLevel,
-  DebugNotifyLevel,
-  DebugRegistryConfig,
-  DebugSummary,
-} from "./debug-registry.ts";
-export {
-  clearDebugEvents,
-  configureDebugRegistry,
-  DEBUG_REGISTRY_DEFAULTS,
-  getDebugEvents,
-  getDebugRegistryConfig,
-  getDebugSummary,
-  recordDebugEvent,
-  redactDebugData,
-  resetDebugRegistry,
-} from "./debug-registry.ts";
-export { fileToUri, resolveToolPath, stripToolPathPrefix, uriToFile } from "./path-utils.ts";
-export type { KnownRootEntry } from "./project-roots.ts";
-export {
-  buildKnownRootsMap,
-  byPathDepth,
-  dedupeTopmostRoots,
-  findProjectRoot,
-  isWithin,
-  isWithinOrEqual,
-  mergeKnownRoots,
-  resolveKnownRoot,
-  segmentCount,
-  sortRootsBySpecificity,
-  walkProject,
-} from "./project-roots.ts";
-export { createRegistry, createSessionStateRegistry } from "./registry-utils.ts";
-export { getActiveBranchEntries } from "./session-utils.ts";
-export { registerSettingsCommand } from "./settings/settings-command.ts";
-export type { SettingsScope, SettingsSection } from "./settings/settings-registry.ts";
-export {
-  clearRegisteredSettings,
-  getRegisteredSettings,
-  registerSettings,
-} from "./settings/settings-registry.ts";
-export { createInputSubmenu, openSettingsOverlay } from "./settings/settings-ui.ts";
-export type { TitleTarget } from "./terminal.ts";
-export {
-  DONE_SYMBOL,
-  formatTitle,
-  signalBell,
-  signalDone,
-  signalWaiting,
-  WAITING_SYMBOL,
-} from "./terminal.ts";
-export type { SuiPiToolPromptSurface, SuiPiToolSpec, ToolExecuteFn } from "./tool-framework.ts";
-export {
-  CharacterParam,
-  derivePromptSurface,
-  FileParam,
-  LineParam,
-  MaxResultsParam,
-  registerSuiPiTools,
-  SymbolParam,
-} from "./tool-framework.ts";
+// 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 "./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/path.ts

@@ -0,0 +1,2 @@
+// supi-core path domain — file and URI path utilities.
+export { fileToUri, resolveToolPath, stripToolPathPrefix, uriToFile } from "./path-utils.ts";

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

@@ -0,0 +1,15 @@
+// supi-core project domain — project root discovery and traversal.
+export type { KnownRootEntry } from "./project-roots.ts";
+export {
+  buildKnownRootsMap,
+  byPathDepth,
+  dedupeTopmostRoots,
+  findProjectRoot,
+  isWithin,
+  isWithinOrEqual,
+  mergeKnownRoots,
+  resolveKnownRoot,
+  segmentCount,
+  sortRootsBySpecificity,
+  walkProject,
+} from "./project-roots.ts";

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

@@ -0,0 +1,4 @@
+// supi-core session domain — session utilities and registries.
+
+export { createRegistry, createSessionStateRegistry } from "./registry-utils.ts";
+export { getActiveBranchEntries } from "./session-utils.ts";

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

@@ -0,0 +1,2 @@
+// supi-core settings-ui domain — settings TUI components (imports pi-tui at runtime, heavy).
+export { createInputSubmenu, openSettingsOverlay } from "./settings/settings-ui.ts";

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

@@ -0,0 +1,9 @@
+// supi-core settings domain — settings registry (lightweight, type-only pi-tui import).
+
+export { registerSettingsCommand } from "./settings/settings-command.ts";
+export type { SettingsScope, SettingsSection } from "./settings/settings-registry.ts";
+export {
+  clearRegisteredSettings,
+  getRegisteredSettings,
+  registerSettings,
+} from "./settings/settings-registry.ts";

package/node_modules/@mrclrchtr/supi-core/src/substrate-types.ts

@@ -0,0 +1,11 @@
+/** 0-based position used by LSP and code-intelligence internally. */
+export interface CodePosition {
+  line: number;
+  character: number;
+}
+
+/** Normalized location — flat replacement for LSP's nested Location/range shape. */
+export interface CodeLocation {
+  uri: string;
+  range: { start: CodePosition; end: CodePosition };
+}

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

@@ -0,0 +1,2 @@
+// supi-core types domain — shared substrate types (zero dependencies, pure types).
+export type { CodeLocation, CodePosition } from "./substrate-types.ts";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-tree-sitter",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "SuPi Tree-sitter extension — structural AST analysis for pi",
   "license": "MIT",
   "repository": {
@@ -24,7 +24,7 @@
   ],
   "dependencies": {
     "web-tree-sitter": "^0.26.8",
-    "@mrclrchtr/supi-core": "1.7.0"
+    "@mrclrchtr/supi-core": "1.8.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",

package/src/session/runtime.ts

@@ -2,7 +2,7 @@
 
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { resolveToolPath } from "@mrclrchtr/supi-core/api";
+import { resolveToolPath } from "@mrclrchtr/supi-core/path";
 import type { Language, Parser, Tree } from "web-tree-sitter";
 import { nodeToRange } from "../coordinates.ts";
 import { detectGrammar, resolveGrammarWasmPath } from "../language.ts";

package/src/session/service-registry.ts

@@ -2,7 +2,7 @@
 // Peer extensions can import `getSessionTreeSitterService` from the package API
 // to reuse the active structural runtime without creating duplicate sessions.
 
-import { createSessionStateRegistry } from "@mrclrchtr/supi-core/api";
+import { createSessionStateRegistry } from "@mrclrchtr/supi-core/session";
 import type { SessionTreeSitterService, SessionTreeSitterServiceState } from "../types.ts";
 
 const registry = createSessionStateRegistry<SessionTreeSitterServiceState>(

package/src/tool/guidance.ts

@@ -1,31 +1,35 @@
-// Prompt guidance and tool description for the tree_sitter tool.
+// Guidance surfaces for the focused tree_sitter_* tool set.
 //
-// Note: We intentionally do NOT include cross-tool routing (e.g., "use lsp for
-// type info") because this package can be installed standalone without supi-lsp.
+// Derives from tool-specs.ts so prompt surfaces stay in sync with
+// the public tool metadata.
 
-import {
-  formatTreeSitterActionList,
-  getTreeSitterActionNamesByGuidanceGroup,
-} from "./action-specs.ts";
+import { TREE_SITTER_TOOL_SPECS, type TreeSitterToolName } from "./tool-specs.ts";
 
-const jsTsStructureActions = getTreeSitterActionNamesByGuidanceGroup("js-ts-structure")
-  .map((action) => `tree_sitter.${action}(file)`)
-  .join(", ");
+export interface TreeSitterToolPromptSurface {
+  description: string;
+  promptSnippet: string;
+  promptGuidelines: string[];
+}
 
-export const toolDescription = `Tree-sitter tool — parser-level structure and syntax queries for supported files.
+export type TreeSitterToolPromptSurfaceMap = Record<
+  TreeSitterToolName,
+  TreeSitterToolPromptSurface
+>;
 
-Actions: ${formatTreeSitterActionList()}.
+const _DEFAULT_SURFACES = buildTreeSitterToolPromptSurfaces();
 
-Use tree_sitter for exact syntax nodes, shallow structure, parsed imports/exports, outgoing calls, or custom AST queries within one file. file is required for all actions. line and character are 1-based UTF-16 coordinates for node_at and callees. query is required for query. outline, imports, and exports are JavaScript/TypeScript-only; node_at and query work across supported grammars; callees works for many grammars. Relative paths resolve from the session working directory, and a leading @ on file paths is stripped.`;
-
-export const promptGuidelines = [
-  `Use ${jsTsStructureActions} for shallow JavaScript or TypeScript structure without reading the whole file.`,
-  "Use tree_sitter.node_at(file, line, character) for the exact syntax node and ancestry at a known position.",
-  "Use tree_sitter.callees(file, line, character) for outgoing calls from the enclosing function or method at a known position.",
-  "Use tree_sitter.query(file, query) for custom Tree-sitter patterns when the built-in actions are not specific enough.",
-  "Use tree_sitter for syntax, node types, source ranges, and other parser-backed structure within one supported file.",
-  "Do not use tree_sitter for type information, cross-file references, semantic renames, or codebase-wide orientation.",
-];
-
-export const promptSnippet =
-  "tree_sitter — parser-backed single-file structure, node lookup, callees, and AST queries";
+/**
+ * Build the full prompt-surface map for all 6 tree_sitter_* tools.
+ */
+export function buildTreeSitterToolPromptSurfaces(): TreeSitterToolPromptSurfaceMap {
+  return Object.fromEntries(
+    TREE_SITTER_TOOL_SPECS.map((spec) => [
+      spec.name,
+      {
+        description: spec.description,
+        promptSnippet: spec.promptSnippet,
+        promptGuidelines: [...spec.promptGuidelines],
+      } satisfies TreeSitterToolPromptSurface,
+    ]),
+  ) as TreeSitterToolPromptSurfaceMap;
+}