pi-usereq 0.4.0

package/src/core/resources.ts

@@ -0,0 +1,63 @@
+/**
+ * @file
+ * @brief Resolves installation-owned bundled resource locations.
+ * @details Encapsulates installation-path discovery, bundled-resource validation, prompt enumeration, and prompt loading directly from the installed extension payload. Runtime is proportional to directory-entry enumeration and prompt file size. Side effects are limited to filesystem reads.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { getInstallationPath, RESOURCE_ROOT_DIRNAME } from "./path-context.js";
+
+/**
+ * @brief Resolves the bundled resource directory inside the installed extension payload.
+ * @details Joins the installation path with `resources`, producing the immutable source tree used for prompt, template, and guideline access during runtime. Time complexity is O(1). No I/O side effects occur.
+ * @return {string} Absolute bundled resource root path.
+ */
+export function getBundledResourceRoot(): string {
+  return path.join(getInstallationPath(), RESOURCE_ROOT_DIRNAME);
+}
+
+/**
+ * @brief Validates that installed bundled resources are accessible.
+ * @details Verifies that the installation-owned resource root plus `prompts`, `templates`, and `guidelines` directories exist before prompt or tool execution. Runtime is O(1) plus bounded filesystem metadata checks. Side effects are limited to filesystem reads.
+ * @return {string} Absolute bundled resource root path.
+ * @throws {Error} Propagates a deterministic error when required installed resource directories are missing.
+ */
+export function ensureBundledResourcesAccessible(): string {
+  const resourceRoot = getBundledResourceRoot();
+  if (!fs.existsSync(resourceRoot) || !fs.statSync(resourceRoot).isDirectory()) {
+    throw new Error(`Missing bundled resources at ${resourceRoot}`);
+  }
+  for (const requiredDirectoryName of ["prompts", "templates", "guidelines"]) {
+    const requiredDirectoryPath = path.join(resourceRoot, requiredDirectoryName);
+    if (!fs.existsSync(requiredDirectoryPath) || !fs.statSync(requiredDirectoryPath).isDirectory()) {
+      throw new Error(`Missing bundled resource directory at ${requiredDirectoryPath}`);
+    }
+  }
+  return resourceRoot;
+}
+
+/**
+ * @brief Reads one bundled markdown prompt by logical prompt name.
+ * @details Resolves the prompt file under the installation-owned `resources/prompts` directory, validates resource accessibility, and loads it as UTF-8 text. Time complexity is O(n) in file size. Side effects are limited to filesystem reads.
+ * @param[in] promptName {string} Prompt identifier without the `.md` suffix.
+ * @return {string} Raw prompt markdown content.
+ * @throws {Error} Propagates `fs.readFileSync` errors when the prompt file is missing or unreadable.
+ */
+export function readBundledPrompt(promptName: string): string {
+  const filePath = path.join(ensureBundledResourcesAccessible(), "prompts", `${promptName}.md`);
+  return fs.readFileSync(filePath, "utf8");
+}
+
+/**
+ * @brief Lists bundled prompt identifiers available in the installed extension payload.
+ * @details Scans the installation-owned prompt directory, keeps visible markdown files only, strips the `.md` suffix, and returns a lexicographically sorted list. Time complexity is O(n log n). Side effects are limited to filesystem reads.
+ * @return {string[]} Sorted prompt names without file extensions.
+ */
+export function listBundledPromptNames(): string[] {
+  return fs
+    .readdirSync(path.join(ensureBundledResourcesAccessible(), "prompts"), { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".md") && !entry.name.startsWith("."))
+    .map((entry) => entry.name.slice(0, -3))
+    .sort((left, right) => left.localeCompare(right));
+}

package/src/core/runtime-project-paths.ts

@@ -0,0 +1,99 @@
+/**
+ * @file
+ * @brief Derives runtime-only repository and base-path facts.
+ * @details Centralizes git-repository probing, repository-root resolution, and base-path-to-git-path formatting for extension status, tool execution, and CLI flows. Runtime is dominated by git subprocess execution plus path normalization. Side effects are limited to subprocess spawning.
+ */
+
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { ReqError } from "./errors.js";
+import { isSameOrAncestorPath, normalizePathSlashes } from "./path-context.js";
+
+/**
+ * @brief Executes one git subprocess and captures UTF-8 output.
+ * @details Delegates to `spawnSync`, keeps execution synchronous for deterministic command flows, and supports an optional working directory. Runtime is dominated by the spawned git process. Side effects include subprocess creation.
+ * @param[in] command {string[]} Git executable plus argument vector.
+ * @param[in] cwd {string | undefined} Optional working directory.
+ * @return {ReturnType<typeof spawnSync>} Captured subprocess result.
+ */
+function runGitCapture(command: string[], cwd?: string): ReturnType<typeof spawnSync> {
+  return spawnSync(command[0]!, command.slice(1), {
+    cwd,
+    encoding: "utf8",
+  });
+}
+
+/**
+ * @brief Tests whether one path is inside a git work tree.
+ * @details Executes `git rev-parse --is-inside-work-tree` in the supplied directory and returns `true` only for a successful literal `true` response. Runtime is dominated by git execution. Side effects include subprocess creation.
+ * @param[in] targetPath {string} Directory to probe.
+ * @return {boolean} `true` when the directory belongs to a git work tree.
+ * @satisfies REQ-145
+ */
+export function isInsideGitRepo(targetPath: string): boolean {
+  const result = runGitCapture(["git", "rev-parse", "--is-inside-work-tree"], targetPath);
+  return result.status === 0 && result.stdout.trim() === "true";
+}
+
+/**
+ * @brief Resolves the repository root for one path inside a git work tree.
+ * @details Executes `git rev-parse --show-toplevel`, normalizes the result to an absolute path, and rejects non-repository paths with `ReqError`. Runtime is dominated by git execution. Side effects include subprocess creation.
+ * @param[in] targetPath {string} Directory inside the target repository.
+ * @return {string} Absolute repository-root path.
+ * @throws {ReqError} Throws when the path is not inside a git repository.
+ * @satisfies REQ-145
+ */
+export function resolveGitRoot(targetPath: string): string {
+  const result = runGitCapture(["git", "rev-parse", "--show-toplevel"], targetPath);
+  if (result.error || result.status !== 0) {
+    throw new ReqError(`Error: '${targetPath}' is not inside a git repository.`, 3);
+  }
+  return path.resolve(result.stdout.trim());
+}
+
+/**
+ * @brief Resolves the runtime git root for one execution path.
+ * @details Returns `undefined` when the path is outside a git repository. Otherwise resolves the repository root and rejects roots that are not identical to or ancestors of the execution path. Runtime is dominated by git execution. Side effects include subprocess creation.
+ * @param[in] executionPath {string} Runtime execution path.
+ * @return {string | undefined} Absolute repository-root path or `undefined` when unavailable.
+ * @satisfies REQ-105, REQ-145
+ */
+export function resolveRuntimeGitPath(executionPath: string): string | undefined {
+  const normalizedExecutionPath = path.resolve(executionPath);
+  if (!isInsideGitRepo(normalizedExecutionPath)) {
+    return undefined;
+  }
+  const gitRoot = resolveGitRoot(normalizedExecutionPath);
+  return isSameOrAncestorPath(gitRoot, normalizedExecutionPath) ? gitRoot : undefined;
+}
+
+/**
+ * @brief Formats the runtime `base-path` relative to the runtime `git-path`.
+ * @details Returns `.` when the repository root is unavailable or identical to the base path. Otherwise returns the slash-normalized relative path from `git-path` to `base-path`. Runtime is O(p) in path length. No external state is mutated.
+ * @param[in] basePath {string} Runtime base path.
+ * @param[in] gitPath {string | undefined} Runtime repository root.
+ * @return {string} Relative base-path token for status rendering.
+ * @satisfies REQ-148
+ */
+export function formatBasePathRelativeToGitPath(basePath: string, gitPath: string | undefined): string {
+  const normalizedBasePath = path.resolve(basePath);
+  if (!gitPath) {
+    return ".";
+  }
+  const normalizedGitPath = path.resolve(gitPath);
+  if (normalizedBasePath === normalizedGitPath) {
+    return ".";
+  }
+  return normalizePathSlashes(path.relative(normalizedGitPath, normalizedBasePath)) || ".";
+}
+
+/**
+ * @brief Formats the runtime git path for status rendering.
+ * @details Returns a slash-normalized absolute path or an empty string when no repository root is available. Runtime is O(p) in path length. No external state is mutated.
+ * @param[in] gitPath {string | undefined} Runtime repository root.
+ * @return {string} Absolute repository path or an empty string.
+ * @satisfies REQ-147
+ */
+export function formatAbsoluteGitPath(gitPath: string | undefined): string {
+  return gitPath ? normalizePathSlashes(path.resolve(gitPath)) : "";
+}

package/src/core/settings-menu.ts

@@ -0,0 +1,233 @@
+/**
+ * @file
+ * @brief Renders pi-usereq configuration menus with the shared pi.dev settings style.
+ * @details Wraps `SettingsList` in one extension-command helper that exposes right-aligned current values, built-in circular scrolling, bottom-line descriptions, and a deterministic bridge for offline test harnesses. Runtime is O(n) in visible choice count plus user interaction cost. Side effects are limited to transient custom-UI rendering.
+ */
+
+import { getSettingsListTheme, type ThemeColor, type ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+import { Container, SettingsList, Text, type Component, type SettingItem, type SettingsListTheme } from "@mariozechner/pi-tui";
+
+/**
+ * @brief Describes one selectable pi-usereq settings-menu choice.
+ * @details Stores the stable action identifier, left-column label, right-column current value, and bottom-line description consumed by the shared settings-menu renderer. The interface is compile-time only and introduces no runtime cost.
+ */
+export interface PiUsereqSettingsMenuChoice {
+  id: string;
+  label: string;
+  value: string;
+  description: string;
+}
+
+/**
+ * @brief Describes the offline bridge exposed by shared settings-menu components.
+ * @details Lets deterministic harnesses and unit tests drive the same settings-menu choices by label without simulating raw terminal key streams. The interface is runtime-facing but carries no side effects by itself.
+ */
+export interface PiUsereqSettingsMenuBridge {
+  title: string;
+  choices: PiUsereqSettingsMenuChoice[];
+  selectByLabel: (label: string) => boolean;
+  cancel: () => void;
+}
+
+/**
+ * @brief Represents a custom menu component augmented with the offline bridge.
+ * @details Extends the generic TUI `Component` contract with one optional bridge field consumed only by deterministic test and debug harness adapters. The interface is compile-time only and introduces no runtime cost.
+ */
+export interface PiUsereqSettingsMenuComponent extends Component {
+  __piUsereqSettingsMenu?: PiUsereqSettingsMenuBridge;
+}
+
+/**
+ * @brief Enumerates the CLI-supported theme tokens consumed by settings menus.
+ * @details Narrows callback-local theme calls to the documented settings-list
+ * semantics used by the pi CLI. Compile-time only and introduces no runtime
+ * cost.
+ */
+type PiUsereqSettingsThemeColor = Extract<ThemeColor, "accent" | "muted" | "dim">;
+
+/**
+ * @brief Describes the callback-local theme surface required by settings menus.
+ * @details Captures the subset of the custom-UI theme API needed to rebuild
+ * title and fallback settings-list styling when the shared global theme is not
+ * available in tests or offline replay. Compile-time only and introduces no
+ * runtime cost.
+ */
+interface PiUsereqSettingsTheme {
+  fg: (color: PiUsereqSettingsThemeColor, text: string) => string;
+  bold: (text: string) => string;
+}
+
+/**
+ * @brief Builds the fallback settings-list theme matching CLI settings semantics.
+ * @details Mirrors the shared CLI settings theme token mapping for labels,
+ * values, descriptions, cursor, and hints while avoiding the global theme
+ * singleton used by the live pi runtime. Runtime is O(1). No external state is
+ * mutated.
+ * @param[in] theme {PiUsereqSettingsTheme} Callback-local pi theme adapter.
+ * @return {SettingsListTheme} Fallback settings-list theme.
+ * @satisfies REQ-151, REQ-156
+ */
+function buildFallbackPiUsereqSettingsListTheme(
+  theme: PiUsereqSettingsTheme,
+): SettingsListTheme {
+  return {
+    label: (text: string, selected: boolean): string =>
+      selected ? theme.fg("accent", text) : text,
+    value: (text: string, selected: boolean): string =>
+      selected ? theme.fg("accent", text) : theme.fg("muted", text),
+    description: (text: string): string => theme.fg("dim", text),
+    cursor: theme.fg("accent", "→ "),
+    hint: (text: string): string => theme.fg("dim", text),
+  };
+}
+
+/**
+ * @brief Resolves the settings-list theme used by pi-usereq configuration menus.
+ * @details Prefers the shared CLI `getSettingsListTheme()` API so extension
+ * menus inherit active-theme behavior from pi itself, then falls back to an
+ * equivalent callback-local mapping when the shared theme singleton is
+ * unavailable in deterministic tests or offline replay. Runtime is O(1). No
+ * external state is mutated.
+ * @param[in] theme {PiUsereqSettingsTheme} Callback-local pi theme adapter.
+ * @return {SettingsListTheme} Settings-list theme used by pi-usereq menus.
+ * @satisfies REQ-151, REQ-156
+ */
+function buildPiUsereqSettingsListTheme(
+  theme: PiUsereqSettingsTheme,
+): SettingsListTheme {
+  try {
+    const sharedTheme = getSettingsListTheme();
+    void sharedTheme.label("", false);
+    void sharedTheme.value("", false);
+    void sharedTheme.description("");
+    void sharedTheme.cursor;
+    void sharedTheme.hint("");
+    return sharedTheme;
+  } catch {
+    return buildFallbackPiUsereqSettingsListTheme(theme);
+  }
+}
+
+/**
+ * @brief Formats the settings-menu title with active-theme semantics.
+ * @details Applies the callback-local `accent` token and bold styling on every
+ * rebuild so custom-menu titles stay synchronized with live theme changes.
+ * Runtime is O(n) in title length. No external state is mutated.
+ * @param[in] theme {PiUsereqSettingsTheme} Callback-local pi theme adapter.
+ * @param[in] title {string} Menu title.
+ * @return {string} Styled title text.
+ * @satisfies REQ-151, REQ-156
+ */
+function formatPiUsereqSettingsMenuTitle(
+  theme: PiUsereqSettingsTheme,
+  title: string,
+): string {
+  return theme.fg("accent", theme.bold(title));
+}
+
+/**
+ * @brief Closes a settings menu immediately with one selected action identifier.
+ * @details Provides the submenu callback used by `SettingsList` so pressing Enter on any menu row resolves the outer custom UI promise with the row identifier. Runtime is O(1). Side effects are limited to one custom-UI completion callback.
+ * @param[in] choiceId {string} Stable choice identifier to emit.
+ * @param[in] done {(value?: string) => void} Outer custom-UI completion callback.
+ * @return {Component} Immediate-completion submenu component.
+ */
+function createImmediateSelectionComponent(choiceId: string, done: (value?: string) => void): Component {
+  queueMicrotask(() => {
+    done(choiceId);
+  });
+  return {
+    render(): string[] {
+      return [];
+    },
+    invalidate(): void {
+      return;
+    },
+  };
+}
+
+/**
+ * @brief Builds `SettingsList` items from one menu-choice vector.
+ * @details Copies labels, current values, and descriptions into `SettingItem` records and attaches a submenu that resolves the outer custom UI with the selected choice identifier. Runtime is O(n) in choice count. No external state is mutated.
+ * @param[in] choices {PiUsereqSettingsMenuChoice[]} Ordered menu-choice vector.
+ * @param[in] done {(value?: string) => void} Outer custom-UI completion callback.
+ * @return {SettingItem[]} `SettingsList` item vector.
+ */
+function buildSettingItems(
+  choices: PiUsereqSettingsMenuChoice[],
+  done: (value?: string) => void,
+): SettingItem[] {
+  return choices.map((choice) => ({
+    id: choice.id,
+    label: choice.label,
+    description: choice.description,
+    currentValue: choice.value,
+    submenu: () => createImmediateSelectionComponent(choice.id, done),
+  }));
+}
+
+/**
+ * @brief Renders one shared pi-usereq settings menu and resolves the selected action.
+ * @details Uses `ctx.ui.custom(...)` plus `SettingsList` so every configuration menu shares pi.dev styling, right-aligned current values, circular scrolling, and bottom-line descriptions. The returned custom component also exposes an offline bridge for deterministic tests and debug harnesses. Runtime is O(n) in visible choice count plus user interaction cost. Side effects are limited to transient custom-UI rendering.
+ * @param[in] ctx {ExtensionCommandContext} Active command context.
+ * @param[in] title {string} Menu title displayed in the heading and offline bridge.
+ * @param[in] choices {PiUsereqSettingsMenuChoice[]} Ordered menu-choice vector.
+ * @return {Promise<string | undefined>} Selected choice identifier or `undefined` when cancelled.
+ * @satisfies REQ-151, REQ-152, REQ-153, REQ-154, REQ-156
+ */
+export async function showPiUsereqSettingsMenu(
+  ctx: ExtensionCommandContext,
+  title: string,
+  choices: PiUsereqSettingsMenuChoice[],
+): Promise<string | undefined> {
+  return ctx.ui.custom<string | undefined>((tui, theme, _keybindings, done) => {
+    const container = new Container();
+    const titleText = new Text(
+      formatPiUsereqSettingsMenuTitle(theme, title),
+      0,
+      0,
+    );
+    const settingsList = new SettingsList(
+      buildSettingItems(choices, done),
+      Math.min(Math.max(choices.length, 1), 12),
+      buildPiUsereqSettingsListTheme(theme),
+      () => undefined,
+      () => done(undefined),
+    );
+    container.addChild(titleText);
+    container.addChild(new Text("", 0, 0));
+    container.addChild(settingsList);
+
+    const component: PiUsereqSettingsMenuComponent = {
+      render(width: number): string[] {
+        return container.render(width);
+      },
+      invalidate(): void {
+        container.invalidate();
+        titleText.setText(formatPiUsereqSettingsMenuTitle(theme, title));
+      },
+      handleInput(data: string): void {
+        settingsList.handleInput(data);
+        tui.requestRender();
+      },
+      __piUsereqSettingsMenu: {
+        title,
+        choices,
+        selectByLabel(label: string): boolean {
+          const choice = choices.find(
+            (candidate) => candidate.label === label || candidate.id === label,
+          );
+          if (!choice) {
+            return false;
+          }
+          done(choice.id);
+          return true;
+        },
+        cancel(): void {
+          done(undefined);
+        },
+      },
+    };
+    return component;
+  });
+}