@mrclrchtr/supi-ask-user 1.3.1 → 1.5.0

package/README.md

@@ -1,6 +1,6 @@
 # @mrclrchtr/supi-ask-user
 
-Structured `ask_user` tool and rich questionnaire overlay for the [pi coding agent](https://github.com/earendil-works/pi). Lets the agent pause and ask you focused, typed decisions — picking from lists, multi-selecting, or entering freeform text.
+Adds a redesigned `ask_user` tool to the [pi coding agent](https://github.com/earendil-works/pi). It lets the model pause and request a small decision form when explicit human input is required.
 
 ## Install
 
@@ -14,34 +14,153 @@ For local development:
 pi install ./packages/supi-ask-user
 ```
 
-After editing the source, run `/reload` to pick up changes.
+After editing the source, run `/reload`.
 
-## What it adds
+## What you get
 
-Registers the `ask_user` tool — callable by the model during an agent run. When the agent needs explicit user input to proceed, it invokes `ask_user` with a questionnaire, and the extension opens an interactive overlay.
+After install, pi gets one new tool:
 
-**Question types:**
+- **`ask_user`** — open a blocking decision form during a run
 
-| Type | Use |
-|------|-----|
-| `choice` | Pick one option (default) or multiple options (`multi: true`) from a list |
-| `text` | Freeform text input |
+The tool presents a structured questionnaire in the TUI overlay and blocks the agent turn until the user responds. It is designed for focused decisions, **not** long surveys or open-ended discovery.
 
-For yes/no questions, use `choice` with options `{value: "yes", label: "Yes"}` and `{value: "no", label: "No"}` — there is no separate `yesno` type.
+Typical use cases:
 
-**Key behaviors:**
+- Clarify a narrow implementation choice
+- Confirm a risky or destructive action
+- Ask for a preference the repo cannot answer
+- Gather one short cluster of related decisions before proceeding
 
-- Returns an error in non-interactive or print-mode sessions (no fallback dialog).
-- Only one questionnaire runs at a time — concurrent `ask_user` calls return an error.
-- Cancelling or closing the overlay aborts the current agent turn.
-- Completed answers appear as a readable summary entry in the `/tree` view.
+## Package surfaces
 
-## Usage
+- `@mrclrchtr/supi-ask-user/extension` — pi extension entrypoint, registers the `ask_user` tool
+- `@mrclrchtr/supi-ask-user/api` — reusable types and utilities
 
-The agent decides when to call `ask_user`. You control how it's used through the system prompt guidelines the extension injects. A minimal example the agent might construct:
+Example:
+
+```ts
+import { normalizeQuestionnaire, AskUserController } from "@mrclrchtr/supi-ask-user/api";
+
+const questionnaire = normalizeQuestionnaire(params);
+const controller = new AskUserController(questionnaire);
+```
+
+## Request shape
+
+`ask_user` accepts a small form with optional framing text:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `title` | string (optional) | Short overall title for the form |
+| `intro` | string (optional) | Why the agent is asking |
+| `questions` | array (1–4) | Choice or text questions |
+| `allowPartialSubmit` | boolean (optional) | Let the user submit partial progress |
+| `allowDiscuss` | boolean (optional) | Let the user switch back into discussion instead of giving a final decision |
+
+## Questions
+
+Each question has a `type`, `id`, `header`, and `prompt`. Two question types are supported:
+
+### `choice` — fixed options
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `options` | array (2–12) | Allowed answers with `value`, `label`, and optional `description`/`preview` |
+| `required` | boolean (default: `true`) | Whether this question must be answered |
+| `multi` | boolean (default: `false`) | Allow selecting multiple options |
+| `allowOther` | boolean | Allow a freeform answer instead of listed options. Single-select only. |
+| `recommendation` | string \| string[] | Recommended option value(s) |
+| `initial` | string \| string[] | Initially selected option value(s) |
+
+Model yes/no questions as a `choice` with `{ value: "yes", label: "Yes" }` and `{ value: "no", label: "No" }`.
+
+### `text` — freeform input
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `required` | boolean (default: `true`) | Whether this question must be answered |
+| `initial` | string | Initial value shown in the editor |
+| `placeholder` | string | Placeholder shown before the user types |
+
+## Result
+
+A completed form returns a result with `details.status` set to one of:
+
+| Status | Meaning |
+|--------|---------|
+| `submitted` | Full submit, all required questions answered |
+| `partial` | Partial submit with some required questions unanswered |
+| `discuss` | User wants to continue the conversation instead of deciding |
+| `cancelled` | User explicitly cancelled (aborts the current agent turn) |
+| `aborted` | The interaction was aborted externally (aborts the current agent turn) |
+
+`details.answersById` maps question IDs to their answers. Each answer has a `kind` and type-specific data:
+
+- `{ kind: "choice", selections: [{ value, label, note? }] }` — single or multi-select choice, with optional per-option user notes
+- `{ kind: "custom", value: "..." }` — freeform `allowOther` answer
+- `{ kind: "text", value: "..." }` — freeform text answer
+
+`details.missingQuestionIds` lists any required questions that were left unanswered on a partial submit.
+
+## Behavior
+
+- Requires pi in interactive (TUI) mode with custom overlay support — no degraded fallback
+- Only one `ask_user` form may be active at a time; calling `ask_user` while another form is in flight returns an error
+- Cancellation or abort stops the current agent turn
+- Completed forms are summarized in the session tree
+- Do not use `ask_user` for open-ended interviews or repo facts the agent can discover on its own
+
+## Tool guidance
+
+The tool registers the following prompt guidance that the model sees:
+
+- Use ask_user only when explicit user input is required to proceed safely; do not use ask_user for open-ended interviews or repo facts.
+- Use ask_user with 1-4 related questions; prefer one when possible.
+- Use ask_user `choice` for fixed options and ask_user `text` for freeform input; model yes/no as `choice` with `{ value: "yes", label: "Yes" }` and `{ value: "no", label: "No" }`.
+- Use ask_user `allowOther` only on single-select `choice` questions.
+- Use ask_user `allowDiscuss` or `allowPartialSubmit` only when that outcome is actionable.
+- Do not call ask_user while another ask_user form is already in flight.
+
+## UI controls
+
+### Choice questions
+
+- `↑↓` — move between options
+- `Space` — select the focused option (single-select) or toggle (multi-select)
+- `Enter` — submit the current answer
+- `n` — edit a note for the focused choice option
+- `←` — go back to the previous question
+- `Esc` — cancel the whole form (or close the note editor if one is open)
+
+On wide terminals, option previews render side-by-side with the option list. On narrow terminals, previews stack below.
+
+Notes are available only for real `choice` options. They do not apply to `text` questions, `Other…` freeform answers, or other exceptional action rows. Saving a non-empty note selects the option if needed; clearing a note leaves the current selection alone; deselecting a multi-select option removes its note with the selection.
+
+Only exceptional action rows are visible:
+
+- `Other…` — when `allowOther` is enabled
+- `Discuss instead…` — when `allowDiscuss` is enabled
+- `Submit partial answers` — when `allowPartialSubmit` is enabled
+- `Skip question` — for optional questions
+
+Back and cancel are keyboard-only (`←`, `Esc`) — no visible rows.
+
+### Text questions
+
+- The editor is visible immediately (no separate entry row)
+- `Enter` — submit the current text
+- `↓` — move from the editor into visible exceptional action rows
+- `↑` — from the first action row, return focus to the editor
+- `Esc` — cancel the whole form
+
+Exceptional action rows (`Discuss instead…`, `Submit partial answers`) may appear below the editor when those paths are enabled.
+
+## Example
 
 ```json
 {
+  "title": "Formatter decision",
+  "intro": "I need one explicit choice before I update the repo config.",
   "questions": [
     {
       "type": "choice",
@@ -53,63 +172,40 @@ The agent decides when to call `ask_user`. You control how it's used through the
         { "value": "prettier", "label": "Prettier" }
       ],
       "recommendation": "biome",
-      "default": "biome"
+      "initial": "biome"
     },
     {
       "type": "text",
       "id": "reason",
       "header": "Reason",
-      "prompt": "Why this formatter?",
-      "default": "Faster linting"
+      "prompt": "Anything I should optimize for?",
+      "required": false,
+      "placeholder": "optional"
     }
-  ]
-}
-```
-
-**Multi-select example:**
-
-```json
-{
-  "type": "choice",
-  "multi": true,
-  "id": "features",
-  "header": "Features",
-  "prompt": "Which features to include?",
-  "options": [
-    { "value": "auth", "label": "Authentication" },
-    { "value": "caching", "label": "Caching" },
-    { "value": "logging", "label": "Logging" }
   ],
-  "recommendation": ["auth", "caching"]
+  "allowDiscuss": true
 }
 ```
 
-**Per-question features:**
-
-- `multi` — set to `true` to enable multi-select (replaces the former `multichoice` type). Default `false`.
-- `recommendation` — highlights the preferred option with a visual badge. String for single-select, array for multi-select.
-- `default` — pre-selects a starting value the user can accept with a single keystroke. String for single-select, array for multi-select.
-- `allowOther` — lets the user type a custom answer instead of picking from options.
-- `allowDiscuss` — lets the user opt into a discussion instead of deciding immediately.
-- `preview` — rich content (markdown, code, or ASCII mockups) shown alongside the option.
-
-**Questionnaire-level controls:**
-
-- `allowSkip` — exposes a Skip action so the user can submit partial results without answering all required questions.
-
-## Limits
-
-- **1–4 questions** per questionnaire. Use one decision per call; chain multiple calls when you need more questions.
-- **2–12 options** per `choice` question (single or multi-select).
-- **60 characters** max per question header.
-- **4000 characters** max per question prompt.
-
-## Requirements
-
-- `@earendil-works/pi-coding-agent`
-- `@earendil-works/pi-tui`
-- `typebox`
-
-## Source
-
-Entrypoint: `src/ask-user.ts` — registers the `ask_user` tool, drives the questionnaire overlay, and manages the concurrency lock.
+## Source layout
+
+- `src/extension.ts` — pi extension entrypoint
+- `src/api.ts` — reusable public surface
+- `src/index.ts` — package barrel
+- `src/ask-user.ts` — tool registration and execution boundary
+- `src/schema.ts` — tool-call parameter schema (TypeBox)
+- `src/types.ts` — internal normalized types and answer shapes
+- `src/normalize.ts` — validation and lowering into internal types
+- `src/tool/guidance.ts` — prompt guidance and tool description
+- `src/session/controller.ts` — headless decision-form state machine
+- `src/session/lock.ts` — session-scoped concurrency lock
+- `src/ui/choose-renderer.ts` — custom-overlay capability gate
+- `src/ui/overlay.ts` — overlay runner that creates the custom interaction session
+- `src/ui/overlay-component.ts` — rich custom interaction state and input orchestration
+- `src/ui/overlay-view.ts` — choice/action row modeling and split-layout helpers
+- `src/ui/overlay-render.ts` — rich overlay rendering built on `Markdown`, `Editor`, and `SelectList`
+- `src/ui/overlay-actions.ts` — exceptional-action list wiring for text questions
+- `src/ui/types.ts` — shared UI runner types
+- `src/render/result.ts` — tool result shaping
+- `src/render/transcript.ts` — transcript rendering
+- `src/render/tree-summary.ts` — session-tree summary labels

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.5.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,
@@ -49,6 +49,7 @@ export {
   redactDebugData,
   resetDebugRegistry,
 } from "./debug-registry.ts";
+export { fileToUri, resolveToolPath, stripToolPathPrefix, uriToFile } from "./path-utils.ts";
 export type { KnownRootEntry } from "./project-roots.ts";
 export {
   buildKnownRootsMap,
@@ -63,15 +64,16 @@ export {
   sortRootsBySpecificity,
   walkProject,
 } from "./project-roots.ts";
+export { createRegistry, createSessionStateRegistry } from "./registry-utils.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-core/src/{context-provider-registry.ts → 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,
@@ -49,6 +49,7 @@ export {
   redactDebugData,
   resetDebugRegistry,
 } from "./debug-registry.ts";
+export { fileToUri, resolveToolPath, stripToolPathPrefix, uriToFile } from "./path-utils.ts";
 export type { KnownRootEntry } from "./project-roots.ts";
 export {
   buildKnownRootsMap,
@@ -63,15 +64,16 @@ export {
   sortRootsBySpecificity,
   walkProject,
 } from "./project-roots.ts";
+export { createRegistry, createSessionStateRegistry } from "./registry-utils.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/path-utils.ts

@@ -0,0 +1,40 @@
+import * as path from "node:path";
+
+/** Strip pi's optional leading `@` file-path prefix from a tool input. */
+export function stripToolPathPrefix(target: string): string {
+  return target.startsWith("@") ? target.slice(1) : target;
+}
+
+/**
+ * Resolve a tool-style file path from a session cwd.
+ *
+ * Built-in pi file tools accept a leading `@` prefix in path arguments, so
+ * shared SuPi path helpers normalize that prefix before resolving relative
+ * paths.
+ */
+export function resolveToolPath(cwd: string, target: string): string {
+  return path.resolve(cwd, stripToolPathPrefix(target));
+}
+
+/** Convert a file path to a file:// URI. */
+export function fileToUri(filePath: string): string {
+  const resolved = path.resolve(filePath);
+  if (process.platform === "win32") {
+    return `file:///${resolved.replace(/\\/g, "/")}`;
+  }
+  return `file://${resolved}`;
+}
+
+/** Convert a file:// URI to a file path. */
+export function uriToFile(uri: string): string {
+  if (!uri.startsWith("file://")) return uri;
+  let filePath = decodeURIComponent(uri.slice(7));
+  if (
+    process.platform === "win32" &&
+    filePath.startsWith("/") &&
+    /^[A-Za-z]:/.test(filePath.slice(1))
+  ) {
+    filePath = filePath.slice(1);
+  }
+  return filePath;
+}