Official

files

Built-in files UI (JavaScript UI plugin).

The app opens the listing; nothing installs until an agent in your Plugins workspace has read the files and you enable the plugin. In a terminal: dvg install divergence/files@0.2.6

Permissions in 0.2.6

  • Read files fs.readMediumReads files in the listed places.List the files of the workspacePlaces: the open workspace
  • Read chats chats.readMediumReads your transcripts and chat lists.Refresh the file list when an agent finishes a turn
  • Show panels ui.slotsAlways grantedShows views in the listed parts of the window.Show the files button and panelSlots: railright

Files

panel.ts4.7 KB
// File panel state, filtering and folder-first tree construction.
// Paths and selection remain workspace-relative, matching the kernel tree ids.
import * as z from "zod";
import type { EffectClient } from "divergence/effect";
import type * as Fiber from "effect/Fiber";
import type { AppState } from "divergence";
import type { Tabs } from "../tabs/contract.ts";

// One open folder's names, keyed by its tree id: "" for the top, else its
// path with a trailing "/".
export interface Listing {
  files: readonly string[];
  folders: readonly string[];
}

export interface FilesState {
  workspaceId: string | null;
  // The folders listed so far. Only these are in the tree; the others show a
  // "Loading…" row until they are opened and listed.
  listing: Record<string, Listing>;
  // The folders whose last listing failed: their row says so instead of
  // "Loading…", and opening them again lists them again.
  failed: ReadonlySet<string>;
  // Every path, from a host before per-folder listing; null otherwise.
  all: readonly string[] | null;
  // The folders open in each workspace's tree, by tree id. They outlast the
  // tree, so a hidden panel or another workspace gives them back as they
  // were.
  open: Record<string, Set<string>>;
  query: string;
  // The host's matches for `query`; the last ones stay until new ones come.
  results: readonly string[];
  // The query `results` answer (trimmed), so an empty answer reads "No matches" only once it is in.
  resultsFor: string | null;
  // The divergence/tabs client while its provider runs, the open file it
  // last announced, and the fiber following it; selection stays empty
  // without it.
  tabs: EffectClient<typeof Tabs> | undefined;
  activePath: string | null;
  follow: Fiber.Fiber<void> | undefined;
}

export const initialState = (): FilesState => ({
  workspaceId: null,
  listing: {},
  failed: new Set(),
  all: null,
  open: {},
  query: "",
  results: [],
  resultsFor: null,
  tabs: undefined,
  activePath: null,
  follow: undefined,
});

// The row a folder holds until it is listed: a tree row is a folder only
// when it has children.
export const isPending = (id: string): boolean => id.endsWith("…");

export interface TreeItem {
  id: string;
  label: string;
  open?: boolean;
  children?: TreeItem[];
}

// The listed folders as tree items, with the ids `files` nesting gives them,
// and `open` on the folders in `open`. A folder not listed yet holds one
// row: "Loading…", or what went wrong when its listing failed.
export function treeItems(
  listing: Record<string, Listing>,
  open: ReadonlySet<string> = new Set(),
  failed: ReadonlySet<string> = new Set(),
  prefix = "",
): TreeItem[] {
  const here = listing[prefix];
  if (!here) return prefix ? [{ id: `${prefix}…`, label: failed.has(prefix) ? "Could not list this folder" : "Loading…" }] : [];
  return [
    ...here.folders.map((name) => {
      const id = `${prefix}${name}/`;
      return { id, label: name, ...(open.has(id) ? { open: true } : {}), children: treeItems(listing, open, failed, id) };
    }),
    ...here.files.map((name) => ({ id: `${prefix}${name}`, label: name })),
  ];
}

// The folders a path is in, outermost first, as tree ids.
export const folderIds = (path: string): string[] =>
  path
    .split("/")
    .slice(0, -1)
    .map((_, index, parts) => `${parts.slice(0, index + 1).join("/")}/`);

export function isOpen(app: AppState): boolean {
  return app.shared?.rightPanel === "files" || app.shared?.rightPanelPreview === "files";
}

export function selectedPath(activePath: string | null): string | null {
  return typeof activePath === "string" ? activePath : null;
}

const finished = z.object({ event: z.literal("run_finished") });
export const runFinished = (kind: unknown): boolean => finished.safeParse(kind).success;

/// The listed folders a change to `paths` (absolute, as a watch reports
/// them) touched: the folder each path is in, and a listed folder that
/// itself changed. `null` when a path is not under `root` (or the root is
/// not known), so every listed folder is listed again. Git's own folder
/// changes at every `git status` and is never listed.
export function touchedFolders(root: string | null, paths: readonly string[], listed: ReadonlySet<string>): string[] | null {
  const touched = new Set<string>();
  for (const path of paths) {
    if (root === null || !path.startsWith(`${root}/`)) {
      if (path === root) continue;
      return null;
    }
    const rel = path.slice(root.length + 1);
    if (/^\.(git|divergence)(\/|$)/.test(rel)) continue;
    // Folders are named as the tree keys them: `src/`, and `` for the top.
    const parent = rel.slice(0, rel.lastIndexOf("/") + 1);
    if (listed.has(parent)) touched.add(parent);
    if (listed.has(`${rel}/`)) touched.add(`${rel}/`);
  }
  return [...touched];
}

Versions

VersionPublishedPlugin APISizePermissionsStatus
0.2.6latestNov 21, 2026>=5 <613.7 KB3 permissionsListed
0.2.5Nov 11, 2026>=5 <613.3 KB3 permissionsListed
0.2.4Nov 9, 2026>=5 <612.3 KB3 permissionsListed
0.2.3Oct 27, 2026>=2 <48 KB3 permissionsListed

Reviews and comments

0 threads · 0 reviews

No comments yet.