@topy-ai/maggie 0.7.32 → 0.7.34

package/bundled-templates/astro-blog/starter/src/lib/providers/email.ts

@@ -0,0 +1,45 @@
+export type EmailProviderId = "resend" | "webhook" | "disabled";
+export type EmailMessage = { from: string; to: string[]; subject: string; html: string; text?: string; replyTo?: string };
+export type EmailResult = { provider: EmailProviderId; status: "sent" | "queued" | "failed"; providerId?: string; reason?: string; error?: string };
+
+export interface EmailProvider {
+  readonly id: EmailProviderId;
+  send(message: EmailMessage): Promise<EmailResult>;
+  health(): { configured: boolean; capabilities: string[]; reason?: string };
+}
+
+const configuredProvider = (): EmailProviderId => {
+  const value = String(import.meta.env.EMAIL_PROVIDER || "resend").toLowerCase();
+  return value === "webhook" || value === "disabled" || value === "resend" ? value : "disabled";
+};
+
+const resend: EmailProvider = {
+  id: "resend",
+  health: () => ({ configured: Boolean(import.meta.env.RESEND_API_KEY && import.meta.env.EMAIL_FROM), capabilities: ["send", "html", "reply-to"], reason: !import.meta.env.RESEND_API_KEY ? "RESEND_API_KEY is not configured" : !import.meta.env.EMAIL_FROM ? "EMAIL_FROM is not configured" : undefined }),
+  async send(message) {
+    const key = import.meta.env.RESEND_API_KEY;
+    if (!key || !import.meta.env.EMAIL_FROM) return { provider: "resend", status: "queued", reason: "RESEND_API_KEY and EMAIL_FROM are required" };
+    try {
+      const response = await fetch("https://api.resend.com/emails", { method: "POST", headers: { authorization: `Bearer ${key}`, "content-type": "application/json" }, body: JSON.stringify({ from: message.from, to: message.to, subject: message.subject, html: message.html, text: message.text, reply_to: message.replyTo }), signal: AbortSignal.timeout(15000) });
+      const payload = await response.json().catch(() => ({})) as { id?: string; message?: string; name?: string };
+      if (!response.ok) return { provider: "resend", status: "failed", error: payload.message || payload.name || `Resend returned ${response.status}` };
+      return { provider: "resend", status: "sent", providerId: payload.id };
+    } catch (error) { return { provider: "resend", status: "failed", error: error instanceof Error ? error.message : "Resend request failed" }; }
+  },
+};
+
+const webhook: EmailProvider = {
+  id: "webhook",
+  health: () => ({ configured: Boolean(import.meta.env.EMAIL_WEBHOOK_URL || import.meta.env.REPORT_EMAIL_WEBHOOK_URL), capabilities: ["send", "html"], reason: import.meta.env.EMAIL_WEBHOOK_URL || import.meta.env.REPORT_EMAIL_WEBHOOK_URL ? undefined : "EMAIL_WEBHOOK_URL is not configured" }),
+  async send(message) {
+    const url = import.meta.env.EMAIL_WEBHOOK_URL || import.meta.env.REPORT_EMAIL_WEBHOOK_URL;
+    if (!url) return { provider: "webhook", status: "queued", reason: "EMAIL_WEBHOOK_URL is not configured" };
+    try { const response = await fetch(url, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(message), signal: AbortSignal.timeout(15000) }); if (!response.ok) return { provider: "webhook", status: "failed", error: `email webhook returned ${response.status}` }; return { provider: "webhook", status: "sent" }; } catch (error) { return { provider: "webhook", status: "failed", error: error instanceof Error ? error.message : "email webhook request failed" }; }
+  },
+};
+
+const disabled: EmailProvider = { id: "disabled", health: () => ({ configured: true, capabilities: [], reason: "email provider is disabled or unknown" }), async send() { return { provider: "disabled", status: "queued", reason: "email provider is disabled or unknown" }; } };
+const providers: Record<string, EmailProvider> = { resend, webhook, disabled };
+export const registerEmailProvider = (provider: EmailProvider): void => { providers[provider.id] = provider; };
+export const getEmailProvider = (provider = configuredProvider()): EmailProvider => providers[provider] || providers.disabled;
+export const emailProviderStatus = () => { const provider = getEmailProvider(); return { provider: provider.id, ...provider.health() }; };

package/bundled-templates/astro-blog/starter/src/lib/providers/media-storage.ts

@@ -0,0 +1,37 @@
+import { createHash } from "node:crypto";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+export type MediaStorageProviderId = "cloudinary" | "local";
+export type MediaUpload = { data: Buffer; filename: string; mimeType?: string; folder?: string; publicId?: string };
+export type MediaUploadResult = { provider: MediaStorageProviderId; key: string; url: string; bytes: number; mimeType?: string; localPath?: string };
+export interface MediaStorageProvider { readonly id: MediaStorageProviderId; upload(input: MediaUpload): Promise<MediaUploadResult>; health(): { configured: boolean; capabilities: string[]; reason?: string } }
+
+const providerName = (): string => String(import.meta.env.MEDIA_STORAGE_PROVIDER || "cloudinary").toLowerCase();
+const sha1 = (value: string) => createHash("sha1").update(value).digest("hex");
+
+const cloudinary: MediaStorageProvider = {
+  id: "cloudinary",
+  health: () => ({ configured: Boolean(import.meta.env.CLOUDINARY_CLOUD_NAME && import.meta.env.CLOUDINARY_API_KEY && import.meta.env.CLOUDINARY_API_SECRET), capabilities: ["upload", "cdn", "transform", "remote-fetch"], reason: !import.meta.env.CLOUDINARY_CLOUD_NAME ? "CLOUDINARY_CLOUD_NAME is not configured" : !import.meta.env.CLOUDINARY_API_KEY || !import.meta.env.CLOUDINARY_API_SECRET ? "Cloudinary API credentials are not configured" : undefined }),
+  async upload(input) {
+    const cloud = import.meta.env.CLOUDINARY_CLOUD_NAME; const key = import.meta.env.CLOUDINARY_API_KEY; const secret = import.meta.env.CLOUDINARY_API_SECRET;
+    if (!cloud || !key || !secret) throw new Error("Cloudinary requires CLOUDINARY_CLOUD_NAME, CLOUDINARY_API_KEY and CLOUDINARY_API_SECRET");
+    const timestamp = Math.floor(Date.now() / 1000); const folder = input.folder || import.meta.env.CLOUDINARY_UPLOAD_FOLDER || "maggie"; const publicId = input.publicId || input.filename.replace(/[^a-zA-Z0-9/_-]/g, "-").replace(/\.[^.]+$/, ""); const params = { folder, overwrite: "true", public_id: publicId, timestamp: String(timestamp) }; const signature = sha1(Object.entries(params).sort(([a], [b]) => a.localeCompare(b)).map(([name, value]) => `${name}=${value}`).join("&") + secret);
+    const type = input.mimeType?.startsWith("video/") ? "video" : input.mimeType?.startsWith("audio/") || input.mimeType === "application/pdf" ? "raw" : "image"; const form = new FormData(); form.set("file", `data:${input.mimeType || "application/octet-stream"};base64,${input.data.toString("base64")}`); for (const [name, value] of Object.entries({ ...params, api_key: key, signature })) form.set(name, value);
+    const response = await fetch(`https://api.cloudinary.com/v1_1/${encodeURIComponent(cloud)}/${type}/upload`, { method: "POST", body: form, signal: AbortSignal.timeout(60000) }); const payload = await response.json().catch(() => ({})) as { secure_url?: string; public_id?: string; error?: { message?: string } }; if (!response.ok || !payload.secure_url) throw new Error(payload.error?.message || `Cloudinary returned ${response.status}`); return { provider: "cloudinary", key: payload.public_id || publicId, url: payload.secure_url, bytes: input.data.byteLength, mimeType: input.mimeType };
+  },
+};
+
+const local: MediaStorageProvider = { id: "local", health: () => ({ configured: true, capabilities: ["upload"] }), async upload(input) { const outputDir = import.meta.env.MEDIA_OUTPUT_DIR || "public/media/uploads"; await mkdir(outputDir, { recursive: true }); const safe = input.filename.replace(/[^a-zA-Z0-9._-]/g, "-"); const localPath = join(outputDir, safe); await writeFile(localPath, input.data); return { provider: "local", key: safe, url: `/${outputDir.replace(/^public\//, "").replace(/\\/g, "/")}/${safe}`, localPath, bytes: input.data.byteLength, mimeType: input.mimeType }; } };
+const providers: Record<string, MediaStorageProvider> = { cloudinary, local };
+export const registerMediaStorageProvider = (provider: MediaStorageProvider): void => { providers[provider.id] = provider; };
+export const getMediaStorageProvider = (provider = providerName()): MediaStorageProvider => {
+  const selected = providers[provider];
+  if (!selected) throw new Error(`Unknown media storage provider: ${provider}`);
+  return selected;
+};
+export const mediaProviderStatus = () => {
+  const name = providerName();
+  const provider = providers[name];
+  return provider ? { provider: provider.id, ...provider.health() } : { provider: name, configured: false, capabilities: [], reason: `Unknown media storage provider: ${name}` };
+};

package/bundled-templates/astro-blog/starter/src/lib/report-delivery.ts

@@ -0,0 +1,26 @@
+import { db, now } from "./db";
+import { getEmailProvider } from "./providers/email";
+
+export type ReportDeliveryResult = { id: string; status: "sent" | "queued" | "failed"; reason?: string; error?: string };
+
+export async function deliverReport(delivery: any): Promise<ReportDeliveryResult> {
+  const report = db().prepare("SELECT * FROM blog_reports WHERE run_type=? ORDER BY completed_at DESC LIMIT 1").get(delivery.report_type) as any;
+  if (!report) return { id: delivery.id, status: "failed", error: "report not found" };
+  const summary = JSON.parse(report.summary_json || "{}"); const findings = JSON.parse(report.findings_json || "[]");
+  const recipient = String(delivery.recipient).split(",").map((value: string) => value.trim()).filter(Boolean);
+  const provider = getEmailProvider();
+  const result = await provider.send({ from: import.meta.env.EMAIL_FROM || "Maggie <onboarding@resend.dev>", to: recipient, subject: `Maggie ${delivery.report_type} report`, html: `<h1>${delivery.report_type} report</h1><p>${JSON.stringify(summary)}</p><p>${findings.length} finding(s) recorded.</p>`, text: `${delivery.report_type} report\n${JSON.stringify(summary)}\n${findings.length} finding(s) recorded.`, replyTo: import.meta.env.EMAIL_REPLY_TO || undefined });
+  if (result.status === "sent") db().prepare("UPDATE report_deliveries SET last_sent_at=?,last_error=NULL,status='active' WHERE id=?").run(now(), delivery.id);
+  else if (result.status === "failed") db().prepare("UPDATE report_deliveries SET status='failed',last_error=? WHERE id=?").run(result.error || "email delivery failed", delivery.id);
+  return { id: delivery.id, status: result.status, reason: result.reason, error: result.error };
+}
+
+export function isDeliveryDue(delivery: any, timestamp = Date.now()): boolean {
+  if (!delivery.schedule) return false;
+  const schedule = String(delivery.schedule);
+  const last = delivery.last_sent_at ? Date.parse(delivery.last_sent_at) : Date.parse(delivery.created_at || "");
+  if (/^\d{4}-\d{2}-\d{2}T/.test(schedule)) return Date.parse(schedule) <= timestamp && !delivery.last_sent_at;
+  if (!Number.isFinite(last)) return true;
+  const interval = schedule === "weekly" ? 7 * 86400000 : schedule === "monthly" ? 30 * 86400000 : 86400000;
+  return timestamp - last >= interval;
+}

package/bundled-templates/astro-blog/starter/src/lib/report-pdf.ts

@@ -0,0 +1,49 @@
+type ReportFinding = { severity?: string; code?: string; message?: string };
+
+const pdfEscape = (value: string) => value.replace(/\\/g, "\\\\").replace(/\(/g, "\\(").replace(/\)/g, "\\)");
+
+const wrap = (value: string, width = 92) => {
+  const words = value.replace(/\s+/g, " ").trim().split(" ");
+  const lines: string[] = [];
+  let line = "";
+  for (const word of words) {
+    if ((line + (line ? " " : "") + word).length > width && line) {
+      lines.push(line); line = word;
+    } else line += (line ? " " : "") + word;
+  }
+  if (line) lines.push(line);
+  return lines.length ? lines : [""];
+};
+
+export const createReportPdf = (title: string, summary: unknown, findings: ReportFinding[]) => {
+  const lines = [title, `Summary: ${JSON.stringify(summary)}`];
+  findings.forEach((finding, index) => lines.push(`${index + 1}. [${finding.severity || "info"}] ${finding.code || "finding"}: ${finding.message || ""}`));
+  const pages: string[][] = [];
+  let page: string[] = [];
+  for (const line of lines.flatMap((item) => wrap(item))) {
+    if (page.length >= 48) { pages.push(page); page = []; }
+    page.push(line);
+  }
+  if (page.length || !pages.length) pages.push(page);
+
+  const objects: string[] = [];
+  const add = (value: string) => { objects.push(value); return objects.length; };
+  const font = add("<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>");
+  const pageIds: number[] = [];
+  const contentIds: number[] = [];
+  pages.forEach((pageLines) => {
+    const stream = ["BT", "/F1 10 Tf", "50 760 Td", ...pageLines.flatMap((line, index) => [`(${pdfEscape(line.slice(0, 150))}) Tj`, ...(index < pageLines.length - 1 ? ["0 -14 Td"] : [])]), "ET"].join("\n");
+    contentIds.push(add(`<< /Length ${stream.length} >>\nstream\n${stream}\nendstream`));
+    pageIds.push(add(""));
+  });
+  const pagesId = add("");
+  pageIds.forEach((pageId, index) => { objects[pageId - 1] = `<< /Type /Page /Parent ${pagesId} 0 R /MediaBox [0 0 612 792] /Resources << /Font << /F1 ${font} 0 R >> >> /Contents ${contentIds[index]} 0 R >>`; });
+  objects[pagesId - 1] = `<< /Type /Pages /Kids [${pageIds.map((id) => `${id} 0 R`).join(" ")}] /Count ${pageIds.length} >>`;
+  const catalog = add(`<< /Type /Catalog /Pages ${pagesId} 0 R >>`);
+  let output = "%PDF-1.4\n%\xE2\xE3\xCF\xD3\n";
+  const offsets = [0];
+  objects.forEach((object, index) => { offsets.push(output.length); output += `${index + 1} 0 obj\n${object}\nendobj\n`; });
+  const xref = output.length;
+  output += `xref\n0 ${objects.length + 1}\n0000000000 65535 f \n${offsets.slice(1).map((offset) => `${String(offset).padStart(10, "0")} 00000 n `).join("\n")}\ntrailer\n<< /Size ${objects.length + 1} /Root ${catalog} 0 R >>\nstartxref\n${xref}\n%%EOF`;
+  return new TextEncoder().encode(output);
+};

package/bundled-templates/astro-blog/starter/src/lib/repository.ts

@@ -0,0 +1,72 @@
+import { posts as demoPosts, topics as demoTopics } from "../data/demo";
+import type { Author, BlogPost, Topic } from "./types";
+import { db } from "./db";
+
+const useSqlite = () => import.meta.env.BLOG_DATA_SOURCE === "sqlite";
+const useDemo = () => import.meta.env.DEV && import.meta.env.BLOG_DATA_SOURCE !== "sqlite";
+const publicPredicate = "p.status = 'published' AND p.published_at IS NOT NULL";
+
+function fromRow(row: any): BlogPost {
+  const topicRows = db().prepare("SELECT t.slug FROM topics t JOIN post_topics pt ON pt.topic_id=t.id WHERE pt.post_id=? AND t.status!='archived'").all(row.id) as { slug: string }[];
+  const faq = db().prepare("SELECT f.id, f.question, f.answer_markdown AS answer FROM faq_items f JOIN post_faqs pf ON pf.faq_id=f.id WHERE pf.post_id=? AND f.status='published' ORDER BY f.sort_order").all(row.id) as any[];
+  const cta = db().prepare("SELECT c.label, c.url FROM ctas c JOIN post_ctas pc ON pc.cta_id=c.id WHERE pc.post_id=? AND c.status='active' LIMIT 1").get(row.id) as any;
+  const alternates = db().prepare("SELECT language,url FROM hreflang_links WHERE post_id=?").all(row.id) as Array<{ language: string; url: string }>;
+  return { id: row.id, source: row.source, sourceId: row.source_id || undefined, slug: row.slug, title: row.title, excerpt: row.excerpt, contentHtml: row.content_html || "", canonicalUrl: row.canonical_override || row.canonical_url, coverImageUrl: row.cover_image_url || undefined, coverImageAlt: row.cover_image_alt, author: { id: row.author_id, slug: row.author_slug, name: row.author_name, jobTitle: row.job_title || undefined, organisation: row.organisation || undefined, bio: row.bio || undefined, profileUrl: row.profile_url || undefined, credentials: JSON.parse(row.credentials_json || "[]") }, topicSlugs: topicRows.map((item) => item.slug), faq, ctaLabel: cta?.label, ctaUrl: cta?.url, language: row.language, status: row.status, publishedAt: row.published_at || undefined, updatedAt: row.updated_at || undefined, seoTitle: row.seo_title || undefined, metaDescription: row.meta_description || undefined, focusKeyword: row.focus_keyword || undefined, canonicalOverride: row.canonical_override || undefined, robotsIndex: row.robots_index || "index", robotsFollow: row.robots_follow || "follow", schemaType: row.schema_type || "Article", scheduledAt: row.scheduled_at || undefined, alternates };
+}
+function sqlitePosts(where = "", params: unknown[] = []): BlogPost[] {
+  const rows = db().prepare(`SELECT p.*, a.slug author_slug, a.name author_name, a.job_title, a.organisation, a.bio, a.profile_url, a.credentials_json FROM posts p JOIN authors a ON a.id=p.author_id WHERE ${publicPredicate} ${where} ORDER BY p.published_at DESC`).all(...params) as any[];
+  return rows.map(fromRow);
+}
+export function publishedPosts(): BlogPost[] {
+  return useSqlite() ? sqlitePosts() : useDemo() ? demoPosts.filter((post) => post.status === "published" && Boolean(post.publishedAt)) : [];
+}
+
+export function postBySlug(slug: string): BlogPost | undefined {
+  return useSqlite() ? sqlitePosts("AND p.slug=?", [slug])[0] : publishedPosts().find((post) => post.slug === slug);
+}
+
+export function topicBySlug(slug: string): Topic | undefined {
+  if (useSqlite()) {
+    const row = db().prepare("SELECT * FROM topics WHERE slug=? AND status!='archived'").get(slug) as any;
+    if (!row) return undefined;
+    const faq = db().prepare("SELECT f.id, f.question, f.answer_markdown AS answer FROM faq_items f JOIN topic_faqs tf ON tf.faq_id=f.id WHERE tf.topic_id=? AND f.status='published' ORDER BY f.sort_order").all(row.id) as any[];
+    return { id: row.id, slug: row.slug, title: row.title, description: row.description, status: row.status, faq };
+  }
+  return useDemo() ? demoTopics.find((topic) => topic.slug === slug && topic.status !== "archived") : undefined;
+}
+
+export function allTopics(): Topic[] {
+  if (!useSqlite()) return useDemo() ? demoTopics : [];
+  return (db().prepare("SELECT * FROM topics WHERE status!='archived' ORDER BY title").all() as any[]).map((row) => ({ id: row.id, slug: row.slug, title: row.title, description: row.description, status: row.status, faq: [] }));
+}
+
+export function authorBySlug(slug: string): Author | undefined {
+  if (useSqlite()) {
+    const row = db().prepare("SELECT * FROM authors WHERE slug=?").get(slug) as any;
+    return row ? { id: row.id, slug: row.slug, name: row.name, jobTitle: row.job_title || undefined, organisation: row.organisation || undefined, bio: row.bio || undefined, profileUrl: row.profile_url || undefined, credentials: JSON.parse(row.credentials_json || "[]") } : undefined;
+  }
+  return useDemo() ? publishedPosts().find((post) => post.author.slug === slug)?.author : undefined;
+}
+
+export function postsForAuthor(slug: string): BlogPost[] {
+  return useSqlite() ? sqlitePosts("AND a.slug=?", [slug]) : publishedPosts().filter((post) => post.author.slug === slug);
+}
+
+export function relatedPosts(post: BlogPost, limit = 3): BlogPost[] {
+  return publishedPosts().filter((candidate) => candidate.id !== post.id && candidate.topicSlugs.some((slug) => post.topicSlugs.includes(slug))).slice(0, limit);
+}
+
+export function ctaForPlacement(placement: string): { label: string; url: string } | undefined {
+  if (!useSqlite()) return useDemo() ? { label: "Get started", url: "/get-started" } : undefined;
+  return db().prepare("SELECT label,url FROM ctas WHERE placement=? AND status='active' ORDER BY updated_at DESC LIMIT 1").get(placement) as { label: string; url: string } | undefined;
+}
+
+export function postsForTopic(topicSlug: string): BlogPost[] {
+  return useSqlite() ? sqlitePosts("AND EXISTS (SELECT 1 FROM post_topics x JOIN topics y ON y.id=x.topic_id WHERE x.post_id=p.id AND y.slug=? )", [topicSlug]) : useDemo() ? publishedPosts().filter((post) => post.topicSlugs.includes(topicSlug)) : [];
+}
+
+export function siteUrl(path: string): string {
+  const baseUrl = import.meta.env.PUBLIC_SITE_URL;
+  if (!baseUrl) throw new Error("PUBLIC_SITE_URL is required; copy .env.example and configure the public site URL");
+  return new URL(path, baseUrl).toString();
+}

package/bundled-templates/astro-blog/starter/src/lib/seo-audit.ts

@@ -0,0 +1,72 @@
+import { db, id, now } from "./db";
+
+type Severity = "info" | "warning" | "error";
+
+export function runTechnicalAudit(): { runId: string; findings: any[] } {
+  const timestamp = now();
+  const runId = id("report");
+  const findings: any[] = [];
+  const add = (postId: string | null, category: string, severity: Severity, code: string, message: string, details: unknown = {}) => {
+    findings.push({ id: id("finding"), run_id: runId, post_id: postId, category, severity, code, message, details_json: JSON.stringify(details), created_at: timestamp });
+    if (code === "content-decay" && postId) {
+      const dueAt = new Date(Date.now() + 14 * 86400000).toISOString();
+      db().prepare("INSERT INTO fact_review_reminders (id,post_id,due_at,reason,status,created_at,updated_at) VALUES (?,?,?,?,?,?,?) ON CONFLICT(post_id,status) DO UPDATE SET due_at=excluded.due_at,reason=excluded.reason,updated_at=excluded.updated_at").run(id("fact_review"), postId, dueAt, "content decay audit", "pending", timestamp, timestamp);
+    }
+  };
+  const posts = db().prepare("SELECT id,title,excerpt,content_html,canonical_url,canonical_override,seo_title,meta_description,author_id,status,published_at,updated_at,language,cover_image_alt FROM posts").all() as any[];
+  const duplicateTitles = new Map<string, any[]>();
+  const entities = db().prepare("SELECT entity_type,entity_key,name,same_as_json,schema_json FROM entity_profiles").all() as any[];
+  const organization = entities.find((entity) => entity.entity_type === "organization");
+  for (const post of posts) {
+    const html = String(post.content_html || "");
+    const text = html.replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim();
+    const titleKey = String(post.title || "").trim().toLowerCase();
+    duplicateTitles.set(titleKey, [...(duplicateTitles.get(titleKey) || []), post]);
+    if (!post.author_id) add(post.id, "content-quality", "error", "missing-author", "Post has no author.");
+    if (post.status === "published" && !post.published_at) add(post.id, "technical", "error", "published-without-date", "Published post is missing published_at.");
+    if (post.published_at && post.updated_at && Date.parse(post.updated_at) < Date.parse(post.published_at)) add(post.id, "technical", "warning", "modified-date-integrity", "updated_at predates published_at.");
+    if ((post.excerpt || "").length < 50) add(post.id, "content-quality", "warning", "thin-description", "Excerpt/meta description is short.");
+    if (!post.seo_title) add(post.id, "technical", "warning", "missing-seo-title", "SEO title is not explicitly set.");
+    if (!post.meta_description) add(post.id, "technical", "warning", "missing-meta-description", "Meta description is not explicitly set.");
+    if (post.canonical_override && post.canonical_override !== post.canonical_url) add(post.id, "technical", "warning", "canonical-conflict", "Canonical override differs from stored canonical URL.");
+    try { if (!new URL(post.canonical_override || post.canonical_url)) add(post.id, "technical", "error", "invalid-canonical", "Canonical URL is invalid."); } catch { add(post.id, "technical", "error", "invalid-canonical", "Canonical URL is invalid."); }
+    if (text.length < 300) add(post.id, "content-quality", "warning", "thin-content", "Post body is shorter than 300 characters.");
+    const firstParagraph = html.match(/<p[^>]*>([\s\S]*?)<\/p>/i)?.[1]?.replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim() || "";
+    if (post.status === "published" && (firstParagraph.length < 40 || firstParagraph.length > 500)) add(post.id, "geo", "info", "answer-first", "Opening paragraph is not a concise answer-first summary.", { length: firstParagraph.length });
+    const h1 = (html.match(/<h1\b/gi) || []).length;
+    if (h1 !== 1) add(post.id, "technical", "warning", "heading-hierarchy", "Rendered content should contain exactly one h1.", { h1 });
+    const images = [...html.matchAll(/<img\b[^>]*>/gi)].map((match) => match[0]);
+    for (const image of images) {
+      if (!/\balt=["'][^"']*["']/i.test(image) && !post.cover_image_alt) add(post.id, "content-quality", "warning", "missing-image-alt", "Image markup is missing descriptive alt text.");
+      if (!/\b(?:width|height)=["'][^"']+["']/i.test(image)) add(post.id, "technical", "warning", "image-dimensions", "Image markup is missing width or height attributes.");
+      const source = image.match(/\bsrc=["']([^"']+)["']/i)?.[1] || "";
+      if (/\.(?:png|jpe?g)(?:[?#].*)?$/i.test(source)) add(post.id, "performance", "info", "image-not-optimized", "Raster image is not using a WebP/AVIF derivative.", { source });
+    }
+    if (!/<a\b[^>]+href=["']https?:\/\//i.test(html)) add(post.id, "content-quality", "info", "citation-completeness", "No external source link was detected for citation review.");
+    if (post.updated_at && Date.parse(post.updated_at) < Date.now() - 365 * 86400000) add(post.id, "content-quality", "warning", "content-decay", "Content has not been updated in over one year.");
+    const faqItems = db().prepare("SELECT question,answer_markdown,status FROM faq_items f JOIN post_faqs pf ON pf.faq_id=f.id WHERE pf.post_id=?").all(post.id) as any[];
+    for (const faq of faqItems) if (faq.status === "published" && (String(faq.question).length < 10 || String(faq.answer_markdown).length < 80)) add(post.id, "geo", "warning", "faq-quality", "Published FAQ question or answer is too short for a useful answer.");
+    const links = db().prepare("SELECT language,url FROM hreflang_links WHERE post_id=?").all(post.id) as any[];
+    const languages = new Set<string>();
+    for (const link of links) { if (languages.has(link.language)) add(post.id, "technical", "warning", "hreflang-duplicate", "Post has duplicate hreflang language entries.", link); languages.add(link.language); try { new URL(link.url); } catch { add(post.id, "technical", "error", "hreflang-invalid-url", "hreflang URL is invalid.", link); } }
+    if (links.length && !languages.has(post.language)) add(post.id, "technical", "warning", "hreflang-missing-self", "hreflang set does not include the post's own language.", { language: post.language });
+    if (organization && post.author_id && !organization.name) add(post.id, "geo", "warning", "entity-incomplete", "Organization entity is missing a stable name.");
+  }
+  for (const [title, items] of duplicateTitles) if (title && items.length > 1) for (const post of items) add(post.id, "content-quality", "warning", "duplicate-title", "Multiple posts share the same normalized title.", { title, count: items.length });
+  const duplicateBodies = new Map<string, any[]>();
+  for (const post of posts) { const bodyKey = String(post.content_html || "").replace(/\s+/g, " ").trim(); if (bodyKey.length >= 100) duplicateBodies.set(bodyKey, [...(duplicateBodies.get(bodyKey) || []), post]); }
+  for (const [bodyKey, items] of duplicateBodies) if (items.length > 1) for (const post of items) add(post.id, "content-quality", "warning", "duplicate-content", "Multiple posts share the same normalized body content.", { count: items.length, fingerprint: bodyKey.slice(0, 80) });
+  const orphaned = db().prepare("SELECT p.id FROM posts p LEFT JOIN post_topics pt ON pt.post_id=p.id WHERE p.status='published' GROUP BY p.id HAVING COUNT(pt.topic_id)=0").all() as Array<{ id: string }>;
+  for (const post of orphaned) add(post.id, "technical", "warning", "orphan-page", "Published post has no topic relationship.");
+  const redirects = db().prepare("SELECT source_path,target_path FROM redirects").all() as Array<{ source_path: string; target_path: string }>;
+  const redirectMap = new Map(redirects.map((row) => [row.source_path, row.target_path]));
+  for (const row of redirects) if (redirectMap.has(row.target_path)) add(null, "technical", "warning", "redirect-chain", "Redirect target is itself redirected.", row);
+  const topicCounts = db().prepare("SELECT t.id,COUNT(pt.post_id) AS count FROM topics t LEFT JOIN post_topics pt ON pt.topic_id=t.id LEFT JOIN posts p ON p.id=pt.post_id AND p.status='published' GROUP BY t.id").all() as Array<{ id: string; count: number }>;
+  const topicRows = db().prepare("SELECT id,title,minimum_published_posts FROM topics WHERE status!='archived'").all() as Array<{ id: string; title: string; minimum_published_posts: number }>;
+  for (const topic of topicCounts) { if (topic.count > 12) add(null, "technical", "info", "pagination-required", "Topic exceeds the page size and requires a paginated index.", topic); const definition = topicRows.find((item) => item.id === topic.id); if (definition && topic.count < definition.minimum_published_posts) add(null, "content-quality", "warning", "thin-topic", "Topic has fewer published posts than its configured minimum.", { topicId: topic.id, title: definition.title, count: topic.count, minimum: definition.minimum_published_posts }); }
+  const summary = { totalPosts: posts.length, findingCount: findings.length, errors: findings.filter((item) => item.severity === "error").length, warnings: findings.filter((item) => item.severity === "warning").length };
+  db().prepare("INSERT INTO blog_reports (id,run_type,status,summary_json,findings_json,started_at,completed_at) VALUES (?,?,?,?,?,?,?)").run(runId, "technical-seo", "completed", JSON.stringify(summary), JSON.stringify(findings), timestamp, timestamp);
+  const insert = db().prepare("INSERT INTO seo_findings (id,run_id,post_id,category,severity,code,message,details_json,created_at) VALUES (?,?,?,?,?,?,?,?,?)");
+  db().transaction(() => findings.forEach((item) => insert.run(item.id, item.run_id, item.post_id, item.category, item.severity, item.code, item.message, item.details_json, item.created_at)))();
+  return { runId, findings };
+}

package/bundled-templates/astro-blog/starter/src/lib/seo-insights.ts

@@ -0,0 +1,14 @@
+import { db } from "./db";
+
+export function seoInsights() {
+  const database = db(); const posts = database.prepare("SELECT id,slug,title,excerpt,content_html,status FROM posts WHERE status='published'").all() as any[]; const bySlug = new Map(posts.map((post) => [post.slug, post])); const internalLinks = posts.flatMap((post) => { const links = [...String(post.content_html || "").matchAll(/href=["'](?:https?:\/\/[^"']+)?\/blog\/([^"'#?]+)/gi)].map((match) => match[1]); return links.filter((slug) => bySlug.has(slug) && slug !== post.slug).map((slug) => ({ from: post.slug, to: slug })); });
+  const linked = new Set(internalLinks.map((link) => link.to)); const suggestions = posts.filter((post) => !linked.has(post.slug)).map((post) => ({ postId: post.id, slug: post.slug, reason: "no incoming internal link detected" })); const topics = database.prepare("SELECT t.id,t.slug,t.title,COUNT(pt.post_id) post_count FROM topics t LEFT JOIN post_topics pt ON pt.topic_id=t.id LEFT JOIN posts p ON p.id=pt.post_id AND p.status='published' GROUP BY t.id ORDER BY post_count").all(); const faq = database.prepare("SELECT COUNT(*) total, SUM(CASE WHEN LENGTH(answer_markdown)>=80 THEN 1 ELSE 0 END) quality_answers FROM faq_items WHERE status='published'").get(); const entities = database.prepare("SELECT entity_type,entity_key,name,same_as_json FROM entity_profiles ORDER BY entity_type,name").all(); const crawlerPolicy = database.prepare("SELECT value_json FROM blog_settings WHERE key='aiCrawlerPolicy'").get() as { value_json: string } | undefined;
+  const answerFirst = posts.map((post) => { const firstParagraph = String(post.content_html || "").match(/<p[^>]*>([\s\S]*?)<\/p>/i)?.[1]?.replace(/<[^>]+>/g, "").trim() || ""; return { slug: post.slug, answerFirst: firstParagraph.length >= 40 && firstParagraph.length <= 500 }; });
+  const refreshRecommendations = posts.map((post) => {
+    const text = String(post.content_html || "").replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim();
+    const reasons = [post.excerpt.length < 50 ? "short-description" : null, text.length < 300 ? "thin-content" : null, !post.content_html?.match(/<a\b[^>]+href=["']https?:\/\//i) ? "missing-citations" : null].filter(Boolean);
+    return reasons.length ? { postId: post.id, slug: post.slug, reasons, recommendedAction: "review-and-refresh" } : null;
+  }).filter(Boolean);
+  const relations = database.prepare("SELECT subject_key,predicate,object_key FROM entity_relations ORDER BY subject_key,predicate,object_key").all();
+  return { internalLinks: { total: internalLinks.length, links: internalLinks, orphanCandidates: suggestions }, topicCoverage: topics, faqQuality: faq, answerFirst, refreshRecommendations, entities, entityGraph: relations, aiCrawlerPolicy: crawlerPolicy ? JSON.parse(crawlerPolicy.value_json) : { allow: true } };
+}

package/bundled-templates/astro-blog/starter/src/lib/seo.ts

@@ -0,0 +1,33 @@
+import type { Author, BlogPost, FaqItem, Topic } from "./types";
+
+export function postJsonLd(post: BlogPost) {
+  return {
+    "@context": "https://schema.org",
+    "@type": post.schemaType || "Article",
+    headline: post.title,
+    description: post.excerpt,
+    url: post.canonicalUrl,
+    mainEntityOfPage: { "@type": "WebPage", "@id": post.canonicalUrl },
+    datePublished: post.publishedAt,
+    ...(post.updatedAt ? { dateModified: post.updatedAt } : {}),
+    author: { "@type": "Person", name: post.author.name, ...(post.author.profileUrl ? { url: post.author.profileUrl } : {}) },
+    ...(post.author.organisation ? { publisher: { "@type": "Organization", name: post.author.organisation } } : {}),
+    ...(post.coverImageUrl ? { image: [post.coverImageUrl] } : {}),
+  };
+}
+
+export function topicJsonLd(topic: Topic, url: string) {
+  return { "@context": "https://schema.org", "@type": "CollectionPage", name: topic.title, description: topic.description, url };
+}
+
+export function faqJsonLd(items: FaqItem[]) {
+  return { "@context": "https://schema.org", "@type": "FAQPage", mainEntity: items.map((item) => ({ "@type": "Question", name: item.question, acceptedAnswer: { "@type": "Answer", text: item.answer } })) };
+}
+
+export function authorJsonLd(author: Author, url: string) {
+  return { "@context": "https://schema.org", "@type": "Person", name: author.name, url, ...(author.jobTitle ? { jobTitle: author.jobTitle } : {}), ...(author.organisation ? { worksFor: { "@type": "Organization", name: author.organisation } } : {}), ...(author.profileUrl ? { sameAs: [author.profileUrl] } : {}), ...(author.credentials?.length ? { knowsAbout: author.credentials } : {}) };
+}
+
+export function organizationJsonLd(entity: { name: string; url: string; logo?: string; sameAs?: string[] }) {
+  return { "@context": "https://schema.org", "@type": "Organization", name: entity.name, url: entity.url, ...(entity.logo ? { logo: entity.logo } : {}), ...(entity.sameAs?.length ? { sameAs: entity.sameAs } : {}) };
+}

package/bundled-templates/astro-blog/starter/src/lib/types.ts

@@ -0,0 +1,58 @@
+export type PublishStatus = "draft" | "review" | "approved" | "scheduled" | "published" | "archived";
+
+export type Author = {
+  id: string;
+  slug: string;
+  name: string;
+  jobTitle?: string;
+  organisation?: string;
+  bio?: string;
+  profileUrl?: string;
+  credentials?: string[];
+};
+
+export type FaqItem = {
+  id: string;
+  question: string;
+  answer: string;
+};
+
+export type Topic = {
+  id: string;
+  slug: string;
+  title: string;
+  description: string;
+  status: "draft" | "published" | "archived";
+  faq: FaqItem[];
+};
+
+export type BlogPost = {
+  id: string;
+  source: "local" | "api-pull" | "cms" | "manual";
+  sourceId?: string;
+  slug: string;
+  title: string;
+  excerpt: string;
+  contentHtml: string;
+  canonicalUrl: string;
+  coverImageUrl?: string;
+  coverImageAlt?: string;
+  author: Author;
+  topicSlugs: string[];
+  faq: FaqItem[];
+  ctaLabel?: string;
+  ctaUrl?: string;
+  language: string;
+  status: PublishStatus;
+  publishedAt?: string;
+  updatedAt?: string;
+  seoTitle?: string;
+  metaDescription?: string;
+  focusKeyword?: string;
+  canonicalOverride?: string;
+  robotsIndex?: "index" | "noindex";
+  robotsFollow?: "follow" | "nofollow";
+  schemaType?: string;
+  scheduledAt?: string;
+  alternates?: Array<{ language: string; url: string }>;
+};