@mrclrchtr/supi-claude-md 1.6.0 → 1.7.0

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

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
   "license": "MIT",
   "repository": {
@@ -20,7 +20,8 @@
   ],
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*"
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-coding-agent": {
@@ -28,6 +29,9 @@
     },
     "@earendil-works/pi-tui": {
       "optional": true
+    },
+    "typebox": {
+      "optional": true
     }
   },
   "main": "src/api.ts",

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

@@ -1,11 +1,12 @@
 // 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.
+// settings registry for supi-wide TUI settings, and a shared tool-spec/registration framework.
 
 export type { SupiConfigLocation, SupiConfigOptions } from "./config/config.ts";
 export {
   loadSupiConfig,
   loadSupiConfigForScope,
+  readJsonFile,
   removeSupiConfigKey,
   writeSupiConfig,
 } from "./config/config.ts";
@@ -83,3 +84,13 @@ export {
   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";

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

@@ -20,7 +20,7 @@ function getProjectConfigPath(cwd: string): string {
   return path.join(cwd, PROJECT_CONFIG_DIR, CONFIG_FILE);
 }
 
-function readJsonFile(filePath: string): Record<string, unknown> | null {
+export function readJsonFile(filePath: string): Record<string, unknown> | null {
   let content: string;
   try {
     content = fs.readFileSync(filePath, "utf-8");

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

@@ -1,11 +1,12 @@
 // 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.
+// settings registry for supi-wide TUI settings, and a shared tool-spec/registration framework.
 
 export type { SupiConfigLocation, SupiConfigOptions } from "./config/config.ts";
 export {
   loadSupiConfig,
   loadSupiConfigForScope,
+  readJsonFile,
   removeSupiConfigKey,
   writeSupiConfig,
 } from "./config/config.ts";
@@ -83,3 +84,13 @@ export {
   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";

package/node_modules/@mrclrchtr/supi-core/src/tool-framework.ts

@@ -0,0 +1,116 @@
+// Shared tool framework for SuPi extensions.
+//
+// Provides a standard ToolSpec→PromptSurface→registerTool pipeline so
+// individual packages do not duplicate spec interfaces, guidance derivation,
+// registration loops, or common TypeBox parameter schemas.
+
+import type {
+  AgentToolResult,
+  AgentToolUpdateCallback,
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { type TSchema, Type } from "typebox";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Minimum contract for a SuPi tool definition. */
+export interface SuiPiToolSpec {
+  name: string;
+  label: string;
+  description: string;
+  promptSnippet: string;
+  promptGuidelines: string[];
+  parameters: TSchema;
+}
+
+/** Derived prompt surface — what pi flattens into the system prompt. */
+export interface SuiPiToolPromptSurface {
+  description: string;
+  promptSnippet: string;
+  promptGuidelines: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Guidance derivation
+// ---------------------------------------------------------------------------
+
+/**
+ * Static derivation: copies spec fields into a prompt surface.
+ *
+ * Packages that need dynamic guidance (e.g. server-coverage injection) should
+ * build their own surfaces, optionally starting from the output of this helper.
+ */
+export function derivePromptSurface(spec: SuiPiToolSpec): SuiPiToolPromptSurface {
+  return {
+    description: spec.description,
+    promptSnippet: spec.promptSnippet,
+    promptGuidelines: [...spec.promptGuidelines],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+
+// biome-ignore lint/complexity/useMaxParams: matches pi ToolDefinition.execute signature
+export type ToolExecuteFn = (
+  toolCallId: string,
+  params: unknown,
+  signal: AbortSignal | undefined,
+  onUpdate: AgentToolUpdateCallback<Record<string, unknown>> | undefined,
+  ctx: ExtensionContext,
+) => Promise<AgentToolResult<Record<string, unknown>>>;
+
+/**
+ * Register a set of tools from specs + pre-derived surfaces.
+ *
+ * `createExecute` receives the spec and returns a pi-compatible execute
+ * function.  This keeps execute-logic package-local while the framework owns
+ * the declarative surface and registration boilerplate.
+ */
+export function registerSuiPiTools(
+  pi: ExtensionAPI,
+  specs: readonly SuiPiToolSpec[],
+  surfaces: Record<string, SuiPiToolPromptSurface>,
+  createExecute: (spec: SuiPiToolSpec) => ToolExecuteFn,
+): void {
+  for (const spec of specs) {
+    const surface = surfaces[spec.name];
+    pi.registerTool({
+      name: spec.name,
+      label: spec.label,
+      description: surface?.description ?? spec.description,
+      promptSnippet: surface?.promptSnippet ?? spec.promptSnippet,
+      promptGuidelines: surface?.promptGuidelines ?? [...spec.promptGuidelines],
+      parameters: spec.parameters,
+      execute: createExecute(spec),
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Shared parameter builders
+// ---------------------------------------------------------------------------
+
+/** File path (relative or absolute). */
+export const FileParam = Type.String({ description: "File path (relative or absolute)" });
+
+/** 1-based line number. */
+export const LineParam = Type.Number({ description: "1-based line number", minimum: 1 });
+
+/** 1-based character column (UTF-16). */
+export const CharacterParam = Type.Number({
+  description: "1-based column number (UTF-16)",
+  minimum: 1,
+});
+
+/** Symbol name for discovery-based resolution. */
+export const SymbolParam = Type.String({
+  description: "Symbol name for discovery-based resolution",
+});
+
+/** Maximum results to return. */
+export const MaxResultsParam = Type.Number({ description: "Maximum results to return" });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-claude-md",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "SuPi claude-md extension — automatic subdirectory context injection for pi",
   "license": "MIT",
   "repository": {
@@ -21,7 +21,7 @@
     "!__tests__"
   ],
   "dependencies": {
-    "@mrclrchtr/supi-core": "1.6.0"
+    "@mrclrchtr/supi-core": "1.7.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"

package/skills/claude-md-improver/references/quality-criteria.md

@@ -88,7 +88,7 @@
 
 ### 7. Auto-Delivered Overlap (10 points)
 
-Score this criterion after a **context baseline review**: compare the CLAUDE.md against what a SuPi-enabled PI session likely already has from `code_intel brief` and other known injected context.
+Score this criterion after a **context baseline review**: compare the CLAUDE.md against what a SuPi-enabled PI session likely already has from `code_brief` and other known injected context.
 
 **10 points**: Almost no overlap. Any overlap is tiny and clearly justified by human-only reasoning.
 
@@ -100,15 +100,15 @@ Score this criterion after a **context baseline review**: compare the CLAUDE.md
 
 **What is NOT overlap:** Gotchas specific to a package's behavior; cross-package patterns that aren't discoverable from manifests; commands and workflows; human-curated "Start Here" guidance with reasoning; concise structure notes that explain boundaries, ownership, initialization order, or important exceptions; and sections classified as **unique** during the baseline review.
 
-**What IS overlap:** Monorepo package tables where every row is `{name, description, path}`; root-level "Modules" or "Packages" sections with >5 entries; the **fully redundant** portion of a section during baseline review; root `## Project structure` / `## Architecture` trees that mostly restate folders, packages, or module layout already visible from `code_intel brief`; high-level architecture overviews that don't add relationships, gotchas, conventions, or exceptions beyond what's in `package.json`; and dependency graphs that could be generated from `pnpm-workspace.yaml`.
+**What IS overlap:** Monorepo package tables where every row is `{name, description, path}`; root-level "Modules" or "Packages" sections with >5 entries; the **fully redundant** portion of a section during baseline review; root `## Project structure` / `## Architecture` trees that mostly restate folders, packages, or module layout already visible from `code_brief`; high-level architecture overviews that don't add relationships, gotchas, conventions, or exceptions beyond what's in `package.json`; and dependency graphs that could be generated from `pnpm-workspace.yaml`.
 
 ## Assessment Process
 
 1. Read the CLAUDE.md file completely.
-2. If SuPi is active, perform a **context baseline review** first: compare against `code_intel brief` and other known injected context, then classify sections as **fully redundant**, **partially redundant**, or **unique**.
+2. If SuPi is active, perform a **context baseline review** first: compare against `code_brief` and other known injected context, then classify sections as **fully redundant**, **partially redundant**, or **unique**.
 3. Cross-reference with the actual codebase: run documented commands (mentally or actually), check that referenced files exist, and verify architecture descriptions.
 4. Score each criterion, calculate the total, assign the grade, list the specific issues, and propose concrete improvements.
 
 ## Red Flags
 
-Watch for commands that would fail (wrong paths, missing deps), references to deleted files or folders, outdated tech versions, template copy without customization, generic advice, stale `TODO` items, duplicate info across multiple CLAUDE.md files, sections that duplicate `code_intel brief` output, and structure sections where the redundant tree/inventory portion should be separated from the unique guidance portion.
+Watch for commands that would fail (wrong paths, missing deps), references to deleted files or folders, outdated tech versions, template copy without customization, generic advice, stale `TODO` items, duplicate info across multiple CLAUDE.md files, sections that duplicate `code_brief` output, and structure sections where the redundant tree/inventory portion should be separated from the unique guidance portion.

package/skills/claude-md-improver/references/templates.md

@@ -241,7 +241,7 @@ For packages within a monorepo or distinct modules.
 - <generation/sync pattern>
 ```
 
-> ⚠️ **When SuPi is active:** The `## Packages` table in this template is auto-generated by `code_intel brief` on the first turn. Consider omitting it or replacing it with `## Start Here` and `## Cross-Package Patterns` sections that capture conventions not visible in manifests.
+> ⚠️ **When SuPi is active:** The `## Packages` table in this template is auto-generated by `code_brief` on the first turn. Consider omitting it or replacing it with `## Start Here` and `## Cross-Package Patterns` sections that capture conventions not visible in manifests.
 
 ---
 
@@ -282,7 +282,7 @@ For projects using SuPi extensions (`code-intelligence`, `claude-md`). Omits sec
 ```
 
 **What's intentionally absent:**
-- `## Modules` / `## Packages` — `code_intel brief` generates this
+- `## Modules` / `## Packages` — `code_brief` generates this
 - Large root `## Project structure` / `## Architecture` directory trees that just restate the workspace layout
 - `## Dependencies` table — derivable from `package.json`
 

package/skills/claude-md-improver/references/update-guidelines.md

@@ -71,13 +71,13 @@ When auditing or updating CLAUDE.md in a project using SuPi extensions, these se
 | `supi-claude-md` | Subdirectory `CLAUDE.md` files wrapped in `<extension-context>` | On `read`/`edit`/`lsp`/`tree_sitter` to subdirectories |
 | `supi-core` | `findProjectRoot`, `walkProject`, XML `<extension-context>` tagging | Available to all extensions |
 
-**Implication:** A root CLAUDE.md doesn't need to document what `code_intel brief` would say. Focus instead on:
+**Implication:** A root CLAUDE.md doesn't need to document what `code_brief` would say. Focus instead on:
 - Commands and workflows
 - Cross-package conventions and patterns
 - Gotchas that aren't in code
 - Human-curated guidance ("start here for X")
 
-When SuPi is active, do a quick baseline review first: compare the CLAUDE.md against `code_intel brief` and other known injected context, then separate each section into overlap vs unique value. If a root `## Project structure` / `## Architecture` section mostly restates the workspace tree, treat that portion as redundant and keep only the orientation, boundary rules, or exceptions that the generated overview cannot supply.
+When SuPi is active, do a quick baseline review first: compare the CLAUDE.md against `code_brief` and other known injected context, then separate each section into overlap vs unique value. If a root `## Project structure` / `## Architecture` section mostly restates the workspace tree, treat that portion as redundant and keep only the orientation, boundary rules, or exceptions that the generated overview cannot supply.
 
 ## What NOT to Add
 
@@ -180,7 +180,7 @@ Bad:
 - `api` depends on `db`, `auth`
 - `web` depends on `api`
 
-Better: Skip — `code_intel brief` shows this live.
+Better: Skip — `code_brief` shows this live.
 ```
 
 **Partially redundant: Root project structure section with both overlap and unique value**

package/skills/claude-md-revision/references/quality-criteria.md

@@ -88,7 +88,7 @@
 
 ### 7. Auto-Delivered Overlap (10 points)
 
-Score this criterion after a **context baseline review**: compare the CLAUDE.md against what a SuPi-enabled PI session likely already has from `code_intel brief` and other known injected context.
+Score this criterion after a **context baseline review**: compare the CLAUDE.md against what a SuPi-enabled PI session likely already has from `code_brief` and other known injected context.
 
 **10 points**: Almost no overlap. Any overlap is tiny and clearly justified by human-only reasoning.
 
@@ -100,15 +100,15 @@ Score this criterion after a **context baseline review**: compare the CLAUDE.md
 
 **What is NOT overlap:** Gotchas specific to a package's behavior; cross-package patterns that aren't discoverable from manifests; commands and workflows; human-curated "Start Here" guidance with reasoning; concise structure notes that explain boundaries, ownership, initialization order, or important exceptions; and sections classified as **unique** during the baseline review.
 
-**What IS overlap:** Monorepo package tables where every row is `{name, description, path}`; root-level "Modules" or "Packages" sections with >5 entries; the **fully redundant** portion of a section during baseline review; root `## Project structure` / `## Architecture` trees that mostly restate folders, packages, or module layout already visible from `code_intel brief`; high-level architecture overviews that don't add relationships, gotchas, conventions, or exceptions beyond what's in `package.json`; and dependency graphs that could be generated from `pnpm-workspace.yaml`.
+**What IS overlap:** Monorepo package tables where every row is `{name, description, path}`; root-level "Modules" or "Packages" sections with >5 entries; the **fully redundant** portion of a section during baseline review; root `## Project structure` / `## Architecture` trees that mostly restate folders, packages, or module layout already visible from `code_brief`; high-level architecture overviews that don't add relationships, gotchas, conventions, or exceptions beyond what's in `package.json`; and dependency graphs that could be generated from `pnpm-workspace.yaml`.
 
 ## Assessment Process
 
 1. Read the CLAUDE.md file completely.
-2. If SuPi is active, perform a **context baseline review** first: compare against `code_intel brief` and other known injected context, then classify sections as **fully redundant**, **partially redundant**, or **unique**.
+2. If SuPi is active, perform a **context baseline review** first: compare against `code_brief` and other known injected context, then classify sections as **fully redundant**, **partially redundant**, or **unique**.
 3. Cross-reference with the actual codebase: run documented commands (mentally or actually), check that referenced files exist, and verify architecture descriptions.
 4. Score each criterion, calculate the total, assign the grade, list the specific issues, and propose concrete improvements.
 
 ## Red Flags
 
-Watch for commands that would fail (wrong paths, missing deps), references to deleted files or folders, outdated tech versions, template copy without customization, generic advice, stale `TODO` items, duplicate info across multiple CLAUDE.md files, sections that duplicate `code_intel brief` output, and structure sections where the redundant tree/inventory portion should be separated from the unique guidance portion.
+Watch for commands that would fail (wrong paths, missing deps), references to deleted files or folders, outdated tech versions, template copy without customization, generic advice, stale `TODO` items, duplicate info across multiple CLAUDE.md files, sections that duplicate `code_brief` output, and structure sections where the redundant tree/inventory portion should be separated from the unique guidance portion.

package/skills/claude-md-revision/references/templates.md

@@ -241,7 +241,7 @@ For packages within a monorepo or distinct modules.
 - <generation/sync pattern>
 ```
 
-> ⚠️ **When SuPi is active:** The `## Packages` table in this template is auto-generated by `code_intel brief` on the first turn. Consider omitting it or replacing it with `## Start Here` and `## Cross-Package Patterns` sections that capture conventions not visible in manifests.
+> ⚠️ **When SuPi is active:** The `## Packages` table in this template is auto-generated by `code_brief` on the first turn. Consider omitting it or replacing it with `## Start Here` and `## Cross-Package Patterns` sections that capture conventions not visible in manifests.
 
 ---
 
@@ -282,7 +282,7 @@ For projects using SuPi extensions (`code-intelligence`, `claude-md`). Omits sec
 ```
 
 **What's intentionally absent:**
-- `## Modules` / `## Packages` — `code_intel brief` generates this
+- `## Modules` / `## Packages` — `code_brief` generates this
 - Large root `## Project structure` / `## Architecture` directory trees that just restate the workspace layout
 - `## Dependencies` table — derivable from `package.json`
 

package/skills/claude-md-revision/references/update-guidelines.md

@@ -71,13 +71,13 @@ When auditing or updating CLAUDE.md in a project using SuPi extensions, these se
 | `supi-claude-md` | Subdirectory `CLAUDE.md` files wrapped in `<extension-context>` | On `read`/`edit`/`lsp`/`tree_sitter` to subdirectories |
 | `supi-core` | `findProjectRoot`, `walkProject`, XML `<extension-context>` tagging | Available to all extensions |
 
-**Implication:** A root CLAUDE.md doesn't need to document what `code_intel brief` would say. Focus instead on:
+**Implication:** A root CLAUDE.md doesn't need to document what `code_brief` would say. Focus instead on:
 - Commands and workflows
 - Cross-package conventions and patterns
 - Gotchas that aren't in code
 - Human-curated guidance ("start here for X")
 
-When SuPi is active, do a quick baseline review first: compare the CLAUDE.md against `code_intel brief` and other known injected context, then separate each section into overlap vs unique value. If a root `## Project structure` / `## Architecture` section mostly restates the workspace tree, treat that portion as redundant and keep only the orientation, boundary rules, or exceptions that the generated overview cannot supply.
+When SuPi is active, do a quick baseline review first: compare the CLAUDE.md against `code_brief` and other known injected context, then separate each section into overlap vs unique value. If a root `## Project structure` / `## Architecture` section mostly restates the workspace tree, treat that portion as redundant and keep only the orientation, boundary rules, or exceptions that the generated overview cannot supply.
 
 ## What NOT to Add
 
@@ -180,7 +180,7 @@ Bad:
 - `api` depends on `db`, `auth`
 - `web` depends on `api`
 
-Better: Skip — `code_intel brief` shows this live.
+Better: Skip — `code_brief` shows this live.
 ```
 
 **Partially redundant: Root project structure section with both overlap and unique value**