@inneranimalmedia/agentsam-sdk 2.6.1 → 2.6.3

package/packages/agentsam-brand/src/extract.js

@@ -0,0 +1,126 @@
+/**
+ * Color / token helpers — pure, deterministic.
+ */
+
+const HEX_RE = /#([0-9a-fA-F]{3,8})\b/g;
+const RGB_RE = /\brgba?\(\s*([0-9.]+)\s*,\s*([0-9.]+)\s*,\s*([0-9.]+)(?:\s*,\s*([0-9.]+))?\s*\)/gi;
+const CSS_VAR_RE = /--([a-zA-Z0-9_-]+)\s*:\s*([^;}+]+)/g;
+const TAILWIND_COLOR_RE = /\b(?:text|bg|border|ring|fill|stroke|from|via|to)-(?:\[(?:#[0-9a-fA-F]{3,8})\]|(?:slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)-(?:50|100|200|300|400|500|600|700|800|900|950))\b/g;
+const FONT_FAMILY_RE = /font-family\s*:\s*([^;}+]+)/gi;
+const FONT_SIZE_RE = /font-size\s*:\s*([^;}+]+)/gi;
+const RADIUS_RE = /border-radius\s*:\s*([^;}+]+)/gi;
+const SHADOW_RE = /box-shadow\s*:\s*([^;}+]+)/gi;
+const SPACING_RE = /(?:padding|margin|gap|letter-spacing)\s*:\s*([^;}+]+)/gi;
+
+export function expandHex(hex) {
+  const h = String(hex || '').replace(/^#/, '').toLowerCase();
+  if (h.length === 3 || h.length === 4) {
+    return `#${h.split('').map((c) => c + c).join('').slice(0, 6)}`;
+  }
+  if (h.length >= 6) return `#${h.slice(0, 6)}`;
+  return null;
+}
+
+export function hexToRgbTuple(hex) {
+  const full = expandHex(hex);
+  if (!full) return null;
+  const n = parseInt(full.slice(1), 16);
+  return [(n >> 16) & 255, (n >> 8) & 255, n & 255];
+}
+
+export function normalizeColorValue(raw) {
+  const s = String(raw || '').trim();
+  if (!s) return null;
+  if (s.startsWith('#')) {
+    const rgb = hexToRgbTuple(s);
+    if (!rgb) return null;
+    return { kind: 'color', value: expandHex(s), normalized_value: `rgb(${rgb[0]} ${rgb[1]} ${rgb[2]})`, rgb };
+  }
+  const m = /^rgba?\(\s*([0-9.]+)\s*,\s*([0-9.]+)\s*,\s*([0-9.]+)/i.exec(s);
+  if (m) {
+    const rgb = [Math.round(Number(m[1])), Math.round(Number(m[2])), Math.round(Number(m[3]))];
+    const hex = `#${rgb.map((n) => n.toString(16).padStart(2, '0')).join('')}`;
+    return { kind: 'color', value: hex, normalized_value: `rgb(${rgb[0]} ${rgb[1]} ${rgb[2]})`, rgb };
+  }
+  return { kind: 'color', value: s, normalized_value: s.toLowerCase(), rgb: null };
+}
+
+export function colorDistance(a, b) {
+  if (!a?.rgb || !b?.rgb) return Infinity;
+  const dr = a.rgb[0] - b.rgb[0];
+  const dg = a.rgb[1] - b.rgb[1];
+  const db = a.rgb[2] - b.rgb[2];
+  return Math.sqrt(dr * dr + dg * dg + db * db);
+}
+
+export function extractFromText(text, path) {
+  const colors = [];
+  const cssVars = [];
+  const typography = [];
+  const spacing = [];
+  const radius = [];
+  const shadow = [];
+  const tw = [];
+
+  const lines = String(text || '').split(/\r?\n/);
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    const lineNo = i + 1;
+
+    for (const m of line.matchAll(HEX_RE)) {
+      const norm = normalizeColorValue(`#${m[1]}`);
+      if (norm) colors.push({ ...norm, evidence: [{ path, line: lineNo }] });
+    }
+    for (const m of line.matchAll(RGB_RE)) {
+      const norm = normalizeColorValue(m[0]);
+      if (norm) colors.push({ ...norm, evidence: [{ path, line: lineNo }] });
+    }
+    for (const m of line.matchAll(CSS_VAR_RE)) {
+      cssVars.push({
+        kind: 'css_var',
+        name: `--${m[1]}`,
+        value: m[2].trim(),
+        evidence: [{ path, line: lineNo, symbol: `--${m[1]}` }],
+      });
+    }
+    for (const m of line.matchAll(TAILWIND_COLOR_RE)) {
+      tw.push({ kind: 'tailwind_color', value: m[0], evidence: [{ path, line: lineNo }] });
+    }
+    for (const m of line.matchAll(FONT_FAMILY_RE)) {
+      typography.push({ kind: 'font_family', value: m[1].trim(), evidence: [{ path, line: lineNo }] });
+    }
+    for (const m of line.matchAll(FONT_SIZE_RE)) {
+      typography.push({ kind: 'font_size', value: m[1].trim(), evidence: [{ path, line: lineNo }] });
+    }
+    for (const m of line.matchAll(RADIUS_RE)) {
+      radius.push({ kind: 'radius', value: m[1].trim(), evidence: [{ path, line: lineNo }] });
+    }
+    for (const m of line.matchAll(SHADOW_RE)) {
+      shadow.push({ kind: 'shadow', value: m[1].trim(), evidence: [{ path, line: lineNo }] });
+    }
+    for (const m of line.matchAll(SPACING_RE)) {
+      spacing.push({ kind: 'spacing', value: m[1].trim(), evidence: [{ path, line: lineNo }] });
+    }
+  }
+
+  return { colors, cssVars, typography, spacing, radius, shadow, tw };
+}
+
+export function isStylePath(relPath) {
+  const p = String(relPath || '').toLowerCase();
+  return (
+    /\.(css|scss|sass|less)$/.test(p) ||
+    /tailwind\.config\./.test(p) ||
+    /theme\.(ts|js|json|cjs|mjs)$/.test(p) ||
+    /tokens?\.(ts|js|json|css)$/.test(p)
+  );
+}
+
+export function isComponentPath(relPath) {
+  const p = String(relPath || '').toLowerCase();
+  return /\.(tsx?|jsx?|vue|svelte)$/.test(p) && !/\.d\.ts$/.test(p) && !/node_modules/.test(p);
+}
+
+export function isAssetPath(relPath) {
+  return /\.(svg|png|jpe?g|webp|ico|gif|woff2?|ttf|otf)$/i.test(relPath || '');
+}

package/packages/agentsam-brand/src/goap-actions.js

@@ -0,0 +1,73 @@
+/**
+ * GOAP action catalog for brand coherence (consumed by agentsam-planner / plan brand --goap).
+ */
+export function brandGoapActions() {
+  return [
+    {
+      id: 'establish-color-token-map',
+      cost: 2,
+      preconditions: { brand_scan_complete: true, canonical_color_tokens: false },
+      effects: { canonical_color_tokens: true },
+    },
+    {
+      id: 'migrate-color-aliases',
+      cost: 6,
+      preconditions: { canonical_color_tokens: true, duplicate_colors_high: true },
+      effects: { duplicate_colors_high: false, duplicate_color_count_ok: true },
+    },
+    {
+      id: 'establish-type-roles',
+      cost: 4,
+      preconditions: { brand_scan_complete: true, canonical_typography: false },
+      effects: { canonical_typography: true },
+    },
+    {
+      id: 'consolidate-button-family',
+      cost: 8,
+      preconditions: { component_inventory_complete: true, shared_button_component: false },
+      effects: { shared_button_component: true },
+    },
+    {
+      id: 'migrate-header-family',
+      cost: 7,
+      preconditions: { header_consistency: false },
+      effects: { header_consistency: true },
+    },
+    {
+      id: 'verify-brand-surfaces',
+      cost: 1,
+      preconditions: {
+        canonical_color_tokens: true,
+        duplicate_color_count_ok: true,
+        brand_verified: false,
+      },
+      effects: { brand_verified: true },
+    },
+  ];
+}
+
+export function brandWorldFromPlan(plan) {
+  const cur = plan?.current_state || {};
+  return {
+    brand_scan_complete: cur.brand_scan_complete === true,
+    canonical_color_tokens: cur.canonical_color_tokens === true,
+    duplicate_colors_high: (cur.duplicate_color_count || 0) > 3,
+    duplicate_color_count_ok: (cur.duplicate_color_count || 0) <= 3,
+    canonical_typography: cur.canonical_typography === true,
+    component_inventory_complete: true,
+    shared_button_component: cur.shared_button_component === true,
+    header_consistency: cur.header_consistency === true,
+    brand_verified: false,
+  };
+}
+
+export function brandGoalFromPlan(plan) {
+  return {
+    canonical_color_tokens: true,
+    duplicate_color_count_ok: true,
+    canonical_typography: true,
+    shared_button_component: true,
+    header_consistency: true,
+    brand_verified: true,
+  };
+}

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

@@ -0,0 +1,48 @@
+export { brandScan } from './scan.js';
+export { brandResolve, parseDeclaredColor } from './resolve.js';
+export { buildBrandContractDraft, writeBrandArtifacts } from './contract.js';
+export { brandPlan } from './plan.js';
+export {
+  brandGoapActions,
+  brandWorldFromPlan,
+  brandGoalFromPlan,
+} from './goap-actions.js';
+
+export const BRAND_CAPABILITY_META = Object.freeze({
+  'brand.scan': {
+    id: 'brand.scan',
+    deterministic: true,
+    model_required: false,
+    side_effects: 'none',
+    produces: ['brand.evidence'],
+  },
+  'brand.resolve': {
+    id: 'brand.resolve',
+    deterministic: true,
+    model_required: false,
+    side_effects: 'none',
+    produces: ['brand.resolved'],
+  },
+  'brand.plan': {
+    id: 'brand.plan',
+    deterministic: true,
+    model_required: false,
+    model_assisted_optional: true,
+    side_effects: 'none',
+    produces: ['brand.plan'],
+  },
+  'brand.apply': {
+    id: 'brand.apply',
+    deterministic: true,
+    model_required: false,
+    side_effects: 'repository-write',
+    status: 'stub',
+  },
+  'brand.verify': {
+    id: 'brand.verify',
+    deterministic: true,
+    model_required: false,
+    side_effects: 'none',
+    status: 'stub',
+  },
+});

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

@@ -0,0 +1,115 @@
+/**
+ * brand.plan — structured refinement proposal (deterministic skeleton).
+ * Model may later enrich; this always returns preserve/normalize actions from evidence.
+ */
+export function brandPlan({ scan, resolved, contract } = {}) {
+  if (!scan || scan.capability !== 'brand.scan') throw new Error('brand_plan_requires_scan');
+  const resolve = resolved || null;
+  const duplicateColors = (scan.conflicts || []).filter((c) => c.kind === 'near_duplicate_color').length;
+  const colorCount = scan.tokens?.colors?.length || 0;
+  const buttonFamilies = scan.patterns?.button_families || 0;
+  const headerFamilies = scan.patterns?.header_families || 0;
+
+  const current_state = {
+    brand_scan_complete: true,
+    canonical_color_tokens: false,
+    duplicate_color_count: duplicateColors,
+    color_token_count: colorCount,
+    canonical_typography: (scan.tokens?.typography?.length || 0) <= 8,
+    shared_button_component: buttonFamilies <= 1 ? true : buttonFamilies <= 2 ? 'partial' : false,
+    header_consistency: headerFamilies <= 1 ? true : headerFamilies <= 2 ? 'partial' : false,
+  };
+
+  const goal_state = {
+    canonical_color_tokens: true,
+    duplicate_color_count_max: 3,
+    canonical_typography: true,
+    shared_button_component: true,
+    header_consistency: true,
+  };
+
+  const steps = [
+    {
+      id: 'preserve_observed_identity',
+      action: 'preserve',
+      title: 'Preserve observed visual identity',
+      reason: 'Adoption-first: do not impose a foreign design system',
+    },
+    {
+      id: 'establish-color-token-map',
+      action: 'normalize',
+      title: 'Establish canonical color token map',
+      reason: `${colorCount} colors observed; ${duplicateColors} near-duplicate pairs`,
+      requires: { brand_scan_complete: true },
+      effects: { canonical_color_tokens: true },
+      cost: 2,
+    },
+  ];
+
+  if (duplicateColors > 3) {
+    steps.push({
+      id: 'migrate-color-aliases',
+      action: 'migrate',
+      title: 'Migrate duplicated color aliases',
+      reason: 'Collapse near-equivalent colors behind resolved tokens',
+      requires: { canonical_color_tokens: true },
+      effects: { duplicate_color_count_max: 3 },
+      cost: 6,
+    });
+  }
+
+  if (buttonFamilies > 1) {
+    steps.push({
+      id: 'consolidate-button-family',
+      action: 'consolidate',
+      title: 'Consolidate Button primitive family',
+      reason: `${buttonFamilies} button-related component families detected`,
+      effects: { shared_button_component: true },
+      cost: 8,
+    });
+  }
+
+  if (headerFamilies > 1) {
+    steps.push({
+      id: 'migrate-header-family',
+      action: 'investigate',
+      title: 'Investigate competing header/nav systems',
+      reason: `${headerFamilies} header/nav families detected`,
+      effects: { header_consistency: true },
+      cost: 7,
+    });
+  }
+
+  steps.push({
+    id: 'verify-brand-surfaces',
+    action: 'verify',
+    title: 'Verify brand surfaces after changes',
+    reason: 'Deterministic verify gate after apply',
+    cost: 1,
+  });
+
+  const ambiguities = resolve?.ambiguities || [];
+
+  return {
+    schema_version: 1,
+    capability: 'brand.plan',
+    deterministic: true,
+    model_required: false,
+    model_assisted_optional: true,
+    side_effects: 'none',
+    philosophy: 'discover → understand → preserve → normalize → improve',
+    repository: scan.repository,
+    current_state,
+    goal_state,
+    steps,
+    ambiguities,
+    contract_id: contract?.id || null,
+    summary: {
+      colors: colorCount,
+      near_duplicate_pairs: duplicateColors,
+      button_families: buttonFamilies,
+      header_families: headerFamilies,
+      typography_tokens: scan.tokens?.typography?.length || 0,
+    },
+  };
+}

package/packages/agentsam-brand/src/resolve.js

@@ -0,0 +1,139 @@
+import { colorDistance, normalizeColorValue } from './extract.js';
+
+/**
+ * brand.resolve — cluster observed evidence into inferred roles (still non-mutating).
+ */
+export function brandResolve(scanResult, options = {}) {
+  if (!scanResult || scanResult.capability !== 'brand.scan') {
+    throw new Error('brand_resolve_requires_brand_scan');
+  }
+
+  const colors = scanResult.tokens?.colors || [];
+  const clusters = [];
+  const used = new Set();
+  const threshold = options.colorDistance ?? 12;
+
+  for (let i = 0; i < colors.length; i += 1) {
+    if (used.has(i)) continue;
+    const seed = colors[i];
+    const members = [seed];
+    used.add(i);
+    for (let j = i + 1; j < colors.length; j += 1) {
+      if (used.has(j)) continue;
+      if (colorDistance(seed, colors[j]) <= threshold) {
+        members.push(colors[j]);
+        used.add(j);
+      }
+    }
+    members.sort((a, b) => (b.occurrences || 0) - (a.occurrences || 0));
+    const primary = members[0];
+    clusters.push({
+      role_hint: inferColorRole(primary, members),
+      value: primary.value,
+      normalized_value: primary.normalized_value,
+      aliases: members.slice(1).map((m) => m.value),
+      occurrences: members.reduce((n, m) => n + (m.occurrences || 0), 0),
+      confidence: Math.min(0.99, 0.55 + Math.min(members.length, 6) * 0.07 + Math.min(primary.occurrences || 0, 40) * 0.005),
+      members: members.map((m) => ({
+        value: m.value,
+        occurrences: m.occurrences,
+        evidence: (m.evidence || []).slice(0, 5),
+      })),
+    });
+  }
+
+  clusters.sort((a, b) => b.occurrences - a.occurrences);
+
+  const typography = scanResult.tokens?.typography || [];
+  const typeRoles = {};
+  for (const row of typography) {
+    const key = row.kind === 'font_family' ? 'families' : row.kind === 'font_size' ? 'sizes' : 'other';
+    (typeRoles[key] ||= []).push({
+      value: row.value,
+      occurrences: row.occurrences,
+      evidence: (row.evidence || []).slice(0, 3),
+    });
+  }
+
+  const ambiguities = clusters
+    .filter((c) => c.aliases.length >= 1 && c.occurrences >= 8)
+    .slice(0, 12)
+    .map((c) => ({
+      kind: 'color_merge_candidate',
+      primary: c.value,
+      aliases: c.aliases,
+      occurrences: c.occurrences,
+      question: `Are ${[c.value, ...c.aliases.slice(0, 3)].join(', ')} the same brand color?`,
+    }));
+
+  return {
+    schema_version: 1,
+    capability: 'brand.resolve',
+    deterministic: true,
+    model_required: false,
+    side_effects: 'none',
+    repository: scanResult.repository,
+    scan_content_hash: scanResult.content_hash,
+    observed: {
+      colors: colors.map((c) => c.value),
+      typography: typography.map((t) => ({ kind: t.kind, value: t.value })),
+    },
+    inferred: {
+      colors: Object.fromEntries(
+        clusters.slice(0, 24).map((c, idx) => [
+          c.role_hint || `cluster_${idx + 1}`,
+          {
+            candidates: [c.value, ...c.aliases],
+            confidence: Number(c.confidence.toFixed(3)),
+            occurrences: c.occurrences,
+          },
+        ]),
+      ),
+      typography: typeRoles,
+      components: scanResult.patterns || {},
+    },
+    declared: {},
+    resolved: {
+      colors: Object.fromEntries(
+        clusters.slice(0, 24).map((c, idx) => [
+          c.role_hint || `cluster_${idx + 1}`,
+          {
+            value: c.value,
+            aliases: c.aliases,
+            confidence: Number(c.confidence.toFixed(3)),
+          },
+        ]),
+      ),
+    },
+    ambiguities,
+    confidence: {
+      colors: colors.length ? Number(Math.min(0.99, 0.7 + colors.length * 0.005).toFixed(3)) : 0,
+      typography: typography.length ? Number(Math.min(0.95, 0.55 + typography.length * 0.02).toFixed(3)) : 0,
+      voice: 0.2,
+    },
+    preservation: {
+      visual_identity: 'high',
+      component_api: 'high',
+      layout_structure: 'medium',
+    },
+    origin: {
+      mode: 'inferred',
+      repository_snapshot: scanResult.repository?.snapshot_id || null,
+    },
+  };
+}
+
+function inferColorRole(primary, members) {
+  const blob = JSON.stringify(members).toLowerCase();
+  const [r, g, b] = primary.rgb || [128, 128, 128];
+  const lum = (0.2126 * r + 0.7152 * g + 0.0722 * b) / 255;
+  if (/accent|primary|brand|orange|red|blue|indigo/.test(blob) && lum > 0.15 && lum < 0.85) return 'accent_candidate';
+  if (lum < 0.18) return 'surface_dark';
+  if (lum > 0.85) return 'surface_light';
+  if (Math.abs(r - g) < 12 && Math.abs(g - b) < 12) return 'neutral';
+  return 'chromatic';
+}
+
+export function parseDeclaredColor(value) {
+  return normalizeColorValue(value);
+}