Skip to content

Write HTML. Render video. Built for agents.

44.1 KB
Raw Blame
#!/usr/bin/env node

import { spawnSync } from "node:child_process";
import { existsSync, statSync, writeFileSync, renameSync, rmSync, realpathSync } from "node:fs";
import { resolve, join, extname, basename, relative, isAbsolute, sep } from "node:path";
import { parseArgs } from "node:util";
import {
  AGENT_SOURCES,
  appendRecord,
  latestRecordFor,
  recordInPlace,
  findByPrompt,
  findByEntity,
  nextId,
  typeDirPath,
  withMediaLock,
  withReservedFile,
  withReservedFileSync,
} from "./lib/manifest.mjs";
import { regenerateIndex } from "./lib/index-gen.mjs";
import { cacheGet, cacheGetByEntity, importFromCache, cachePut } from "./lib/cache.mjs";
import {
  runCapability,
  listTypes,
  providerMatches,
  providerNamesFor,
  providerTierFor,
} from "./lib/registry.mjs";
import { freezeUrl, freezeLocalFile, isDirectMediaUrl } from "./lib/freeze.mjs";
import { findExistingAsset } from "./lib/adopt.mjs";
import { probe as probeMedia } from "./lib/probe.mjs";
import { track } from "./lib/telemetry.mjs";
import { recordMiss } from "./lib/misses.mjs";
import { buildStats } from "./lib/stats.mjs";
import { typesMatch } from "./lib/match.mjs";
import { listCandidates, formatCandidates, CANDIDATE_CAP } from "./lib/candidates.mjs";
import { findGlobalBySha } from "./lib/cache.mjs";
import { heygenAuthMethod } from "../audio/scripts/lib/heygen.mjs";
import { buildCube, paramsFromIntent } from "./lib/cube-build.mjs";
import { validateCubeFile } from "./lib/cube-validate.mjs";
import { analyzeMediaGrade, formatMeasuredNote } from "./lib/grade-analyzer.mjs";
import { FfBinarySettingError, ffmpegBinary, ffprobeBinary } from "./lib/ff-binaries.mjs";
import {
  freezeLibraryLut,
  isLibraryLutOfflineMiss,
  matchColorLook,
} from "./lib/lut-preset-provider.mjs";
import {
  HEYGEN_AUTH_COMMAND,
  HEYGEN_INSTALL_COMMAND,
  HEYGEN_MIN_VERSION,
  HEYGEN_UPDATE_COMMAND,
  consumeHeygenRemediation,
  heygenMiss,
  firstSemver,
  flushHeygenFailureTracking,
  versionLessThan,
} from "./lib/heygen-cli.mjs";
import { BundledSfxAssetsError, inspectBundledSfxAssets } from "./lib/bundled-sfx-provider.mjs";
import { OPENVERSE_SFX_PROVIDER } from "./lib/sfx-provider.mjs";
import { writeSfxCredit } from "./lib/openverse.mjs";
import {
  fetchMediaVectors,
  mediaVectorRows,
  rankMediaRowsWithVectors,
} from "./lib/local-media-search.mjs";

const INGEST_TYPES = listTypes();
const DEFAULT_EXT = {
  bgm: ".wav",
  sfx: ".mp3",
  voice: ".wav",
  image: ".jpg",
  icon: ".svg",
  logo: ".svg",
  brand: ".png",
  video: ".mp4",
  grade: ".cube",
  lut: ".cube",
};

// resolve shells `fetch`/`freezeUrl` and modern ESM; 18 is the floor where those
// exist without flags. Named so the --doctor node check verifies something real
// (O2). Declared before the top-level `--doctor` branch that calls runDoctor().
const MIN_NODE_VERSION = "18.0.0";

const { values: args } = parseArgs({
  options: {
    type: { type: "string", short: "t" },
    intent: { type: "string", short: "i" },
    entity: { type: "string", short: "e" },
    project: { type: "string", short: "p", default: "." },
    adopt: { type: "boolean", default: false },
    candidates: { type: "boolean", default: false },
    doctor: { type: "boolean", default: false },
    stats: { type: "boolean", default: false },
    days: { type: "string" },
    "dry-run": { type: "boolean", default: false },
    reuse: { type: "string" },
    from: { type: "string" },
    source: { type: "string" },
    params: { type: "string" },
    for: { type: "string" },
    analyze: { type: "boolean", default: false },
    "local-only": { type: "boolean", default: false },
    provider: { type: "string" },
    "avatar-id": { type: "string" },
    "voice-id": { type: "string" },
    json: { type: "boolean", default: false },
    help: { type: "boolean", short: "h", default: false },
  },
  strict: true,
});

if (args.help) {
  console.log(`media-use resolve — turn a media need into a frozen local file

Usage:
  node resolve.mjs --type <type> --intent "<description>" [--project <dir>]

Types: ${listTypes().join(", ")}

Options:
  --type, -t      Media type (required)
  --intent, -i    What you need (required)
  --entity, -e    Entity name for cache matching (optional)
  --project, -p   Project directory (default: .)
  --adopt         Adopt all existing assets/ files into the manifest
  --candidates    List reusable assets (project + global cache) for --type; no
                  download, no mutation. Read them and decide reuse yourself.
  --doctor        Check local CLI dependencies; no manifest changes.
  --stats         Print local usage stats from .media and ~/.media; no mutation.
  --days <N>      Limit --stats to records/misses from the last N days when
                  timestamps are available.
  --reuse <sha>   Import a specific global-cache asset (by content sha/prefix,
                  from --candidates) into this project
  --from <file>   Freeze a local file or direct public URL (ingest)
  --source <how>  With --from: how the file was made (${AGENT_SOURCES.join(" | ")}).
                  A file already inside the project is then recorded where it is
  --params <json> Build an explicit parametric LUT (lut/grade only)
  --for <media>   Analyze a local image/video and add measured grade adjust
                  suggestions (grade only)
  --analyze       Return --for grade evidence without recording a candidate
  --local-only    Offline: skip every network provider
  --provider      Force one generator (e.g. codex, mflux, kokoro, heygen)
  --avatar-id     Override the default avatar for heygen.video generation
  --voice-id      Override the default voice for voice/heygen.video generation
  --json          Output JSON instead of one-line result
  --help, -h      Show this help`);
  process.exit(0);
}

const projectDir = resolve(args.project);
const type = args.type;
const intent = args.intent;
const entity = args.entity || null;

if (args.adopt) {
  const { adoptExistingAssets } = await import("./lib/adopt.mjs");
  let adopted;
  try {
    adopted = adoptExistingAssets(projectDir);
  } catch (err) {
    exitError(err.message);
  }
  if (args.json) {
    console.log(JSON.stringify({ ok: true, adopted: adopted.length, assets: adopted }));
  } else if (adopted.length === 0) {
    console.log("no new assets to adopt (assets/ empty or already registered)");
  } else {
    console.log(`adopted ${adopted.length} asset${adopted.length === 1 ? "" : "s"} from assets/`);
    for (const r of adopted) console.log(`  ${r.id} → ${r.path} (${r.type})`);
  }
  process.exit(0);
}

// Candidates: side-effect-free listing of reusable assets (project + global
// cache) for --type. No download, no provider, no mutation. The agent reads
// these and decides semantic fit itself.
if (args.candidates || args["dry-run"]) {
  await showCandidates();
  process.exit(0);
}

if (args.doctor) {
  const doctor = runDoctor();
  const failed = doctor.checks.filter((check) => !check.ok);
  // Non-PII: instrument the exact question the feature exists to answer — how
  // often is --doctor run and which check fails most. Awaited so a short-lived
  // run flushes before exit.
  await track("media_use_doctor_run", {
    ok: doctor.ok,
    checks_failed: failed.length,
    failed: failed.map((check) => check.name),
  });
  if (args.json) {
    console.log(JSON.stringify({ ok: doctor.ok, checks: doctor.checks }));
  } else {
    printDoctor(doctor.checks);
  }
  process.exit(doctor.ok ? 0 : 1);
}

if (args.stats) {
  const report = buildStats({
    projectDir,
    days: args.days ? Number(args.days) : undefined,
  });
  if (args.json) {
    console.log(JSON.stringify(report));
  } else {
    printStats(report);
  }
  process.exit(0);
}

// Reuse a global-cache asset selected by content sha or prefix.
if (args.reuse !== undefined) {
  await reuseGlobal(args.reuse);
  process.exit(0);
}

if (args.source && !args.from) {
  console.error("error: --source goes with --from <file>");
  process.exit(2);
}

// Ingest: freeze a user-supplied local file or direct public URL (no search).
if (args.from) {
  await ingest(args.from);
  process.exit(0);
}

if (args.analyze) {
  if (type !== "grade" || !args.for) {
    console.error("error: --analyze requires --type grade and --for <media>");
    process.exit(2);
  }
  const mediaPath = resolve(args.for);
  if (!existsSync(mediaPath)) {
    console.error(`error: --for file not found: ${mediaPath}`);
    process.exit(2);
  }
  let analysis;
  try {
    analysis = analyzeMediaGrade(mediaPath, {
      ffmpegPath: ffmpegBinary(),
      ffprobePath: ffprobeBinary(),
    });
  } catch (err) {
    exitError(err.message);
  }
  if (args.json) {
    console.log(JSON.stringify({ ok: true, type: "grade-analysis", ...analysis }));
  } else {
    console.log(formatMeasuredNote(mediaPath, analysis.measured));
    console.log(`suggested adjust: ${JSON.stringify(analysis.adjust)}`);
  }
  process.exit(0);
}

// Resolve named recipe bundles without a provider.
if (type === "recipe") {
  const { useRecipe } = await import("./lib/recipe-store.mjs");
  const name = (entity || intent || "").trim();
  if (!name) exitError("--type recipe needs --entity <name> (or --intent <name>)", 2);
  try {
    const used = useRecipe({ projectDir, name });
    if (args.json) {
      console.log(JSON.stringify({ ok: true, ...used }));
    } else {
      console.log(
        `resolved recipe ${used.recipe.name} (v${used.recipe.version}, ${used.recipe.workflow})`,
      );
      console.log(`  frame spec → ${used.frameSpecPath} (copied over)`);
      console.log(`  storyboard skeleton → ${used.skeletonPath}`);
      if (used.briefSkeletonPath) console.log(`  brief skeleton → ${used.briefSkeletonPath}`);
    }
    process.exit(0);
  } catch (err) {
    exitError(err.message, 1);
  }
}

if (args.params !== undefined) {
  if (type !== "lut" && type !== "grade") {
    exitError(
      type
        ? `--params only supports --type lut or grade (got ${type})`
        : "--params requires --type lut or grade",
      2,
    );
  }
  try {
    await runParams();
    process.exit(0);
  } catch (err) {
    exitError(err.message, 1);
  }
}

if (!args.type || !args.intent || !args.intent.trim()) {
  console.error("error: --type and a non-empty --intent are required");
  process.exit(2);
}

if (!listTypes().includes(args.type)) {
  console.error(`error: unknown media type: ${args.type} (known: ${listTypes().join(", ")})`);
  process.exit(2);
}

// Forced-provider validation: reject an unknown/unavailable provider name up
// front so a typo reads as a typo, not a catalog miss (`no provider could
// resolve`). Match rule mirrors runProviders (full name or dotted prefix).
if (args.provider && !providerMatches(args.type, args.provider)) {
  console.error(
    `error: unknown provider "${args.provider}" for type ${args.type} (available: ${providerNamesFor(args.type).join(", ")})`,
  );
  process.exit(2);
}

function recordAvailable(projectDir, record) {
  if (!record) return false;
  if (record.path) return existsSync(join(projectDir, record.path));
  return record.type === "grade" && record.grading;
}

// Sparse `{ authMethod }` for a heygen-family provider name (e.g. "heygen.tts"),
// else `{}` — keeps auth_method telemetry absent for every non-heygen resolve
// instead of implying an auth method that doesn't apply.
function heygenAuthMethodFor(provider) {
  if (!provider || !provider.startsWith("heygen.")) return {};
  const authMethod = heygenAuthMethod();
  return authMethod ? { authMethod } : {};
}

function localizeImportedRecord(record, localPath) {
  if (record?.type === "grade" && record.grading?.lut) {
    record.grading = {
      ...record.grading,
      lut: { ...record.grading.lut, src: localPath },
    };
  }
  return record;
}

async function run() {
  // A forced provider bypasses reuse and pins the provider cascade.
  const forced = !!args.provider;

  // 1. project manifest — exact-prompt match
  const projectHit = forced ? null : findByPrompt(projectDir, intent, type);
  if (recordAvailable(projectDir, projectHit)) {
    return result(projectHit, "cached");
  }

  // 1b. entity match in project. icon and image are interchangeable for
  // entity hits — both live in images/, and figma-imported brand marks are
  // always recorded as type image while agents ask for logos as type icon.
  if (!forced && entity) {
    const entityHit = findByEntity(projectDir, entity);
    if (entityHit && typesMatch(entityHit.type, type) && recordAvailable(projectDir, entityHit)) {
      return result(entityHit, "cached");
    }
  }

  // 1c. scan existing assets/ directory for unregistered matches
  const existingAsset =
    forced || type === "grade" || type === "lut"
      ? null
      : findExistingAsset(projectDir, intent, type);
  if (existingAsset) {
    const recorded = latestRecordFor(projectDir, existingAsset.relativePath);
    if (recorded) return result(recorded, "cached");
    const id = nextId(projectDir, type);
    const record = {
      id,
      type: existingAsset.type,
      path: existingAsset.relativePath,
      source: "existing",
      description: existingAsset.name.replace(/[-_]/g, " "),
      provenance: { provider: "local", adopted: true, prompt: intent },
    };
    appendRecord(projectDir, record);
    regenerateIndex(projectDir);
    return result(record, "existing");
  }

  // 2. global cache — exact-prompt or entity match
  const cacheHit = forced ? null : cacheGet(intent, type);
  if (cacheHit) {
    const ext = extname(cacheHit.cached_path);
    const imported = withReservedFileSync(projectDir, type, ext, ({ id, localPath }) =>
      localizeImportedRecord(importFromCache(cacheHit, projectDir, id, localPath), localPath),
    );
    if (imported) {
      appendRecord(projectDir, imported);
      regenerateIndex(projectDir);
      return result(imported, "reused");
    }
  }

  if (!forced && entity) {
    const entityCacheHit = cacheGetByEntity(entity);
    if (entityCacheHit && typesMatch(entityCacheHit.type, type)) {
      const ext = extname(entityCacheHit.cached_path);
      const imported = withReservedFileSync(projectDir, type, ext, ({ id, localPath }) =>
        localizeImportedRecord(
          importFromCache(entityCacheHit, projectDir, id, localPath),
          localPath,
        ),
      );
      if (imported) {
        appendRecord(projectDir, imported);
        regenerateIndex(projectDir);
        return result(imported, "reused");
      }
    }
  }

  // --local-only skips every remote provider.
  const localOnly = args["local-only"];
  const ctx = {
    entity,
    projectDir,
    localOnly,
    provider: args.provider,
    avatarId: args["avatar-id"],
    voiceId: args["voice-id"],
  };

  // Suggest candidates before a new fetch.
  try {
    const { similar } = listCandidates({ projectDir, type, intent, cap: CANDIDATE_CAP });
    if (similar > 0) {
      console.error(
        `media-use: ${similar} similar cached asset${similar === 1 ? "" : "s"} already ${similar === 1 ? "exists" : "exist"} — run \`resolve --candidates --type ${type} --intent "${intent}"\` to review and reuse instead of fetching.`,
      );
    }
  } catch {
    // hint is best-effort; never block a resolve
  }

  if (type === "grade" || type === "lut") {
    return resolveColor(type, intent, { projectDir });
  }

  // SFX search is Openverse, the bundled library, then the local media index.
  let searchResult = null;
  let providerFailure = null;
  let localIndexFailure = null;
  try {
    searchResult = await runCapability(type, "search", intent, ctx);
    if (!searchResult && type === "sfx" && !args.provider && !localOnly) {
      const registry =
        process.env.HYPERFRAMES_REGISTRY ||
        "https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry";
      try {
        await fetchMediaVectors(registry);
        const ranked = await rankMediaRowsWithVectors(
          intent,
          mediaVectorRows().filter((row) => row.kind === "sfx"),
        );
        const row = ranked.rows[0];
        const candidates = row
          ? [resolve(row.file), join(import.meta.dirname, "..", "..", "..", row.file)]
          : [];
        const localPath = candidates.find((candidate) => existsSync(candidate));
        if (row && localPath) {
          searchResult = {
            localPath,
            ext: extname(localPath),
            source: "local-index",
            metadata: {
              description: row.description,
              duration: row.duration ?? null,
              provider: "catalog.local",
              provenance: { library_key: row.id, tier: ranked.tier },
            },
          };
        }
      } catch (error) {
        localIndexFailure = error;
      }
    }
  } catch (error) {
    providerFailure = error;
    // search failed, try generate
  }

  if (localIndexFailure) {
    throw new Error(`local SFX index unavailable: ${localIndexFailure.message}`, {
      cause: localIndexFailure,
    });
  }

  // 4. generate fallback — same ordered cascade for the generate capability
  if (!searchResult) {
    try {
      searchResult = await runCapability(type, "generate", intent, ctx);
    } catch (error) {
      providerFailure ??= error;
      // generate failed too
    }
  }

  // Flush provider failure telemetry before the process can exit.
  await flushHeygenFailureTracking();

  if (!searchResult) {
    await track("media_use_resolve_miss", {
      type,
      local_only: !!localOnly,
      provider_override: !!args.provider,
    });
    recordMiss({
      type,
      intent,
      provider_override: !!args.provider,
      local_only: !!args["local-only"],
    });
    // brand stays local: no frame.md/design.md -> upsell the HyperFrames design
    // flow rather than reporting a generic miss (B5).
    const ownFailure =
      providerFailure instanceof BundledSfxAssetsError ||
      providerFailure instanceof FfBinarySettingError;
    const heygen = consumeHeygenRemediation();
    const miss = heygen && !ownFailure ? heygenMiss(type, heygen) : null;
    const typed = providerFailure instanceof BundledSfxAssetsError ? providerFailure : miss;
    const msg = ownFailure
      ? providerFailure.message
      : miss
        ? miss.error
        : type === "brand"
          ? "no brand spec found — add a frame.md or design.md (colors/font/logo) to this project. Run the HyperFrames design flow to create one; brand tokens are read locally for deterministic rendering."
          : args.provider
            ? `provider "${args.provider}" could not resolve ${type}: "${intent}"${localOnly ? " (--local-only skips network providers; drop it or the --provider override)" : ""}`
            : `no provider could resolve ${type}: "${intent}"`;
    if (args.json) {
      console.log(
        JSON.stringify({
          ok: false,
          ...(typed ? { code: typed.code, fix: typed.fix } : {}),
          error: msg,
        }),
      );
    } else {
      console.error(`error: ${msg}`);
    }
    process.exit(1);
  }

  // 5. freeze and register atomically.
  const ext = searchResult.ext || extFromUrl(searchResult.url || "") || defaultExt(type);
  const { id, localPath, fullPath } = await withReservedFile(
    projectDir,
    type,
    ext,
    async (reservation) => {
      if (searchResult.localPath) {
        freezeLocalFile(searchResult.localPath, reservation.fullPath);
      } else if (searchResult.url) {
        await freezeUrl(searchResult.url, reservation.fullPath);
      } else {
        throw new Error("provider returned no url or localPath");
      }
      return reservation;
    },
  );

  const record = {
    id,
    type,
    path: localPath,
    source: searchResult.source || "search",
    description: searchResult.metadata?.description || intent,
    ...(searchResult.metadata?.duration != null && {
      duration: Math.round(searchResult.metadata.duration * 10) / 10,
    }),
    ...(searchResult.metadata?.width != null && { width: searchResult.metadata.width }),
    ...(searchResult.metadata?.height != null && { height: searchResult.metadata.height }),
    ...(searchResult.metadata?.transparent != null && {
      transparent: searchResult.metadata.transparent,
    }),
    ...(entity && { entity }),
    provenance: {
      provider: searchResult.metadata?.provider || "unknown",
      prompt: intent,
      // Keep auth method sparse for non-HeyGen providers.
      ...heygenAuthMethodFor(searchResult.metadata?.provider),
      ...searchResult.metadata?.provenance,
    },
  };

  appendRecord(projectDir, record);
  regenerateIndex(projectDir);
  // Promote fetched assets into the global cache for reuse.
  try {
    cachePut(fullPath, record);
  } catch {
    // promotion is best-effort; a resolve still succeeds locally
  }
  return result(record, searchResult.source || "search");
}

function mergeSmartAdjust(block) {
  if (!args.for) return block;
  const mediaPath = resolve(args.for);
  // Clear upfront error beats an ffmpeg "No such file" stack on a typo'd path.
  if (!existsSync(mediaPath)) throw new Error(`--for file not found: ${mediaPath}`);
  const analysis = analyzeMediaGrade(mediaPath, {
    ffmpegPath: ffmpegBinary(),
    ffprobePath: ffprobeBinary(),
  });
  console.error(formatMeasuredNote(mediaPath, analysis.measured));
  return {
    ...block,
    adjust: {
      ...(block.adjust || {}),
      ...analysis.adjust,
    },
  };
}

function freezeGeneratedLut(
  params,
  {
    projectDir,
    type,
    description = "parametric color grade",
    validationErrorPrefix = "generated LUT failed validation",
  },
) {
  return withReservedFileSync(projectDir, type, ".cube", ({ id, localPath, fullPath }) => {
    const tmpPath = `${fullPath}.tmp`;
    try {
      // Write + validate at .tmp, then atomic rename, so a crash between write and
      // validate can't leave an invalid .cube at the final path.
      writeFileSync(tmpPath, buildCube(params));
      const check = validateCubeFile(tmpPath);
      if (!check.ok) throw new Error(check.error);
      renameSync(tmpPath, fullPath);
    } catch (err) {
      rmSync(tmpPath, { force: true });
      throw new Error(`${validationErrorPrefix}: ${err.message}`);
    }
    return {
      id,
      localPath,
      fullPath,
      lut: { src: localPath, intensity: 1 },
      source: "generated",
      description,
      metadata: {
        provider: "cube_lut.builder",
        provenance: { params },
      },
    };
  });
}

function exitError(message, status = 1) {
  if (args.json) {
    console.log(JSON.stringify({ ok: false, error: message }));
  } else {
    console.error(`error: ${message}`);
  }
  process.exit(status);
}

function parseExplicitParams() {
  try {
    return JSON.parse(args.params);
  } catch (err) {
    throw new Error(`invalid --params JSON: ${err.message}`);
  }
}

async function runParams() {
  if (type === "lut" && args.for) {
    throw new Error("--for is only supported with --type grade");
  }
  const params = parseExplicitParams();
  const description =
    typeof intent === "string" && intent.trim()
      ? intent.trim()
      : `custom parametric ${type === "lut" ? "lut" : "grade"}`;
  const frozen = freezeGeneratedLut(params, {
    projectDir,
    type,
    description,
    validationErrorPrefix: "--params produced an invalid LUT",
  });
  const record = {
    id: frozen.id,
    type,
    path: frozen.localPath,
    source: frozen.source,
    description: frozen.description,
    ...(type === "grade" && { grading: mergeSmartAdjust({ intensity: 1, lut: frozen.lut }) }),
    provenance: {
      provider: frozen.metadata.provider,
      ...frozen.metadata.provenance,
    },
  };
  return finalizeColorRecord(record, frozen.source, frozen.fullPath);
}

async function finalizeColorRecord(record, source, fullPath = null) {
  appendRecord(projectDir, record);
  regenerateIndex(projectDir);
  if (fullPath) {
    try {
      cachePut(fullPath, record);
    } catch {
      // promotion is best-effort
    }
  }
  return result(record, source);
}

async function colorMiss(type, intent) {
  await track("media_use_resolve_miss", {
    type,
    local_only: !!args["local-only"],
    provider_override: !!args.provider,
  });
  recordMiss({
    type,
    intent,
    provider_override: !!args.provider,
    local_only: !!args["local-only"],
  });
  const msg = `no local color grade could resolve ${type}: "${intent}"`;
  if (args.json) {
    console.log(JSON.stringify({ ok: false, error: msg }));
  } else {
    console.error(`error: ${msg}`);
  }
  process.exit(1);
}

async function resolveGrade(intent, { projectDir }) {
  const match = matchColorLook(intent);
  if (match?.kind === "preset") {
    const id = nextId(projectDir, "grade");
    const grading = mergeSmartAdjust({ preset: match.preset, intensity: 1 });
    const record = {
      id,
      type: "grade",
      source: "preset",
      description: intent,
      grading,
      provenance: {
        provider: "color_grade.local",
        prompt: intent,
        preset: match.preset,
      },
    };
    return finalizeColorRecord(record, "preset");
  }

  if (match?.kind === "library") {
    let frozen;
    try {
      frozen = await freezeLibraryLut(match, {
        projectDir,
        type: "grade",
        localOnly: args["local-only"],
      });
    } catch (err) {
      if (isLibraryLutOfflineMiss(err)) return colorMiss("grade", intent);
      throw err;
    }
    const grading = mergeSmartAdjust({ intensity: 1, lut: frozen.lut });
    const record = {
      id: frozen.id,
      type: "grade",
      path: frozen.localPath,
      source: frozen.source,
      description: frozen.description,
      grading,
      provenance: {
        provider: frozen.metadata.provider,
        prompt: intent,
        ...frozen.metadata.provenance,
      },
    };
    return finalizeColorRecord(record, frozen.source, frozen.fullPath);
  }

  const params = paramsFromIntent(intent);
  if (!params) {
    // No creative look matched. With --for, the measured adjust block is a
    // valid grade on its own (footage auto-correction); only a true miss
    // (no look AND no analysis) aborts.
    if (args.for) {
      const grading = mergeSmartAdjust({ intensity: 1 });
      const record = {
        id: nextId(projectDir, "grade"),
        type: "grade",
        source: "measured",
        description: intent,
        grading,
        provenance: { provider: "color_grade.local", prompt: intent, measured: true },
      };
      return finalizeColorRecord(record, "measured");
    }
    return colorMiss("grade", intent);
  }
  const frozen = freezeGeneratedLut(params, { projectDir, type: "grade" });
  const grading = mergeSmartAdjust({ intensity: 1, lut: frozen.lut });
  const record = {
    id: frozen.id,
    type: "grade",
    path: frozen.localPath,
    source: frozen.source,
    description: intent,
    grading,
    provenance: {
      provider: frozen.metadata.provider,
      prompt: intent,
      ...frozen.metadata.provenance,
    },
  };
  return finalizeColorRecord(record, frozen.source, frozen.fullPath);
}

async function resolveLut(intent, { projectDir }) {
  if (args.for) {
    throw new Error("--for is only supported with --type grade");
  }
  const match = matchColorLook(intent);
  if (match?.kind === "library") {
    let frozen;
    try {
      frozen = await freezeLibraryLut(match, {
        projectDir,
        type: "lut",
        localOnly: args["local-only"],
      });
    } catch (err) {
      if (isLibraryLutOfflineMiss(err)) return colorMiss("lut", intent);
      throw err;
    }
    const record = {
      id: frozen.id,
      type: "lut",
      path: frozen.localPath,
      source: frozen.source,
      description: frozen.description,
      provenance: {
        provider: frozen.metadata.provider,
        prompt: intent,
        ...frozen.metadata.provenance,
      },
    };
    return finalizeColorRecord(record, frozen.source, frozen.fullPath);
  }

  const params = paramsFromIntent(intent);
  if (!params) return colorMiss("lut", intent);
  const frozen = freezeGeneratedLut(params, { projectDir, type: "lut" });
  const record = {
    id: frozen.id,
    type: "lut",
    path: frozen.localPath,
    source: frozen.source,
    description: intent,
    provenance: {
      provider: frozen.metadata.provider,
      prompt: intent,
      ...frozen.metadata.provenance,
    },
  };
  return finalizeColorRecord(record, frozen.source, frozen.fullPath);
}

async function resolveColor(type, intent, options) {
  if (type === "grade") return resolveGrade(intent, options);
  return resolveLut(intent, options);
}

async function ingest(src) {
  if (!type || !INGEST_TYPES.includes(type)) {
    console.error(`error: --from requires --type (one of: ${INGEST_TYPES.join(", ")})`);
    process.exit(2);
  }
  const isUrl = /^https?:\/\//i.test(src);
  if (isUrl && !isDirectMediaUrl(src)) {
    console.error(
      `error: --from takes a direct public media URL or a local file; "${src}" is not a direct media link (no platform pages / yt-dlp)`,
    );
    process.exit(2);
  }
  if (!isUrl && !existsSync(resolve(src))) {
    console.error(`error: file not found: ${src}`);
    process.exit(2);
  }
  // Refuse 0-byte input: an empty asset would register clean but fail at render
  // (freezeUrl already rejects empty responses; this covers local files).
  if (!isUrl && statSync(resolve(src)).size === 0) {
    console.error(`error: refusing to ingest a 0-byte file: ${src}`);
    process.exit(2);
  }
  if (args.source && !AGENT_SOURCES.includes(args.source)) {
    console.error(`error: --source takes one of: ${AGENT_SOURCES.join(", ")}`);
    process.exit(2);
  }
  if (args.source && (type === "lut" || type === "grade")) {
    console.error("error: --source records media files; a LUT or grade is ingested without it");
    process.exit(2);
  }
  const real = (path) => (existsSync(path) ? realpathSync(path) : path);
  const inProject = args.source && !isUrl ? relative(real(projectDir), real(resolve(src))) : null;
  if (
    inProject &&
    inProject !== ".." &&
    !inProject.startsWith(`..${sep}`) &&
    !isAbsolute(inProject)
  ) {
    return recordProjectFile(inProject.split(sep).join("/"));
  }
  const ext = extname(isUrl ? new URL(src).pathname : src) || defaultExt(type);
  const { id, localPath, fullPath } = await withReservedFile(
    projectDir,
    type,
    ext,
    async (reservation) => {
      if (isUrl) await freezeUrl(src, reservation.fullPath);
      else freezeLocalFile(resolve(src), reservation.fullPath);
      return reservation;
    },
  );
  if (type === "lut" || type === "grade") {
    try {
      const check = validateCubeFile(fullPath);
      if (!check.ok) throw new Error(check.error);
    } catch (err) {
      rmSync(fullPath, { force: true });
      exitError(`ingested LUT is invalid: ${err.message}`, 1);
    }
  }
  const record = {
    id,
    type,
    path: localPath,
    source: args.source || "ingested",
    description: basename(src.split("?")[0]),
    provenance: { provider: "local", from: src },
  };
  appendRecord(projectDir, record);
  regenerateIndex(projectDir);
  try {
    cachePut(fullPath, record); // surface ingested assets globally too (B3)
  } catch {
    // best-effort
  }
  await result(record, "ingested");
}

async function recordProjectFile(path) {
  let duration;
  try {
    duration = probeMedia(join(projectDir, path)).duration;
  } catch (err) {
    exitError(err.message);
  }
  const record = recordInPlace(projectDir, {
    type,
    path,
    source: args.source,
    description: intent,
    duration,
    provenance: {
      provider: args.provider || "local",
      from: path,
      ...(intent && { prompt: intent }),
    },
  });
  regenerateIndex(projectDir);
  // "recorded", not the record's source, so usage counts keep meaning fetches.
  await result(record, "recorded");
}

async function showCandidates() {
  const projectDir = resolve(args.project);
  const type = args.type;
  if (!type || !listTypes().includes(type)) {
    console.error(`error: --candidates requires --type (one of: ${listTypes().join(", ")})`);
    process.exit(2);
  }
  const intent = args.intent || "";
  const { candidates, truncated, total, similar } = listCandidates({
    projectDir,
    type,
    intent,
    cap: CANDIDATE_CAP,
  });
  await track("media_use_candidates", {
    type,
    project_n: total.project,
    global_n: total.global,
    local_only: !!args["local-only"],
  });
  if (args.json) {
    console.log(JSON.stringify({ ok: true, candidates, truncated, total, similar }));
  } else {
    console.log(formatCandidates(candidates, { truncated, total }));
  }
}

// Best-effort latest stable CLI tag from the CDN (the install script's source of
// truth). null on any failure (offline, no curl) — treated as "unknown", never fatal.
function latestHeygenStable() {
  const probe = runCommand("curl", [
    "-fsSL",
    "--max-time",
    "4",
    "https://static.heygen.ai/cli/stable",
  ]);
  return probe.status === 0 ? firstSemver(commandText(probe)) : null;
}

function heygenAuthCheck() {
  // heygen auth status emits JSON by default; parse that output directly.
  const authProbe = runCommand("heygen", ["auth", "status"]);
  // spawnSync sets .error/.signal on a timeout or spawn failure (status then
  // null). A stalled auth endpoint (transient network/DNS) must not be reported
  // as an authoritative "not authenticated" with a re-login fix.
  const timedOut = authProbe.error?.code === "ETIMEDOUT" || authProbe.signal != null;
  const email = authProbe.status === 0 ? emailFromAuthStatus(commandText(authProbe)) : null;
  return {
    name: "heygen authenticated",
    ok: !!email,
    detail: email
      ? `heygen authenticated as ${email}`
      : timedOut
        ? "heygen auth status timed out — possible network issue, not proof of sign-out"
        : "heygen not authenticated",
    fix: email ? "" : timedOut ? "check network, then re-run --doctor" : HEYGEN_AUTH_COMMAND,
  };
}

function runDoctor() {
  const checks = [];
  const bundledSfx = inspectBundledSfxAssets();
  checks.push({
    name: "bundled SFX assets",
    ok: bundledSfx.ok,
    detail: bundledSfx.detail,
    fix: bundledSfx.fix,
  });
  const heygenVersionProbe = runCommand("heygen", ["--version"]);
  const heygenOnPath = heygenVersionProbe.status === 0;
  const heygenVersionText = commandText(heygenVersionProbe);
  const heygenVersion = firstSemver(heygenVersionText);

  checks.push({
    name: "heygen on PATH",
    ok: heygenOnPath,
    // Just "is the binary here" — the version row below owns the version string,
    // so this row must not also render `heygen v0.3.0` (two byte-identical lines).
    detail: heygenOnPath ? "heygen found on PATH" : "heygen not found",
    fix: heygenOnPath ? "" : HEYGEN_INSTALL_COMMAND,
  });

  if (!heygenOnPath) {
    checks.push({
      name: "heygen version",
      ok: false,
      detail: "heygen version unavailable",
      fix: HEYGEN_INSTALL_COMMAND,
    });
    checks.push({
      name: "heygen authenticated",
      ok: false,
      detail: "heygen auth status unavailable",
      fix: HEYGEN_INSTALL_COMMAND,
    });
  } else if (heygenVersion) {
    const versionOk = !versionLessThan(heygenVersion, HEYGEN_MIN_VERSION);
    // Keep it latest: even when the installed version clears the floor, nudge
    // `heygen update` if a newer stable exists. Best-effort — silently skipped
    // when the CDN is unreachable, so it never blocks the check.
    const latest = versionOk ? latestHeygenStable() : null;
    const behind = latest && versionLessThan(heygenVersion, latest);
    checks.push({
      name: "heygen version",
      ok: versionOk,
      detail: versionOk
        ? `heygen v${heygenVersion}${behind ? ` (latest v${latest} available)` : ""}`
        : `heygen v${heygenVersion} (need >= v${HEYGEN_MIN_VERSION})`,
      fix: versionOk ? (behind ? HEYGEN_UPDATE_COMMAND : "") : HEYGEN_UPDATE_COMMAND,
    });

    // Older CLI versions cannot provide the auth status used here.
    checks.push(
      versionOk
        ? heygenAuthCheck()
        : {
            name: "heygen authenticated",
            ok: false,
            detail: "skipped — update heygen first",
            fix: HEYGEN_UPDATE_COMMAND,
          },
    );
  } else {
    // Fail-open: heygen ran but printed no semver (dev/stripped build). We can't
    // verify the version, so we don't block on it — but say so rather than a bare
    // green check that implies a real version comparison happened.
    checks.push({
      name: "heygen version",
      ok: true,
      detail: "heygen present; version unverifiable (no semver in --version output)",
      fix: "",
    });

    checks.push(heygenAuthCheck());
  }

  checks.push(ffDoctorCheck("ffmpeg", ffmpegBinary), ffDoctorCheck("ffprobe", ffprobeBinary));

  const nodeOk = !versionLessThan(process.versions.node, MIN_NODE_VERSION);
  checks.push({
    name: "node version",
    ok: nodeOk,
    detail: `${process.version} (need >= v${MIN_NODE_VERSION})`,
    fix: nodeOk ? "" : `upgrade Node to >= v${MIN_NODE_VERSION}`,
  });

  // ffmpeg AND ffprobe are both strictly required (see references/setup-providers.md); the exit code
  // must reflect that so a script gating on `--doctor` doesn't pass with ffprobe
  // missing and then break at the first probe call.
  const ffmpeg = checks.find((check) => check.name === "ffmpeg on PATH");
  const ffprobe = checks.find((check) => check.name === "ffprobe on PATH");
  return { ok: bundledSfx.ok && !!ffmpeg?.ok && !!ffprobe?.ok, checks };
}

function printDoctor(checks) {
  const heygenChecks = new Set(["heygen on PATH", "heygen version", "heygen authenticated"]);
  for (const check of checks) {
    const prefix = check.ok ? "✓" : "✗";
    const freePath = heygenChecks.has(check.name)
      ? " — free-usage path: bgm/image/voice/avatar-video"
      : "";
    const fix = check.ok || !check.fix ? "" : ` — fix: ${check.fix}`;
    console.log(`${prefix} ${check.detail}${freePath}${fix}`);
  }
}

function printStats(report) {
  console.log("media-use stats");
  console.log(`total resolves: ${report.total_resolves}`);
  console.log(`misses: ${report.misses}`);
  console.log(
    `hit rate: ${report.hit_rate == null ? "n/a" : `${Math.round(report.hit_rate * 100)}%`}`,
  );
  printMap("by type", report.by_type);
  printMap("by source", report.by_source);
  printMap("by provider", report.by_provider);
  printMap("by via", report.by_via);
  console.log(`global cache assets: ${report.global_cache_assets}`);
  console.log(`global cache disk: ${report.global_cache_disk_bytes} bytes`);
  console.log(`cross-project reuse: ${report.cross_project_reuse}`);
  console.log("top missed intents:");
  const entries = Object.entries(report.top_missed_intents);
  if (entries.length === 0) {
    console.log("  none");
    return;
  }
  for (const [type, misses] of entries) {
    console.log(`  ${type}:`);
    for (const miss of misses) console.log(`    ${miss.count}  ${miss.intent}`);
  }
}

function printMap(label, values) {
  const entries = Object.entries(values);
  console.log(`${label}:`);
  if (entries.length === 0) {
    console.log("  none");
    return;
  }
  for (const [key, value] of entries) console.log(`  ${key}: ${value}`);
}

function ffDoctorCheck(name, binary) {
  let bin;
  try {
    bin = binary();
  } catch (err) {
    return {
      name: `${name} on PATH`,
      ok: false,
      detail: err.message,
      fix: "fix or unset that variable",
    };
  }
  const probe = runCommand(bin, ["-version"]);
  const ok = probe.status === 0;
  return {
    name: `${name} on PATH`,
    ok,
    detail: ok ? firstLine(probe.stdout) : `${name} not found`,
    fix: ok ? "" : "brew install ffmpeg",
  };
}

function runCommand(bin, argv) {
  return spawnSync(bin, argv, {
    encoding: "utf8",
    timeout: 15000,
  });
}

function commandText(result) {
  return [result.stdout, result.stderr].filter(Boolean).join("\n").trim();
}

function firstLine(text) {
  return (
    String(text || "")
      .trim()
      .split(/\r?\n/)[0] || ""
  );
}

function emailFromAuthStatus(text) {
  // JSON only (auth status emits JSON by default). No prose regex fallback: a
  // human-format body like "Session expired. Contact [email protected]" would
  // otherwise report the user as authenticated as [email protected].
  const trimmed = String(text || "").trim();
  if (!trimmed.startsWith("{")) return null;
  try {
    const parsed = JSON.parse(trimmed);
    return parsed?.data?.email || parsed?.email || null;
  } catch {
    return null;
  }
}

async function reuseGlobal(shaArg) {
  const projectDir = resolve(args.project);
  const type = args.type;
  if (!type || !listTypes().includes(type)) {
    console.error(`error: --reuse requires --type (one of: ${listTypes().join(", ")})`);
    process.exit(2);
  }
  if (!shaArg || !shaArg.trim()) {
    console.error("error: --reuse needs a content sha/prefix (from `resolve --candidates`)");
    process.exit(2);
  }
  const rec = findGlobalBySha(shaArg);
  if (rec && rec.ambiguous) {
    console.error(
      `error: sha prefix "${shaArg}" is ambiguous (${rec.count} matches) — use more characters`,
    );
    process.exit(2);
  }
  if (!rec) {
    console.error(`error: no reusable global asset matches sha "${shaArg}"`);
    process.exit(1);
  }
  // Do not import an asset under the wrong type.
  if (!typesMatch(rec.type, type)) {
    console.error(`error: sha "${shaArg}" is a ${rec.type} asset, not ${type}`);
    process.exit(2);
  }
  const ext = extname(rec.cached_path || "") || defaultExt(type);
  const imported = withReservedFileSync(projectDir, type, ext, ({ id, localPath }) =>
    localizeImportedRecord(importFromCache(rec, projectDir, id, localPath), localPath),
  );
  if (!imported) {
    console.error(`error: cache entry for "${shaArg}" is incomplete or missing on disk`);
    process.exit(1);
  }
  // Distinguish an explicit agent reuse from an automatic normalize-exact hit.
  imported.source = "reused-explicit";
  imported.provenance = { ...imported.provenance, reused_by: "agent" };
  appendRecord(projectDir, imported);
  regenerateIndex(projectDir);
  await result(imported, "reused-explicit");
}

async function result(record, source) {
  const { provider, license, credit, source_url: sourceUrl } = record.provenance ?? {};
  // Under the media lock: two resolves at once each read, then rewrite, the whole credits file.
  if (provider === OPENVERSE_SFX_PROVIDER)
    withMediaLock(projectDir, () =>
      writeSfxCredit(join(typeDirPath(projectDir, "sfx"), "CREDITS.md"), record.path, {
        license,
        credit,
        sourceUrl,
      }),
    );
  // Non-PII usage event: which media type, how it resolved, which provider won.
  // Never the intent text or paths. Awaited so a short-lived run flushes it.
  await track("media_use_resolve", {
    type: record.type,
    source,
    provider: record.provenance?.provider,
    // How a library LUT resolved: "url" (CDN), "params-fallback" (CDN failed →
    // parametric), or "params" (offline). Surfaces silent CDN→params downgrades
    // in prod, which --doctor can't (it only answers "reachable now?").
    via: record.provenance?.via,
    // OAuth vs. API-key HeyGen paths are sparse for non-HeyGen providers.
    // signal about the fetch that actually consumed a heygen credit, not
    // about the (free, no-credential) act of copying a cached file.
    auth_method: record.provenance?.authMethod,
    // Provider tiers stay sparse and follow the registry's A/N/P declaration.
    provider_tier: providerTierFor(record.provenance?.provider),
    local_only: !!args["local-only"],
    provider_override: !!args.provider,
  });
  if (args.json) {
    const grading = record.type === "grade" && record.grading ? record.grading : null;
    console.log(
      JSON.stringify({
        ok: true,
        ...record,
        ...(grading || {}),
        ...(grading && { grading }),
        _source: source,
      }),
    );
  } else {
    const meta = formatMeta(record, source);
    console.log(`resolved ${record.id} → ${record.path || "inline"} (${meta})`);
  }
}

function formatMeta(record, source) {
  const parts = [record.type];
  if (record.grading?.preset) parts.push(`preset ${record.grading.preset}`);
  if (record.grading?.lut) parts.push("lut");
  if (record.duration != null) parts.push(`${record.duration}s`);
  if (record.width && record.height) parts.push(`${record.width}×${record.height}`);
  if (record.transparent) parts.push("transparent");
  if (source === "reused" || source === "reused-explicit") parts.push("reused");
  if (source === "generated") parts.push("generated");
  return parts.join(", ");
}

function extFromUrl(url) {
  try {
    return extname(new URL(url).pathname) || null;
  } catch {
    return null;
  }
}

function defaultExt(type) {
  return DEFAULT_EXT[type] || ".bin";
}

run().catch((err) => {
  if (args.json) {
    console.log(JSON.stringify({ ok: false, error: err.message }));
  } else {
    console.error(`error: ${err.message}`);
  }
  process.exit(1);
});