@narumitw/pi-files 0.0.0-stage → 0.1.0

package/src/scope/policy.ts

@@ -0,0 +1,55 @@
+import type { ExtensionAPI, ToolInfo } from "@earendil-works/pi-coding-agent";
+import type { ScopeState } from "./state.js";
+
+const READERS = new Set(["read", "ls", "find", "grep"]);
+const WRITERS = new Set(["write", "edit"]);
+
+/** Provenance is a stock-CLI compatibility check, not an implementation attestation. */
+export function isStockBuiltin(tool: ToolInfo | undefined, name: string): boolean {
+  return tool?.sourceInfo.source === "builtin" && tool.sourceInfo.path === `builtin:${name}`;
+}
+
+export function assertUsableLoadout(pi: Pick<ExtensionAPI, "getAllTools" | "getActiveTools" | "getSettings">): void {
+  const tools = pi.getAllTools();
+  const active = new Set(pi.getActiveTools());
+  const codemode = tools.find((tool) => tool.name === "codemode");
+  if (active.has("codemode") && isStockBuiltin(codemode, "codemode") && pi.getSettings().codemode?.mode === "only") {
+    throw new Error(
+      "Scope cannot start with active codemode.mode=only: codemode can bypass tool guards and hides the direct editing tools. Set Pi's codemode.mode to on and reload first; Scope does not change that setting.",
+    );
+  }
+  if (
+    ![...WRITERS].some(
+      (name) =>
+        active.has(name) &&
+        isStockBuiltin(
+          tools.find((tool) => tool.name === name),
+          name,
+        ),
+    )
+  ) {
+    throw new Error(
+      "Scope requires an active, unmodified built-in write or edit tool; custom replacements are unsupported",
+    );
+  }
+}
+
+export type ToolDecision = { kind: "pass" } | { kind: "target" } | { kind: "block"; reason: string };
+
+export function decideTool(name: string, tools: readonly ToolInfo[], scope: ScopeState): ToolDecision {
+  if (scope.state === "inactive") return { kind: "pass" };
+  const tool = tools.find((candidate) => candidate.name === name);
+  if (READERS.has(name) && isStockBuiltin(tool, name)) return { kind: "pass" };
+  if (scope.state === "blocked") {
+    return {
+      kind: "block",
+      reason:
+        scope.error ?? "Scope is not initialized; edits remain blocked. Use /scope to repair or /scope off to exit.",
+    };
+  }
+  if (WRITERS.has(name) && isStockBuiltin(tool, name)) return { kind: "target" };
+  return {
+    kind: "block",
+    reason: `${JSON.stringify(name)} is blocked while Scope is active. Only stock readers and target-checked write/edit calls are supported. Shell, codemode, delegation, and opaque tools require /scope off.`,
+  };
+}

package/src/scope/settings.ts

@@ -0,0 +1,138 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+
+export interface ScopeSettings {
+  showHiddenFiles: boolean;
+}
+
+// Keep one lexical key across first creation and atomic replacement. A file-identity
+// queue can change keys when a missing file appears through a parent symlink.
+// In-process ordering only, shared by stores with the same absolute lexical path.
+// This is not a cross-process lock and does not merge aliases of parent symlinks.
+const queues = new Map<string, Promise<void>>();
+
+function enqueue<T>(path: string, operation: () => Promise<T>): Promise<T> {
+  const result = (queues.get(path) ?? Promise.resolve()).then(operation);
+  const settled = result.then(
+    () => {},
+    () => {},
+  );
+  queues.set(path, settled);
+  void settled.then(() => {
+    if (queues.get(path) === settled) queues.delete(path);
+  });
+  return result;
+}
+
+function isMissing(error: unknown): boolean {
+  return !!error && typeof error === "object" && "code" in error && error.code === "ENOENT";
+}
+
+function validateDocument(value: unknown, path: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`Invalid Scope settings at ${JSON.stringify(path)}: expected a JSON object.`);
+  }
+  const document = value as Record<string, unknown>;
+  if (Object.hasOwn(document, "showHiddenFiles") && typeof document.showHiddenFiles !== "boolean") {
+    throw new Error(`Invalid Scope settings at ${JSON.stringify(path)}: showHiddenFiles must be a boolean.`);
+  }
+  return document;
+}
+
+async function readDocument(path: string): Promise<{ document: Record<string, unknown>; mode: number }> {
+  let stats: Awaited<ReturnType<typeof fs.lstat>>;
+  try {
+    stats = await fs.lstat(path);
+  } catch (error) {
+    if (isMissing(error)) return { document: {}, mode: 0o600 };
+    throw error;
+  }
+  // Atomic rename would replace a settings symlink instead of its referent.
+  // Reject it explicitly, including dangling links, rather than surprise the user.
+  if (stats.isSymbolicLink() || !stats.isFile()) {
+    throw new Error(`Scope settings must be a regular file, not a symlink: ${JSON.stringify(path)}.`);
+  }
+  const text = await fs.readFile(path, "utf8");
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error) {
+    throw new Error(`Invalid Scope settings JSON at ${JSON.stringify(path)}. Repair the file before saving.`, {
+      cause: error,
+    });
+  }
+  return { document: validateDocument(parsed, path), mode: Number(stats.mode) & 0o777 };
+}
+
+export class ScopeSettingsStore {
+  readonly #filePath: string;
+  #current: ScopeSettings = { showHiddenFiles: false };
+
+  constructor(filePath: string) {
+    this.#filePath = resolve(filePath);
+  }
+
+  get current(): ScopeSettings {
+    return { ...this.#current };
+  }
+
+  /** Side-effect-free load; a failed read leaves the last effective value intact. */
+  load(): Promise<ScopeSettings> {
+    return enqueue(this.#filePath, async () => {
+      const { document } = await readDocument(this.#filePath);
+      this.#current = { showHiddenFiles: (document.showHiddenFiles as boolean | undefined) ?? false };
+      return this.current;
+    });
+  }
+
+  /** Read the latest valid document and change only the owned field. */
+  saveShowHiddenFiles(value: boolean): Promise<ScopeSettings> {
+    return enqueue(this.#filePath, async () => {
+      if (typeof value !== "boolean") throw new Error("showHiddenFiles must be a boolean.");
+      const { document, mode } = await readDocument(this.#filePath);
+      const directory = dirname(this.#filePath);
+      await fs.mkdir(directory, { recursive: true });
+      const temporary = join(directory, `.${basename(this.#filePath)}.${process.pid}.${randomUUID()}.tmp`);
+      let handle: Awaited<ReturnType<typeof fs.open>> | undefined;
+      let ownedTemporary = false;
+      try {
+        handle = await fs.open(temporary, "wx", mode);
+        ownedTemporary = true;
+        await handle.writeFile(`${JSON.stringify({ ...document, showHiddenFiles: value }, null, 2)}\n`, "utf8");
+        await handle.close();
+        handle = undefined;
+        await fs.rename(temporary, this.#filePath);
+        ownedTemporary = false;
+      } catch (error) {
+        const failures: unknown[] = [error];
+        if (handle) {
+          try {
+            await handle.close();
+          } catch (closeError) {
+            failures.push(closeError);
+          }
+        }
+        if (ownedTemporary) {
+          try {
+            await fs.unlink(temporary);
+          } catch (cleanupError) {
+            if (!isMissing(cleanupError)) failures.push(cleanupError);
+          }
+        }
+        if (failures.length > 1) {
+          throw new AggregateError(failures, `Scope settings save and cleanup failed at ${JSON.stringify(temporary)}.`);
+        }
+        throw error;
+      }
+      // Publish runtime state only after the complete file was renamed successfully.
+      this.#current = { showHiddenFiles: value };
+      return this.current;
+    });
+  }
+
+  /** Drain prior operations; load/save promises carry their own errors to the caller. */
+  flush(): Promise<void> {
+    return enqueue(this.#filePath, async () => {});
+  }
+}

package/src/scope/state.ts

@@ -0,0 +1,91 @@
+import { isAbsolute, resolve } from "node:path";
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
+import type { ScopeTarget } from "./paths.js";
+
+// Persisted session identity must survive package renames or active guards would be lost.
+export const STATE_TYPE = "scope-state";
+export const MAX_TARGETS = 100;
+export const MAX_STATE_BYTES = 24_000;
+
+export interface ScopeSnapshot {
+  version: 1;
+  cwd: string;
+  targets: ScopeTarget[] | null;
+}
+
+export interface ScopeState {
+  state: "inactive" | "active" | "blocked";
+  entryId?: string;
+  snapshot?: ScopeSnapshot;
+  error?: string;
+}
+
+function absolutePath(value: unknown): value is string {
+  return typeof value === "string" && !value.includes("\0") && isAbsolute(value) && resolve(value) === value;
+}
+
+export function createSnapshot(cwd: string, targets: readonly ScopeTarget[] | null): ScopeSnapshot {
+  if (!absolutePath(cwd)) throw new Error("Scope workspace must be an absolute normalized path");
+  if (targets !== null && (targets.length === 0 || targets.length > MAX_TARGETS)) {
+    throw new Error(`Select between 1 and ${MAX_TARGETS} files; use /scope off to end the restriction`);
+  }
+  const unique = new Map<string, ScopeTarget>();
+  for (const target of targets ?? []) {
+    if (!absolutePath(target?.path) || !absolutePath(target?.canonical)) {
+      throw new Error("Scope targets must contain absolute normalized paths");
+    }
+    if (!unique.has(target.canonical)) unique.set(target.canonical, { path: target.path, canonical: target.canonical });
+  }
+  const snapshot: ScopeSnapshot = {
+    version: 1,
+    cwd,
+    targets:
+      targets === null
+        ? null
+        : [...unique.values()].sort((a, b) => (a.canonical < b.canonical ? -1 : a.canonical > b.canonical ? 1 : 0)),
+  };
+  if (Buffer.byteLength(JSON.stringify(snapshot)) > MAX_STATE_BYTES) {
+    throw new Error(`Scope selection exceeds the ${MAX_STATE_BYTES}-byte notice limit; select fewer files`);
+  }
+  return snapshot;
+}
+
+export function parseSnapshot(value: unknown): ScopeSnapshot {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("Invalid scope snapshot");
+  const data = value as Record<string, unknown>;
+  if (data.version !== 1 || typeof data.cwd !== "string" || (data.targets !== null && !Array.isArray(data.targets))) {
+    throw new Error("Invalid or unsupported scope snapshot");
+  }
+  return createSnapshot(data.cwd, data.targets as ScopeTarget[] | null);
+}
+
+export function restoreScope(branch: readonly SessionEntry[], cwd: string): ScopeState {
+  for (let index = branch.length - 1; index >= 0; index -= 1) {
+    const entry = branch[index];
+    if (entry.type !== "custom" || entry.customType !== STATE_TYPE) continue;
+    try {
+      const snapshot = parseSnapshot(entry.data);
+      if (snapshot.cwd !== resolve(cwd)) throw new Error("Saved scope belongs to another workspace");
+      return { state: snapshot.targets === null ? "inactive" : "active", snapshot, entryId: entry.id };
+    } catch (error) {
+      return {
+        state: "blocked",
+        entryId: entry.id,
+        error: `${error instanceof Error ? error.message : "Scope restoration failed"}. Edits remain blocked; repair with /scope or exit with /scope off.`,
+      };
+    }
+  }
+  return { state: "inactive" };
+}
+
+export function sameScope(left: ScopeSnapshot | undefined, right: ScopeSnapshot): boolean {
+  if (!left || left.cwd !== right.cwd || (left.targets === null) !== (right.targets === null)) return false;
+  if (left.targets === null || right.targets === null) return left.targets === right.targets;
+  return (
+    left.targets.length === right.targets.length &&
+    left.targets.every((target, index) => {
+      const other = right.targets?.[index];
+      return target.canonical === other?.canonical && target.path === other.path;
+    })
+  );
+}

package/src/scope/ui.ts

@@ -0,0 +1,106 @@
+import { stripVTControlCharacters } from "node:util";
+import type { ExtensionCommandContext, ExtensionUIContext, Theme } from "@earendil-works/pi-coding-agent";
+import type { Component, TUI } from "@earendil-works/pi-tui";
+import { HorizontalRule, hardWrapTerminalDocument, renderBoundedFrameLayout } from "@narumitw/pi-tui-kit";
+
+export function scopeFrame(
+  tui: TUI,
+  theme: Theme,
+  width: number,
+  title: string,
+  context: readonly string[],
+  content: readonly string[],
+  priorityRows: readonly number[],
+  focusedRow?: number,
+  hints: readonly string[] = [],
+) {
+  // The owned overlay uses terminal bounds; three spare rows are presentation
+  // space, not a prediction of the native editor dock or another widget's height.
+  const rows = Number.isFinite(tui.terminal.rows) ? Math.floor(tui.terminal.rows) : 24;
+  const rule = new HorizontalRule({ ruleStyle: (line) => theme.fg("border", line) });
+  return renderBoundedFrameLayout({
+    width,
+    maxRows: Math.max(1, rows - 3),
+    rule: rule.render(width)[0] ?? "",
+    title: [theme.fg("accent", theme.bold(title))],
+    context: context.flatMap((line) => hardWrapTerminalDocument(line, width).map((part) => theme.fg("muted", part))),
+    content,
+    hints: hints.flatMap((line) => exactRows(line, width).map((part) => theme.fg("dim", part))),
+    compactHint: hints[0] ? theme.fg("dim", hints[0]) : "",
+    priorityRows,
+    focusedRow,
+  });
+}
+
+export function exactRows(value: string, width: number): string[] {
+  return hardWrapTerminalDocument(value, width);
+}
+
+/**
+ * Pi does not expose the editor dock's allocated height to custom components.
+ * A full-width bottom overlay gives every Scope screen the real terminal bounds
+ * without inspecting, hiding, or changing another component's widgets or footer.
+ */
+export function scopeOverlayContext(ctx: ExtensionCommandContext): ExtensionCommandContext {
+  const ui = ctx.ui;
+  const custom: ExtensionUIContext["custom"] = (factory, options) =>
+    ui.custom(
+      (tui, theme, keys, done) => {
+        const created = factory(tui, theme, keys, done);
+        return created instanceof Promise
+          ? created.then((component) => boundedOverlay(component, tui, theme))
+          : boundedOverlay(created, tui, theme);
+      },
+      {
+        ...options,
+        overlay: true,
+        overlayOptions: {
+          anchor: "bottom-left",
+          width: "100%",
+          maxHeight: "100%",
+          margin: 0,
+        },
+      },
+    );
+  const scopedUI = new Proxy(ui, {
+    get(target, key) {
+      if (key === "custom") return custom;
+      const value = Reflect.get(target, key, target);
+      return typeof value === "function" ? value.bind(target) : value;
+    },
+  });
+  return new Proxy(ctx, {
+    get(target, key) {
+      if (key === "ui") return scopedUI;
+      const value = Reflect.get(target, key, target);
+      return typeof value === "function" ? value.bind(target) : value;
+    },
+  });
+}
+
+function boundedOverlay<C extends Component>(component: C, tui: TUI, theme: Theme): C {
+  const render = (width: number) => {
+    width = Number.isFinite(width) ? Math.max(0, Math.floor(width)) : 0;
+    if (width === 0) return [];
+    const lines = component.render(width);
+    const height = Math.max(1, Number.isFinite(tui.terminal.rows) ? Math.floor(tui.terminal.rows) : 24);
+    if (lines.length <= height) return lines;
+    // Scope and Kit menu frames already fit. Kit's fixed-height task loader can
+    // overflow tiny terminals: remove only its frame/spacing, then retain the
+    // task label through the public bounded frame without changing cancellation.
+    const rule = new HorizontalRule({ ruleStyle: (line) => theme.fg("border", line) }).render(width)[0] ?? "";
+    const framed = lines[0] === rule && lines.at(-1) === rule;
+    const content = (framed ? lines.slice(1, -1) : lines).filter((line) => stripVTControlCharacters(line).trim());
+    return renderBoundedFrameLayout({ width, maxRows: height, rule, title: [], content, priorityRows: [0] }).lines;
+  };
+  return new Proxy(component, {
+    get(target, key) {
+      if (key === "render") return render;
+      const value = Reflect.get(target, key, target);
+      return typeof value === "function" ? value.bind(target) : value;
+    },
+    set(target, key, value) {
+      return Reflect.set(target, key, value, target);
+    },
+  });
+}