@softure-ai/blog 0.0.0-stage → 0.1.6

package/src/db/publish-run.ts

@@ -0,0 +1,224 @@
+// A publish run (FIRE_TRACKER `src/db/blog-publish.ts`): the heart of `softure-blog publish`.
+//
+// All or nothing. Every file is read and checked before the first write, and the writes go
+// through one transaction: one bad file or one taken slug, and no row changes. A release publishes
+// the whole folder, and half a folder in production is worse than no change.
+//
+// A dry run unless `commit`: the transaction is rolled back, but the result shows exactly what a
+// commit would do (the rows before and after, read from the database).
+import type { BlogArticleInput, BlogArticleKind, BlogArticleStatus, BlogPublishAction } from "../contract.js";
+import { parseArticleFile, type ParseArticleFileOptions } from "../content/article-file.js";
+import type { Queryable } from "@softure-ai/db";
+import { eq } from "drizzle-orm";
+import { findTermFormConflicts, toGlossary } from "../render/glossary.js";
+import { listArticles, publishArticle, type BlogContext } from "./articles.js";
+import { articles } from "./schema.js";
+
+export interface ArticleFile {
+  /** The file name (or path); it must read `<slug>.md`. */
+  readonly name: string;
+  readonly text: string;
+}
+
+/**
+ * The quality gate (BL-6 fills it): the problems of a file that is about to go public. It runs only
+ * for files whose status is `published` and not under `withdraw`: a withdrawal must always pass, and a
+ * draft reaches no reader.
+ */
+export type PublishGate = (file: ArticleFile, article: BlogArticleInput) => readonly string[];
+
+export interface RunBlogPublishOptions extends ParseArticleFileOptions {
+  /** Write the changes; without it the run is a dry run. */
+  readonly commit?: boolean;
+  /** Publish the files as `withdrawn`, whatever their status (taking a text down at once). */
+  readonly withdraw?: boolean;
+  readonly gate?: PublishGate;
+}
+
+/** A problem that stops the run; `subject` is a file name, an article id or a cluster. */
+export interface PublishProblem {
+  readonly subject: string;
+  readonly message: string;
+}
+
+/** What the run did (or would do) to one article; BL-5 derives the changed addresses from it. */
+export interface PublishedChange {
+  readonly id: string;
+  readonly kind: BlogArticleKind;
+  readonly action: BlogPublishAction;
+  readonly statusBefore: BlogArticleStatus | null;
+  readonly statusAfter: BlogArticleStatus;
+  readonly slugBefore: string | null;
+  readonly slug: string;
+  /** The slug that entered the slug history in this run. */
+  readonly previousSlug: string | null;
+}
+
+export type BlogPublishRun =
+  | { readonly status: "refused"; readonly problems: readonly PublishProblem[]; readonly warnings: readonly PublishProblem[] }
+  | { readonly status: "done"; readonly committed: boolean; readonly changes: readonly PublishedChange[]; readonly warnings: readonly PublishProblem[] };
+
+/** SQLSTATE of an exclusion constraint violation: the deferred one-pillar rule at commit. */
+const EXCLUSION_VIOLATION = "23P01";
+/** SQLSTATE of a unique violation; on `articles_slug_key` it is a lost slug race. */
+const UNIQUE_VIOLATION = "23505";
+const SLUG_CONSTRAINT = "articles_slug_key";
+
+class DryRunRollback extends Error {}
+
+class PublishRefused extends Error {
+  constructor(readonly problems: readonly PublishProblem[]) {
+    super(problems.map((problem) => problem.message).join("; "));
+  }
+}
+
+export async function runBlogPublish(ctx: BlogContext, files: readonly ArticleFile[], options: RunBlogPublishOptions = {}): Promise<BlogPublishRun> {
+  const problems: PublishProblem[] = [];
+  const warnings: PublishProblem[] = [];
+  const inputs: BlogArticleInput[] = [];
+
+  for (const file of files) {
+    const parsed = parseArticleFile(file.text, file.name, options);
+    if (!parsed.ok) {
+      problems.push(...parsed.errors.map((message) => ({ subject: file.name, message })));
+      continue;
+    }
+    const isGoingPublic = options.withdraw !== true && parsed.article.status === "published";
+    const gateProblems = isGoingPublic && options.gate !== undefined ? options.gate(file, parsed.article) : [];
+    if (gateProblems.length > 0) {
+      problems.push(...gateProblems.map((message) => ({ subject: file.name, message: `quality gate: ${message}` })));
+      continue;
+    }
+    if (options.withdraw === true && parsed.article.status !== "withdrawn") {
+      warnings.push({
+        subject: file.name,
+        message: `the file says status: ${parsed.article.status}; set it to withdrawn, or the next full publish brings the text back`,
+      });
+    }
+    inputs.push(options.withdraw === true ? { ...parsed.article, status: "withdrawn" } : parsed.article);
+  }
+
+  problems.push(...findDuplicateIds(inputs), ...findPillarProblems(inputs));
+  if (problems.length > 0) return { status: "refused", problems, warnings };
+
+  const changes: PublishedChange[] = [];
+  try {
+    await ctx.db.transaction(async (tx) => {
+      for (const input of inputs) {
+        const result = await publishArticleOrRefuse({ ...ctx, db: tx }, input);
+        if (!result.ok) {
+          const reason = result.error === "blog.slug_taken" ? "is the slug of" : "redirects to";
+          throw new PublishRefused([{ subject: input.id, message: `slug ${input.slug} ${reason} article ${result.otherArticleId} (${result.error})` }]);
+        }
+        changes.push({
+          id: input.id,
+          kind: input.kind,
+          action: result.action,
+          statusBefore: result.before?.status ?? null,
+          statusAfter: result.after.status,
+          slugBefore: result.before?.slug ?? null,
+          slug: result.after.slug,
+          previousSlug: result.previousSlug,
+        });
+      }
+      const glossary = await checkGlossaryForms({ ...ctx, db: tx }, inputs);
+      if (glossary.problems.length > 0) throw new PublishRefused(glossary.problems);
+      warnings.push(...glossary.warnings);
+      if (options.commit !== true) throw new DryRunRollback();
+    });
+  } catch (error) {
+    if (error instanceof DryRunRollback) return { status: "done", committed: false, changes, warnings };
+    if (error instanceof PublishRefused) return { status: "refused", problems: error.problems, warnings };
+    if (findDriverError(error)?.code === EXCLUSION_VIOLATION) {
+      return {
+        status: "refused",
+        problems: [{ subject: "pillar", message: "a cluster would have two pillars: one is in the database and not in this run; mark only one text of a cluster pillar: true" }],
+        warnings,
+      };
+    }
+    throw error;
+  }
+  return { status: "done", committed: true, changes, warnings };
+}
+
+function findDuplicateIds(inputs: readonly BlogArticleInput[]): PublishProblem[] {
+  const seen = new Set<string>();
+  const duplicates = new Set<string>();
+  for (const { id } of inputs) {
+    if (seen.has(id)) duplicates.add(id);
+    seen.add(id);
+  }
+  return [...duplicates].map((id) => ({ subject: id, message: "two files have this id" }));
+}
+
+/**
+ * One pillar per cluster among the run's texts that are not withdrawn, checked before any write
+ * for a clear message. The database's deferred exclusion constraint also covers texts outside the
+ * run (a run of one file).
+ */
+function findPillarProblems(inputs: readonly BlogArticleInput[]): PublishProblem[] {
+  const pillars = new Map<string, string[]>();
+  for (const input of inputs) {
+    if (input.isPillar && input.cluster !== null && input.status !== "withdrawn") {
+      pillars.set(input.cluster, [...(pillars.get(input.cluster) ?? []), input.id]);
+    }
+  }
+  return [...pillars]
+    .filter(([, ids]) => ids.length > 1)
+    .map(([cluster, ids]) => ({ subject: cluster, message: `two pillars in one cluster: ${ids.join(", ")}` }));
+}
+
+/**
+ * One term per glossary form, over the published terms as this run leaves them (read inside its
+ * transaction, after its writes), so a run of one file sees the terms stored before it. A conflict
+ * with a term of this run refuses the run; one only between stored terms is not this run's doing and
+ * is a warning. The renderer links such a form to one of the terms either way.
+ */
+async function checkGlossaryForms(ctx: BlogContext, inputs: readonly BlogArticleInput[]): Promise<{ problems: PublishProblem[]; warnings: PublishProblem[] }> {
+  const runTerms = new Set(inputs.filter((input) => input.kind === "term").map((input) => input.slug));
+  const problems: PublishProblem[] = [];
+  const warnings: PublishProblem[] = [];
+  for (const conflict of findTermFormConflicts(toGlossary(await listArticles(ctx, { kind: "term" })))) {
+    const problem = { subject: "glossary", message: `form "${conflict.form}" is claimed by terms ${conflict.slugs.join(", ")}; a form belongs to one term, so remove it from all but one` };
+    if (conflict.slugs.some((slug) => runTerms.has(slug))) problems.push(problem);
+    else warnings.push(problem);
+  }
+  return { problems, warnings };
+}
+
+/**
+ * `publishArticle`, with a lost slug race turned into a refusal. Another run can commit the same
+ * slug between this run's free-slug read and its write; the unique index then makes the write wait
+ * for that run and fail with 23505. The savepoint is rolled back, so the transaction still reads
+ * (at read committed, the winner's row is visible now) and names the article that took the slug.
+ */
+async function publishArticleOrRefuse(ctx: BlogContext, input: BlogArticleInput): ReturnType<typeof publishArticle> {
+  try {
+    return await publishArticle(ctx, input);
+  } catch (error) {
+    const driverError = findDriverError(error);
+    if (driverError?.code !== UNIQUE_VIOLATION || driverError.constraint !== SLUG_CONSTRAINT) throw error;
+    const winner = await findSlugOwner(ctx.db, input.slug);
+    const owner = winner === undefined ? "another article published at the same time" : `article ${winner}`;
+    throw new PublishRefused([{ subject: input.id, message: `slug ${input.slug} is the slug of ${owner} (blog.slug_taken)` }]);
+  }
+}
+
+async function findSlugOwner(db: Queryable, slug: string): Promise<string | undefined> {
+  const [row] = await db.select({ id: articles.id }).from(articles).where(eq(articles.slug, slug));
+  return row?.id;
+}
+
+interface DriverError {
+  readonly code: string;
+  readonly constraint: string | undefined;
+}
+
+/** The driver error (SQLSTATE and constraint) behind an error; drizzle wraps it as the `cause`. */
+function findDriverError(error: unknown): DriverError | undefined {
+  for (let current: unknown = error, depth = 0; current instanceof Error && depth < 3; current = current.cause, depth += 1) {
+    const { code, constraint } = current as { code?: unknown; constraint?: unknown };
+    if (typeof code === "string") return { code, constraint: typeof constraint === "string" ? constraint : undefined };
+  }
+  return undefined;
+}

package/src/db/schema.ts

@@ -0,0 +1,36 @@
+// Drizzle view of the module's tables (migrations/0001_create_articles.sql). The migration is the
+// source of truth; this file only types the queries.
+import { boolean, date, jsonb, pgSchema, text, timestamp } from "drizzle-orm/pg-core";
+import type { BlogArticleKind, BlogArticleStatus, BlogFaqEntry, BlogFields, BlogSource } from "../contract.js";
+
+export const blogSchema = pgSchema("blog");
+
+export const articles = blogSchema.table("articles", {
+  id: text("id").primaryKey(),
+  slug: text("slug").notNull().unique("articles_slug_key"),
+  kind: text("kind").$type<BlogArticleKind>().notNull(),
+  cluster: text("cluster"),
+  isPillar: boolean("is_pillar").notNull().default(false),
+  title: text("title").notNull(),
+  description: text("description").notNull(),
+  summary: text("summary"),
+  bodyMarkdown: text("body_markdown").notNull(),
+  status: text("status").$type<BlogArticleStatus>().notNull(),
+  currentAsOf: date("current_as_of", { mode: "string" }).notNull(),
+  publishedAt: timestamp("published_at", { withTimezone: true }),
+  updatedAt: timestamp("updated_at", { withTimezone: true }),
+  sources: jsonb("sources").$type<readonly BlogSource[]>().notNull().default([]),
+  faq: jsonb("faq").$type<readonly BlogFaqEntry[]>().notNull().default([]),
+  termForms: jsonb("term_forms").$type<readonly string[]>().notNull().default([]),
+  fields: jsonb("fields").$type<BlogFields>().notNull().default({}),
+  contentSha256: text("content_sha256").notNull(),
+  createdAt: timestamp("created_at", { withTimezone: true }).notNull(),
+});
+
+export const slugHistory = blogSchema.table("slug_history", {
+  oldSlug: text("old_slug").primaryKey(),
+  articleId: text("article_id")
+    .notNull()
+    .references(() => articles.id, { onDelete: "cascade" }),
+  changedAt: timestamp("changed_at", { withTimezone: true }).notNull(),
+});

package/src/discovery/dates.ts

@@ -0,0 +1,27 @@
+// The dates search engines and feed readers get: the last real change of a text, never a build or
+// request date. `updated_at` moves only when the content hash of a published text changes (BL-2), so
+// it is a `lastmod` a search engine can trust.
+import type { BlogArticle } from "../contract.js";
+
+export type DatedText = Pick<BlogArticle, "slug" | "publishedAt" | "updatedAt">;
+
+/** When a published text last changed: its update, else its publication. */
+export function getTextLastModified(text: DatedText): Date {
+  return text.updatedAt ?? requirePublishedAt(text);
+}
+
+/** The newest change among the texts; `null` for none. */
+export function getLatestModified(texts: readonly DatedText[]): Date | null {
+  return texts.reduce<Date | null>((latest, text) => {
+    const moment = getTextLastModified(text);
+    return latest === null || moment > latest ? moment : latest;
+  }, null);
+}
+
+/** A published text always has `published_at` (the store sets it); a missing one is a bug, not a date to invent. */
+export function requirePublishedAt(text: Pick<BlogArticle, "slug" | "publishedAt">): Date {
+  if (text.publishedAt === null) {
+    throw new Error(`requirePublishedAt: text ${text.slug} has no published_at; discovery takes published texts only`);
+  }
+  return text.publishedAt;
+}

package/src/discovery/index.ts

@@ -0,0 +1,18 @@
+// Discovery without React and without Next: sitemap entries, the RSS feed, "read next", the IndexNow
+// paths and submit, and the cache refresh request after a publish. The Next pieces
+// (`../next/discovery.ts`, `../next/refresh.ts`) render and serve what it returns.
+export { getLatestModified, getTextLastModified, type DatedText } from "./dates.js";
+export { getIndexNowPaths, type IndexNowChange } from "./indexnow.js";
+export {
+  BLOG_REFRESH_RATE_LIMIT_BUCKET,
+  BLOG_REFRESH_SECRET_ENV,
+  MIN_REFRESH_SECRET_LENGTH,
+  requestBlogRefresh,
+  type BlogRefreshFailure,
+  type BlogRefreshOutcome,
+  type RequestBlogRefreshOptions,
+} from "./refresh.js";
+export { getRelatedArticles, PILLAR_RELATED_LIMIT, RELATED_LIMIT, type RelatedCandidate } from "./related.js";
+export { buildBlogRss, escapeXml, type BuildBlogRssInput, type FeedChannel, type FeedText } from "./rss.js";
+export { getBlogSitemapEntries, type BlogSitemapEntry, type BlogSitemapInput, type SitemapText } from "./sitemap.js";
+export { submitBlogChanges, type BlogIndexNowOutcome, type BlogIndexNowSubmit, type SubmitBlogChangesOptions } from "./submit.js";

package/src/discovery/indexnow.ts

@@ -0,0 +1,25 @@
+// The addresses a publish run changed, for IndexNow (FIRE_TRACKER `src/lib/indexnow.ts`).
+import type { PublishedChange } from "../db/publish-run.js";
+import { getTextPath, type BlogRoutes } from "../pages/paths.js";
+
+export type IndexNowChange = Pick<PublishedChange, "kind" | "action" | "statusBefore" | "statusAfter" | "slug" | "previousSlug">;
+
+/**
+ * The paths whose answer changed: a text public before or after (a withdrawn one answers 410 now, and
+ * search engines should learn it), its old slug when it was public (now a 301), and the hub of its
+ * kind (the listing for an article, the glossary for a term). A draft that stayed a draft and an
+ * unchanged text add nothing. Texts first, then hubs, without repeats.
+ */
+export function getIndexNowPaths(changes: readonly IndexNowChange[], routes: BlogRoutes): string[] {
+  const texts = new Set<string>();
+  const hubs = new Set<string>();
+  for (const change of changes) {
+    const wasPublic = change.statusBefore === "published";
+    const isPublic = change.statusAfter === "published";
+    if (change.action === "unchanged" || (!wasPublic && !isPublic)) continue;
+    texts.add(getTextPath(routes, change.kind, change.slug));
+    if (change.previousSlug !== null && wasPublic) texts.add(getTextPath(routes, change.kind, change.previousSlug));
+    hubs.add(change.kind === "term" ? routes.glossary : routes.index);
+  }
+  return [...texts, ...hubs];
+}

package/src/discovery/refresh.ts

@@ -0,0 +1,79 @@
+// The cache refresh after a publish: the command runs outside the app and cannot reach Next's cache,
+// so it asks the running app, through the route `refreshBlogCache` (`@softure-ai/blog/next`), to
+// expire the blog's cached reads. Both sides read one secret from the environment.
+import type { SoftureConfig } from "@softure-ai/core";
+import { getBlogOptions, getBlogRefreshPath } from "../server/options.js";
+import type { IndexNowChange } from "./indexnow.js";
+
+/** The variable both the route and the command read the shared secret from. */
+export const BLOG_REFRESH_SECRET_ENV = "BLOG_REFRESH_SECRET";
+/** A shorter secret is a setup bug: the route refuses to run with it and the command does not send it. */
+export const MIN_REFRESH_SECRET_LENGTH = 32;
+/** The security bucket the route counts in; `BLOG_RATE_LIMIT_BUCKETS` holds its default. */
+export const BLOG_REFRESH_RATE_LIMIT_BUCKET = "blog-refresh";
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+export type BlogRefreshFailure = "blog.refresh_invalid_secret" | "blog.refresh_unreachable" | "blog.refresh_rejected";
+
+export type BlogRefreshOutcome =
+  /** No secret in the environment: the app shows the change after `revalidateSeconds`. */
+  | { readonly kind: "not_configured"; readonly revalidateSeconds: number }
+  /** The run changed no text. */
+  | { readonly kind: "skipped" }
+  /** No commit: the address a commit would call, and no request. */
+  | { readonly kind: "dry_run"; readonly url: string }
+  | { readonly kind: "refreshed"; readonly url: string }
+  | { readonly kind: "failed"; readonly code: BlogRefreshFailure; readonly reason: string; readonly revalidateSeconds: number };
+
+export interface RequestBlogRefreshOptions {
+  /** Sends the request only when `true`, i.e. after a committed run; otherwise a dry run. */
+  readonly commit?: boolean;
+  /** The app's origin to call, when it differs from `appOrigin` (a private name in a container). */
+  readonly appUrl?: string;
+  /** Default: `process.env`. */
+  readonly env?: Readonly<Record<string, string | undefined>>;
+  readonly fetchImpl?: typeof fetch;
+  readonly timeoutMs?: number;
+}
+
+/**
+ * Asks the running app to refresh the blog's cache after a publish run. Call it before the IndexNow
+ * submit, so a crawler that answers the ping finds the new text. Never throws for an expected
+ * failure: the refresh is an extra after a publish and must not undo it.
+ */
+export async function requestBlogRefresh(config: SoftureConfig, changes: readonly IndexNowChange[], options: RequestBlogRefreshOptions = {}): Promise<BlogRefreshOutcome> {
+  const { revalidateSeconds } = getBlogOptions(config);
+  if (changes.every((change) => change.action === "unchanged")) return { kind: "skipped" };
+  const secret = ((options.env ?? process.env)[BLOG_REFRESH_SECRET_ENV] ?? "").trim();
+  if (secret === "") return { kind: "not_configured", revalidateSeconds };
+
+  // Also on a dry run: the editor learns of a short secret before the commit that needs it.
+  if (secret.length < MIN_REFRESH_SECRET_LENGTH) {
+    return { kind: "failed", code: "blog.refresh_invalid_secret", reason: `${BLOG_REFRESH_SECRET_ENV} must be at least ${String(MIN_REFRESH_SECRET_LENGTH)} characters`, revalidateSeconds };
+  }
+  const url = new URL(getBlogRefreshPath(config), options.appUrl ?? config.appOrigin).toString();
+  if (options.commit !== true) return { kind: "dry_run", url };
+
+  try {
+    const response = await (options.fetchImpl ?? fetch)(url, {
+      method: "POST",
+      headers: { authorization: `Bearer ${secret}` },
+      // Never followed: a redirect would carry the request, or drop the secret, somewhere else.
+      redirect: "manual",
+      signal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+    });
+    if (response.status === 204 || response.status === 200) return { kind: "refreshed", url };
+    return { kind: "failed", code: "blog.refresh_rejected", reason: `${url} answered ${String(response.status)}${describeStatus(response.status)}`, revalidateSeconds };
+  } catch (error) {
+    return { kind: "failed", code: "blog.refresh_unreachable", reason: `${url} could not be reached: ${error instanceof Error ? error.message : String(error)}`, revalidateSeconds };
+  }
+}
+
+function describeStatus(status: number): string {
+  if (status === 401) return ` (the app has another ${BLOG_REFRESH_SECRET_ENV})`;
+  if (status === 404) return " (mount refreshBlogCache at that path)";
+  if (status === 429) return " (too many refreshes from this address)";
+  if (status >= 300 && status < 400) return " (a redirect; pass the final origin with --app-url)";
+  return "";
+}

package/src/discovery/related.ts

@@ -0,0 +1,35 @@
+// "Read next" under an article (FIRE_TRACKER `src/lib/blog-discovery.ts`), chosen without manual lists.
+import type { BlogArticle } from "../contract.js";
+
+export type RelatedCandidate = Pick<BlogArticle, "id" | "cluster" | "isPillar">;
+
+/** How many texts "read next" shows under an article. */
+export const RELATED_LIMIT = 4;
+
+/** At most this many satellites under a pillar: its whole cluster, but a longer list is a listing. */
+export const PILLAR_RELATED_LIMIT = 6;
+
+/** Pillars first, then the input order (newest first). */
+function pillarsFirst<T extends RelatedCandidate>(texts: readonly T[]): T[] {
+  return [...texts.filter((text) => text.isPillar), ...texts.filter((text) => !text.isPillar)];
+}
+
+/**
+ * - **A satellite:** the pillar of its cluster, the rest of the cluster, then pillars and texts of
+ *   other clusters; {@link RELATED_LIMIT} in total.
+ * - **A pillar:** every satellite of its cluster (up to {@link PILLAR_RELATED_LIMIT}), filled up to
+ *   {@link RELATED_LIMIT} from other clusters.
+ * - **No cluster:** pillars, then the newest.
+ *
+ * `published` comes newest first (the store's order); an article never recommends itself.
+ */
+export function getRelatedArticles<T extends RelatedCandidate>(article: RelatedCandidate, published: readonly T[]): T[] {
+  const others = published.filter((candidate) => candidate.id !== article.id);
+  const sameCluster = article.cluster === null ? [] : others.filter((candidate) => candidate.cluster === article.cluster);
+  const rest = pillarsFirst(others.filter((candidate) => !sameCluster.includes(candidate)));
+  if (article.isPillar) {
+    const satellites = sameCluster.slice(0, PILLAR_RELATED_LIMIT);
+    return [...satellites, ...rest].slice(0, Math.max(satellites.length, RELATED_LIMIT));
+  }
+  return [...pillarsFirst(sameCluster), ...rest].slice(0, RELATED_LIMIT);
+}

package/src/discovery/rss.ts

@@ -0,0 +1,77 @@
+// The blog's RSS 2.0 feed (FIRE_TRACKER `src/lib/blog-discovery.ts`). An item is the title, the
+// address, the description and the publication date, **without the body**: the reader goes to the
+// page, where the sources and the disclaimer are; a text torn from them would be advice without context.
+import type { SiteUrls } from "@softure-ai/core";
+import type { BlogArticle } from "../contract.js";
+import { getArticlePath, getTermPath, type BlogRoutes } from "../pages/paths.js";
+import { getLatestModified, requirePublishedAt } from "./dates.js";
+
+export type FeedText = Pick<BlogArticle, "id" | "slug" | "kind" | "title" | "description" | "cluster" | "publishedAt" | "updatedAt">;
+
+export interface FeedChannel {
+  readonly title: string;
+  readonly description: string;
+  /** The feed's language, e.g. `en` or `pl`. */
+  readonly language: string;
+}
+
+export interface BuildBlogRssInput {
+  readonly articles: readonly FeedText[];
+  readonly terms: readonly FeedText[];
+  /** The site's origin and canonical rule (`getSiteUrls(config)`): items and the channel link a page's canonical URL. */
+  readonly urls: SiteUrls;
+  readonly routes: BlogRoutes;
+  /** The feed's own path (`routes.rss`), for `atom:link rel="self"`. */
+  readonly feedPath: string;
+  readonly channel: FeedChannel;
+  /** An item's `<category>`: e.g. the cluster label of an article, the glossary title of a term; `null` for none. */
+  readonly getCategory: (text: FeedText) => string | null;
+}
+
+const XML_ESCAPES: Readonly<Record<string, string>> = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&apos;" };
+
+export function escapeXml(text: string): string {
+  return text.replace(/[&<>"']/g, (character) => XML_ESCAPES[character] ?? character);
+}
+
+/**
+ * The feed of the published articles and terms together, newest publication first. `guid` is the
+ * text's id with `isPermaLink="false"`: it survives a slug change, so a reader never shows an old text
+ * again as new. `lastBuildDate` is the newest change, absent for an empty blog.
+ */
+export function buildBlogRss(input: BuildBlogRssInput): string {
+  const lastModified = getLatestModified([...input.articles, ...input.terms]);
+  const items = [
+    ...input.articles.map((text) => ({ text, path: getArticlePath(input.routes, text.slug) })),
+    ...input.terms.map((text) => ({ text, path: getTermPath(input.routes, text.slug) })),
+  ]
+    .sort((a, b) => requirePublishedAt(b.text).getTime() - requirePublishedAt(a.text).getTime())
+    .map(({ text, path }) => {
+      const category = input.getCategory(text);
+      return [
+        "    <item>",
+        `      <title>${escapeXml(text.title)}</title>`,
+        `      <link>${escapeXml(input.urls.getCanonicalUrl(path))}</link>`,
+        `      <guid isPermaLink="false">${escapeXml(text.id)}</guid>`,
+        `      <description>${escapeXml(text.description)}</description>`,
+        `      <pubDate>${requirePublishedAt(text).toUTCString()}</pubDate>`,
+        ...(category === null ? [] : [`      <category>${escapeXml(category)}</category>`]),
+        "    </item>",
+      ].join("\n");
+    });
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">',
+    "  <channel>",
+    `    <title>${escapeXml(input.channel.title)}</title>`,
+    `    <link>${escapeXml(input.urls.getCanonicalUrl(input.routes.index))}</link>`,
+    `    <description>${escapeXml(input.channel.description)}</description>`,
+    `    <language>${escapeXml(input.channel.language)}</language>`,
+    `    <atom:link href="${escapeXml(`${input.urls.origin}${input.feedPath}`)}" rel="self" type="application/rss+xml"/>`,
+    ...(lastModified === null ? [] : [`    <lastBuildDate>${lastModified.toUTCString()}</lastBuildDate>`]),
+    ...items,
+    "  </channel>",
+    "</rss>",
+    "",
+  ].join("\n");
+}

package/src/discovery/sitemap.ts

@@ -0,0 +1,59 @@
+// The blog's entries for `@softure-ai/seo`'s sitemap (FIRE_TRACKER `src/lib/blog-discovery.ts`). Paths
+// only: seo makes them absolute on its site origin with its canonical rule.
+import type { BlogArticle } from "../contract.js";
+import { getTermPath, getArticlePath, type BlogRoutes } from "../pages/paths.js";
+import { getLatestModified, getTextLastModified } from "./dates.js";
+
+/** The shape of seo's `SitemapEntry`, written out so the blog needs no seo import. */
+export interface BlogSitemapEntry {
+  readonly path: string;
+  readonly lastModified?: Date;
+  readonly priority: number;
+}
+
+export type SitemapText = Pick<BlogArticle, "slug" | "isPillar" | "publishedAt" | "updatedAt">;
+
+export interface BlogSitemapInput {
+  /** Published articles. */
+  readonly articles: readonly SitemapText[];
+  /** Published glossary terms. */
+  readonly terms: readonly SitemapText[];
+  readonly routes: BlogRoutes;
+  /** The method page's path when the app mounts it, else `null`. */
+  readonly methodPath: string | null;
+}
+
+const HUB_PRIORITY = 0.7;
+const PILLAR_PRIORITY = 0.7;
+const ARTICLE_PRIORITY = 0.6;
+const GLOSSARY_PRIORITY = 0.5;
+const METHOD_PRIORITY = 0.3;
+
+/**
+ * The listing and its articles, the glossary and its terms, and the method page. **An empty list adds
+ * no hub**: an empty listing or glossary is `noindex`, and a sitemap pointing at a page kept out of the
+ * index is a contradicting signal. The method page has no content date, so it has no `lastModified`.
+ */
+export function getBlogSitemapEntries({ articles, terms, routes, methodPath }: BlogSitemapInput): BlogSitemapEntry[] {
+  const entries: BlogSitemapEntry[] = [];
+  const listingModified = getLatestModified(articles);
+  if (listingModified !== null) {
+    entries.push(
+      { path: routes.index, lastModified: listingModified, priority: HUB_PRIORITY },
+      ...articles.map((article) => ({
+        path: getArticlePath(routes, article.slug),
+        lastModified: getTextLastModified(article),
+        priority: article.isPillar ? PILLAR_PRIORITY : ARTICLE_PRIORITY,
+      })),
+    );
+  }
+  const glossaryModified = getLatestModified(terms);
+  if (glossaryModified !== null) {
+    entries.push(
+      { path: routes.glossary, lastModified: glossaryModified, priority: GLOSSARY_PRIORITY },
+      ...terms.map((term) => ({ path: getTermPath(routes, term.slug), lastModified: getTextLastModified(term), priority: GLOSSARY_PRIORITY })),
+    );
+  }
+  if (methodPath !== null) entries.push({ path: methodPath, priority: METHOD_PRIORITY });
+  return entries;
+}

package/src/discovery/submit.ts

@@ -0,0 +1,69 @@
+// The IndexNow submit after a publish: the CLI calls it after `softure-blog publish`, and an app with
+// its own publishing path calls it after `runBlogPublish`. It reaches `@softure-ai/seo` through a
+// dynamic import, and only when the config lists `seo()`: seo is an optional peer, so an app without
+// it still runs the blog.
+import { getModule, type SoftureConfig } from "@softure-ai/core";
+import { getBlogRoutes } from "../server/options.js";
+import { getIndexNowPaths, type IndexNowChange } from "./indexnow.js";
+
+const SEO_MODULE_ID = "seo";
+
+export type BlogIndexNowOutcome =
+  /** seo is not listed, or it has no IndexNow key: nothing is sent. */
+  | { readonly kind: "not_configured"; readonly reason: string }
+  /** The run changed no public address. */
+  | { readonly kind: "skipped" }
+  /** No commit: the URLs a commit would submit, and no request. */
+  | { readonly kind: "dry_run"; readonly endpoint: string; readonly urls: readonly string[] }
+  | { readonly kind: "submitted"; readonly status: number; readonly count: number }
+  | { readonly kind: "failed"; readonly code: string; readonly reason: string };
+
+export interface BlogIndexNowSubmit {
+  /** The changed paths (`getIndexNowPaths`), also when nothing is sent. */
+  readonly paths: readonly string[];
+  readonly outcome: BlogIndexNowOutcome;
+}
+
+export interface SubmitBlogChangesOptions {
+  /** Sends the request only when `true`, i.e. after a committed run; otherwise a dry run. */
+  readonly commit?: boolean;
+  readonly fetchImpl?: typeof fetch;
+}
+
+/**
+ * Submits the addresses a publish run changed through seo's IndexNow, on seo's site origin. Refresh
+ * the app's cache first (`requestBlogRefresh`, or `revalidateTag("softure-blog", { expire: 0 })` inside
+ * Next), so a crawler that comes at once sees the new text.
+ * Never throws for an expected failure: a submit is an extra after a publish and must not undo it.
+ */
+export async function submitBlogChanges(config: SoftureConfig, changes: readonly IndexNowChange[], options: SubmitBlogChangesOptions = {}): Promise<BlogIndexNowSubmit> {
+  const paths = getIndexNowPaths(changes, getBlogRoutes(config));
+  const seoModule = getModule(config, SEO_MODULE_ID);
+  if (seoModule === undefined) return { paths, outcome: { kind: "not_configured", reason: "the seo module is not enabled; add seo({ indexNow: { key } }) to modules" } };
+
+  const [{ buildCanonicalUrl, resolveSeoSettings }, { submitToIndexNow }] = await Promise.all([import("@softure-ai/seo"), import("@softure-ai/seo/server")]);
+  // The seo module factory parsed its options and declares both routes.
+  const settings = resolveSeoSettings(seoModule.options as Parameters<typeof resolveSeoSettings>[0], {
+    appOrigin: config.appOrigin,
+    routes: seoModule.routes as unknown as Parameters<typeof resolveSeoSettings>[1]["routes"],
+  });
+  if (settings.indexNowKey === null) return { paths, outcome: { kind: "not_configured", reason: "seo has no IndexNow key; set seo({ indexNow: { key } })" } };
+
+  // Canonical URLs (seo's host and trailing-slash rule), so the engines learn the address the pages declare.
+  const urls = paths.map((path) => buildCanonicalUrl(path, settings));
+  const result = await submitToIndexNow(urls, {
+    key: settings.indexNowKey,
+    siteOrigin: settings.siteOrigin,
+    keyPath: settings.routes.indexNowKey,
+    commit: options.commit === true,
+    ...(options.fetchImpl === undefined ? {} : { fetchImpl: options.fetchImpl }),
+  });
+  switch (result.kind) {
+    case "dry_run":
+      return { paths, outcome: { kind: "dry_run", endpoint: result.endpoint, urls: result.body.urlList } };
+    case "failed":
+      return { paths, outcome: { kind: "failed", code: result.code, reason: result.reason } };
+    default:
+      return { paths, outcome: result };
+  }
+}