@opengsd/gsd-pi 1.0.0

package/src/resources/extensions/shared/layout-utils.ts

@@ -0,0 +1,75 @@
+/**
+ * ANSI-aware TUI layout utilities that depend on @gsd/pi-tui.
+ *
+ * Separated from format-utils.ts so that modules needing only pure
+ * formatting (e.g. HTML report generation) can import format-utils
+ * without pulling in the @gsd/pi-tui dependency — which fails when
+ * loaded outside jiti's alias resolution context.
+ */
+
+import { truncateToWidth, visibleWidth } from "@gsd/pi-tui";
+
+// ─── Layout Helpers ───────────────────────────────────────────────────────────
+
+/** Pad a string with trailing spaces to fill `width` (ANSI-aware). */
+export function padRight(content: string, width: number): string {
+  const vis = visibleWidth(content);
+  return content + " ".repeat(Math.max(0, width - vis));
+}
+
+/** Build a line with left-aligned and right-aligned content. */
+export function joinColumns(left: string, right: string, width: number): string {
+  const leftW = visibleWidth(left);
+  const rightW = visibleWidth(right);
+  if (leftW + rightW + 2 > width) {
+    return truncateToWidth(`${left}  ${right}`, width);
+  }
+  return left + " ".repeat(width - leftW - rightW) + right;
+}
+
+/** Center content within `width` (ANSI-aware). */
+export function centerLine(content: string, width: number): string {
+  const vis = visibleWidth(content);
+  if (vis >= width) return truncateToWidth(content, width);
+  const leftPad = Math.floor((width - vis) / 2);
+  return " ".repeat(leftPad) + content;
+}
+
+/** Join as many parts as fit within `width`, separated by `separator`. */
+export function fitColumns(parts: string[], width: number, separator = "  "): string {
+  const filtered = parts.filter(Boolean);
+  if (filtered.length === 0) return "";
+  let result = filtered[0];
+  for (let i = 1; i < filtered.length; i++) {
+    const candidate = `${result}${separator}${filtered[i]}`;
+    if (visibleWidth(candidate) > width) break;
+    result = candidate;
+  }
+  return truncateToWidth(result, width);
+}
+
+/**
+ * Merge two sets of lines into a side-by-side layout with a vertical divider.
+ *
+ * Each left line is padded to `leftWidth`, then joined with a styled divider
+ * and the corresponding right line. Output lines are truncated to `totalWidth`.
+ */
+export function mergeSideBySide(
+  leftLines: string[],
+  rightLines: string[],
+  leftWidth: number,
+  divider: string,
+  totalWidth: number,
+): string[] {
+  const maxLen = Math.max(leftLines.length, rightLines.length);
+  const merged: string[] = [];
+
+  for (let i = 0; i < maxLen; i++) {
+    const left = i < leftLines.length ? leftLines[i] : "";
+    const right = i < rightLines.length ? rightLines[i] : "";
+    const paddedLeft = padRight(left, leftWidth);
+    merged.push(truncateToWidth(paddedLeft + divider + right, totalWidth));
+  }
+
+  return merged;
+}

package/src/resources/extensions/shared/mod.ts

@@ -0,0 +1,31 @@
+// Barrel file — re-exports consumed by external modules
+
+export {
+	GLYPH,
+	INDENT,
+	STATUS_GLYPH,
+	STATUS_COLOR,
+} from "./ui.js";
+export type { ProgressStatus } from "./ui.js";
+
+export {
+	stripAnsi,
+	formatTokenCount,
+	formatDuration,
+	sparkline,
+	normalizeStringArray,
+	fileLink,
+} from "./format-utils.js";
+
+export {
+	padRight,
+	joinColumns,
+	centerLine,
+	fitColumns,
+} from "./layout-utils.js";
+
+export { shortcutDesc } from "./terminal.js";
+export { toPosixPath } from "./path-display.js";
+export { sanitizeError, maskEditorLine } from "./sanitize.js";
+export { formatDateShort, truncateWithEllipsis } from "./format-utils.js";
+export { splitFrontmatter, parseFrontmatterMap } from "./frontmatter.js";

package/src/resources/extensions/shared/next-action-ui.ts

@@ -0,0 +1,226 @@
+/**
+ * Shared next-action prompt for GSD extensions.
+ *
+ * Renders a consistent "step complete" UI at the end of every GSD stage:
+ *
+ *   ─────────────────────────────────────────
+ *   ✓  Phase 1 research complete
+ *
+ *      [caller summary lines]
+ *
+ *      [optional extra content block]
+ *
+ *   Files written:
+ *      .gsd/phases/01-foo/01-RESEARCH.md
+ *
+ *   › 1. Plan phase 1           ← recommended, pre-selected
+ *        Create PLAN.md files for execution
+ *
+ *     2. Not yet
+ *        Run /gsd-plan-phase 1 when ready.
+ *   ─────────────────────────────────────────
+ *
+ * Usage:
+ *
+ *   const choice = await showNextAction(ctx, {
+ *     title: "Phase 1 research complete",
+ *     summary: ["6 libraries evaluated", "Stack: Phaser 3 + TypeScript"],
+ *     files: ["/abs/path/to/01-RESEARCH.md"],
+ *     extra: ["Wave 1: 01-01, 01-02  (parallel)", "Wave 2: 01-03"],
+ *     actions: [
+ *       { id: "plan",  label: "Plan phase 1",   description: "Create PLAN.md files for execution", recommended: true },
+ *       { id: "later", label: "Discuss first",  description: "Capture constraints before planning" },
+ *     ],
+ *     notYetMessage: "Run /gsd-plan-phase 1 when ready.",
+ *   });
+ *
+ *   // choice is one of the action ids, or "not_yet"
+ *   if (choice === "plan") { ... }
+ *
+ * "Not yet" is always appended automatically as the last option.
+ * Pressing Escape also resolves as "not_yet".
+ */
+
+import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
+import { type Theme } from "@gsd/pi-coding-agent";
+import { Key, matchesKey, type TUI } from "@gsd/pi-tui";
+import { makeUI } from "./ui.js";
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+export interface NextAction {
+	/** Unique id returned when this action is chosen. */
+	id: string;
+	/** Short label shown in the list (e.g. "Plan phase 1"). */
+	label: string;
+	/** One-line description shown below the label. */
+	description: string;
+	/** Pre-selects this item and renders it with a (recommended) marker. At most one. */
+	recommended?: boolean;
+}
+
+export interface NextActionOptions {
+	/** Bold heading after the ✓ — e.g. "Phase 1 research complete". */
+	title: string;
+	/**
+	 * Stage-specific narrative lines rendered below the title.
+	 * Keep these short and informative.
+	 */
+	summary?: string[];
+	/**
+	 * Absolute paths to files that were written this step.
+	 * Displayed as relative paths from cwd when possible.
+	 */
+	files?: string[];
+	/**
+	 * Optional extra content rendered between the file list and the actions.
+	 * Each string is one display line — already formatted by the caller.
+	 */
+	extra?: string[];
+	/** The action choices. "Not yet" is always appended automatically. */
+	actions: NextAction[];
+	/**
+	 * Message shown in the "Not yet" description line.
+	 * e.g. "Run /gsd-plan-phase 1 when ready."
+	 */
+	notYetMessage?: string;
+	/**
+	 * Current working directory — used to make file paths relative.
+	 * Defaults to process.cwd().
+	 */
+	cwd?: string;
+}
+
+/**
+ * Show the next-action prompt and return the chosen action id, or "not_yet".
+ */
+export async function showNextAction(
+	ctx: ExtensionCommandContext,
+	opts: NextActionOptions,
+): Promise<string> {
+	const cwd = opts.cwd ?? process.cwd();
+	const notYetMessage = opts.notYetMessage ?? "Continue when ready.";
+
+	const allActions: NextAction[] = [
+		...opts.actions,
+		{ id: "not_yet", label: "Not yet", description: notYetMessage },
+	];
+
+	const recommendedIdx = allActions.findIndex((a) => a.recommended);
+	const defaultIdx = recommendedIdx >= 0 ? recommendedIdx : 0;
+
+	const relativeFiles = (opts.files ?? []).map((f) => {
+		try {
+			const rel = f.startsWith(cwd) ? f.slice(cwd.length).replace(/^\//, "") : f;
+			return rel || f;
+		} catch {
+			return f;
+		}
+	});
+
+	// Headless/non-interactive guard: avoid emitting interactive select requests
+	// in contexts where no human can answer (no UI, RPC/headless shims).
+	if (!isInteractiveUIContext(ctx)) {
+		return "not_yet";
+	}
+
+	const result = await ctx.ui.custom<string>((_tui: TUI, theme: Theme, _kb, done) => {
+		let cursorIdx = defaultIdx;
+		let cachedLines: string[] | undefined;
+
+		function refresh() { cachedLines = undefined; _tui.requestRender(); }
+
+		function handleInput(data: string) {
+			if (matchesKey(data, Key.up)) { cursorIdx = Math.max(0, cursorIdx - 1); refresh(); return; }
+			if (matchesKey(data, Key.down)) { cursorIdx = Math.min(allActions.length - 1, cursorIdx + 1); refresh(); return; }
+			const num = parseInt(data, 10);
+			if (!isNaN(num) && num >= 1 && num <= allActions.length) { done(allActions[num - 1].id); return; }
+			if (matchesKey(data, Key.enter) || matchesKey(data, Key.space)) { done(allActions[cursorIdx].id); return; }
+			if (matchesKey(data, Key.escape)) { done("not_yet"); return; }
+		}
+
+		function render(width: number): string[] {
+			if (cachedLines) return cachedLines;
+			const ui = makeUI(theme, width);
+			const lines: string[] = [];
+			const push = (...rows: string[][]) => { for (const r of rows) lines.push(...r); };
+
+			// ── Header — uses success colour to signal completion ────────────
+			// Note: next-action intentionally uses "success" for its bar/title
+			// to distinguish it from regular accent-coloured screens.
+			push(ui.bar());
+			push(ui.blank());
+			push(ui.header(`  ✓  ${opts.title}`));
+
+			// ── Summary ──────────────────────────────────────────────────────
+			if (opts.summary && opts.summary.length > 0) {
+				push(ui.blank());
+				for (const line of opts.summary) push(ui.subtitle(`     ${line}`));
+			}
+
+			// ── Files written ─────────────────────────────────────────────────
+			if (relativeFiles.length > 0) {
+				push(ui.blank());
+				push(ui.meta("  Files written:"));
+				for (const f of relativeFiles) push(ui.meta(`     ${f}`));
+			}
+
+			// ── Extra content ─────────────────────────────────────────────────
+			if (opts.extra && opts.extra.length > 0) {
+				push(ui.blank());
+				for (const line of opts.extra) push(ui.subtitle(`  ${line}`));
+			}
+
+			// ── Actions ───────────────────────────────────────────────────────
+			push(ui.blank());
+			for (let i = 0; i < allActions.length; i++) {
+				const action = allActions[i];
+				const isSelected = i === cursorIdx;
+				const isNotYet = action.id === "not_yet";
+				const tag = action.recommended ? "(recommended)" : undefined;
+
+				if (isSelected) {
+					push(ui.actionSelected(i + 1, action.label, action.description, tag));
+				} else if (isNotYet) {
+					push(ui.actionDim(i + 1, action.label, action.description));
+				} else {
+					push(ui.actionUnselected(i + 1, action.label, action.description, tag));
+				}
+				push(ui.blank());
+			}
+
+			// ── Footer ────────────────────────────────────────────────────────
+			const numHint = allActions.map((_, i) => `${i + 1}`).join("/");
+			push(ui.hints([`↑/↓ to choose`, `${numHint} to quick-select`, `enter to confirm`]));
+			push(ui.bar());
+
+			cachedLines = lines;
+			return lines;
+		}
+
+		return { render, invalidate: () => { cachedLines = undefined; }, handleInput };
+	});
+
+	// Fallback for RPC mode where ctx.ui.custom() returns undefined (#447).
+	// Fall back to ctx.ui.select() which IS implemented in RPC mode.
+	if (result === undefined || result === null) {
+		const labels = allActions.map(a => {
+			const tag = a.recommended ? " (recommended)" : "";
+			return `${a.label}${tag}: ${a.description}`;
+		});
+		const selected = await ctx.ui.select(opts.title, labels);
+		if (selected === undefined || selected === null) return "not_yet";
+		const idx = labels.indexOf(selected as string);
+		return idx >= 0 ? allActions[idx].id : "not_yet";
+	}
+
+	return result;
+}
+
+function isInteractiveUIContext(ctx: ExtensionCommandContext): boolean {
+	if (!ctx.hasUI) return false;
+	if (process.env.GSD_HEADLESS === "1") return false;
+	const uiMode = (ctx.ui as { mode?: string } | undefined)?.mode;
+	if (uiMode === "rpc" || uiMode === "headless") return false;
+	return true;
+}

package/src/resources/extensions/shared/path-display.ts

@@ -0,0 +1,19 @@
+/**
+ * Cross-platform path display for LLM-visible text.
+ *
+ * Paths injected into prompts, tool results, or extension messages must use
+ * forward slashes. Windows backslash paths cause bash failures when the model
+ * copies them into shell commands — bash interprets backslashes as escape chars.
+ *
+ * Use this ONLY for paths entering text the LLM or shell sees.
+ * Filesystem operations (fs.readFile, path.join, spawn cwd) handle native
+ * separators correctly and should NOT be normalized.
+ */
+
+/**
+ * Convert a filesystem path to forward-slash form for display in LLM text.
+ * No-op on Unix. On Windows converts `C:\Users\name` to `C:/Users/name`.
+ */
+export function toPosixPath(fsPath: string): string {
+  return fsPath.replaceAll("\\", "/");
+}

package/src/resources/extensions/shared/rtk-session-stats.ts

@@ -0,0 +1,248 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { formatTokenCount } from "./format-utils.js";
+import { buildRtkEnv, isRtkEnabled, resolveRtkBinaryPath } from "./rtk.js";
+
+const SESSION_BASELINES_FILE = "rtk-session-baselines.json";
+const CURRENT_SUMMARY_TTL_MS = 15_000;
+const CURRENT_SUMMARY_TIMEOUT_MS = 5_000;
+const MAX_BASELINE_SESSIONS = 200;
+
+export interface RtkGainSummary {
+  totalCommands: number;
+  totalInput: number;
+  totalOutput: number;
+  totalSaved: number;
+  avgSavingsPct: number;
+  totalTimeMs: number;
+  avgTimeMs: number;
+}
+
+export interface RtkSessionSavings {
+  commands: number;
+  inputTokens: number;
+  outputTokens: number;
+  savedTokens: number;
+  savingsPct: number;
+  totalTimeMs: number;
+  avgTimeMs: number;
+  updatedAt: string;
+}
+
+interface BaselineEntry {
+  summary: RtkGainSummary;
+  createdAt: string;
+  updatedAt: string;
+}
+
+interface BaselineStore {
+  version: 1;
+  sessions: Record<string, BaselineEntry>;
+}
+
+let cachedSummary: { at: number; binaryPath: string; summary: RtkGainSummary | null } | null = null;
+
+function getRuntimeDir(basePath: string): string {
+  return join(basePath, ".gsd", "runtime");
+}
+
+function getBaselinesPath(basePath: string): string {
+  return join(getRuntimeDir(basePath), SESSION_BASELINES_FILE);
+}
+
+function defaultStore(): BaselineStore {
+  return { version: 1, sessions: {} };
+}
+
+function loadBaselineStore(basePath: string): BaselineStore {
+  const path = getBaselinesPath(basePath);
+  if (!existsSync(path)) return defaultStore();
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf-8")) as Partial<BaselineStore>;
+    if (parsed.version !== 1 || typeof parsed.sessions !== "object" || parsed.sessions === null) {
+      return defaultStore();
+    }
+    return {
+      version: 1,
+      sessions: parsed.sessions as Record<string, BaselineEntry>,
+    };
+  } catch {
+    return defaultStore();
+  }
+}
+
+function saveBaselineStore(basePath: string, store: BaselineStore): void {
+  const runtimeDir = getRuntimeDir(basePath);
+  mkdirSync(runtimeDir, { recursive: true });
+
+  const entries = Object.entries(store.sessions)
+    .sort((left, right) => right[1].updatedAt.localeCompare(left[1].updatedAt))
+    .slice(0, MAX_BASELINE_SESSIONS);
+
+  const normalized: BaselineStore = {
+    version: 1,
+    sessions: Object.fromEntries(entries),
+  };
+
+  writeFileSync(getBaselinesPath(basePath), JSON.stringify(normalized, null, 2), "utf-8");
+}
+
+function normalizeSummary(raw: unknown): RtkGainSummary | null {
+  if (!raw || typeof raw !== "object") return null;
+  const summary = raw as Record<string, unknown>;
+  return {
+    totalCommands: Number(summary.total_commands ?? 0),
+    totalInput: Number(summary.total_input ?? 0),
+    totalOutput: Number(summary.total_output ?? 0),
+    totalSaved: Number(summary.total_saved ?? 0),
+    avgSavingsPct: Number(summary.avg_savings_pct ?? 0),
+    totalTimeMs: Number(summary.total_time_ms ?? 0),
+    avgTimeMs: Number(summary.avg_time_ms ?? 0),
+  };
+}
+
+export function readCurrentRtkGainSummary(env: NodeJS.ProcessEnv = process.env): RtkGainSummary | null {
+  if (!isRtkEnabled(env)) return null;
+
+  const binaryPath = resolveRtkBinaryPath({ env });
+  if (!binaryPath) return null;
+
+  if (
+    cachedSummary &&
+    cachedSummary.binaryPath === binaryPath &&
+    Date.now() - cachedSummary.at < CURRENT_SUMMARY_TTL_MS
+  ) {
+    return cachedSummary.summary;
+  }
+
+  const result = spawnSync(binaryPath, ["gain", "--all", "--format", "json"], {
+    encoding: "utf-8",
+    env: buildRtkEnv(env),
+    stdio: ["ignore", "pipe", "ignore"],
+    timeout: CURRENT_SUMMARY_TIMEOUT_MS,
+    // .cmd/.bat wrappers (used by fake-rtk in tests) require shell:true on Windows
+    shell: /\.(cmd|bat)$/i.test(binaryPath),
+  });
+
+  if (result.error || result.status !== 0) {
+    cachedSummary = { at: Date.now(), binaryPath, summary: null };
+    return null;
+  }
+
+  try {
+    const parsed = JSON.parse(result.stdout ?? "{}") as { summary?: unknown };
+    const summary = normalizeSummary(parsed.summary ?? null);
+    cachedSummary = { at: Date.now(), binaryPath, summary };
+    return summary;
+  } catch {
+    cachedSummary = { at: Date.now(), binaryPath, summary: null };
+    return null;
+  }
+}
+
+function computeSavingsDelta(current: RtkGainSummary, baseline: RtkGainSummary): RtkSessionSavings {
+  const commands = Math.max(0, current.totalCommands - baseline.totalCommands);
+  const inputTokens = Math.max(0, current.totalInput - baseline.totalInput);
+  const outputTokens = Math.max(0, current.totalOutput - baseline.totalOutput);
+  const savedTokens = Math.max(0, current.totalSaved - baseline.totalSaved);
+  const totalTimeMs = Math.max(0, current.totalTimeMs - baseline.totalTimeMs);
+  const avgTimeMs = commands > 0 ? Math.round(totalTimeMs / commands) : 0;
+  const savingsPct = inputTokens > 0 ? (savedTokens / inputTokens) * 100 : 0;
+
+  return {
+    commands,
+    inputTokens,
+    outputTokens,
+    savedTokens,
+    savingsPct,
+    totalTimeMs,
+    avgTimeMs,
+    updatedAt: new Date().toISOString(),
+  };
+}
+
+export function ensureRtkSessionBaseline(
+  basePath: string,
+  sessionId: string,
+  env: NodeJS.ProcessEnv = process.env,
+): RtkGainSummary | null {
+  if (!sessionId) return null;
+
+  const current = readCurrentRtkGainSummary(env);
+  if (!current) return null;
+
+  const store = loadBaselineStore(basePath);
+  const existing = store.sessions[sessionId];
+  if (existing) return existing.summary;
+
+  const now = new Date().toISOString();
+  store.sessions[sessionId] = {
+    summary: current,
+    createdAt: now,
+    updatedAt: now,
+  };
+  saveBaselineStore(basePath, store);
+  return current;
+}
+
+export function getRtkSessionSavings(
+  basePath: string,
+  sessionId: string | null | undefined,
+  env: NodeJS.ProcessEnv = process.env,
+): RtkSessionSavings | null {
+  if (!sessionId) return null;
+
+  const current = readCurrentRtkGainSummary(env);
+  if (!current) return null;
+
+  const store = loadBaselineStore(basePath);
+  const existing = store.sessions[sessionId];
+  if (!existing) {
+    const now = new Date().toISOString();
+    store.sessions[sessionId] = {
+      summary: current,
+      createdAt: now,
+      updatedAt: now,
+    };
+    saveBaselineStore(basePath, store);
+    return computeSavingsDelta(current, current);
+  }
+
+  if (
+    current.totalCommands < existing.summary.totalCommands ||
+    current.totalInput < existing.summary.totalInput ||
+    current.totalSaved < existing.summary.totalSaved
+  ) {
+    const now = new Date().toISOString();
+    store.sessions[sessionId] = {
+      summary: current,
+      createdAt: existing.createdAt,
+      updatedAt: now,
+    };
+    saveBaselineStore(basePath, store);
+    return computeSavingsDelta(current, current);
+  }
+
+  existing.updatedAt = new Date().toISOString();
+  saveBaselineStore(basePath, store);
+  return computeSavingsDelta(current, existing.summary);
+}
+
+export function clearRtkSessionBaseline(basePath: string, sessionId: string): void {
+  if (!sessionId) return;
+  const store = loadBaselineStore(basePath);
+  if (!(sessionId in store.sessions)) return;
+  delete store.sessions[sessionId];
+  saveBaselineStore(basePath, store);
+}
+
+export function formatRtkSavingsLabel(savings: RtkSessionSavings | null | undefined): string | null {
+  if (!savings) return null;
+  if (savings.commands <= 0) return "rtk: waiting for shell usage";
+  if (savings.inputTokens <= 0 && savings.outputTokens <= 0) {
+    return `rtk: active (${savings.commands} cmd${savings.commands === 1 ? "" : "s"})`;
+  }
+  return `rtk: ${formatTokenCount(savings.savedTokens)} saved (${Math.round(savings.savingsPct)}%)`;
+}

package/src/resources/extensions/shared/rtk-shared.ts

@@ -0,0 +1,58 @@
+import { existsSync } from "node:fs";
+import { homedir as osHomedir } from "node:os";
+import { delimiter, join } from "node:path";
+
+export const GSD_RTK_DISABLED_ENV = "GSD_RTK_DISABLED";
+export const GSD_RTK_PATH_ENV = "GSD_RTK_PATH";
+export const RTK_TELEMETRY_DISABLED_ENV = "RTK_TELEMETRY_DISABLED";
+
+export function isTruthy(value: string | undefined): boolean {
+  if (!value) return false;
+  const normalized = value.trim().toLowerCase();
+  return normalized === "1" || normalized === "true" || normalized === "yes";
+}
+
+export function isRtkEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  return !isTruthy(env[GSD_RTK_DISABLED_ENV]);
+}
+
+export function getManagedRtkDir(env: NodeJS.ProcessEnv = process.env): string {
+  return join(env.GSD_HOME || join(osHomedir(), ".gsd"), "agent", "bin");
+}
+
+export function getRtkBinaryName(platform: NodeJS.Platform = process.platform): string {
+  return platform === "win32" ? "rtk.exe" : "rtk";
+}
+
+export function getPathValue(env: NodeJS.ProcessEnv): string | undefined {
+  const pathKey = Object.keys(env).find((key) => key.toLowerCase() === "path");
+  return pathKey ? env[pathKey] : env.PATH;
+}
+
+export function resolvePathCandidates(pathValue: string | undefined): string[] {
+  if (!pathValue) return [];
+  return pathValue
+    .split(delimiter)
+    .map((part) => part.trim())
+    .filter(Boolean);
+}
+
+export function resolveSystemRtkPath(
+  pathValue: string | undefined,
+  platform: NodeJS.Platform = process.platform,
+): string | null {
+  const candidates = platform === "win32"
+    ? ["rtk.exe", "rtk.cmd", "rtk.bat", "rtk"]
+    : ["rtk"];
+
+  for (const dir of resolvePathCandidates(pathValue)) {
+    for (const candidate of candidates) {
+      const fullPath = join(dir, candidate);
+      if (existsSync(fullPath)) {
+        return fullPath;
+      }
+    }
+  }
+
+  return null;
+}