@hraness/dawg 0.0.0-stage → 0.3.0

package/src/session/delta.ts

@@ -0,0 +1,249 @@
+/**
+ * Reverse deltas for session history.
+ *
+ * Every event stores a `rewind`: how to turn the composition it produced back
+ * into the one it replaced, instead of the whole previous composition.
+ * Objects diff per key, arrays of `{id}` objects diff per id and position,
+ * and anything else is replaced wholesale. Applying the rewinds of the newest
+ * events in reverse order recovers any older composition, which is what undo
+ * and the daemon's rebase need. A single-note edit costs about 150 bytes
+ * instead of a full copy of the score, so the record stays small and the
+ * session never becomes un-editable.
+ */
+export type Rewind =
+  /** The value in the earlier composition (also used for a key that was removed). */
+  | { set: unknown }
+  /** The key did not exist in the earlier composition. */
+  | { del: true }
+  /** Per-key rewinds for a plain object. */
+  | { obj: Record<string, Rewind> }
+  /**
+   * An array of `{id}` objects: remove the items at `drop` (indices into the
+   * later array), then place `put` values at their earlier indices.
+   */
+  | { arr: { drop: number[]; put: [number, unknown][] } };
+
+const MAX_DEPTH = 16;
+
+/** Applying this rewind changes nothing. */
+export const IDENTITY_REWIND: Rewind = Object.freeze({ obj: {} }) as Rewind;
+
+export function isIdentityRewind(value: Rewind | undefined): boolean {
+  return (
+    value !== undefined && "obj" in value && Object.keys(value.obj).length === 0
+  );
+}
+
+/** The rewind that turns `after` back into `before`; identity when equal. */
+export function diffRewind(before: unknown, after: unknown): Rewind {
+  return diff(before, after, 0) ?? IDENTITY_REWIND;
+}
+
+function diff(
+  before: unknown,
+  after: unknown,
+  depth: number,
+): Rewind | undefined {
+  if (depth >= MAX_DEPTH)
+    return deepEqual(before, after) ? undefined : { set: before };
+  if (isPlainObject(before) && isPlainObject(after)) {
+    const obj: Record<string, Rewind> = {};
+    for (const key of Object.keys(before)) {
+      if (!(key in after) || after[key] === undefined)
+        obj[key] = { set: before[key] };
+      else {
+        const child = diff(before[key], after[key], depth + 1);
+        if (child) obj[key] = child;
+      }
+    }
+    for (const key of Object.keys(after))
+      if (!(key in before) || before[key] === undefined)
+        obj[key] = { del: true };
+    return Object.keys(obj).length === 0 ? undefined : { obj };
+  }
+  if (isKeyedArray(before) && isKeyedArray(after)) {
+    const beforeIndex = new Map<string, number>();
+    before.forEach((item, index) => beforeIndex.set(item.id, index));
+    // Greedy common subsequence by id: an item is kept when it is unchanged
+    // and keeps its relative order. Edits touch few items, so this is near
+    // optimal and always correct; a full reorder degrades to a full copy.
+    const kept = new Set<number>();
+    const drop: number[] = [];
+    let last = -1;
+    after.forEach((item, index) => {
+      const at = beforeIndex.get(item.id);
+      if (at !== undefined && at > last && deepEqual(before[at], item)) {
+        kept.add(at);
+        last = at;
+      } else drop.push(index);
+    });
+    const put: [number, unknown][] = [];
+    before.forEach((item, index) => {
+      if (!kept.has(index)) put.push([index, item]);
+    });
+    return drop.length === 0 && put.length === 0
+      ? undefined
+      : { arr: { drop, put } };
+  }
+  return deepEqual(before, after) ? undefined : { set: before };
+}
+
+/** The earlier value: `rewind` applied to `after`. Throws on a shape mismatch. */
+export function applyRewind(after: unknown, rewind: Rewind): unknown {
+  if ("set" in rewind) return rewind.set;
+  if ("del" in rewind) return undefined;
+  if ("obj" in rewind) {
+    // The identity rewind applies to any value, not only objects.
+    if (isIdentityRewind(rewind)) return after;
+    if (!isPlainObject(after)) throw new Error("rewind expects an object");
+    const result: Record<string, unknown> = { ...after };
+    for (const [key, child] of Object.entries(rewind.obj)) {
+      if ("del" in child) delete result[key];
+      else result[key] = applyRewind(result[key], child);
+    }
+    return result;
+  }
+  if (!Array.isArray(after)) throw new Error("rewind expects an array");
+  const dropped = new Set(rewind.arr.drop);
+  const kept: unknown[] = [];
+  after.forEach((item, index) => {
+    if (!dropped.has(index)) kept.push(item);
+  });
+  const put = new Map(rewind.arr.put);
+  const length = kept.length + put.size;
+  const result: unknown[] = [];
+  let next = 0;
+  for (let index = 0; index < length; index += 1) {
+    if (put.has(index)) result.push(put.get(index));
+    else {
+      if (next >= kept.length) throw new Error("rewind indices are invalid");
+      result.push(kept[next]);
+      next += 1;
+    }
+  }
+  if (next !== kept.length) throw new Error("rewind indices are invalid");
+  return result;
+}
+
+/**
+ * The composition before `events[index]`, by rewinding `composition` (the
+ * one after the last event) through every later event. Undefined when any
+ * event in that range has no usable rewind.
+ */
+export function rewindComposition(
+  composition: unknown,
+  events: readonly { rewind?: Rewind | undefined }[],
+  index: number,
+): unknown {
+  if (!Number.isSafeInteger(index) || index < 0 || index >= events.length)
+    return undefined;
+  let value = composition;
+  try {
+    for (let at = events.length - 1; at >= index; at -= 1) {
+      const rewind = events[at]!.rewind;
+      if (rewind === undefined) return undefined;
+      value = applyRewind(value, rewind);
+    }
+  } catch {
+    return undefined;
+  }
+  return value;
+}
+
+/** Validates a stored rewind from `unknown`; `undefined` when absent. */
+export function parseRewind(value: unknown): Rewind | undefined {
+  if (value === undefined) return undefined;
+  return parse(value, 0);
+}
+
+function parse(value: unknown, depth: number): Rewind {
+  if (!isPlainObject(value) || depth > MAX_DEPTH)
+    throw new Error("session event rewind is invalid");
+  const keys = Object.keys(value);
+  if (keys.length !== 1) throw new Error("session event rewind is invalid");
+  if ("set" in value) {
+    if (value.set === undefined)
+      throw new Error("session event rewind is invalid");
+    return { set: value.set };
+  }
+  if ("del" in value) {
+    if (value.del !== true) throw new Error("session event rewind is invalid");
+    return { del: true };
+  }
+  if ("obj" in value) {
+    if (!isPlainObject(value.obj))
+      throw new Error("session event rewind is invalid");
+    const obj: Record<string, Rewind> = {};
+    for (const [key, child] of Object.entries(value.obj))
+      obj[key] = parse(child, depth + 1);
+    return { obj };
+  }
+  if ("arr" in value && isPlainObject(value.arr)) {
+    const { drop, put } = value.arr;
+    if (
+      !Array.isArray(drop) ||
+      !Array.isArray(put) ||
+      !drop.every((index) => Number.isSafeInteger(index) && index >= 0) ||
+      !put.every(
+        (entry) =>
+          Array.isArray(entry) &&
+          entry.length === 2 &&
+          Number.isSafeInteger(entry[0]) &&
+          entry[0] >= 0 &&
+          entry[1] !== undefined,
+      )
+    )
+      throw new Error("session event rewind is invalid");
+    return {
+      arr: {
+        drop: drop as number[],
+        put: put.map((entry) => [entry[0], entry[1]] as [number, unknown]),
+      },
+    };
+  }
+  throw new Error("session event rewind is invalid");
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isKeyedArray(value: unknown): value is { id: string }[] {
+  if (!Array.isArray(value)) return false;
+  const seen = new Set<string>();
+  for (const item of value) {
+    if (!isPlainObject(item) || typeof item.id !== "string") return false;
+    if (seen.has(item.id)) return false;
+    seen.add(item.id);
+  }
+  return true;
+}
+
+function deepEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (
+    typeof a !== "object" ||
+    typeof b !== "object" ||
+    a === null ||
+    b === null
+  )
+    return false;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  if (Array.isArray(a)) {
+    const other = b as unknown[];
+    if (a.length !== other.length) return false;
+    for (let index = 0; index < a.length; index += 1)
+      if (!deepEqual(a[index], other[index])) return false;
+    return true;
+  }
+  const left = a as Record<string, unknown>;
+  const right = b as Record<string, unknown>;
+  const keys = Object.keys(left).filter((key) => left[key] !== undefined);
+  const otherKeys = Object.keys(right).filter(
+    (key) => right[key] !== undefined,
+  );
+  if (keys.length !== otherKeys.length) return false;
+  for (const key of keys)
+    if (!(key in right) || !deepEqual(left[key], right[key])) return false;
+  return true;
+}

package/src/session/list.ts

@@ -0,0 +1,180 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import {
+  readCurrentSessionId,
+  sessionPaths,
+  loadSession,
+  stateDir,
+} from "./store.ts";
+import { daemonLockPath } from "./protocol.ts";
+
+export type SessionSummary = {
+  sessionId: string;
+  revision: number;
+  updatedAt: string;
+  current: boolean;
+  daemonPid: number | null;
+  tracks: number | null;
+  name: string;
+  nameSource: "auto" | "user";
+  forkOf?: { sessionId: string; revision: number };
+  error?: string;
+};
+
+/** Lists sessions under `<workspace>/.dawg/sessions`, newest first. */
+export async function listSessions(
+  workspace: string,
+): Promise<SessionSummary[]> {
+  let names: string[];
+  try {
+    names = await readdir(join(stateDir(workspace), "sessions"));
+  } catch {
+    return [];
+  }
+  const current = await readCurrentSessionId(workspace).catch(() => undefined);
+  const summaries: SessionSummary[] = [];
+  for (const name of names
+    .filter((entry) => entry.endsWith(".json"))
+    .slice(0, 512)) {
+    const sessionId = name.slice(0, -".json".length);
+    let paths;
+    try {
+      paths = sessionPaths(workspace, sessionId);
+    } catch {
+      continue;
+    }
+    const daemonPid = await liveDaemonPid(daemonLockPath(paths));
+    try {
+      const record = await loadSession<{ tracks?: unknown }>(paths);
+      summaries.push({
+        sessionId,
+        revision: record.revision,
+        updatedAt: record.updatedAt,
+        current: sessionId === current,
+        daemonPid,
+        tracks: Array.isArray(record.composition?.tracks)
+          ? record.composition.tracks.length
+          : null,
+        name: record.meta.name,
+        nameSource: record.meta.nameSource,
+        ...(record.meta.forkOf ? { forkOf: record.meta.forkOf } : {}),
+      });
+    } catch (error) {
+      summaries.push({
+        sessionId,
+        revision: -1,
+        updatedAt: "",
+        current: sessionId === current,
+        daemonPid,
+        tracks: null,
+        name: "",
+        nameSource: "auto",
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+  return summaries.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+}
+
+export async function printSessions(
+  workspace: string,
+  out: { write(text: string): unknown },
+): Promise<void> {
+  const sessions = await listSessions(workspace);
+  if (sessions.length === 0) {
+    out.write("no sessions in .dawg (run `dawg` to create one)\n");
+    return;
+  }
+  for (const session of sessions) {
+    const marker = session.current ? "*" : " ";
+    const detail = session.error
+      ? `unreadable · ${session.error}`
+      : `rev ${session.revision} · ${session.tracks ?? "?"} tracks · updated ${session.updatedAt}`;
+    const daemon = session.daemonPid ? ` · dawgd pid ${session.daemonPid}` : "";
+    out.write(`${marker} ${formatSessionLine(session, sessions)}${daemon}\n`);
+  }
+}
+
+/** One `/sessions` row: name, short id, tracks, revision, age, fork parent. */
+export function formatSessionLine(
+  session: SessionSummary,
+  all: readonly SessionSummary[] = [],
+  now = Date.now(),
+): string {
+  const id = session.sessionId.slice(0, 8);
+  if (session.error) return `${id}  unreadable · ${session.error}`;
+  const parent = session.forkOf
+    ? all.find((entry) => entry.sessionId === session.forkOf!.sessionId)
+    : undefined;
+  const fork = session.forkOf
+    ? ` · fork of ${parent?.name || session.forkOf.sessionId.slice(0, 8)}@${session.forkOf.revision}`
+    : "";
+  return `${session.name.padEnd(24)} ${id}  ${session.tracks ?? "?"} tracks · rev ${session.revision} · ${relativeTime(session.updatedAt, now)}${fork}`;
+}
+
+export function relativeTime(iso: string, now = Date.now()): string {
+  const at = Date.parse(iso);
+  if (!Number.isFinite(at)) return "unknown";
+  const seconds = Math.max(0, Math.round((now - at) / 1000));
+  if (seconds < 60) return "just now";
+  if (seconds < 3600) return `${Math.floor(seconds / 60)}m ago`;
+  if (seconds < 86_400) return `${Math.floor(seconds / 3600)}h ago`;
+  return `${Math.floor(seconds / 86_400)}d ago`;
+}
+
+export type SessionResolution =
+  | { status: "found"; session: SessionSummary }
+  | { status: "missing" }
+  | { status: "ambiguous"; candidates: SessionSummary[] };
+
+/**
+ * Resolves `--session <name|id>`: an exact id, then an exact name
+ * (case-insensitive), then a unique id prefix of at least 4 characters.
+ */
+export function resolveSession(
+  sessions: readonly SessionSummary[],
+  query: string,
+): SessionResolution {
+  const readable = sessions.filter((session) => !session.error);
+  const byId = readable.find((session) => session.sessionId === query);
+  if (byId) return { status: "found", session: byId };
+  const lower = query.trim().toLowerCase();
+  const byName = readable.filter(
+    (session) => session.name.toLowerCase() === lower,
+  );
+  if (byName.length === 1) return { status: "found", session: byName[0]! };
+  if (byName.length > 1) return { status: "ambiguous", candidates: byName };
+  if (query.length >= 4) {
+    const byPrefix = readable.filter((session) =>
+      session.sessionId.startsWith(query),
+    );
+    if (byPrefix.length === 1)
+      return { status: "found", session: byPrefix[0]! };
+    if (byPrefix.length > 1)
+      return { status: "ambiguous", candidates: byPrefix };
+  }
+  return { status: "missing" };
+}
+
+export function ambiguousSessionMessage(
+  query: string,
+  candidates: readonly SessionSummary[],
+): string {
+  return [
+    `session "${query}" is ambiguous; use an id:`,
+    ...candidates.map((session) => `  ${formatSessionLine(session)}`),
+  ].join("\n");
+}
+
+async function liveDaemonPid(lockPath: string): Promise<number | null> {
+  try {
+    const text = await readFile(join(lockPath, "owner"), "utf8");
+    if (text.length > 256) return null;
+    const pid = (JSON.parse(text) as { pid?: unknown }).pid;
+    if (!Number.isSafeInteger(pid) || (pid as number) <= 0) return null;
+    process.kill(pid as number, 0);
+    return pid as number;
+  } catch {
+    return null;
+  }
+}

package/src/session/lock.ts

@@ -0,0 +1,92 @@
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+
+type LockOwner = { pid: number; token: string };
+
+/** Never expire an active writer's lock merely because a write takes time. */
+export async function acquireSessionLock(
+  path: string,
+  timeoutMs = 3_000,
+): Promise<() => Promise<void>> {
+  const owner: LockOwner = { pid: process.pid, token: randomUUID() };
+  const started = Date.now();
+  while (true) {
+    try {
+      await mkdir(path);
+    } catch (error) {
+      if (!hasCode(error, "EEXIST")) throw error;
+      await reclaimDeadOwner(path);
+      if (Date.now() - started >= timeoutMs)
+        throw new Error("timed out waiting for the dawg session lock");
+      await new Promise((resolve) => setTimeout(resolve, 8));
+      continue;
+    }
+    try {
+      await writeFile(join(path, "owner"), JSON.stringify(owner), {
+        encoding: "utf8",
+        flag: "wx",
+      });
+    } catch (error) {
+      await rm(path, { recursive: true, force: true });
+      throw error;
+    }
+    return async () => {
+      const current = await readOwner(path);
+      if (current?.pid === owner.pid && current.token === owner.token)
+        await rm(path, { recursive: true, force: true });
+    };
+  }
+}
+
+async function reclaimDeadOwner(path: string): Promise<void> {
+  // Serialize reclaimers separately. Otherwise two readers of a dead PID can
+  // remove a new writer's lock after the first reclaimer removes the old one.
+  const reclaimPath = `${path}.reclaim`;
+  try {
+    await mkdir(reclaimPath);
+  } catch (error) {
+    if (hasCode(error, "EEXIST")) return;
+    throw error;
+  }
+  try {
+    const owner = await readOwner(path);
+    if (!owner) return; // A writer may still be publishing its owner record.
+    try {
+      process.kill(owner.pid, 0);
+    } catch (error) {
+      if (hasCode(error, "ESRCH"))
+        await rm(path, { recursive: true, force: true });
+    }
+  } finally {
+    await rm(reclaimPath, { recursive: true, force: true });
+  }
+}
+
+async function readOwner(path: string): Promise<LockOwner | undefined> {
+  try {
+    const text = await readFile(join(path, "owner"), "utf8");
+    if (text.length > 256) return undefined;
+    const value: unknown = JSON.parse(text);
+    // Read locks left by earlier versions (Track 0.1), which stored only a PID.
+    if (Number.isSafeInteger(value) && (value as number) > 0)
+      return { pid: value as number, token: "legacy" };
+    if (
+      typeof value === "object" &&
+      value !== null &&
+      "pid" in value &&
+      Number.isSafeInteger(value.pid) &&
+      (value.pid as number) > 0 &&
+      "token" in value &&
+      typeof value.token === "string"
+    )
+      return { pid: value.pid as number, token: value.token };
+  } catch {
+    // Missing, unreadable, or incomplete owner records cannot prove death.
+  }
+  return undefined;
+}
+
+function hasCode(error: unknown, code: string): boolean {
+  return error instanceof Error && "code" in error && error.code === code;
+}