weftens 0.0.1 → 0.1.1

package/agent-cores/amazon-ppc/src/parse.mjs

@@ -0,0 +1,153 @@
+// Dependency-free parser for an Amazon Ads search-term report.
+// Accepts CSV (comma or tab) or JSON. Normalizes the messy real-world column
+// names Amazon exports ("7 Day Total Sales", "Customer Search Term", "$1.23",
+// "25.00%") into clean numeric rows. No LLM, no deps.
+
+// --- CSV tokenizer: RFC-4180-ish, handles quoted fields with embedded commas/quotes ---
+export function parseDelimited(text) {
+  const rows = [];
+  let field = '';
+  let record = [];
+  let inQuotes = false;
+  let delimiter = null;
+
+  // Sniff delimiter from the header line (tab beats comma if present).
+  const firstLine = text.slice(0, text.indexOf('\n') === -1 ? text.length : text.indexOf('\n'));
+  delimiter = firstLine.includes('\t') && !firstLine.includes(',') ? '\t' : ',';
+
+  const pushField = () => {
+    record.push(field);
+    field = '';
+  };
+  const pushRecord = () => {
+    // ignore a trailing empty record (blank last line)
+    if (record.length > 1 || (record.length === 1 && record[0] !== '')) rows.push(record);
+    record = [];
+  };
+
+  for (let i = 0; i < text.length; i += 1) {
+    const c = text[i];
+    if (inQuotes) {
+      if (c === '"') {
+        if (text[i + 1] === '"') { field += '"'; i += 1; } // escaped quote
+        else inQuotes = false;
+      } else field += c;
+    } else if (c === '"') {
+      inQuotes = true;
+    } else if (c === delimiter) {
+      pushField();
+    } else if (c === '\r') {
+      // swallow; \n handles the record break
+    } else if (c === '\n') {
+      pushField();
+      pushRecord();
+    } else {
+      field += c;
+    }
+  }
+  // flush trailing field/record if file did not end with newline
+  if (field !== '' || record.length > 0) {
+    pushField();
+    pushRecord();
+  }
+  return rows;
+}
+
+// Map a raw header cell to a canonical key by stripping to alphanumerics.
+const HEADER_ALIASES = [
+  ['searchterm', 'searchTerm'],
+  ['customersearchterm', 'searchTerm'],
+  ['campaignname', 'campaign'],
+  ['campaign', 'campaign'],
+  ['adgroupname', 'adGroup'],
+  ['adgroup', 'adGroup'],
+  ['matchtype', 'matchType'],
+  ['targeting', 'targeting'],
+  ['impressions', 'impressions'],
+  ['clicks', 'clicks'],
+  ['spend', 'spend'],
+  ['cost', 'spend'],
+  ['costperclickcpc', 'cpc'],
+  ['costperclick', 'cpc'],
+  ['cpc', 'cpc'],
+  ['7daytotalsales', 'sales'],
+  ['7daytotalsales', 'sales'],
+  ['totalsales', 'sales'],
+  ['sales', 'sales'],
+  ['7daytotalorders', 'orders'],
+  ['7daytotalorders', 'orders'],
+  ['totalorders', 'orders'],
+  ['orders', 'orders'],
+];
+
+function canonicalKey(rawHeader) {
+  const norm = String(rawHeader).toLowerCase().replace(/[^a-z0-9]/g, '');
+  // longest alias match first so "7daytotalsales" wins over "sales"
+  let best = null;
+  for (const [alias, key] of HEADER_ALIASES) {
+    if (norm === alias) return key; // exact wins immediately
+    if (norm.includes(alias) && (!best || alias.length > best.aliasLen)) {
+      best = { key, aliasLen: alias.length };
+    }
+  }
+  return best ? best.key : null;
+}
+
+// Strip currency/percent/thousands formatting to a number. "%" values are
+// returned as a fraction (25% -> 0.25). Returns 0 for blank/undefined.
+function toNumber(raw, { percent = false } = {}) {
+  if (raw === undefined || raw === null) return 0;
+  let s = String(raw).trim();
+  if (s === '' || s === '-' || s.toLowerCase() === 'n/a') return 0;
+  const isPct = percent || s.includes('%');
+  s = s.replace(/[$£€,%\s]/g, '');
+  const n = Number(s);
+  if (Number.isNaN(n)) return 0;
+  return isPct ? n / 100 : n;
+}
+
+// Turn a JSON array or parsed CSV into normalized numeric rows.
+export function normalizeRows(input) {
+  let records;
+  if (typeof input === 'string') {
+    const trimmed = input.trimStart();
+    if (trimmed.startsWith('[') || trimmed.startsWith('{')) {
+      const json = JSON.parse(trimmed);
+      records = Array.isArray(json) ? json : json.rows || json.searchTerms || [];
+      return records.map((r) => normalizeObject(r)).filter(Boolean);
+    }
+    const cells = parseDelimited(input);
+    if (cells.length < 2) return [];
+    const header = cells[0].map(canonicalKey);
+    return cells.slice(1).map((cols) => {
+      const obj = {};
+      header.forEach((k, i) => { if (k) obj[k] = cols[i]; });
+      return normalizeObject(obj);
+    }).filter(Boolean);
+  }
+  // already an array of objects
+  return input.map((r) => normalizeObject(r)).filter(Boolean);
+}
+
+function normalizeObject(r) {
+  // allow objects whose keys are already-raw Amazon headers
+  const lookup = {};
+  for (const [k, v] of Object.entries(r)) {
+    const ck = canonicalKey(k);
+    if (ck && lookup[ck] === undefined) lookup[ck] = v;
+  }
+  const searchTerm = String(lookup.searchTerm ?? '').trim();
+  if (!searchTerm) return null;
+  return {
+    searchTerm,
+    campaign: String(lookup.campaign ?? '').trim() || '(unknown campaign)',
+    adGroup: String(lookup.adGroup ?? '').trim() || '',
+    matchType: String(lookup.matchType ?? lookup.targeting ?? '').trim(),
+    impressions: Math.round(toNumber(lookup.impressions)),
+    clicks: Math.round(toNumber(lookup.clicks)),
+    spend: toNumber(lookup.spend),
+    cpc: toNumber(lookup.cpc),
+    sales: toNumber(lookup.sales),
+    orders: Math.round(toNumber(lookup.orders)),
+  };
+}

package/agent-cores/amazon-ppc/test/fixtures/search-term-report.csv

@@ -0,0 +1,8 @@
+Campaign Name,Ad Group Name,Match Type,Customer Search Term,Impressions,Clicks,Cost Per Click (CPC),Spend,7 Day Total Sales,7 Day Total Orders (#)
+Auto - Garlic Press,Auto Group,auto,garlic press,5000,40,$0.50,$20.00,$0.00,0
+Auto - Garlic Press,Auto Group,auto,stainless garlic press,3200,30,$0.50,$15.00,$120.00,8
+Broad - Garlic,Broad Group,broad,garlic mincer tool,4100,25,$0.88,$22.00,$40.00,2
+Exact - Pro Press,Exact Group,exact,professional garlic press,6000,50,$0.20,$10.00,$200.00,15
+Broad - Garlic,Broad Group,broad,cheap kitchen gadget,2200,12,$0.54,$6.50,$0.00,0
+Broad - Garlic,Broad Group,broad,garlic,20000,3,$0.50,$1.50,$0.00,0
+Auto - Garlic Press,Auto Group,auto,rocker garlic press,1800,18,$0.50,$9.00,$90.00,5

package/agent-cores/amazon-ppc/test/fixtures/search-term-report.json

@@ -0,0 +1,5 @@
+[
+  { "Customer Search Term": "garlic press", "Campaign Name": "Auto - Garlic Press", "Match Type": "auto", "Impressions": 5000, "Clicks": 40, "Spend": 20.0, "7 Day Total Sales": 0, "7 Day Total Orders (#)": 0 },
+  { "Customer Search Term": "stainless garlic press", "Campaign Name": "Auto - Garlic Press", "Match Type": "auto", "Impressions": 3200, "Clicks": 30, "Spend": 15.0, "7 Day Total Sales": 120.0, "7 Day Total Orders (#)": 8 },
+  { "Customer Search Term": "professional garlic press", "Campaign Name": "Exact - Pro Press", "Match Type": "exact", "Impressions": 6000, "Clicks": 50, "Spend": 10.0, "7 Day Total Sales": 200.0, "7 Day Total Orders (#)": 15 }
+]

package/agent-cores/amazon-ppc/test/optimize.test.mjs

@@ -0,0 +1,161 @@
+// Offline tests — run with `node --test`, zero install. Asserts the optimizer
+// computes real, specific proposals from a known search-term report with seeded
+// issues. If these pass, the core is doing deterministic arithmetic, not echoing.
+
+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 { optimize } from '../src/optimize.mjs';
+import { normalizeRows, parseDelimited } from '../src/parse.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const csv = readFileSync(join(__dirname, 'fixtures', 'search-term-report.csv'), 'utf8');
+const jsonText = readFileSync(join(__dirname, 'fixtures', 'search-term-report.json'), 'utf8');
+
+const CFG = { targetAcos: 25, margin: 35 };
+const run = () => optimize(csv, CFG);
+const findNeg = (r, term) => r.negatives.find((n) => n.term === term);
+const findPromo = (r, term) => r.promotions.find((p) => p.term === term);
+const findRebid = (r, term) => r.rebids.find((b) => b.term === term);
+
+test('CSV parser strips $/%/commas and normalizes messy Amazon headers', () => {
+  const rows = normalizeRows(csv);
+  assert.equal(rows.length, 7);
+  const r = rows.find((x) => x.searchTerm === 'garlic mincer tool');
+  assert.equal(r.spend, 22.0);
+  assert.equal(r.sales, 40.0);
+  assert.equal(r.orders, 2);
+  assert.equal(r.clicks, 25);
+  assert.equal(r.cpc, 0.88);
+});
+
+test('CSV tokenizer handles a quoted field containing a comma', () => {
+  const rows = parseDelimited('a,b\n"hello, world",2\n');
+  assert.deepEqual(rows[1], ['hello, world', '2']);
+});
+
+test('negates zero-order waste terms and estimates spend stopped', () => {
+  const r = run();
+  assert.equal(r.negatives.length, 2);
+  const gp = findNeg(r, 'garlic press');
+  assert.ok(gp, 'garlic press negated');
+  assert.equal(gp.spendStopped, 20.0);
+  assert.match(gp.reason, /40 clicks, 0 orders/);
+  assert.ok(findNeg(r, 'cheap kitchen gadget'), '12-click zero-order term negated');
+  assert.equal(r.summary.estSpendStopped, 26.5);
+});
+
+test('does NOT negate a low-signal term (3 clicks, $1.50, 0 orders) — it holds', () => {
+  const r = run();
+  assert.equal(findNeg(r, 'garlic'), undefined);
+  const held = r.held.find((h) => h.term === 'garlic');
+  assert.ok(held && held.action === 'hold', 'low-signal term held, not negated');
+});
+
+test('promotes converting non-exact winners with the margin math attached', () => {
+  const r = run();
+  assert.equal(r.promotions.length, 2);
+  const p = findPromo(r, 'stainless garlic press');
+  assert.ok(p, 'winner promoted');
+  assert.equal(p.newMatchType, 'exact');
+  assert.equal(p.acos, 12.5);
+  // rev/click $4.00 * 25% target = $1.00 ideal, capped to 1.5x CPC($0.50) = $0.75
+  assert.equal(p.startingBid, 0.75);
+  assert.equal(p.capped, true);
+  assert.equal(p.negateInSource, true);
+  assert.match(p.marginMath, /\$4 rev\/click x 25% target ACOS = \$1 ideal bid/);
+});
+
+test('promotions are ranked by sales (biggest winner first)', () => {
+  const r = run();
+  assert.equal(r.promotions[0].term, 'stainless garlic press'); // $120
+  assert.equal(r.promotions[1].term, 'rocker garlic press'); // $90
+});
+
+test('does NOT promote a high-ACOS term (55% > 25% target) — it re-bids down', () => {
+  const r = run();
+  assert.equal(findPromo(r, 'garlic mincer tool'), undefined);
+  const b = findRebid(r, 'garlic mincer tool');
+  assert.ok(b, 'high-ACOS converting term re-bid instead of promoted');
+  assert.equal(b.direction, 'down');
+});
+
+test('re-bids DOWN an overpaying term, capped at -50%, flagged as losing vs break-even', () => {
+  const r = run();
+  const b = findRebid(r, 'garlic mincer tool');
+  assert.equal(b.oldBid, 0.88);
+  // ideal $0.40 but -50% cut floor is $0.44 -> capped
+  assert.equal(b.newBid, 0.44);
+  assert.equal(b.capped, true);
+  assert.match(b.why, /losing: ACOS above 35% break-even/);
+});
+
+test('re-bids UP an underpriced converter, capped at +100%', () => {
+  const r = run();
+  const b = findRebid(r, 'professional garlic press');
+  assert.ok(b && b.direction === 'up');
+  assert.equal(b.oldBid, 0.2);
+  // ideal $1.00 but +100% ceiling is $0.40 -> capped
+  assert.equal(b.newBid, 0.4);
+  assert.equal(b.capped, true);
+  assert.equal(b.changePct, 100);
+});
+
+test('re-bids ranked by magnitude of change', () => {
+  const r = run();
+  assert.equal(r.rebids[0].term, 'professional garlic press'); // +100%
+  assert.equal(r.rebids[1].term, 'garlic mincer tool'); // -50%
+});
+
+test('computes correct account totals and blended ACOS', () => {
+  const r = run();
+  assert.equal(r.totals.terms, 7);
+  assert.equal(r.totals.clicks, 178);
+  assert.equal(r.totals.spend, 84.0);
+  assert.equal(r.totals.sales, 450.0);
+  assert.equal(r.totals.orders, 30);
+  assert.equal(r.totals.acos, 18.67); // 84/450
+});
+
+test('inventory gate suppresses scaling on a low-inventory campaign', () => {
+  const r = optimize(csv, { ...CFG, lowInventoryCampaigns: ['Auto - Garlic Press'] });
+  // stainless + rocker garlic press were promotions from that auto campaign
+  assert.equal(findPromo(r, 'stainless garlic press'), undefined);
+  assert.equal(findPromo(r, 'rocker garlic press'), undefined);
+  const held = r.held.find((h) => h.term === 'stainless garlic press');
+  assert.ok(held && held.action === 'promote-suppressed', 'promotion suppressed by inventory gate');
+  assert.match(held.reason, /low inventory/);
+  // negatives from the same campaign still fire (a stock-out does not un-waste spend)
+  assert.ok(findNeg(r, 'garlic press'), 'negatives unaffected by inventory gate');
+});
+
+test('margin-only config sets target below break-even (0.75 x margin)', () => {
+  const r = optimize(csv, { margin: 40 }); // no explicit targetAcos
+  assert.equal(r.config.margin, 40);
+  assert.equal(r.config.targetAcos, 30); // 40 * 0.75
+  assert.equal(r.config.breakEvenAcos, 40);
+});
+
+test('deterministic: same input -> byte-identical output', () => {
+  const a = JSON.stringify(optimize(csv, CFG));
+  const b = JSON.stringify(optimize(csv, CFG));
+  assert.equal(a, b);
+});
+
+test('JSON report input parses through the same path as CSV', () => {
+  const r = optimize(jsonText, CFG);
+  assert.equal(r.totals.terms, 3);
+  assert.ok(findNeg(r, 'garlic press'));
+  assert.ok(findPromo(r, 'stainless garlic press'));
+  assert.ok(findRebid(r, 'professional garlic press'));
+});
+
+test('every proposal is propose-only and carries its numbers', () => {
+  const r = run();
+  for (const n of r.negatives) assert.ok(typeof n.spendStopped === 'number' && n.reason);
+  for (const p of r.promotions) assert.ok(typeof p.startingBid === 'number' && p.marginMath);
+  for (const b of r.rebids) assert.ok(b.oldBid >= 0 && b.newBid >= 0 && b.why);
+  assert.match(r.summary.headline, /PROPOSE-ONLY/);
+});

package/agent-cores/content-ops/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@agent-cores/content-ops",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Content-operations engine. Deterministic: parse a CMS export, compute keep/update/retire decisions with evidence, metadata gaps, and migration-readiness QA. No LLM in the core.",
+  "bin": {
+    "content-ops": "src/cli.mjs"
+  },
+  "scripts": {
+    "test": "node --test",
+    "inventory": "node src/cli.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/agent-cores/content-ops/src/cli.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+// Real CLI.
+//   content-ops <file.csv|file.json> [--asof YYYY-MM-DD] [--pretty]
+// Reads a CMS export from disk, computes the inventory, prints JSON to stdout
+// (machine-readable) and a one-line summary to stderr.
+
+import { readFileSync } from 'node:fs';
+import { inventoryFromText } from './inventory.mjs';
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--asof') args.asof = argv[++i];
+    else if (a === '--pretty') args.pretty = true;
+    else if (a === '--csv') args.hint = 'csv';
+    else if (a === '--json') args.hint = 'json';
+    else args._.push(a);
+  }
+  return args;
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const file = args._[0];
+  if (!file) {
+    console.error('Usage: content-ops <file.csv|file.json> [--asof YYYY-MM-DD] [--pretty]');
+    process.exitCode = 1;
+    return;
+  }
+
+  const hint = args.hint ?? (file.toLowerCase().endsWith('.json') ? 'json' : file.toLowerCase().endsWith('.csv') ? 'csv' : null);
+  const text = readFileSync(file, 'utf8');
+  const result = inventoryFromText(text, hint, { asOf: args.asof });
+
+  const c = result.counts;
+  const m = result.migrationReadiness;
+  console.error(
+    `content-ops: ${c.total} URLs (asOf ${result.asOf}) — ` +
+      `keep ${c.keep} / update ${c.update} / retire ${c.retire} / review ${c.review} — ` +
+      `${m.redirectsRequired} redirect(s) needed, readiness ${m.readinessScore}/100`,
+  );
+  console.log(JSON.stringify(result, null, args.pretty ? 2 : 0));
+}
+
+try {
+  main();
+} catch (err) {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exitCode = 1;
+}