@mrclrchtr/supi-ask-user 1.5.0 → 1.7.0

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

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "1.5.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-ask-user",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "SuPi ask-user extension — rich questionnaire UI for structured agent-user decisions",
   "license": "MIT",
   "repository": {
@@ -21,7 +21,7 @@
   ],
   "main": "src/api.ts",
   "dependencies": {
-    "@mrclrchtr/supi-core": "1.5.0"
+    "@mrclrchtr/supi-core": "1.7.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"

package/src/ui/overlay-component.ts

@@ -24,6 +24,7 @@ import {
   choiceRowValue,
   defaultChoiceRowIndex,
   type FocusTarget,
+  noteTargetLabel,
   type OverlayAction,
   type OverlayMode,
   previewOptionIndexForRows,
@@ -32,7 +33,6 @@ import type { OverlayArgs } from "./types.ts";
 
 export class AskUserOverlay implements Component, Focusable {
   focused = false;
-
   private readonly editor: Editor;
   private focus: FocusTarget = "choices";
   private mode: OverlayMode = "choice";
@@ -40,7 +40,6 @@ export class AskUserOverlay implements Component, Focusable {
   private cachedWidth: number | undefined;
   private cachedLines: string[] | undefined;
   private readonly onAbort: () => void;
-
   private choiceRows: ChoiceRow[] = [];
   private choiceRowIndex = 0;
   private previewOptionIndex = 0;
@@ -48,7 +47,6 @@ export class AskUserOverlay implements Component, Focusable {
   private textActions: Array<{ action: OverlayAction; label: string }> = [];
   private actionIndex = 0;
   private actionList: SelectList | undefined;
-
   constructor(private readonly args: OverlayArgs) {
     this.editor = new Editor(args.tui, makeEditorTheme(args.theme));
     this.editor.onSubmit = (value) => this.handleEditorSubmit(value);
@@ -79,6 +77,10 @@ export class AskUserOverlay implements Component, Focusable {
         this.args.controller.currentQuestion,
         this.previewOptionIndex,
       ),
+      noteTargetLabel:
+        this.mode === "note-input"
+          ? noteTargetLabel(this.args.controller, this.choiceRows, this.choiceRowIndex)
+          : undefined,
     });
     return this.cachedLines;
   }
@@ -155,7 +157,6 @@ export class AskUserOverlay implements Component, Focusable {
 
     this.choiceList.handleInput(data);
   }
-
   private handleActionKey(data: string): void {
     const question = this.args.controller.currentQuestion;
     if (!this.actionList) return;
@@ -390,7 +391,6 @@ export class AskUserOverlay implements Component, Focusable {
     this.cachedLines = undefined;
     this.args.tui.requestRender();
   }
-
   private finish(): void {
     if (this.closed) return;
     this.closed = true;

package/src/ui/overlay-render.ts

@@ -29,6 +29,7 @@ export interface RenderOverlayFrameArgs {
   actionList: SelectList | undefined;
   textActionLabels: string[];
   previewText?: string;
+  noteTargetLabel?: string;
 }
 
 export function renderOverlayFrame(args: RenderOverlayFrameArgs): string[] {
@@ -191,7 +192,9 @@ function renderEditorLines(args: RenderOverlayFrameArgs, width: number): string[
       : args.mode === "custom-input"
         ? "Other answer"
         : args.mode === "note-input"
-          ? "Option note"
+          ? args.noteTargetLabel
+            ? `Note for: ${args.noteTargetLabel}`
+            : "Option note"
           : "Your answer";
 
   const lines = [args.theme.fg("accent", label), ...args.editor.render(Math.max(20, width - 1))];

package/src/ui/overlay-view.ts

@@ -150,19 +150,34 @@ export function choiceRowValue(row: ChoiceRow): string {
   return row.kind === "option" ? `option:${row.optionIndex}` : `action:${row.action}`;
 }
 
+export function noteTargetLabel(
+  controller: AskUserController,
+  choiceRows: ChoiceRow[],
+  choiceRowIndex: number,
+): string | undefined {
+  const question = controller.currentQuestion;
+  if (question.type !== "choice") return undefined;
+  const row = choiceRows[choiceRowIndex];
+  if (row?.kind !== "option") return undefined;
+  return question.options[row.optionIndex]?.label;
+}
+
 function renderOptionRow(args: {
   option: { label: string; description?: string };
   labelText: string;
+  hasNote: boolean;
   isSelected: boolean;
   theme: Theme;
   width: number;
 }): string[] {
-  const { theme, isSelected, labelText, width, option } = args;
+  const { theme, isSelected, labelText, hasNote, width, option } = args;
   const prefix = isSelected ? "\u2192 " : "  ";
+  const baseText = isSelected
+    ? theme.fg("accent", `${prefix}${labelText}`)
+    : `${prefix}${labelText}`;
+  const noteSuffix = hasNote ? ` ${theme.fg("accent", "[note]")}` : "";
 
-  const lines: string[] = [
-    isSelected ? theme.fg("accent", `${prefix}${labelText}`) : `${prefix}${labelText}`,
-  ];
+  const lines: string[] = [`${baseText}${noteSuffix}`];
 
   if (option.description) {
     const descWidth = Math.max(10, width - 2);
@@ -200,9 +215,8 @@ function prepareOptionLabel(
   option: { label: string },
   marker: string,
   recommended: boolean,
-  hasNote: boolean,
 ): string {
-  return `${marker} ${option.label}${recommended ? " (recommended)" : ""}${hasNote ? " [note]" : ""}`;
+  return `${marker} ${option.label}${recommended ? " (recommended)" : ""}`;
 }
 
 export function renderChoiceList(args: {
@@ -228,9 +242,9 @@ export function renderChoiceList(args: {
       const marker = prepareOptionMarker(question, row.optionIndex, selectedIndexes);
       const recommended = question.recommendedIndexes.includes(row.optionIndex);
       const hasNote = !!controller.getChoiceOptionNote(question.id, option.value);
-      const labelText = prepareOptionLabel(option, marker, recommended, hasNote);
+      const labelText = prepareOptionLabel(option, marker, recommended);
 
-      lines.push(...renderOptionRow({ option, labelText, isSelected, theme, width }));
+      lines.push(...renderOptionRow({ option, labelText, hasNote, isSelected, theme, width }));
     } else {
       const answer = controller.getAnswer(question.id);
       const actionLabelText =