@inneranimalmedia/agentsam-sdk 2.6.3 → 2.6.5

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

@@ -0,0 +1,109 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { BrandAssetError, assert } from './errors.js';
+
+const PNG_SIG = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+export function sha256Buffer(buf) {
+  return `sha256:${crypto.createHash('sha256').update(buf).digest('hex')}`;
+}
+
+export function sha256File(filePath) {
+  return sha256Buffer(fs.readFileSync(filePath));
+}
+
+export function isExcludedIntermediate(filePath) {
+  const base = path.basename(String(filePath || '')).toLowerCase();
+  if (base.endsWith('.pbm')) return true;
+  if (base.includes('trace')) return true;
+  return false;
+}
+
+export function sniffContentType(filePath, buf) {
+  const ext = path.extname(filePath).toLowerCase();
+  if (buf?.length >= 8 && buf.subarray(0, 8).equals(PNG_SIG)) return 'image/png';
+  if (buf?.length >= 12 && buf.toString('ascii', 0, 4) === 'RIFF' && buf.toString('ascii', 8, 12) === 'WEBP') {
+    return 'image/webp';
+  }
+  if (buf?.length >= 12 && buf.toString('ascii', 4, 8) === 'ftyp') {
+    const brand = buf.toString('ascii', 8, 12);
+    if (brand === 'avif' || brand === 'avis' || brand === 'mif1') return 'image/avif';
+  }
+  if (ext === '.svg' || (buf && /<svg[\s>]/i.test(buf.toString('utf8', 0, Math.min(buf.length, 512))))) {
+    return 'image/svg+xml';
+  }
+  if (ext === '.icns') return 'image/x-icns';
+  if (ext === '.png') return 'image/png';
+  if (ext === '.webp') return 'image/webp';
+  if (ext === '.avif') return 'image/avif';
+  if (ext === '.jpg' || ext === '.jpeg') return 'image/jpeg';
+  return 'application/octet-stream';
+}
+
+export function readPngDimensions(buf) {
+  if (!buf || buf.length < 24 || !buf.subarray(0, 8).equals(PNG_SIG)) return null;
+  return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) };
+}
+
+/** SVG product-asset gate: no scripts, no external URLs, no embedded rasters. */
+export function validateSvgMark(svgText) {
+  const issues = [];
+  const text = String(svgText || '');
+  if (!/<svg[\s>]/i.test(text)) issues.push('missing_svg_root');
+  if (/<script[\s>]/i.test(text)) issues.push('script_element');
+  if (/on[a-z]+\s*=/i.test(text)) issues.push('inline_event_handler');
+  if (/<image[\s>]/i.test(text)) issues.push('embedded_image_element');
+  if (/xlink:href\s*=\s*["']https?:/i.test(text)) issues.push('external_xlink');
+  if (/href\s*=\s*["']https?:/i.test(text)) issues.push('external_href');
+  if (/data:image\//i.test(text)) issues.push('data_image_uri');
+  return { ok: issues.length === 0, issues };
+}
+
+/**
+ * Inspect a local asset file. Pure — no brand/product identity knowledge.
+ */
+export function inspectBrandAsset(filePath, { role = 'asset', buffer = null } = {}) {
+  const abs = path.resolve(filePath);
+  assert(!isExcludedIntermediate(abs), 'asset_excluded_intermediate', `Excluded intermediate: ${path.basename(abs)}`);
+  assert(fs.existsSync(abs), 'asset_missing', `Asset not found: ${abs}`);
+
+  const buf = buffer || fs.readFileSync(abs);
+  const contentType = sniffContentType(abs, buf);
+  const sha256 = sha256Buffer(buf);
+  let width = null;
+  let height = null;
+  let alpha = null;
+
+  if (contentType === 'image/png') {
+    const dim = readPngDimensions(buf);
+    if (dim) {
+      width = dim.width;
+      height = dim.height;
+    }
+    if (buf.length >= 26) {
+      const colorType = buf[25];
+      alpha = colorType === 4 || colorType === 6;
+    }
+  } else if (contentType === 'image/svg+xml') {
+    const gate = validateSvgMark(buf.toString('utf8'));
+    if (!gate.ok) {
+      throw new BrandAssetError('svg_unsafe', `Unsafe SVG: ${gate.issues.join(',')}`, gate);
+    }
+  }
+
+  return {
+    role,
+    path: abs,
+    basename: path.basename(abs),
+    bytes: buf.length,
+    content_type: contentType,
+    sha256,
+    width,
+    height,
+    alpha,
+  };
+}
+
+/** Alias used by public SDK surface. */
+export const inspectLocalAsset = inspectBrandAsset;

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

@@ -0,0 +1,83 @@
+import { assert } from './errors.js';
+
+export const BRAND_ASSETS_SCHEMA = 'agentsam.brand-asset-promotion.v1';
+
+function cleanSegment(value, label) {
+  const s = String(value || '').trim().toLowerCase().replace(/[^a-z0-9._-]+/g, '-');
+  assert(s, `${label}_required`, `${label} is required`);
+  assert(!s.includes('..') && !s.startsWith('/') && !s.includes('\\'), `${label}_invalid`, `Invalid ${label}`);
+  return s;
+}
+
+/**
+ * Default key prefix: brands/<brand>/<asset>/<version>
+ * Override with naming.prefix or naming.convention callback.
+ */
+export function brandAssetPrefix({ brand, asset, version, naming = {} } = {}) {
+  if (naming.prefix) {
+    return String(naming.prefix).replace(/^\/+|\/+$/g, '');
+  }
+  if (typeof naming.prefixFn === 'function') {
+    return String(naming.prefixFn({ brand, asset, version })).replace(/^\/+|\/+$/g, '');
+  }
+  const b = cleanSegment(brand, 'brand');
+  const a = cleanSegment(asset, 'asset');
+  const v = cleanSegment(version, 'version');
+  return `brands/${b}/${a}/${v}`;
+}
+
+function leafFor(assetId, kind, dims = {}) {
+  const asset = cleanSegment(assetId, 'asset');
+  const w = dims.width || dims.size || null;
+  if (kind === 'master') return `${asset}-master.png`;
+  if (kind === 'mark') return `${asset}-mark.svg`;
+  if (kind === 'icns') return `${asset}.icns`;
+  if (kind === 'png' && w) return `${asset}-${w}.png`;
+  if (kind === 'webp' && w) return `${asset}-${w}.webp`;
+  if (kind === 'avif' && w) return `${asset}-${w}.avif`;
+  if (kind === 'jpeg' && w) return `${asset}-${w}.jpg`;
+  return `${asset}.${kind}`;
+}
+
+/**
+ * Resolve R2/object keys from identity + optional naming strategy.
+ * NO brand/asset identity branches — leaf names are generic or explicit.
+ */
+export function resolveKeyLayout({
+  brand,
+  asset,
+  version,
+  naming = {},
+  derivatives = [],
+} = {}) {
+  const base = brandAssetPrefix({ brand, asset, version, naming });
+  const assetId = cleanSegment(asset, 'asset');
+  const files = typeof naming.files === 'function'
+    ? naming.files({ brand, asset: assetId, version, base })
+    : (naming.files || {});
+
+  const layout = {
+    prefix: base,
+    convention: naming.convention || 'brands',
+    source: `${base}/source/${files.source || leafFor(assetId, 'master')}`,
+    vector: {
+      mark: `${base}/vector/${files.mark || leafFor(assetId, 'mark')}`,
+    },
+    native: {
+      icns: `${base}/native/${files.icns || leafFor(assetId, 'icns')}`,
+    },
+    derivatives: {},
+    manifest: `${base}/manifest.json`,
+  };
+
+  for (const d of derivatives) {
+    const id = d.id || `${d.format}-${d.width || d.size || 'x'}`;
+    const folder = d.role === 'web' || d.format === 'webp' || d.format === 'avif' ? 'web' : 'raster';
+    const filename = d.filename
+      || files[id]
+      || leafFor(assetId, d.format, { width: d.width || d.size, height: d.height || d.size });
+    layout.derivatives[id] = `${base}/${folder}/${filename}`;
+  }
+
+  return Object.freeze(layout);
+}

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

@@ -0,0 +1,142 @@
+/**
+ * Semantic delivery naming — human-readable aliases.
+ * Machine identity remains asset.id (ast_…). Filename is never the identity.
+ *
+ * Discipline: readable + contextual — never keyword-stuffed SEO spam.
+ */
+
+const STOP = new Set([
+  'best', 'cheap', 'near', 'me', 'the', 'a', 'an', 'and', 'or', 'of', 'for',
+  'to', 'in', 'on', 'with', 'company', 'services', 'service',
+]);
+
+export function slugifySegment(value, { maxWords = 6 } = {}) {
+  const raw = String(value || '')
+    .toLowerCase()
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  const words = raw.split('-').filter((w) => w && !STOP.has(w) && w.length < 32);
+  return words.slice(0, maxWords).join('-');
+}
+
+/**
+ * Build a delivery alias slug from brand + role + semantic context.
+ * @example agentsam-software-workspace-hero
+ */
+export function buildSemanticSlug({
+  brandId,
+  role,
+  subject = [],
+  page,
+  section,
+  locale,
+  strategy = 'semantic',
+} = {}) {
+  if (strategy === 'identity') {
+    return null; // caller uses asset id only
+  }
+
+  const parts = [];
+  if (brandId) parts.push(slugifySegment(brandId, { maxWords: 4 }));
+
+  const roleTail = String(role || '')
+    .split('.')
+    .filter(Boolean)
+    .slice(-2)
+    .join('-');
+  if (roleTail) parts.push(slugifySegment(roleTail, { maxWords: 3 }));
+
+  const subjects = Array.isArray(subject) ? subject : [subject];
+  for (const s of subjects.slice(0, 2)) {
+    const seg = slugifySegment(s, { maxWords: 3 });
+    if (seg && !parts.join('-').includes(seg)) parts.push(seg);
+  }
+
+  if (page) {
+    const p = slugifySegment(page, { maxWords: 3 });
+    if (p && !parts.includes(p)) parts.push(p);
+  }
+  if (section && section !== 'hero' && section !== 'main') {
+    const s = slugifySegment(section, { maxWords: 2 });
+    if (s && !parts.includes(s)) parts.push(s);
+  }
+
+  let slug = parts.filter(Boolean).join('-').replace(/-+/g, '-');
+  if (locale && locale !== 'en' && locale !== 'en-US') {
+    slug = `${slug}-${slugifySegment(locale, { maxWords: 2 })}`;
+  }
+
+  // Hard cap — readable, not a keyword dump
+  const tokens = slug.split('-').filter(Boolean);
+  if (tokens.length > 8) slug = tokens.slice(0, 8).join('-');
+  if (slug.length > 80) slug = slug.slice(0, 80).replace(/-$/, '');
+
+  return slug || 'asset';
+}
+
+/**
+ * Width-suffixed delivery alias.
+ * acme-showroom-hero-1280.avif
+ */
+export function buildDerivativeFilename(slug, { width, format, dpr } = {}) {
+  const ext = String(format || 'webp').toLowerCase().replace('jpeg', 'jpg');
+  let base = slug || 'asset';
+  if (width) base = `${base}-${width}`;
+  if (dpr && dpr > 1) base = `${base}@${dpr}x`;
+  return `${base}.${ext}`;
+}
+
+/**
+ * Reject obvious keyword-stuffed proposals.
+ */
+export function validateDeliveryName(name) {
+  const warnings = [];
+  const base = String(name || '').replace(/\.[a-z0-9]+$/i, '');
+  const parts = base.split('-').filter(Boolean);
+  if (parts.length > 10) warnings.push('too_many_segments');
+  if (base.length > 96) warnings.push('name_too_long');
+  const spam = parts.filter((p) => STOP.has(p) || /^(seo|keyword|rank|best|cheap)$/.test(p));
+  if (spam.length >= 2) warnings.push('keyword_stuffing');
+  if (/^\d+$/.test(base) || /^img[_-]?\d+/i.test(base)) warnings.push('opaque_camera_name');
+  return { ok: warnings.length === 0, warnings };
+}
+
+/**
+ * Enrich an asset node with naming + semantic fields (non-destructive).
+ */
+export function applySemanticNaming(asset, context = {}) {
+  const semantic = {
+    subject: context.subject || asset.semantic?.subject || [],
+    page: context.page || asset.semantic?.page || null,
+    section: context.section || asset.semantic?.section || null,
+    locale: context.locale || asset.semantic?.locale || 'en-US',
+    intent: context.intent || asset.semantic?.intent || null,
+  };
+
+  const slug = buildSemanticSlug({
+    brandId: context.brandId || context.brand,
+    role: asset.role,
+    subject: semantic.subject,
+    page: semantic.page,
+    section: semantic.section,
+    locale: semantic.locale,
+    strategy: context.strategy || 'semantic',
+  });
+
+  const check = validateDeliveryName(slug);
+
+  return {
+    ...asset,
+    semantic: { ...asset.semantic, ...semantic },
+    naming: {
+      slug,
+      strategy: context.strategy || 'semantic',
+      aliases: asset.naming?.aliases || [],
+      validation: check,
+      ...(asset.naming || {}),
+      slug, // ensure latest wins
+    },
+  };
+}

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

@@ -0,0 +1,316 @@
+/**
+ * agentsam brand optimize — role-aware optimization without exposing encoders.
+ *
+ * Flow: inspect → classify path → plan formats → schedule processor → receipt
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { inspectBrandAsset } from './inspect.js';
+import { getAssetRole } from './v2/roles.js';
+import { planSemanticDerivatives } from './v2/derivatives-semantic.js';
+import {
+  discoverProcessors,
+  optimizeWithScheduler,
+  encodeWithScheduler,
+  resolveProcessor,
+} from './processors/index.js';
+import {
+  applySemanticNaming,
+  buildDerivativeFilename,
+  buildSemanticSlug,
+} from './naming.js';
+import { assert } from './errors.js';
+
+/**
+ * Role → encode policy (not a global "quality 80").
+ */
+export function optimizePolicyForRole(role, meta = {}) {
+  const def = getAssetRole(role) || {};
+  const family = def.family || 'raster';
+  const alpha = Boolean(meta.alpha);
+
+  if (family === 'logo' || role?.startsWith('logo.') || role === 'favicon') {
+    return {
+      keep_master: true,
+      formats: alpha ? ['png', 'webp'] : ['webp', 'png'],
+      lossless_preferred: true,
+      quality: null,
+      cqLevel: null,
+      materialize_widths: [],
+      note: 'logo/vector-preserving path — prefer SVG master when available',
+    };
+  }
+
+  if (family === 'hero' || role?.startsWith('hero.') || role?.startsWith('social.')) {
+    return {
+      keep_master: true,
+      formats: ['avif', 'webp'],
+      lossless_preferred: false,
+      quality: 82,
+      cqLevel: 28,
+      materialize_widths: [1280, 1920],
+      note: 'photographic / hero delivery — AVIF + WebP; master retained for CF',
+    };
+  }
+
+  if (role?.includes('screenshot') || role?.startsWith('product.')) {
+    return {
+      keep_master: true,
+      formats: ['webp', 'avif'],
+      lossless_preferred: true,
+      quality: 90,
+      cqLevel: 24,
+      materialize_widths: [960, 1600],
+      note: 'UI/screenshot — sharper WebP/AVIF',
+    };
+  }
+
+  if (family === 'icon' || role?.startsWith('icon.')) {
+    return {
+      keep_master: true,
+      formats: ['png', 'webp'],
+      lossless_preferred: true,
+      quality: null,
+      cqLevel: null,
+      materialize_widths: [512, 1024],
+      note: 'app icon ladder — lossless-ish',
+    };
+  }
+
+  return {
+    keep_master: true,
+    formats: alpha ? ['webp', 'png'] : ['avif', 'webp'],
+    lossless_preferred: alpha,
+    quality: 80,
+    cqLevel: 30,
+    materialize_widths: [],
+    note: 'generic raster policy',
+  };
+}
+
+/**
+ * Optimize a source file into role-aware delivery candidates.
+ */
+export async function optimizeBrandAsset({
+  sourcePath,
+  role = 'asset.generic',
+  target = 'web',
+  brandId = '',
+  outDir,
+  processor,
+  dryRun = false,
+  semantic = {},
+  widths,
+} = {}) {
+  assert(sourcePath && fs.existsSync(sourcePath), 'source_missing', `Source missing: ${sourcePath}`);
+
+  const meta = inspectBrandAsset(sourcePath, { role });
+  const policy = optimizePolicyForRole(role, meta);
+  const discovery = discoverProcessors();
+
+  const slug = buildSemanticSlug({
+    brandId,
+    role,
+    subject: semantic.subject,
+    page: semantic.page,
+    section: semantic.section,
+    locale: semantic.locale,
+  });
+
+  const assetDraft = applySemanticNaming(
+    { id: `ast_${meta.sha256?.slice(7, 15) || Date.now().toString(36)}`, role, master: { path: sourcePath } },
+    { brandId, ...semantic },
+  );
+
+  const plan = {
+    role,
+    target,
+    policy,
+    naming: assetDraft.naming,
+    semantic: assetDraft.semantic,
+    source: {
+      path: sourcePath,
+      bytes: meta.bytes,
+      width: meta.width,
+      height: meta.height,
+      content_type: meta.content_type,
+      alpha: meta.alpha,
+      sha256: meta.sha256,
+    },
+    processors: discovery,
+    candidates: [],
+    artifacts: [],
+  };
+
+  if (target === 'cloudflare' || target === 'cf') {
+    plan.delivery = {
+      provider: 'cloudflare-images',
+      strategy: 'retain_master_edge_derive',
+      note: 'Upload high-quality master; let CF negotiate AVIF/WebP',
+    };
+    const edge = await resolveProcessor({ delivery: 'cloudflare-images', prefer_edge: true }, { force: 'cloudflare' });
+    for (const format of policy.formats) {
+      const edgePlan = await edge.encode(sourcePath, { format, quality: policy.quality });
+      plan.candidates.push({
+        format,
+        ...edgePlan,
+        filename: buildDerivativeFilename(slug, { format }),
+      });
+    }
+    if (dryRun) return { ok: true, dry_run: true, ...plan };
+    return { ok: true, ...plan, asset: assetDraft };
+  }
+
+  const destRoot = outDir || path.join(path.dirname(sourcePath), '.agentsam-optimize');
+  if (!dryRun) fs.mkdirSync(destRoot, { recursive: true });
+
+  const encodeWidths = widths || policy.materialize_widths || [];
+  const formats = policy.formats;
+
+  for (const format of formats) {
+    const filename = buildDerivativeFilename(slug, { format });
+    const outPath = path.join(destRoot, filename);
+    const candidate = {
+      format,
+      filename,
+      outPath,
+      status: dryRun ? 'planned' : 'pending',
+    };
+
+    if (dryRun) {
+      plan.candidates.push(candidate);
+      continue;
+    }
+
+    try {
+      const result = await encodeWithScheduler(sourcePath, {
+        format,
+        quality: policy.quality,
+        cqLevel: policy.cqLevel,
+        lossless: policy.lossless_preferred && (format === 'png' || format === 'webp'),
+        auto: format === 'webp' || format === 'avif' ? undefined : undefined,
+        outPath,
+        processor,
+        preserve_alpha: meta.alpha,
+      });
+      const savings = meta.bytes > 0
+        ? Number((((meta.bytes - result.bytes) / meta.bytes) * 100).toFixed(1))
+        : null;
+      plan.candidates.push({
+        ...candidate,
+        status: 'generated',
+        ...result,
+        savings_pct: savings,
+        receipt: {
+          processor: result.processor,
+          version: result.processor_version || null,
+          encoder: format,
+          options: result.options,
+        },
+      });
+      plan.artifacts.push(result.path);
+    } catch (err) {
+      // Try optimize path as fallback once
+      try {
+        const result = await optimizeWithScheduler(sourcePath, {
+          format,
+          quality: policy.quality,
+          outPath,
+          processor,
+        });
+        plan.candidates.push({
+          ...candidate,
+          status: 'generated',
+          ...result,
+          savings_pct: meta.bytes > 0
+            ? Number((((meta.bytes - result.bytes) / meta.bytes) * 100).toFixed(1))
+            : null,
+        });
+        plan.artifacts.push(result.path);
+      } catch (err2) {
+        plan.candidates.push({
+          ...candidate,
+          status: 'failed',
+          error: err2?.message || err?.message || String(err2 || err),
+        });
+      }
+    }
+  }
+
+  // Optional width materialization (first format only — keep lean)
+  const primaryFormat = formats[0];
+  for (const w of encodeWidths) {
+    const filename = buildDerivativeFilename(slug, { width: w, format: primaryFormat });
+    const outPath = path.join(destRoot, filename);
+    if (dryRun) {
+      plan.candidates.push({ format: primaryFormat, width: w, filename, status: 'planned' });
+      continue;
+    }
+    try {
+      const proc = await resolveProcessor({ format: primaryFormat }, { force: processor });
+      const resized = path.join(destRoot, `.tmp-${w}.png`);
+      if (typeof proc.resize === 'function') {
+        await proc.resize(sourcePath, { width: w, outPath: resized });
+        const encoded = await encodeWithScheduler(resized, {
+          format: primaryFormat,
+          quality: policy.quality,
+          cqLevel: policy.cqLevel,
+          outPath,
+          processor,
+        });
+        try {
+          fs.unlinkSync(resized);
+        } catch {
+          /* ignore */
+        }
+        plan.candidates.push({
+          format: primaryFormat,
+          width: w,
+          filename,
+          status: 'generated',
+          ...encoded,
+        });
+        plan.artifacts.push(encoded.path);
+      }
+    } catch (err) {
+      plan.candidates.push({
+        format: primaryFormat,
+        width: w,
+        filename,
+        status: 'failed',
+        error: err?.message || String(err),
+      });
+    }
+  }
+
+  // Comparison summary for Studio slider
+  const best = plan.candidates
+    .filter((c) => c.status === 'generated' && c.bytes != null)
+    .sort((a, b) => a.bytes - b.bytes)[0] || null;
+
+  plan.comparison = best
+    ? {
+        original: { bytes: meta.bytes, format: meta.content_type, width: meta.width, height: meta.height },
+        optimized: {
+          bytes: best.bytes,
+          format: best.format,
+          width: best.width,
+          height: best.height,
+          processor: best.processor,
+          savings_pct: best.savings_pct,
+        },
+      }
+    : null;
+
+  // Attach semantic derivative planner for pack consumers
+  plan.semantic_derivatives = planSemanticDerivatives(role, { materialize: 'pack' });
+
+  return {
+    ok: plan.candidates.some((c) => c.status === 'generated' || c.status === 'planned'),
+    dry_run: dryRun,
+    out_dir: destRoot,
+    asset: assetDraft,
+    ...plan,
+  };
+}