fix(cli): audio accepts several files, as its help says (#6535)

docs/packages/cli.mdx

@@ -701,6 +701,7 @@ Measure how sound moves in time, so a cut or an animation can land on it.
 
 ```bash
 npx hyperframes audio sfx/whoosh.mp3                  # one file, in file seconds
+npx hyperframes audio sfx/hit.wav sfx/whoosh.mp3      # several files, one report
 npx hyperframes audio sfx/hit.wav --place-at 4.2      # not in the film yet: where it lands if it starts at 4.2 s
 npx hyperframes audio --element '#riser'              # one clip of the film, in film seconds
 npx hyperframes audio --at 12                         # every sound playing at 12 s

packages/cli/src/cli.commands.test.ts

@@ -19,6 +19,7 @@ function commandLoaderBlock(): string {
 
 // Vite cannot resolve a template-string import, so each listed top-level command is named here.
 const LIST_COMMANDS: Record<string, () => Promise<{ default: unknown }>> = {
+  audio: () => import("./commands/audio.js"),
   catalog: () => import("./commands/catalog.js"),
   compare: () => import("./commands/compare.js"),
   figma: () => import("./commands/figma.js"),

packages/cli/src/utils/reject-extra-positionals.test.ts

@@ -0,0 +1,24 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { ArgsDef, CommandDef } from "citty";
+import audio from "../commands/audio.js";
+import { CliUsageError } from "./commandResult.js";
+import { resolveExtraPositionals } from "./reject-extra-positionals.js";
+
+afterEach(() => vi.restoreAllMocks());
+
+describe("resolveExtraPositionals", () => {
+  it("lets audio take several files, which its help promises and its analysis handles", () => {
+    const parsed = { _: ["a.wav", "b.wav"], files: "a.wav" };
+    expect(() =>
+      resolveExtraPositionals(audio as CommandDef<ArgsDef>, "audio", parsed),
+    ).not.toThrow();
+  });
+
+  it("still rejects an extra argument for a command that reads one", () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    const single = { args: { file: { type: "positional" } } } as CommandDef<ArgsDef>;
+    expect(() => resolveExtraPositionals(single, "single", { _: ["a", "b"], file: "a" })).toThrow(
+      CliUsageError,
+    );
+  });
+});

packages/cli/src/utils/reject-extra-positionals.ts

@@ -7,6 +7,7 @@ import { isTextFile } from "./textFile.js";
 
 // Leaf commands that read extra positionals from `args._` on purpose, by command path.
 export const ACCEPTS_EXTRA_POSITIONALS = new Set([
+  "audio",
   "compare",
   "figma asset",
   "skills update",