pim-agent 0.0.1 → 0.10.0

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

@@ -0,0 +1,279 @@
+import { readFileSync, unlinkSync } from "node:fs";
+import { mkdir, open, stat, unlink, utimes } from "node:fs/promises";
+import { hostname } from "node:os";
+import { dirname } from "node:path";
+
+import { FileWatch } from "../shared/FileWatch";
+import { FsErrors } from "../shared/FsErrors";
+import { Fs } from "../shared/Fs";
+import { Json } from "../shared/Json";
+
+export type LeaseFrontend = "tui" | "daemon";
+
+/** What one holder wrote into `<sessionPath>.lease`. */
+export type LeaseRecord = {
+  readonly pid: number;
+  readonly hostname: string;
+  readonly frontend: LeaseFrontend;
+  readonly startedAt: number;
+};
+
+export type LeaseHandle = {
+  release(): Promise<void>;
+};
+
+export type AcquireResult =
+  | { readonly ok: true; readonly handle: LeaseHandle }
+  /** Absent when the holder's file is torn or vanished mid-read. */
+  | { readonly ok: false; readonly holder?: LeaseRecord };
+
+export type LeaseOptions = {
+  readonly heartbeatMs?: number;
+  readonly pollMs?: number;
+  readonly timeoutMs?: number;
+  /** Called with the current holder each time an acquire is denied and another poll follows. */
+  readonly onBlocked?: (holder: LeaseRecord | undefined) => void;
+};
+
+const HEARTBEAT_MS = 5_000;
+const STALE_MS = 30_000;
+const POLL_MS = 250;
+const TIMEOUT_MS = 5 * 60_000;
+const STEAL_ATTEMPTS = 3;
+const STEAL_BACKOFF_MS = 50;
+
+const HOST = hostname();
+
+const held = new Set<string>();
+let exitHooked = false;
+
+function pathFor(sessionPath: string): string {
+  return `${sessionPath}.lease`;
+}
+
+function toRecord(value: unknown): LeaseRecord | undefined {
+  const raw = Json.asRecord(value);
+  if (
+    typeof raw?.pid !== "number" ||
+    typeof raw.hostname !== "string" ||
+    typeof raw.startedAt !== "number" ||
+    (raw.frontend !== "tui" && raw.frontend !== "daemon")
+  ) {
+    return undefined;
+  }
+  return {
+    pid: raw.pid,
+    hostname: raw.hostname,
+    frontend: raw.frontend,
+    startedAt: raw.startedAt,
+  };
+}
+
+async function recordAt(path: string): Promise<LeaseRecord | undefined> {
+  return toRecord(await Fs.readJsonOr<unknown>(path, undefined));
+}
+
+/** The current holder, or undefined when the file is absent, torn, or half-written. */
+async function read(sessionPath: string): Promise<LeaseRecord | undefined> {
+  return await recordAt(pathFor(sessionPath));
+}
+
+function isAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    // EPERM is someone else's live process.
+    return FsErrors.code(err) !== "ESRCH";
+  }
+}
+
+/** A holder is stale once its pid is gone, or once it stops heartbeating; never across hosts. */
+function isStale(
+  record: LeaseRecord,
+  mtimeMs: number,
+  now = Date.now()
+): boolean {
+  if (record.hostname !== HOST) {
+    return false;
+  }
+  return !isAlive(record.pid) || now - mtimeMs > STALE_MS;
+}
+
+/** Whether this very process wrote that record — the one holder allowed to release it. */
+function isOurs(record: LeaseRecord | undefined): boolean {
+  return record?.pid === process.pid && record.hostname === HOST;
+}
+
+async function stealable(
+  path: string,
+  record: LeaseRecord | undefined
+): Promise<boolean> {
+  const mtimeMs = await stat(path).then(
+    (stats) => stats.mtimeMs,
+    () => undefined
+  );
+  if (mtimeMs === undefined) {
+    return true;
+  }
+  // A torn file is a holder mid-write until it stops being refreshed.
+  return record === undefined
+    ? Date.now() - mtimeMs > STALE_MS
+    : isStale(record, mtimeMs);
+}
+
+async function claim(
+  path: string,
+  frontend: LeaseFrontend
+): Promise<LeaseRecord | undefined> {
+  const record: LeaseRecord = {
+    pid: process.pid,
+    hostname: HOST,
+    frontend,
+    startedAt: Date.now(),
+  };
+  const file = await open(path, "wx").catch((err: unknown) => {
+    if (FsErrors.code(err) === "EEXIST") {
+      return undefined;
+    }
+    // The session's directory is pi's to create, and a lease can precede the file it guards.
+    if (FsErrors.code(err) === "ENOENT") {
+      return mkdir(dirname(path), { recursive: true }).then(() =>
+        open(path, "wx")
+      );
+    }
+    throw err;
+  });
+  if (file === undefined) {
+    return undefined;
+  }
+  try {
+    await file.writeFile(`${JSON.stringify(record)}\n`);
+  } finally {
+    await file.close();
+  }
+  return record;
+}
+
+function hookExit(): void {
+  if (exitHooked) {
+    return;
+  }
+  exitHooked = true;
+  process.on("exit", () => {
+    for (const path of held) {
+      try {
+        if (isOurs(toRecord(Json.tryParseJson(readFileSync(path, "utf8"))))) {
+          unlinkSync(path);
+        }
+      } catch {}
+    }
+  });
+}
+
+function handleFor(path: string, options: LeaseOptions): LeaseHandle {
+  held.add(path);
+  hookExit();
+  // Bump mtime rather than rewrite: a rename would clobber whoever holds the file next.
+  const beat = setInterval(() => {
+    const now = new Date();
+    void utimes(path, now, now).catch(() => undefined);
+  }, options.heartbeatMs ?? HEARTBEAT_MS);
+  beat.unref?.();
+
+  let released = false;
+  return {
+    release: async (): Promise<void> => {
+      if (released) {
+        return;
+      }
+      released = true;
+      clearInterval(beat);
+      held.delete(path);
+      if (isOurs(await recordAt(path))) {
+        await unlink(path).catch(() => undefined);
+      }
+    },
+  };
+}
+
+/** Create-exclusive, stealing only a lease whose holder is provably gone. */
+async function acquire(
+  sessionPath: string,
+  frontend: LeaseFrontend,
+  options: LeaseOptions = {}
+): Promise<AcquireResult> {
+  const path = pathFor(sessionPath);
+  for (let attempt = 0; ; attempt++) {
+    if (await claim(path, frontend)) {
+      return { ok: true, handle: handleFor(path, options) };
+    }
+    const holder = await recordAt(path);
+    if (attempt >= STEAL_ATTEMPTS || !(await stealable(path, holder))) {
+      return holder === undefined ? { ok: false } : { ok: false, holder };
+    }
+    await unlink(path).catch(() => undefined);
+    await Bun.sleep(STEAL_BACKOFF_MS);
+  }
+}
+
+/** Polls until the lease is free, the deadline passes, or the holder is stealable. */
+async function waitFor(
+  sessionPath: string,
+  frontend: LeaseFrontend,
+  options: LeaseOptions = {}
+): Promise<AcquireResult> {
+  const deadline = Date.now() + (options.timeoutMs ?? TIMEOUT_MS);
+  while (true) {
+    const result = await acquire(sessionPath, frontend, options);
+    if (result.ok || Date.now() >= deadline) {
+      return result;
+    }
+    options.onBlocked?.(result.holder);
+    await Bun.sleep(options.pollMs ?? POLL_MS);
+  }
+}
+
+function denial(result: { readonly holder?: LeaseRecord }): string {
+  const holder = result.holder;
+  const who =
+    holder === undefined
+      ? "another process"
+      : `${holder.frontend} (pid ${holder.pid})`;
+  return `Session is busy: ${who} still holds its turn lease.`;
+}
+
+/** The only safe way to take a lease: waits for it, and always gives it back. */
+async function hold<T>(
+  sessionPath: string,
+  frontend: LeaseFrontend,
+  work: () => Promise<T>,
+  options: LeaseOptions = {}
+): Promise<T> {
+  const result = await waitFor(sessionPath, frontend, options);
+  if (!result.ok) {
+    throw new Error(denial(result));
+  }
+  try {
+    return await work();
+  } finally {
+    await result.handle.release();
+  }
+}
+
+/** Fires whenever the lease appears, changes hands, or is released. */
+function watch(sessionPath: string, onChange: () => void): () => void {
+  return FileWatch.file(pathFor(sessionPath), onChange);
+}
+
+/** A turn lease over one session file, held as a sibling `<sessionPath>.lease`. */
+export const SessionLease = {
+  pathFor,
+  read,
+  acquire,
+  hold,
+  waitFor,
+  watch,
+  isStale,
+  isOurs,
+};

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

@@ -0,0 +1,267 @@
+import { join } from "node:path";
+
+import { Fs } from "../shared/Fs";
+import { Json } from "../shared/Json";
+import { Paths } from "../shared/Paths";
+
+export type SessionEntry = {
+  readonly archived?: boolean;
+  /** Sticky: set by hand, and 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. */
+  readonly expanded?: boolean;
+  /** What to call the directory instead of its base name; the directory itself is never touched. */
+  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. */
+  readonly order: readonly string[];
+};
+
+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.
+   */
+  readonly pins: readonly string[];
+};
+
+type Loaded = {
+  readonly sessions: Map<string, SessionEntry>;
+  readonly projects: Map<string, ProjectEntry>;
+  pins: string[];
+};
+
+const NONE: SessionEntry = {};
+
+/** Per-session and per-project overrides, shared by every surface on a machine. */
+export class SessionMeta {
+  private readonly file: string;
+  private readonly writes = Fs.serialised();
+
+  /** Defaults to `~/.pim/sessions.json`. */
+  public constructor(path?: string) {
+    this.file = path ?? join(Paths.pimHomeDir(), "sessions.json");
+  }
+
+  public async of(sessionId: string): Promise<SessionEntry> {
+    return (await this.sessions()).get(sessionId) ?? NONE;
+  }
+
+  /** One read for a whole listing; `of` per row is one read per row. */
+  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. */
+  public async pins(): Promise<readonly string[]> {
+    return ordered(await this.read());
+  }
+
+  public setArchived(sessionId: string, archived: boolean): Promise<void> {
+    return this.mutate((loaded) =>
+      put(loaded.sessions, sessionId, { archived })
+    );
+  }
+
+  public setUnread(sessionId: string, unread: boolean): Promise<void> {
+    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. */
+  public setPinned(cwd: string, pinned: boolean): Promise<void> {
+    return this.mutate((loaded) => {
+      const at = loaded.pins.indexOf(cwd);
+      if (at !== -1) {
+        loaded.pins.splice(at, 1);
+      }
+      if (pinned) {
+        loaded.pins.unshift(cwd);
+      }
+      return put(loaded.projects, cwd, { pinned });
+    });
+  }
+
+  /**
+   * 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. */
+  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. */
+  public setPinOrder(order: readonly string[]): Promise<void> {
+    return this.mutate((loaded) => {
+      loaded.pins = [...new Set(order)].filter(
+        (cwd) => loaded.projects.get(cwd)?.pinned === true
+      );
+      return true;
+    });
+  }
+
+  /** Drops the sessions that are gone; a pin outlives every session of its project. */
+  public prune(alive: ReadonlySet<string>): Promise<void> {
+    return this.mutate((loaded) => {
+      let dropped = false;
+      for (const sessionId of loaded.sessions.keys()) {
+        if (!alive.has(sessionId)) {
+          loaded.sessions.delete(sessionId);
+          dropped = true;
+        }
+      }
+      return dropped;
+    });
+  }
+
+  /** Settles the writes taken so far, for a clean stop. */
+  public async flush(): Promise<void> {
+    await this.writes.run(async () => undefined);
+  }
+
+  private async read(): Promise<Loaded> {
+    const raw = Json.asRecord(
+      await Fs.readJsonOr<unknown>(this.file, undefined)
+    );
+    if (raw?.version !== 1) {
+      return { sessions: new Map(), projects: new Map(), pins: [] };
+    }
+    return {
+      sessions: parseAll(raw.sessions, parseSession),
+      projects: parseAll(raw.projects, parseProject),
+      pins: Array.isArray(raw.pins)
+        ? raw.pins.filter((cwd) => typeof cwd === "string")
+        : [],
+    };
+  }
+
+  /** Re-reads under the lock, so a write by another process survives this one. */
+  private async mutate(update: (loaded: Loaded) => boolean): Promise<void> {
+    await this.writes.run(async () => {
+      const loaded = await this.read();
+      if (!update(loaded)) {
+        return;
+      }
+      await Paths.ensurePimHome();
+      await Fs.writeJson(this.file, {
+        version: 1,
+        sessions: Object.fromEntries(loaded.sessions),
+        projects: Object.fromEntries(loaded.projects),
+        pins: loaded.pins,
+      } satisfies Stored);
+    });
+  }
+}
+
+/**
+ * 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.
+ */
+function ordered({ projects, pins }: Loaded): readonly string[] {
+  const unplaced = new Set(
+    [...projects]
+      .filter(([, entry]) => entry.pinned === true)
+      .map(([cwd]) => cwd)
+  );
+  const listed = pins.filter((cwd) => unplaced.delete(cwd));
+  return [...listed, ...[...unplaced].sort()];
+}
+
+function put<T extends object>(
+  into: Map<string, T>,
+  key: string,
+  patch: T
+): boolean {
+  const next = onlySet({ ...into.get(key), ...patch });
+  if (Object.keys(next).length === 0) {
+    into.delete(key);
+  } else {
+    into.set(key, next);
+  }
+  return true;
+}
+
+/** Every field is opt-in, so a false flag or an empty name is the same as an absent one. */
+function onlySet<T extends object>(entry: T): T {
+  return Object.fromEntries(
+    Object.entries(entry).filter(
+      ([, value]) =>
+        value === true || (typeof value === "string" && value !== "")
+    )
+  ) as T;
+}
+
+function parseAll<T>(
+  value: unknown,
+  parse: (value: unknown) => T | undefined
+): Map<string, T> {
+  const parsed = new Map<string, T>();
+  for (const [key, entry] of Object.entries(Json.asRecord(value) ?? {})) {
+    const valid = parse(entry);
+    if (valid !== undefined) {
+      parsed.set(key, valid);
+    }
+  }
+  return parsed;
+}
+
+function parseSession(value: unknown): SessionEntry | undefined {
+  const raw = Json.asRecord(value);
+  if (raw === undefined || !isFlag(raw.archived) || !isFlag(raw.unread)) {
+    return undefined;
+  }
+  return onlySet({ archived: raw.archived, unread: raw.unread });
+}
+
+function parseProject(value: unknown): ProjectEntry | undefined {
+  const raw = Json.asRecord(value);
+  if (
+    raw === undefined ||
+    !isFlag(raw.pinned) ||
+    !isFlag(raw.expanded) ||
+    !isName(raw.label)
+  ) {
+    return undefined;
+  }
+  return onlySet({
+    pinned: raw.pinned,
+    expanded: raw.expanded,
+    label: raw.label,
+  });
+}
+
+function isFlag(value: unknown): value is boolean | undefined {
+  return value === undefined || typeof value === "boolean";
+}
+
+function isName(value: unknown): value is string | undefined {
+  return value === undefined || typeof value === "string";
+}

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

@@ -0,0 +1,18 @@
+/**
+ * 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.
+ */
+const LIMIT = 80;
+
+/** What pi should store for this name: whitespace collapsed, controls gone, `""` to clear. */
+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.
+  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 };