Open source alternative to Semrush and Ahrefs
TypeScript backlink-analysisgoogle-search-console-mcpkeyword-researchmcpseoseo-agentseo-auditseo-automationseo-skillsseo-toolssite-audit
import { runBatch } from "@/db/runBatch";
import { ProjectContextRepository } from "@/server/features/project-context/repositories/ProjectContextRepository";
import { resolveContextUpdates } from "@/server/features/project-context/services/contextUpdateOps";
import { ReportTemplateRepository } from "@/server/features/reports/repositories/ReportTemplateRepository";
import {
CUSTOM_SECTION_KEY_PREFIX,
PROJECT_CONTEXT_SECTION_KEYS,
PROJECT_CONTEXT_SECTION_LABELS,
type ContextAuthor,
type KeyPageRole,
type ProjectContextSectionKey,
type ProjectContextUpdate,
} from "@/types/schemas/projectContext";
// Project memory: the qualitative context SAM, MCP clients and the settings UI
// share. Reading, writing and rendering it all go through here; the per-op
// caps and normalization live in contextUpdateOps.
const RESEARCH_LOG_RETENTION_DAYS = 90;
const RESEARCH_LOG_LIMIT = 20;
type ProjectContext = {
sections: {
key: ProjectContextSectionKey;
content: string;
updatedAt: string;
updatedBy: ContextAuthor;
}[];
/** Typed sections with nothing stored, so agents know what to fill. */
missingSections: ProjectContextSectionKey[];
customSections: {
slug: string;
title: string | null;
content: string;
updatedAt: string;
updatedBy: ContextAuthor;
}[];
competitors: {
id: string;
domain: string;
name: string | null;
notes: string | null;
updatedAt: string;
updatedBy: ContextAuthor;
}[];
keyPages: {
id: string;
url: string;
role: KeyPageRole;
topic: string | null;
notes: string | null;
updatedAt: string;
updatedBy: ContextAuthor;
}[];
researchLog: {
id: string;
entryDate: string;
summary: string;
createdBy: ContextAuthor;
}[];
/**
* The project's report templates. They belong to the reports feature, but
* this digest is the one block every skill already reads, so it is where
* agents discover them.
*/
reportTemplates: { name: string; description: string }[];
};
export async function getProjectContext(
projectId: string,
): Promise<ProjectContext> {
const [sectionRows, competitors, keyPages, researchLog, reportTemplates] =
await Promise.all([
ProjectContextRepository.listSections(projectId),
ProjectContextRepository.listCompetitors(projectId),
ProjectContextRepository.listKeyPages(projectId),
ProjectContextRepository.listResearchLog(projectId, RESEARCH_LOG_LIMIT),
ReportTemplateRepository.listTemplates(projectId),
]);
const stored = new Map(sectionRows.map((row) => [row.key, row]));
// Typed sections keep their declared order, which is also the order the
// digest and the settings UI render them in.
const sections = PROJECT_CONTEXT_SECTION_KEYS.flatMap((key) => {
const row = stored.get(key);
return row
? [
{
key,
content: row.content,
updatedAt: row.updatedAt,
updatedBy: row.updatedBy,
},
]
: [];
});
return {
sections,
missingSections: PROJECT_CONTEXT_SECTION_KEYS.filter(
(key) => !stored.has(key),
),
customSections: sectionRows
.filter((row) => row.key.startsWith(CUSTOM_SECTION_KEY_PREFIX))
.map((row) => ({
slug: row.key.slice(CUSTOM_SECTION_KEY_PREFIX.length),
title: row.title,
content: row.content,
updatedAt: row.updatedAt,
updatedBy: row.updatedBy,
})),
competitors,
keyPages,
researchLog: researchLog.map((row) => ({
id: row.id,
entryDate: row.entryDate,
summary: row.summary,
createdBy: row.createdBy,
})),
reportTemplates: reportTemplates.map((template) => ({
name: template.name,
description: template.description,
})),
};
}
function dayStamp(offsetDays = 0): string {
const date = new Date(Date.now() + offsetDays * 24 * 60 * 60 * 1000);
return date.toISOString().slice(0, 10);
}
/**
* Applies the patch ops in order, then returns the resulting context. The batch
* is resolved and capped up front, so a call that trips a limit writes nothing
* at all rather than leaving the project half-updated.
*/
export async function applyContextUpdates(
projectId: string,
updates: ProjectContextUpdate[],
updatedBy: ContextAuthor,
): Promise<ProjectContext> {
const [sectionRows, competitorRows, keyPageRows] = await Promise.all([
ProjectContextRepository.listSections(projectId),
ProjectContextRepository.listCompetitors(projectId),
ProjectContextRepository.listKeyPages(projectId),
]);
const resolved = resolveContextUpdates(updates, {
customKeys: new Set(
sectionRows
.map((row) => row.key)
.filter((key) => key.startsWith(CUSTOM_SECTION_KEY_PREFIX)),
),
domains: new Set(competitorRows.map((row) => row.domain)),
urls: new Set(keyPageRows.map((row) => row.url)),
});
// One atomic batch (D1 batch / PG transaction): a mid-batch failure rolls
// everything back, which is what lets callers retry a whole batch safely.
await runBatch((tx) =>
resolved.flatMap((op): Promise<unknown>[] => {
switch (op.kind) {
case "upsertSection":
return [
ProjectContextRepository.upsertSection(tx, {
projectId,
key: op.key,
title: op.title,
content: op.content,
updatedBy,
}),
];
case "deleteSection":
return [
ProjectContextRepository.deleteSection(tx, projectId, op.key),
];
case "upsertCompetitors":
return ProjectContextRepository.upsertCompetitors(
tx,
projectId,
op.rows,
updatedBy,
);
case "deleteCompetitors":
return ProjectContextRepository.deleteCompetitors(
tx,
projectId,
op.domains,
);
case "upsertKeyPages":
return ProjectContextRepository.upsertKeyPages(
tx,
projectId,
op.rows,
updatedBy,
);
case "deleteKeyPages":
return ProjectContextRepository.deleteKeyPages(
tx,
projectId,
op.urls,
);
case "deleteResearchLog":
return ProjectContextRepository.deleteResearchLogEntries(
tx,
projectId,
op.ids,
);
case "appendResearchLog":
return [
ProjectContextRepository.appendResearchLogEntry(tx, {
projectId,
entryDate: dayStamp(),
summary: op.summary,
createdBy: updatedBy,
}),
// The log only has to answer "was this bought recently?", so it
// is pruned on write instead of growing forever.
ProjectContextRepository.pruneResearchLogBefore(
tx,
projectId,
dayStamp(-RESEARCH_LOG_RETENTION_DAYS),
),
];
}
}),
);
return getProjectContext(projectId);
}
function pushSection(lines: string[], heading: string, body: string[]) {
lines.push(
`## ${heading}`,
"",
...(body.length > 0 ? body : ["_Empty_"]),
"",
);
}
/**
* The one markdown digest of a project's memory, rendered for the MCP tool's
* `text` payload and for SAM's read-only context block. Typed sections are
* always listed — an empty one shows up as missing, which is the signal agents
* use to offer setup.
*
* The report-templates section is omitted entirely when there are none, so a
* project with no templates reads exactly as it did before.
*/
export function renderProjectContextMarkdown(context: ProjectContext): string {
const lines = ["# Project context", ""];
for (const key of PROJECT_CONTEXT_SECTION_KEYS) {
const section = context.sections.find((entry) => entry.key === key);
pushSection(
lines,
PROJECT_CONTEXT_SECTION_LABELS[key],
section ? [section.content] : [],
);
}
for (const custom of context.customSections) {
pushSection(lines, custom.title ?? custom.slug, [custom.content]);
}
pushSection(
lines,
"Competitors",
context.competitors.map((competitor) =>
[
`- ${competitor.domain}`,
competitor.name ? ` — ${competitor.name}` : "",
competitor.notes ? ` (${competitor.notes})` : "",
].join(""),
),
);
pushSection(
lines,
"Key pages",
context.keyPages.map((page) =>
[
`- ${page.url} — ${page.role}`,
page.topic ? ` · ${page.topic}` : "",
page.notes ? ` (${page.notes})` : "",
].join(""),
),
);
// The log is capped at the newest entries, so the heading counts what is
// actually here — an agent deciding whether research is stale must not read
// a truncated list as the whole 90-day window.
pushSection(
lines,
context.researchLog.length === 0
? "Research log"
: `Research log (${context.researchLog.length} ${
context.researchLog.length === 1 ? "entry" : "entries"
})`,
[
// Competitors render by domain and key pages by url — the keys their
// remove ops take. A log entry's only address is its id, so it is the
// key that has to appear here for removeResearchLog to be usable.
...context.researchLog.map(
(entry) => `- ${entry.entryDate}: ${entry.summary} [id: ${entry.id}]`,
),
...(context.researchLog.length >= RESEARCH_LOG_LIMIT
? [
"",
`_Older entries within the ${RESEARCH_LOG_RETENTION_DAYS}-day window are omitted._`,
]
: []),
],
);
if (context.reportTemplates.length > 0) {
pushSection(
lines,
"Report templates",
context.reportTemplates.map(
(template) => `- ${template.name}: ${template.description}`,
),
);
}
lines.push(
context.missingSections.length > 0
? `Missing sections: ${context.missingSections.join(", ")}`
: "Missing sections: none",
);
return lines.join("\n");
}
export const ProjectContextService = {
getProjectContext,
applyContextUpdates,
renderProjectContextMarkdown,
} as const;