Open-source agentic AI Search Execution Platform. Track AI visibility, find opportunities, and let agents turn signals into prioritized actions and drafted fixes across ChatGPT, Claude, Gemini, Google AI Overviews, Google AI Mode, Perplexity, Grok, and Microsoft Copilot.
TypeScript aeoai-agentai-searchanswer-engine-optimizationbrand-monitoringchatgptclaudecopilotdockergeminigeogoogle-ai-overviewsgrokmcpnextjsopen-sourceperplexityseosupabasetypescript
fix(content): keep internal indexes and misspelled competitors out of opportunity text (#1026)
Cihan8e579e41dc42
diff --git a/server/src/lib/action-center/from-opportunity.js b/server/src/lib/action-center/from-opportunity.jsindex 2780dc28b..e41dfa3a7 100644--- a/server/src/lib/action-center/from-opportunity.js+++ b/server/src/lib/action-center/from-opportunity.js@@ -111,11 +111,16 @@ export function initialTaskStatus(taskKey, opportunity) {* was already sent, and records the action on the opportunity.** @param {object} opportunity - the content_opportunities row- * @param {{ assetKey?: string|null, userId: string }} opts+ * @param {{ assetKey?: string|null, userId: string, readable?: object }} opts - `readable`:+ * the same row with its text cleaned for reading (opportunity-text.js); the+ * action shows that text, while the row written back keeps its own.* @returns {Promise<{ actionId: string, created: boolean }>}*/-export async function sendToActionCenter(opportunity, { assetKey = null, userId }) {- const assets = opportunityAssets(opportunity);+export async function sendToActionCenter(+ opportunity,+ { assetKey = null, userId, readable = opportunity },+) {+ const assets = opportunityAssets(readable);const chosen = assetKey ? assets.filter((a) => a.key === assetKey) : assets;if (!chosen.length) {const err = new Error('Asset not found');@@ -155,7 +160,7 @@ export async function sendToActionCenter(opportunity, { assetKey = null, userIdsource: OPPORTUNITY_ACTION_KIND,opportunityId: opportunity.id,assetKey,- title: assetKey ? chosen[0].title : opportunity.title,+ title: assetKey ? chosen[0].title : readable.title,decision: chosen[0].decision,assets: chosen.map(({ key: k, type, channel, decision, title }) => ({key: k,diff --git a/server/src/lib/opportunity-generator.js b/server/src/lib/opportunity-generator.jsindex 2730d04c9..dafa7c77e 100644--- a/server/src/lib/opportunity-generator.js+++ b/server/src/lib/opportunity-generator.js@@ -27,6 +27,7 @@ import {import { loadClusterOpportunities, loadOpportunityBaskets } from './open-opportunities.js';import { basket, duplicateThreshold, findDuplicate, storedBasket } from './opportunity-dedup.js';import { loadClusters } from './prompt-clusters.js';+import { cleanOpportunityText } from './opportunity-text.js';import { reopenStrengthened } from './opportunity-reopen.js';import {claimOpportunitySlots,@@ -264,7 +265,7 @@ export async function generateContentOpportunities(.toISOString().slice(0, 10);const memberIds = clusters.flatMap((c) => c.prompt_ids);- const [prompts, volumes, metricsRes, topicsRes, domainsRes, existing, pagesRes] =+ const [prompts, volumes, metricsRes, topicsRes, domainsRes, existing, pagesRes, competitorsRes] =await Promise.all([loadPromptTexts(memberIds),selectInChunks(memberIds, (chunk) =>@@ -286,9 +287,11 @@ export async function generateContentOpportunities(.select('url, title, h1, description, lastmod, ai_citations, ga_sessions').eq('brand_id', brandId).eq('fetch_status', 200),+ supabaseAdmin.from('competitors').select('name').eq('brand_id', brandId),]);if (volumes.error) throw new Error(volumes.error.message);if (pagesRes.error) throw new Error(pagesRes.error.message);+ const competitorNamesList = (competitorsRes.data || []).map((c) => c.name);if (metricsRes.error) throw new Error(metricsRes.error.message);const byPrompt = new Map(prompts.map((p) => [p.id, { text: p.text }]));@@ -463,6 +466,24 @@ ${if (!Number.isInteger(opp.clusterIndex) || !cand || done.has(cand.id)) continue;done.add(cand.id);+ // CONTENT-005: any bracketed index the model repeated becomes what it+ // stood for in this run, and misspelled competitors their real names.+ const clean = (text) =>+ cleanOpportunityText(text, {+ clusters: picked.map((p) => clusterById.get(p.id).label),+ pages: pagesFor.get(cand.id),+ existing: shown.map((o) => o.title),+ competitors: competitorNamesList,+ // The prompt numbered clusters [0], [1]…: a lone index is one of them.+ bare: true,+ });+ opp.title = clean(opp.title);+ opp.description = clean(opp.description);+ opp.supportingAssets = (opp.supportingAssets || []).map((a) => ({+ ...a,+ title: clean(a.title),+ }));+const target = Number.isInteger(opp.sameAs) ? shown[opp.sameAs] : null;if (target) {// Related clusters deleted by a re-clustering since are dropped here.diff --git a/server/src/lib/opportunity-text.js b/server/src/lib/opportunity-text.jsnew file mode 100644index 000000000..59d882ab7--- /dev/null+++ b/server/src/lib/opportunity-text.js@@ -0,0 +1,171 @@+/**+ * Readable opportunity text (CONTENT-005).+ *+ * The generator shows the model its inputs by bracketed index — clusters as+ * [0], pages as [P0], existing opportunities as [E0] — and asks it never to+ * repeat them. It sometimes does anyway, and the older per-prompt generator+ * often did: "targeting prompt [0] to close the gap", "improve [P2] by …+ * from [P1]". Competitor names also come back misspelled ("Profund").+ *+ * New opportunities are cleaned before they're saved, with the run's own+ * clusters, pages and opportunities to resolve each index. Stored ones are+ * cleaned when they're read, with what the row itself records, so old text+ * reads properly without being rewritten.+ */++/**+ * "prompt [0]", "cluster [1]", "page [P2]" and bare "[P2]" / "[E0]", with the+ * leading noun so "prompt [0]" becomes the prompt itself rather than+ * "prompt "…"". A bare "[3]" is only an index when the caller says so+ * (`bare`): in stored text it may as well be ordinary writing.+ */+const NAMED = /\b(?:prompts?|clusters?|pages?|opportunit(?:y|ies))\s*\[(P|E)?(\d+)\]/gi;+const PREFIXED = /\s?\[(P|E)(\d+)\]/gi;+const BARE = /\s?\[()(\d+)\]/g;++/** A leaked index of any kind, for checks and tests. */+export const LEAKED_REFERENCE = /\[(?:P|E)?\d+\]/i;++const quote = (text) => `"${String(text).trim()}"`;++/**+ * Replaces every bracketed index with what it stood for: a cluster's label, a+ * page's title or URL, an existing opportunity's title. Without that list (or+ * past its end) a prompt index becomes `prompt` (the opportunity's own prompt)+ * or "this prompt", and the others a neutral word ("the page"). The spacing+ * around it is tidied.+ *+ * @param {string} text+ * @param {{+ * clusters?: string[],+ * pages?: { title?: string|null, h1?: string|null, url?: string }[],+ * existing?: string[],+ * prompt?: string|null,+ * bare?: boolean,+ * }} ctx - `bare`: also treat a lone "[3]" as a cluster index+ */+export function resolveReferences(+ text,+ { clusters = [], pages = [], existing = [], prompt = null, bare = false } = {},+) {+ if (!text || !LEAKED_REFERENCE.test(text)) return text;+ const resolve = (match, kind, digits) => {+ const n = Number(digits);+ const lead = /^\s/.test(match) ? ' ' : '';+ if (kind?.toUpperCase() === 'P') {+ const page = pages[n];+ return `${lead}${page ? page.title || page.h1 || page.url : 'the page'}`;+ }+ if (kind?.toUpperCase() === 'E') {+ return existing[n] ? `${lead}${quote(existing[n])}` : `${lead}an existing opportunity`;+ }+ if (clusters[n]) return `${lead}${quote(clusters[n])}`;+ return `${lead}${prompt ? quote(prompt) : 'this prompt'}`;+ };+ let replaced = text.replace(NAMED, resolve).replace(PREFIXED, resolve);+ if (bare) replaced = replaced.replace(BARE, resolve);+ return replaced+ .replace(/\s{2,}/g, ' ')+ .replace(/\s+([,.;:!?])/g, '$1')+ .trim();+}++/** Edit distance, with an early exit once it exceeds `max`. */+export function distance(a, b, max = Infinity) {+ if (Math.abs(a.length - b.length) > max) return max + 1;+ let prev = Array.from({ length: b.length + 1 }, (_, j) => j);+ for (let i = 1; i <= a.length; i++) {+ const row = [i];+ let best = i;+ for (let j = 1; j <= b.length; j++) {+ row[j] = Math.min(prev[j] + 1, row[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));+ best = Math.min(best, row[j]);+ }+ if (best > max) return max + 1;+ prev = row;+ }+ return prev[b.length];+}++/** Typos allowed for a name: one for short names, two from eight letters. */+const allowedTypos = (name) => (name.length >= 8 ? 2 : 1);++const WORD = /[\p{L}\p{N}][\p{L}\p{N}'’.-]*/gu;++/**+ * Corrects misspelled competitor names to the brand's configured spelling:+ * "Profund" becomes "Profound". Only words close to a configured name are+ * touched — capitalized like a name, at most one typo (two for names of+ * eight letters or more), and never names shorter than five letters, where+ * a typo is too likely to be another word — and a word that already matches+ * (in any case) stays.+ *+ * @param {string} text+ * @param {string[]} names - the brand's competitor names+ */+export function fixCompetitorNames(text, names = []) {+ const targets = names+ .map((n) => String(n ?? '').trim())+ .filter((n) => n.replace(/\s/g, '').length >= 5)+ .map((name) => ({ name, lower: name.toLowerCase(), words: name.split(/\s+/).length }));+ if (!text || targets.length === 0) return text;++ const words = [...text.matchAll(WORD)].map((m) => ({+ start: m.index,+ end: m.index + m[0].length,+ text: m[0].replace(/[.'’-]+$/, ''),+ }));+ const edits = [];+ for (let i = 0; i < words.length; i++) {+ for (const t of targets) {+ const span = words.slice(i, i + t.words);+ if (span.length < t.words) continue;+ const candidate = span.map((w) => w.text).join(' ');+ // Names are written as names: a lowercase word ("writes") is never+ // taken for a competitor ("Writer").+ if (candidate[0] !== candidate[0].toUpperCase()) continue;+ const lower = candidate.toLowerCase();+ if (lower === t.lower) continue;+ if (distance(lower, t.lower, allowedTypos(t.lower)) <= allowedTypos(t.lower)) {+ edits.push({ start: span[0].start, end: span[0].start + candidate.length, name: t.name });+ break;+ }+ }+ }+ let out = text;+ for (const e of edits.reverse()) out = out.slice(0, e.start) + e.name + out.slice(e.end);+ return out;+}++/** Both cleanups, references first. */+export function cleanOpportunityText(text, { competitors = [], ...refs } = {}) {+ if (!text) return text;+ return fixCompetitorNames(resolveReferences(text, refs), competitors);+}++/**+ * A stored opportunity row with readable title, description and asset titles.+ * The lists an index pointed into weren't stored — [P2] numbered the run's+ * candidate pages, not the target pages kept — so nothing is matched by+ * position: a page reads "the page", and a prompt index the prompt a+ * single-prompt opportunity was written for (or "this prompt"). Only certain+ * leaks are touched; a bare "[3]" may be ordinary writing. The stored row is+ * not changed.+ */+export function cleanStoredOpportunity(row, competitors = []) {+ if (!row) return row;+ const sd = row.source_data || {};+ const ctx = {+ competitors,+ prompt: row.cluster_id ? null : sd.promptText || null,+ };+ const clean = (t) => cleanOpportunityText(t, ctx);+ return {+ ...row,+ title: clean(row.title),+ description: clean(row.description),+ source_data: Array.isArray(sd.assets)+ ? { ...sd, assets: sd.assets.map((a) => ({ ...a, title: clean(a.title) })) }+ : row.source_data,+ };+}diff --git a/server/src/lib/opportunity-text.test.js b/server/src/lib/opportunity-text.test.jsnew file mode 100644index 000000000..0159ebe03--- /dev/null+++ b/server/src/lib/opportunity-text.test.js@@ -0,0 +1,139 @@+import { describe, expect, it } from 'vitest';+import {+ LEAKED_REFERENCE,+ cleanStoredOpportunity,+ distance,+ fixCompetitorNames,+ resolveReferences,+} from './opportunity-text.js';++// CONTENT-005: internal indexes and misspelled competitor names must not+// reach what users read.++describe('resolveReferences', () => {+ it('turns "prompt [0]" into the prompt itself', () => {+ expect(+ resolveReferences('Develop a pillar piece targeting prompt [0] to close the 48% gap.', {+ clusters: ['how to optimize content for AEO'],+ }),+ ).toBe(+ 'Develop a pillar piece targeting "how to optimize content for AEO" to close the 48% gap.',+ );+ });++ it('turns page indexes into page titles, or the URL without one', () => {+ expect(+ resolveReferences('We must defend and improve [P2] by incorporating features from [P1].', {+ pages: [+ { title: 'Home', url: 'https://a.com/' },+ { title: null, url: 'https://semrush.com/kb/ai-overviews' },+ { title: 'Google AI Overviews rank tracker', url: 'https://a.com/features' },+ ],+ }),+ ).toBe(+ 'We must defend and improve Google AI Overviews rank tracker by incorporating features from https://semrush.com/kb/ai-overviews.',+ );+ });++ it('names existing opportunities and cluster indexes', () => {+ expect(+ resolveReferences('Same need as [E0]; merge with cluster [1].', {+ existing: ['Best AI SEO tools guide'],+ clusters: ['AEO basics', 'AEO vs SEO'],+ }),+ ).toBe('Same need as "Best AI SEO tools guide"; merge with "AEO vs SEO".');+ });++ it('falls back to neutral words when an index has nothing behind it', () => {+ const out = resolveReferences('To address Prompt [1], update [P3] and see [E4].', {});+ expect(out).toBe('To address this prompt, update the page and see an existing opportunity.');+ expect(LEAKED_REFERENCE.test(out)).toBe(false);+ });++ it('treats a lone [3] as an index only when asked (the generator does)', () => {+ expect(resolveReferences('Answer [1] first.', { clusters: ['A', 'B'] })).toBe(+ 'Answer [1] first.',+ );+ expect(resolveReferences('Answer [1] first.', { clusters: ['A', 'B'], bare: true })).toBe(+ 'Answer "B" first.',+ );+ });++ it('leaves text without indexes untouched', () => {+ const text = 'Compare the top [best] tools of 2026.';+ expect(resolveReferences(text, {})).toBe(text);+ });+});++describe('fixCompetitorNames', () => {+ it('corrects a misspelled competitor to the configured name', () => {+ expect(+ fixCompetitorNames('Bridge the visibility deficit against Profund and Searchable.', [+ 'Profound',+ 'Searchable',+ ]),+ ).toBe('Bridge the visibility deficit against Profound and Searchable.');+ });++ it('handles multi-word names and keeps punctuation', () => {+ expect(fixCompetitorNames('Unlike Demo Cofee Co, we ship.', ['Demo Coffee Co'])).toBe(+ 'Unlike Demo Coffee Co, we ship.',+ );+ });++ it('leaves ordinary words and short names alone', () => {+ expect(fixCompetitorNames('Profit and profile matter more.', ['Profound'])).toBe(+ 'Profit and profile matter more.',+ );+ expect(fixCompetitorNames('Use Sem and Ahref.', ['Semr', 'Ahrefs'])).toBe(+ 'Use Sem and Ahrefs.',+ );+ });+});++describe('fixCompetitorNames on everyday words', () => {+ it('never takes a lowercase word for a competitor', () => {+ expect(fixCompetitorNames('Our team writes guides; Writr is a rival.', ['Writer'])).toBe(+ 'Our team writes guides; Writer is a rival.',+ );+ });+});++describe('distance', () => {+ it('is the edit distance, capped once it passes the limit', () => {+ expect(distance('profund', 'profound')).toBe(1);+ expect(distance('kitten', 'sitting')).toBe(3);+ expect(distance('a', 'abcdef', 2)).toBe(3);+ });+});++describe('cleanStoredOpportunity', () => {+ it('cleans an old single-prompt row without guessing what an index pointed at', () => {+ const row = {+ cluster_id: null,+ title: 'Optimize for prompt [0]',+ description: 'Beat Profund on [P0], the top [5] in the list.',+ source_data: {+ promptText: 'best AEO tools',+ targetPages: [{ title: 'Tools page', url: 'https://a.com/tools' }],+ assets: [{ key: 'a1', title: 'Refresh [P2]' }],+ },+ };+ const clean = cleanStoredOpportunity(row, ['Profound']);+ expect(clean.title).toBe('Optimize for "best AEO tools"');+ // [P0] numbered the run's candidate pages, not the stored target pages.+ expect(clean.description).toBe('Beat Profound on the page, the top [5] in the list.');+ expect(clean.source_data.assets[0].title).toBe('Refresh the page');+ expect(row.title).toBe('Optimize for prompt [0]');+ });++ it("doesn't name one of a cluster row's prompts for an index that numbered clusters", () => {+ const row = {+ cluster_id: 'c1',+ title: 'Merge with cluster [1]',+ description: null,+ source_data: { prompts: ['A', 'B'] },+ };+ expect(cleanStoredOpportunity(row).title).toBe('Merge with this prompt');+ });+});diff --git a/server/src/routes/content.js b/server/src/routes/content.jsindex a9828ceb6..a94f9a50e 100644--- a/server/src/routes/content.js+++ b/server/src/routes/content.js@@ -24,10 +24,25 @@ import {import { loadClusters } from '../lib/prompt-clusters.js';import { sendToActionCenter } from '../lib/action-center/from-opportunity.js';import { IDEA_MAX_LENGTH } from '../lib/opportunity-generator.js';+import { cleanStoredOpportunity } from '../lib/opportunity-text.js';const router = Router();-function mapOpportunityRow(row) {+/**+ * The brand's competitor names, which opportunity text is checked against+ * when it's read (CONTENT-005).+ */+async function competitorNames(brandId) {+ const { data } = await supabaseAdmin.from('competitors').select('name').eq('brand_id', brandId);+ return (data || []).map((c) => c.name);+}++/**+ * The API's opportunity. Text is shown cleaned of leaked internal indexes and+ * misspelled competitor names; the stored row is left as it is.+ */+function mapOpportunityRow(stored, competitors = []) {+ const row = cleanStoredOpportunity(stored, competitors);return {id: row.id,brandId: row.brand_id,@@ -365,8 +380,11 @@ router.get('/brand/:brandId', async (req, res) => {p_created_to: toBound,});- const [{ data, error: dataError, count }, { data: aggregateData, error: aggregateError }] =- await Promise.all([dataQuery, aggregateQuery]);+ const [+ { data, error: dataError, count },+ { data: aggregateData, error: aggregateError },+ competitors,+ ] = await Promise.all([dataQuery, aggregateQuery, competitorNames(brandId)]);if (dataError) {throw new Error(dataError.message);@@ -384,7 +402,7 @@ router.get('/brand/:brandId', async (req, res) => {};return res.json({- opportunities: (data || []).map(mapOpportunityRow),+ opportunities: (data || []).map((row) => mapOpportunityRow(row, competitors)),total: count || 0,@@ -655,8 +673,11 @@ router.post('/bulk/send-webhook', async (req, res) => {let sent = 0;let failed = 0;+ // What the workflow receives reads the way the page shows it.+ const competitors = await competitorNames(brandId);- for (const opportunity of opportunities) {+ for (const stored of opportunities) {+ const opportunity = cleanStoredOpportunity(stored, competitors);try {let prompt = null;if (opportunity.prompt_id) {@@ -755,7 +776,7 @@ router.patch('/:id/status', async (req, res) => {if (error) throw new Error(error.message);if (!data) return res.status(404).json({ error: 'Opportunity not found' });- return res.json(mapOpportunityRow(data));+ return res.json(mapOpportunityRow(data, await competitorNames(data.brand_id)));} catch (error) {req.log.error({ err: error }, 'update opportunity status error');return res.status(error.status || 500).json({@@ -773,7 +794,9 @@ router.post('/:id/send-webhook', async (req, res) => {try {const { id } = req.params;- const opportunity = await assertOpportunityAccess(id, req.user.id);+ // What the workflow receives reads the way the page shows it.+ const stored = await assertOpportunityAccess(id, req.user.id);+ const opportunity = cleanStoredOpportunity(stored, await competitorNames(stored.brand_id));const { data: webhookConfig } = await supabaseAdmin.from('webhook_configs')@@ -1067,6 +1090,11 @@ Searches AI engines ran while answering them: ${(sourceData.queries?.top || []).`: '';+ // The brief is written from the text as users read it, not leaked indexes.+ const readable = cleanStoredOpportunity(+ opportunity,+ (competitors || []).map((c) => c.name),+ );const userPrompt = `Brand: ${brand?.name || 'Unknown'}Industry: ${brand?.industry || 'Not specified'}Description: ${brand?.description || 'N/A'}@@ -1074,8 +1102,8 @@ Domain: ${(domains || []).map((d) => d.domain).join(', ') || 'N/A'}Competitors: ${(competitors || []).map((c) => `${c.name} (${c.domain})`).join(', ') || 'None'}Opportunity:-- Title: ${opportunity.title}-- Description: ${opportunity.description}+- Title: ${readable.title}+- Description: ${readable.description}- Type: ${opportunity.type}- Impact: ${opportunity.impact}- Score: ${opportunity.opportunity_score}@@ -1258,7 +1286,10 @@ router.post('/:id/action', async (req, res) => {try {const opp = await assertOpportunityAccess(req.params.id, req.user.id);const assetKey = typeof req.body?.assetKey === 'string' ? req.body.assetKey : null;- const result = await sendToActionCenter(opp, { assetKey, userId: req.user.id });+ // The action's title and assets read the way the page shows them; the+ // opportunity's own stored text is left as it is.+ const readable = cleanStoredOpportunity(opp, await competitorNames(opp.brand_id));+ const result = await sendToActionCenter(opp, { assetKey, userId: req.user.id, readable });return res.status(result.created ? 201 : 200).json(result);} catch (error) {req.log.error({ err: error }, 'send opportunity to action center error');@@ -1358,7 +1389,7 @@ router.get('/:id', async (req, res) => {const opp = await assertOpportunityAccess(id, req.user.id);- return res.json(mapOpportunityRow(opp));+ return res.json(mapOpportunityRow(opp, await competitorNames(opp.brand_id)));} catch (error) {req.log.error({ err: error }, 'get opportunity error');return res.status(error.status || 500).json({