@drantoniou/uploadcheck 0.1.0 → 0.3.0

package/api-client.mjs

@@ -0,0 +1,88 @@
+// Shared UploadCheck API HTTP client — the submit/poll/report primitives used by
+// both `uploadcheck check` (one-shot) and `uploadcheck watch` (folder daemon).
+// Every call authenticates with the workspace key (Bearer UPLOADCHECK_API_KEY) and
+// therefore draws on the same prepaid minutes; the watcher adds no new server surface.
+import { createReadStream } from "node:fs";
+
+const TERMINAL_STATUSES = new Set(["completed", "failed", "cancelled"]);
+
+export async function postJson(apiBaseUrl, path, payload, apiKey) {
+  const response = await fetch(`${apiBaseUrl}${path}`, {
+    method: "POST",
+    headers: { "content-type": "application/json", authorization: `Bearer ${apiKey}` },
+    body: JSON.stringify(payload)
+  });
+  const body = await response.json();
+  if (!response.ok) throw new Error(`UploadCheck API ${response.status}: ${JSON.stringify(body)}`);
+  return body;
+}
+
+export async function getJson(apiBaseUrl, path, apiKey) {
+  const response = await fetch(`${apiBaseUrl}${path}`, {
+    method: "GET",
+    headers: apiKey ? { authorization: `Bearer ${apiKey}` } : undefined
+  });
+  const body = await response.json();
+  if (!response.ok) throw new Error(`UploadCheck API ${response.status}: ${JSON.stringify(body)}`);
+  return body;
+}
+
+export async function getText(apiBaseUrl, path, apiKey) {
+  const response = await fetch(`${apiBaseUrl}${path}`, {
+    method: "GET",
+    headers: apiKey ? { authorization: `Bearer ${apiKey}` } : undefined
+  });
+  const text = await response.text();
+  if (!response.ok) throw new Error(`UploadCheck API ${response.status}: ${text}`);
+  return text;
+}
+
+// Submit a built job request (inline or signed-upload) and return the job payload.
+export async function submitJob(request, apiKey) {
+  if (request.kind === "signed_upload") return runSignedUploadJob(request, apiKey);
+  return postJson(request.apiBaseUrl, request.path, request.payload, apiKey);
+}
+
+async function runSignedUploadJob(request, apiKey) {
+  const upload = await postJson(request.apiBaseUrl, request.createUpload.path, request.createUpload.payload, apiKey);
+  const putResponse = await fetch(upload.signedPutUrl, {
+    method: "PUT",
+    headers: { "content-type": request.contentType, "content-length": String(request.sizeBytes) },
+    body: createReadStream(request.filePath),
+    duplex: "half"
+  });
+  if (!putResponse.ok) {
+    const text = await putResponse.text();
+    throw new Error(`UploadCheck upload ${putResponse.status}: ${text}`);
+  }
+  return postJson(request.apiBaseUrl, request.createJob.path, { ...request.createJob.payload, upload_id: upload.uploadId }, apiKey);
+}
+
+// Poll a job until it reaches a terminal status (completed/failed/cancelled).
+// onProgress(job) is called on each poll so the caller can show a progress line.
+export async function pollJobUntilDone(apiBaseUrl, jobId, apiKey, { intervalMs = 4000, timeoutMs = 30 * 60 * 1000, onProgress = null } = {}) {
+  const started = Date.now();
+  for (;;) {
+    const job = await getJson(apiBaseUrl, `/v1/qc/jobs/${jobId}`, apiKey);
+    if (onProgress) onProgress(job);
+    if (TERMINAL_STATUSES.has(job.status)) return job;
+    if (Date.now() - started > timeoutMs) throw new Error(`Timed out waiting for job ${jobId} (last status: ${job.status})`);
+    await sleep(intervalMs);
+  }
+}
+
+export function fetchReport(apiBaseUrl, jobId, apiKey) {
+  return getJson(apiBaseUrl, `/v1/qc/jobs/${jobId}/report`, apiKey);
+}
+
+// Marker CSV (Premiere/Resolve) — may not exist for every job; returns null on 404.
+export async function fetchMarkerCsv(apiBaseUrl, jobId, apiKey) {
+  try {
+    return await getText(apiBaseUrl, `/v1/qc/jobs/${jobId}/artifacts/markers`, apiKey);
+  } catch {
+    return null;
+  }
+}
+
+export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export { TERMINAL_STATUSES };

package/index.mjs

@@ -1,17 +1,23 @@
 #!/usr/bin/env node
-import { createReadStream } from "node:fs";
-import { buildCostBasisRequest, buildEstimateRequest, buildJobRequest, buildLaunchDoctorRequest, buildLaunchEvidenceRequest, buildLaunchHandoffRequest, buildLaunchStatusRequest, buildNpoPipelineHandoffRequest, buildPipelineHandoffRequest, buildPipelineRecipesRequest, buildRemoteLaunchEvidence, buildUsageRequest, formatCostBasisSummary, formatJobSummary, formatLaunchDoctorSummary, formatLaunchEvidenceSummary, formatLaunchHandoffSummary, formatLaunchStatusSummary, formatNpoPipelineHandoffSummary, formatPipelineHandoffSummary, formatPipelineRecipesSummary, formatUsageSummary, parseArgs } from "./request-builder.mjs";
+import { buildCostBasisRequest, buildEstimateRequest, buildJobRequest, buildLaunchDoctorRequest, buildLaunchEvidenceRequest, buildLaunchHandoffRequest, buildLaunchStatusRequest, buildNpoPipelineHandoffRequest, buildPipelineHandoffRequest, buildPipelineRecipesRequest, buildRemoteLaunchEvidence, formatCostBasisSummary, formatJobSummary, formatLaunchDoctorSummary, formatLaunchEvidenceSummary, formatLaunchHandoffSummary, formatLaunchStatusSummary, formatNpoPipelineHandoffSummary, formatPipelineHandoffSummary, formatPipelineRecipesSummary, parseArgs } from "./request-builder.mjs";
+import { getJson, postJson, submitJob } from "./api-client.mjs";
+import { runWatch } from "./watch.mjs";
 
 try {
   const { command, target, options } = parseArgs(process.argv.slice(2));
-  const apiKey = options.apiKey || process.env.UPLOADCHECK_API_KEY || process.env.QCGENIE_API_KEY;
+  const apiKey = options.apiKey || process.env.UPLOADCHECK_API_KEY;
+
+  if (command === "watch") {
+    await runWatch(target, options, apiKey);
+    process.exit(process.exitCode || 0);
+  }
 
   const request = command === "estimate"
     ? buildEstimateRequest(options)
-    : (command === "usage" ? buildUsageRequest(options) : (command === "launch-status" ? buildLaunchStatusRequest(options) : (command === "launch-handoff" ? buildLaunchHandoffRequest(options) : (command === "launch-doctor" ? buildLaunchDoctorRequest(options) : (command === "launch-evidence" ? buildLaunchEvidenceRequest(options) : (command === "pipeline-handoff" ? buildPipelineHandoffRequest(options) : (command === "npo-pipeline-handoff" ? buildNpoPipelineHandoffRequest(options) : (command === "recipes" ? buildPipelineRecipesRequest(options) : (command === "cost-basis" ? buildCostBasisRequest(options) : buildJobRequest(target, options))))))))));
+    : (command === "launch-status" ? buildLaunchStatusRequest(options) : (command === "launch-handoff" ? buildLaunchHandoffRequest(options) : (command === "launch-doctor" ? buildLaunchDoctorRequest(options) : (command === "launch-evidence" ? buildLaunchEvidenceRequest(options) : (command === "pipeline-handoff" ? buildPipelineHandoffRequest(options) : (command === "npo-pipeline-handoff" ? buildNpoPipelineHandoffRequest(options) : (command === "recipes" ? buildPipelineRecipesRequest(options) : (command === "cost-basis" ? buildCostBasisRequest(options) : buildJobRequest(target, options)))))))));
   if (!request.public && !apiKey) throw new Error("Set UPLOADCHECK_API_KEY or pass --api-key.");
-  const rawPayload = request.kind === "signed_upload"
-    ? await runSignedUploadJob(request, apiKey)
+  const rawPayload = (request.kind === "signed_upload" || request.kind === "job")
+    ? await submitJob(request, apiKey)
     : (request.method === "GET" ? await getJson(request.apiBaseUrl, request.path, apiKey) : await postJson(request.apiBaseUrl, request.path, request.payload, apiKey));
   const payload = request.kind === "launch_evidence" && rawPayload.name !== "UploadCheck.app Remote Launch Evidence"
     ? buildRemoteLaunchEvidence(rawPayload, { source: `${request.apiBaseUrl}${request.path}` })
@@ -24,7 +30,6 @@ try {
 }
 
 function formatSummary(kind, payload) {
-  if (kind === "usage") return formatUsageSummary(payload);
   if (kind === "launch_status") return formatLaunchStatusSummary(payload);
   if (kind === "launch_handoff") return formatLaunchHandoffSummary(payload);
   if (kind === "launch_doctor") return formatLaunchDoctorSummary(payload);
@@ -36,54 +41,3 @@ function formatSummary(kind, payload) {
   return formatJobSummary(payload);
 }
 
-async function runSignedUploadJob(request, apiKey) {
-  const upload = await postJson(request.apiBaseUrl, request.createUpload.path, request.createUpload.payload, apiKey);
-  const putResponse = await fetch(upload.signedPutUrl, {
-    method: "PUT",
-    headers: {
-      "content-type": request.contentType,
-      "content-length": String(request.sizeBytes)
-    },
-    body: createReadStream(request.filePath),
-    duplex: "half"
-  });
-  if (!putResponse.ok) {
-    const text = await putResponse.text();
-    throw new Error(`UploadCheck upload ${putResponse.status}: ${text}`);
-  }
-  const jobPayload = {
-    ...request.createJob.payload,
-    upload_id: upload.uploadId
-  };
-  return postJson(request.apiBaseUrl, request.createJob.path, jobPayload, apiKey);
-}
-
-async function postJson(apiBaseUrl, path, payload, apiKey) {
-  const response = await fetch(`${apiBaseUrl}${path}`, {
-    method: "POST",
-    headers: {
-      "content-type": "application/json",
-      authorization: `Bearer ${apiKey}`
-    },
-    body: JSON.stringify(payload)
-  });
-  const body = await response.json();
-  if (!response.ok) {
-    throw new Error(`UploadCheck API ${response.status}: ${JSON.stringify(body)}`);
-  }
-  return body;
-}
-
-async function getJson(apiBaseUrl, path, apiKey) {
-  const response = await fetch(`${apiBaseUrl}${path}`, {
-    method: "GET",
-    headers: apiKey ? {
-      authorization: `Bearer ${apiKey}`
-    } : undefined
-  });
-  const body = await response.json();
-  if (!response.ok) {
-    throw new Error(`UploadCheck API ${response.status}: ${JSON.stringify(body)}`);
-  }
-  return body;
-}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@drantoniou/uploadcheck",
-  "version": "0.1.0",
-  "description": "Quality check videos, podcasts, and clips before you upload.",
+  "version": "0.3.0",
+  "description": "The quality gate for AI-generated media. Check videos, podcasts, and clips before you publish — or `watch` a folder to auto-QC every render.",
   "homepage": "https://uploadcheck.app",
   "repository": {
     "type": "git",
@@ -18,7 +18,10 @@
   },
   "files": [
     "index.mjs",
+    "api-client.mjs",
+    "watch.mjs",
     "launch-evidence.mjs",
+    "qc-profiles.mjs",
     "request-builder.mjs"
   ],
   "license": "UNLICENSED",

package/qc-profiles.mjs

@@ -0,0 +1,123 @@
+export const NTO_LONG_FORM_CHECKS = [
+  "canvas_fill",
+  "loop_freeze",
+  "repeat_fatigue",
+  "speaker_visual_binding",
+  "static_head_dominance",
+  "literal_subject_match",
+  "visual_narration_match",
+  "first_three_seconds",
+  "end_screen_tease",
+  "rehook_cadence",
+  "contact_sheet_evidence",
+  "text_crop_jitter",
+  "text_overlap",
+  "thumbnail_text_readability",
+  "hallucinated_plate_text",
+  "clean_segment_source_scrub",
+  "voiceover_music_balance",
+  "dead_air",
+  "text_contrast",
+  "text_safe_area"
+];
+
+export const PROFILE_CHECKS = {
+  nto_long_form: NTO_LONG_FORM_CHECKS,
+  generic_creator_video: [
+    "canvas_fill",
+    "loop_freeze",
+    "repeat_fatigue",
+    "dead_air",
+    "text_contrast",
+    "text_overlap",
+    "text_safe_area"
+  ],
+  shorts: [
+    "canvas_fill",
+    "shorts_format",
+    "opening_footer_text_presence",
+    "first_three_seconds",
+    "end_screen_tease",
+    "text_contrast",
+    "text_safe_area",
+    "text_crop_jitter",
+    "text_overlap",
+    "repeat_fatigue",
+    "sentence_boundary",
+    "dialogue_in_music_short",
+    "voiceover_music_balance",
+    "dead_air"
+  ],
+  audio: [
+    "dead_air",
+    "voiceover_music_balance",
+    "spoken_leaks",
+    "pronunciation_watchlist",
+    "script_faithfulness",
+    "sentence_boundary",
+    "chunk_sidecar_failures"
+  ],
+  npo_podcast_or_audio: [
+    "dead_air",
+    "voiceover_music_balance",
+    "spoken_leaks",
+    "pronunciation_watchlist",
+    "script_faithfulness",
+    "sentence_boundary",
+    "chunk_sidecar_failures"
+  ],
+  thumbnail: [
+    "text_overlap",
+    "thumbnail_text_readability"
+  ]
+};
+
+export const PROFILE_IDS = [...Object.keys(PROFILE_CHECKS), "auto"];
+
+export function normalizeProfileId(value) {
+  const normalized = String(value || "").trim().toLowerCase().replaceAll("-", "_");
+  if (!normalized) return null;
+  if (normalized === "long_form" || normalized === "nto") return "nto_long_form";
+  if (normalized === "short" || normalized === "youtube_short" || normalized === "reels" || normalized === "tiktok") return "shorts";
+  if (normalized === "podcast" || normalized === "npo_audio") return "npo_podcast_or_audio";
+  if (normalized === "generic_video" || normalized === "creator_video") return "generic_creator_video";
+  if (PROFILE_IDS.includes(normalized)) return normalized;
+  return null;
+}
+
+export function checksForProfile(profile, context = {}) {
+  const normalized = normalizeProfileId(profile);
+  if (!normalized) return null;
+  const resolved = normalized === "auto" ? inferProfile(context) : normalized;
+  const checks = PROFILE_CHECKS[resolved];
+  return checks ? { profile: resolved, requestedProfile: normalized, checks: checks.join(",") } : null;
+}
+
+export function inferProfile(context = {}) {
+  const mediaKind = String(context.mediaKind || context.media_kind || "").toLowerCase();
+  if (mediaKind === "audio") return "audio";
+  if (mediaKind === "image") return "thumbnail";
+  const durationSeconds = Number(context.durationSeconds ?? context.duration_seconds ?? 0) || 0;
+  const filename = String(context.filename || context.mediaFilename || context.media_filename || "").toLowerCase();
+  if ((durationSeconds >= 45 && durationSeconds <= 75) || filename.includes("short") || filename.includes("reel") || filename.includes("tiktok")) {
+    return "shorts";
+  }
+  return "generic_creator_video";
+}
+
+export function applyProfileToInput(input = {}) {
+  const profile = input.profile || input.qc_profile || input.qcProfile;
+  if (input.checks || !profile) return { ...input };
+  const resolved = checksForProfile(profile, {
+    mediaKind: input.media_kind || input.mediaKind,
+    durationSeconds: input.duration_seconds || input.durationSeconds,
+    filename: input.filename || input.media_filename || input.mediaFilename
+  });
+  if (!resolved) return { ...input };
+  return {
+    ...input,
+    profile: resolved.profile,
+    requested_profile: resolved.requestedProfile,
+    checks: resolved.checks
+  };
+}

package/request-builder.mjs

@@ -1,11 +1,12 @@
 import { extname, basename, join, relative } from "node:path";
 import { statSync, readFileSync, existsSync, readdirSync } from "node:fs";
+import { applyProfileToInput } from "./qc-profiles.mjs";
 
 const DEFAULT_API_BASE_URL = "https://api.uploadcheck.app";
 const DEFAULT_MAX_INLINE_MB = 128;
 const LAUNCH_PROOF_CONTRACT_VERSION = "2026-06-06.render-web-proof";
 
-const CONTENT_TYPES = new Map([
+export const CONTENT_TYPES = new Map([
   [".mp4", "video/mp4"],
   [".mov", "video/quicktime"],
   [".m4v", "video/x-m4v"],
@@ -53,7 +54,9 @@ export function buildJobRequest(target, options = {}) {
     payload.filename = basename(target);
   }
 
+  if (options.profile) payload.profile = options.profile;
   if (options.checks) payload.checks = options.checks;
+  applyProfilePayload(payload);
   attachManifest(payload, options);
   attachTranscript(payload, options);
   attachWatchlist(payload, options);
@@ -78,7 +81,9 @@ export function buildSignedUploadPlan(target, options = {}, fileStat = null) {
   const apiBaseUrl = trimTrailingSlash(options.apiBaseUrl || process.env.UPLOADCHECK_API_BASE_URL || DEFAULT_API_BASE_URL);
   const contentType = inferContentType(target);
   const jobPayload = {};
+  if (options.profile) jobPayload.profile = options.profile;
   if (options.checks) jobPayload.checks = options.checks;
+  applyProfilePayload(jobPayload, { contentType, mediaKind: inferMediaKind(contentType), filename: basename(target) });
   attachManifest(jobPayload, options);
   attachTranscript(jobPayload, options);
   attachWatchlist(jobPayload, options);
@@ -114,9 +119,9 @@ export function buildSignedUploadPlan(target, options = {}, fileStat = null) {
 export function parseArgs(argv) {
   const args = [...argv];
   const command = args.shift();
-  if (!["check", "estimate", "usage", "launch-status", "launch-handoff", "launch-doctor", "launch-evidence", "pipeline-handoff", "npo-pipeline-handoff", "recipes", "cost-basis"].includes(command)) throw new Error("Usage: uploadcheck check <file-or-url> | uploadcheck estimate --minutes N | uploadcheck usage | uploadcheck launch-status | uploadcheck launch-handoff | uploadcheck launch-doctor | uploadcheck launch-evidence | uploadcheck pipeline-handoff | uploadcheck npo-pipeline-handoff | uploadcheck recipes | uploadcheck cost-basis");
+  if (!["check", "watch", "estimate", "usage", "launch-status", "launch-handoff", "launch-doctor", "launch-evidence", "pipeline-handoff", "npo-pipeline-handoff", "recipes", "cost-basis"].includes(command)) throw new Error("Usage: uploadcheck check <file-or-url> | uploadcheck watch <folder> | uploadcheck estimate --minutes N | uploadcheck usage | uploadcheck launch-status | uploadcheck launch-handoff | uploadcheck launch-doctor | uploadcheck launch-evidence | uploadcheck pipeline-handoff | uploadcheck npo-pipeline-handoff | uploadcheck recipes | uploadcheck cost-basis");
 
-  const target = command === "check" ? args.shift() : null;
+  const target = (command === "check" || command === "watch") ? args.shift() : null;
   const options = { json: false };
 
   while (args.length) {
@@ -129,6 +134,8 @@ export function parseArgs(argv) {
       options.apiKey = requireValue(arg, args.shift());
     } else if (arg === "--checks") {
       options.checks = requireValue(arg, args.shift());
+    } else if (arg === "--profile") {
+      options.profile = requireValue(arg, args.shift());
     } else if (arg === "--manifest") {
       options.manifestPath = requireValue(arg, args.shift());
     } else if (arg === "--transcript") {
@@ -175,6 +182,18 @@ export function parseArgs(argv) {
       const mode = requireValue(arg, args.shift());
       if (!["auto", "inline", "signed"].includes(mode)) throw new Error("--upload-mode must be auto, inline, or signed");
       options.uploadMode = mode;
+    } else if (arg === "--once") {
+      options.once = true;
+    } else if (arg === "--concurrency") {
+      options.concurrency = requireValue(arg, args.shift());
+    } else if (arg === "--settle-ms") {
+      options.settleMs = requireValue(arg, args.shift());
+    } else if (arg === "--poll-ms") {
+      options.pollMs = requireValue(arg, args.shift());
+    } else if (arg === "--on-pass") {
+      options.onPass = requireValue(arg, args.shift());
+    } else if (arg === "--on-fail") {
+      options.onFail = requireValue(arg, args.shift());
     } else {
       throw new Error(`Unknown option: ${arg}`);
     }
@@ -271,26 +290,14 @@ export function buildCostBasisRequest(options = {}) {
   };
 }
 
-export function buildUsageRequest(options = {}) {
-  const apiBaseUrl = trimTrailingSlash(options.apiBaseUrl || process.env.UPLOADCHECK_API_BASE_URL || DEFAULT_API_BASE_URL);
-  const params = new URLSearchParams();
-  if (options.billingPeriod) params.set("billing_period", options.billingPeriod);
-  if (options.limit) params.set("limit", Number(options.limit));
-  const query = params.toString();
-  return {
-    apiBaseUrl,
-    path: `/v1/usage/margins${query ? `?${query}` : ""}`,
-    method: "GET",
-    kind: "usage"
-  };
-}
-
 export function buildEstimateRequest(options = {}) {
   const apiBaseUrl = trimTrailingSlash(options.apiBaseUrl || process.env.UPLOADCHECK_API_BASE_URL || DEFAULT_API_BASE_URL);
   const payload = {};
+  if (options.profile) payload.profile = options.profile;
   if (options.checks) payload.checks = options.checks;
   if (options.minutes) payload.minutes = Number(options.minutes);
   if (options.durationSeconds) payload.duration_seconds = Number(options.durationSeconds);
+  applyProfilePayload(payload);
   attachCostOptions(payload, options);
   return {
     apiBaseUrl,
@@ -315,19 +322,6 @@ export function formatJobSummary(payload) {
   return `UploadCheck job ${payload.jobId || payload.id || "(unknown)"}: ${status} / ${verdict} | ${minutes} min${ingressSuffix}${suffix}`;
 }
 
-export function formatUsageSummary(payload) {
-  const summary = payload.summary || {};
-  const minutes = Number(summary.minutes || 0);
-  const cogs = Number(summary.estimatedCogsCents || 0) / 100;
-  const costPerMinuteCents = Number(summary.estimatedCostPerMinuteCents || 0);
-  const grossMarginPct = Number(summary.estimatedGrossMarginPct || 0);
-  const status = summary.marginSafe === false ? "MARGIN RISK" : "MARGIN SAFE";
-  const observed = summary.observedProviderUsageEntries > 0
-    ? ` | observed cost/min ${Number(summary.observedCostPerMinuteCents || 0).toFixed(4)}c | observed margin ${Number(summary.observedGrossMarginPct || 0).toFixed(2)}%`
-    : "";
-  return `UploadCheck usage: ${status} | ${minutes} min | est. COGS $${cogs.toFixed(4)} | cost/min ${costPerMinuteCents.toFixed(4)}c | margin ${grossMarginPct.toFixed(2)}%${observed}`;
-}
-
 export function formatLaunchStatusSummary(payload) {
   const status = payload.product_hunt_ready ? "READY" : "NOT READY";
   const blockers = (payload.remaining_blockers || []).map((blocker) => blocker.id).filter(Boolean);
@@ -486,6 +480,20 @@ function attachCostOptions(payload, options) {
   if (options.costGuardrail) payload.cost_guardrail = options.costGuardrail;
 }
 
+function applyProfilePayload(payload, context = {}) {
+  const resolved = applyProfileToInput({
+    ...payload,
+    media_kind: payload.media_kind,
+    duration_seconds: payload.duration_seconds,
+    mediaKind: payload.media_kind || context.mediaKind,
+    filename: payload.filename || context.filename,
+    media_content_type: payload.media_content_type || context.contentType
+  });
+  if (resolved.profile) payload.profile = resolved.profile;
+  if (resolved.requested_profile) payload.requested_profile = resolved.requested_profile;
+  if (resolved.checks) payload.checks = resolved.checks;
+}
+
 function formatMediaIngress(mediaIngress) {
   if (!mediaIngress?.mode) return "";
   const detail = [mediaIngress.mode, mediaIngress.contentType, formatBytes(mediaIngress.bytes), formatSha256(mediaIngress.sha256)].filter(Boolean).join(" ");

package/watch.mjs

@@ -0,0 +1,225 @@
+// `uploadcheck watch <folder>` — auto-QC every media file dropped into a folder.
+//
+// This is the automation layer for AI/agency pipelines: a video generator (or a
+// human editor) drops renders into an inbox and UploadCheck reviews each one,
+// writing the report next to the source file. It is a thin orchestration loop over
+// the same submit/poll/report primitives `uploadcheck check` already uses — no new
+// server endpoint, no extra dependency. Auth is the workspace key, so scans draw on
+// the same prepaid minutes.
+//
+// Design notes:
+//   * Discovery uses a periodic readdir sweep (reliable across network drives) plus
+//     fs.watch for low-latency wakeups. fs.watch alone is unreliable; the sweep is
+//     the workhorse.
+//   * Stable-write gating: a file is only submitted once its size+mtime have stayed
+//     unchanged across two sweeps AND it is older than --settle-ms, so a half-written
+//     multi-GB render is never QC'd mid-copy.
+//   * Dedup is two-layered: an on-disk ledger keyed by sha(size:mtime:relpath), plus
+//     a shortcut that skips any file whose <file>.uploadcheck.json report already
+//     exists. Restarts never re-meter minutes.
+import { readdirSync, statSync, existsSync, writeFileSync, readFileSync, watch as fsWatch } from "node:fs";
+import { join, extname, basename, dirname, resolve, relative } from "node:path";
+import { createHash } from "node:crypto";
+import { spawn } from "node:child_process";
+import { buildJobRequest, CONTENT_TYPES } from "./request-builder.mjs";
+import { submitJob, pollJobUntilDone, fetchReport, fetchMarkerCsv, sleep } from "./api-client.mjs";
+
+const LEDGER_NAME = ".uploadcheck-watch.json";
+const AGGREGATE_CSV = "uploadcheck-report.csv";
+const DEFAULT_SETTLE_MS = 5000;
+const DEFAULT_CONCURRENCY = 2;
+const DEFAULT_POLL_MS = 4000;
+const SWEEP_INTERVAL_MS = 3000;
+
+export const isMediaFile = (name) => CONTENT_TYPES.has(extname(name).toLowerCase());
+// Our own output files + the ledger must never be treated as inputs.
+export const isOwnOutput = (name) => name === LEDGER_NAME || name === AGGREGATE_CSV ||
+  name.endsWith(".uploadcheck.json") || name.endsWith(".uploadcheck.markers.csv");
+
+const sourceKeyFor = (dir, filePath, stat) =>
+  createHash("sha256").update(`${stat.size}:${Math.round(stat.mtimeMs)}:${relative(dir, filePath)}`).digest("hex").slice(0, 16);
+
+const reportPathFor = (filePath) => `${filePath}.uploadcheck.json`;
+const markerPathFor = (filePath) => `${filePath}.uploadcheck.markers.csv`;
+
+function loadLedger(dir) {
+  const p = join(dir, LEDGER_NAME);
+  if (!existsSync(p)) return { done: {} };
+  try { return JSON.parse(readFileSync(p, "utf8")); } catch { return { done: {} }; }
+}
+function saveLedger(dir, ledger) {
+  try { writeFileSync(join(dir, LEDGER_NAME), JSON.stringify(ledger, null, 2)); } catch { /* best-effort */ }
+}
+
+// A file is "settled" once it's old enough and unchanged since we last saw it.
+function isSettled(filePath, stat, seen, settleMs) {
+  const ageMs = Date.now() - stat.mtimeMs;
+  const prev = seen.get(filePath);
+  seen.set(filePath, { size: stat.size, mtimeMs: stat.mtimeMs });
+  if (ageMs < settleMs) return false;
+  if (!prev) return false; // need at least one prior observation to confirm stability
+  return prev.size === stat.size && prev.mtimeMs === stat.mtimeMs;
+}
+
+function discoverCandidates(dir) {
+  const out = [];
+  let entries;
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return out; }
+  for (const ent of entries) {
+    if (!ent.isFile()) continue;
+    if (isOwnOutput(ent.name) || ent.name.startsWith(".")) continue;
+    if (!isMediaFile(ent.name)) continue;
+    out.push(join(dir, ent.name));
+  }
+  return out;
+}
+
+function appendAggregateRow(dir, row) {
+  const p = join(dir, AGGREGATE_CSV);
+  const header = "file,verdict,status,flags,job_id,checked_at\n";
+  const line = [row.file, row.verdict, row.status, row.flags, row.jobId, row.checkedAt]
+    .map((v) => `"${String(v ?? "").replace(/"/g, '""')}"`).join(",") + "\n";
+  try {
+    if (!existsSync(p)) writeFileSync(p, header + line);
+    else writeFileSync(p, readFileSync(p, "utf8") + line);
+  } catch { /* best-effort */ }
+}
+
+// Run a user-supplied shell command after a verdict (--on-pass / --on-fail).
+// The file path is exposed to the command as $UPLOADCHECK_FILE (and the verdict as
+// $UPLOADCHECK_VERDICT), so `mv "$UPLOADCHECK_FILE" done/` style commands work.
+// Failures are logged, never fatal.
+function runHook(command, filePath, verdict) {
+  if (!command) return Promise.resolve();
+  return new Promise((resolve) => {
+    const child = spawn(command, {
+      shell: true,
+      stdio: "inherit",
+      env: { ...process.env, UPLOADCHECK_FILE: filePath, UPLOADCHECK_VERDICT: String(verdict || "") }
+    });
+    child.on("error", (e) => { console.error(`[watch] hook error: ${e.message}`); resolve(); });
+    child.on("exit", () => resolve());
+  });
+}
+
+async function processFile(filePath, { apiBaseUrl, apiKey, options, dir, ledger, nowIso }) {
+  const name = basename(filePath);
+  // Build the job exactly like `uploadcheck check` (inline vs signed-upload auto-switch).
+  // A deterministic idempotency key from the content key means a re-submit of the same
+  // bytes is a no-op server-side, even if the local ledger was wiped.
+  const stat = statSync(filePath);
+  const sourceKey = sourceKeyFor(dir, filePath, stat);
+  const request = buildJobRequest(filePath, { ...options, idempotencyKey: options.idempotencyKey || `watch-${sourceKey}` });
+
+  console.log(`[watch] submitting ${name} ...`);
+  const job = await submitJob(request, apiKey);
+  const jobId = job.jobId;
+  const finished = await pollJobUntilDone(apiBaseUrl, jobId, apiKey, {
+    intervalMs: Number(options.pollMs) || DEFAULT_POLL_MS,
+    onProgress: (j) => { if (j.progressPct != null && j.status !== "completed") process.stdout.write(`\r[watch] ${name}: ${j.status} ${j.progressPct}%   `); }
+  });
+  process.stdout.write("\r");
+
+  let report = null;
+  if (finished.status === "completed") {
+    report = await fetchReport(apiBaseUrl, jobId, apiKey);
+    writeFileSync(reportPathFor(filePath), JSON.stringify({ sourceKey, job: finished, report }, null, 2));
+    const csv = await fetchMarkerCsv(apiBaseUrl, jobId, apiKey);
+    if (csv) writeFileSync(markerPathFor(filePath), csv);
+  } else {
+    // Still record the terminal outcome so a failed job isn't retried forever.
+    writeFileSync(reportPathFor(filePath), JSON.stringify({ sourceKey, job: finished, report: null }, null, 2));
+  }
+
+  const verdict = (report && (report.verdict || report.summary?.verdict)) || finished.verdict || finished.status;
+  const flagCount = report ? (report.flags?.length ?? (report.summary?.blocked?.length || 0)) : 0;
+  appendAggregateRow(dir, { file: name, verdict, status: finished.status, flags: flagCount, jobId, checkedAt: nowIso });
+  ledger.done[sourceKey] = { file: name, jobId, verdict, status: finished.status, at: nowIso };
+  saveLedger(dir, ledger);
+
+  const verdictUpper = String(verdict).toUpperCase();
+  const passed = finished.status === "completed" && !verdictUpper.includes("BLOCK");
+  const mark = finished.status !== "completed" ? "⚠️" : (verdictUpper.includes("BLOCK") ? "❌ BLOCK" : (verdictUpper.includes("WATCH") ? "⚠️ WATCH" : "✅"));
+  console.log(`[watch] ${name}: ${mark} (${flagCount} flag${flagCount === 1 ? "" : "s"}) → ${basename(reportPathFor(filePath))}`);
+
+  // Pipeline glue: run --on-pass when nothing blocks (a clean PASS or WATCH), or
+  // --on-fail on a BLOCK / failed job. WATCH counts as a pass — it ships with notes.
+  if (passed && options.onPass) await runHook(options.onPass, filePath, verdict);
+  else if (!passed && options.onFail) await runHook(options.onFail, filePath, verdict);
+}
+
+// Run a list of files through processFile with bounded concurrency.
+async function runPool(files, concurrency, worker) {
+  const queue = [...files];
+  const runners = Array.from({ length: Math.max(1, concurrency) }, async () => {
+    for (;;) {
+      const next = queue.shift();
+      if (!next) return;
+      try { await worker(next); }
+      catch (err) { console.error(`[watch] ${basename(next)}: ${err.message}`); }
+    }
+  });
+  await Promise.all(runners);
+}
+
+export async function runWatch(target, options, apiKey) {
+  if (!target) throw new Error("Usage: uploadcheck watch <folder> [--once] [--concurrency N] [--settle-ms MS]");
+  const dir = resolve(target);
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) throw new Error(`Not a folder: ${dir}`);
+  if (!apiKey) throw new Error("Set UPLOADCHECK_API_KEY or pass --api-key.");
+
+  const apiBaseUrl = (options.apiBaseUrl || process.env.UPLOADCHECK_API_BASE_URL || "https://api.uploadcheck.app").replace(/\/+$/, "");
+  const concurrency = Number(options.concurrency) || DEFAULT_CONCURRENCY;
+  const settleMs = Number(options.settleMs) || DEFAULT_SETTLE_MS;
+  const ledger = loadLedger(dir);
+  const seen = new Map();   // filePath -> last {size, mtimeMs} for stable-write gating
+  const inFlight = new Set();
+
+  const alreadyDone = (filePath) => {
+    if (existsSync(reportPathFor(filePath))) return true; // report next to source = done
+    try {
+      const key = sourceKeyFor(dir, filePath, statSync(filePath));
+      return Boolean(ledger.done[key]);
+    } catch { return false; }
+  };
+
+  const nowIso = () => new Date().toISOString();
+
+  async function sweep() {
+    const candidates = discoverCandidates(dir).filter((f) => !inFlight.has(f) && !alreadyDone(f));
+    const ready = [];
+    for (const f of candidates) {
+      let stat;
+      try { stat = statSync(f); } catch { continue; }
+      if (isSettled(f, stat, seen, settleMs)) ready.push(f);
+    }
+    if (!ready.length) return;
+    ready.forEach((f) => inFlight.add(f));
+    await runPool(ready, concurrency, (f) =>
+      processFile(f, { apiBaseUrl, apiKey, options, dir, ledger, nowIso: nowIso() }).finally(() => inFlight.delete(f))
+    );
+  }
+
+  if (options.once) {
+    console.log(`[watch] one-shot scan of ${dir}`);
+    // In --once mode files are already on disk and settled — submit immediately.
+    const ready = discoverCandidates(dir).filter((f) => !alreadyDone(f));
+    if (!ready.length) { console.log("[watch] nothing new to scan."); return; }
+    ready.forEach((f) => inFlight.add(f));
+    await runPool(ready, concurrency, (f) => processFile(f, { apiBaseUrl, apiKey, options, dir, ledger, nowIso: nowIso() }));
+    console.log(`[watch] done — ${ready.length} file(s) scanned. Aggregate: ${join(dir, AGGREGATE_CSV)}`);
+    return;
+  }
+
+  console.log(`[watch] watching ${dir} (concurrency ${concurrency}, settle ${settleMs}ms). Drop media files in; Ctrl-C to stop.`);
+  let watcher = null;
+  try { watcher = fsWatch(dir, { persistent: true }, () => {}); } catch { /* sweep still covers it */ }
+  let stopped = false;
+  process.on("SIGINT", () => { stopped = true; if (watcher) watcher.close(); console.log("\n[watch] stopping."); process.exit(0); });
+
+  await sweep(); // catch backlog first
+  while (!stopped) {
+    await sleep(SWEEP_INTERVAL_MS);
+    await sweep();
+  }
+}