@inneranimalmedia/agentsam-sdk 2.6.4 → 2.6.7

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

@@ -0,0 +1,305 @@
+/**
+ * Brand pack — materialize slug-keyed folder + zip + gallery.html
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import zlib from 'node:zlib';
+import { spawnSync } from 'node:child_process';
+import { BrandAssetError, assert } from './errors.js';
+import { brandAssetPrefix } from './keys.js';
+import { FORMAT_CAPABILITIES, formatCapabilities } from './capabilities.js';
+import { deriveBrandAssets } from './derivatives.js';
+import { getDerivativePreset } from '../presets/index.js';
+import { inspectBrandAsset } from './inspect.js';
+
+function crc32(buf) {
+  let c = ~0;
+  for (let i = 0; i < buf.length; i += 1) {
+    c ^= buf[i];
+    for (let k = 0; k < 8; k += 1) {
+      c = (c >>> 1) ^ (0xedb88320 & -(c & 1));
+    }
+  }
+  return ~c >>> 0;
+}
+
+/** Minimal ZIP (store + deflate) writer — no new dependencies. */
+export function writeZipArchive(entries, outPath) {
+  const parts = [];
+  const central = [];
+  let offset = 0;
+
+  for (const entry of entries) {
+    const name = String(entry.name).replace(/\\/g, '/').replace(/^\/+/, '');
+    const data = Buffer.isBuffer(entry.data) ? entry.data : Buffer.from(entry.data || '');
+    const nameBuf = Buffer.from(name, 'utf8');
+    const compressed = zlib.deflateRawSync(data);
+    const useStore = compressed.length >= data.length;
+    const payload = useStore ? data : compressed;
+    const method = useStore ? 0 : 8;
+    const crc = crc32(data);
+
+    const local = Buffer.alloc(30);
+    local.writeUInt32LE(0x04034b50, 0);
+    local.writeUInt16LE(20, 4);
+    local.writeUInt16LE(0, 6);
+    local.writeUInt16LE(method, 8);
+    local.writeUInt16LE(0, 10);
+    local.writeUInt16LE(0, 12);
+    local.writeUInt32LE(crc, 14);
+    local.writeUInt32LE(payload.length, 18);
+    local.writeUInt32LE(data.length, 22);
+    local.writeUInt16LE(nameBuf.length, 26);
+    local.writeUInt16LE(0, 28);
+
+    parts.push(local, nameBuf, payload);
+
+    const cen = Buffer.alloc(46);
+    cen.writeUInt32LE(0x02014b50, 0);
+    cen.writeUInt16LE(20, 4);
+    cen.writeUInt16LE(20, 6);
+    cen.writeUInt16LE(0, 8);
+    cen.writeUInt16LE(method, 10);
+    cen.writeUInt16LE(0, 12);
+    cen.writeUInt16LE(0, 14);
+    cen.writeUInt32LE(crc, 16);
+    cen.writeUInt32LE(payload.length, 20);
+    cen.writeUInt32LE(data.length, 24);
+    cen.writeUInt16LE(nameBuf.length, 28);
+    cen.writeUInt16LE(0, 30);
+    cen.writeUInt16LE(0, 32);
+    cen.writeUInt16LE(0, 34);
+    cen.writeUInt16LE(0, 36);
+    cen.writeUInt32LE(0, 38);
+    cen.writeUInt32LE(offset, 42);
+    central.push(cen, nameBuf);
+
+    offset += local.length + nameBuf.length + payload.length;
+  }
+
+  const centralStart = offset;
+  const centralBuf = Buffer.concat(central);
+  const end = Buffer.alloc(22);
+  end.writeUInt32LE(0x06054b50, 0);
+  end.writeUInt16LE(0, 4);
+  end.writeUInt16LE(0, 6);
+  end.writeUInt16LE(entries.length, 8);
+  end.writeUInt16LE(entries.length, 10);
+  end.writeUInt32LE(centralBuf.length, 12);
+  end.writeUInt32LE(centralStart, 16);
+  end.writeUInt16LE(0, 20);
+
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  fs.writeFileSync(outPath, Buffer.concat([...parts, centralBuf, end]));
+  return outPath;
+}
+
+export function buildGalleryHtml({ brand, asset, version, items = [] } = {}) {
+  const cards = items.map((it) => {
+    const rel = String(it.rel || it.path || '').replace(/\\/g, '/');
+    const label = it.label || path.basename(rel);
+    const isSvg = /\.svg$/i.test(rel);
+    const media = isSvg
+      ? `<object type="image/svg+xml" data="./${rel}" aria-label="${label}"></object>`
+      : `<img src="./${rel}" alt="${label}" loading="lazy" />`;
+    return `<figure class="card"><div class="frame">${media}</div><figcaption>${label}<br/><small>${it.dims || ''} ${it.bytes_label || ''}</small></figcaption></figure>`;
+  }).join('\n');
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>${brand} / ${asset} / ${version} — brand pack</title>
+  <style>
+    :root { color-scheme: dark; --bg:#0a0a0c; --fg:#e8e6e3; --muted:#8a8580; --line:#2a2a32; }
+    * { box-sizing: border-box; }
+    body { margin:0; font-family: ui-sans-serif, system-ui, sans-serif; background:var(--bg); color:var(--fg); padding:32px; }
+    h1 { font-size:1.4rem; font-weight:560; margin:0 0 8px; }
+    p { color:var(--muted); margin:0 0 24px; }
+    .grid { display:grid; grid-template-columns:repeat(auto-fill,minmax(180px,1fr)); gap:16px; }
+    .card { margin:0; border:1px solid var(--line); border-radius:10px; overflow:hidden; background:#121216; }
+    .frame { aspect-ratio:1; display:grid; place-items:center; padding:12px; background:
+      linear-gradient(45deg,#1a1a20 25%,transparent 25%),
+      linear-gradient(-45deg,#1a1a20 25%,transparent 25%),
+      linear-gradient(45deg,transparent 75%,#1a1a20 75%),
+      linear-gradient(-45deg,transparent 75%,#1a1a20 75%);
+      background-size:16px 16px; background-position:0 0,0 8px,8px -8px,-8px 0; }
+    .frame img, .frame object { max-width:100%; max-height:100%; }
+    figcaption { padding:10px 12px; font-size:0.78rem; border-top:1px solid var(--line); color:var(--muted); }
+    small { opacity:0.8; }
+  </style>
+</head>
+<body>
+  <h1>${brand} · ${asset} · ${version}</h1>
+  <p>Brand pack preview — ${items.length} asset(s). Open this file or serve the pack folder.</p>
+  <div class="grid">
+${cards}
+  </div>
+</body>
+</html>
+`;
+}
+
+function formatBytesLabel(bytes) {
+  const n = Number(bytes) || 0;
+  if (n < 1024) return `${n} B`;
+  return `${(n / 1024).toFixed(n >= 10240 ? 0 : 1)} KB`;
+}
+
+/**
+ * Build a brand pack directory (and optional zip).
+ */
+export async function buildBrandPack({
+  brand,
+  asset,
+  version = 'v1',
+  sourcePath,
+  markPath = null,
+  preset = 'app-icon',
+  derivatives = null,
+  outDir,
+  zipPath = null,
+  altText = '',
+  title = '',
+  description = '',
+  cwd = process.cwd(),
+} = {}) {
+  assert(brand && asset, 'identity_required', 'brand and asset are required');
+  assert(sourcePath || markPath, 'source_required', 'sourcePath or markPath required');
+
+  const prefix = brandAssetPrefix({ brand, asset, version });
+  const root = path.resolve(outDir || path.join(cwd, '.agentsam', 'brand', 'packs', brand, asset, version));
+  fs.rmSync(root, { recursive: true, force: true });
+  fs.mkdirSync(root, { recursive: true });
+
+  const sourceDir = path.join(root, 'source');
+  const rasterDir = path.join(root, 'raster');
+  const vectorDir = path.join(root, 'vector');
+  const platformDir = path.join(root, 'platform');
+  for (const d of [sourceDir, rasterDir, vectorDir, platformDir]) fs.mkdirSync(d, { recursive: true });
+
+  const galleryItems = [];
+  let deriveResult = { artifacts: [] };
+
+  if (sourcePath && fs.existsSync(sourcePath)) {
+    const ext = path.extname(sourcePath) || '.png';
+    const dest = path.join(sourceDir, `${asset}-master${ext}`);
+    fs.copyFileSync(sourcePath, dest);
+    const insp = inspectBrandAsset(dest, { role: 'source' });
+    galleryItems.push({
+      rel: path.relative(root, dest),
+      label: `source · ${path.basename(dest)}`,
+      dims: insp.width ? `${insp.width}×${insp.height}` : '',
+      bytes_label: formatBytesLabel(insp.bytes),
+    });
+
+    const derivs = derivatives
+      || getDerivativePreset(preset)?.derivatives
+      || getDerivativePreset('app-icon')?.derivatives
+      || [];
+
+    const workDerive = path.join(root, '.derive-work');
+    deriveResult = await deriveBrandAssets({
+      sourcePath: dest,
+      outDir: workDerive,
+      derivatives: derivs,
+      asset,
+    });
+
+    for (const art of deriveResult.artifacts || []) {
+      if (art.status !== 'generated' || !art.path) continue;
+      const folder = art.format === 'ico' || art.format === 'icns'
+        ? platformDir
+        : (art.format === 'webp' || art.format === 'avif' ? path.join(root, 'web') : rasterDir);
+      fs.mkdirSync(folder, { recursive: true });
+      const leaf = path.basename(art.path);
+      const destArt = path.join(folder, leaf);
+      fs.copyFileSync(art.path, destArt);
+      galleryItems.push({
+        rel: path.relative(root, destArt),
+        label: `${art.id || leaf}`,
+        dims: art.width ? `${art.width}×${art.height}` : '',
+        bytes_label: formatBytesLabel(art.bytes),
+      });
+    }
+    fs.rmSync(workDerive, { recursive: true, force: true });
+  }
+
+  if (markPath && fs.existsSync(markPath)) {
+    const dest = path.join(vectorDir, `${asset}-mark.svg`);
+    fs.copyFileSync(markPath, dest);
+    galleryItems.push({
+      rel: path.relative(root, dest),
+      label: 'vector · mark',
+      dims: '',
+      bytes_label: formatBytesLabel(fs.statSync(dest).size),
+    });
+  }
+
+  const manifest = {
+    schema: 'agentsam.brand-pack.v1',
+    brand: String(brand).toLowerCase(),
+    asset: String(asset).toLowerCase(),
+    version: String(version).toLowerCase(),
+    prefix,
+    preset: preset || null,
+    seo: {
+      alt_text: altText || null,
+      title: title || null,
+      description: description || null,
+    },
+    format_capabilities: FORMAT_CAPABILITIES,
+    artifacts: galleryItems.map((g) => ({
+      path: g.rel,
+      label: g.label,
+      capabilities: formatCapabilities(path.extname(g.rel).slice(1)),
+    })),
+    created_at: new Date().toISOString(),
+  };
+  fs.writeFileSync(path.join(root, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`);
+
+  const galleryHtml = buildGalleryHtml({
+    brand: manifest.brand,
+    asset: manifest.asset,
+    version: manifest.version,
+    items: galleryItems,
+  });
+  fs.writeFileSync(path.join(root, 'gallery.html'), galleryHtml);
+
+  let zip = null;
+  if (zipPath) {
+    const absZip = path.resolve(zipPath);
+    const entries = [];
+    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 entries.push({ name: `${prefix}/${rel}`, data: fs.readFileSync(full) });
+      }
+    };
+    walk(root);
+    // Prefer system zip when available for better tooling; fall back to pure JS
+    const tmpListDir = root;
+    const zipCmd = spawnSync('zip', ['-r', '-q', absZip, '.'], { cwd: tmpListDir, encoding: 'utf8' });
+    if (zipCmd.status === 0 && fs.existsSync(absZip)) {
+      zip = absZip;
+    } else {
+      writeZipArchive(entries, absZip);
+      zip = absZip;
+    }
+  }
+
+  return {
+    ok: true,
+    capability: 'brand.pack',
+    root,
+    zip,
+    prefix,
+    manifest,
+    gallery: path.join(root, 'gallery.html'),
+    item_count: galleryItems.length,
+    derive: deriveResult,
+  };
+}

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

@@ -0,0 +1,276 @@
+import path from 'node:path';
+import { BRAND_ASSETS_SCHEMA, resolveKeyLayout } from './keys.js';
+import { inspectBrandAsset, isExcludedIntermediate } from './inspect.js';
+import { formatBytesKb } from './derivatives.js';
+import { assert } from './errors.js';
+
+/**
+ * Normalize promotion input into a generic manifest/plan.
+ * Accepts either a full promotion spec or CLI-ish options.
+ */
+export function normalizePromotionSpec(input = {}) {
+  const brand = String(input.brand || '').trim();
+  const asset = String(input.asset || '').trim();
+  const version = String(input.version || 'v1').trim();
+  assert(brand, 'brand_required', 'brand is required');
+  assert(asset, 'asset_required', 'asset is required');
+
+  const inputs = Array.isArray(input.inputs)
+    ? input.inputs.map((row, i) => ({
+      id: row.id || `input-${i}`,
+      role: row.role || 'source',
+      path: row.path,
+      filename: row.filename || null,
+    }))
+    : buildInputsFromLegacyFlags(input);
+
+  let derivatives = Array.isArray(input.derivatives) ? [...input.derivatives] : [];
+  if (!derivatives.length && Array.isArray(input.derive)) {
+    derivatives = input.derive.map(parseDeriveFlag);
+  }
+
+  const destinations = input.destinations || {
+    storage: input.storage
+      ? input.storage
+      : input.storageBinding || input.bucket
+        ? {
+          provider: input.bucket && !input.storageBinding ? 'cloudflare-r2' : 'cloudflare-r2',
+          binding: input.storageBinding || null,
+          bucket: input.bucket || null,
+        }
+        : null,
+    delivery: input.imageDelivery || input.delivery || null,
+    registry: input.registry || null,
+  };
+
+  return {
+    schema: input.schema || BRAND_ASSETS_SCHEMA,
+    brand,
+    asset,
+    version,
+    naming: input.naming || (input.prefix ? { prefix: input.prefix, convention: input.convention || 'custom' } : { convention: input.convention || 'brands' }),
+    inputs,
+    derivatives,
+    destinations,
+    seo: input.seo || {
+      alt_text: input.alt_text || input.alt || null,
+      title: input.title || null,
+      description: input.description || null,
+    },
+  };
+}
+
+function buildInputsFromLegacyFlags(input) {
+  const rows = [];
+  if (input.source) rows.push({ id: 'source', role: 'source', path: input.source });
+  if (input.mark || input.svg) rows.push({ id: 'mark', role: 'vector.mark', path: input.mark || input.svg });
+  if (input.icns) rows.push({ id: 'icns', role: 'native.icon', path: input.icns });
+  // Optional pre-built primary raster
+  if (input.png || input.icon) rows.push({ id: 'raster-primary', role: 'raster.primary', path: input.png || input.icon });
+  if (input.webp) rows.push({ id: 'webp', role: 'web.webp', path: input.webp });
+  if (input.avif) rows.push({ id: 'avif', role: 'web.avif', path: input.avif });
+  return rows;
+}
+
+/** Parse --derive png:1024 or webp:1024:q92 */
+export function parseDeriveFlag(value) {
+  const raw = String(value || '').trim();
+  const parts = raw.split(':');
+  const format = parts[0];
+  const size = Number(parts[1]) || null;
+  let quality = null;
+  for (const p of parts.slice(2)) {
+    if (/^q\d+$/i.test(p)) quality = Number(p.slice(1));
+  }
+  return {
+    id: `${format}-${size || 'x'}`,
+    role: format === 'webp' || format === 'avif' ? 'web' : 'raster',
+    format,
+    width: size,
+    height: size,
+    quality,
+  };
+}
+
+/**
+ * Plan a brand asset promotion. Pure-ish: inspects local files, no writes.
+ * Delivery/storage adapters are optional for capability negotiation.
+ */
+export async function planBrandAssetPromotion(input = {}, options = {}) {
+  const spec = normalizePromotionSpec(input);
+  const delivery = options.deliveryAdapter || null;
+
+  const inspectedInputs = [];
+  const rejected = [];
+  for (const row of spec.inputs) {
+    if (!row.path) continue;
+    if (isExcludedIntermediate(row.path)) {
+      rejected.push({ path: row.path, reason: 'intermediate_artifact' });
+      continue;
+    }
+    const inspected = inspectBrandAsset(row.path, { role: row.role });
+    inspectedInputs.push({ ...row, ...inspected });
+  }
+
+  const keys = resolveKeyLayout({
+    brand: spec.brand,
+    asset: spec.asset,
+    version: spec.version,
+    naming: spec.naming,
+    derivatives: spec.derivatives,
+  });
+
+  const objects = [];
+  for (const row of inspectedInputs) {
+    let key;
+    if (row.role === 'source') key = keys.source;
+    else if (row.role === 'vector.mark') key = keys.vector.mark;
+    else if (row.role === 'native.icon') key = keys.native.icns;
+    else if (row.role === 'raster.primary') {
+      key = keys.derivatives['png-1024']
+        || `${keys.prefix}/raster/${path.basename(row.path)}`;
+    } else {
+      key = `${keys.prefix}/${row.role.replace(/\./g, '/')}/${row.filename || path.basename(row.path)}`;
+    }
+
+    let deliveryEligible = false;
+    if (delivery && typeof delivery.supports === 'function') {
+      deliveryEligible = Boolean(await delivery.supports({
+        contentType: row.content_type,
+        role: row.role,
+      }));
+    }
+
+    objects.push({
+      id: row.id,
+      role: row.role,
+      key,
+      local_path: row.path,
+      content_type: row.content_type,
+      bytes: row.bytes,
+      size_label: formatBytesKb(row.bytes),
+      sha256: row.sha256,
+      width: row.width,
+      height: row.height,
+      alpha: row.alpha,
+      // Eligibility for a delivery adapter — NOT proof of publish
+      delivery_eligible: deliveryEligible,
+    });
+  }
+
+  // Planned derivative slots (not yet generated — derive step fills paths)
+  const plannedDerivatives = spec.derivatives.map((d) => {
+    const id = d.id || `${d.format}-${d.width || d.size || 'x'}`;
+    return {
+      id,
+      role: d.role || 'raster',
+      format: d.format,
+      width: d.width || d.size || null,
+      height: d.height || d.size || null,
+      quality: d.quality ?? null,
+      key: keys.derivatives[id] || null,
+      status: 'planned',
+    };
+  });
+
+  const wouldWrite = {
+    storage_objects: objects.length + plannedDerivatives.length + 1,
+    registry_rows: objects.length + plannedDerivatives.length,
+    delivery_candidates: objects.filter((o) => o.delivery_eligible).length,
+    manifest: 1,
+  };
+
+  return {
+    schema: BRAND_ASSETS_SCHEMA,
+    capability: 'brand.plan',
+    brand: spec.brand,
+    asset: spec.asset,
+    version: spec.version,
+    naming: spec.naming,
+    keys,
+    inputs: inspectedInputs,
+    objects,
+    derivatives: plannedDerivatives,
+    destinations: spec.destinations,
+    rejected,
+    would_write: wouldWrite,
+    manifest_draft: createBrandAssetManifest({
+      spec,
+      keys,
+      objects,
+      derivatives: plannedDerivatives,
+    }),
+  };
+}
+
+export function createBrandAssetManifest({
+  spec,
+  keys,
+  objects,
+  derivatives,
+  storage = null,
+  delivery = null,
+} = {}) {
+  const source = objects.find((o) => o.role === 'source');
+  const mark = objects.find((o) => o.role === 'vector.mark');
+
+  // Normalize delivery — never invent CF Images identity from R2 keys
+  let deliveryBlock = null;
+  if (delivery) {
+    const status = delivery.status
+      || (delivery.dry_run ? 'planned' : null)
+      || (delivery.skipped ? 'skipped' : null)
+      || (delivery.ok === false ? 'failed' : null)
+      || (delivery.provider_receipt?.provider_asset_id || delivery.provider_receipt?.image_id ? 'published' : null)
+      || 'unknown';
+    const assetId = delivery.provider_receipt?.provider_asset_id
+      || delivery.provider_receipt?.image_id
+      || null;
+    deliveryBlock = {
+      provider: delivery.provider || null,
+      status,
+      // Only present when status === published with real id
+      provider_asset_id: status === 'published' ? assetId : null,
+      account_id: status === 'published'
+        ? (delivery.provider_receipt?.account_id || null)
+        : (delivery.account_id || null),
+      account_hash: status === 'published'
+        ? (delivery.provider_receipt?.account_hash || null)
+        : (delivery.account_hash || null),
+      delivery_base: status === 'published'
+        ? (delivery.provider_receipt?.delivery_base || null)
+        : null,
+      variants: status === 'published' ? (delivery.provider_receipt?.variants || []) : [],
+      source: delivery.provider_receipt?.source || delivery.source || null,
+      error: delivery.error || null,
+      reason: delivery.reason || null,
+    };
+  }
+
+  return {
+    schema: BRAND_ASSETS_SCHEMA,
+    brand: spec.brand,
+    asset: spec.asset,
+    version: spec.version,
+    prefix: keys.prefix,
+    convention: keys.convention,
+    master: source
+      ? {
+        key: source.key,
+        format: source.content_type,
+        width: source.width,
+        height: source.height,
+        alpha: source.alpha,
+        sha256: source.sha256,
+      }
+      : null,
+    vector: mark ? { mark: mark.key } : null,
+    derivatives: Object.fromEntries(
+      (derivatives || []).filter((d) => d.key).map((d) => [d.id, { key: d.key, format: d.format, width: d.width, height: d.height }]),
+    ),
+    // STORAGE ≠ DELIVERY — never collapse these
+    storage: storage || spec.destinations?.storage || null,
+    delivery: deliveryBlock,
+    destinations: spec.destinations || null,
+  };
+}