@hraness/dawg 0.0.0-stage → 0.2.0

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;
+}

package/src/session/meta.ts

@@ -0,0 +1,253 @@
+/**
+ * Session metadata: the human name, who chose it, and fork lineage. It is
+ * stored inside the session record beside the composition, versioned on its
+ * own counter so renames never bump the score revision or the undo history.
+ */
+export const MAX_SESSION_NAME_LENGTH = 40;
+export const DEFAULT_SESSION_NAME = "untitled";
+const MAX_TIMESTAMP_LENGTH = 64;
+const MAX_ID_LENGTH = 64;
+const FINGERPRINT_PATTERN = /^[0-9a-f]{1,32}$/;
+/** C0/C1 controls, zero-width and bidi formatting characters. */
+const UNPRINTABLE = new RegExp(
+  "[\\u0000-\\u001f\\u007f-\\u009f\\u200b-\\u200f\\u2028-\\u202e\\u2066-\\u2069\\ufeff]",
+  "g",
+);
+const ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+export type NameSource = "auto" | "user";
+
+export type SessionMeta = {
+  name: string;
+  /** `user` permanently stops auto-naming until `/rename --auto`. */
+  nameSource: NameSource;
+  forkOf?: { sessionId: string; revision: number };
+  createdAt: string;
+  updatedAt: string;
+  /** Incremented on every metadata write; independent of the score revision. */
+  version: number;
+  /** Fingerprint hash the current auto name was chosen for. */
+  namedFingerprint?: string;
+  /** Track-and-instrument-set hash at the last auto name. */
+  namedStructure?: string;
+};
+
+/** Fields a client may change. `null` clears an optional field. */
+export type MetaPatch = {
+  name?: string;
+  nameSource?: NameSource;
+  namedFingerprint?: string | null;
+  namedStructure?: string | null;
+};
+
+/** A conditional write applies only when every given field still matches. */
+export type MetaExpect = { name?: string; nameSource?: NameSource };
+
+export class MetaValidationError extends Error {
+  public constructor(message: string) {
+    super(message);
+    this.name = "MetaValidationError";
+  }
+}
+
+/** Trims, collapses whitespace, drops control characters, bounds to 40. */
+export function normalizeSessionName(value: unknown): string {
+  if (typeof value !== "string" || value.length > 1024)
+    throw new MetaValidationError("session name must be a short string");
+  const name = value
+    .replace(UNPRINTABLE, " ")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, MAX_SESSION_NAME_LENGTH)
+    .trim();
+  if (name.length === 0) throw new MetaValidationError("session name is empty");
+  return name;
+}
+
+export function defaultSessionMeta(
+  at: string,
+  name = DEFAULT_SESSION_NAME,
+): SessionMeta {
+  return {
+    name,
+    nameSource: "auto",
+    createdAt: at,
+    updatedAt: at,
+    version: 0,
+  };
+}
+
+/**
+ * Validates metadata read from disk or the wire. Records written before
+ * metadata existed get a deterministic name derived from their id.
+ */
+export function parseSessionMeta(
+  value: unknown,
+  fallback: { sessionId: string; updatedAt: string },
+): SessionMeta {
+  if (value === undefined || value === null)
+    return defaultSessionMeta(
+      fallback.updatedAt,
+      `session ${fallback.sessionId.slice(0, 8)}`,
+    );
+  if (typeof value !== "object" || Array.isArray(value))
+    throw new MetaValidationError("session meta must be an object");
+  const meta = value as Record<string, unknown>;
+  const nameSource = meta.nameSource;
+  if (nameSource !== "auto" && nameSource !== "user")
+    throw new MetaValidationError("session nameSource is invalid");
+  if (!Number.isSafeInteger(meta.version) || (meta.version as number) < 0)
+    throw new MetaValidationError("session meta version is invalid");
+  const result: SessionMeta = {
+    name: normalizeSessionName(meta.name),
+    nameSource,
+    createdAt: timestamp(meta.createdAt, "createdAt"),
+    updatedAt: timestamp(meta.updatedAt, "updatedAt"),
+    version: meta.version as number,
+  };
+  if (meta.forkOf !== undefined) {
+    const fork = meta.forkOf;
+    if (typeof fork !== "object" || fork === null)
+      throw new MetaValidationError("session forkOf is invalid");
+    const { sessionId, revision } = fork as Record<string, unknown>;
+    if (
+      typeof sessionId !== "string" ||
+      sessionId.length === 0 ||
+      sessionId.length > MAX_ID_LENGTH ||
+      !ID_PATTERN.test(sessionId) ||
+      !Number.isSafeInteger(revision) ||
+      (revision as number) < 0
+    )
+      throw new MetaValidationError("session forkOf is invalid");
+    result.forkOf = { sessionId, revision: revision as number };
+  }
+  const fingerprint = optionalFingerprint(meta.namedFingerprint);
+  if (fingerprint) result.namedFingerprint = fingerprint;
+  const structure = optionalFingerprint(meta.namedStructure);
+  if (structure) result.namedStructure = structure;
+  return result;
+}
+
+/** Validates a client patch from `unknown`; unknown keys are ignored. */
+export function parseMetaPatch(value: unknown): MetaPatch {
+  if (typeof value !== "object" || value === null || Array.isArray(value))
+    throw new MetaValidationError("meta patch must be an object");
+  const raw = value as Record<string, unknown>;
+  const patch: MetaPatch = {};
+  if (raw.name !== undefined) patch.name = normalizeSessionName(raw.name);
+  if (raw.nameSource !== undefined) {
+    if (raw.nameSource !== "auto" && raw.nameSource !== "user")
+      throw new MetaValidationError("nameSource is invalid");
+    patch.nameSource = raw.nameSource;
+  }
+  for (const key of ["namedFingerprint", "namedStructure"] as const) {
+    if (raw[key] === undefined) continue;
+    patch[key] = raw[key] === null ? null : requireFingerprint(raw[key]);
+  }
+  if (Object.keys(patch).length === 0)
+    throw new MetaValidationError("meta patch is empty");
+  return patch;
+}
+
+export function parseMetaExpect(value: unknown): MetaExpect | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "object" || Array.isArray(value))
+    throw new MetaValidationError("meta condition must be an object");
+  const raw = value as Record<string, unknown>;
+  const expect: MetaExpect = {};
+  if (raw.name !== undefined) expect.name = normalizeSessionName(raw.name);
+  if (raw.nameSource !== undefined) {
+    if (raw.nameSource !== "auto" && raw.nameSource !== "user")
+      throw new MetaValidationError("nameSource is invalid");
+    expect.nameSource = raw.nameSource;
+  }
+  return expect;
+}
+
+export function metaMatches(meta: SessionMeta, expect?: MetaExpect): boolean {
+  if (!expect) return true;
+  if (expect.name !== undefined && expect.name !== meta.name) return false;
+  if (expect.nameSource !== undefined && expect.nameSource !== meta.nameSource)
+    return false;
+  return true;
+}
+
+export function applyMetaPatch(
+  meta: SessionMeta,
+  patch: MetaPatch,
+  at: string,
+): SessionMeta {
+  const next: SessionMeta = {
+    ...meta,
+    updatedAt: at,
+    version: meta.version + 1,
+  };
+  if (patch.name !== undefined) next.name = patch.name;
+  if (patch.nameSource !== undefined) next.nameSource = patch.nameSource;
+  for (const key of ["namedFingerprint", "namedStructure"] as const) {
+    if (patch[key] === null) delete next[key];
+    else if (patch[key] !== undefined) next[key] = patch[key];
+  }
+  return next;
+}
+
+/** Splits a trailing ` N` (N ≥ 2) suffix: `x 3` → `{ base: "x", n: 3 }`. */
+export function splitNameNumber(name: string): { base: string; n: number } {
+  const match = name.match(/^(.*\S) (\d{1,4})$/);
+  if (!match) return { base: name, n: 1 };
+  const n = Number(match[2]);
+  return n >= 2 ? { base: match[1]!, n } : { base: name, n: 1 };
+}
+
+/**
+ * Default fork name: strip any trailing ` N` from the parent, then take the
+ * highest ` N` among sessions with that base, plus one (`x` → `x 2` → `x 3`;
+ * a fork of `x 2` is `x 3` too).
+ */
+export function forkName(parent: string, existing: readonly string[]): string {
+  const { base } = splitNameNumber(parent);
+  let highest = 1;
+  for (const name of existing) {
+    const split = splitNameNumber(name);
+    if (split.base === base) highest = Math.max(highest, split.n);
+  }
+  return withNumber(base, highest + 1);
+}
+
+/** Adds or bumps a ` N` suffix until the name is not in `taken`. */
+export function uniqueName(name: string, taken: readonly string[]): string {
+  const lower = new Set(taken.map((entry) => entry.toLowerCase()));
+  if (!lower.has(name.toLowerCase())) return name;
+  const { base, n } = splitNameNumber(name);
+  for (let next = Math.max(2, n + 1); next < 10_000; next += 1) {
+    const candidate = withNumber(base, next);
+    if (!lower.has(candidate.toLowerCase())) return candidate;
+  }
+  return name;
+}
+
+export function withNumber(base: string, n: number): string {
+  const suffix = ` ${n}`;
+  return `${base.slice(0, MAX_SESSION_NAME_LENGTH - suffix.length).trimEnd()}${suffix}`;
+}
+
+function timestamp(value: unknown, label: string): string {
+  if (
+    typeof value !== "string" ||
+    value.length === 0 ||
+    value.length > MAX_TIMESTAMP_LENGTH
+  )
+    throw new MetaValidationError(`session ${label} is invalid`);
+  return value;
+}
+
+function optionalFingerprint(value: unknown): string | undefined {
+  if (value === undefined || value === null) return undefined;
+  return requireFingerprint(value);
+}
+
+function requireFingerprint(value: unknown): string {
+  if (typeof value !== "string" || !FINGERPRINT_PATTERN.test(value))
+    throw new MetaValidationError("fingerprint is invalid");
+  return value;
+}