pim-agent 0.12.1 → 0.14.0

package/packages/core/src/session/SessionMeta.ts

@@ -6,23 +6,22 @@ import { Paths } from "../shared/Paths";
 
 export type SessionEntry = {
   readonly archived?: boolean;
-  /** Sticky: set by hand, and only a read clears it. */
+  /** Set by hand; only a read clears it. */
   readonly unread?: boolean;
 };
 
 export type ProjectEntry = {
   readonly pinned?: boolean;
-  /** The sidebar group stands unfolded; absent is folded, which is where a project starts. */
+  /** Absent means folded. */
   readonly expanded?: boolean;
-  /** What to call the directory instead of its base name; the directory itself is never touched. */
+  /** Display name instead of the directory's base name. */
   readonly label?: string;
 };
 
-/** The pin flags and the order they are shown in, from one read of the file. */
 export type Pinning = {
   /** Keyed by absolute cwd. */
   readonly projects: ReadonlyMap<string, ProjectEntry>;
-  /** The pinned directories, in the order they are shown. */
+  /** Pinned cwds in display order. */
   readonly order: readonly string[];
 };
 
@@ -30,13 +29,7 @@ type Stored = {
   readonly version: 1;
   readonly sessions: Record<string, SessionEntry>;
   readonly projects: Record<string, ProjectEntry>;
-  /**
-   * Where the pinned directories sort, and only that: `projects` stays the
-   * truth of whether one is pinned. An entry here that is not pinned is
-   * ignored and a pin it has never heard of still sorts, so a file written by
-   * a pim that predates the order — or by one that does not write it — needs
-   * no migration.
-   */
+  /** Sort order only; `projects` decides what is pinned. */
   readonly pins: readonly string[];
 };
 
@@ -48,7 +41,7 @@ type Loaded = {
 
 const NONE: SessionEntry = {};
 
-/** Per-session and per-project overrides, shared by every surface on a machine. */
+/** Per-session and per-project UI state, shared by every surface on the machine. */
 export class SessionMeta {
   private readonly file: string;
   private readonly writes = Fs.serialised();
@@ -62,18 +55,17 @@ export class SessionMeta {
     return (await this.sessions()).get(sessionId) ?? NONE;
   }
 
-  /** One read for a whole listing; `of` per row is one read per row. */
+  /** One file read for the whole listing. */
   public async sessions(): Promise<ReadonlyMap<string, SessionEntry>> {
     return (await this.read()).sessions;
   }
 
-  /** The pinned directories in display order; a listing wants both halves, and this is one read for them. */
   public async pinning(): Promise<Pinning> {
     const loaded = await this.read();
     return { projects: loaded.projects, order: ordered(loaded) };
   }
 
-  /** The pinned directories in display order. */
+  /** Pinned cwds in display order. */
   public async pins(): Promise<readonly string[]> {
     return ordered(await this.read());
   }
@@ -88,7 +80,7 @@ export class SessionMeta {
     return this.mutate((loaded) => put(loaded.sessions, sessionId, { unread }));
   }
 
-  /** A new pin goes to the top, where you have just put it; an old one leaves the order with the flag. */
+  /** A new pin goes to the top. */
   public setPinned(cwd: string, pinned: boolean): Promise<void> {
     return this.mutate((loaded) => {
       const at = loaded.pins.indexOf(cwd);
@@ -102,22 +94,18 @@ export class SessionMeta {
     });
   }
 
-  /**
-   * Folds a project's group, or unfolds it. Kept beside the pin rather than
-   * in the browser, so the fold a phone made is the fold a desktop opens to.
-   */
   public setExpanded(cwd: string, expanded: boolean): Promise<void> {
     return this.mutate((loaded) => put(loaded.projects, cwd, { expanded }));
   }
 
-  /** Names the project for the sidebar; `null` puts it back to its base name. */
+  /** `null` restores the base name. */
   public setLabel(cwd: string, label: string | null): Promise<void> {
     return this.mutate((loaded) =>
       put(loaded.projects, cwd, { label: label ?? "" })
     );
   }
 
-  /** Takes the whole order rather than a move, so two surfaces settle on the last one written. */
+  /** Replaces the whole order; unpinned and duplicate cwds are dropped. */
   public setPinOrder(order: readonly string[]): Promise<void> {
     return this.mutate((loaded) => {
       loaded.pins = [...new Set(order)].filter(
@@ -127,7 +115,7 @@ export class SessionMeta {
     });
   }
 
-  /** Drops the sessions that are gone; a pin outlives every session of its project. */
+  /** Drops entries for sessions not in `alive`. Projects are kept. */
   public prune(alive: ReadonlySet<string>): Promise<void> {
     return this.mutate((loaded) => {
       let dropped = false;
@@ -141,7 +129,7 @@ export class SessionMeta {
     });
   }
 
-  /** Settles the writes taken so far, for a clean stop. */
+  /** Waits for pending writes. */
   public async flush(): Promise<void> {
     await this.writes.run(async () => undefined);
   }
@@ -162,7 +150,7 @@ export class SessionMeta {
     };
   }
 
-  /** Re-reads under the lock, so a write by another process survives this one. */
+  /** Re-reads under the lock so another process's write is not lost. */
   private async mutate(update: (loaded: Loaded) => boolean): Promise<void> {
     await this.writes.run(async () => {
       const loaded = await this.read();
@@ -180,11 +168,7 @@ export class SessionMeta {
   }
 }
 
-/**
- * The pinned directories in display order: the ones the stored order names,
- * then any pin it has not heard of, by path. A duplicate in the order is
- * taken once, at the first place it appears.
- */
+/** Stored order first, then pins missing from it sorted by path. */
 function ordered({ projects, pins }: Loaded): readonly string[] {
   const unplaced = new Set(
     [...projects]
@@ -209,7 +193,7 @@ function put<T extends object>(
   return true;
 }
 
-/** Every field is opt-in, so a false flag or an empty name is the same as an absent one. */
+/** Drops `false` and `""` fields; they mean the same as absent. */
 function onlySet<T extends object>(entry: T): T {
   return Object.fromEntries(
     Object.entries(entry).filter(

package/packages/core/src/session/SessionName.ts

@@ -1,18 +1,14 @@
-/**
- * Twice the width a sidebar row can show, so a name is never silently cut at the
- * length it happens to render at, and a pasted essay still cannot become one.
- */
+/** In code points. */
 const LIMIT = 80;
 
-/** What pi should store for this name: whitespace collapsed, controls gone, `""` to clear. */
+/** Collapses whitespace and strips control characters; `""` clears the name. */
 function normalise(name: string | null | undefined): string {
   const clean = (name ?? "")
     .replace(/\p{Cc}/gu, " ")
     .replace(/\s+/gu, " ")
     .trim();
-  // By code point: a cap that splits a surrogate pair stores half a character.
+  // Slice by code point so a surrogate pair is never split.
   return [...clean].slice(0, LIMIT).join("").trim();
 }
 
-/** The one spelling of a session name pim writes into pi's `session_info`. */
 export const SessionName = { normalise };

package/packages/core/src/session/SessionRegistry.ts

@@ -20,7 +20,6 @@ import { SessionLease } from "./SessionLease";
 import { SessionName } from "./SessionName";
 import type { SessionUi } from "./SessionUi";
 
-/** A session as pi stores it: one JSONL file under a cwd-encoded directory. */
 export type SessionSummary = {
   readonly sessionId: string;
   readonly cwd: string;
@@ -31,9 +30,9 @@ export type SessionSummary = {
 
 export type SessionRegistryDeps = {
   readonly defaults: { readonly cwd: string; readonly model?: string };
-  /** The process-wide pi installation; one is built here when a caller has none to share. */
+  /** Defaults to a new runtime over `agentDir`. */
   readonly runtime?: AgentRuntime;
-  /** Where auth, models, settings and sessions live; must agree with pi's own `getAgentDir()`. */
+  /** Must match pi's `getAgentDir()`. */
   readonly agentDir?: string;
   readonly capacity?: number;
   readonly customTools?: (
@@ -41,20 +40,19 @@ export type SessionRegistryDeps = {
   ) => readonly ToolDefinition[];
   /** Appended to every session's system prompt. */
   readonly systemInstruction?: () => Promise<string | undefined>;
-  /** Where this frontend's human is reading. */
   readonly surface?: Surface;
 };
 
 export type SessionCreateOptions = {
   readonly cwd?: string;
-  /** Open the new session like this one: model, chosen thinking level, and cwd when none is given. */
+  /** Copies model, thinking level and (if `cwd` is unset) cwd from this host. */
   readonly like?: SessionHost;
 };
 
-/** A session tree is thousands of files and each header is one open; fanning out over all of them at once is how a listing runs the process out of descriptors. */
+/** Concurrent header reads, to avoid running out of file descriptors. */
 const HEADER_READS = 32;
 
-/** Live sessions keyed on pi's session UUID; the catalogue is pi's sessions directory, read on demand. */
+/** Live sessions keyed by pi's session id, plus listing of pi's sessions directory. */
 export class SessionRegistry {
   private readonly deps: SessionRegistryDeps;
   private readonly runtime: AgentRuntime;
@@ -68,10 +66,8 @@ export class SessionRegistry {
   }
 
   /**
-   * Where the extensions of every host built from here speak. It belongs to the
-   * registry rather than each caller because `create` binds an agent eagerly,
-   * and pi freezes a session's UI mode at that bind. Resolved per call: a
-   * host outlives the stream that speaks for it.
+   * UI sink for hosts built after this call. Lives here because `create` binds
+   * the agent eagerly and pi fixes the UI at bind time.
    */
   public setUi(ui: (host: SessionHost) => SessionUi | undefined): void {
     this.ui = ui;
@@ -89,7 +85,7 @@ export class SessionRegistry {
     await this.runtime.init();
   }
 
-  /** Sessions on disk, newest first; reads only each file's header line. */
+  /** Newest first; reads only each file's header. */
   public async list(cwd?: string): Promise<readonly SessionSummary[]> {
     const summaries = (
       await Pool.mapPooled(
@@ -104,15 +100,13 @@ export class SessionRegistry {
     return summaries.sort((a, b) => b.modifiedAt - a.modifiedAt);
   }
 
-  /** The live host for `sessionId`, if one is currently loaded. */
   public peek(sessionId: string): SessionHost | undefined {
     return this.hosts.peek(sessionId);
   }
 
   /**
-   * Rename a session through pi's own session name, so its `/resume` picker shows
-   * it too; `null` clears it. A live session is renamed by its agent, a closed one
-   * by appending to its file under the turn lease. Answers with the name pi kept.
+   * Sets pi's session name; `null` clears it. A closed session's file is
+   * appended to under the turn lease. Returns the stored name.
    */
   public async setName(
     sessionId: string,
@@ -127,8 +121,7 @@ export class SessionRegistry {
       throw new Error(`unknown session: ${sessionId}`);
     }
     const next = SessionName.normalise(name);
-    // Reopening is a plain read today, but a pi that migrates the file rewrites it.
-    // The lease is only ever held for a whole turn, so a rename refuses rather than queues.
+    // Fails fast instead of waiting out a whole turn.
     return await SessionLease.hold(
       summary.path,
       "daemon",
@@ -141,7 +134,6 @@ export class SessionRegistry {
     );
   }
 
-  /** Every model this machine has credentials for, qualified as `SessionHost.setModel` takes them. */
   public models(): readonly ModelChoice[] {
     return this.runtime.models();
   }
@@ -164,7 +156,7 @@ export class SessionRegistry {
     );
   }
 
-  /** Start a new session; the agent is built eagerly because pi assigns the UUID and file. */
+  /** Builds the agent eagerly: pi assigns the session id. */
   public async create(
     options: SessionCreateOptions = {}
   ): Promise<SessionHost> {
@@ -189,11 +181,7 @@ export class SessionRegistry {
     await this.hosts.disposeAll();
   }
 
-  /**
-   * One session by id. Pi names a file for the id it carries, so the usual
-   * answer is one glob and one header; resolving it by listing would read the
-   * header of every session on disk to throw all but one away.
-   */
+  /** Tries files named for the id first, then falls back to a full listing. */
   private async find(sessionId: string): Promise<SessionSummary | undefined> {
     for (const path of await this.paths(`*/*${sessionId}.jsonl`)) {
       const summary = await readSummary(path);
@@ -201,7 +189,6 @@ export class SessionRegistry {
         return summary;
       }
     }
-    // A file named something else entirely: the id is the header's, not the name's.
     return (await this.list()).find(
       (summary) => summary.sessionId === sessionId
     );
@@ -224,8 +211,6 @@ export class SessionRegistry {
 
   private buildHost(label: string, settings: HostSettings): SessionHost {
     const ui = this.ui;
-    // Named so the sink can reach back for the host it belongs to; the closure
-    // only ever runs once construction has returned.
     const host: SessionHost = new SessionHost({
       label: `session ${label}`,
       settings,
@@ -235,7 +220,6 @@ export class SessionRegistry {
       modelRegistry: this.runtime.modelRegistry,
       settingsManagerFor: (cwd) => this.runtime.settingsManagerFor(cwd),
       persistSettings: async () => {},
-      // The terminal can hold the same file open, so every mutation goes through the turn lease.
       lease: "daemon",
       customTools: this.deps.customTools,
       ...(this.deps.systemInstruction === undefined

package/packages/core/src/session/SessionUi.ts

@@ -5,13 +5,13 @@ import type {
 
 import type { NoticeSeverity } from "../view/ViewBlock";
 
-/** The slice of pi's dialog options a surface without a terminal can honour; the rest is countdown chrome. */
+/** The subset of pi's dialog options a non-terminal surface honours. */
 export type UiAsk = {
   readonly timeout?: number;
   readonly signal?: AbortSignal;
 };
 
-/** Where an extension's own words go. Four of pi's thirty methods: the ones that address a human rather than a terminal. */
+/** The parts of pi's `ExtensionUIContext` a non-terminal surface implements. */
 export type SessionUi = {
   readonly notify: (text: string, severity: NoticeSeverity) => void;
   readonly select: (
@@ -31,15 +31,11 @@ export type SessionUi = {
   ) => Promise<string | undefined>;
 };
 
-/** Everything off the terminal paints with; also what pi's border getters hand back. */
 const IDENTITY = (text: string): string => text;
 
-/**
- * pi keeps its own `theme` instance to itself, and nothing off the terminal has
- * colours to paint with. `satisfies` covers the whole public surface — `keyof`
- * skips the private fields the cast is for — so a method pi adds is a type
- * error here rather than a throw inside somebody's event handler.
- */
+const DEFAULT_COLOR = { kind: "indexed", index: 7 } as const;
+
+/** `satisfies` checks every public member, so a method pi adds is a type error here. */
 const PLAIN_THEME = {
   fg: (_color: string, text: string) => text,
   bg: (_color: string, text: string) => text,
@@ -53,6 +49,9 @@ const PLAIN_THEME = {
   getColorMode: () => "truecolor",
   getThinkingBorderColor: () => IDENTITY,
   getBashModeBorderColor: () => IDENTITY,
+  appearance: "dark",
+  colors: new Proxy({}, { get: () => DEFAULT_COLOR }) as Theme["colors"],
+  style: IDENTITY,
 } satisfies { [K in keyof Theme]: Theme[K] } as unknown as Theme;
 
 function severityOf(
@@ -61,7 +60,7 @@ function severityOf(
   return kind === "warning" ? "warn" : (kind ?? "info");
 }
 
-/** A dialog an extension awaits goes unanswered rather than ever throwing at it. */
+/** A failing sink answers `undefined` instead of throwing. */
 async function settle<T>(
   ask: () => Promise<T> | undefined
 ): Promise<T | undefined> {
@@ -74,13 +73,10 @@ async function settle<T>(
 }
 
 /**
- * Widens the sink onto pi's `ExtensionUIContext`, no-opping everything a
- * terminal owns exactly as pi's own RPC mode does. `sink` is read per call, so
- * an agent rebuilt under a host keeps whatever its host was last handed.
+ * Adapts a sink to pi's `ExtensionUIContext`; terminal-only methods are no-ops,
+ * as in pi's RPC mode. `sink` is read per call.
  *
- * Every method has to be an *own* property: pi re-wraps what it is given with
- * `{ ...ui }` (`runner.js:274`), which copies own enumerable keys only. A class
- * instance would arrive with `notify` and the rest of the prototype missing.
+ * Must be a plain object: pi copies it with `{ ...ui }`, which drops prototype methods.
  */
 export function adaptSessionUi(
   sink: () => SessionUi | undefined

package/packages/core/src/session/WriteMark.ts

@@ -1,32 +1,26 @@
 import type { EventLog } from "./EventLog";
 
-/** How much of a session file one process can account for: durable lines, and pi's own entries. */
+/** Lines in a session file (`head`) and entries pi holds in memory (`entries`). */
 export type WriteMark = {
   readonly head: number;
   readonly entries: number;
 };
 
-/** Pi's in-memory entry list: an `AgentSession`'s `sessionManager`, or one held directly. */
 type EntrySource = {
   getEntries(): readonly unknown[];
 };
 
-/** Nothing accounted for yet, which `foreignSince` reads as "the file is pi's to write". */
 const UNREAD: WriteMark = { head: 0, entries: 0 };
 
-/** Head first: an append between the two reads must under-count the file, never over. */
+/** Reads head first so a concurrent append under-counts the file, never over-counts. */
 async function of(log: EventLog, source: EntrySource): Promise<WriteMark> {
   return { head: await log.head(), entries: source.getEntries().length };
 }
 
 /**
- * Whether the file gained lines beyond the ones pi appended from memory. A turn, a
- * model change, a compaction, a `/name` and an idle `!bash` all move both counts
- * together, so only a writer that is not this process makes the difference positive.
- *
- * pi names a session file before it writes one, buffering entries until the first
- * assistant reply, so a mark taken before the file exists is answered by the whole of
- * it: header plus every entry pi was holding.
+ * Whether another process appended lines since `mark`. Our own writes move both
+ * counts together. A mark taken before pi created the file (`head` 0) counts
+ * the header plus every buffered entry as ours.
  */
 function foreignSince(mark: WriteMark, next: WriteMark): boolean {
   const base = mark.head === 0 ? { head: 1, entries: 0 } : mark;
@@ -34,10 +28,8 @@ function foreignSince(mark: WriteMark, next: WriteMark): boolean {
 }
 
 /**
- * Whether every line the file gained since `mark` is one no reader has to replay.
- * A rename appends `session_info` and moves no history, so a surface that absorbs
- * it stays on the session it is already holding. Only ask between turns: a window
- * that also holds our own appends is not benign, and a running turn's is.
+ * Whether every line added since `mark` is a `session_info` (a rename), so no
+ * replay is needed. Only meaningful between turns.
  */
 async function benignSince(log: EventLog, mark: WriteMark): Promise<boolean> {
   const added = await log.read(mark.head);
@@ -47,5 +39,4 @@ async function benignSince(log: EventLog, mark: WriteMark): Promise<boolean> {
   );
 }
 
-/** Write accounting over one session file: whose lines are these? */
 export const WriteMark = { UNREAD, of, foreignSince, benignSince };

package/packages/core/src/shared/Cli.ts

@@ -1,4 +1,4 @@
-// Never throw on an unknown flag or positional: the same argv reaches every mode.
+// Ignores unknown flags and positionals: the same argv reaches every mode.
 function scan(
   args: ReadonlyArray<string>,
   visit: (key: string, take: () => string | undefined) => void

package/packages/core/src/shared/DaemonUnit.ts

@@ -1,12 +1,11 @@
 import type { Unit } from "./Supervisor";
 
-/** The single unit every pim surface runs inside; `--surfaces` picks which of them come up. */
 export const DaemonUnit = {
   mode: "daemon",
   description: "Pim daemon",
 } satisfies Unit;
 
-/** One unit per surface, which is how pim shipped until the surfaces shared a process. */
+/** Legacy per-surface units, removed on install. */
 export const SupersededUnits: ReadonlyArray<Unit> = [
   { mode: "web", description: "Pim web daemon" },
   { mode: "telegram", description: "Pim Telegram daemon" },

package/packages/core/src/shared/DiffLines.ts

@@ -28,7 +28,7 @@ export type ToolDiff = {
   readonly hunks: readonly ToolDiffHunk[];
 };
 
-// Keep the EOF-newline flag out of `lines`, or `joinComparable` emits a phantom blank line.
+// The EOF newline is a flag, not an empty last line, or diffs gain a phantom blank line.
 export type ToolDiffSide = {
   readonly lines: readonly string[];
   readonly hasTrailingNewline: boolean;
@@ -48,16 +48,11 @@ function buildToolDiff(
 
   const lines = build(oldSide.lines, newSide.lines);
 
-  if (!lines.some((line) => line.kind !== "context")) {
+  if (lines.every((line) => line.kind === "context")) {
     return undefined;
   }
 
-  const emphasized = attachEmphasis(lines);
-
-  return {
-    path,
-    hunks: buildHunks(emphasized, contextSize),
-  };
+  return { path, hunks: buildHunks(attachEmphasis(lines), contextSize) };
 }
 
 function fromText(text: string): ToolDiffSide {
@@ -82,48 +77,35 @@ function attachEmphasis(
   let i = 0;
 
   while (i < result.length) {
-    if (result[i]?.kind !== "removed") {
+    if (result[i]!.kind !== "removed") {
       i += 1;
       continue;
     }
 
     let removedEnd = i;
-    while (
-      removedEnd < result.length &&
-      result[removedEnd]?.kind === "removed"
-    ) {
+    while (result[removedEnd]?.kind === "removed") {
       removedEnd += 1;
     }
-
     let addedEnd = removedEnd;
-    while (addedEnd < result.length && result[addedEnd]?.kind === "added") {
+    while (result[addedEnd]?.kind === "added") {
       addedEnd += 1;
     }
 
-    const removedCount = removedEnd - i;
-    const addedCount = addedEnd - removedEnd;
-
-    if (removedCount > 0 && removedCount === addedCount) {
-      for (let k = 0; k < removedCount; k += 1) {
-        const removed = result[i + k];
-        const added = result[removedEnd + k];
-
-        if (removed === undefined || added === undefined) {
-          continue;
-        }
-
+    // Only pair lines when the removed and added runs are the same length.
+    const count = removedEnd - i;
+    if (count === addedEnd - removedEnd) {
+      for (let k = 0; k < count; k += 1) {
+        const removed = result[i + k]!;
+        const added = result[removedEnd + k]!;
         const ranges = computeIntraLineRanges(removed.text, added.text);
-
-        if (ranges === undefined) {
-          continue;
+        if (ranges !== undefined) {
+          result[i + k] = { ...removed, emphasis: ranges.removed };
+          result[removedEnd + k] = { ...added, emphasis: ranges.added };
         }
-
-        result[i + k] = { ...removed, emphasis: ranges.removed };
-        result[removedEnd + k] = { ...added, emphasis: ranges.added };
       }
     }
 
-    i = addedEnd > i ? addedEnd : i + 1;
+    i = addedEnd;
   }
 
   return result;

package/packages/core/src/shared/DiffRenderer.ts

@@ -112,8 +112,7 @@ function backgroundsFor(theme: Theme): DiffBackgrounds {
 }
 
 function isLightTheme(theme: Theme): boolean {
-  const name = theme.name?.toLowerCase() ?? "";
-  return name === "light" || name.includes("light");
+  return theme.name?.toLowerCase().includes("light") ?? false;
 }
 
 function renderHunk(
@@ -174,10 +173,6 @@ function applyEmphasis(
   lineBg: string,
   emphBg: string
 ): string {
-  if (ranges.length === 0) {
-    return text;
-  }
-
   const starts = new Set<number>();
   const ends = new Set<number>();
 
@@ -192,6 +187,9 @@ function applyEmphasis(
     return text;
   }
 
+  const marker = (pos: number): string =>
+    (ends.has(pos) ? lineBg : "") + (starts.has(pos) ? emphBg : "");
+
   let result = "";
   let visiblePos = 0;
   let i = 0;
@@ -209,16 +207,9 @@ function applyEmphasis(
       continue;
     }
 
-    if (ends.has(visiblePos) || starts.has(visiblePos)) {
-      if (i > segStart) {
-        result += text.slice(segStart, i);
-      }
-      if (ends.has(visiblePos)) {
-        result += lineBg;
-      }
-      if (starts.has(visiblePos)) {
-        result += emphBg;
-      }
+    const mark = marker(visiblePos);
+    if (mark !== "") {
+      result += text.slice(segStart, i) + mark;
       segStart = i;
     }
 
@@ -226,17 +217,7 @@ function applyEmphasis(
     i += 1;
   }
 
-  if (i > segStart) {
-    result += text.slice(segStart, i);
-  }
-  if (ends.has(visiblePos)) {
-    result += lineBg;
-  }
-  if (starts.has(visiblePos)) {
-    result += emphBg;
-  }
-
-  return result;
+  return result + text.slice(segStart) + marker(visiblePos);
 }
 
 function applyBackground(

package/packages/core/src/shared/Directories.ts

@@ -10,11 +10,11 @@ export type DirectoryEntry = {
 };
 
 export type DirectoryListing = {
-  /** What was read: absolute, resolved, and with `~` expanded. */
+  /** Absolute, resolved, `~` expanded. */
   readonly path: string;
-  /** Absent at the root of the filesystem, which is its own parent. */
+  /** Absent at the filesystem root. */
   readonly parent?: string;
-  /** The directories inside it, name-sorted, hidden ones included. */
+  /** Subdirectories only, name-sorted, hidden included. */
   readonly entries: readonly DirectoryEntry[];
 };
 
@@ -78,7 +78,7 @@ function refusal(error: unknown, path: string): string {
   }
 }
 
-/** Makes one directory inside an existing one. Never recursive: a parent that is missing is said so, not invented. */
+/** Not recursive: a missing parent is an error. */
 async function create(path: string): Promise<void> {
   const name = basename(Paths.expandHome(path));
   if (name === "" || name === "." || name === "..") {