@inneranimalmedia/agentsam-sdk 2.6.4 → 2.6.7

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

@@ -0,0 +1,159 @@
+/**
+ * Localhost brand pack gallery preview.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import http from 'node:http';
+import { spawn, spawnSync } from 'node:child_process';
+import { BrandAssetError } from './errors.js';
+import { buildGalleryHtml } from './pack.js';
+
+function openBrowser(url) {
+  const plat = process.platform;
+  if (plat === 'darwin') spawn('open', [url], { detached: true, stdio: 'ignore' }).unref();
+  else if (plat === 'win32') spawn('cmd', ['/c', 'start', '', url], { detached: true, stdio: 'ignore' }).unref();
+  else spawn('xdg-open', [url], { detached: true, stdio: 'ignore' }).unref();
+}
+
+function findFile(root, name) {
+  const stack = [root];
+  while (stack.length) {
+    const dir = stack.pop();
+    for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, ent.name);
+      if (ent.isDirectory()) stack.push(full);
+      else if (ent.name === name) return full;
+    }
+  }
+  return null;
+}
+
+function ensureGallery(root) {
+  const gallery = path.join(root, 'gallery.html');
+  if (fs.existsSync(gallery)) return gallery;
+  const manifestPath = path.join(root, 'manifest.json');
+  if (!fs.existsSync(manifestPath)) return null;
+  const m = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  const items = [];
+  const walk = (dir, base = '') => {
+    for (const name of fs.readdirSync(dir)) {
+      const full = path.join(dir, name);
+      const rel = path.join(base, name).replace(/\\/g, '/');
+      if (fs.statSync(full).isDirectory()) walk(full, rel);
+      else if (/\.(png|jpe?g|webp|avif|gif|svg)$/i.test(name)) items.push({ rel, label: rel });
+    }
+  };
+  walk(root);
+  fs.writeFileSync(
+    gallery,
+    buildGalleryHtml({
+      brand: m.brand || 'brand',
+      asset: m.asset || 'asset',
+      version: m.version || 'v1',
+      items,
+    }),
+  );
+  return gallery;
+}
+
+/**
+ * Resolve a pack root from a directory or zip.
+ */
+export function resolvePackRoot(fromPath, { cwd = process.cwd() } = {}) {
+  const abs = path.resolve(cwd, fromPath);
+  if (!fs.existsSync(abs)) {
+    throw new BrandAssetError('preview_missing', `Not found: ${fromPath}`);
+  }
+  if (fs.statSync(abs).isDirectory()) {
+    ensureGallery(abs);
+    return abs;
+  }
+  if (/\.zip$/i.test(abs)) {
+    const tmp = path.join(cwd, '.agentsam', 'brand', 'preview', `zip-${Date.now()}`);
+    fs.mkdirSync(tmp, { recursive: true });
+    const r = spawnSync('unzip', ['-q', abs, '-d', tmp], { encoding: 'utf8' });
+    if (r.status !== 0) {
+      throw new BrandAssetError('unzip_failed', r.stderr || 'unzip failed — install unzip or pass a pack directory');
+    }
+    const found = findFile(tmp, 'gallery.html') || findFile(tmp, 'manifest.json');
+    if (!found) throw new BrandAssetError('pack_invalid', 'Zip has no gallery.html / manifest.json');
+    const root = path.dirname(found);
+    ensureGallery(root);
+    return root;
+  }
+  throw new BrandAssetError('preview_unsupported', 'Pass a pack directory or .zip');
+}
+
+/**
+ * Serve pack root on 127.0.0.1 and optionally open the browser.
+ */
+export async function previewBrandPack({
+  from,
+  cwd = process.cwd(),
+  open = true,
+  waitForEnter = true,
+  write = (s) => process.stdout.write(s),
+} = {}) {
+  const root = resolvePackRoot(from, { cwd });
+  if (!fs.existsSync(path.join(root, 'gallery.html'))) {
+    throw new BrandAssetError('gallery_missing', 'Pack has no gallery.html — run brand pack/build first');
+  }
+
+  const indexFile = fs.existsSync(path.join(root, 'studio.html')) ? 'studio.html' : 'gallery.html';
+
+  const server = http.createServer((req, res) => {
+    try {
+      const urlPath = decodeURIComponent((req.url || '/').split('?')[0]);
+      let filePath = path.join(root, urlPath === '/' ? indexFile : urlPath);
+      filePath = path.normalize(filePath);
+      if (!filePath.startsWith(root)) {
+        res.writeHead(403);
+        res.end('forbidden');
+        return;
+      }
+      if (!fs.existsSync(filePath) || fs.statSync(filePath).isDirectory()) {
+        res.writeHead(404);
+        res.end('not found');
+        return;
+      }
+      const ext = path.extname(filePath).toLowerCase();
+      const types = {
+        '.html': 'text/html; charset=utf-8',
+        '.json': 'application/json',
+        '.png': 'image/png',
+        '.jpg': 'image/jpeg',
+        '.jpeg': 'image/jpeg',
+        '.webp': 'image/webp',
+        '.avif': 'image/avif',
+        '.gif': 'image/gif',
+        '.svg': 'image/svg+xml',
+      };
+      res.writeHead(200, { 'Content-Type': types[ext] || 'application/octet-stream' });
+      fs.createReadStream(filePath).pipe(res);
+    } catch (err) {
+      res.writeHead(500);
+      res.end(String(err?.message || err));
+    }
+  });
+
+  await new Promise((resolve, reject) => {
+    server.listen(0, '127.0.0.1', (err) => (err ? reject(err) : resolve()));
+  });
+  const { port } = server.address();
+  const url = `http://127.0.0.1:${port}/${indexFile}`;
+  write(`Brand pack preview\n  ${url}\n`);
+  if (open) {
+    try { openBrowser(url); } catch { /* ignore */ }
+  }
+
+  if (waitForEnter && process.stdin.isTTY) {
+    write('Press Enter to stop preview…\n');
+    await new Promise((resolve) => {
+      process.stdin.resume();
+      process.stdin.once('data', () => resolve());
+    });
+  }
+
+  await new Promise((resolve) => server.close(() => resolve()));
+  return { ok: true, capability: 'brand.preview', url, root, port };
+}

package/packages/agentsam-brand/src/core/processors/cloudflare.js

@@ -0,0 +1,68 @@
+/**
+ * Cloudflare Images — edge DERIVABLE transforms.
+ * Does not locally encode; returns a delivery plan / transform descriptor.
+ */
+
+import { inspectBrandAsset } from '../inspect.js';
+
+export const cloudflareProcessor = {
+  id: 'cloudflare',
+  label: 'Cloudflare Images',
+
+  available() {
+    // Edge path is always "available" as a planner target when CF is configured.
+    // Actual upload uses CloudflareImagesDeliveryAdapter.
+    return true;
+  },
+
+  async inspect(input) {
+    const meta = typeof input === 'string' && input.includes('/')
+      ? inspectBrandAsset(input)
+      : { path: input, processor: 'cloudflare' };
+    meta.processor = 'cloudflare';
+    meta.derivative_kind = 'edge';
+    return meta;
+  },
+
+  /**
+   * Plan an edge resize — no local bytes written.
+   */
+  async resize(input, options = {}) {
+    return {
+      path: null,
+      format: options.format || 'auto',
+      bytes: null,
+      width: options.width || null,
+      height: options.height || null,
+      processor: 'cloudflare',
+      derivative_kind: 'edge',
+      materialized: false,
+      options: {
+        width: options.width,
+        height: options.height,
+        fit: options.fit || 'scale-down',
+      },
+      note: 'Cloudflare Images generates this on request — retain high-quality master',
+    };
+  },
+
+  async encode(input, options = {}) {
+    return {
+      path: null,
+      format: options.format || 'auto',
+      bytes: null,
+      processor: 'cloudflare',
+      derivative_kind: 'edge',
+      materialized: false,
+      options: {
+        format: options.format || 'auto', // CF auto AVIF/WebP negotiation
+        quality: options.quality,
+      },
+      note: 'Prefer role_canonical master upload; let CF negotiate encoding',
+    };
+  },
+
+  async optimize(input, options = {}) {
+    return this.encode(input, options);
+  },
+};

package/packages/agentsam-brand/src/core/processors/contract.js

@@ -0,0 +1,203 @@
+/**
+ * ImageProcessor adapter contract.
+ *
+ * PUBLIC API stays: agentsam brand optimize / derive
+ * Encoders are pluggable backends — never the product surface.
+ *
+ * REJECTED as hard dependency:
+ *   @squoosh/cli (npm 0.7.3) — abandoned, Node 12–16 only, crashes on Node 22+
+ *
+ * ALLOWED backends (benchmark / prefer per job):
+ *   sharp | squoosh (maintained binary) | native (ImageMagick) | cloudflare | wasm | go
+ */
+
+/** @typedef {'sharp'|'squoosh'|'native'|'cloudflare'|'wasm'|'go'|'ffmpeg'|'custom'} ProcessorId */
+
+/**
+ * @typedef {object} ImageMetadata
+ * @property {string} path
+ * @property {string} content_type
+ * @property {number} bytes
+ * @property {number|null} [width]
+ * @property {number|null} [height]
+ * @property {boolean|null} [alpha]
+ * @property {string} [sha256]
+ * @property {string} [processor]
+ */
+
+/**
+ * @typedef {object} EncodeOptions
+ * @property {'png'|'jpeg'|'jpg'|'webp'|'avif'|'jxl'|'wp2'|'oxipng'} format
+ * @property {number} [quality]   // 0–100 where applicable
+ * @property {number} [cqLevel]   // AVIF
+ * @property {boolean} [lossless]
+ * @property {number} [level]     // oxipng 1–6
+ * @property {'auto'|object} [auto]
+ */
+
+/**
+ * @typedef {object} ResizeOptions
+ * @property {number} [width]
+ * @property {number} [height]
+ * @property {'contain'|'cover'|'stretch'} [fit]
+ * @property {string} [method] // lanczos3 | mitchell | catrom | triangle
+ */
+
+/**
+ * @typedef {object} ProcessorAsset
+ * @property {string} path
+ * @property {string} format
+ * @property {number} bytes
+ * @property {number|null} [width]
+ * @property {number|null} [height]
+ * @property {string} processor
+ * @property {string} [processor_version]
+ * @property {object} [options]
+ * @property {string} [sha256]
+ * @property {string} [content_type]
+ */
+
+/**
+ * @typedef {object} ImageProcessor
+ * @property {ProcessorId} id
+ * @property {string} label
+ * @property {() => Promise<boolean>|boolean} available
+ * @property {(input: string) => Promise<ImageMetadata>} [inspect]
+ * @property {(input: string, options: ResizeOptions & { outPath: string }) => Promise<ProcessorAsset>} [resize]
+ * @property {(input: string, options: EncodeOptions & { outPath: string }) => Promise<ProcessorAsset>} [encode]
+ * @property {(input: string, options: object & { outPath: string }) => Promise<ProcessorAsset>} [optimize]
+ */
+
+/** Official abandoned npm package — never require / spawn via npx. */
+export const REJECTED_PROCESSORS = Object.freeze({
+  'squoosh-npm': {
+    id: 'squoosh-npm',
+    package: '@squoosh/cli',
+    reason: 'abandoned (0.7.3); Node 12–16 only; crashes on Node 22+ (navigator setter)',
+    status: 'rejected',
+  },
+  'squoosh-lib': {
+    id: 'squoosh-lib',
+    package: '@squoosh/lib',
+    reason: 'abandoned companion to @squoosh/cli',
+    status: 'rejected',
+  },
+});
+
+export const PROCESSOR_CAPABILITIES = Object.freeze({
+  sharp: {
+    id: 'sharp',
+    label: 'Sharp',
+    kind: 'node',
+    formats: ['png', 'jpeg', 'webp', 'avif', 'tiff', 'gif'],
+    resize: true,
+    alpha: true,
+    optimize: true,
+    speed: 'fast',
+  },
+  squoosh: {
+    id: 'squoosh',
+    label: 'Squoosh (maintained binary)',
+    kind: 'binary',
+    formats: ['png', 'jpeg', 'webp', 'avif', 'jxl', 'wp2', 'oxipng', 'mozjpeg'],
+    resize: true,
+    alpha: true,
+    optimize: true,
+    butteraugli: true,
+    speed: 'medium',
+    note: 'Homebrew/Scoop fork — NOT @squoosh/cli npm',
+  },
+  native: {
+    id: 'native',
+    label: 'ImageMagick',
+    kind: 'binary',
+    formats: ['png', 'jpeg', 'webp', 'avif', 'icns', 'tiff'],
+    resize: true,
+    alpha: true,
+    optimize: false,
+    speed: 'medium',
+  },
+  cloudflare: {
+    id: 'cloudflare',
+    label: 'Cloudflare Images',
+    kind: 'edge',
+    formats: ['avif', 'webp', 'jpeg', 'png'],
+    resize: true,
+    alpha: true,
+    optimize: true,
+    speed: 'edge',
+    note: 'DERIVABLE at edge — materialize masters; CF negotiates delivery',
+  },
+  wasm: {
+    id: 'wasm',
+    label: 'WASM codecs',
+    kind: 'wasm',
+    formats: ['webp', 'avif', 'png'],
+    resize: true,
+    alpha: true,
+    optimize: true,
+    speed: 'preview',
+    note: 'Studio instant preview / crop — not production bake unless bound',
+  },
+  go: {
+    id: 'go',
+    label: 'Go media worker',
+    kind: 'worker',
+    formats: ['*'],
+    resize: true,
+    alpha: true,
+    optimize: true,
+    speed: 'heavy',
+    note: 'Queued durable jobs — 4K / batch / benchmark suites',
+  },
+});
+
+/**
+ * Job planner hint — preferred then fallback.
+ * @param {object} requirements
+ */
+export function planProcessorOrder(requirements = {}) {
+  const preferred = [];
+  const fallback = [];
+
+  if (requirements.edge_only || requirements.delivery === 'cloudflare-images') {
+    preferred.push('cloudflare');
+    fallback.push('sharp', 'squoosh', 'native');
+    return { preferred, fallback };
+  }
+
+  if (requirements.preview || requirements.surface === 'studio') {
+    preferred.push('wasm', 'sharp');
+    fallback.push('squoosh');
+    return { preferred, fallback };
+  }
+
+  if (requirements.heavy || requirements.benchmark) {
+    preferred.push('go', 'squoosh');
+    fallback.push('sharp', 'native');
+    return { preferred, fallback };
+  }
+
+  if (requirements.preserve_alpha && requirements.format === 'png') {
+    preferred.push('sharp', 'squoosh');
+    fallback.push('native');
+    return { preferred, fallback };
+  }
+
+  if (requirements.format === 'icns') {
+    preferred.push('native');
+    fallback.push();
+    return { preferred, fallback };
+  }
+
+  if (requirements.format === 'jxl' || requirements.format === 'wp2' || requirements.butteraugli) {
+    preferred.push('squoosh');
+    fallback.push('sharp', 'go');
+    return { preferred, fallback };
+  }
+
+  // Default local path: dependable Node first, codec binary second
+  preferred.push('sharp', 'squoosh');
+  fallback.push('native', 'cloudflare');
+  return { preferred, fallback };
+}

package/packages/agentsam-brand/src/core/processors/index.js

@@ -0,0 +1,148 @@
+/**
+ * Processor registry + scheduler.
+ * Public surface never names Squoosh/Sharp — only agentsam brand optimize.
+ */
+
+import {
+  PROCESSOR_CAPABILITIES,
+  REJECTED_PROCESSORS,
+  planProcessorOrder,
+} from './contract.js';
+import { sharpProcessor } from './sharp.js';
+import { squooshProcessor, hasSquooshBinary } from './squoosh-binary.js';
+import { nativeProcessor, hasMagick } from './native.js';
+import { cloudflareProcessor } from './cloudflare.js';
+import { BrandAssetError } from '../errors.js';
+
+const PROCESSORS = Object.freeze({
+  sharp: sharpProcessor,
+  squoosh: squooshProcessor,
+  native: nativeProcessor,
+  cloudflare: cloudflareProcessor,
+});
+
+export {
+  PROCESSOR_CAPABILITIES,
+  REJECTED_PROCESSORS,
+  planProcessorOrder,
+  hasSquooshBinary,
+  hasMagick,
+};
+
+export function listProcessors() {
+  return Object.values(PROCESSORS).map((p) => {
+    const caps = PROCESSOR_CAPABILITIES[p.id] || {};
+    let available = false;
+    try {
+      available = Boolean(p.available());
+    } catch {
+      available = false;
+    }
+    return {
+      id: p.id,
+      label: p.label,
+      available,
+      ...caps,
+    };
+  });
+}
+
+export function discoverProcessors() {
+  const listed = listProcessors();
+  const available = listed.filter((p) => p.available).map((p) => p.id);
+  return {
+    processors: listed,
+    available,
+    preferred: available.includes('sharp')
+      ? 'sharp'
+      : available.includes('squoosh')
+        ? 'squoosh'
+        : available.includes('native')
+          ? 'native'
+          : null,
+    rejected: Object.values(REJECTED_PROCESSORS),
+    note: '@squoosh/cli npm is rejected; use maintained squoosh binary or sharp',
+  };
+}
+
+export function getProcessor(id) {
+  if (id === 'squoosh-npm' || id === '@squoosh/cli') {
+    throw new BrandAssetError(
+      'processor_rejected',
+      '@squoosh/cli is abandoned and incompatible with Node 22+. Use sharp or the maintained squoosh binary.',
+      REJECTED_PROCESSORS['squoosh-npm'],
+    );
+  }
+  return PROCESSORS[id] || null;
+}
+
+/**
+ * Pick first available processor from preferred → fallback.
+ */
+export async function resolveProcessor(requirements = {}, { force } = {}) {
+  if (force) {
+    const p = getProcessor(force);
+    if (!p) throw new BrandAssetError('unknown_processor', `Unknown processor: ${force}`);
+    if (force !== 'cloudflare' && !(await Promise.resolve(p.available()))) {
+      throw new BrandAssetError('processor_unavailable', `${force} is not available`);
+    }
+    return p;
+  }
+
+  const order = planProcessorOrder(requirements);
+  const chain = [...order.preferred, ...order.fallback];
+  for (const id of chain) {
+    const p = PROCESSORS[id];
+    if (!p) continue;
+    if (id === 'cloudflare') {
+      if (requirements.edge_ok || requirements.delivery === 'cloudflare-images' || requirements.prefer_edge) {
+        return p;
+      }
+      continue;
+    }
+    if (await Promise.resolve(p.available())) return p;
+  }
+  throw new BrandAssetError(
+    'processor_unavailable',
+    'No image processor available (install sharp, squoosh binary, or ImageMagick)',
+    discoverProcessors(),
+  );
+}
+
+/**
+ * Run encode through the scheduler.
+ */
+export async function encodeWithScheduler(input, options = {}) {
+  const processor = await resolveProcessor(
+    {
+      format: options.format,
+      preserve_alpha: options.preserve_alpha,
+      butteraugli: options.auto === 'auto' || options.butteraugli,
+      delivery: options.delivery,
+      edge_ok: options.edge_ok,
+    },
+    { force: options.processor },
+  );
+  return processor.encode(input, options);
+}
+
+/**
+ * Run optimize (role-aware caller supplies policy).
+ */
+export async function optimizeWithScheduler(input, options = {}) {
+  const processor = await resolveProcessor(
+    {
+      format: options.format,
+      preserve_alpha: options.preserve_alpha,
+      butteraugli: true,
+      preview: options.preview,
+      heavy: options.heavy,
+      delivery: options.delivery,
+    },
+    { force: options.processor },
+  );
+  if (typeof processor.optimize === 'function') {
+    return processor.optimize(input, options);
+  }
+  return processor.encode(input, options);
+}

package/packages/agentsam-brand/src/core/processors/native.js

@@ -0,0 +1,82 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { inspectBrandAsset } from '../inspect.js';
+import { BrandAssetError } from '../errors.js';
+
+export function hasMagick() {
+  const r = spawnSync('magick', ['-version'], { encoding: 'utf8' });
+  return r.status === 0;
+}
+
+export const nativeProcessor = {
+  id: 'native',
+  label: 'ImageMagick',
+
+  available() {
+    return hasMagick();
+  },
+
+  async inspect(input) {
+    const meta = inspectBrandAsset(input);
+    meta.processor = 'native';
+    return meta;
+  },
+
+  async resize(input, { width, height, outPath }) {
+    if (!hasMagick()) throw new BrandAssetError('processor_unavailable', 'magick not found');
+    fs.mkdirSync(path.dirname(outPath), { recursive: true });
+    const args = [path.resolve(input)];
+    if (width || height) args.push('-resize', `${width || ''}x${height || ''}`);
+    args.push('-background', 'none', outPath);
+    const r = spawnSync('magick', args, { encoding: 'utf8' });
+    if (r.status !== 0) {
+      throw new BrandAssetError('derive_failed', r.stderr || r.stdout || 'magick resize failed');
+    }
+    const inspected = inspectBrandAsset(outPath);
+    return {
+      path: outPath,
+      format: path.extname(outPath).slice(1).toLowerCase(),
+      bytes: inspected.bytes,
+      width: inspected.width,
+      height: inspected.height,
+      sha256: inspected.sha256,
+      content_type: inspected.content_type,
+      processor: 'native',
+      options: { width, height },
+    };
+  },
+
+  async encode(input, { format, quality, outPath }) {
+    if (!hasMagick()) throw new BrandAssetError('processor_unavailable', 'magick not found');
+    fs.mkdirSync(path.dirname(outPath), { recursive: true });
+    const fmt = String(format || 'png').toLowerCase();
+    const args = [path.resolve(input), '-background', 'none'];
+    if (fmt === 'png') args.push('-define', 'png:color-type=6');
+    if ((fmt === 'webp' || fmt === 'avif' || fmt === 'jpeg' || fmt === 'jpg') && quality != null) {
+      args.push('-quality', String(quality));
+    } else if (fmt === 'webp') args.push('-quality', '90');
+    else if (fmt === 'avif') args.push('-quality', '80');
+    args.push(outPath);
+    const r = spawnSync('magick', args, { encoding: 'utf8' });
+    if (r.status !== 0) {
+      throw new BrandAssetError('derive_failed', r.stderr || r.stdout || 'magick encode failed');
+    }
+    const inspected = inspectBrandAsset(outPath);
+    return {
+      path: outPath,
+      format: fmt === 'jpg' ? 'jpeg' : fmt,
+      bytes: inspected.bytes,
+      width: inspected.width,
+      height: inspected.height,
+      sha256: inspected.sha256,
+      content_type: inspected.content_type,
+      processor: 'native',
+      options: { format: fmt, quality },
+    };
+  },
+
+  async optimize(input, options = {}) {
+    return this.encode(input, { format: options.format || 'webp', ...options });
+  },
+};