@hraness/dawg 0.2.0 → 0.4.0

package/src/project/sync.ts

@@ -0,0 +1,432 @@
+/**
+ * Two-way sync between the project files and the session score.
+ *
+ * files → score: a change to `song.ts` or `tracks/<slug>/track.ts` (fs.watch
+ * plus a slow poll, debounced 150 ms) evaluates the project, adopts the
+ * session's note ids, diffs against the current score and commits one
+ * `files.apply` revision through the session port. A failed evaluation is
+ * reported as a card and leaves the score alone.
+ *
+ * score → files: a new score revision reprints the project and writes only
+ * the files whose bytes differ. Files whose last evaluation already equals
+ * the score are never rewritten, so an author's own formatting survives.
+ *
+ * Echo suppression: `.dawg/sync.json` records the hash of every file dawg
+ * wrote; a watcher event whose file still hashes the same is ignored, in
+ * this window and every other one.
+ */
+
+import { createHash } from "node:crypto";
+import { watch, type FSWatcher } from "node:fs";
+import { readdir, readFile, rm, stat } from "node:fs/promises";
+import { join } from "node:path";
+import {
+  adoptNoteIds,
+  applyScoreOperations,
+  diffScores,
+} from "../../core/diff.ts";
+import { encodeLoop } from "../../core/loop.ts";
+import type { ScoreOperation, TrackScore } from "../../core/score.ts";
+import {
+  evaluateProject,
+  formatDiagnostic,
+  type Diagnostic,
+  type EvalResult,
+} from "../../core/sdk/eval.ts";
+import { printProject } from "../../core/sdk/print.ts";
+import { writeAtomic } from "./init.ts";
+import { typecheckProject, type TypecheckResult } from "./typecheck.ts";
+
+export const SYNC_DEBOUNCE_MS = 150;
+export const SYNC_POLL_MS = 1_500;
+const SYNC_STATE_FILE = ".dawg/sync.json";
+const MAX_TRACKED_FILES = 512;
+
+/** Header indicator state: `types ✓` or `types ✗ N`. */
+export type TypesState = Readonly<{ ok: boolean; errors: number }>;
+
+/** Result of reconciling an evaluated score with the session score. */
+export type FilesApplyPlan = Readonly<{
+  /** The session score after the file change, with session note ids kept. */
+  next: TrackScore;
+  operations: readonly ScoreOperation[];
+}>;
+
+/**
+ * Pure core of files → score: adopts `current`'s note ids into `evaluated`
+ * and returns the operations (and resulting score) that bring `current` to
+ * it. Empty `operations` means the files already match the score.
+ */
+export function applyFiles(
+  current: TrackScore,
+  evaluated: TrackScore,
+): FilesApplyPlan {
+  const target = adoptNoteIds(current, evaluated);
+  const operations = diffScores(current, target);
+  const next =
+    operations.length === 0
+      ? current
+      : applyScoreOperations(current, operations);
+  return Object.freeze({ next, operations });
+}
+
+/** What the sync needs from its window. */
+export type SyncHost = Readonly<{
+  project: string;
+  /** Current session score. */
+  current(): TrackScore;
+  /**
+   * Commits the plan as one `files.apply` revision. Resolves with the
+   * score the session now holds (it may be ahead after a rebase).
+   */
+  commit(plan: FilesApplyPlan, summary: string): Promise<TrackScore>;
+  card(
+    text: string,
+    tone: "info" | "success" | "warning" | "error",
+    hint?: string,
+  ): void;
+  types(state: TypesState): void;
+}>;
+
+export type SyncOptions = Readonly<{
+  evaluate?: (project: string) => Promise<EvalResult>;
+  typecheck?: (project: string) => Promise<TypecheckResult>;
+  debounceMs?: number;
+  pollMs?: number;
+  /** Disable fs.watch and polling (tests drive `checkFiles` directly). */
+  watch?: boolean;
+}>;
+
+export type ProjectSync = Readonly<{
+  /** Call when the session score changed (local edit or another window). */
+  scoreChanged(score: TrackScore): void;
+  /**
+   * Evaluate the files now (debounce skipped); resolves when applied with a
+   * one-line outcome (`applied from files · 1 note`, `files rejected · …`,
+   * `files match the score`), the last one when nothing changed since.
+   */
+  checkFiles(): Promise<string>;
+  /** Reprint now (debounce skipped); resolves when written. */
+  flushScore(): Promise<void>;
+  stop(): Promise<void>;
+}>;
+
+type SyncState = { files: Record<string, string> };
+
+export function startProjectSync(
+  host: SyncHost,
+  options: SyncOptions = {},
+): ProjectSync {
+  const evaluate =
+    options.evaluate ?? ((project: string) => evaluateProject(project));
+  const typecheck =
+    options.typecheck ?? ((project: string) => typecheckProject(project));
+  const debounceMs = options.debounceMs ?? SYNC_DEBOUNCE_MS;
+  const project = host.project;
+  const statePath = join(project, SYNC_STATE_FILE);
+  /** Hashes of the project files as of the last successful evaluation. */
+  let seen = new Map<string, string>();
+  /** Outcome of the last evaluation, returned when the files did not change. */
+  let lastOutcome = "files match the score";
+  /** Encoded score the files were last known to equal. */
+  let filesEqual = "";
+  let lastRejection = "";
+  let stopped = false;
+  let queue: Promise<void> = Promise.resolve();
+  let fileTimer: ReturnType<typeof setTimeout> | undefined;
+  let scoreTimer: ReturnType<typeof setTimeout> | undefined;
+  let pendingScore: TrackScore | undefined;
+  let watchers: FSWatcher[] = [];
+  let poll: ReturnType<typeof setInterval> | undefined;
+
+  const enqueue = <T>(task: () => Promise<T>): Promise<T> => {
+    const run = queue.then(task, task);
+    queue = run.then(
+      () => undefined,
+      () => undefined,
+    );
+    return run;
+  };
+
+  const readState = async (): Promise<SyncState> => {
+    try {
+      const value: unknown = JSON.parse(await readFile(statePath, "utf8"));
+      if (typeof value !== "object" || value === null) return { files: {} };
+      const files = (value as Record<string, unknown>).files;
+      if (typeof files !== "object" || files === null) return { files: {} };
+      const out: Record<string, string> = {};
+      for (const [path, hash] of Object.entries(
+        files as Record<string, unknown>,
+      ))
+        if (
+          typeof hash === "string" &&
+          /^[0-9a-f]{64}$/.test(hash) &&
+          path.length < 512
+        )
+          out[path] = hash;
+      return { files: out };
+    } catch {
+      return { files: {} };
+    }
+  };
+  const writeState = (state: SyncState) =>
+    writeAtomic(statePath, `${JSON.stringify(state, null, 2)}\n`);
+
+  /**
+   * Evaluates the files. In `files-win` mode (edits) the result is committed;
+   * in `score-wins` mode (startup with unchanged files) a difference reprints
+   * the files from the score instead.
+   */
+  const checkFilesNow = async (
+    mode: "files-win" | "score-wins" = "files-win",
+  ): Promise<string> => {
+    if (stopped) return lastOutcome;
+    const current = await hashProject(project);
+    if (mode === "files-win" && sameHashes(current, seen)) return lastOutcome;
+    const result = await evaluate(project);
+    if (!result.ok) {
+      const text = result.diagnostics.map(formatDiagnostic).join("; ");
+      if (text !== lastRejection) {
+        lastRejection = text;
+        host.card(
+          `files rejected · ${firstLine(text)}`,
+          "error",
+          "fix the file to apply",
+        );
+      }
+      void runTypecheck();
+      return (lastOutcome = `files rejected · ${text}`);
+    }
+    lastRejection = "";
+    seen = current;
+    const plan = applyFiles(host.current(), result.score);
+    if (plan.operations.length === 0) {
+      filesEqual = encodeLoop(host.current());
+      void runTypecheck();
+      return (lastOutcome = "files match the score");
+    }
+    if (mode === "score-wins") {
+      pendingScore = host.current();
+      await flushScoreNow();
+      void runTypecheck();
+      return (lastOutcome = "files reprinted from the score");
+    }
+    const summary = summarize(plan.operations);
+    try {
+      const committed = await host.commit(plan, summary);
+      filesEqual = encodeLoop(committed);
+      host.card(`applied from files · ${summary}`, "success");
+      lastOutcome = `applied from files · ${summary}`;
+    } catch (error) {
+      host.card(
+        `files not applied · ${firstLine(error instanceof Error ? error.message : String(error))}`,
+        "warning",
+      );
+      lastOutcome = `files not applied · ${error instanceof Error ? error.message : String(error)}`;
+    }
+    void runTypecheck();
+    return lastOutcome;
+  };
+
+  const flushScoreNow = async (): Promise<void> => {
+    if (stopped || !pendingScore) return;
+    const score = pendingScore;
+    pendingScore = undefined;
+    const encoded = encodeLoop(score);
+    if (encoded === filesEqual) return;
+    const printed = printProject(score);
+    const state = await readState();
+    const files = { ...state.files };
+    const expected = new Set(printed.files.map((file) => file.path));
+    const hashes = new Map<string, string>();
+    for (const file of printed.files) {
+      const hash = sha256(file.text);
+      hashes.set(file.path, hash);
+      const existing = await readOptional(join(project, file.path));
+      if (existing === file.text) continue;
+      await writeAtomic(join(project, file.path), file.text);
+      files[file.path] = hash;
+    }
+    // Track files we printed earlier for tracks that no longer exist.
+    for (const [path, hash] of Object.entries(state.files)) {
+      if (expected.has(path) || !path.startsWith("tracks/")) continue;
+      const existing = await readOptional(join(project, path));
+      if (existing !== undefined && sha256(existing) === hash)
+        await rm(join(project, path), { force: true });
+      delete files[path];
+    }
+    await writeState({ files });
+    seen = await hashProject(project);
+    filesEqual = encoded;
+  };
+
+  let typecheckRunning = false;
+  let typecheckAgain = false;
+  const runTypecheck = async (): Promise<void> => {
+    if (stopped) return;
+    if (typecheckRunning) {
+      typecheckAgain = true;
+      return;
+    }
+    typecheckRunning = true;
+    try {
+      const result = await typecheck(project);
+      host.types({ ok: result.ok, errors: result.diagnostics.length });
+    } catch {
+      host.types({ ok: false, errors: 1 });
+    } finally {
+      typecheckRunning = false;
+      if (typecheckAgain) {
+        typecheckAgain = false;
+        void runTypecheck();
+      }
+    }
+  };
+
+  const scheduleFiles = () => {
+    if (stopped) return;
+    if (fileTimer) clearTimeout(fileTimer);
+    fileTimer = setTimeout(() => {
+      fileTimer = undefined;
+      void enqueue(() => checkFilesNow("files-win"));
+    }, debounceMs);
+  };
+
+  if (options.watch !== false) {
+    const onEvent = (_event: string, filename: string | Buffer | null) => {
+      const name = filename === null ? "" : String(filename);
+      if (name && !isProjectSource(name)) return;
+      scheduleFiles();
+    };
+    try {
+      watchers.push(watch(project, { persistent: false }, onEvent));
+      watchers.push(
+        watch(
+          join(project, "tracks"),
+          { persistent: false, recursive: true },
+          onEvent,
+        ),
+      );
+    } catch {
+      watchers.forEach((watcher) => watcher.close());
+      watchers = [];
+    }
+    poll = setInterval(
+      () => void enqueue(() => checkFilesNow("files-win")),
+      options.pollMs ?? SYNC_POLL_MS,
+    );
+    poll.unref?.();
+  }
+  // Startup: files edited since dawg last wrote them (or never recorded)
+  // win; otherwise the session score wins and reprints what files lack.
+  void enqueue(async () => {
+    const state = await readState();
+    const current = await hashProject(project);
+    const edited =
+      current.size === 0 ||
+      [...current].some(([path, hash]) => state.files[path] !== hash);
+    await checkFilesNow(edited ? "files-win" : "score-wins");
+  });
+
+  return Object.freeze({
+    scoreChanged(score: TrackScore) {
+      if (stopped) return;
+      pendingScore = score;
+      if (scoreTimer) clearTimeout(scoreTimer);
+      scoreTimer = setTimeout(() => {
+        scoreTimer = undefined;
+        void enqueue(flushScoreNow);
+      }, debounceMs);
+    },
+    checkFiles: () => enqueue(() => checkFilesNow("files-win")),
+    flushScore: () => enqueue(flushScoreNow),
+    async stop() {
+      stopped = true;
+      if (fileTimer) clearTimeout(fileTimer);
+      if (scoreTimer) clearTimeout(scoreTimer);
+      if (poll) clearInterval(poll);
+      watchers.forEach((watcher) => watcher.close());
+      watchers = [];
+      await queue.catch(() => undefined);
+    },
+  });
+}
+
+/** Project-relative source paths: `song.ts` and each track file under `tracks/`. */
+export async function projectSourceFiles(project: string): Promise<string[]> {
+  const files = ["song.ts"];
+  let dirs: string[] = [];
+  try {
+    dirs = (await readdir(join(project, "tracks"), { withFileTypes: true }))
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name)
+      .sort();
+  } catch {
+    dirs = [];
+  }
+  for (const dir of dirs.slice(0, MAX_TRACKED_FILES)) {
+    const path = `tracks/${dir}/track.ts`;
+    try {
+      if ((await stat(join(project, path))).isFile()) files.push(path);
+    } catch {
+      // A directory without a track file (samples only) is not a source.
+    }
+  }
+  return files;
+}
+
+function isProjectSource(name: string): boolean {
+  return (
+    name === "song.ts" || /(^|\/)track\.ts$/.test(name) || !name.includes(".")
+  );
+}
+
+async function hashProject(project: string): Promise<Map<string, string>> {
+  const out = new Map<string, string>();
+  for (const path of await projectSourceFiles(project)) {
+    const text = await readOptional(join(project, path));
+    if (text !== undefined) out.set(path, sha256(text));
+  }
+  return out;
+}
+
+function sameHashes(a: Map<string, string>, b: Map<string, string>): boolean {
+  if (a.size !== b.size) return false;
+  for (const [path, hash] of a) if (b.get(path) !== hash) return false;
+  return true;
+}
+
+function sha256(text: string): string {
+  return createHash("sha256").update(text).digest("hex");
+}
+
+async function readOptional(path: string): Promise<string | undefined> {
+  try {
+    return await readFile(path, "utf8");
+  } catch {
+    return undefined;
+  }
+}
+
+function firstLine(text: string): string {
+  const line = text.split("\n")[0] ?? "";
+  return line.length > 120 ? `${line.slice(0, 119)}…` : line;
+}
+
+/** `2 notes, 1 track` style summary of a plan for the activity card. */
+export function summarize(operations: readonly ScoreOperation[]): string {
+  const counts = new Map<string, number>();
+  for (const op of operations) {
+    const key = op.type.endsWith("Note")
+      ? "note"
+      : op.type.endsWith("Track")
+        ? "track"
+        : "setting";
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+  }
+  return [...counts.entries()]
+    .map(([key, count]) => `${count} ${key}${count === 1 ? "" : "s"}`)
+    .join(", ");
+}
+
+export type { Diagnostic };

package/src/project/typecheck.ts

@@ -0,0 +1,149 @@
+/**
+ * Typechecks a project with the TypeScript compiler dawg depends on.
+ *
+ * TypeScript 7 is a native binary with no JavaScript watch API, so each check
+ * is one `tsc --noEmit --incremental` run whose build info lives in
+ * `.dawg/tsbuild/`; a warm check on a small project takes tens of
+ * milliseconds. Diagnostics come back as `file:line:col message`.
+ */
+
+import { realpathSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { Diagnostic } from "../../core/sdk/eval.ts";
+import type { CommandRunner } from "../auth/runner.ts";
+import { systemRunner } from "../auth/runner.ts";
+
+export const TYPECHECK_TIMEOUT_MS = 60_000;
+const MAX_DIAGNOSTICS = 200;
+
+export type TypecheckResult = Readonly<{
+  ok: boolean;
+  diagnostics: readonly Diagnostic[];
+  ms: number;
+}>;
+
+export type TypecheckOptions = Readonly<{
+  runner?: CommandRunner;
+  /** Path of the `tsc` executable; resolved from the dependency by default. */
+  tsc?: string;
+}>;
+
+/** Native `tsc` from `@typescript/typescript-<platform>-<arch>`, else `tsc` on PATH. */
+export function resolveTsc(
+  runner: CommandRunner = systemRunner,
+): string | undefined {
+  const name = `@typescript/typescript-${process.platform}-${process.arch}/package.json`;
+  try {
+    const url = import.meta.resolve(name);
+    return join(dirname(fileURLToPath(url)), "lib", "tsc");
+  } catch {
+    return runner.which("tsc");
+  }
+}
+
+/** Runs `tsc` on `<project>/tsconfig.json` and parses its diagnostics. */
+export async function typecheckProject(
+  project: string,
+  options: TypecheckOptions = {},
+): Promise<TypecheckResult> {
+  const started = performance.now();
+  const runner = options.runner ?? systemRunner;
+  const tsc = options.tsc ?? resolveTsc(runner);
+  if (!tsc)
+    return {
+      ok: false,
+      diagnostics: [{ message: "typescript is not installed (no tsc found)" }],
+      ms: elapsed(started),
+    };
+  const stateDir = join(project, ".dawg", "tsbuild");
+  await mkdir(stateDir, { recursive: true });
+  const result = await runner.run(
+    tsc,
+    [
+      "--noEmit",
+      "--pretty",
+      "false",
+      "--incremental",
+      "--tsBuildInfoFile",
+      join(stateDir, "project.tsbuildinfo"),
+      "-p",
+      join(project, "tsconfig.json"),
+    ],
+    {
+      timeoutMs: TYPECHECK_TIMEOUT_MS,
+      maxOutputBytes: 1024 * 1024,
+      env: { NO_COLOR: "1" },
+    },
+  );
+  if (result.killed)
+    return {
+      ok: false,
+      diagnostics: [{ message: "typecheck timed out" }],
+      ms: elapsed(started),
+    };
+  const diagnostics = parseTscOutput(
+    `${result.stdout}\n${result.stderr}`,
+    project,
+  );
+  if (result.code !== 0 && diagnostics.length === 0)
+    diagnostics.push({
+      message: `tsc exited with code ${result.code}${
+        result.stderr.trim() ? `: ${result.stderr.trim().split("\n")[0]}` : ""
+      }`,
+    });
+  return {
+    ok: result.code === 0 && diagnostics.length === 0,
+    diagnostics,
+    ms: elapsed(started),
+  };
+}
+
+/**
+ * Parses `file(line,col): error TSnnnn: message` lines. tsc prints paths
+ * relative to its working directory; they come back project-relative.
+ */
+export function parseTscOutput(
+  output: string,
+  project: string,
+  cwd: string = process.cwd(),
+): Diagnostic[] {
+  const out: Diagnostic[] = [];
+  const roots = [project];
+  try {
+    roots.push(realpathSync(project));
+  } catch {
+    // An unreadable project keeps the literal path.
+  }
+  const relativize = (file: string): string => {
+    const absolute = isAbsolute(file) ? file : resolve(cwd, file);
+    for (const root of roots) {
+      const rel = relative(root, absolute);
+      if (rel && !rel.startsWith("..") && !isAbsolute(rel)) return rel;
+    }
+    return file;
+  };
+  for (const raw of output.split("\n")) {
+    const line = raw.trimEnd();
+    const match = line.match(/^(.*?)\((\d+),(\d+)\): error (TS\d+): (.*)$/);
+    if (match) {
+      const file = relativize(match[1]!);
+      out.push({
+        file,
+        line: Number(match[2]),
+        col: Number(match[3]),
+        message: `${match[5]} (${match[4]})`,
+      });
+    } else {
+      const bare = line.match(/^error (TS\d+): (.*)$/);
+      if (bare) out.push({ message: `${bare[2]} (${bare[1]})` });
+    }
+    if (out.length >= MAX_DIAGNOSTICS) break;
+  }
+  return out;
+}
+
+function elapsed(started: number): number {
+  return Math.round(performance.now() - started);
+}

package/src/render.ts

@@ -1,5 +1,6 @@
 /**
- * `dawg render <out.wav>`: renders a session (or a `track.loop/v1` file) to
+ * `dawg render <out.wav>`: renders a session, the project files (`song.ts`,
+ * in a project with no `--session`), or a `track.loop/v1` file to
  * a stereo 16-bit PCM WAV through the same deterministic renderer playback
  * uses, so two renders of one score are byte-identical. It reads the session
  * record from disk and never starts dawgd or plays audio.
@@ -10,6 +11,16 @@ import { resolve } from "node:path";
 import { scoreFromJSON, type TrackScore } from "../core/score.ts";
 import { decodeLoop } from "../core/loop.ts";
 import { renderScoreWav } from "./audio/wav.ts";
+import { SampleLibrary, hasSamplerTracks } from "./audio/samples.ts";
+import {
+  PackStore,
+  creditsLine,
+  packCredits,
+  withWavComment,
+  writeCredits,
+} from "./audio/packs.ts";
+import { evaluateProject, formatDiagnostic } from "../core/sdk/eval.ts";
+import { isProject } from "./project/init.ts";
 import { resolveSessionArg } from "./session/attach.ts";
 import {
   loadSession,
@@ -31,6 +42,10 @@ export async function runRenderCommand(
   stderr: Output,
 ): Promise<number> {
   const rest = argv.slice(1);
+  if (rest.includes("--help") || rest.includes("-h")) {
+    stdout.write(`${RENDER_USAGE}\n`);
+    return 0;
+  }
   const options = new Map<string, string>();
   const positional: string[] = [];
   for (let index = 0; index < rest.length; index += 1) {
@@ -38,13 +53,13 @@ export async function runRenderCommand(
     if (arg === "--session" || arg === "--import") {
       const value = rest[index + 1];
       if (value === undefined || value.startsWith("--")) {
-        stderr.write(`${arg} needs a value\n${RENDER_USAGE}\n`);
+        stderr.write(`${arg} needs a value · ${RENDER_USAGE}\n`);
         return 2;
       }
       options.set(arg, value);
       index += 1;
     } else if (arg.startsWith("--")) {
-      stderr.write(`unknown option ${arg}\n${RENDER_USAGE}\n`);
+      stderr.write(`unknown option · ${arg} · ${RENDER_USAGE}\n`);
       return 2;
     } else positional.push(arg);
   }
@@ -62,13 +77,33 @@ export async function runRenderCommand(
     );
     return 1;
   }
-  const wav = renderScoreWav(score);
+  let samples;
+  if (hasSamplerTracks(score)) {
+    samples = await new SampleLibrary({ projectRoot: workspace }).load(score);
+    for (const problem of samples.problems)
+      stderr.write(`sample ${problem.level} · ${problem.message}\n`);
+  }
+  let wav = renderScoreWav(score, { samples });
+  // Pack sounds: name the packs (and CC-BY attributions) in the WAV's INFO
+  // comment and on stdout; CREDITS.md in a project keeps the attributions.
+  const refs = score.tracks.flatMap((track) =>
+    Object.values(track.sampler?.voices ?? {}),
+  );
+  let credits: string | undefined;
+  if (refs.some((ref) => ref.src.startsWith("pack:"))) {
+    const list = packCredits(refs, await new PackStore().list());
+    credits = creditsLine(list);
+    if (credits) wav = withWavComment(wav, `samples: ${credits}`);
+    if (await isProject(workspace).catch(() => false))
+      await writeCredits(workspace, list).catch(() => undefined);
+  }
   const path = resolve(workspace, target);
   const temporary = `${path}.${process.pid}.tmp`;
   await writeFile(temporary, wav);
   await rename(temporary, path);
   const sha = createHash("sha256").update(wav).digest("hex");
   stdout.write(`rendered · ${target} · ${wav.byteLength} bytes · ${sha}\n`);
+  if (credits) stdout.write(`credits · ${credits}\n`);
   return 0;
 }
 
@@ -84,16 +119,24 @@ async function loadScore(
     return decodeLoop(contents.toString("utf8"));
   }
   const query = options.get("--session");
+  if (query === undefined && (await isProject(workspace))) {
+    const evaluated = await evaluateProject(workspace);
+    if (!evaluated.ok)
+      throw new Error(
+        `${evaluated.diagnostics.map(formatDiagnostic).join("; ").slice(0, 400)} · fix song.ts and retry (dawg check)`,
+      );
+    return evaluated.score;
+  }
   const sessionId =
     query === undefined
       ? await readCurrentSessionId(workspace)
       : await resolveSessionArg(workspace, query);
   if (sessionId === undefined)
-    throw new Error("no session here; run `dawg` first or pass --import");
+    throw new Error("no session here · run dawg first or pass --import");
   const record = await loadSession<unknown>(
     sessionPaths(workspace, sessionId),
   ).catch(() => {
-    throw new Error(`no session named "${query ?? sessionId}"`);
+    throw new Error(`no session named "${query ?? sessionId}" · dawg sessions`);
   });
   return scoreFromJSON(record.composition);
 }