@narumitw/pi-files 0.0.0-stage → 0.1.0

package/src/file-context.ts

@@ -0,0 +1,321 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, open, readdir, realpath } from "node:fs/promises";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import type { GitFileContext, GitProjectInfo, GitRevisionFile } from "./git-context.js";
+
+const DEFAULT_MAX_FILES = 5_000;
+const DEFAULT_MAX_BYTES = 1_000_000;
+export const MAX_QUOTE_BYTES = 50_000;
+export const MAX_QUOTE_LINES = 500;
+export const MAX_PENDING_QUOTES = 8;
+export const MAX_PENDING_QUOTE_BYTES = 100_000;
+const IGNORED_DIRECTORIES = new Set([
+  ".git",
+  ".hg",
+  ".svn",
+  ".next",
+  "build",
+  "coverage",
+  "dist",
+  "node_modules",
+  "target",
+]);
+
+export interface FileQuoteGitProvenance {
+  head: string;
+  branch?: string;
+  status?: string;
+  revision?: string;
+  blob?: string;
+  contentSha256: string;
+  source?: "worktree" | "revision" | "git_diff";
+  base?: string;
+}
+
+export type FileQuoteGitProvenanceInput = Omit<FileQuoteGitProvenance, "contentSha256">;
+
+export interface FileQuote {
+  path: string;
+  startLine: number;
+  endLine: number;
+  text: string;
+  git?: FileQuoteGitProvenance;
+}
+
+export interface LoadedProjectTextFile {
+  path: string;
+  lines: string[];
+}
+
+interface DiscoveryOptions {
+  maxFiles?: number;
+  signal?: AbortSignal;
+}
+
+interface LoadOptions {
+  maxBytes?: number;
+  beforeOpen?: () => Promise<void>;
+  signal?: AbortSignal;
+}
+
+export async function discoverProjectFiles(root: string, options: DiscoveryOptions = {}): Promise<string[]> {
+  const maxFiles = Math.max(1, options.maxFiles ?? DEFAULT_MAX_FILES);
+  const files: string[] = [];
+  options.signal?.throwIfAborted();
+
+  const canonicalRoot = await realpath(root);
+  const directories: Array<{ directory: string; prefix: string }> = [{ directory: canonicalRoot, prefix: "" }];
+  options.signal?.throwIfAborted();
+
+  for (let index = 0; index < directories.length && files.length < maxFiles; index += 1) {
+    options.signal?.throwIfAborted();
+    const current = directories[index];
+    if (!current) break;
+    const { directory, prefix } = current;
+    const entries = (await readdir(directory, { withFileTypes: true })).sort((left, right) =>
+      compareStrings(left.name, right.name),
+    );
+    options.signal?.throwIfAborted();
+    for (const entry of entries) {
+      options.signal?.throwIfAborted();
+      if (IGNORED_DIRECTORIES.has(entry.name) || entry.isSymbolicLink()) continue;
+      const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
+      const absolutePath = resolve(directory, entry.name);
+      if (entry.isDirectory()) {
+        directories.push({ directory: absolutePath, prefix: relativePath });
+      } else if (entry.isFile()) {
+        files.push(relativePath);
+        if (files.length >= maxFiles) break;
+      }
+    }
+  }
+  options.signal?.throwIfAborted();
+  return files.sort(compareStrings);
+}
+
+export async function loadProjectTextFile(
+  root: string,
+  projectPath: string,
+  options: LoadOptions = {},
+): Promise<LoadedProjectTextFile> {
+  options.signal?.throwIfAborted();
+  if (!projectPath || isAbsolute(projectPath)) throw new Error("File path is outside the project");
+  const canonicalRoot = await realpath(root);
+  options.signal?.throwIfAborted();
+  const candidate = resolve(canonicalRoot, projectPath);
+  if (!isInside(canonicalRoot, candidate)) throw new Error("File path is outside the project");
+
+  let canonicalFile: string;
+  try {
+    canonicalFile = await realpath(candidate);
+  } catch (error: unknown) {
+    throw new Error(`Cannot open ${projectPath}: ${formatError(error)}`);
+  }
+  options.signal?.throwIfAborted();
+  if (!isInside(canonicalRoot, canonicalFile)) throw new Error("File path is outside the project");
+  const info = await lstat(canonicalFile);
+  options.signal?.throwIfAborted();
+  if (!info.isFile()) throw new Error(`${projectPath} is not a regular file`);
+
+  const maxBytes = Math.max(1, options.maxBytes ?? DEFAULT_MAX_BYTES);
+  if (info.size > maxBytes) throw new Error(`${projectPath} exceeds ${maxBytes} bytes`);
+  await options.beforeOpen?.();
+  options.signal?.throwIfAborted();
+  let file: Awaited<ReturnType<typeof open>>;
+  try {
+    file = await open(canonicalFile, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+  } catch (error: unknown) {
+    throw new Error(`Cannot safely open ${projectPath}: ${formatError(error)}`);
+  }
+  try {
+    options.signal?.throwIfAborted();
+    const openedInfo = await file.stat();
+    options.signal?.throwIfAborted();
+    if (!openedInfo.isFile()) throw new Error(`${projectPath} is not a regular file`);
+    if (openedInfo.dev !== info.dev || openedInfo.ino !== info.ino) {
+      throw new Error(`${projectPath} changed while it was being opened safely`);
+    }
+    if (openedInfo.size > maxBytes) throw new Error(`${projectPath} exceeds ${maxBytes} bytes`);
+    const buffer = Buffer.alloc(maxBytes + 1);
+    let offset = 0;
+    while (offset < buffer.length) {
+      options.signal?.throwIfAborted();
+      const { bytesRead } = await file.read(buffer, offset, buffer.length - offset, offset);
+      options.signal?.throwIfAborted();
+      if (bytesRead === 0) break;
+      offset += bytesRead;
+    }
+    if (offset > maxBytes) throw new Error(`${projectPath} exceeds ${maxBytes} bytes`);
+    const contents = buffer.subarray(0, offset);
+    if (contents.includes(0)) throw new Error(`${projectPath} appears to be binary`);
+    return {
+      path: projectPath.replaceAll("\\", "/"),
+      lines: normalizeTextLines(contents.toString("utf8")),
+    };
+  } finally {
+    await file.close();
+  }
+}
+
+export function createFileQuote(
+  path: string,
+  lines: readonly string[],
+  anchorIndex: number,
+  cursorIndex: number,
+  git?: FileQuoteGitProvenanceInput,
+): FileQuote {
+  if (lines.length === 0) throw new Error("Cannot quote an empty file");
+  const startIndex = Math.max(0, Math.min(anchorIndex, cursorIndex, lines.length - 1));
+  const endIndex = Math.max(0, Math.min(Math.max(anchorIndex, cursorIndex), lines.length - 1));
+  const text = lines.slice(startIndex, endIndex + 1).join("\n");
+  return createFileQuoteSnapshot(path, startIndex + 1, endIndex + 1, text, git);
+}
+
+export function createFileQuoteSnapshot(
+  path: string,
+  startLine: number,
+  endLine: number,
+  text: string,
+  git?: FileQuoteGitProvenanceInput,
+): FileQuote {
+  if (!Number.isSafeInteger(startLine) || !Number.isSafeInteger(endLine) || startLine < 1) {
+    throw new Error("Quote lines must be positive integers");
+  }
+  if (endLine < startLine) throw new Error("Quote end line precedes its start line");
+  if (text.split("\n").length > MAX_QUOTE_LINES) {
+    throw new Error(`Quote exceeds ${MAX_QUOTE_LINES} lines`);
+  }
+  if (Buffer.byteLength(text, "utf8") > MAX_QUOTE_BYTES) {
+    throw new Error(`Quote exceeds ${MAX_QUOTE_BYTES} bytes`);
+  }
+  return {
+    path,
+    startLine,
+    endLine,
+    text,
+    ...(git
+      ? {
+          git: {
+            head: git.head,
+            ...(git.branch !== undefined ? { branch: git.branch } : {}),
+            ...(git.status !== undefined ? { status: git.status } : {}),
+            ...(git.revision !== undefined ? { revision: git.revision } : {}),
+            ...(git.blob !== undefined ? { blob: git.blob } : {}),
+            contentSha256: createHash("sha256").update(text, "utf8").digest("hex"),
+            ...(git.source !== undefined ? { source: git.source } : {}),
+            ...(git.base !== undefined ? { base: git.base } : {}),
+          },
+        }
+      : {}),
+  };
+}
+
+/** Capture the exact worktree or historical preview with selection-time provenance. */
+export function createPreviewQuote(
+  file: LoadedProjectTextFile,
+  anchor: number,
+  cursor: number,
+  project?: GitProjectInfo,
+  git?: GitFileContext,
+  revision?: GitRevisionFile,
+): FileQuote {
+  return createFileQuote(
+    file.path,
+    file.lines,
+    anchor,
+    cursor,
+    project
+      ? {
+          head: project.head,
+          branch: project.branch,
+          status: revision ? "historical" : (git?.status?.label ?? "clean"),
+          revision: revision?.revision,
+          blob: revision?.blob ?? git?.blob,
+          source: revision ? "revision" : "worktree",
+          base: revision ? undefined : "HEAD",
+        }
+      : undefined,
+  );
+}
+
+export function appendPendingQuote(current: readonly FileQuote[], quote: FileQuote): FileQuote[] {
+  if (current.length >= MAX_PENDING_QUOTES) {
+    throw new Error(`File Context supports at most ${MAX_PENDING_QUOTES} pending quotes`);
+  }
+  const totalBytes = [...current, quote].reduce((total, item) => total + Buffer.byteLength(item.text, "utf8"), 0);
+  if (totalBytes > MAX_PENDING_QUOTE_BYTES) {
+    throw new Error(`Pending quotes exceed ${MAX_PENDING_QUOTE_BYTES} bytes`);
+  }
+  return [...current, quote];
+}
+
+export function formatPromptWithQuote(prompt: string, quote: FileQuote): string {
+  return formatPromptWithQuotes(prompt, [quote]);
+}
+
+export function formatPromptWithQuotes(prompt: string, quotes: readonly FileQuote[]): string {
+  if (quotes.length === 0) return prompt;
+  return `${formatQuoteContext(quotes)}\n\n${prompt}`;
+}
+
+export function formatQuoteContext(quotes: readonly FileQuote[]): string {
+  const blocks = quotes.map((quote) => {
+    const path = escapeXml(quote.path);
+    const text = escapeXml(quote.text);
+    const attributes = [
+      `path="${path}"`,
+      `lines="${quote.startLine}-${quote.endLine}"`,
+      ...formatGitAttributes(quote.git),
+    ].join(" ");
+    return `<user_file_quote ${attributes}>\n${text}\n</user_file_quote>`;
+  });
+  const description =
+    quotes.length === 1
+      ? "The user intentionally selected the file excerpt above."
+      : "The user intentionally selected the file excerpts above.";
+  return `${blocks.join("\n\n")}\n\n${description}`;
+}
+
+function normalizeTextLines(contents: string): string[] {
+  if (contents === "") return [];
+  const lines = contents.replaceAll("\r\n", "\n").replaceAll("\r", "\n").split("\n");
+  if (lines.at(-1) === "") lines.pop();
+  return lines;
+}
+
+function compareStrings(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function isInside(root: string, candidate: string): boolean {
+  const result = relative(root, candidate);
+  return result === "" || (!result.startsWith(`..${sep}`) && result !== ".." && !isAbsolute(result));
+}
+
+function formatGitAttributes(git: FileQuoteGitProvenance | undefined): string[] {
+  if (!git) return [];
+  return [
+    ["git_head", git.head],
+    ["git_branch", git.branch],
+    ["git_status", git.status],
+    ["git_revision", git.revision],
+    ["git_blob", git.blob],
+    ["content_sha256", git.contentSha256],
+    ["source", git.source],
+    ["git_base", git.base],
+  ].flatMap(([name, value]) => (value ? [`${name}="${escapeXml(value)}"`] : []));
+}
+
+function escapeXml(value: string): string {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&apos;");
+}
+
+function formatError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/file-search.ts

@@ -0,0 +1,246 @@
+import { safeTerminalText } from "./file-browser.js";
+
+const MAX_SEARCH_QUERY_LENGTH = 256;
+const MAX_SEARCH_QUERY_PARTS = 8;
+const PATH_SCORE_PENALTY = 50;
+const PREFIX_SCORE = 100;
+const SUBSTRING_SCORE = 200;
+const TYPO_SCORE = 300;
+const SUBSEQUENCE_SCORE = 400;
+const TOKENIZED_SCORE = 500;
+const NO_MATCH = Number.POSITIVE_INFINITY;
+const PATH_PART_SEPARATOR = /[/._\-\s]+/u;
+
+interface ProjectFileEntry {
+  path: string;
+  normalizedPath: string;
+  normalizedBasename: string;
+  basenameParts: readonly string[];
+  pathParts: readonly string[];
+  originalIndex: number;
+}
+
+interface RankedProjectFile {
+  path: string;
+  score: number;
+  originalIndex: number;
+}
+
+type TypoDistanceCache = Map<string, Map<string, number | undefined>>;
+
+export class ProjectFileSearch {
+  private readonly files: readonly string[];
+  private readonly entries: readonly ProjectFileEntry[];
+
+  constructor(files: readonly string[]) {
+    this.files = [...files];
+    this.entries = this.files.map((path, originalIndex) => {
+      const normalizedPath = safeTerminalText(path).toLowerCase();
+      const normalizedBasename = normalizedPath.slice(normalizedPath.lastIndexOf("/") + 1);
+      return {
+        path,
+        normalizedPath,
+        normalizedBasename,
+        basenameParts: splitPathParts(normalizedBasename),
+        pathParts: splitPathParts(normalizedPath),
+        originalIndex,
+      };
+    });
+  }
+
+  search(query: string): string[] {
+    const trimmedQuery = safeTerminalText(query).trim();
+    if (!trimmedQuery) return [...this.files];
+    if (trimmedQuery.length > MAX_SEARCH_QUERY_LENGTH) return [];
+    const normalizedQuery = trimmedQuery.toLowerCase();
+    const queryParts = splitPathParts(normalizedQuery);
+    const typoDistanceCache: TypoDistanceCache = new Map();
+
+    return this.entries
+      .flatMap((entry): RankedProjectFile[] => {
+        const score = scoreEntry(normalizedQuery, queryParts, entry, typoDistanceCache);
+        return Number.isFinite(score) ? [{ path: entry.path, score, originalIndex: entry.originalIndex }] : [];
+      })
+      .sort((left, right) => left.score - right.score || left.originalIndex - right.originalIndex)
+      .map((result) => result.path);
+  }
+}
+
+function scoreEntry(
+  query: string,
+  queryParts: readonly string[],
+  entry: ProjectFileEntry,
+  typoDistanceCache: TypoDistanceCache,
+): number {
+  const basenameScore = scoreField(query, queryParts, entry.normalizedBasename, entry.basenameParts, typoDistanceCache);
+  const pathScore = scoreField(query, queryParts, entry.normalizedPath, entry.pathParts, typoDistanceCache);
+  return Math.min(basenameScore, pathScore + PATH_SCORE_PENALTY);
+}
+
+function scoreField(
+  query: string,
+  queryParts: readonly string[],
+  text: string,
+  textParts: readonly string[],
+  typoDistanceCache: TypoDistanceCache,
+): number {
+  const directScore = scoreText(query, text);
+  if (directScore < TYPO_SCORE) return directScore;
+  const typoScore = scoreTypo(query, textParts, typoDistanceCache);
+  if (Number.isFinite(typoScore)) return Math.min(directScore, typoScore);
+  if (Number.isFinite(directScore)) return directScore;
+  return scoreTokenized(queryParts, textParts, typoDistanceCache);
+}
+
+function scoreTokenized(
+  queryParts: readonly string[],
+  candidateParts: readonly string[],
+  typoDistanceCache: TypoDistanceCache,
+): number {
+  if (queryParts.length < 2 || queryParts.length > MAX_SEARCH_QUERY_PARTS) return NO_MATCH;
+
+  let totalScore = TOKENIZED_SCORE;
+  for (const queryPart of queryParts) {
+    let bestDirectScore = NO_MATCH;
+    for (let index = 0; index < candidateParts.length; index += 1) {
+      bestDirectScore = Math.min(bestDirectScore, scoreText(queryPart, candidateParts[index] ?? "") + index * 2);
+    }
+    const bestPartScore =
+      bestDirectScore < TYPO_SCORE
+        ? bestDirectScore
+        : Math.min(bestDirectScore, scoreTypo(queryPart, candidateParts, typoDistanceCache));
+    if (!Number.isFinite(bestPartScore)) return NO_MATCH;
+    totalScore += bestPartScore;
+  }
+  return totalScore;
+}
+
+function scoreText(query: string, text: string): number {
+  if (query === text) return 0;
+  if (text.startsWith(query)) return PREFIX_SCORE + lengthPenalty(query, text);
+
+  const substringIndex = text.indexOf(query);
+  if (substringIndex >= 0) {
+    return SUBSTRING_SCORE + substringIndex * 2 + lengthPenalty(query, text);
+  }
+
+  return scoreSubsequence(query, text);
+}
+
+function scoreSubsequence(query: string, text: string): number {
+  let queryIndex = 0;
+  let firstMatch = -1;
+  let previousMatch = -1;
+  let gaps = 0;
+  let boundaryMatches = 0;
+  let consecutiveMatches = 0;
+
+  for (let textIndex = 0; textIndex < text.length && queryIndex < query.length; textIndex += 1) {
+    if (text[textIndex] !== query[queryIndex]) continue;
+    if (firstMatch < 0) firstMatch = textIndex;
+    if (previousMatch >= 0) {
+      const gap = textIndex - previousMatch - 1;
+      gaps += gap;
+      if (gap === 0) consecutiveMatches += 1;
+    }
+    if (textIndex === 0 || PATH_PART_SEPARATOR.test(text[textIndex - 1] ?? "")) {
+      boundaryMatches += 1;
+    }
+    previousMatch = textIndex;
+    queryIndex += 1;
+  }
+
+  if (queryIndex !== query.length) return NO_MATCH;
+  return (
+    SUBSEQUENCE_SCORE +
+    gaps * 3 +
+    firstMatch * 2 +
+    lengthPenalty(query, text) -
+    boundaryMatches * 8 -
+    consecutiveMatches
+  );
+}
+
+function scoreTypo(query: string, parts: readonly string[], typoDistanceCache: TypoDistanceCache): number {
+  const maxDistance = allowedTypoDistance(query.length);
+  if (maxDistance === 0) return NO_MATCH;
+
+  let bestScore = NO_MATCH;
+  for (let index = 0; index < parts.length; index += 1) {
+    const part = parts[index] ?? "";
+    if (Math.abs(query.length - part.length) > maxDistance) continue;
+    const distance = cachedTypoDistance(query, part, maxDistance, typoDistanceCache);
+    if (distance === undefined || distance === 0) continue;
+    bestScore = Math.min(bestScore, TYPO_SCORE + distance * 20 + index * 2 + Math.abs(query.length - part.length));
+  }
+  return bestScore;
+}
+
+function cachedTypoDistance(
+  query: string,
+  part: string,
+  maxDistance: number,
+  cache: TypoDistanceCache,
+): number | undefined {
+  let queryCache = cache.get(query);
+  if (!queryCache) {
+    queryCache = new Map();
+    cache.set(query, queryCache);
+  }
+  if (queryCache.has(part)) return queryCache.get(part);
+  const distance = boundedDamerauLevenshtein(query, part, maxDistance);
+  queryCache.set(part, distance);
+  return distance;
+}
+
+function boundedDamerauLevenshtein(left: string, right: string, maxDistance: number): number | undefined {
+  if (Math.abs(left.length - right.length) > maxDistance) return undefined;
+
+  const unreachable = maxDistance + 1;
+  let previousPrevious = Array.from({ length: left.length + 1 }, () => unreachable);
+  let previous = Array.from({ length: left.length + 1 }, (_, index) => (index <= maxDistance ? index : unreachable));
+
+  for (let rightIndex = 1; rightIndex <= right.length; rightIndex += 1) {
+    const current = Array.from({ length: left.length + 1 }, () => unreachable);
+    if (rightIndex <= maxDistance) current[0] = rightIndex;
+    const start = Math.max(1, rightIndex - maxDistance);
+    const end = Math.min(left.length, rightIndex + maxDistance);
+    for (let leftIndex = start; leftIndex <= end; leftIndex += 1) {
+      const substitutionCost = left[leftIndex - 1] === right[rightIndex - 1] ? 0 : 1;
+      current[leftIndex] = Math.min(
+        (previous[leftIndex] ?? unreachable) + 1,
+        (current[leftIndex - 1] ?? unreachable) + 1,
+        (previous[leftIndex - 1] ?? unreachable) + substitutionCost,
+      );
+      if (
+        leftIndex > 1 &&
+        rightIndex > 1 &&
+        left[leftIndex - 1] === right[rightIndex - 2] &&
+        left[leftIndex - 2] === right[rightIndex - 1]
+      ) {
+        current[leftIndex] = Math.min(
+          current[leftIndex] ?? unreachable,
+          (previousPrevious[leftIndex - 2] ?? unreachable) + 1,
+        );
+      }
+    }
+    previousPrevious = previous;
+    previous = current;
+  }
+
+  const distance = previous[left.length] ?? unreachable;
+  return distance <= maxDistance ? distance : undefined;
+}
+
+function allowedTypoDistance(queryLength: number): number {
+  if (queryLength < 5) return 0;
+  return queryLength < 10 ? 1 : 2;
+}
+
+function splitPathParts(value: string): string[] {
+  return value.split(PATH_PART_SEPARATOR).filter(Boolean);
+}
+
+function lengthPenalty(query: string, text: string): number {
+  return Math.max(0, text.length - query.length) / 100;
+}

package/src/files-menu.ts

@@ -0,0 +1,125 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { defineMenu, runMenu } from "@narumitw/pi-tui-kit";
+import type { ContextService } from "./context-service.js";
+import { displayPath } from "./scope/display.js";
+import type { ScopeService } from "./scope/edit-scope.js";
+
+type Screen = "main" | "status" | "help";
+type Action = "browse" | "review" | "scope" | "settings";
+
+export async function showFilesMenu(
+  ctx: ExtensionCommandContext,
+  context: ContextService,
+  scope: ScopeService,
+): Promise<void> {
+  if (ctx.mode !== "tui" || !ctx.hasUI) throw new Error("/files requires Pi TUI mode");
+  const signal = AbortSignal.any([context.signal(ctx), scope.signal(ctx), ...(ctx.signal ? [ctx.signal] : [])]);
+  const current = () => !signal.aborted;
+  const state = () => ({ context: context.getState(ctx), scope: scope.getView(ctx) });
+  let next: Action | undefined;
+  const menu = defineMenu<ReturnType<typeof state>, Screen, Action, ExtensionCommandContext>({
+    start: "main",
+    screens: {
+      main: ({ state }) => ({
+        kind: "actions",
+        title: "Files",
+        lines: [
+          `Next prompt context: ${state.context.quotes.length} snippets`,
+          state.scope.state === "inactive"
+            ? "Edit scope: unrestricted"
+            : state.scope.state === "blocked"
+              ? "Edit scope: unavailable · edits blocked"
+              : `Edit scope: ${state.scope.targets.length} allowed files`,
+        ],
+        items: [
+          {
+            id: "browse",
+            label: "Browse files",
+            description: "Preview files and attach context; does not grant edit permission",
+            action: "browse",
+          },
+          {
+            id: "review",
+            label: `Review queued context (${state.context.quotes.length})`,
+            description: "Inspect exact snapshots and remove snippets",
+            action: "review",
+            disabled: !state.context.quotes.length,
+          },
+          {
+            id: "scope",
+            label: "Manage edit scope",
+            description: "Select allowed targets, reserve a new file, or end the restriction",
+            action: "scope",
+          },
+          {
+            id: "settings",
+            label: "Settings",
+            description: "Browser shortcut and hidden-file discovery preference",
+            action: "settings",
+          },
+          { id: "status", label: "Status", description: "Review context and every allowed target", to: "status" },
+          { id: "help", label: "Help", description: "Read state lifetimes and the protection boundary", to: "help" },
+        ],
+        hint: "close",
+      }),
+      status: ({ state }) => ({
+        kind: "detail",
+        title: "Files Status",
+        lines: [
+          `Next prompt context: ${state.context.quotes.length}/${state.context.maximumQuotes} snippets · ${state.context.totalBytes}/${state.context.maximumBytes} bytes`,
+          `Browser shortcut: ${state.context.shortcut ?? "disabled"}`,
+          `Edit scope: ${state.scope.state}`,
+          ...(state.scope.error ? [state.scope.error] : []),
+          ...state.scope.targets.map(
+            (target) =>
+              `${displayPath(target.path)}${target.canonical !== target.path ? ` → ${displayPath(target.canonical)}` : ""}`,
+          ),
+          ...(state.scope.state === "inactive" ? [] : ["/files off explicitly ends the editing restriction."]),
+          "Reserved new-file targets are created only by a normal write call.",
+        ],
+        hint: "back",
+      }),
+      help: () => ({
+        kind: "detail",
+        title: "Files Help",
+        lines: [
+          "Context snapshots attach once to the next ordinary prompt; selecting context never grants edit permission.",
+          "Edit scope lasts until explicitly ended and is restored from the active session branch; selecting a target never loads its content.",
+          "An active restriction allows only stock readers and target-checked native write/edit. Shell, codemode, delegation, and custom tools are blocked.",
+          "This is an in-process guard, not an OS sandbox. The user-controlled external editor is outside native-tool enforcement.",
+          "/file-context [browse|remove] and /edit-scope or /scope [off] keep their existing workflows.",
+          "Do not load predecessor extensions with Files. Remove or disable their user and project resources, then reload.",
+          "Escape goes back. Ctrl+C closes transient UI without ending an active restriction.",
+        ],
+        hint: "back",
+      }),
+    },
+    actions: {
+      browse: () => {
+        next = "browse";
+        return { kind: "close" };
+      },
+      review: () => {
+        next = "review";
+        return { kind: "close" };
+      },
+      scope: () => {
+        next = "scope";
+        return { kind: "close" };
+      },
+      settings: () => {
+        next = "settings";
+        return { kind: "close" };
+      },
+    },
+  });
+  const result = await runMenu(ctx, menu, { signal, isCurrent: current, getState: state });
+  if (!current() || result.kind !== "closed") return;
+  if (next === "browse") await context.browse(ctx);
+  else if (next === "review") await context.open(ctx, "remove");
+  else if (next === "scope") await scope.open(ctx, signal);
+  else if (next === "settings") {
+    const { showFilesSettings } = await import("./files-settings.js");
+    if (current()) await showFilesSettings(ctx, context, scope);
+  }
+}