ossclip 0.1.34 → 0.1.36

package/src/program.ts

@@ -9,13 +9,14 @@ import {
   RESOLUTION_CHOICES,
   ResolutionChoiceSchema,
   SceneComponentIdSchema,
+  SfxLevelSchema,
 } from "@ossclip/core";
 import { STUDIO_ENTRY } from "@ossclip/renderer";
 import { loadEnvFiles } from "./env";
 import { ExportFormatSchema, runAnalyze } from "./analyze";
 import { expandHome } from "./paths";
 import { phaseBucketProps } from "./phase-timing";
-import { dictionaryFlag, jumpCutsFlag, produce, reviewFlag } from "./produce";
+import { dictionaryFlag, jumpCutsFlag, produce, reviewFlag, sfxFlag } from "./produce";
 import { accountsFlag, atFlag, deliveryFlag, platformsFlag, youtubePrivacyFlag } from "./publish";
 // The one interactive import that is STATIC rather than `await import()`: the
 // `resetInputSource()` run boundary in `buildProgram` has to run synchronously
@@ -343,6 +344,31 @@ export function buildProgram(): Command {
         "runs so the editor's Render replays the same window without an LLM call",
     )
     .option("--intent <text>", "what the video should be ('educational video about agents…')")
+    .option(
+      "--sfx",
+      // No commander default, the `--watermark` contract: untyped must stay
+      // UNDEFINED so the config's `sfx` key can supply it — a `false` default
+      // here would make every run's flag beat the config it was written for.
+      "place sound effects from the bundled pack (and any pack in ~/.ossclip/sfx) " +
+        "on the beats the producer planned. Requires --produce. Config key: \"sfx\"",
+    )
+    .option(
+      "--sfx-level <level>",
+      "how much sound design: subtle | normal (default) | meme (unlocks the " +
+        "meme-tagged sounds). Implies --sfx. Config key: \"sfxLevel\"",
+      (v: string) => {
+        // Parse, never coerce (CLAUDE.md): a typo'd `--sfx-level mem` must not
+        // silently fall back to `normal` — the level decides whether a vine
+        // boom can land in the video at all.
+        const parsed = SfxLevelSchema.safeParse(v.trim());
+        if (!parsed.success) {
+          throw new InvalidArgumentError(
+            `--sfx-level wants one of ${SfxLevelSchema.options.join(", ")}, got "${v}"`,
+          );
+        }
+        return parsed.data;
+      },
+    )
     .option(
       "--llm <provider>",
       // Must state `defaultProviderName`'s real order — the old text omitted
@@ -446,6 +472,21 @@ export function buildProgram(): Command {
         "(set it once with coverInVideo: true in ~/.ossclip/config.json)",
     )
     .option("--no-cover-in-video", "no cover overlay, even when the config turns it on")
+    // The watermark's tri-state carrying a VALUE: commander folds the pair
+    // onto one key (string when typed, false for --no-color-grade, undefined
+    // when neither — which is what lets overrides.json and then the config's
+    // `colorGrade` decide). The value is NOT parsed here, unlike --sfx-level:
+    // it may be a preset id OR a .cube filename, so an enum parse can't hold
+    // it — classification and validation live at the consumer
+    // (colorGradeFlagValue / resolveProductionColorGrade in produce.ts),
+    // where a typo warns and the run proceeds ungraded rather than dying.
+    .option(
+      "--color-grade <look>",
+      "color grade the footage: a preset (talking-head | teal-orange | filmic-fade | " +
+        "cwa | punchy | mono) or a .cube LUT filename from ~/.ossclip/luts " +
+        '(set it once with colorGrade: {"preset": "..."} in ~/.ossclip/config.json)',
+    )
+    .option("--no-color-grade", "no color grade, even when the config sets one")
     // Same tri-state shape as --watermark above (positive declared first so
     // commander's default stays undefined = "not typed"): the config's
     // `youtube` key supplies the default (resolveYoutube), and a typed
@@ -661,6 +702,12 @@ export function buildProgram(): Command {
           noiseDb: opts.noiseDb,
           produce: opts.produce,
           intent: opts.intent,
+          // `--sfx-level` implies `--sfx` (sfxFlag), resolved HERE so the
+          // implication is one pure function rather than a condition produce
+          // has to remember. Untyped stays undefined, which is what lets the
+          // config's `sfx` key decide (`resolveSfx` at the use site).
+          sfx: sfxFlag(opts.sfx, opts.sfxLevel),
+          sfxLevel: opts.sfxLevel,
           provider,
           llmModel: opts.llmModel,
           llmFastModel: opts.llmFastModel,
@@ -690,6 +737,12 @@ export function buildProgram(): Command {
           // The watermark's tri-state again, resolved by resolveCoverInVideo
           // at the use site against the config's `coverInVideo`.
           coverInVideo: opts.coverInVideo,
+          // string | false | undefined straight through: undefined = "not
+          // typed" lets overrides.json and then the config's `colorGrade`
+          // decide, and the value itself is classified and validated at the
+          // use site (resolveProductionColorGrade) — see the option's own
+          // comment for why no parse happens here.
+          colorGrade: opts.colorGrade,
           // The same tri-state contract as watermark, resolved by
           // resolveYoutube at the use site; --portrait rides along untyped =
           // undefined so the config's path can supply it.
@@ -761,7 +814,13 @@ export function buildProgram(): Command {
         // run does write. Reusing this path is what gives --review the edit
         // command's whole posture (resolveEditorPageDir's loud "run pnpm
         // build" degrade, startEditServer, openInBrowser) for free.
-        await offerEditor(result, { flag: openEditor, port: opts.editorPort });
+        await offerEditor(result, {
+          flag: openEditor,
+          port: opts.editorPort,
+          // Typed-only, like `edit`'s --port: commander's 5174 default is not
+          // a choice, so a busy port still attaches or bumps for it.
+          portPinned: command.getOptionValueSource("editorPort") === "cli",
+        });
         // Deliberately LAST — after the render summary and the editor offer —
         // so the one question ossclip ever asks is the last thing on screen.
         await maybeAskRating(telemetry);
@@ -956,7 +1015,7 @@ export function buildProgram(): Command {
     .argument("[workdir]", "a work directory containing render-props.json")
     .option("--port <n>", "port to listen on", (v) => Number.parseInt(v, 10), 5174)
     .option("--no-open", "do not open a browser")
-    .action(async (workdir: string | undefined, opts) => {
+    .action(async (workdir: string | undefined, opts, command: Command) => {
       const { startEditServer, resolveEditorPageDir } = await import("./edit");
       // An npm install ships the page prebuilt (editor-dist/); a clone builds
       // it once with `pnpm build`. A server that starts fine but 404s every
@@ -976,11 +1035,29 @@ export function buildProgram(): Command {
       const target =
         workdir === undefined ? undefined : await resolveWorkdirArgument(workdir, "edit");
 
-      const server = await startEditServer(target, { port: opts.port, pageDir });
-      console.log(`▸ editor at ${server.url}`);
+      // A busy port is not a crash. `openEditServer` owns the whole ladder —
+      // attach to our own editor already serving THIS project, prompt about
+      // one serving another, step around a stranger — and it needs to know
+      // whether the port was TYPED: someone who passes `--port` has a reason
+      // for that number (a bookmark, a tunnel), so their run refuses rather
+      // than silently landing somewhere else. `getOptionValueSource` is the
+      // same "did the user type it" test `--sort` uses.
+      const { openEditServer, liveEditPortDeps } = await import("./edit-port");
+      const opened = await openEditServer(
+        target ?? null,
+        { port: opts.port, pinned: command.getOptionValueSource("port") === "cli" },
+        liveEditPortDeps((port) => startEditServer(target, { port, pageDir })),
+      );
+      // The user picked "cancel" at the conflict prompt: nothing started,
+      // nothing to open, exit 0.
+      if (opened.kind === "cancelled") return;
+      const url = opened.kind === "attached" ? opened.url : opened.server.url;
+      // The attach path already printed "▸ already open at …" — saying
+      // "editor at" underneath it would read as a second server.
+      if (opened.kind === "started") console.log(`▸ editor at ${url}`);
       if (opts.open) {
         const { openInBrowser } = await import("./open");
-        openInBrowser(server.url);
+        openInBrowser(url);
       }
       // Fire-and-forget on purpose: the server keeps the process alive for
       // the request's lifetime, and awaiting here would put a metrics POST

package/src/replay-argv.ts

@@ -20,6 +20,9 @@
 // Type-only, so no runtime edge back into produce.ts (which imports this
 // module): the tri-state's vocabulary belongs to its resolver.
 import type { JumpCutsMode } from "./produce";
+// Type-only for the same reason: the level's own zod enum lives in core's
+// producer half, and this module must stay a pure argv builder.
+import type { SfxLevel } from "@ossclip/core";
 
 let stashed: string[] | null = null;
 
@@ -71,6 +74,10 @@ export function recordedProduceArgs(pins: {
   audience?: string;
   /** The RESOLVED thumbnail brief — pinned only when non-empty. */
   thumbnailBrief?: string;
+  /** The RESOLVED `--sfx` switch (flag or config), pinned only when ON. */
+  sfx?: boolean;
+  /** The RESOLVED `--sfx-level`, pinned alongside an ON `sfx`. */
+  sfxLevel?: SfxLevel;
 }): string[] {
   // --review and --no-render are stripped at record (cut-review step 1):
   // command.json exists for exactly one consumer — the editor's Render
@@ -201,5 +208,28 @@ export function recordedProduceArgs(pins: {
   ) {
     args.push("--thumbnail-brief", pins.thumbnailBrief);
   }
+  // The sound-effect pins, the watermark's config-dependent-default rationale
+  // on a pair of flags: `sfx`/`sfxLevel` are both config keys, so an unpinned
+  // record replays a different amount of sound design — or none — the moment
+  // that config is edited or the replay runs on another machine. It matters
+  // more here than for the watermark: an editor render carries the REVIEWED
+  // plan forward from production.json instead of re-placing (produce's
+  // `priorSfxPlan`), so `--sfx` is what decides whether the sound design the
+  // user just dragged into place is in the video at all.
+  //
+  // ON ONLY, and that is the jump-cuts "auto" case rather than the watermark's
+  // both-directions rule: there is no `--no-sfx` spelling to pin an off-run
+  // with (program.ts declares `--sfx` alone, so the config key can still
+  // supply the default). An off-record replayed under a later config-on
+  // therefore GAINS sound effects — the accepted cost of a flag with one
+  // spelling, and the day `--no-sfx` exists this pin becomes unconditional
+  // like the watermark's. `--sfx-level` implies `--sfx`, so a typed level in
+  // the argv already settles the switch and the includes-guard leaves it be.
+  if (pins.sfx === true) {
+    if (!args.includes("--sfx") && !args.includes("--sfx-level")) args.push("--sfx");
+    if (pins.sfxLevel !== undefined && !args.includes("--sfx-level")) {
+      args.push("--sfx-level", pins.sfxLevel);
+    }
+  }
   return args;
 }