weftens 0.0.1 → 0.1.1

package/agent-cores/content-ops/test/inventory.test.mjs

@@ -0,0 +1,177 @@
+// Offline tests — run with `node --test`, zero install. Asserts the engine makes
+// the specific keep/update/retire decisions the seeded fixture demands, flags the
+// seeded metadata gaps, and is deterministic. If these pass, the core is doing real
+// arithmetic on real data — not echoing a prompt.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { inventoryFromText, buildInventory, DEFAULT_THRESHOLDS } from '../src/inventory.mjs';
+import { parseCsv, csvToRecords } from '../src/parse.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const csvText = readFileSync(join(__dirname, 'fixtures', 'cms-export.csv'), 'utf8');
+const jsonText = readFileSync(join(__dirname, 'fixtures', 'cms-export.json'), 'utf8');
+
+// Pin asOf so hand-computed staleness matches the seeded expectations.
+const ASOF = '2026-07-01';
+const run = () => inventoryFromText(csvText, 'csv', { asOf: ASOF });
+const byUrl = (r, u) => r.items.find((it) => it.url === u);
+
+test('CSV parser handles quoted fields with embedded commas', () => {
+  const rows = parseCsv('a,b\n"x, y",z\n');
+  assert.deepEqual(rows, [['a', 'b'], ['x, y', 'z']]);
+  // the seeded homepage row has a comma inside a quoted meta description
+  const recs = csvToRecords(csvText);
+  const home = recs.find((r) => r.url === 'https://acme.example/');
+  assert.equal(home.author, 'Team', 'quoted comma must not shift the author column');
+  assert.match(home['meta description'], /Acme, updated recently/);
+});
+
+test('retires stale + low-traffic content with a redirect requirement', () => {
+  const r = run();
+  const it = byUrl(r, 'https://acme.example/old-news-2019');
+  assert.equal(it.decision, 'retire');
+  assert.match(it.reasons.join(' '), /stale.*low traffic|low traffic.*stale/);
+  assert.equal(it.redirectTarget, null, 'redirect target is an unresolved decision, not omitted');
+});
+
+test('retires thin + low-traffic content as ROT even when recent', () => {
+  const r = run();
+  const it = byUrl(r, 'https://acme.example/tags/misc');
+  assert.equal(it.decision, 'retire');
+  assert.match(it.reasons.join(' '), /thin content/);
+});
+
+test('updates high-traffic pages that have gone stale (never retires them)', () => {
+  const r = run();
+  const it = byUrl(r, 'https://acme.example/pricing-guide');
+  assert.equal(it.decision, 'update');
+  assert.match(it.reasons.join(' '), /high traffic/);
+});
+
+test('keeps high-traffic fresh content', () => {
+  const r = run();
+  const it = byUrl(r, 'https://acme.example/');
+  assert.equal(it.decision, 'keep');
+});
+
+test('updates a low-but-aging article that is not yet ROT', () => {
+  const r = run();
+  const it = byUrl(r, 'https://acme.example/blog/mid-article');
+  assert.equal(it.decision, 'update');
+});
+
+test('updates decayed moderate-traffic reference docs', () => {
+  const r = run();
+  const it = byUrl(r, 'https://acme.example/docs/reference');
+  assert.equal(it.decision, 'update');
+});
+
+test('routes rows with insufficient data to review, never a guessed decision', () => {
+  const r = run();
+  const noTraffic = byUrl(r, 'https://acme.example/reports/quarterly');
+  assert.equal(noTraffic.decision, 'review');
+  assert.match(noTraffic.reasons.join(' '), /pageviews/);
+
+  const noDate = byUrl(r, 'https://acme.example/orphan');
+  assert.equal(noDate.decision, 'review');
+  assert.equal(noDate.confidence, 'low');
+});
+
+test('decision counts match the seeded fixture exactly', () => {
+  const r = run();
+  assert.deepEqual(r.counts, { total: 12, keep: 5, update: 3, retire: 2, review: 2 });
+});
+
+test('flags the seeded metadata gaps (missing desc, short/long title, long desc)', () => {
+  const r = run();
+  const gapFor = (url, field) =>
+    r.metadataGaps.find((g) => g.url === url && g.field === field);
+
+  // tags/misc has an empty meta description
+  assert.ok(gapFor('https://acme.example/tags/misc', 'metaDescription'));
+  // jane-doe bio: title too short AND meta description missing (tier-1 page)
+  const jane = byUrl(r, 'https://acme.example/team/jane-doe');
+  assert.ok(jane.metadataGaps.some((g) => g.field === 'title' && /too short/.test(g.issue)));
+  assert.ok(jane.metadataGaps.some((g) => g.field === 'metaDescription' && g.issue === 'missing'));
+  // pricing-guide meta description exceeds 160 chars
+  const pricing = byUrl(r, 'https://acme.example/pricing-guide');
+  assert.ok(pricing.metadataGaps.some((g) => g.field === 'metaDescription' && /too long/.test(g.issue)));
+  // reference doc title exceeds 65 chars
+  const ref = byUrl(r, 'https://acme.example/docs/reference');
+  assert.ok(ref.metadataGaps.some((g) => g.field === 'title' && /too long/.test(g.issue)));
+});
+
+test('a missing date is a blocking (fail) gap', () => {
+  const r = run();
+  const orphan = byUrl(r, 'https://acme.example/orphan');
+  assert.ok(orphan.metadataGaps.some((g) => g.field === 'date' && g.severity === 'fail'));
+  assert.ok(r.migrationReadiness.blockingGaps >= 1);
+});
+
+test('detects duplicate titles across URLs (taxonomy collision)', () => {
+  const r = run();
+  const dup = r.duplicates.titles.find((d) => d.title === 'complete guide');
+  assert.ok(dup, 'the two "Complete Guide" pages are flagged');
+  assert.equal(dup.count, 2);
+});
+
+test('surfaces source fields with no canonical destination', () => {
+  const r = run();
+  assert.ok(r.unmappedFields.includes('author'), '"author" has no mapped destination');
+});
+
+test('migration readiness: redirect ledger, blockers, and a bounded score', () => {
+  const r = run();
+  const m = r.migrationReadiness;
+  assert.equal(m.redirectsRequired, 2);
+  assert.equal(m.redirectLedger.length, 2);
+  assert.ok(m.redirectLedger.every((e) => e.to === null && e.resolved === false && e.status === 301));
+  assert.ok(m.blockers.some((b) => /redirect target/.test(b)));
+  assert.ok(m.readinessScore >= 0 && m.readinessScore <= 100);
+  assert.equal(typeof m.fieldCoverage.pageviews.pct, 'number');
+});
+
+test('same input -> byte-identical output (deterministic, no wall clock)', () => {
+  const a = run();
+  const b = run();
+  assert.equal(JSON.stringify(a), JSON.stringify(b));
+});
+
+test('default asOf is the latest date in the export, not Date.now()', () => {
+  const r = inventoryFromText(csvText, 'csv'); // no asOf passed
+  assert.equal(r.asOf, '2026-06-20', 'latest last-updated in the CSV drives asOf');
+  // and it is still deterministic across runs
+  const r2 = inventoryFromText(csvText, 'csv');
+  assert.equal(JSON.stringify(r), JSON.stringify(r2));
+});
+
+test('JSON export path works and applies the same decision logic', () => {
+  const r = inventoryFromText(jsonText, 'json');
+  assert.equal(byUrl(r, 'https://acme.example/legacy-faq').decision, 'retire');
+  assert.equal(byUrl(r, 'https://acme.example/flagship').decision, 'update');
+  assert.equal(byUrl(r, 'https://acme.example/whats-new').decision, 'keep');
+});
+
+test('empty export yields a well-formed, non-crashing result', () => {
+  const r = buildInventory([]);
+  assert.equal(r.counts.total, 0);
+  assert.equal(r.migrationReadiness.readinessScore, 0);
+  assert.ok(r.migrationReadiness.blockers.length > 0);
+});
+
+test('thresholds are overridable and change decisions predictably', () => {
+  // Baseline: /guide is mid-traffic (300 views) and fresh (122 days) -> keep.
+  const base = run();
+  assert.equal(base.items.find((it) => it.url === 'https://acme.example/guide').decision, 'keep');
+  // Tighten veryStaleDays below 122: the same page now reads as decayed -> update.
+  const strict = inventoryFromText(csvText, 'csv', {
+    asOf: ASOF,
+    thresholds: { ...DEFAULT_THRESHOLDS, veryStaleDays: 100 },
+  });
+  const guide = strict.items.find((it) => it.url === 'https://acme.example/guide');
+  assert.equal(guide.decision, 'update');
+});

package/agent-cores/meta-ads/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@agent-cores/meta-ads",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Meta (Facebook/Instagram) ads auditor. Deterministic: parse an Ads Manager export, compute a ranked PROPOSE-ONLY change sheet (pause wasted spend, creative fatigue, low ROAS, cost-per-result inefficiency). No LLM in the core.",
+  "bin": {
+    "meta-ads": "src/cli.mjs"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/agent-cores/meta-ads/src/analyze.mjs

@@ -0,0 +1,166 @@
+// Deterministic Meta (Facebook/Instagram) ads analysis. No LLM. PROPOSE-ONLY.
+//
+// Input: parsed rows (canonical fields from parse.mjs), one per breakdown entity — an
+// ad, an ad set, or a campaign. Output: a ranked change sheet; every row carries the
+// evidence numbers that triggered it. The core never calls a model and never touches an
+// account — a human applies the proposed changes.
+//
+// Four finding families, mirroring the Meta buyer's job:
+//   pause       — spend with zero results (burning budget, nothing back)
+//   low-roas    — purchases tracked but ROAS < 1 (losing money on every dollar)
+//   inefficient — cost per result far above the account average (expensive but not losing)
+//   fatigue     — high frequency (the same people seeing it too often — refresh creative)
+
+export const DEFAULT_THRESHOLDS = {
+  pauseMinSpend: 20,      // spend where "0 results" is signal, not noise
+  lowRoasMax: 1,          // ROAS < 1 loses money
+  lowRoasMinSpend: 30,
+  effCprMultiple: 3,      // cost/result >= 3x the account average
+  effMinSpend: 30,
+  fatigueFrequency: 3.5,  // avg impressions per person before fatigue bites
+  fatigueMinSpend: 20,
+};
+
+function sum(arr, f) {
+  let t = 0;
+  for (const x of arr) { const v = f(x); if (Number.isFinite(v)) t += v; }
+  return t;
+}
+function round(n, dp = 2) {
+  if (!Number.isFinite(n)) return n;
+  const m = 10 ** dp;
+  return Math.round(n * m) / m;
+}
+// Name an entity by its most granular identifier, and say which level that is.
+function label(r) {
+  if (r.ad) return { name: r.ad, level: 'ad' };
+  if (r.adset) return { name: r.adset, level: 'ad set' };
+  return { name: r.campaign || '(unnamed)', level: 'campaign' };
+}
+function where(r) {
+  return [r.campaign, r.adset, r.ad].filter(Boolean).join(' / ') || 'account';
+}
+
+export function analyze(input, options = {}) {
+  const thresholds = { ...DEFAULT_THRESHOLDS, ...(options.thresholds || {}) };
+  const rows = Array.isArray(input) ? input : (Array.isArray(input?.rows) ? input.rows : []);
+
+  const totalSpend = sum(rows, (r) => r.spend);
+  const totalResults = sum(rows, (r) => r.results);
+  const totalValue = sum(rows, (r) => r.purchaseValue ?? (Number.isFinite(r.roas) && Number.isFinite(r.spend) ? r.roas * r.spend : 0));
+  const accountCPR = totalResults > 0 ? totalSpend / totalResults : null;
+  const accountROAS = totalSpend > 0 && totalValue > 0 ? totalValue / totalSpend : null;
+
+  const changes = [];
+
+  for (const r of rows) {
+    const spend = r.spend || 0;
+    const results = r.results || 0;
+    const roas = Number.isFinite(r.roas) ? r.roas : null;
+    const cpr = Number.isFinite(r.costPerResult) ? r.costPerResult : (results > 0 ? spend / results : null);
+    const { name, level } = label(r);
+
+    // 1. pause — spend, zero results
+    if (results === 0 && spend >= thresholds.pauseMinSpend) {
+      changes.push({
+        type: 'pause',
+        change: `Pause ${level} "${name}" — spend with zero results`,
+        where: where(r),
+        why: `$${round(spend)} spent, 0 results${r.linkClicks ? `, ${r.linkClicks} link clicks that never converted` : ''}`,
+        expectedEffect: `Recover ~$${round(spend)}/period of wasted spend`,
+        risk: 'If this is a new ad still in learning, give it a few days of results before killing it.',
+        dollars: round(spend),
+        evidence: { entity: name, level, spend: round(spend), results: 0, roas },
+      });
+      continue; // one primary call per entity
+    }
+
+    // 2. low ROAS — losing money on tracked purchases
+    if (roas != null && roas < thresholds.lowRoasMax && spend >= thresholds.lowRoasMinSpend) {
+      const value = round(spend * roas);
+      const loss = round(spend - value);
+      changes.push({
+        type: 'low-roas',
+        change: `Pause or rework ${level} "${name}" — ROAS ${round(roas, 2)} is below break-even`,
+        where: where(r),
+        why: `$${round(spend)} spent returned ~$${value} (ROAS ${round(roas, 2)}) — losing ~$${loss}`,
+        expectedEffect: `Stop ~$${loss}/period of net loss; reallocate to profitable ad sets`,
+        risk: 'ROAS can lag with a long purchase window; confirm the attribution window before pausing a recent ad.',
+        dollars: loss,
+        evidence: { entity: name, level, spend: round(spend), roas: round(roas, 2), value },
+      });
+      continue;
+    }
+
+    // 3. inefficient — cost per result far above account average (and not already low-roas)
+    if (accountCPR != null && cpr != null && results > 0 && spend >= thresholds.effMinSpend
+      && cpr >= thresholds.effCprMultiple * accountCPR) {
+      const overspend = round(spend - results * accountCPR);
+      changes.push({
+        type: 'inefficient',
+        change: `Reduce or restructure ${level} "${name}" — cost per result far above account average`,
+        where: where(r),
+        why: `$${round(cpr)}/result vs $${round(accountCPR)} account average (${round(cpr / accountCPR, 1)}x) on $${round(spend)} spend`,
+        expectedEffect: `Recover ~$${overspend}/period of over-average cost`,
+        risk: 'A small results count makes cost-per-result noisy; check it holds over more conversions before cutting.',
+        dollars: overspend,
+        evidence: { entity: name, level, spend: round(spend), costPerResult: round(cpr), accountCPR: round(accountCPR), results },
+      });
+      continue;
+    }
+
+    // 4. fatigue — high frequency (creative refresh). Not a "continue" gate: a healthy ad
+    // can still be fatiguing, but pause/low-roas/inefficient are more urgent when present.
+    if (Number.isFinite(r.frequency) && r.frequency >= thresholds.fatigueFrequency && spend >= thresholds.fatigueMinSpend) {
+      changes.push({
+        type: 'fatigue',
+        change: `Refresh creative on ${level} "${name}" — audience is seeing it too often`,
+        where: where(r),
+        why: `frequency ${round(r.frequency, 1)} (each person saw it ~${Math.round(r.frequency)}x) on $${round(spend)} spend`,
+        expectedEffect: 'New creative usually recovers CTR/CPM as fatigue resets; expand or refresh the audience too',
+        risk: 'High frequency on a small retargeting pool can be fine; judge against that audience size.',
+        dollars: round(spend * 0.25), // a quarter of spend treated as at-risk to fatigue, for ranking
+        evidence: { entity: name, level, frequency: round(r.frequency, 1), spend: round(spend) },
+      });
+    }
+  }
+
+  // rank by dollars; tiebreak by type order then a stable key
+  const typeRank = { pause: 0, 'low-roas': 1, inefficient: 2, fatigue: 3 };
+  const keyed = changes.map((c, i) => ({ ...c, _i: i }));
+  keyed.sort((a, b) => {
+    if ((b.dollars || 0) !== (a.dollars || 0)) return (b.dollars || 0) - (a.dollars || 0);
+    if (typeRank[a.type] !== typeRank[b.type]) return typeRank[a.type] - typeRank[b.type];
+    return a._i - b._i;
+  });
+  const ranked = keyed.map(({ _i, ...c }, idx) => ({ rank: idx + 1, ...c }));
+
+  const recoverable = round(sum(ranked.filter((c) => c.type === 'pause' || c.type === 'low-roas' || c.type === 'inefficient'), (c) => c.dollars), 2);
+
+  return {
+    proposeOnly: true,
+    account: {
+      rows: rows.length,
+      totalSpend: round(totalSpend),
+      totalResults: round(totalResults, 1),
+      accountCostPerResult: accountCPR == null ? null : round(accountCPR),
+      accountROAS: accountROAS == null ? null : round(accountROAS, 2),
+    },
+    counts: {
+      total: ranked.length,
+      pause: ranked.filter((c) => c.type === 'pause').length,
+      lowRoas: ranked.filter((c) => c.type === 'low-roas').length,
+      inefficient: ranked.filter((c) => c.type === 'inefficient').length,
+      fatigue: ranked.filter((c) => c.type === 'fatigue').length,
+    },
+    wastedSpendRecoverable: recoverable,
+    summary: buildSummary(ranked, recoverable),
+    changes: ranked,
+  };
+}
+
+function buildSummary(ranked, recoverable) {
+  if (ranked.length === 0) return 'No pause, ROAS, cost, or fatigue changes found in the exported report.';
+  return `${ranked.length} proposed change(s); ~$${recoverable} recoverable from wasted/losing/over-cost spend. `
+    + `Start with: ${ranked[0].change}.`;
+}

package/agent-cores/meta-ads/src/cli.mjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+// Real CLI. Reads a Meta Ads Manager export (CSV or JSON) from a file path, prints the
+// PROPOSE-ONLY change sheet as JSON on stdout and a one-line summary on stderr. No
+// account access.
+//   meta-ads <export.csv> [--pretty]
+//   meta-ads <export.json>          (a JSON array of rows, or { "rows": [...] })
+
+import { readFileSync } from 'node:fs';
+import { analyze } from './analyze.mjs';
+import { parseReport } from './parse.mjs';
+
+function main() {
+  const argv = process.argv.slice(2);
+  const pretty = argv.includes('--pretty');
+  const file = argv.find((a) => !a.startsWith('--'));
+  if (!file) {
+    console.error('Usage: meta-ads <export.csv|export.json> [--pretty]');
+    process.exitCode = 1;
+    return;
+  }
+  const text = readFileSync(file, 'utf8');
+  let rows;
+  if (file.endsWith('.json')) {
+    const parsed = JSON.parse(text);
+    rows = Array.isArray(parsed) ? parsed : (parsed.rows || []);
+  } else {
+    rows = parseReport(text);
+  }
+  const result = analyze(rows);
+  console.error(`meta-ads: ${result.summary}`);
+  console.log(JSON.stringify(result, null, pretty ? 2 : 0));
+}
+
+try {
+  main();
+} catch (err) {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exitCode = 1;
+}

package/agent-cores/meta-ads/src/parse.mjs

@@ -0,0 +1,123 @@
+// Dependency-free CSV parser + Meta Ads Manager column mapper. A Meta export is a clean
+// header row followed by one row per breakdown level (campaign / ad set / ad). We find
+// the header by known column tokens, map arbitrary spellings to canonical field names,
+// and coerce currency / percent / number cells.
+
+// --- CSV tokenizer (state machine; handles quotes, embedded commas, CRLF) ---
+export function parseCsv(text) {
+  const rows = [];
+  let row = [];
+  let field = '';
+  let inQuotes = false;
+  const s = String(text).replace(/^/, ''); // strip BOM
+
+  for (let i = 0; i < s.length; i += 1) {
+    const c = s[i];
+    if (inQuotes) {
+      if (c === '"') {
+        if (s[i + 1] === '"') { field += '"'; i += 1; }
+        else inQuotes = false;
+      } else field += c;
+    } else if (c === '"') inQuotes = true;
+    else if (c === ',') { row.push(field); field = ''; }
+    else if (c === '\n') { row.push(field); field = ''; rows.push(row); row = []; }
+    else if (c === '\r') { /* handled by \n */ }
+    else field += c;
+  }
+  if (field.length > 0 || row.length > 0) { row.push(field); rows.push(row); }
+  return rows;
+}
+
+function normHeader(h) {
+  return String(h).toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim();
+}
+
+// canonical field -> normalized header spellings that map to it
+const ALIASES = {
+  campaign: ['campaign name', 'campaign'],
+  adset: ['ad set name', 'ad set', 'adset name', 'adset'],
+  ad: ['ad name', 'ad'],
+  spend: ['amount spent usd', 'amount spent', 'spend'],
+  impressions: ['impressions', 'impr'],
+  reach: ['reach'],
+  frequency: ['frequency'],
+  results: ['results', 'result'],
+  resultType: ['result indicator', 'result type', 'result name'],
+  costPerResult: ['cost per result', 'cost per results'],
+  linkClicks: ['link clicks', 'clicks all', 'clicks'],
+  ctr: ['ctr link click through rate', 'ctr all', 'ctr'],
+  purchases: ['purchases', 'website purchases'],
+  purchaseValue: ['purchases conversion value', 'website purchases conversion value', 'purchase conversion value'],
+  roas: ['purchase roas return on ad spend', 'website purchase roas', 'purchase roas', 'roas'],
+};
+
+const HEADER_TO_FIELD = (() => {
+  const m = new Map();
+  for (const [field, spellings] of Object.entries(ALIASES)) for (const sp of spellings) m.set(sp, field);
+  return m;
+})();
+
+const PERCENT_FIELDS = new Set(['ctr']);
+const NUMERIC_FIELDS = new Set([
+  'spend', 'impressions', 'reach', 'frequency', 'results', 'costPerResult',
+  'linkClicks', 'purchases', 'purchaseValue', 'roas',
+]);
+
+export function toNumber(raw) {
+  if (raw == null) return null;
+  let v = String(raw).trim();
+  if (v === '' || v === '--' || v === '—' || v.toLowerCase() === 'n/a') return null;
+  v = v.replace(/[$£€,%\s"]/g, '');
+  if (v === '') return null;
+  const n = Number.parseFloat(v);
+  return Number.isFinite(n) ? n : null;
+}
+
+// Percent cell -> fraction. "0.30%" -> 0.003, "1.00%" -> 0.01, bare "0.3" -> 0.003.
+export function toPercent(raw) {
+  if (raw == null) return null;
+  const v = String(raw).trim();
+  if (v === '' || v === '--' || v === '—') return null;
+  const hadPercent = v.includes('%');
+  const n = toNumber(v);
+  if (n == null) return null;
+  return hadPercent ? n / 100 : (n > 1 ? n / 100 : n);
+}
+
+function coerce(field, raw) {
+  if (PERCENT_FIELDS.has(field)) return toPercent(raw);
+  if (NUMERIC_FIELDS.has(field)) return toNumber(raw);
+  return raw == null ? '' : String(raw).trim();
+}
+
+function findHeader(rows, minKnown = 3) {
+  for (let i = 0; i < rows.length; i += 1) {
+    const mapped = rows[i].map((h) => HEADER_TO_FIELD.get(normHeader(h))).filter(Boolean);
+    if (new Set(mapped).size >= minKnown) return i;
+  }
+  return -1;
+}
+
+// Parse a Meta Ads Manager CSV export into canonical row objects.
+export function parseReport(text) {
+  const rows = parseCsv(text);
+  const headerIdx = findHeader(rows);
+  if (headerIdx === -1) {
+    throw new Error('No recognizable Meta Ads header row found (need e.g. "Ad set name", "Amount spent", "Results").');
+  }
+  const colField = rows[headerIdx].map((h) => HEADER_TO_FIELD.get(normHeader(h)) || null);
+
+  const out = [];
+  for (let i = headerIdx + 1; i < rows.length; i += 1) {
+    const cells = rows[i];
+    if (cells.every((c) => (c || '').trim() === '')) continue;
+    const rec = {};
+    for (let c = 0; c < colField.length; c += 1) {
+      const field = colField[c];
+      if (field) rec[field] = coerce(field, cells[c]);
+    }
+    // require at least one identifying name so we don't emit garbage rows
+    if (rec.ad || rec.adset || rec.campaign) out.push(rec);
+  }
+  return out;
+}

package/agent-cores/meta-ads/test/analyze.test.js

@@ -0,0 +1,72 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { parseReport } from '../src/parse.mjs';
+import { analyze, DEFAULT_THRESHOLDS } from '../src/analyze.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const fixture = () => parseReport(readFileSync(join(HERE, 'fixtures', 'meta-ads.csv'), 'utf8'));
+const find = (result, entity) => result.changes.find((c) => c.evidence.entity === entity);
+
+test('parse maps Meta columns and coerces numbers/percent', () => {
+  const rows = fixture();
+  assert.equal(rows.length, 5);
+  const a = rows.find((r) => r.ad === 'Video A');
+  assert.equal(a.spend, 85);
+  assert.equal(a.results, 0);
+  assert.equal(a.frequency, 1.25);
+  assert.equal(rows.find((r) => r.ad === 'Video E').ctr, 0.01); // "1.00%" -> 0.01
+});
+
+test('the whole sheet is propose-only', () => {
+  assert.equal(analyze(fixture()).proposeOnly, true);
+});
+
+test('pause: spend with zero results is flagged', () => {
+  const r = find(analyze(fixture()), 'Video A');
+  assert.equal(r.type, 'pause');
+  assert.equal(r.dollars, 85);
+});
+
+test('low-roas: ROAS below break-even is flagged as a loss', () => {
+  const r = find(analyze(fixture()), 'Story C'); // roas 0.6, spend 70
+  assert.equal(r.type, 'low-roas');
+  assert.equal(r.dollars, 28); // 70 - 70*0.6
+});
+
+test('inefficient: cost/result far above account average is flagged (not double-counted as low-roas)', () => {
+  const r = find(analyze(fixture()), 'Image D'); // cpr 80 vs ~26 account, roas 1.3 (profitable)
+  assert.equal(r.type, 'inefficient');
+  assert.ok(r.evidence.costPerResult >= 3 * r.evidence.accountCPR);
+});
+
+test('fatigue: high frequency triggers a creative-refresh proposal', () => {
+  const r = find(analyze(fixture()), 'Carousel B'); // frequency 4.8
+  assert.equal(r.type, 'fatigue');
+});
+
+test('a healthy ad produces no finding', () => {
+  assert.equal(find(analyze(fixture()), 'Video E'), undefined);
+});
+
+test('changes are ranked by dollars, descending', () => {
+  const { changes } = analyze(fixture());
+  for (let i = 1; i < changes.length; i += 1) {
+    assert.ok((changes[i - 1].dollars || 0) >= (changes[i].dollars || 0));
+    assert.equal(changes[i].rank, i + 1);
+  }
+});
+
+test('empty input yields a clean, empty propose-only sheet', () => {
+  const result = analyze([]);
+  assert.equal(result.changes.length, 0);
+  assert.match(result.summary, /No pause/);
+});
+
+test('thresholds are overridable', () => {
+  assert.equal(typeof DEFAULT_THRESHOLDS.fatigueFrequency, 'number');
+  const strict = analyze(fixture(), { thresholds: { fatigueFrequency: 10 } });
+  assert.equal(strict.changes.find((c) => c.type === 'fatigue'), undefined);
+});

package/agent-cores/meta-ads/test/fixtures/meta-ads.csv

@@ -0,0 +1,6 @@
+Campaign name,Ad set name,Ad name,Amount spent (USD),Impressions,Reach,Frequency,Results,Result indicator,Cost per result,Link clicks,CTR (link click-through rate),Purchases,Purchase ROAS (return on ad spend)
+Prospecting,Broad Interests,Video A,85.00,40000,32000,1.25,0,actions:purchase,,120,0.30%,0,
+Prospecting,Lookalike 1%,Carousel B,120.00,90000,18750,4.80,6,actions:purchase,20.00,300,0.33%,6,2.10
+Retargeting,Cart Abandoners 7d,Story C,70.00,15000,12000,1.25,1,actions:purchase,70.00,45,0.30%,1,0.60
+Prospecting,Interest - Cooking,Image D,80.00,20000,17500,1.14,1,actions:purchase,80.00,60,0.30%,1,1.30
+Retargeting,Site Visitors 30d,Video E,90.00,20000,16000,1.25,9,actions:purchase,10.00,200,1.00%,9,3.50

package/agent-cores/paid-search/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@agent-cores/paid-search",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Google Ads paid-search auditor. Deterministic: parse exported search-terms + campaign reports, compute a ranked change sheet (negatives, budget moves, structure fixes). PROPOSE-ONLY. No LLM in the core.",
+  "bin": {
+    "paid-search": "src/cli.mjs"
+  },
+  "scripts": {
+    "test": "node --test",
+    "audit": "node src/cli.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}