@hraness/dawg 0.6.1 → 0.7.0

package/src/media/cli.ts

@@ -16,6 +16,7 @@
  */
 import { systemRunner, type CommandRunner } from "../auth/runner.ts";
 import { doctor, formatDoctor } from "./backend.ts";
+import { analysisCacheStatus, analysisDoctorLine } from "../audio/analysis.ts";
 import { trackSlug } from "./paths.ts";
 import { MediaAbortError } from "./process.ts";
 import { findMediaTool } from "./registry.ts";
@@ -26,7 +27,7 @@ export type Output = { write(text: string): unknown };
 
 export const MEDIA_HELP = `dawg media — local media tools (see DAWG.md "Media tools")
 
-  dawg media doctor                      backend + binaries + install commands
+  dawg media doctor                      backend + binaries + install commands + analysis cache
   dawg media download <url> [--name n]   YouTube audio → tracks/<slug>/downloads/<n>.wav
   dawg media stems <file>                six stems → <file>.stems/
   dawg media analyze <file>              tempo, key, beat grid, peaks → <file>.analysis.json
@@ -68,6 +69,15 @@ export function parseMediaArgv(argv: readonly string[]): {
   json: boolean;
   help: boolean;
 } {
+  // `dawg media --help` (or `-h`): a leading help flag is not a verb.
+  if (argv[0] === "--help" || argv[0] === "-h")
+    return {
+      verb: undefined,
+      args: {},
+      track: "main",
+      json: false,
+      help: true,
+    };
   const [verb, ...rest] = argv;
   const args: Record<string, unknown> = {};
   const positional: string[] = [];
@@ -139,8 +149,15 @@ export async function runMediaCommand(
       ...host,
       ...(options.signal ? { signal: options.signal } : {}),
     });
-    if (parsed.json) stdout.write(`${JSON.stringify(report, null, 2)}\n`);
-    else stdout.write(`${formatDoctor(report).join("\n")}\n`);
+    const analysis = await analysisCacheStatus(cwd);
+    if (parsed.json)
+      stdout.write(
+        `${JSON.stringify({ ...report, analysisCache: analysis }, null, 2)}\n`,
+      );
+    else
+      stdout.write(
+        `${[...formatDoctor(report), await analysisDoctorLine(cwd)].join("\n")}\n`,
+      );
     return 0;
   }
   const spec = VERBS[parsed.verb];

package/src/media/import.ts

@@ -38,6 +38,8 @@ export type ImportSampleArgs = Readonly<{
   end?: number;
   /** Root note name or MIDI number the sample is pitched at (default C4). */
   root?: string | number;
+  /** 1 folds to mono (0.7 audio clips); absent keeps today's stereo. */
+  channels?: 1 | 2;
 }>;
 
 export async function importSample(
@@ -68,7 +70,7 @@ export async function importSample(
       "-ar",
       String(SAMPLE_LIMITS.sampleRate),
       "-ac",
-      "2",
+      String(args.channels ?? 2),
       "-c:a",
       "pcm_s16le",
       temp,

package/src/project/check.ts

@@ -13,7 +13,9 @@ import {
   modalPairWarnings,
 } from "../../core/resonators.ts";
 import { plainSineWarnings } from "../audio/instrument-check.ts";
+import { clipPinDiagnostics } from "./clip-pins.ts";
 import { isProject } from "./init.ts";
+import { parseSimpleArgv } from "../argv.ts";
 import { typecheckProject } from "./typecheck.ts";
 
 export type CheckDeps = Readonly<{
@@ -41,12 +43,18 @@ export async function checkProject(
     (deps.typecheck ?? typecheckProject)(project),
     (deps.evaluate ?? evaluateProject)(project),
   ]);
+  // 0.7: a clip or take whose file no longer matches its pinned sha256
+  // fails like a type error.
+  const pins = evaluated.ok
+    ? await clipPinDiagnostics(project, evaluated.score)
+    : [];
   const diagnostics = [
     ...types.diagnostics,
     ...(evaluated.ok ? [] : evaluated.diagnostics),
+    ...pins,
   ];
   return Object.freeze({
-    ok: types.ok && evaluated.ok,
+    ok: types.ok && evaluated.ok && pins.length === 0,
     diagnostics: Object.freeze(diagnostics),
     typesMs: types.ms,
     evalMs: evaluated.ms,
@@ -64,6 +72,9 @@ export async function checkProject(
   });
 }
 
+export const CHECK_USAGE =
+  "usage: dawg check · typecheck and evaluate the project in this directory; exit 1 on problems";
+
 export async function runCheckCommand(
   argv: readonly string[],
   cwd: string,
@@ -71,6 +82,15 @@ export async function runCheckCommand(
   stderr: { write(text: string): unknown },
   deps: CheckDeps = {},
 ): Promise<number> {
+  const parsed = parseSimpleArgv(argv.slice(1), 0);
+  if (parsed.kind === "help") {
+    stdout.write(`${CHECK_USAGE}\n`);
+    return 0;
+  }
+  if (parsed.kind === "error") {
+    stderr.write(`${parsed.problem} · ${CHECK_USAGE}\n`);
+    return 2;
+  }
   const project = cwd;
   if (!(await isProject(project))) {
     stderr.write(
@@ -92,6 +112,5 @@ export async function runCheckCommand(
   }
   const count = report.diagnostics.length;
   stderr.write(`${count} problem${count === 1 ? "" : "s"}\n`);
-  void argv;
   return 1;
 }

package/src/project/clip-pins.ts

@@ -0,0 +1,72 @@
+/**
+ * `dawg check` re-hashes every audio clip and take (0.7) and reports a file
+ * that is missing or no longer matches its pinned sha256, pointing at the
+ * track file the way a type error does.
+ */
+
+import { createHash } from "node:crypto";
+import { readFile, stat } from "node:fs/promises";
+import { relative, resolve } from "node:path";
+import type { Diagnostic } from "../../core/sdk/eval.ts";
+import type { TrackScore } from "../../core/score.ts";
+import { trackDirectories } from "../../core/sdk/print.ts";
+
+const MAX_CLIP_FILE_BYTES = 50 * 1024 * 1024;
+
+export async function clipPinDiagnostics(
+  project: string,
+  score: TrackScore,
+): Promise<Diagnostic[]> {
+  const out: Diagnostic[] = [];
+  const hashes = new Map<string, string | undefined>();
+  const hashOf = async (src: string): Promise<string | undefined> => {
+    if (hashes.has(src)) return hashes.get(src);
+    let hash: string | undefined;
+    const path = resolve(project, src);
+    if (!relative(project, path).startsWith("..")) {
+      try {
+        const info = await stat(path);
+        if (info.isFile() && info.size <= MAX_CLIP_FILE_BYTES)
+          hash = createHash("sha256")
+            .update(await readFile(path))
+            .digest("hex");
+      } catch {
+        hash = undefined;
+      }
+    }
+    hashes.set(src, hash);
+    return hash;
+  };
+  const dirs = trackDirectories(score);
+  for (const track of score.tracks) {
+    const file = `tracks/${dirs.get(track.id) ?? track.id}/track.ts`;
+    const items: [string, string, string][] = [
+      ...(track.takes ?? []).map(
+        (t) => [`take ${t.name}`, t.src, t.sha256] as [string, string, string],
+      ),
+      ...(track.clips ?? []).map(
+        (c) => [`clip ${c.id}`, c.src, c.sha256] as [string, string, string],
+      ),
+    ];
+    const usedTakes = new Set((track.clips ?? []).map((c) => c.take));
+    for (const [label, src, pinned] of items) {
+      const actual = await hashOf(src);
+      if (actual === pinned) continue;
+      // An unused take that is gone is only advice (sources.md 6).
+      if (
+        actual === undefined &&
+        label.startsWith("take ") &&
+        !usedTakes.has(label.slice(5))
+      )
+        continue;
+      out.push({
+        file,
+        message:
+          actual === undefined
+            ? `${label}: ${src} is missing (re-import it or remove the clip)`
+            : `${label}: ${src} does not match its sha256 pin (${pinned.slice(0, 8)} pinned, ${actual.slice(0, 8)} on disk); delete the sha256 line to re-pin`,
+      });
+    }
+  }
+  return out;
+}

package/src/project/init.ts

@@ -15,9 +15,11 @@
  */
 
 import { createHash } from "node:crypto";
-import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { mkdir, readFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { parseSimpleArgv } from "../argv.ts";
+import { durableWrite } from "../fs/durable.ts";
 
 export const PROJECT_FILE = "dawg.json";
 export const PROJECT_FORMAT = "dawg.project/v1";
@@ -78,6 +80,7 @@ export default song({
   meter: [4, 4],
   bars: 4,
   tracks: [],
+  calibration: 1,
 });
 `;
 
@@ -210,6 +213,9 @@ export async function initProject(
   return Object.freeze({ wrote: Object.freeze(wrote), sdkVersion });
 }
 
+export const INIT_USAGE =
+  "usage: dawg init [dir] · writes song.ts, dawg.json, tsconfig.json and .dawg/sdk (existing files are kept)";
+
 /** `dawg init [dir]`: creates the project and prints what it wrote. */
 export async function runInitCommand(
   argv: readonly string[],
@@ -217,8 +223,17 @@ export async function runInitCommand(
   stdout: { write(text: string): unknown },
   stderr: { write(text: string): unknown },
 ): Promise<number> {
-  const target =
-    argv[1] && !argv[1].startsWith("--") ? resolve(cwd, argv[1]) : cwd;
+  const parsed = parseSimpleArgv(argv.slice(1), 1);
+  if (parsed.kind === "help") {
+    stdout.write(`${INIT_USAGE}\n`);
+    return 0;
+  }
+  if (parsed.kind === "error") {
+    stderr.write(`${parsed.problem} · ${INIT_USAGE}\n`);
+    return 2;
+  }
+  const dir = parsed.positionals[0];
+  const target = dir ? resolve(cwd, dir) : cwd;
   try {
     const result = await initProject(target);
     if (result.wrote.length === 0)
@@ -241,13 +256,13 @@ async function readOptional(path: string): Promise<string | undefined> {
   }
 }
 
-/** Temp file + rename so a reader never sees a partial file. */
+/**
+ * Temp file + fsync + rename + directory fsync, so a reader never sees a
+ * partial file and a crash never loses a write `.dawg/sync.json` vouches for.
+ */
 export async function writeAtomic(
   path: string,
   contents: string,
 ): Promise<void> {
-  await mkdir(dirname(path), { recursive: true });
-  const temporary = `${path}.${process.pid}.tmp`;
-  await writeFile(temporary, contents, "utf8");
-  await rename(temporary, path);
+  await durableWrite(path, contents);
 }