Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

24.5 KB
Raw Blame
/**
 * Workspace files panel logic, kept DOM-free so it can be unit-tested:
 *   - the directory tree's shape — listings fetched lazily per directory and keyed by its
 *     Workspace-relative path ("" is the root), the set of open directories, and the flat
 *     row list the tree renders from the two (the row's own shape and the keyboard step over
 *     it are the UI package's `FileTree`'s, shared with the app's other file trees);
 *   - the search box's filter over the rows that are loaded;
 *   - which directory a dropped batch lands in;
 *   - when the panel is too narrow for a tree beside a preview, and how wide the tree pane
 *     may be dragged when it is not;
 *   - which files count as text — by extension, or by looking at their first bytes when
 *     the extension says nothing — and so can be previewed as text and edited in place, and
 *     how the read-only file browser previews a file by its name;
 *   - the persisted preferences (tree visibility, tree width, soft wrap) and the
 *     unsaved-changes decision;
 *   - what the panel's "add to conversation" puts in the composer — the `@path` reference,
 *     the fenced block a preview selection becomes, and where each of them may be spliced
 *     into a draft that is already half typed.
 */
import type { FileBrowserPreviewKind, FileTreeRow } from "@adelie/ui";
import type { WorkspaceFileEntry, WorkspaceSearchHit } from "@adelie/server/api";
import { joinWorkspacePath } from "./file-path";

// ------------------------------------------------------------------------------- layout

/** Below this panel width the tree and the preview no longer fit side by side. */
export const TREE_LAYOUT_MIN_WIDTH = 480;

/**
 * Whether the panel falls back to the single-column drill-down (tree or preview, never
 * both). An unmeasured width (0, before the first ResizeObserver callback) keeps the
 * two-pane default rather than flashing the fallback for a frame.
 */
export function isNarrowLayout(panelWidth: number): boolean {
  return panelWidth > 0 && panelWidth < TREE_LAYOUT_MIN_WIDTH;
}

/** Narrowest the tree pane may be dragged: below this a nested name is all ellipsis. */
export const TREE_MIN_WIDTH = 160;

/** Room the preview keeps whatever the tree is dragged to. */
export const PREVIEW_MIN_WIDTH = 240;

/**
 * The tree pane's width until the user drags the divider: about a third of the panel,
 * within bounds that keep names readable and leave the preview its room.
 */
export function defaultTreeWidth(panelWidth: number): number {
  return Math.max(168, Math.min(256, Math.round(panelWidth * 0.36)));
}

/** Widest the tree pane may be dragged at this panel width — never below the tree's own minimum, so a panel with no room for both still has a draggable range of zero rather than an inverted one. */
export function maxTreeWidth(panelWidth: number): number {
  return Math.max(TREE_MIN_WIDTH, panelWidth - PREVIEW_MIN_WIDTH);
}

/**
 * A tree-pane width brought within this panel's bounds. An unmeasured panel (0, before the
 * first ResizeObserver callback) has no ceiling to apply: clamping against it would size
 * the pane to the minimum for one frame and then jump.
 */
export function clampTreeWidth(width: number, panelWidth: number): number {
  const requested = Math.max(TREE_MIN_WIDTH, Math.round(Number.isFinite(width) ? width : 0));
  return panelWidth <= 0 ? requested : Math.min(maxTreeWidth(panelWidth), requested);
}

// -------------------------------------------------------------------------------- paths

/** The directory a Workspace-relative path sits in ("" for a root-level entry). */
export function parentDir(path: string): string {
  const i = path.lastIndexOf("/");
  return i >= 0 ? path.slice(0, i) : "";
}

export function baseName(path: string): string {
  const i = path.lastIndexOf("/");
  return i >= 0 ? path.slice(i + 1) : path;
}

/** Whether `path` is `dir` itself or lies inside it. */
export function isWithin(path: string, dir: string): boolean {
  return path === dir || path.startsWith(`${dir}/`);
}

/**
 * Where `path` is once `from` has moved to `to`: `to` itself, or the same place under it when
 * `path` lay inside `from`; null when the move did not touch it. A sibling that merely shares a
 * prefix (`docs-old` beside `docs`) is untouched.
 */
export function movedPath(path: string, from: string, to: string): string | null {
  return isWithin(path, from) ? `${to}${path.slice(from.length)}` : null;
}

/** The set with every path the move touched carried to its new place. */
export function movedSet(set: ReadonlySet<string>, from: string, to: string): Set<string> {
  return new Set([...set].map((p) => movedPath(p, from, to) ?? p));
}

/** The loaded listings with every directory the move touched filed under its new path. */
export function movedListings(
  listings: Listings,
  from: string,
  to: string,
): Map<string, readonly WorkspaceFileEntry[]> {
  return new Map([...listings].map(([dir, entries]) => [movedPath(dir, from, to) ?? dir, entries]));
}

/** What a new text file is called until it is named. */
export const DEFAULT_TEXT_FILE_NAME = "untitled.txt";

/**
 * The end of a file name's stem — where its extension starts, or its whole length when it has
 * none. The name field selects up to here, so typing replaces `untitled` and keeps `.txt`. A
 * leading dot (`.env`) is part of the stem, not an extension.
 */
export function stemEnd(name: string): number {
  const dot = name.lastIndexOf(".");
  return dot > 0 ? dot : name.length;
}

/**
 * A typed new-entry name made into the relative path it creates under the chosen directory:
 * trimmed, with the slashes at either end dropped (a folder named `drafts/` is `drafts`, and a
 * leading `/` would otherwise read as the Workspace root). A `/` inside stays: it creates the
 * folders in between.
 */
export function newEntryName(raw: string): string {
  return raw.trim().replace(/^\/+/, "").replace(/\/+$/, "");
}

/** The directories from the root down to the path's parent, root first: "a/b/c.txt" → ["", "a", "a/b"]. */
export function ancestorDirs(path: string): string[] {
  const out = [""];
  const segments = path.split("/").filter((s) => s !== "");
  for (let i = 1; i < segments.length; i += 1) out.push(segments.slice(0, i).join("/"));
  return out;
}

// --------------------------------------------------------------------------------- tree

/** Loaded directory listings by directory path ("" = the Workspace root). A missing key means "not fetched yet". */
export type Listings = ReadonlyMap<string, readonly WorkspaceFileEntry[]>;

/** Directories first, then by name — the order the server lists in, reapplied after a client-side insertion. */
export function sortEntries(entries: readonly WorkspaceFileEntry[]): WorkspaceFileEntry[] {
  return [...entries].sort((a, b) =>
    a.kind === b.kind ? a.name.localeCompare(b.name) : a.kind === "dir" ? -1 : 1,
  );
}

/**
 * The listings with `entry` in `dir`, inserted in sorted position and replacing a same-named
 * entry (an upload or a save overwrote it). Returns a new map; the input is left untouched.
 */
export function upsertEntry(
  listings: Listings,
  dir: string,
  entry: WorkspaceFileEntry,
): Map<string, readonly WorkspaceFileEntry[]> {
  const next = new Map(listings);
  const current = listings.get(dir) ?? [];
  next.set(dir, sortEntries([...current.filter((e) => e.name !== entry.name), entry]));
  return next;
}

/** The expanded set with every directory above `path` open, so the row for `path` is on screen. */
export function expandTo(expanded: ReadonlySet<string>, path: string): Set<string> {
  const next = new Set(expanded);
  for (const dir of ancestorDirs(path)) next.add(dir);
  return next;
}

/**
 * The expanded set with `dir` opened (its ancestors too, so it is reachable) or closed. Closing
 * leaves the descendants' own state alone: reopening the directory brings back the subtree the
 * way it was left.
 */
export function withExpanded(
  expanded: ReadonlySet<string>,
  dir: string,
  open: boolean,
): Set<string> {
  if (open) {
    const next = expandTo(expanded, dir);
    next.add(dir);
    return next;
  }
  const next = new Set(expanded);
  next.delete(dir);
  return next;
}

/** One rendered tree row: a shared tree row plus what the Workspace shows beside a file's name. */
export interface TreeRow extends FileTreeRow {
  sizeBytes: number;
  mtime: string;
}

/**
 * The rows the tree draws, top to bottom: a depth-first walk from the root (always open)
 * into every open directory whose listing has arrived. An open directory that is still
 * loading contributes its own row and no children.
 */
export function flattenTree(listings: Listings, expanded: ReadonlySet<string>): TreeRow[] {
  const rows: TreeRow[] = [];
  const walk = (dir: string, depth: number): void => {
    const entries = listings.get(dir) ?? [];
    for (const [index, entry] of entries.entries()) {
      const path = joinWorkspacePath(dir, entry.name);
      const isDir = entry.kind === "dir";
      const open = isDir && expanded.has(path);
      const children = isDir ? listings.get(path) : undefined;
      rows.push({
        path,
        name: entry.name,
        kind: entry.kind,
        depth,
        posInSet: index + 1,
        setSize: entries.length,
        expanded: open,
        loaded: !isDir || children !== undefined,
        empty: isDir && children !== undefined && children.length === 0,
        sizeBytes: entry.sizeBytes,
        mtime: entry.mtime,
      });
      if (open && children !== undefined) walk(path, depth + 1);
    }
  };
  walk("", 0);
  return rows;
}

/**
 * The rows a whole-Workspace search draws: one per hit the server returned, flat, each naming
 * its full path rather than its base name.
 *
 * Flat because there is no tree to place them in — a hit can sit in a directory the lazy tree
 * has never listed, and the hits are already ordered shallowest first, so nesting them would
 * mean loading every ancestor of every hit to draw scaffolding nobody asked for. The full path
 * because the base name is the part the reader just typed; where the file *is* is the answer
 * they are looking for.
 *
 * Every row is depth 0 and closed: a directory hit is somewhere to go, not something to unfold
 * in a list that is not a tree.
 */
export function searchRows(hits: readonly WorkspaceSearchHit[]): TreeRow[] {
  return hits.map((hit, index) => ({
    path: hit.path,
    name: hit.path,
    kind: hit.kind,
    depth: 0,
    posInSet: index + 1,
    setSize: hits.length,
    expanded: false,
    loaded: hit.kind === "file",
    empty: false,
    sizeBytes: hit.sizeBytes,
    mtime: hit.mtime,
  }));
}

// --------------------------------------------------------------------------------- drop

/**
 * The directory a drop lands in: a folder row under the pointer takes the files itself, a
 * file row hands them to its own directory, and anywhere else in the panel means the
 * current directory.
 */
export function dropTargetDir(
  hit: { kind: "dir" | "file"; path: string } | null,
  currentDir: string,
): string {
  if (hit === null) return currentDir;
  return hit.kind === "dir" ? hit.path : parentDir(hit.path);
}

// ---------------------------------------------------------------------------- file kinds

const TEXT_EXTS = new Set([
  "txt",
  "md",
  "json",
  "js",
  "mjs",
  "cjs",
  "ts",
  "tsx",
  "jsx",
  "py",
  "sh",
  "bash",
  "yaml",
  "yml",
  "toml",
  "css",
  "csv",
  "log",
  "xml",
  "ini",
  "conf",
  "rs",
  "go",
  "java",
  "c",
  "h",
  "cpp",
  "hpp",
  "sql",
  "rb",
  "php",
  "gitignore",
  "env",
]);
const IMAGE_EXTS = new Set(["png", "jpg", "jpeg", "gif", "webp", "svg"]);
const HTML_EXTS = new Set(["html", "htm"]);

/**
 * How a file previews, decided from its name. `unknown` is not "unsupported" yet: the
 * browser reads such a file's first bytes and treats it as text when they look like text
 * (a Makefile, a LICENSE, a dotfile with no extension).
 */
export type PreviewKind = "text" | "md" | "image" | "html" | "pdf" | "doc" | "unknown";

/** The lowercased extension, or the whole lowercased name when it has none ("Makefile" → "makefile", ".env" → "env"). */
export function extOf(name: string): string {
  const i = name.lastIndexOf(".");
  return i >= 0 ? name.slice(i + 1).toLowerCase() : name.toLowerCase();
}

export function previewKindFor(name: string): PreviewKind {
  const ext = extOf(name);
  if (IMAGE_EXTS.has(ext)) return "image";
  if (ext === "pdf") return "pdf";
  // Word previews through the server's own text extraction (a .docx is a zip of XML, see
  // services/docx-preview.ts), read-only: a preview of a document is not its source.
  if (ext === "docx" || ext === "doc") return "doc";
  if (HTML_EXTS.has(ext)) return "html";
  if (ext === "md") return "md";
  if (TEXT_EXTS.has(ext)) return "text";
  return "unknown";
}

/**
 * How a file previews in the read-only file browser (the UI package's `FileBrowser`), from its
 * name: the Workspace panel's own classification, minus the two answers a read-only browser
 * cannot give. HTML reads as its source, since rendering it would need the panel's sandboxed
 * frame; a name that says nothing reads as unsupported, since nobody there is reading the first
 * bytes to find out.
 */
export function previewKindOf(name: string): FileBrowserPreviewKind {
  const kind = previewKindFor(name);
  if (kind === "html") return "text";
  // A Word document needs the server's extraction fetch, which this read-only browser does not
  // do; it names the type instead of drawing an empty pane.
  if (kind === "doc") return "unsupported";
  return kind === "unknown" ? "unsupported" : kind;
}

/**
 * `bytes` without a multi-byte UTF-8 sequence cut off at its end: a read chunk can end
 * anywhere, and judging validity on the partial character would call a text file binary.
 */
export function utf8Complete(bytes: Uint8Array): Uint8Array {
  let i = bytes.length - 1;
  let back = 0;
  while (i >= 0 && back < 3 && (bytes[i]! & 0xc0) === 0x80) {
    i -= 1;
    back += 1;
  }
  if (i < 0) return bytes;
  const lead = bytes[i]!;
  const need = lead >= 0xf0 ? 4 : lead >= 0xe0 ? 3 : lead >= 0xc0 ? 2 : 1;
  return bytes.length - i < need ? bytes.subarray(0, i) : bytes;
}

/** Control bytes a text file legitimately carries: tab, LF, CR, FF, backspace, escape (ANSI-colored logs). */
const TEXT_CONTROL_BYTES = new Set([8, 9, 10, 12, 13, 27]);

/**
 * Whether a sample of a file's bytes reads as text: no NUL byte, few other control bytes,
 * and valid UTF-8 once a trailing partial character is set aside. Deliberately strict —
 * a binary mistaken for text becomes an editable garble, while a text file of some other
 * encoding merely stays a download.
 */
export function looksLikeText(bytes: Uint8Array): boolean {
  if (bytes.length === 0) return true;
  let control = 0;
  for (const b of bytes) {
    if (b === 0) return false;
    if (b < 0x20 && !TEXT_CONTROL_BYTES.has(b)) control += 1;
  }
  if (control / bytes.length > 0.1) return false;
  try {
    new TextDecoder("utf-8", { fatal: true }).decode(utf8Complete(bytes));
    return true;
  } catch {
    return false;
  }
}

// ------------------------------------------------------------------------------ editing

/** Bytes a text preview reads before it is cut off; a longer file previews truncated and cannot be edited in place. */
export const TEXT_PREVIEW_LIMIT = 1024 * 1024;

/** Per-file ceiling of the content write endpoint, in whole MB — the server's `MAX_UPLOAD_BYTES`, mirrored so an oversize save or upload is refused before any bytes travel. */
export const WORKSPACE_UPLOAD_LIMIT_MB = 14;

/**
 * Whether a preview can switch to the editor: a text-like kind whose full content is (or can
 * be) on hand. A truncated preview is exactly the case that must stay read-only — saving it
 * back would write the truncated text over the whole file.
 */
export function canEditPreview(preview: { kind: string; truncated?: boolean }): boolean {
  return (
    (preview.kind === "text" || preview.kind === "md" || preview.kind === "html") &&
    preview.truncated !== true
  );
}

/** The in-place editor: the file, the text it opened with, and what has been typed since. */
export interface EditorState {
  path: string;
  baseline: string;
  draft: string;
  /**
   * The version marker the baseline was read with, sent back as the save's write
   * precondition so the write cannot land on a file the Agent has since rewritten.
   */
  version: string;
  /** The file was found to carry a different version while this editor was open. */
  changedOnDisk?: boolean;
}

export function isDirty(editor: EditorState | null): boolean {
  return editor !== null && editor.draft !== editor.baseline;
}

/**
 * Whether landing on `nextPath` (null: on no file) would abandon typed changes and so must
 * ask first. Re-opening the file being edited keeps the editor and asks nothing.
 */
export function needsDiscardConfirm(editor: EditorState | null, nextPath: string | null): boolean {
  return isDirty(editor) && nextPath !== editor!.path;
}

// --------------------------------------------------------------------------- preference

/** Minimal storage interface (the subset of localStorage used here); tests inject an in-memory implementation. */
export interface TreePreferenceStorage {
  getItem(key: string): string | null;
  setItem(key: string, value: string): void;
}

/** Global preferences, not per Session: whether the tree pane is shown, how wide it is, and whether the editor soft-wraps. */
export const TREE_VISIBLE_KEY = "penguin.files.treeVisible";
export const TREE_WIDTH_KEY = "penguin.files.treeWidth";
/** Soft wrap, shared by the source view and the editor (see parseWrapLines on why one value, and on the key's name). */
export const EDITOR_WRAP_KEY = "penguin.files.editorWrap";

/** Tolerant parse: only an explicit "off" spelling hides the tree; nothing stored or anything unrecognized shows it (the default). */
export function parseTreeVisible(raw: string | null): boolean {
  if (raw === null) return true;
  const value = raw.trim().toLowerCase();
  return !(value === "0" || value === "false" || value === "hidden" || value === "no");
}

export function readTreeVisible(storage?: TreePreferenceStorage): boolean {
  try {
    // localStorage is resolved inside the try: merely touching it throws when site data is
    // blocked, and this runs from a useState initializer.
    return parseTreeVisible((storage ?? localStorage).getItem(TREE_VISIBLE_KEY));
  } catch {
    return true;
  }
}

export function writeTreeVisible(visible: boolean, storage?: TreePreferenceStorage): void {
  try {
    (storage ?? localStorage).setItem(TREE_VISIBLE_KEY, visible ? "1" : "0");
  } catch {
    /* best-effort persistence (quota limits / private browsing) */
  }
}

/**
 * Tolerant parse of the stored tree width: null for nothing stored and for anything that is
 * not a positive number, which is what makes the caller fall back to the width the pane had
 * before it was ever dragged.
 */
export function parseTreeWidth(raw: string | null): number | null {
  if (raw === null) return null;
  const value = Number.parseInt(raw.trim(), 10);
  return Number.isFinite(value) && value > 0 ? value : null;
}

export function readTreeWidth(storage?: TreePreferenceStorage): number | null {
  try {
    return parseTreeWidth((storage ?? localStorage).getItem(TREE_WIDTH_KEY));
  } catch {
    return null;
  }
}

export function writeTreeWidth(width: number, storage?: TreePreferenceStorage): void {
  try {
    (storage ?? localStorage).setItem(TREE_WIDTH_KEY, String(Math.round(width)));
  } catch {
    /* best-effort persistence (quota limits / private browsing) */
  }
}

/**
 * Tolerant parse of the soft-wrap preference: ON unless an explicit off spelling is stored.
 * Wrapping is what a reader wants of a file — a line that runs off the right edge has to be
 * chased to be read — and the same file being edited should not reflow on the way in.
 *
 * One value for both the source view and the editor, deliberately. They are the same file
 * seen two ways, and Edit swaps them in place: a separate preference would let pressing Edit
 * reflow the whole file and carry the line you were aiming at off the screen. The stored key
 * still reads `editorWrap` because the editor had the toggle first and a rename would silently
 * discard everyone's answer.
 */
export function parseWrapLines(raw: string | null): boolean {
  if (raw === null) return true;
  const value = raw.trim().toLowerCase();
  return !(value === "0" || value === "false" || value === "off" || value === "no");
}

export function readWrapLines(storage?: TreePreferenceStorage): boolean {
  try {
    return parseWrapLines((storage ?? localStorage).getItem(EDITOR_WRAP_KEY));
  } catch {
    return true;
  }
}

export function writeWrapLines(wrap: boolean, storage?: TreePreferenceStorage): void {
  try {
    (storage ?? localStorage).setItem(EDITOR_WRAP_KEY, wrap ? "1" : "0");
  } catch {
    /* best-effort persistence (quota limits / private browsing) */
  }
}

// -------------------------------------------------------------- composer references

/**
 * Something a surface hands the composer: what it points at, and the text the message carries
 * once it is sent. The Files panel hands a Workspace entry or a quoted range of one; the
 * conversation's own selection menu hands an excerpt of the conversation.
 *
 * The text is deliberately kept out of the textarea. What a surface contributes is a whole
 * thing — a file, a directory, a quoted range, an excerpt — and the draft is where the person is
 * writing; splicing the one into the other buries what they were saying under what they were
 * pointing at. The composer shows a chip naming it instead, the same shape `/agent` and `/skill`
 * already stage their picks in.
 */
export type ComposerReference = WorkspaceReference | ExcerptReference;

/** A Workspace entry, or a quoted range of one — what the Files panel hands the composer. */
export interface WorkspaceReference {
  /** Which glyph the chip wears, and what its label means. */
  kind: "file" | "dir" | "quote";
  /** Workspace-relative path: the chip's label comes from its last segment, its tooltip from the whole. */
  path: string;
  /** What goes into the message. */
  text: string;
  /** 1-based and inclusive, on a `quote` whose place in the file could be resolved. */
  fromLine?: number;
  toLine?: number;
}

/**
 * Text selected in the conversation itself. It has no path to name it by, so the chip is
 * labelled by the excerpt's own start and its tooltip is the whole excerpt.
 */
export interface ExcerptReference {
  kind: "excerpt";
  /** The selected text, as the selection read it: the chip's label and tooltip come from this. */
  excerpt: string;
  /** What goes into the message: the excerpt as a Markdown blockquote. */
  text: string;
}

/**
 * A line range as `:12` or `:12-18` — the `file:line` form every editor and stack trace uses, which
 * is why it is written the same way in both languages and read the same way by the model.
 */
export function lineSuffix(fromLine: number, toLine: number): string {
  return fromLine === toLine ? `:${fromLine}` : `:${fromLine}-${toLine}`;
}

/**
 * The `@`-prefixed reference a Workspace entry inserts into the composer. The trailing
 * slash on a directory is the only thing in the string that says it is one; nothing parses
 * these — the `@` is there for the reader, not for a mention mechanism.
 */
export function pathReference(path: string, kind: "dir" | "file"): string {
  return kind === "dir" ? `@${path}/` : `@${path}`;
}

/** The longest run of backticks anywhere in `text`. */
function longestBacktickRun(text: string): number {
  let longest = 0;
  let run = 0;
  for (const ch of text) {
    if (ch !== "`") {
      run = 0;
      continue;
    }
    run += 1;
    if (run > longest) longest = run;
  }
  return longest;
}

/**
 * The fenced block a preview selection inserts: a `@path` header carrying the line range,
 * then the selection verbatim. The fence is opened one backtick longer than the longest run
 * the selection itself contains, so a selection that carries fences still nests correctly.
 * The selected text is neither trimmed nor re-indented — the block is what was on screen.
 */
export function selectionBlock({
  path,
  language,
  selection,
  fromLine,
  toLine,
}: {
  path: string;
  language: string;
  selection: string;
  /** 1-based and inclusive. Both are omitted where the selection's place in the file cannot be resolved — a guessed range would be a lie, so the header then carries the path alone. */
  fromLine?: number;
  toLine?: number;
}): string {
  const range = fromLine === undefined || toLine === undefined ? "" : lineSuffix(fromLine, toLine);
  const fence = "`".repeat(Math.max(3, longestBacktickRun(selection) + 1));
  const body = selection.endsWith("\n") ? selection : `${selection}\n`;
  return `@${path}${range}\n${fence}${language}\n${body}${fence}`;
}