@visual-z/xeno 0.1.0

package/src/store/workspace.ts

@@ -0,0 +1,256 @@
+/**
+ * Workspace scanning, reconciliation and restore.
+ *
+ * The tree can move a cursor between nodes; this is what lets the files move
+ * with it. Two properties shape everything here:
+ *
+ *   TURN GRANULARITY. The workspace is scanned once per turn, not per tool
+ *   call. Per-call is too fine to be meaningful -- the documented criticism
+ *   of character-level versioning is that a single keystroke is not a change
+ *   -- and a turn is the same unit as "a message and the edit it produced".
+ *
+ *   TWO INDEPENDENT SOURCES. A tool's effect says what the tool CLAIMED to
+ *   do; a scan says what ACTUALLY changed. bash can write anywhere and its
+ *   effect records only an exit code, so without the scan an edit outside
+ *   every declared path would be invisible -- and a restore would silently
+ *   fail to undo it. Comparing the two makes that detectable, which is the
+ *   same rule the handoff applies to the model: claims are checked, not
+ *   believed.
+ *
+ * A restore moves the workspace and nothing else. Migrations, sent requests
+ * and started processes do not come back, and applyRestore says so rather
+ * than implying it undid the world.
+ */
+
+import { readdir, rm, stat, lstat } from "node:fs/promises";
+import type { Dirent } from "node:fs";
+import { join, dirname, relative, sep, isAbsolute } from "node:path";
+import type { Effect } from "../core/events.ts";
+import { blobAddress, digestFile, verifyBlob, restoreBlob } from "./blobs.ts";
+
+export interface ScanLimits {
+  maxFiles: number;
+  maxFileBytes: number;
+  maxTotalBytes: number;
+}
+
+/**
+ * Hashing and blob capture stream regular files, so file size has no default
+ * product cap. Callers may impose explicit resource limits. Exceeding one,
+ * losing a directory, or meeting an unsupported file type fails the whole scan;
+ * a partial listing could make a restore delete files it never recorded.
+ */
+export const DEFAULT_SCAN_LIMITS: ScanLimits = {
+  maxFiles: Infinity,
+  maxFileBytes: Infinity,
+  maxTotalBytes: Infinity,
+};
+
+/**
+ * Directories never scanned, snapshotted or restored.
+ *
+ * One constant rather than a default repeated at each call site: the snapshot
+ * and the restore have to agree exactly. A path the snapshot skipped is absent
+ * from every target file set, and applyRestore deletes whatever is not in the
+ * target -- so a restore using a shorter list than the snapshot would delete
+ * the log, the git directory, or the user's dependencies.
+ */
+export const DEFAULT_IGNORE: readonly string[] = [".xeno", ".git", "node_modules"];
+
+/** Relative path -> content digest. Same address space as the blob store. */
+export type FileSet = Record<string, string>;
+
+export function workspaceVersion(files: FileSet): string {
+  return blobAddress(JSON.stringify(Object.entries(files).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)));
+}
+
+export type ScanResult =
+  | { ok: true; files: FileSet }
+  | { ok: false; error: string };
+
+export interface ScanDelta {
+  added: FileSet;
+  changed: FileSet;
+  removed: string[];
+}
+
+export interface Reconciliation {
+  /** Changed on disk with no tool claiming it -- usually a shell command. */
+  undeclared: string[];
+  /** A tool claimed an edit the disk does not show. */
+  declaredButUnchanged: string[];
+}
+
+export interface RestoreResult {
+  restored: string[];
+  removed: string[];
+  /** Target files whose content is no longer in the blob store. */
+  unrecoverable: string[];
+  /** What this restore did not and could not touch. */
+  note: string;
+}
+
+function isIgnored(rel: string, ignore: readonly string[]): boolean {
+  const parts = rel.split(sep);
+  return ignore.some((i) => parts.includes(i));
+}
+
+export async function scanWorkspace(
+  root: string,
+  ignore: readonly string[],
+  limits: ScanLimits = DEFAULT_SCAN_LIMITS,
+): Promise<ScanResult> {
+  const files: FileSet = {};
+  let count = 0;
+  let total = 0;
+
+  async function walk(dir: string): Promise<string | null> {
+    let entries: Dirent[];
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch (err) {
+      return `cannot scan ${dir}: ${String(err)}`;
+    }
+    for (const entry of entries.sort((a, b) => (a.name < b.name ? -1 : 1))) {
+      const abs = join(dir, entry.name);
+      const rel = relative(root, abs);
+      if (isIgnored(rel, ignore)) continue;
+      if (entry.isDirectory()) {
+        const err = await walk(abs);
+        if (err) return err;
+        continue;
+      }
+      if (!entry.isFile()) return `cannot snapshot unsupported file type: ${rel}`;
+
+      const info = await stat(abs);
+      if (info.size > limits.maxFileBytes) {
+        return `${rel} is ${info.size} bytes, over maxFileBytes (${limits.maxFileBytes})`;
+      }
+      if (++count > limits.maxFiles) {
+        return `workspace has more than maxFiles (${limits.maxFiles}) files`;
+      }
+      total += info.size;
+      if (total > limits.maxTotalBytes) {
+        return `workspace exceeds maxTotalBytes (${limits.maxTotalBytes})`;
+      }
+      files[rel.split(sep).join("/")] = await digestFile(abs);
+    }
+    return null;
+  }
+
+  try {
+    const error = await walk(root);
+    return error ? { ok: false, error } : { ok: true, files };
+  } catch (error) { return { ok: false, error: `incomplete workspace scan: ${String(error)}` }; }
+}
+
+export function diffScans(before: FileSet, after: FileSet): ScanDelta {
+  const added: FileSet = {};
+  const changed: FileSet = {};
+  const removed: string[] = [];
+
+  for (const [path, sha] of Object.entries(after)) {
+    const was = before[path];
+    if (was === undefined) added[path] = sha;
+    else if (was !== sha) changed[path] = sha;
+  }
+  for (const path of Object.keys(before)) {
+    if (!(path in after)) removed.push(path);
+  }
+  return { added, changed, removed: removed.sort() };
+}
+
+export function reconcile(effects: readonly Effect[], observed: ScanDelta): Reconciliation {
+  // Only edits claim to change the workspace. A read claims nothing, and a
+  // command claims only its exit code -- which is exactly why the scan is
+  // needed to see what a command did.
+  const declared = new Set(
+    effects.filter((e) => e.kind === "edit").map((e) => e.path),
+  );
+  const touched = [
+    ...Object.keys(observed.added),
+    ...Object.keys(observed.changed),
+    ...observed.removed,
+  ];
+
+  return {
+    undeclared: touched.filter((p) => !declared.has(p)).sort(),
+    declaredButUnchanged: [...declared].filter((p) => !touched.includes(p)).sort(),
+  };
+}
+
+/**
+ * Replays deltas up to and including `toNode` to get the file set at that
+ * point. Pure, so a restore can be planned and inspected before anything is
+ * written.
+ */
+export function planRestore(
+  deltas: readonly (ScanDelta & { node: number })[],
+  toNode: number,
+): FileSet {
+  const files: FileSet = {};
+  for (const d of deltas) {
+    if (d.node > toNode) break;
+    for (const [path, sha] of Object.entries(d.added)) files[path] = sha;
+    for (const [path, sha] of Object.entries(d.changed)) files[path] = sha;
+    for (const path of d.removed) delete files[path];
+  }
+  return files;
+}
+
+export async function applyRestore(
+  root: string,
+  store: string,
+  target: FileSet,
+  ignore: readonly string[],
+): Promise<RestoreResult> {
+  const restored: string[] = [];
+  const unrecoverable: string[] = [];
+
+  // Validate the complete plan before its first write or deletion. Missing
+  // objects and a failed scan cannot be interpreted as an empty target (H).
+  const current = await scanWorkspace(root, ignore);
+  if (!current.ok) throw new Error(current.error);
+  for (const [path, sha] of Object.entries(target)) {
+    if (isAbsolute(path) || path.split(/[\\/]/).some((p) => p === "..") || isIgnored(path, ignore)) {
+      throw new Error(`unsafe restore path: ${path}`);
+    }
+    let parent = dirname(join(root, path));
+    while (parent !== root && parent.startsWith(root + sep)) {
+      try { if ((await lstat(parent)).isSymbolicLink()) throw new Error(`restore path crosses symlink: ${path}`); }
+      catch (error) { if ((error as { code?: string }).code !== "ENOENT") throw error; }
+      parent = dirname(parent);
+    }
+    if (!await verifyBlob(store, sha)) unrecoverable.push(path);
+  }
+  if (unrecoverable.length > 0) return {
+    restored: [], removed: [], unrecoverable: unrecoverable.sort(),
+    note: "Restore not applied: missing snapshot objects. Workspace and cursor remain unchanged.",
+  };
+
+  for (const [path, sha] of Object.entries(target)) {
+    const abs = join(root, path);
+    await restoreBlob(store, sha, abs);
+    restored.push(path);
+  }
+
+  // Anything present but not in the target was created after this point.
+  const removed: string[] = [];
+  if (current.ok) {
+    for (const path of Object.keys(current.files)) {
+      if (path in target) continue;
+      await rm(join(root, path), { force: true });
+      removed.push(path);
+    }
+  }
+
+  return {
+    restored: restored.sort(),
+    removed: removed.sort(),
+    unrecoverable: unrecoverable.sort(),
+    note:
+      "Restored the workspace only. Anything outside it is not undone: " +
+      "database migrations, requests already sent, processes already " +
+      "started, and files outside the workspace root all remain as they are.",
+  };
+}

package/src/store/worktree.ts

@@ -0,0 +1,233 @@
+/**
+ * Git worktree isolation for branches that write.
+ *
+ * A worktree is a second checkout sharing one object database, which is why
+ * it is the isolation primitive parallel agents converged on: each branch
+ * edits its own files, and conflicts surface at merge time through ordinary
+ * git tooling instead of as silent overwrites during the work.
+ *
+ * What this does NOT isolate, stated because assuming otherwise is how these
+ * setups break:
+ *
+ *   ENVIRONMENT. Ports, databases, and anything else outside the working
+ *   directory are still shared. Two branches running a dev server or a
+ *   migration will collide, and a test can fail because a sibling took the
+ *   port rather than because the branch is wrong. That needs containers.
+ *
+ *   ESCAPE. A branch can point git back at the shared checkout with `git -C`
+ *   or GIT_DIR, which has been an actual reported escape. Preventing it is a
+ *   sandbox's job, and this project has no sandbox layer; the isolation here
+ *   is for cooperative branches, not adversarial ones.
+ */
+
+import { mkdtemp, rm, realpath } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+/** Branch prefix, so a stale worktree is identifiable months later. */
+export const WORKTREE_BRANCH_PREFIX = "xeno/";
+
+export interface WorktreeInfo {
+  path: string;
+  branch: string | null;
+  locked: boolean;
+}
+
+export type CreateResult =
+  | { ok: true; path: string; branch: string; snapshot: { head: string; tree: string } }
+  | { ok: false; error: string };
+
+export type RemoveResult =
+  | { ok: true }
+  | { ok: false; error: string; dirty: boolean };
+
+interface GitRun {
+  code: number;
+  stdout: string;
+  stderr: string;
+}
+
+function git(cwd: string, args: string[], env?: Record<string, string | undefined>): GitRun {
+  const p = Bun.spawnSync(["git", ...args], { cwd, ...(env ? { env } : {}) });
+  const dec = new TextDecoder();
+  return {
+    code: p.exitCode,
+    stdout: dec.decode(p.stdout),
+    stderr: dec.decode(p.stderr),
+  };
+}
+
+export async function isGitRepo(dir: string): Promise<boolean> {
+  return git(dir, ["rev-parse", "--git-dir"]).code === 0;
+}
+
+export async function createWorktree(repo: string, name: string): Promise<CreateResult> {
+  // Refused rather than degraded. Falling back to the shared directory is the
+  // exact failure isolation exists to prevent: parallel writing branches
+  // would overwrite each other with nothing to indicate isolation was never
+  // in place.
+  if (!(await isGitRepo(repo))) {
+    return {
+      ok: false,
+      error:
+        `${repo} is not a git repository, so a writing branch cannot be isolated. ` +
+        "Initialise one, or run the branch read-only.",
+    };
+  }
+
+  // O.4: snapshot the working copy through a private index. Never stash, reset,
+  // or stage the user's index merely to construct a child input.
+  const root = git(repo, ["rev-parse", "--show-toplevel"]);
+  if (root.code !== 0 || await realpath(repo) !== await realpath(root.stdout.trim())) {
+    return { ok: false, error: "writing branch input must be the repository root" };
+  }
+  const head = git(repo, ["rev-parse", "--verify", "HEAD"]);
+  if (head.code !== 0) return { ok: false, error: "writing branch input requires an existing HEAD commit" };
+  const unmerged = git(repo, ["ls-files", "--unmerged"]);
+  if (unmerged.code !== 0 || unmerged.stdout.length > 0) return { ok: false, error: "resolve index conflicts before creating a writing branch" };
+  const staged = git(repo, ["ls-files", "--stage", "-z"]);
+  if (staged.code !== 0 || staged.stdout.split("\0").some(entry => entry.startsWith("160000 "))) {
+    return { ok: false, error: "writing branch snapshots do not yet support submodules" };
+  }
+  const scratch = await mkdtemp(join(tmpdir(), "xeno-input-index-"));
+  let tree: string;
+  try {
+    const env = { ...process.env, GIT_INDEX_FILE: join(scratch, "index") };
+    for (const args of [["read-tree", head.stdout.trim()], ["add", "--all", "--", "."]]) {
+      const result = git(repo, args, env);
+      if (result.code !== 0) return { ok: false, error: `cannot capture branch input: ${result.stderr.trim()}` };
+    }
+    const captured = git(repo, ["ls-files", "--stage", "-z"], env);
+    if (captured.code !== 0 || captured.stdout.split("\0").some(entry => entry.startsWith("160000 "))) {
+      return { ok: false, error: "writing branch snapshots do not yet support nested repositories or submodules" };
+    }
+    const written = git(repo, ["write-tree"], env);
+    if (written.code !== 0) return { ok: false, error: `cannot capture branch input tree: ${written.stderr.trim()}` };
+    tree = written.stdout.trim();
+  } finally { await rm(scratch, { recursive: true, force: true }); }
+
+  const branch = `${WORKTREE_BRANCH_PREFIX}${name}`;
+  const created = await mkdtemp(join(tmpdir(), `xeno-wt-${name}-`));
+  // Resolved through symlinks, because git reports the real path and a
+  // caller comparing the two would never match. On macOS /var is a symlink
+  // to /private/var, so every temp path differs by default.
+  const path = await realpath(created);
+  // mkdtemp created it; git worktree add needs the path not to exist.
+  await rm(path, { recursive: true, force: true });
+
+  // --lock in the same call: locking afterwards leaves a window in which a
+  // concurrent prune can remove the worktree that was just created.
+  const add = git(repo, ["worktree", "add", "--lock", "-b", branch, path, head.stdout.trim()]);
+  if (add.code !== 0) {
+    return { ok: false, error: `git worktree add failed: ${add.stderr.trim()}` };
+  }
+  // Only this freshly created disposable checkout is reset. The child index
+  // carries the parent's uncommitted input, so normal diff/inspection still sees it.
+  const hydrate = git(path, ["read-tree", "--reset", "-u", tree]);
+  if (hydrate.code !== 0) {
+    const removed = await removeWorktree(repo, path, branch, { force: true });
+    return { ok: false, error: `cannot materialize branch input: ${hydrate.stderr.trim()}` +
+      (removed.ok ? "" : `; cleanup required at ${path}: ${removed.error}`) };
+  }
+  return { ok: true, path, branch, snapshot: { head: head.stdout.trim(), tree } };
+}
+
+/**
+ * Parses `--porcelain -z`, the only output format documented as stable
+ * across git versions and user configuration. `-z` additionally survives a
+ * path containing a newline, which a line-based parse would split into two
+ * bogus entries.
+ */
+export async function listWorktrees(repo: string): Promise<WorktreeInfo[]> {
+  const out = git(repo, ["worktree", "list", "--porcelain", "-z"]);
+  if (out.code !== 0) return [];
+
+  const worktrees: WorktreeInfo[] = [];
+  let current: Partial<WorktreeInfo> = {};
+  for (const record of out.stdout.split("\0")) {
+    if (record === "") {
+      // A blank record terminates one worktree's attributes.
+      if (current.path) {
+        worktrees.push({
+          path: current.path,
+          branch: current.branch ?? null,
+          locked: current.locked ?? false,
+        });
+      }
+      current = {};
+      continue;
+    }
+    const [key, ...rest] = record.split(" ");
+    const value = rest.join(" ");
+    if (key === "worktree") current.path = value;
+    else if (key === "branch") current.branch = value.replace(/^refs\/heads\//, "");
+    else if (key === "locked") current.locked = true;
+  }
+  if (current.path) {
+    worktrees.push({
+      path: current.path,
+      branch: current.branch ?? null,
+      locked: current.locked ?? false,
+    });
+  }
+  return worktrees;
+}
+
+/**
+ * Removes a worktree, its registration and its branch.
+ *
+ * A dirty worktree is reported rather than forced. The refusal is evidence
+ * to look at: uncommitted changes there may be exactly the work the branch
+ * was for, and discarding them silently is the destructive-restore mistake
+ * in a different costume. `force` exists for a caller that has decided.
+ */
+export async function removeWorktree(
+  repo: string,
+  path: string,
+  branch: string | null,
+  opts: { force?: boolean } = {},
+): Promise<RemoveResult> {
+  // Created with --lock, so unlock first; a locked worktree otherwise needs
+  // --force twice, which would conflate "locked" with "dirty".
+  git(repo, ["worktree", "unlock", path]);
+
+  const args = ["worktree", "remove", path];
+  if (opts.force) args.push("--force");
+  const removed = git(repo, args);
+
+  if (removed.code !== 0) {
+    const dirty = /contains modified or untracked files|is dirty/i.test(removed.stderr);
+    return {
+      ok: false,
+      error: dirty
+        ? `${path} has uncommitted changes. Inspect them before removing, ` +
+          "or pass force to discard them."
+        : `git worktree remove failed: ${removed.stderr.trim()}`,
+      dirty,
+    };
+  }
+
+  // Removing a worktree never deletes its branch, so a run of branches would
+  // otherwise leave a branch behind for every one of them.
+  if (branch) git(repo, ["branch", "-D", branch]);
+  return { ok: true };
+}
+
+/**
+ * Clears registrations left behind by hand-deleted directories.
+ *
+ * Only for that case. A worktree that was MOVED must be repaired instead --
+ * pruning it discards a working directory that still exists.
+ */
+export async function pruneWorktrees(repo: string): Promise<void> {
+  // A lock exists to stop pruning, and createWorktree takes one -- so a
+  // hand-deleted worktree of ours would stay registered forever without
+  // unlocking first. Only ours: the prefix check keeps this from unlocking
+  // a worktree someone locked deliberately.
+  for (const wt of await listWorktrees(repo)) {
+    if (wt.locked && wt.branch?.startsWith(WORKTREE_BRANCH_PREFIX)) {
+      git(repo, ["worktree", "unlock", wt.path]);
+    }
+  }
+  git(repo, ["worktree", "prune"]);
+}

package/src/tui/ansi.ts

@@ -0,0 +1,67 @@
+/**
+ * Escape sequences the renderer emits. Each constant names the standard it
+ * comes from and what breaks without it -- a bare number in a CSI is otherwise
+ * a magic that nobody can audit.
+ */
+
+/**
+ * DECSET 2026 — begin synchronized output.
+ * Spec: https://gist.github.com/christianparpart/d8d62cc110656ba92d4e171cec8a547a
+ * (mode 2026, adopted by xterm, tmux, kitty, iTerm2, Windows Terminal).
+ * Without this, tmux paints each cursor move as its own frame and the user
+ * sees the cursor jump and the frame tear while a diff is applied.
+ */
+export const SYNC_BEGIN = "\x1b[?2026h";
+
+/**
+ * DECRST 2026 — end synchronized output, the matching close of SYNC_BEGIN.
+ * Omitting it leaves the terminal buffering subsequent output forever, so
+ * the next frame (and everything after) never appears.
+ */
+export const SYNC_END = "\x1b[?2026l";
+
+/**
+ * CR — carriage return. ASCII 0x0D / ECMA-48. Returns to column 0 of the
+ * current row so a changed line can be overwritten in place.
+ */
+export const CR = "\r";
+
+/**
+ * LF — line feed. ASCII 0x0A / ECMA-48. Advances onto a newly grown row of
+ * the live region; a CSI CUD at the bottom of the screen is clamped and
+ * would overwrite the last line instead of extending the region.
+ */
+export const LF = "\n";
+
+/**
+ * CSI CUU — cursor up N rows. ECMA-48 §8.3.14. Relative moves are what make
+ * a line-diff possible without knowing the absolute row of the live region
+ * (a main-screen TUI does not own the viewport origin).
+ */
+export function cursorUp(n: number): string {
+  return n > 0 ? `\x1b[${n}A` : "";
+}
+
+/**
+ * CSI CUD — cursor down N rows. ECMA-48 §8.3.13. Used to skip unchanged
+ * lines when the cursor sits above them, not to grow the region (see LF).
+ */
+export function cursorDown(n: number): string {
+  return n > 0 ? `\x1b[${n}B` : "";
+}
+
+/**
+ * CSI EL 0 — erase from cursor to end of line. ECMA-48 §8.3.41.
+ * Without it a shorter replacement leaves the tail of the previous longer
+ * line sitting on screen.
+ */
+export const ERASE_LINE_TAIL = "\x1b[K";
+
+/**
+ * CSI ED 0 — erase from cursor to end of display. ECMA-48 §8.3.39.
+ * Used when the new frame is shorter than the old one. Safe only because
+ * the live region sits at the bottom of the main screen: anything below it
+ * is leftover rows of a taller previous frame, not the user's scrollback
+ * (scrollback is above us).
+ */
+export const ERASE_DOWN = "\x1b[J";

package/src/tui/autocomplete.ts

@@ -0,0 +1,29 @@
+import { CombinedAutocompleteProvider, type AutocompleteItem, type AutocompleteSuggestions, type SlashCommand } from "../vendor/pi-tui/autocomplete.ts";
+import { fuzzyFilter } from "../vendor/pi-tui/fuzzy.ts";
+
+/** Pi's completion rules, with xeno's workspace index in place of an fd dependency. */
+export class WorkspaceAutocomplete extends CombinedAutocompleteProvider {
+  triggerCharacters = ["/", "@"];
+  private readonly paths: (refresh?: boolean) => Promise<readonly string[]>;
+
+  constructor(commands: SlashCommand[], workspace: string, paths: (refresh?: boolean) => Promise<readonly string[]>) {
+    super(commands, workspace);
+    this.paths = paths;
+  }
+
+  override async getSuggestions(lines: string[], line: number, col: number,
+    options: { signal: AbortSignal; force?: boolean }): Promise<AutocompleteSuggestions | null> {
+    const before = (lines[line] ?? "").slice(0, col);
+    const prefix = /(?:^|\s)(@(?:"[^"]*|[^\s]*))$/.exec(before)?.[1];
+    if (prefix !== undefined) {
+      const paths = await this.paths(options.force === true || prefix === "@");
+      if (options.signal.aborted) return null;
+      const query = prefix.slice(1).replace(/^"/, "");
+      const items: AutocompleteItem[] = fuzzyFilter([...paths], query, (p) => p).map((path) => ({
+        value: `@${/\s/.test(path) ? `"${path}"` : path}`, label: path,
+      }));
+      return items.length > 0 ? { items, prefix } : null;
+    }
+    return super.getSuggestions(lines, line, col, options);
+  }
+}

package/src/tui/complete.ts

@@ -0,0 +1,87 @@
+/**
+ * Path completion as a pure function: the caller reads the directory,
+ * this module only matches names. I/O in applyKey would make "tab on
+ * src/fo" a test that needs a disk.
+ */
+
+export interface PathCompletion {
+  readonly completed: string;
+  readonly candidates: readonly string[];
+}
+
+export interface PathToken {
+  readonly start: number;
+  readonly end: number;
+  readonly prefix: string;
+}
+
+/**
+ * Longest prefix of `entries` that still starts with `prefix`. One match
+ * completes fully; several matches complete only as far as they agree,
+ * so a later Tab can still distinguish them.
+ */
+export function completePath(prefix: string, entries: readonly string[]): PathCompletion {
+  const candidates = entries.filter((e) => e.startsWith(prefix));
+  if (candidates.length === 0) return { completed: prefix, candidates: [] };
+  if (candidates.length === 1) return { completed: candidates[0]!, candidates };
+  return { completed: longestCommonPrefix(candidates), candidates };
+}
+
+/**
+ * The whitespace-delimited token the cursor is in. Null when it does not
+ * look like a path, so Tab in ordinary prose keeps its existing no-op
+ * rather than swallowing the key.
+ */
+export function pathTokenAtCursor(text: string, cursor: number): PathToken | null {
+  let start = cursor;
+  while (start > 0 && !isTokenSep(text[start - 1]!)) start--;
+  let end = cursor;
+  while (end < text.length && !isTokenSep(text[end]!)) end++;
+  const prefix = text.slice(start, end);
+  if (!looksLikePath(prefix)) return null;
+  return { start, end, prefix };
+}
+
+export function looksLikePath(s: string): boolean {
+  if (s.length === 0) return false;
+  // @-mentions are a different picker; stealing them here would hide
+  // the file-index path the user already has.
+  if (s.startsWith("@")) return false;
+  return s.includes("/") || s.startsWith("~") || s.startsWith(".");
+}
+
+/** Directory to list for a typed prefix. "src/fo" → "src"; "fo" → ".". */
+export function dirOfPrefix(prefix: string): string {
+  if (prefix.endsWith("/")) return prefix.slice(0, -1) || ".";
+  const i = prefix.lastIndexOf("/");
+  if (i < 0) return ".";
+  if (i === 0) return "/";
+  return prefix.slice(0, i);
+}
+
+/** Join listing names back onto the prefix's directory, matching completePath. */
+export function entriesFromNames(prefix: string, names: readonly string[]): readonly string[] {
+  const dir = dirOfPrefix(prefix);
+  return names.map((name) => {
+    if (dir === ".") return name;
+    if (dir === "/") return `/${name}`;
+    return `${dir}/${name}`;
+  });
+}
+
+function isTokenSep(ch: string): boolean {
+  return /\s/.test(ch);
+}
+
+function longestCommonPrefix(xs: readonly string[]): string {
+  const first = xs[0];
+  if (first === undefined) return "";
+  let p = first;
+  for (const s of xs) {
+    while (!s.startsWith(p)) {
+      if (p.length === 0) return "";
+      p = p.slice(0, -1);
+    }
+  }
+  return p;
+}