weftens 0.0.1 → 0.1.0

package/agent-cores/seo-content/src/strategy.mjs

@@ -0,0 +1,266 @@
+// Deterministic content & entity SEO strategy engine. No LLM.
+//
+// Input: normalized search-performance records (query, url, clicks, impressions,
+// ctr, position, volume). Output: a keyword strategy — striking-distance keywords,
+// high-impression/low-CTR opportunities, cannibalization, topic clusters, and a
+// ranked opportunity list with the arithmetic shown on every row.
+//
+// Every projection is a modeled ESTIMATE (labeled). Cannibalization is observed
+// directly in the data (labeled verified-in-data). Nothing here writes prose.
+
+// Organic click-through rate by SERP position. Conservative industry-style curve;
+// used to model the click ceiling a page is leaving on the table. Estimates only.
+const CTR_CURVE = {
+  1: 0.283, 2: 0.157, 3: 0.110, 4: 0.080, 5: 0.061,
+  6: 0.048, 7: 0.040, 8: 0.033, 9: 0.028, 10: 0.025,
+  11: 0.015, 12: 0.013, 13: 0.012, 14: 0.011, 15: 0.010,
+  16: 0.009, 17: 0.008, 18: 0.008, 19: 0.007, 20: 0.007,
+};
+
+export function expectedCtr(position) {
+  if (position == null || !Number.isFinite(position)) return 0;
+  if (position < 1) return CTR_CURVE[1];
+  if (position > 20) return 0.005;
+  const lo = Math.floor(position);
+  const hi = Math.ceil(position);
+  if (lo === hi) return CTR_CURVE[lo];
+  const frac = position - lo;
+  return CTR_CURVE[lo] + (CTR_CURVE[hi] - CTR_CURVE[lo]) * frac; // linear interpolation
+}
+
+const STOPWORDS = new Set([
+  'a', 'an', 'the', 'to', 'for', 'of', 'in', 'on', 'at', 'and', 'or', 'with',
+  'my', 'your', 'is', 'are', 'how', 'what', 'best', 'near', 'me', 'do', 'i',
+  'can', 'you', 'vs', 'get', 'use',
+]);
+
+// Deterministic intent staging from lexical signals. Precedence: act > compare > learn.
+const INTENT_RULES = [
+  ['act', /\b(buy|price|pricing|cost|costs|cheap|cheapest|deal|deals|coupon|discount|order|shop|hire|book|booking|near me|for sale|quote|demo|sign ?up|trial|subscribe|download|free)\b/],
+  ['compare', /\b(best|top|vs|versus|review|reviews|comparison|compare|alternative|alternatives|which|better)\b/],
+  ['learn', /\b(how|what|why|when|who|where|guide|tutorial|ideas|examples|tips|meaning|definition|learn|explained)\b/],
+];
+
+export function classifyIntent(query) {
+  const q = ` ${query.toLowerCase()} `;
+  for (const [stage, re] of INTENT_RULES) {
+    if (re.test(q)) return stage;
+  }
+  return 'unknown';
+}
+
+const round = (n, d = 0) => {
+  const f = 10 ** d;
+  return Math.round(n * f) / f;
+};
+const pct = (fraction) => `${round(fraction * 100, 1)}%`;
+
+export function buildStrategy(records, options = {}) {
+  const cfg = {
+    strikingMin: 11,
+    strikingMax: 20,
+    strikingTarget: 5, // realistic mid-page-one landing spot to model against
+    lowCtrMaxPosition: 10,
+    lowCtrMinImpressions: 100,
+    lowCtrRatio: 0.7, // flag when actual CTR is below 70% of the position's expected CTR
+    cannibalMinImpressions: 1,
+    ...options,
+  };
+
+  const rows = records
+    .filter((r) => r.query)
+    .map((r) => ({ ...r, intent: classifyIntent(r.query) }));
+
+  const strikingDistance = [];
+  const lowCtrOpportunities = [];
+  const opportunities = [];
+
+  for (const r of rows) {
+    const pos = r.position;
+    if (pos == null) continue;
+
+    // --- Striking distance: page-two keywords one push from page one ---
+    if (pos >= cfg.strikingMin && pos <= cfg.strikingMax) {
+      const projectedCtr = expectedCtr(cfg.strikingTarget);
+      const projectedClicks = r.impressions * projectedCtr;
+      const gain = Math.max(0, projectedClicks - r.clicks);
+      const rec = {
+        query: r.query,
+        url: r.url,
+        intent: r.intent,
+        position: pos,
+        impressions: r.impressions,
+        clicks: r.clicks,
+        ctr: r.ctr,
+        lever: 'improve-rank',
+        target: `position ${cfg.strikingTarget}`,
+        projectedCtr: round(projectedCtr, 4),
+        projectedClicks: round(projectedClicks, 1),
+        opportunityClicks: round(gain, 1),
+        confidence: 'estimated',
+        math: `pos ${round(pos, 1)} (page 2) → target pos ${cfg.strikingTarget}: `
+          + `${r.impressions} impr × ${pct(projectedCtr)} = ${round(projectedClicks, 1)} est. clicks `
+          + `− ${r.clicks} now = +${round(gain, 1)}`,
+      };
+      strikingDistance.push(rec);
+      opportunities.push(rec);
+      continue;
+    }
+
+    // --- High-impression / low-CTR: ranks on page one but underclicks its slot ---
+    if (pos <= cfg.lowCtrMaxPosition && r.impressions >= cfg.lowCtrMinImpressions) {
+      const expCtr = expectedCtr(pos);
+      if (expCtr > 0 && r.ctr < expCtr * cfg.lowCtrRatio) {
+        const projectedClicks = r.impressions * expCtr;
+        const gain = Math.max(0, projectedClicks - r.clicks);
+        const rec = {
+          query: r.query,
+          url: r.url,
+          intent: r.intent,
+          position: pos,
+          impressions: r.impressions,
+          clicks: r.clicks,
+          ctr: r.ctr,
+          lever: 'improve-ctr',
+          target: 'title/meta rewrite',
+          projectedCtr: round(expCtr, 4),
+          projectedClicks: round(projectedClicks, 1),
+          opportunityClicks: round(gain, 1),
+          confidence: 'estimated',
+          math: `pos ${round(pos, 1)}: actual CTR ${pct(r.ctr)} vs expected ${pct(expCtr)}; `
+            + `${r.impressions} impr × ${pct(expCtr)} = ${round(projectedClicks, 1)} est. clicks `
+            + `− ${r.clicks} now = +${round(gain, 1)}`,
+        };
+        lowCtrOpportunities.push(rec);
+        opportunities.push(rec);
+      }
+    }
+  }
+
+  const cannibalization = detectCannibalization(rows, cfg);
+  const clusters = clusterTopics(rows);
+
+  // Ranked opportunity list: highest modeled click gain first, deterministic tie-break.
+  const cmp = (a, b) => (b.opportunityClicks - a.opportunityClicks)
+    || a.query.localeCompare(b.query)
+    || (a.url || '').localeCompare(b.url || '');
+  opportunities.sort(cmp);
+  strikingDistance.sort(cmp);
+  lowCtrOpportunities.sort(cmp);
+
+  const totalOpportunityClicks = round(
+    opportunities.reduce((s, o) => s + o.opportunityClicks, 0), 1,
+  );
+
+  return {
+    input: {
+      rows: rows.length,
+      hasUrls: rows.some((r) => r.url),
+      withPosition: rows.filter((r) => r.position != null).length,
+    },
+    summary: buildSummary({
+      rows, strikingDistance, lowCtrOpportunities, cannibalization,
+      opportunities, totalOpportunityClicks,
+    }),
+    totalOpportunityClicks,
+    strikingDistance,
+    lowCtrOpportunities,
+    cannibalization,
+    clusters,
+    opportunities,
+  };
+}
+
+function detectCannibalization(rows, cfg) {
+  const byQuery = new Map();
+  for (const r of rows) {
+    if (!r.url) continue;
+    if (r.impressions < cfg.cannibalMinImpressions) continue;
+    if (!byQuery.has(r.query)) byQuery.set(r.query, new Map());
+    const urls = byQuery.get(r.query);
+    // aggregate in case the same query+url appears on multiple rows
+    const prev = urls.get(r.url) || { url: r.url, clicks: 0, impressions: 0, position: r.position };
+    prev.clicks += r.clicks;
+    prev.impressions += r.impressions;
+    // keep the best (lowest) position seen for that url
+    if (r.position != null && (prev.position == null || r.position < prev.position)) prev.position = r.position;
+    urls.set(r.url, prev);
+  }
+
+  const out = [];
+  for (const [query, urlMap] of byQuery) {
+    if (urlMap.size < 2) continue;
+    const urls = [...urlMap.values()].sort(
+      (a, b) => (b.impressions - a.impressions) || a.url.localeCompare(b.url),
+    );
+    const totalImpr = urls.reduce((s, u) => s + u.impressions, 0);
+    const primary = urls[0];
+    const competing = urls.slice(1);
+    const splitImpr = totalImpr - primary.impressions;
+    const splitShare = totalImpr > 0 ? splitImpr / totalImpr : 0;
+    out.push({
+      query,
+      urlCount: urls.length,
+      urls: urls.map((u) => ({
+        url: u.url,
+        clicks: u.clicks,
+        impressions: u.impressions,
+        position: u.position,
+      })),
+      primaryUrl: primary.url,
+      competingUrls: competing.map((u) => u.url),
+      splitShare: round(splitShare, 3),
+      severity: splitShare >= 0.2 ? 'warn' : 'info',
+      confidence: 'verified-in-data',
+      note: `${urls.length} URLs rank for "${query}"; ${pct(splitShare)} of impressions land off the primary URL (${primary.url}).`,
+    });
+  }
+  out.sort((a, b) => (b.splitShare - a.splitShare) || a.query.localeCompare(b.query));
+  return out;
+}
+
+// Heuristic (not semantic) topic clustering: group queries by their highest-signal
+// shared token. Deterministic; used to sketch pillar/cluster structure.
+function clusterTopics(rows) {
+  const freq = new Map();
+  const tokenize = (q) => q.toLowerCase().split(/[^a-z0-9]+/).filter((t) => t && t.length > 2 && !STOPWORDS.has(t));
+  for (const r of rows) {
+    for (const t of new Set(tokenize(r.query))) freq.set(t, (freq.get(t) || 0) + 1);
+  }
+  const clusters = new Map();
+  for (const r of rows) {
+    const tokens = tokenize(r.query);
+    let label = tokens[0] || r.query.toLowerCase();
+    let bestFreq = -1;
+    for (const t of tokens) {
+      const f = freq.get(t) || 0;
+      if (f > bestFreq || (f === bestFreq && t < label)) { bestFreq = f; label = t; }
+    }
+    if (!clusters.has(label)) clusters.set(label, { topic: label, queries: [], impressions: 0, clicks: 0 });
+    const c = clusters.get(label);
+    c.queries.push(r.query);
+    c.impressions += r.impressions;
+    c.clicks += r.clicks;
+  }
+  return [...clusters.values()]
+    .map((c) => ({ ...c, size: c.queries.length, queries: [...c.queries].sort() }))
+    .sort((a, b) => (b.impressions - a.impressions) || (b.size - a.size) || a.topic.localeCompare(b.topic));
+}
+
+// Factual, templated read — filled from the numbers, not generated prose.
+function buildSummary(s) {
+  const parts = [];
+  parts.push(`${s.rows.length} queries analyzed; ${s.opportunities.length} carry modeled upside worth ~${s.totalOpportunityClicks} est. clicks/mo.`);
+  if (s.strikingDistance.length) {
+    const top = s.strikingDistance[0];
+    parts.push(`${s.strikingDistance.length} striking-distance keyword(s) (page 2) — biggest: "${top.query}" (+${top.opportunityClicks} est. clicks if moved to top of page 1).`);
+  }
+  if (s.lowCtrOpportunities.length) {
+    const top = s.lowCtrOpportunities[0];
+    parts.push(`${s.lowCtrOpportunities.length} page-one keyword(s) underclicking their slot — biggest: "${top.query}" (title/meta lever, +${top.opportunityClicks} est. clicks).`);
+  }
+  if (s.cannibalization.length) {
+    parts.push(`${s.cannibalization.length} query(ies) split across multiple URLs (cannibalization) — consolidate to one canonical page.`);
+  }
+  return parts.join(' ');
+}

package/agent-cores/seo-content/test/fixtures/gsc-sample.csv

@@ -0,0 +1,11 @@
+Query,Landing Page,Clicks,Impressions,CTR,Position
+crm for real estate agents,https://acme.example/crm-real-estate,20,"2,000",1.00%,14.0
+best crm for solar installers,https://acme.example/crm-solar,8,900,0.89%,17.4
+free crm,https://acme.example/free-crm,50,"5,000",1.00%,4.0
+crm pricing,https://acme.example/pricing,40,800,5.00%,6.0
+crm pricing,https://acme.example/plans,5,300,1.67%,9.0
+best crm software,https://acme.example/best-crm,110,"1,000",11.00%,3.0
+how to use a crm,https://acme.example/crm-guide,300,"3,000",10.00%,2.0
+buy crm software online,https://acme.example/checkout,2,60,3.33%,8.0
+enterprise crm platform,https://acme.example/enterprise,1,1200,0.08%,42.0
+crm integrations,https://acme.example/integrations,12,1500,0.80%,7.0

package/agent-cores/seo-content/test/parse.test.mjs

@@ -0,0 +1,59 @@
+// Parser tests — run with `node --test`. Confirms the CSV/JSON normalizer turns
+// messy real-export columns into clean numeric records.
+
+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 { parseRecords, parseCsv, _internal } from '../src/parse.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const csv = readFileSync(join(__dirname, 'fixtures', 'gsc-sample.csv'), 'utf8');
+
+test('CSV parser respects quoted fields with embedded commas', () => {
+  const rows = parseCsv('a,b\n"1,234",x\n');
+  assert.deepEqual(rows, [['a', 'b'], ['1,234', 'x']]);
+});
+
+test('thousands separators and percent CTR parse to real numbers', () => {
+  const recs = parseRecords(csv);
+  const rre = recs.find((r) => r.query === 'crm for real estate agents');
+  assert.equal(rre.impressions, 2000, '"2,000" -> 2000');
+  assert.equal(rre.clicks, 20);
+  assert.equal(rre.ctr, 0.01, '1.00% -> 0.01');
+  assert.equal(rre.position, 14);
+});
+
+test('bare CTR ">1" is treated as a percentage, "<=1" as a fraction', () => {
+  const near = (a, b) => assert.ok(Math.abs(a - b) < 1e-9, `${a} ~= ${b}`);
+  near(_internal.parseCtr('5.2'), 0.052);
+  near(_internal.parseCtr('0.052'), 0.052);
+  near(_internal.parseCtr('5.2%'), 0.052);
+});
+
+test('header aliases normalize across GSC/Semrush/Ahrefs naming', () => {
+  assert.equal(_internal.normalizeHeader('Keyword'), 'query');
+  assert.equal(_internal.normalizeHeader('Avg. Position'), 'position');
+  assert.equal(_internal.normalizeHeader('URL Clicks'), 'clicks');
+  assert.equal(_internal.normalizeHeader('Search Volume'), 'volume');
+});
+
+test('CTR is derived from clicks/impressions when the column is absent', () => {
+  const recs = parseRecords('Keyword,URL,Clicks,Impressions,Position\nx,https://a,25,1000,6\n');
+  assert.equal(recs[0].ctr, 0.025);
+});
+
+test('JSON input yields the same normalized shape as CSV', () => {
+  const recs = parseRecords(JSON.stringify([
+    { query: 'x', url: 'https://a', clicks: 10, impressions: 500, ctr: '2%', position: 8 },
+  ]));
+  assert.equal(recs.length, 1);
+  assert.deepEqual(recs[0], {
+    query: 'x', url: 'https://a', clicks: 10, impressions: 500, ctr: 0.02, position: 8, volume: null,
+  });
+});
+
+test('all ten fixture rows parse (none dropped)', () => {
+  assert.equal(parseRecords(csv).length, 10);
+});

package/agent-cores/seo-content/test/strategy.test.mjs

@@ -0,0 +1,108 @@
+// Strategy-engine tests — run with `node --test`. Every assertion pins a SPECIFIC
+// seeded issue in the fixture. If these pass, the engine is doing real arithmetic
+// and threshold logic, 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 { parseRecords } from '../src/parse.mjs';
+import { buildStrategy, expectedCtr, classifyIntent } from '../src/strategy.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const csv = readFileSync(join(__dirname, 'fixtures', 'gsc-sample.csv'), 'utf8');
+const records = parseRecords(csv);
+const result = buildStrategy(records);
+
+const q = (list, query) => list.find((x) => x.query === query);
+
+test('striking-distance detects the two page-two keywords (pos 11-20)', () => {
+  const queries = result.strikingDistance.map((r) => r.query).sort();
+  assert.deepEqual(queries, ['best crm for solar installers', 'crm for real estate agents']);
+  for (const r of result.strikingDistance) {
+    assert.ok(r.position >= 11 && r.position <= 20);
+    assert.equal(r.lever, 'improve-rank');
+  }
+});
+
+test('striking-distance click math is real: 2000 impr x CTR@pos5 - 20 now', () => {
+  const rec = q(result.strikingDistance, 'crm for real estate agents');
+  // expectedCtr(5) = 0.061 -> 2000*0.061 = 122 ; gain = 122 - 20 = 102
+  assert.equal(rec.projectedCtr, 0.061);
+  assert.equal(rec.projectedClicks, 122);
+  assert.equal(rec.opportunityClicks, 102);
+  assert.match(rec.math, /2000 impr/);
+});
+
+test('high-impression/low-CTR flags "free crm" with the title/meta lever', () => {
+  const rec = q(result.lowCtrOpportunities, 'free crm');
+  assert.ok(rec, 'free crm surfaced as a low-CTR opportunity');
+  assert.equal(rec.lever, 'improve-ctr');
+  // pos4 expected CTR 0.08 -> 5000*0.08 = 400 ; gain = 400 - 50 = 350
+  assert.equal(rec.projectedClicks, 400);
+  assert.equal(rec.opportunityClicks, 350);
+});
+
+test('a healthy page-one keyword is NOT flagged as low-CTR', () => {
+  // "best crm software" pos3, 11% CTR is above 70% of expected(3)=0.11
+  assert.equal(q(result.lowCtrOpportunities, 'best crm software'), undefined);
+});
+
+test('cannibalization: "crm pricing" splits across two URLs', () => {
+  const rec = q(result.cannibalization, 'crm pricing');
+  assert.ok(rec, 'cannibalization detected');
+  assert.equal(rec.urlCount, 2);
+  assert.equal(rec.primaryUrl, 'https://acme.example/pricing');
+  assert.deepEqual(rec.competingUrls, ['https://acme.example/plans']);
+  // 300 of 1100 impressions land off the primary URL -> ~0.273, above the 0.2 warn line
+  assert.equal(rec.splitShare, 0.273);
+  assert.equal(rec.severity, 'warn');
+  assert.equal(rec.confidence, 'verified-in-data');
+});
+
+test('a single-URL query is not reported as cannibalization', () => {
+  assert.equal(q(result.cannibalization, 'free crm'), undefined);
+});
+
+test('opportunity list is ranked by modeled click gain, descending', () => {
+  const gains = result.opportunities.map((o) => o.opportunityClicks);
+  for (let i = 1; i < gains.length; i += 1) {
+    assert.ok(gains[i - 1] >= gains[i], 'sorted descending by opportunityClicks');
+  }
+  assert.ok(result.totalOpportunityClicks > 0);
+});
+
+test('intent classification is lexical and deterministic', () => {
+  assert.equal(classifyIntent('buy crm software online'), 'act');
+  assert.equal(classifyIntent('best crm software'), 'compare');
+  assert.equal(classifyIntent('how to use a crm'), 'learn');
+  assert.equal(classifyIntent('enterprise crm platform'), 'unknown');
+});
+
+test('expectedCtr curve is monotonic down and interpolates fractional positions', () => {
+  assert.ok(expectedCtr(1) > expectedCtr(5));
+  assert.ok(expectedCtr(5) > expectedCtr(10));
+  assert.ok(expectedCtr(10) > expectedCtr(20));
+  const mid = expectedCtr(1.5);
+  assert.ok(mid < expectedCtr(1) && mid > expectedCtr(2), 'pos 1.5 lies between pos 1 and 2');
+});
+
+test('topic clustering groups the crm queries under a shared token', () => {
+  const crm = result.clusters.find((c) => c.topic === 'crm');
+  assert.ok(crm, 'a "crm" cluster exists');
+  assert.ok(crm.size >= 5);
+  assert.ok(crm.impressions > 0);
+});
+
+test('same input -> byte-identical output (deterministic)', () => {
+  const a = JSON.stringify(buildStrategy(parseRecords(csv)));
+  const b = JSON.stringify(buildStrategy(parseRecords(csv)));
+  assert.equal(a, b);
+});
+
+test('the templated read reports real counts, no fabricated prose', () => {
+  assert.match(result.summary, /10 queries analyzed/);
+  assert.match(result.summary, /striking-distance/);
+  assert.match(result.summary, /cannibalization/);
+});

package/agent-cores/seo-technical/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@agent-cores/seo-technical",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Technical-SEO auditor. Deterministic: fetch a URL, compute crawl/index/render findings. No LLM in the core.",
+  "bin": {
+    "seo-technical": "src/cli.mjs"
+  },
+  "scripts": {
+    "test": "node --test",
+    "audit": "node src/cli.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}