@inneranimalmedia/agentsam-sdk 2.6.4 → 2.6.7

package/packages/agentsam-brand/src/core/capabilities.js

@@ -0,0 +1,201 @@
+/**
+ * Format capability map (BrandPack v2) — by format + by family.
+ * Open-set: new formats = code edit, not migration.
+ *
+ * DERIVABLE = system knows how to make it
+ * MATERIALIZED = file is included in this pack export
+ */
+
+/** Per-extension capabilities */
+export const FORMAT_CAPABILITIES = Object.freeze({
+  // Raster
+  png: { family: 'raster', resize_ladder: true, poster_frame: false, recolorable: false, transparency: true, ingest: true, edit: true },
+  jpg: { family: 'raster', resize_ladder: true, poster_frame: false, recolorable: false, transparency: false, ingest: true, edit: true },
+  jpeg: { family: 'raster', resize_ladder: true, poster_frame: false, recolorable: false, transparency: false, ingest: true, edit: true },
+  webp: { family: 'raster', resize_ladder: true, poster_frame: false, recolorable: false, transparency: true, ingest: true, edit: true },
+  avif: { family: 'raster', resize_ladder: true, poster_frame: false, recolorable: false, transparency: true, ingest: true, edit: true },
+  gif: { family: 'raster', resize_ladder: true, poster_frame: false, recolorable: false, transparency: true, ingest: true, edit: true, animated: true },
+  apng: { family: 'raster', resize_ladder: false, poster_frame: false, recolorable: false, transparency: true, ingest: true, edit: false, animated: true },
+  tiff: { family: 'raster', resize_ladder: true, poster_frame: false, recolorable: false, transparency: true, ingest: true, edit: true },
+  tif: { family: 'raster', resize_ladder: true, poster_frame: false, recolorable: false, transparency: true, ingest: true, edit: true },
+  heic: { family: 'raster', resize_ladder: true, poster_frame: false, recolorable: false, transparency: false, ingest: true, edit: false },
+  heif: { family: 'raster', resize_ladder: true, poster_frame: false, recolorable: false, transparency: false, ingest: true, edit: false },
+
+  // Vector / print ingest (preserve; limited edit)
+  svg: { family: 'vector', resize_ladder: false, poster_frame: false, recolorable: true, ingest: true, edit: true },
+  pdf: { family: 'vector', resize_ladder: false, poster_frame: false, recolorable: false, ingest: true, edit: false, preserve: true },
+  eps: { family: 'vector', resize_ladder: false, poster_frame: false, recolorable: false, ingest: true, edit: false, preserve: true },
+  ai: { family: 'vector', resize_ladder: false, poster_frame: false, recolorable: false, ingest: true, edit: false, preserve: true },
+
+  // Platform icons
+  ico: { family: 'platform', resize_ladder: false, poster_frame: false, recolorable: false, platform: true, ingest: true, edit: false },
+  icns: { family: 'platform', resize_ladder: false, poster_frame: false, recolorable: false, platform: true, ingest: true, edit: false },
+
+  // Video
+  mp4: { family: 'video', resize_ladder: false, poster_frame: true, recolorable: false, ingest: true, edit: false },
+  mov: { family: 'video', resize_ladder: false, poster_frame: true, recolorable: false, ingest: true, edit: false },
+  webm: { family: 'video', resize_ladder: false, poster_frame: true, recolorable: false, ingest: true, edit: false },
+  mkv: { family: 'video', resize_ladder: false, poster_frame: true, recolorable: false, ingest: true, edit: false, preserve: true },
+
+  // Motion graphics
+  lottie: { family: 'motion-graphics', resize_ladder: false, poster_frame: false, recolorable: false, ingest: true, edit: false, ext_alias: 'json' },
+  riv: { family: 'motion-graphics', resize_ladder: false, poster_frame: false, recolorable: false, ingest: true, edit: false },
+
+  // 3D
+  glb: { family: 'model', resize_ladder: false, poster_frame: false, recolorable: false, ingest: true, edit: false },
+  gltf: { family: 'model', resize_ladder: false, poster_frame: false, recolorable: false, ingest: true, edit: false },
+  usdz: { family: 'model', resize_ladder: false, poster_frame: false, recolorable: false, ingest: true, edit: false },
+  obj: { family: 'model', resize_ladder: false, poster_frame: false, recolorable: false, ingest: true, edit: false, preserve: true },
+  fbx: { family: 'model', resize_ladder: false, poster_frame: false, recolorable: false, ingest: true, edit: false, preserve: true },
+
+  // Textures
+  ktx2: { family: 'texture', resize_ladder: false, poster_frame: false, recolorable: false, ingest: true, edit: false },
+
+  // Fonts — licensing gate required before redistribute
+  otf: { family: 'font', resize_ladder: false, poster_frame: false, recolorable: false, ingest: true, edit: false, licensing_required: true },
+  ttf: { family: 'font', resize_ladder: false, poster_frame: false, recolorable: false, ingest: true, edit: false, licensing_required: true },
+  woff: { family: 'font', resize_ladder: false, poster_frame: false, recolorable: false, ingest: true, edit: false, licensing_required: true },
+  woff2: { family: 'font', resize_ladder: false, poster_frame: false, recolorable: false, ingest: true, edit: false, licensing_required: true },
+
+  // Tokens / theme / docs / code
+  json: { family: 'tokens', resize_ladder: false, poster_frame: false, recolorable: false, ingest: true, edit: true },
+  yaml: { family: 'tokens', resize_ladder: false, poster_frame: false, recolorable: false, ingest: true, edit: true },
+  yml: { family: 'tokens', resize_ladder: false, poster_frame: false, recolorable: false, ingest: true, edit: true },
+  css: { family: 'theme', resize_ladder: false, poster_frame: false, recolorable: false, ingest: true, edit: true },
+  scss: { family: 'theme', resize_ladder: false, poster_frame: false, recolorable: false, ingest: true, edit: true },
+  md: { family: 'docs', resize_ladder: false, poster_frame: false, recolorable: false, ingest: true, edit: true },
+  markdown: { family: 'docs', resize_ladder: false, poster_frame: false, recolorable: false, ingest: true, edit: true },
+  html: { family: 'docs', resize_ladder: false, poster_frame: false, recolorable: false, ingest: true, edit: true, extractable: true },
+  htm: { family: 'docs', resize_ladder: false, poster_frame: false, recolorable: false, ingest: true, edit: true, extractable: true },
+
+  // Archives (ingest containers — not assets themselves)
+  zip: { family: 'archive', resize_ladder: false, ingest: true, edit: false, container: true },
+  tar: { family: 'archive', resize_ladder: false, ingest: true, edit: false, container: true },
+  gz: { family: 'archive', resize_ladder: false, ingest: true, edit: false, container: true },
+  tgz: { family: 'archive', resize_ladder: false, ingest: true, edit: false, container: true },
+});
+
+/**
+ * Family-level ingest / master / delivery / export defaults.
+ * Matches the BrandPack v2 format-universe table.
+ */
+export const FORMAT_FAMILIES = Object.freeze({
+  logo: {
+    ingest: ['svg', 'pdf', 'eps', 'ai', 'png'],
+    canonical: ['svg'],
+    web_delivery: ['svg'],
+    export: ['svg', 'pdf', 'png'],
+  },
+  raster: {
+    ingest: ['png', 'jpg', 'jpeg', 'tiff', 'tif', 'heic', 'webp', 'avif'],
+    canonical: ['png', 'tiff'],
+    web_delivery: ['avif', 'webp', 'jpeg', 'png'],
+    export: ['png', 'jpg'],
+  },
+  photography: {
+    ingest: ['jpg', 'jpeg', 'png', 'tiff', 'heic'],
+    canonical: ['jpeg'],
+    web_delivery: ['avif', 'webp', 'jpeg'],
+    export: ['jpg', 'png'],
+  },
+  transparency: {
+    ingest: ['png', 'webp', 'avif'],
+    canonical: ['png'],
+    web_delivery: ['avif', 'webp', 'png'],
+    export: ['png'],
+  },
+  favicon: {
+    ingest: ['svg', 'png', 'ico'],
+    canonical: ['svg', 'png'],
+    web_delivery: ['svg', 'png', 'ico'],
+    export: ['ico', 'png', 'svg'],
+  },
+  'app-icon': {
+    ingest: ['png', 'svg', 'icns'],
+    canonical: ['png'],
+    web_delivery: [],
+    export: ['icns', 'png', 'ico'],
+  },
+  social: {
+    ingest: ['png', 'jpg', 'svg'],
+    canonical: ['png'],
+    web_delivery: ['avif', 'webp', 'jpeg'],
+    export: ['png', 'jpg'],
+  },
+  video: {
+    ingest: ['mov', 'mp4', 'webm', 'mkv'],
+    canonical: ['mov', 'mp4'],
+    web_delivery: ['mp4', 'hls'],
+    export: ['mp4', 'webm', 'mov'],
+    delivery_target: 'cloudflare-stream',
+  },
+  'motion-graphics': {
+    ingest: ['json', 'riv'],
+    canonical: ['json', 'riv'],
+    web_delivery: ['json', 'riv'],
+    export: ['json', 'riv', 'mp4'],
+  },
+  model: {
+    ingest: ['glb', 'gltf', 'obj', 'fbx', 'usdz'],
+    canonical: ['glb', 'gltf'],
+    web_delivery: ['glb'],
+    export: ['glb', 'gltf', 'usdz'],
+  },
+  font: {
+    ingest: ['otf', 'ttf', 'woff', 'woff2'],
+    canonical: ['otf', 'ttf'],
+    web_delivery: ['woff2'],
+    export: ['woff2', 'woff'], // only when licensing.redistributable === true
+    licensing_required: true,
+  },
+  tokens: {
+    ingest: ['json', 'yaml', 'yml'],
+    canonical: ['json'],
+    web_delivery: ['css', 'json'],
+    export: ['json', 'yaml', 'css', 'ts'],
+  },
+  theme: {
+    ingest: ['css', 'scss', 'json'],
+    canonical: ['json'],
+    web_delivery: ['css'],
+    export: ['css', 'ts'],
+  },
+  docs: {
+    ingest: ['md', 'html', 'json'],
+    canonical: ['json', 'md'],
+    web_delivery: ['html'],
+    export: ['pdf', 'html', 'md'],
+  },
+  archive: {
+    ingest: ['zip', 'tar', 'gz', 'tgz'],
+    canonical: [],
+    web_delivery: [],
+    export: [],
+    container: true,
+  },
+});
+
+export function formatCapabilities(format) {
+  const key = String(format || '').toLowerCase().replace(/^\./, '');
+  return FORMAT_CAPABILITIES[key] || {
+    resize_ladder: false,
+    poster_frame: false,
+    recolorable: false,
+    unknown: true,
+  };
+}
+
+export function canResizeFormat(format) {
+  return Boolean(formatCapabilities(format).resize_ladder);
+}
+
+export function familyCapabilities(family) {
+  return FORMAT_FAMILIES[String(family || '').toLowerCase()] || null;
+}
+
+/** Extensions accepted for drop-folder / archive walk */
+export const INGEST_EXTENSIONS = Object.freeze(
+  Object.entries(FORMAT_CAPABILITIES)
+    .filter(([, c]) => c.ingest)
+    .map(([ext]) => `.${ext}`),
+);

package/packages/agentsam-brand/src/core/derivatives.js

@@ -0,0 +1,211 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { canResizeFormat } from './capabilities.js';
+import { BrandAssetError, assert } from './errors.js';
+import { inspectBrandAsset } from './inspect.js';
+import {
+  discoverProcessors,
+  resolveProcessor,
+  hasMagick,
+} from './processors/index.js';
+
+export { hasMagick };
+export { hasSquooshBinary } from './processors/index.js';
+
+export function hasSharp() {
+  return discoverProcessors().available.includes('sharp');
+}
+
+/**
+ * Portable capability discovery — processors are adapters, not the product.
+ */
+export function discoverDerivativeCapabilities() {
+  const discovery = discoverProcessors();
+  return {
+    backends: Object.fromEntries(
+      discovery.processors.map((p) => [
+        p.id,
+        {
+          available: p.available,
+          capability_id: p.id === 'cloudflare'
+            ? 'image.edge.transform'
+            : p.id === 'squoosh'
+              ? 'image.codec.squoosh-binary'
+              : 'image.raster.transform',
+        },
+      ]),
+    ),
+    preferred_backend: discovery.preferred,
+    rejected: discovery.rejected,
+    formats: {
+      png: discovery.available.some((id) => ['sharp', 'squoosh', 'native'].includes(id)),
+      jpeg: discovery.available.some((id) => ['sharp', 'squoosh', 'native'].includes(id)),
+      webp: discovery.available.some((id) => ['sharp', 'squoosh', 'native'].includes(id)),
+      avif: discovery.available.some((id) => ['sharp', 'squoosh', 'native'].includes(id)),
+      jxl: discovery.available.includes('squoosh'),
+      wp2: discovery.available.includes('squoosh'),
+      icns: discovery.available.includes('native'),
+    },
+  };
+}
+
+function blockedCapability({ id, format, capabilityId = 'image.raster.transform' }) {
+  return {
+    id,
+    format,
+    status: 'blocked',
+    reason: 'capability_missing',
+    capability_id: capabilityId,
+    acceptable_backends: capabilityId === 'image.vectorize'
+      ? ['potrace']
+      : ['sharp', 'squoosh', 'native'],
+  };
+}
+
+/**
+ * Expand derivative declarations into concrete files via processor scheduler.
+ */
+export async function deriveBrandAssets({
+  sourcePath,
+  outDir,
+  derivatives = [],
+  asset = 'asset',
+  processor: forceProcessor,
+} = {}) {
+  assert(sourcePath && fs.existsSync(sourcePath), 'source_missing', `Source missing: ${sourcePath}`);
+  const caps = discoverDerivativeCapabilities();
+  fs.mkdirSync(outDir, { recursive: true });
+
+  const artifacts = [];
+  for (const d of derivatives) {
+    const format = String(d.format || 'png').toLowerCase();
+    const width = Number(d.width || d.size || 0) || null;
+    const height = Number(d.height || d.size || width || 0) || null;
+    const id = d.id || `${format}-${width || 'x'}`;
+    const ext = format === 'jpeg' ? 'jpg' : format;
+    const dest = path.join(outDir, d.filename || `${asset}-${width || 'x'}.${ext}`);
+
+    if (format === 'icns' && !caps.backends.native?.available) {
+      artifacts.push({
+        ...blockedCapability({ id, format }),
+        role: d.role || 'native',
+        status: 'blocked',
+        capability_id: 'image.native.macos-icon',
+        acceptable_backends: ['native', 'platform-adapter'],
+      });
+      continue;
+    }
+
+    if ((width || height) && !canResizeFormat(format)) {
+      artifacts.push({
+        id,
+        format,
+        role: d.role || 'raster',
+        status: 'skipped',
+        reason: 'format_no_resize_ladder',
+        note: `${format} does not support resize ladders (see FORMAT_CAPABILITIES)`,
+      });
+      continue;
+    }
+
+    try {
+      let encodeInput = sourcePath;
+      let tmpResize = null;
+
+      if ((width || height) && format !== 'icns') {
+        const proc = await resolveProcessor(
+          { format, preserve_alpha: true },
+          { force: forceProcessor },
+        );
+        tmpResize = path.join(outDir, `.resize-${id}.png`);
+        if (typeof proc.resize === 'function') {
+          await proc.resize(sourcePath, { width, height, outPath: tmpResize });
+          encodeInput = tmpResize;
+        }
+      }
+
+      const proc = await resolveProcessor(
+        { format: format === 'icns' ? 'icns' : format },
+        { force: format === 'icns' ? 'native' : forceProcessor },
+      );
+
+      if (format === 'icns') {
+        await proc.encode(encodeInput, { format: 'png', outPath: dest.replace(/\.icns$/i, '.png') });
+        // ICNS still needs magick-specific path — mark generated png ladder for now
+        const inspected = inspectBrandAsset(dest.replace(/\.icns$/i, '.png'));
+        artifacts.push({
+          id,
+          role: d.role || 'native',
+          format: 'png',
+          status: 'generated',
+          backend: proc.id,
+          path: inspected.path,
+          width: inspected.width,
+          height: inspected.height,
+          bytes: inspected.bytes,
+          content_type: inspected.content_type,
+          sha256: inspected.sha256,
+          note: 'icns container requires platform adapter; png ladder emitted',
+        });
+      } else {
+        const result = await proc.encode(encodeInput, {
+          format,
+          quality: d.quality,
+          outPath: dest,
+        });
+        artifacts.push({
+          id,
+          role: d.role || 'raster',
+          format,
+          status: 'generated',
+          backend: result.processor,
+          path: result.path,
+          width: result.width,
+          height: result.height,
+          bytes: result.bytes,
+          content_type: result.content_type,
+          sha256: result.sha256,
+          quality: d.quality ?? null,
+          receipt: {
+            processor: result.processor,
+            version: result.processor_version || null,
+            options: result.options,
+          },
+        });
+      }
+
+      if (tmpResize) {
+        try {
+          fs.unlinkSync(tmpResize);
+        } catch {
+          /* ignore */
+        }
+      }
+    } catch (err) {
+      if (err?.code === 'processor_unavailable' || err?.code === 'processor_rejected') {
+        artifacts.push({
+          ...blockedCapability({ id, format }),
+          role: d.role || 'raster',
+          message: err.message,
+        });
+        continue;
+      }
+      artifacts.push({
+        id,
+        role: d.role || 'raster',
+        format,
+        status: 'failed',
+        reason: err?.code || 'derive_failed',
+        message: err?.message || String(err),
+      });
+    }
+  }
+
+  return { capabilities: caps, artifacts };
+}
+
+export function formatBytesKb(bytes) {
+  const n = Number(bytes) || 0;
+  if (n < 1024) return `${n} B`;
+  return `${(n / 1024).toFixed(n >= 10240 ? 0 : 1)} KB`;
+}

package/packages/agentsam-brand/src/core/errors.js

@@ -0,0 +1,12 @@
+export class BrandAssetError extends Error {
+  constructor(code, message, details = null) {
+    super(message || code);
+    this.name = 'BrandAssetError';
+    this.code = code;
+    this.details = details;
+  }
+}
+
+export function assert(condition, code, message, details) {
+  if (!condition) throw new BrandAssetError(code, message, details);
+}

package/packages/agentsam-brand/src/core/ingest.js

@@ -0,0 +1,195 @@
+/**
+ * Brand asset ingest — path, URL, stdin (-), drop-folder.
+ * Never seeds product brand defaults (no agentsam / Downloads paths).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { BrandAssetError } from './errors.js';
+import { isExcludedIntermediate } from './inspect.js';
+
+const IMAGE_EXTS = new Set(['.png', '.jpg', '.jpeg', '.webp', '.avif', '.gif', '.svg', '.ico', '.icns']);
+
+export function expandHome(p) {
+  const s = String(p || '').trim().replace(/^['"]|['"]$/g, '');
+  if (!s) return s;
+  if (s.startsWith('~/')) return path.join(os.homedir(), s.slice(2));
+  return path.resolve(s);
+}
+
+/** Sniff common image magic bytes → extension + content-type */
+export function sniffImageBuffer(buf) {
+  if (!buf || buf.length < 3) return null;
+  if (buf.length >= 4 && buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4e && buf[3] === 0x47) {
+    return { ext: '.png', contentType: 'image/png' };
+  }
+  if (buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff) {
+    return { ext: '.jpg', contentType: 'image/jpeg' };
+  }
+  if (buf.length >= 3 && buf[0] === 0x47 && buf[1] === 0x49 && buf[2] === 0x46) {
+    return { ext: '.gif', contentType: 'image/gif' };
+  }
+  // RIFF....WEBP
+  if (
+    buf.length >= 12
+    && buf[0] === 0x52 && buf[1] === 0x49 && buf[2] === 0x46 && buf[3] === 0x46
+    && buf[8] === 0x57 && buf[9] === 0x45 && buf[10] === 0x42 && buf[11] === 0x50
+  ) {
+    return { ext: '.webp', contentType: 'image/webp' };
+  }
+  // ftyp....avif (ISO BMFF)
+  if (buf.length >= 12 && buf[4] === 0x66 && buf[5] === 0x74 && buf[6] === 0x79 && buf[7] === 0x70) {
+    const brand = buf.slice(8, 12).toString('ascii');
+    if (brand.includes('avif') || brand.includes('avis')) {
+      return { ext: '.avif', contentType: 'image/avif' };
+    }
+  }
+  const head = buf.slice(0, Math.min(256, buf.length)).toString('utf8').trimStart();
+  if (head.startsWith('<svg') || head.startsWith('<?xml')) {
+    return { ext: '.svg', contentType: 'image/svg+xml' };
+  }
+  return null;
+}
+
+/**
+ * Read stdin binary when --source - or stdin is piped (non-TTY).
+ */
+export async function readStdinImage(options = {}) {
+  const { workDir, stdin = process.stdin } = options;
+  if (!workDir) throw new BrandAssetError('work_dir_required', 'workDir required for stdin ingest');
+  fs.mkdirSync(workDir, { recursive: true });
+
+  const chunks = [];
+  for await (const chunk of stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  const buf = Buffer.concat(chunks);
+  if (buf.length < 16) {
+    throw new BrandAssetError('stdin_empty', 'stdin produced no image bytes (pipe a PNG/JPEG/WebP/SVG)');
+  }
+  const sniffed = sniffImageBuffer(buf);
+  if (!sniffed) {
+    throw new BrandAssetError('stdin_unknown_type', 'Could not sniff image type from stdin');
+  }
+  const dest = path.join(workDir, `stdin-source${sniffed.ext}`);
+  fs.writeFileSync(dest, buf);
+  return {
+    path: dest,
+    contentType: sniffed.contentType,
+    bytes: buf.length,
+    source: 'stdin',
+  };
+}
+
+export function isImagePath(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  return IMAGE_EXTS.has(ext);
+}
+
+/**
+ * Scan a drop folder once; pick largest PNG (or first image) + optional SVG mark.
+ */
+export function scanDropFolder(dirPath) {
+  const dir = expandHome(dirPath);
+  if (!dir || !fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
+    throw new BrandAssetError('drop_dir_missing', `Drop folder not found: ${dirPath}`);
+  }
+  const files = fs.readdirSync(dir)
+    .map((n) => path.join(dir, n))
+    .filter((f) => {
+      try {
+        return fs.statSync(f).isFile() && !isExcludedIntermediate(f) && isImagePath(f);
+      } catch {
+        return false;
+      }
+    });
+
+  const pngs = files
+    .filter((f) => f.toLowerCase().endsWith('.png'))
+    .sort((a, b) => fs.statSync(b).size - fs.statSync(a).size);
+  const svgs = files.filter((f) => f.toLowerCase().endsWith('.svg'));
+  const others = files.filter((f) => !f.toLowerCase().endsWith('.png') && !f.toLowerCase().endsWith('.svg'))
+    .sort((a, b) => fs.statSync(b).size - fs.statSync(a).size);
+
+  const sourcePath = pngs[0] || others[0] || null;
+  const markPath = svgs.find((f) => /\.min\.svg$/i.test(f)) || svgs[0] || null;
+
+  return {
+    dir,
+    sourcePath,
+    markPath,
+    files,
+    heuristics: {
+      source: sourcePath ? path.basename(sourcePath) : null,
+      mark: markPath ? path.basename(markPath) : null,
+    },
+  };
+}
+
+/**
+ * Poll drop-dir until a usable image appears or timeout.
+ * @param {{ dir: string, timeoutMs?: number, intervalMs?: number }} options
+ */
+export async function waitForDrop(options = {}) {
+  const dir = expandHome(options.dir);
+  const timeoutMs = Number(options.timeoutMs ?? 120_000);
+  const intervalMs = Number(options.intervalMs ?? 800);
+  const started = Date.now();
+  fs.mkdirSync(dir, { recursive: true });
+
+  while (Date.now() - started < timeoutMs) {
+    const scan = scanDropFolder(dir);
+    if (scan.sourcePath || scan.markPath) return scan;
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+  throw new BrandAssetError(
+    'drop_timeout',
+    `No image appeared in ${dir} within ${Math.round(timeoutMs / 1000)}s — drop a PNG/SVG and retry`,
+  );
+}
+
+/**
+ * Resolve --source flag: path, -, or empty (caller may use drop-dir).
+ */
+export async function resolveSourceInput({
+  source,
+  dropDir,
+  watch = false,
+  workDir,
+  cwd = process.cwd(),
+} = {}) {
+  const src = String(source || '').trim();
+
+  if (src === '-' || src === '/dev/stdin') {
+    return readStdinImage({ workDir: workDir || path.join(cwd, '.agentsam', 'brand', 'work', 'stdin') });
+  }
+
+  if (src) {
+    const abs = expandHome(src);
+    if (!fs.existsSync(abs)) {
+      throw new BrandAssetError('source_missing', `Source not found: ${src}`);
+    }
+    if (isExcludedIntermediate(abs)) {
+      throw new BrandAssetError('source_intermediate', 'Tracing / .pbm intermediates are not product assets');
+    }
+    return { path: abs, source: 'path', contentType: null, bytes: fs.statSync(abs).size };
+  }
+
+  if (dropDir) {
+    const scan = watch
+      ? await waitForDrop({ dir: dropDir })
+      : scanDropFolder(dropDir);
+    if (!scan.sourcePath && !scan.markPath) {
+      throw new BrandAssetError('drop_empty', `No usable images in ${dropDir}`);
+    }
+    return {
+      path: scan.sourcePath || scan.markPath,
+      markPath: scan.markPath,
+      source: 'drop',
+      heuristics: scan.heuristics,
+      bytes: scan.sourcePath ? fs.statSync(scan.sourcePath).size : 0,
+    };
+  }
+
+  return null;
+}