feat: add deterministic cleared project media

2026-09-02 06:38:40 +03:00
parent eb672bd664
commit dfd56f0a48
11 changed files with 2954 additions and 0 deletions
--- a/scripts/lib/asset-recipes.mjs
+++ b/scripts/lib/asset-recipes.mjs
@@ -0,0 +1,91 @@
+import { readFile, realpath, stat } from 'node:fs/promises';
+import { basename, extname, isAbsolute, relative, resolve, sep } from 'node:path';
+
+const idPattern = /^[a-z][a-z0-9-]{0,63}$/u;
+const outputPattern = /^project-[a-z0-9][a-z0-9-]*\.(webp|png|webm)$/u;
+
+const fail = (rule) => { throw new Error(rule); };
+
+const exactKeys = (record, allowed, rule) => {
+  if (Object.keys(record).some((key) => !allowed.includes(key))) fail(rule);
+};
+
+export const readJson = async (path, rule = 'ASSET-JSON-001') => {
+  try {
+    return JSON.parse(await readFile(path, 'utf8'));
+  } catch {
+    fail(rule);
+  }
+};
+
+export const loadRecipes = async (path) => {
+  const input = await readJson(path, 'ASSET-RECIPE-001');
+  if (!input || typeof input !== 'object' || input.schema !== 'portfolio-asset-recipes/v1' || !Array.isArray(input.assets)) {
+    fail('ASSET-RECIPE-001');
+  }
+  exactKeys(input, ['schema', 'assets'], 'ASSET-RECIPE-001');
+  const seenIds = new Set();
+  const seenOutputs = new Set();
+  const assets = input.assets.map((asset) => {
+    if (!asset || typeof asset !== 'object') fail('ASSET-RECIPE-001');
+    exactKeys(asset, [
+      'id', 'kind', 'output', 'maxWidth', 'startSeconds', 'durationSeconds',
+      'rightsHolder', 'license', 'attribution',
+    ], 'ASSET-RECIPE-001');
+    if (!idPattern.test(asset.id) || !['image', 'video'].includes(asset.kind) || !outputPattern.test(asset.output)) {
+      fail('ASSET-RECIPE-001');
+    }
+    if (asset.kind === 'image' && !/\.(webp|png)$/u.test(asset.output)) fail('ASSET-RECIPE-001');
+    if (asset.kind === 'video' && !asset.output.endsWith('.webm')) fail('ASSET-RECIPE-001');
+    if (!Number.isInteger(asset.maxWidth) || asset.maxWidth < 64 || asset.maxWidth > 4096) fail('ASSET-RECIPE-001');
+    if (asset.kind === 'video' && (
+      typeof asset.startSeconds !== 'number' || asset.startSeconds < 0 ||
+      typeof asset.durationSeconds !== 'number' || asset.durationSeconds <= 0 || asset.durationSeconds > 30
+    )) fail('ASSET-RECIPE-001');
+    for (const field of ['rightsHolder', 'license', 'attribution']) {
+      if (typeof asset[field] !== 'string' || asset[field].trim().length === 0 || /[\u0000-\u001f\u007f]/u.test(asset[field])) {
+        fail('ASSET-RECIPE-001');
+      }
+    }
+    if (seenIds.has(asset.id) || seenOutputs.has(asset.output.toLowerCase())) fail('ASSET-RECIPE-002');
+    seenIds.add(asset.id);
+    seenOutputs.add(asset.output.toLowerCase());
+    return Object.freeze({ ...asset });
+  });
+  return Object.freeze(assets);
+};
+
+export const loadPrivateMapping = async (path, recipes) => {
+  const input = await readJson(path, 'ASSET-MAPPING-001');
+  if (!input || typeof input !== 'object' || input.schema !== 'portfolio-private-source-map/v1' ||
+    !input.sources || typeof input.sources !== 'object' || Array.isArray(input.sources)) fail('ASSET-MAPPING-001');
+  exactKeys(input, ['schema', 'sources'], 'ASSET-MAPPING-001');
+  const ids = recipes.map(({ id }) => id).sort();
+  if (JSON.stringify(Object.keys(input.sources).sort()) !== JSON.stringify(ids)) fail('ASSET-MAPPING-002');
+  for (const value of Object.values(input.sources)) {
+    if (typeof value !== 'string' || value.length === 0 || isAbsolute(value) || value.includes('\\') ||
+      value.split('/').some((part) => part === '' || part === '.' || part === '..')) fail('ASSET-MAPPING-001');
+  }
+  return input.sources;
+};
+
+export const resolvePrivateSource = async (sourceRoot, mappedPath) => {
+  const root = await realpath(sourceRoot);
+  const candidate = resolve(root, mappedPath);
+  const rel = relative(root, candidate);
+  if (!rel || rel.startsWith(`..${sep}`) || rel === '..' || isAbsolute(rel)) fail('ASSET-SOURCE-001');
+  let resolved;
+  try {
+    resolved = await realpath(candidate);
+  } catch {
+    fail('ASSET-SOURCE-001');
+  }
+  const resolvedRel = relative(root, resolved);
+  if (resolvedRel.startsWith(`..${sep}`) || resolvedRel === '..' || isAbsolute(resolvedRel)) fail('ASSET-SOURCE-001');
+  const info = await stat(resolved);
+  if (!info.isFile() || info.size <= 0 || info.size > 100 * 1024 * 1024) fail('ASSET-SOURCE-002');
+  return resolved;
+};
+
+export const publicFileNameFor = (recipe) => basename(recipe.output);
+export const publicExtensionFor = (recipe) => extname(recipe.output).slice(1);
--- a/scripts/lib/hash-file.mjs
+++ b/scripts/lib/hash-file.mjs
@@ -0,0 +1,10 @@
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+
+export const hashFile = async (path) => new Promise((resolve, reject) => {
+  const digest = createHash('sha256');
+  const stream = createReadStream(path);
+  stream.on('error', reject);
+  stream.on('data', (chunk) => digest.update(chunk));
+  stream.on('end', () => resolve(digest.digest('hex')));
+});
--- a/scripts/lib/privacy-scan.mjs
+++ b/scripts/lib/privacy-scan.mjs
@@ -0,0 +1,118 @@
+import { access, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import sharp from 'sharp';
+import { fileTypeFromFile } from 'file-type';
+import { createWorker, OEM } from 'tesseract.js';
+import {
+  BinaryBitmap,
+  HybridBinarizer,
+  MultiFormatReader,
+  NotFoundException,
+  RGBLuminanceSource,
+} from '@zxing/library';
+
+const normalize = (value) => value.normalize('NFKC').toLocaleLowerCase('en-US');
+const fail = (rule, location = '') => { throw new Error(location ? `${rule}:${location}` : rule); };
+
+export const loadDenylist = async (path) => {
+  let text;
+  try {
+    text = await readFile(path, 'utf8');
+  } catch {
+    fail('PRIVACY-DENYLIST-001');
+  }
+  const terms = [...new Set(text.split(/\r?\n/u).map((line) => line.trim()).filter(Boolean).map(normalize))];
+  if (terms.length === 0 || terms.some((term) => term.length < 3 || /[\u0000-\u001f\u007f]/u.test(term))) {
+    fail('PRIVACY-DENYLIST-001');
+  }
+  return terms;
+};
+
+export const scanText = (bytesOrText, denylist, rule = 'PRIVACY-BYTES-001') => {
+  const text = normalize(Buffer.isBuffer(bytesOrText) || bytesOrText instanceof Uint8Array
+    ? Buffer.from(bytesOrText).toString('utf8')
+    : String(bytesOrText));
+  if (denylist.some((term) => text.includes(normalize(term)))) fail(rule);
+};
+
+const scanBarcode = async (path) => {
+  let decoded;
+  try {
+    decoded = await sharp(path).removeAlpha().greyscale().raw().toBuffer({ resolveWithObject: true });
+  } catch {
+    fail('ASSET-DECODE-001');
+  }
+  const { data, info } = decoded;
+  const luminance = new RGBLuminanceSource(new Uint8ClampedArray(data), info.width, info.height);
+  const bitmap = new BinaryBitmap(new HybridBinarizer(luminance));
+  try {
+    new MultiFormatReader().decode(bitmap);
+    fail('PRIVACY-BARCODE-001');
+  } catch (error) {
+    if (error instanceof NotFoundException || error?.name === 'NotFoundException') return;
+    if (error instanceof Error && error.message === 'PRIVACY-BARCODE-001') throw error;
+    fail('PRIVACY-BARCODE-002');
+  }
+};
+
+const scanOcr = async (path, denylist) => {
+  const candidates = ['/usr/share/tessdata', '/usr/share/tesseract-ocr/5/tessdata'];
+  let langPath;
+  for (const candidate of candidates) {
+    try {
+      await access(join(candidate, 'eng.traineddata'));
+      langPath = candidate;
+      break;
+    } catch {}
+  }
+  if (!langPath) fail('PRIVACY-OCR-002');
+  let worker;
+  try {
+    worker = await createWorker('eng', OEM.LSTM_ONLY, { langPath, gzip: false, cacheMethod: 'none' });
+  } catch {
+    fail('PRIVACY-OCR-002');
+  }
+  let timer;
+  try {
+    const result = await Promise.race([
+      worker.recognize(path),
+      new Promise((_, reject) => { timer = setTimeout(() => reject(new Error('timeout')), 25_000); }),
+    ]);
+    scanText(result.data.text, denylist, 'PRIVACY-OCR-001');
+  } catch (error) {
+    if (error instanceof Error && error.message === 'PRIVACY-OCR-001') throw error;
+    fail('PRIVACY-OCR-002');
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+    await worker.terminate().catch(() => {});
+  }
+};
+
+export const scanImage = async (path, denylist, options = {}) => {
+  let type;
+  try { type = await fileTypeFromFile(path); } catch { fail('PRIVACY-TYPE-001'); }
+  if (!type || !['image/png', 'image/webp', 'image/jpeg'].includes(type.mime)) fail('PRIVACY-TYPE-001');
+  let metadata;
+  try {
+    metadata = await sharp(path, { failOn: 'error', limitInputPixels: 50_000_000 }).metadata();
+  } catch {
+    fail('ASSET-DECODE-001');
+  }
+  if (metadata.exif || metadata.icc || metadata.iptc || metadata.xmp || metadata.orientation !== undefined) {
+    fail('PRIVACY-METADATA-001');
+  }
+  scanText(await readFile(path), denylist);
+  await scanBarcode(path);
+  if (options.runOcr !== false) await scanOcr(path, denylist);
+  return { width: metadata.width, height: metadata.height, mediaType: type.mime };
+};
+
+export const scanBinary = async (path, denylist) => {
+  let bytes;
+  try { bytes = await readFile(path); } catch { fail('PRIVACY-TYPE-001'); }
+  scanText(bytes, denylist);
+  let type;
+  try { type = await fileTypeFromFile(path); } catch { fail('PRIVACY-TYPE-001'); }
+  if (!type || !['video/webm', 'video/mp4'].includes(type.mime)) fail('PRIVACY-TYPE-001');
+  return { mediaType: type.mime };
+};
--- a/scripts/lib/video-frames.mjs
+++ b/scripts/lib/video-frames.mjs
@@ -0,0 +1,74 @@
+import { execFile } from 'node:child_process';
+import { mkdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+const fail = (rule) => { throw new Error(rule); };
+
+export const runMediaCommand = async (command, args, rule, timeout = 60_000) => {
+  try {
+    return await execFileAsync(command, args, {
+      encoding: 'utf8', timeout, maxBuffer: 8 * 1024 * 1024, windowsHide: true,
+    });
+  } catch {
+    fail(rule);
+  }
+};
+
+export const probeVideo = async (path, options = {}) => {
+  const { stdout } = await runMediaCommand('ffprobe', [
+    '-v', 'error', '-show_entries', 'format=duration:stream=index,codec_type,width,height,duration',
+    '-of', 'json', path,
+  ], 'ASSET-VIDEO-PROBE-001', 20_000);
+  let probe;
+  try { probe = JSON.parse(stdout); } catch { fail('ASSET-VIDEO-PROBE-001'); }
+  const videoStreams = probe.streams?.filter((stream) => stream.codec_type === 'video') ?? [];
+  const audioStreams = probe.streams?.filter((stream) => stream.codec_type === 'audio') ?? [];
+  const unexpected = probe.streams?.filter((stream) => !['video', 'audio'].includes(stream.codec_type)) ?? [];
+  const duration = Number(probe.format?.duration ?? videoStreams[0]?.duration);
+  if (videoStreams.length !== 1 || unexpected.length > 0 || (options.allowAudio === false && audioStreams.length > 0) ||
+    !Number.isFinite(duration) || duration <= 0 || duration > 120) {
+    fail('ASSET-VIDEO-PROBE-001');
+  }
+  return { duration, width: Number(videoStreams[0].width), height: Number(videoStreams[0].height) };
+};
+
+export const encodeVideoDerivatives = async ({ source, webmPath, mp4Path, posterPath, startSeconds, durationSeconds, maxWidth }) => {
+  const common = [
+    '-hide_banner', '-loglevel', 'error', '-nostdin', '-y', '-threads', '1',
+    '-ss', String(startSeconds), '-i', source, '-t', String(durationSeconds), '-map', '0:v:0',
+    '-an', '-sn', '-dn', '-vf', `scale=w='min(${maxWidth},iw)':h=-2:flags=lanczos`,
+    '-map_metadata', '-1', '-map_chapters', '-1', '-pix_fmt', 'yuv420p',
+  ];
+  await runMediaCommand('ffmpeg', [
+    ...common, '-fflags', '+bitexact', '-flags:v', '+bitexact',
+    '-c:v', 'libvpx-vp9', '-deadline', 'good', '-cpu-used', '4', '-row-mt', '0',
+    '-b:v', '0', '-crf', '34', '-threads', '1', webmPath,
+  ], 'ASSET-VIDEO-ENCODE-001', 120_000);
+  await runMediaCommand('ffmpeg', [
+    ...common, '-fflags', '+bitexact', '-flags:v', '+bitexact',
+    '-c:v', 'libx264', '-preset', 'slow', '-crf', '25', '-threads', '1',
+    '-movflags', '+faststart', mp4Path,
+  ], 'ASSET-VIDEO-ENCODE-001', 120_000);
+  await runMediaCommand('ffmpeg', [
+    '-hide_banner', '-loglevel', 'error', '-nostdin', '-y', '-threads', '1',
+    '-ss', '0.05', '-i', webmPath, '-frames:v', '1', '-an', '-sn', '-dn', '-map_metadata', '-1', posterPath,
+  ], 'ASSET-VIDEO-POSTER-001', 30_000);
+};
+
+export const extractVideoFrames = async ({ source, durationSeconds, outputDir, prefix = 'frame' }) => {
+  await mkdir(outputDir, { recursive: true });
+  const points = [...new Set([0.05, durationSeconds / 2, Math.max(0.05, durationSeconds - 0.1)].map((value) => Math.min(durationSeconds, Math.max(0, value)).toFixed(3)))];
+  const paths = [];
+  for (const [index, point] of points.entries()) {
+    const path = join(outputDir, `${prefix}-${String(index + 1).padStart(2, '0')}.png`);
+    await runMediaCommand('ffmpeg', [
+      '-hide_banner', '-loglevel', 'error', '-nostdin', '-y', '-threads', '1',
+      '-ss', point, '-i', source, '-frames:v', '1', '-an', '-sn', '-dn', '-map_metadata', '-1', path,
+    ], 'ASSET-VIDEO-FRAME-001', 30_000);
+    if ((await readFile(path)).length === 0) fail('ASSET-VIDEO-FRAME-001');
+    paths.push(path);
+  }
+  return paths;
+};
--- a/scripts/prepare-assets.mjs
+++ b/scripts/prepare-assets.mjs
@@ -0,0 +1,265 @@
+#!/usr/bin/env node
+import { copyFile, mkdir, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises';
+import { basename, dirname, extname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import sharp from 'sharp';
+import { fileTypeFromFile } from 'file-type';
+
+import { hashFile } from './lib/hash-file.mjs';
+import { loadPrivateMapping, loadRecipes, readJson, resolvePrivateSource } from './lib/asset-recipes.mjs';
+import { loadDenylist, scanBinary, scanImage } from './lib/privacy-scan.mjs';
+import { encodeVideoDerivatives, extractVideoFrames, probeVideo } from './lib/video-frames.mjs';
+
+const repositoryRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const fail = (rule) => { throw new Error(rule); };
+
+const assertSafeOutputRoot = (path, rule) => {
+  const resolved = resolve(path);
+  const permittedRepositoryOutput = join(repositoryRoot, 'inputs', 'prepared-assets');
+  if (resolved !== permittedRepositoryOutput && !resolved.startsWith('/tmp/')) fail(rule);
+  return resolved;
+};
+
+const resetDirectory = async (path, rule) => {
+  const safe = assertSafeOutputRoot(path, rule);
+  await rm(safe, { recursive: true, force: true });
+  await mkdir(safe, { recursive: true });
+  return safe;
+};
+
+const sorted = (items) => [...items].sort((left, right) => left.fileName.localeCompare(right.fileName, 'en-US'));
+
+const candidate = async ({ id, fileName, path, mediaType, width, height, durationMs, recipe }) => ({
+  id,
+  fileName,
+  sha256: await hashFile(path),
+  mediaType,
+  width,
+  height,
+  durationMs,
+  rightsHolder: recipe.rightsHolder,
+  license: recipe.license,
+  attribution: recipe.attribution,
+});
+
+const encodeImage = async (source, output, recipe) => {
+  let detected;
+  try { detected = await fileTypeFromFile(source); } catch { fail('ASSET-TYPE-001'); }
+  if (!detected || !['image/jpeg', 'image/png', 'image/webp'].includes(detected.mime)) fail('ASSET-TYPE-001');
+  try {
+    let pipeline = sharp(source, { failOn: 'error', limitInputPixels: 50_000_000, sequentialRead: true })
+      .rotate()
+      .resize({ width: recipe.maxWidth, withoutEnlargement: true, fit: 'inside', kernel: sharp.kernel.lanczos3 });
+    pipeline = recipe.output.endsWith('.png')
+      ? pipeline.png({ compressionLevel: 9, adaptiveFiltering: false, palette: false })
+      : pipeline.webp({ lossless: true, effort: 6, smartSubsample: false });
+    await pipeline.toFile(output);
+  } catch {
+    fail('ASSET-DECODE-001');
+  }
+  const details = await scanImage(output, [], { runOcr: false });
+  return details;
+};
+
+const prepareImage = async ({ source, recipe, stagingRoot, denylist }) => {
+  const path = join(stagingRoot, recipe.output);
+  const details = await encodeImage(source, path, recipe);
+  await scanImage(path, denylist, { runOcr: true });
+  return [await candidate({
+    id: recipe.id, fileName: recipe.output, path, mediaType: details.mediaType,
+    width: details.width, height: details.height, durationMs: null, recipe,
+  })];
+};
+
+const prepareVideo = async ({ source, recipe, stagingRoot, reportDir, denylist }) => {
+  const sourceProbe = await probeVideo(source);
+  if (recipe.startSeconds + recipe.durationSeconds > sourceProbe.duration + 0.05) fail('ASSET-VIDEO-RANGE-001');
+  const base = recipe.output.slice(0, -'.webm'.length);
+  const webmPath = join(stagingRoot, `${base}.webm`);
+  const mp4Path = join(stagingRoot, `${base}.mp4`);
+  const posterPath = join(stagingRoot, `${base}-poster.webp`);
+  await encodeVideoDerivatives({
+    source, webmPath, mp4Path, posterPath,
+    startSeconds: recipe.startSeconds, durationSeconds: recipe.durationSeconds, maxWidth: recipe.maxWidth,
+  });
+  const webmProbe = await probeVideo(webmPath, { allowAudio: false });
+  const mp4Probe = await probeVideo(mp4Path, { allowAudio: false });
+  const frames = await extractVideoFrames({
+    source: webmPath,
+    durationSeconds: Math.min(webmProbe.duration, recipe.durationSeconds),
+    outputDir: join(reportDir, 'video-frames'),
+    prefix: recipe.id,
+  });
+  await scanBinary(webmPath, denylist);
+  await scanBinary(mp4Path, denylist);
+  await scanImage(posterPath, denylist, { runOcr: true });
+  for (const frame of frames) await scanImage(frame, denylist, { runOcr: true });
+  const poster = await sharp(posterPath).metadata();
+  return [
+    await candidate({
+      id: recipe.id, fileName: `${base}.webm`, path: webmPath, mediaType: 'video/webm',
+      width: webmProbe.width, height: webmProbe.height, durationMs: Math.round(webmProbe.duration * 1000), recipe,
+    }),
+    await candidate({
+      id: `${recipe.id}-mp4`, fileName: `${base}.mp4`, path: mp4Path, mediaType: 'video/mp4',
+      width: mp4Probe.width, height: mp4Probe.height, durationMs: Math.round(mp4Probe.duration * 1000), recipe,
+    }),
+    await candidate({
+      id: `${recipe.id}-poster`, fileName: `${base}-poster.webp`, path: posterPath, mediaType: 'image/webp',
+      width: poster.width, height: poster.height, durationMs: null, recipe,
+    }),
+  ];
+};
+
+const createContactSheet = async (candidates, stagingRoot, reportDir) => {
+  const images = candidates.filter(({ mediaType }) => mediaType.startsWith('image/')).map((image) => ({
+    id: image.id,
+    path: join(stagingRoot, image.fileName),
+  }));
+  let frameNames = [];
+  try { frameNames = (await readdir(join(reportDir, 'video-frames'))).filter((name) => name.endsWith('.png')).sort(); } catch {}
+  images.push(...frameNames.map((name, index) => ({
+    id: `private-game-loop-frame-${String(index + 1).padStart(2, '0')}`,
+    path: join(reportDir, 'video-frames', name),
+  })));
+  if (images.length === 0) return;
+  const imageWidth = 1100;
+  const width = 1200;
+  const composites = [];
+  let y = 30;
+  for (const image of images) {
+    const thumb = await sharp(image.path)
+      .resize({ width: imageWidth, height: 1400, fit: 'inside', withoutEnlargement: false })
+      .png()
+      .toBuffer();
+    const metadata = await sharp(thumb).metadata();
+    const left = Math.round((width - (metadata.width ?? imageWidth)) / 2);
+    composites.push({ input: thumb, left, top: y });
+    const safeLabel = image.id.replace(/[^a-z0-9-]/gu, '');
+    const label = Buffer.from(`<svg width="1100" height="54" xmlns="http://www.w3.org/2000/svg"><rect width="1100" height="54" fill="#11131a"/><text x="16" y="36" font-size="24" font-family="sans-serif" fill="#f4f2f7">${safeLabel}</text></svg>`);
+    y += metadata.height ?? 0;
+    composites.push({ input: label, left: 50, top: y + 8 });
+    y += 86;
+  }
+  await sharp({ create: { width, height: y + 20, channels: 3, background: '#070910' } })
+    .composite(composites)
+    .webp({ lossless: true, effort: 6 })
+    .toFile(join(reportDir, 'contact-sheet.webp'));
+};
+
+const approvalProjection = (recipes, candidates) => ({
+  schema: 'portfolio-asset-approvals/v1',
+  assets: recipes.map(({ id }) => ({
+    id,
+    files: sorted(candidates.filter((item) => item.id === id || item.id.startsWith(`${id}-`)))
+      .map(({ fileName, sha256 }) => ({ fileName, sha256 })),
+  })).sort((left, right) => left.id.localeCompare(right.id, 'en-US')),
+});
+
+const approvalsMatch = async (path, expected) => {
+  const actual = await readJson(path, 'ASSET-APPROVAL-001');
+  if (JSON.stringify(actual) !== JSON.stringify(expected)) fail('ASSET-APPROVAL-002');
+};
+
+const publish = async ({ candidates, stagingRoot, publishRoot, manifestPath }) => {
+  if (candidates.some((item) => /pending|requires confirmation/iu.test(`${item.rightsHolder} ${item.license}`))) {
+    fail('ASSET-RIGHTS-001');
+  }
+  const safePublishRoot = await resetDirectory(publishRoot, 'ASSET-PUBLISH-001');
+  for (const item of candidates) await copyFile(join(stagingRoot, item.fileName), join(safePublishRoot, item.fileName));
+  await mkdir(dirname(manifestPath), { recursive: true });
+  await writeFile(manifestPath, `${JSON.stringify({ assets: candidates }, null, 2)}\n`, 'utf8');
+};
+
+export const prepareAssets = async (options) => {
+  const required = ['sourceRoot', 'mappingPath', 'denylistPath', 'recipesPath', 'stagingRoot', 'reportDir'];
+  if (!options || required.some((key) => typeof options[key] !== 'string')) fail('ASSET-ARGUMENT-001');
+  const recipes = await loadRecipes(options.recipesPath);
+  const mapping = await loadPrivateMapping(options.mappingPath, recipes);
+  const denylist = await loadDenylist(options.denylistPath);
+  const stagingRoot = await resetDirectory(options.stagingRoot, 'ASSET-STAGING-001');
+  const reportDir = await resetDirectory(options.reportDir, 'ASSET-REPORT-001');
+  const candidates = [];
+  for (const recipe of recipes) {
+    const source = await resolvePrivateSource(options.sourceRoot, mapping[recipe.id]);
+    const prepared = recipe.kind === 'image'
+      ? await prepareImage({ source, recipe, stagingRoot, denylist })
+      : await prepareVideo({ source, recipe, stagingRoot, reportDir, denylist });
+    candidates.push(...prepared);
+  }
+  const finalCandidates = sorted(candidates);
+  const approval = approvalProjection(recipes, finalCandidates);
+  await writeFile(join(reportDir, 'candidate-approval.json'), `${JSON.stringify(approval, null, 2)}\n`, 'utf8');
+  await writeFile(join(reportDir, 'scan-report.json'), `${JSON.stringify({
+    schema: 'portfolio-private-scan-report/v1', automatedChecks: 'passed', publication: 'pending-manual-approval',
+    assets: finalCandidates.map(({ id, fileName, sha256 }) => ({ id, fileName, sha256 })),
+  }, null, 2)}\n`, 'utf8');
+  await createContactSheet(finalCandidates, stagingRoot, reportDir);
+  let approvalStatus = 'pending';
+  if (options.approvalRegisterPath !== undefined) {
+    if (typeof options.publishRoot !== 'string' || typeof options.manifestPath !== 'string') fail('ASSET-ARGUMENT-001');
+    await approvalsMatch(options.approvalRegisterPath, approval);
+    await publish({ candidates: finalCandidates, stagingRoot, publishRoot: options.publishRoot, manifestPath: options.manifestPath });
+    approvalStatus = 'approved';
+  }
+  return { candidates: finalCandidates, approvalStatus, reportDir };
+};
+
+export const verifyPreparedAssets = async ({ publishRoot, manifestPath, denylistPath }) => {
+  if (![publishRoot, manifestPath, denylistPath].every((value) => typeof value === 'string')) fail('ASSET-ARGUMENT-001');
+  const manifest = await readJson(manifestPath, 'ASSET-MANIFEST-001');
+  if (!manifest || typeof manifest !== 'object' || !Array.isArray(manifest.assets)) fail('ASSET-MANIFEST-001');
+  const expected = manifest.assets.map(({ fileName }) => fileName).sort();
+  const actual = (await readdir(publishRoot, { withFileTypes: true }))
+    .map((entry) => {
+      if (!entry.isFile()) fail('ASSET-EXACT-001');
+      return entry.name;
+    }).sort();
+  if (JSON.stringify(actual) !== JSON.stringify(expected)) fail('ASSET-EXACT-001');
+  const denylist = await loadDenylist(denylistPath);
+  for (const item of manifest.assets) {
+    if (!item || typeof item.fileName !== 'string' || !/^project-[a-z0-9-]+\.(webp|png|webm|mp4)$/u.test(item.fileName)) fail('ASSET-MANIFEST-001');
+    const path = join(publishRoot, item.fileName);
+    if ((await stat(path)).nlink !== 1) fail('ASSET-EXACT-001');
+    if (await hashFile(path) !== item.sha256) fail('ASSET-HASH-001');
+    if (item.mediaType.startsWith('image/')) await scanImage(path, denylist, { runOcr: true });
+    else await scanBinary(path, denylist);
+  }
+  return true;
+};
+
+const parseArgs = (argv) => {
+  const values = {};
+  let verify = false;
+  for (let index = 0; index < argv.length; index += 1) {
+    const key = argv[index];
+    if (key === '--verify') { verify = true; continue; }
+    if (!key?.startsWith('--') || index + 1 >= argv.length) fail('ASSET-ARGUMENT-001');
+    values[key.slice(2)] = argv[index + 1];
+    index += 1;
+  }
+  return { verify, values };
+};
+
+const runCli = async () => {
+  const { verify, values } = parseArgs(process.argv.slice(2));
+  if (verify) {
+    await verifyPreparedAssets({ publishRoot: values['publish-root'], manifestPath: values.manifest, denylistPath: values.denylist });
+    return;
+  }
+  await prepareAssets({
+    sourceRoot: values['source-root'], mappingPath: values.mapping, denylistPath: values.denylist,
+    recipesPath: values.recipes, stagingRoot: values['staging-root'], reportDir: values['report-dir'],
+    approvalRegisterPath: values.approvals, publishRoot: values['publish-root'], manifestPath: values.manifest,
+  });
+};
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  runCli().catch((error) => {
+    const message = error instanceof Error && /^[A-Z]+(?:-[A-Z]+)*-\d{3}(?::[a-z0-9-]+)?$/u.test(error.message)
+      ? error.message
+      : 'ASSET-UNEXPECTED-001';
+    process.stderr.write(`${message}\n`);
+    process.exitCode = 1;
+  });
+}