@mrclrchtr/supi-tree-sitter 1.4.0 → 1.5.0

package/README.md

@@ -33,7 +33,7 @@ After install, pi gets one tool:
 | `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 |
 
-Coordinates use **1-based** line and character columns. Character positions use UTF-16 code units.
+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
 
@@ -54,10 +54,10 @@ The current tool description covers:
 
 ## Package surfaces
 
-- `@mrclrchtr/supi-tree-sitter/api` — reusable parsing session factory and shared result types
+- `@mrclrchtr/supi-tree-sitter/api` — reusable parsing session factory, shared session-scoped structural service access, and shared result types
 - `@mrclrchtr/supi-tree-sitter/extension` — pi extension entrypoint
 
-Example:
+Owned session example:
 
 ```ts
 import { createTreeSitterSession } from "@mrclrchtr/supi-tree-sitter/api";
@@ -71,9 +71,21 @@ const callees = await session.calleesAt("src/index.ts", 42, 10);
 session.dispose();
 ```
 
+Shared session-scoped service example:
+
+```ts
+import { getSessionTreeSitterService } from "@mrclrchtr/supi-tree-sitter/api";
+
+const state = getSessionTreeSitterService("/project");
+if (state.kind === "ready") {
+  const outline = await state.service.outline("src/index.ts");
+}
+```
+
 ## Source
 
 - `src/tree-sitter.ts` — tool registration and action handling
-- `src/runtime.ts` — parser and query runtime
-- `src/session.ts` — reusable session API
-- `src/outline.ts`, `src/imports.ts`, `src/exports.ts`, `src/node-at.ts`, `src/callees.ts` — structural analyses
+- `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
+- `src/tool/outline.ts`, `src/tool/imports.ts`, `src/tool/exports.ts`, `src/tool/node-at.ts`, `src/tool/callees.ts` — structural analyses

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

@@ -0,0 +1,107 @@
+# @mrclrchtr/supi-core
+
+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
+
+### As a dependency for another extension
+
+```bash
+pnpm add @mrclrchtr/supi-core
+```
+
+### As a pi package
+
+```bash
+pi install npm:@mrclrchtr/supi-core
+```
+
+Installing it as a pi package adds the minimal `/supi-settings` extension surface.
+
+## Package surfaces
+
+- `@mrclrchtr/supi-core/api` — reusable helpers for other packages and extensions
+- `@mrclrchtr/supi-core/extension` — minimal pi extension that registers `/supi-settings`
+
+## 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/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

@@ -0,0 +1,44 @@
+{
+  "name": "@mrclrchtr/supi-core",
+  "version": "1.5.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": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    }
+  },
+  "main": "src/api.ts",
+  "exports": {
+    "./api": "./src/api.ts",
+    "./extension": "./src/extension.ts",
+    "./package.json": "./package.json"
+  },
+  "pi": {
+    "extensions": [
+      "./src/extension.ts"
+    ]
+  }
+}

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

@@ -0,0 +1,85 @@
+// supi-core — shared infrastructure for SuPi extensions.
+// 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/config.ts";
+export {
+  loadSupiConfig,
+  loadSupiConfigForScope,
+  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";

package/node_modules/@mrclrchtr/supi-core/src/config/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 type { SettingsScope } from "../settings/settings-registry.ts";
+import { registerSettings } from "../settings/settings-registry.ts";
+import { loadSupiConfigForScope, removeSupiConfigKey, writeSupiConfig } from "./config.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/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;
+}

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

@@ -0,0 +1,119 @@
+// Shared context-message utilities for SuPi extensions.
+//
+// Provides a generic prune-and-reorder pattern for extensions that inject
+// managed context messages (via `before_agent_start` with a `customType` and
+// `contextToken`) and maintain them via the `context` event.
+
+/**
+ * Minimal message shape needed for context-message operations.
+ * Extensions cast their event.messages entries to this type.
+ */
+export type ContextMessageLike = {
+  role?: string;
+  customType?: string;
+  content?: unknown;
+  details?: unknown;
+};
+
+/**
+ * Extract the `contextToken` string from a message's `details` object.
+ * Returns `null` when the token is absent or not a string.
+ */
+export function getContextToken(details: unknown): string | null {
+  if (!details || typeof details !== "object") return null;
+  const token = (details as { contextToken?: unknown }).contextToken;
+  return typeof token === "string" ? token : null;
+}
+
+/**
+ * Find the index of the last message with `role: "user"`.
+ * Returns `-1` when no user message exists.
+ */
+export function findLastUserMessageIndex<T extends ContextMessageLike>(messages: T[]): number {
+  for (let index = messages.length - 1; index >= 0; index--) {
+    if (messages[index]?.role === "user") return index;
+  }
+  return -1;
+}
+
+/**
+ * Filter stale context messages and reorder the active one before the last user message.
+ *
+ * - Removes all messages matching `customType` whose token differs from `activeToken`.
+ * - When `activeToken` is `null`, removes **all** messages of that `customType`.
+ * - If the active context message is after the last user message, moves it before.
+ *
+ * Returns the modified array, or the original reference when no changes were needed.
+ */
+export function pruneAndReorderContextMessages<T extends ContextMessageLike>(
+  messages: T[],
+  customType: string,
+  activeToken: string | null,
+): T[] {
+  // Remove stale messages of the target customType
+  const filtered = messages.filter((message) => {
+    if (message.customType !== customType) return true;
+    if (!activeToken) return false;
+    return getContextToken(message.details) === activeToken;
+  });
+
+  if (!activeToken) return filtered;
+
+  // Find the active context message
+  const contextIndex = filtered.findIndex(
+    (message) =>
+      message.customType === customType && getContextToken(message.details) === activeToken,
+  );
+  if (contextIndex === -1) return filtered;
+
+  // Find the last user message
+  const userIndex = findLastUserMessageIndex(filtered);
+  if (userIndex === -1 || contextIndex < userIndex) return filtered;
+
+  // Move context message before last user message
+  const next = [...filtered];
+  const [contextMessage] = next.splice(contextIndex, 1);
+  if (!contextMessage) return filtered;
+  next.splice(userIndex, 0, contextMessage);
+  return next;
+}
+
+/**
+ * Restore the raw prompt content on a context message that was swapped for display text.
+ *
+ * Extensions using `registerMessageRenderer` store their LLM-facing content in
+ * `details.promptContent` and put a human-readable summary in `content`. This function
+ * reverses the swap so the model sees the original prompt content.
+ *
+ * Returns the original array reference when no change is needed.
+ */
+export function restorePromptContent<T extends ContextMessageLike>(
+  messages: T[],
+  customType: string,
+  activeToken: string | null,
+): T[] {
+  if (!activeToken) return messages;
+
+  const index = messages.findIndex(
+    (message) =>
+      message.customType === customType && getContextToken(message.details) === activeToken,
+  );
+  if (index === -1) return messages;
+
+  const promptContent = getPromptContent(messages[index]?.details);
+  if (!promptContent || messages[index]?.content === promptContent) return messages;
+
+  const next = [...messages];
+  next[index] = { ...next[index], content: promptContent };
+  return next;
+}
+
+/**
+ * Extract the `promptContent` string from a message's `details` object.
+ * Returns `null` when absent or not a string.
+ */
+export function getPromptContent(details: unknown): string | null {
+  if (!details || typeof details !== "object") return null;
+  const promptContent = (details as { promptContent?: unknown }).promptContent;
+  return typeof promptContent === "string" ? promptContent : null;
+}