@softure-ai/blog 0.1.6 → 0.1.7

package/src/db/history.ts

@@ -0,0 +1,83 @@
+// The history of articles an app published before it moved to this module: when each text first went
+// public, when it last changed, and the slugs it had before. A first publish into `blog.*` would
+// otherwise date every text today and lose the old addresses' 301s.
+//
+// The app exports it once from its own tables as JSON (README, "Moving an existing blog") and passes it
+// to `softure-blog publish --history <file>`. It applies only to an article that has no row yet, so a
+// re-run with the same file changes nothing, and the article file's own `published_at` still wins.
+import { z } from "zod";
+
+const SLUG = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+
+const timestamp = z.iso.datetime({
+  offset: true,
+  error: (issue) =>
+    issue.input === undefined
+      ? "is required: an ISO 8601 timestamp, or null for a text that was never published"
+      : "must be an ISO 8601 timestamp with a time zone, e.g. 2026-09-01T08:00:00Z",
+});
+
+const oldSlugSchema = z.strictObject({
+  slug: z.string().max(100).regex(SLUG, "must be a kebab-case slug"),
+  changed_at: timestamp.optional(),
+});
+
+const entrySchema = z
+  .strictObject({
+    id: z.string().max(100).regex(SLUG, "must be a kebab-case article id"),
+    published_at: timestamp.nullable(),
+    updated_at: timestamp.nullable().optional(),
+    old_slugs: z.array(oldSlugSchema).default([]),
+  })
+  .refine((entry) => entry.updated_at === undefined || entry.updated_at === null || entry.published_at !== null, {
+    message: "updated_at needs published_at: a text is updated only after it was published",
+    path: ["updated_at"],
+  });
+
+export const articleHistorySchema = z
+  .strictObject({ articles: z.array(entrySchema) })
+  .superRefine((history, context) => {
+    const ids = new Set<string>();
+    const slugs = new Set<string>();
+    history.articles.forEach((entry, index) => {
+      if (ids.has(entry.id)) context.addIssue({ code: "custom", path: ["articles", index, "id"], message: `"${entry.id}" is listed twice` });
+      ids.add(entry.id);
+      entry.old_slugs.forEach((old, slugIndex) => {
+        if (slugs.has(old.slug)) context.addIssue({ code: "custom", path: ["articles", index, "old_slugs", slugIndex, "slug"], message: `"${old.slug}" is an old slug twice` });
+        slugs.add(old.slug);
+      });
+    });
+  });
+
+/** What the module keeps from an article's earlier life. */
+export interface ArticleHistory {
+  readonly publishedAt: Date | null;
+  /** Kept only with `publishedAt`. */
+  readonly updatedAt: Date | null;
+  readonly oldSlugs: readonly { readonly slug: string; readonly changedAt: Date | null }[];
+}
+
+/** History by article id. */
+export type ArticleHistoryMap = ReadonlyMap<string, ArticleHistory>;
+
+/** The parsed history, or the problems that name the field (`articles.3.published_at: …`). */
+export function parseArticleHistory(input: unknown): { readonly ok: true; readonly history: ArticleHistoryMap } | { readonly ok: false; readonly errors: readonly string[] } {
+  const parsed = articleHistorySchema.safeParse(input);
+  if (!parsed.success) {
+    return { ok: false, errors: parsed.error.issues.map((issue) => `${issue.path.join(".") || "history"}: ${issue.message}`) };
+  }
+  const toDate = (value: string | null | undefined) => (value === null || value === undefined ? null : new Date(value));
+  return {
+    ok: true,
+    history: new Map(
+      parsed.data.articles.map((entry) => [
+        entry.id,
+        {
+          publishedAt: toDate(entry.published_at),
+          updatedAt: toDate(entry.updated_at),
+          oldSlugs: entry.old_slugs.map((old) => ({ slug: old.slug, changedAt: toDate(old.changed_at) })),
+        },
+      ]),
+    ),
+  };
+}

package/src/db/publish-run.ts

@@ -12,6 +12,7 @@ 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 type { ArticleHistory, ArticleHistoryMap } from "./history.js";
 import { articles } from "./schema.js";
 
 export interface ArticleFile {
@@ -33,6 +34,11 @@ export interface RunBlogPublishOptions extends ParseArticleFileOptions {
   /** Publish the files as `withdrawn`, whatever their status (taking a text down at once). */
   readonly withdraw?: boolean;
   readonly gate?: PublishGate;
+  /**
+   * The earlier life of articles an app moves in (history.ts), by id: applied to an article of the run
+   * that has no row yet. An entry for an id outside the run is a warning.
+   */
+  readonly history?: ArticleHistoryMap;
 }
 
 /** A problem that stops the run; `subject` is a file name, an article id or a cluster. */
@@ -52,6 +58,11 @@ export interface PublishedChange {
   readonly slug: string;
   /** The slug that entered the slug history in this run. */
   readonly previousSlug: string | null;
+  /** Set when the run applied the article's history (`history`): its dates and old slugs. */
+  readonly imported?: {
+    readonly publishedAt: Date | null;
+    readonly oldSlugs: number;
+  };
 }
 
 export type BlogPublishRun =
@@ -100,15 +111,21 @@ export async function runBlogPublish(ctx: BlogContext, files: readonly ArticleFi
 
   problems.push(...findDuplicateIds(inputs), ...findPillarProblems(inputs));
   if (problems.length > 0) return { status: "refused", problems, warnings };
+  const runIds = new Set(inputs.map((input) => input.id));
+  for (const id of options.history?.keys() ?? []) {
+    if (!runIds.has(id)) warnings.push({ subject: id, message: "the history names an article that is not in this run; it is applied when its file is published" });
+  }
 
   const changes: PublishedChange[] = [];
   try {
     await ctx.db.transaction(async (tx) => {
       for (const input of inputs) {
-        const result = await publishArticleOrRefuse({ ...ctx, db: tx }, input);
+        const history = options.history?.get(input.id);
+        const result = await publishArticleOrRefuse({ ...ctx, db: tx }, input, history);
         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})` }]);
+          const slug = result.slug === undefined ? `slug ${input.slug}` : `old slug ${result.slug} (history)`;
+          throw new PublishRefused([{ subject: input.id, message: `${slug} ${reason} article ${result.otherArticleId} (${result.error})` }]);
         }
         changes.push({
           id: input.id,
@@ -119,6 +136,9 @@ export async function runBlogPublish(ctx: BlogContext, files: readonly ArticleFi
           slugBefore: result.before?.slug ?? null,
           slug: result.after.slug,
           previousSlug: result.previousSlug,
+          ...(result.imported === true && history !== undefined
+            ? { imported: { publishedAt: result.after.publishedAt, oldSlugs: history.oldSlugs.filter((old) => old.slug !== input.slug).length } }
+            : {}),
         });
       }
       const glossary = await checkGlossaryForms({ ...ctx, db: tx }, inputs);
@@ -192,9 +212,9 @@ async function checkGlossaryForms(ctx: BlogContext, inputs: readonly BlogArticle
  * 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> {
+async function publishArticleOrRefuse(ctx: BlogContext, input: BlogArticleInput, history: ArticleHistory | undefined): ReturnType<typeof publishArticle> {
   try {
-    return await publishArticle(ctx, input);
+    return await publishArticle(ctx, input, history === undefined ? {} : { history });
   } catch (error) {
     const driverError = findDriverError(error);
     if (driverError?.code !== UNIQUE_VIOLATION || driverError.constraint !== SLUG_CONSTRAINT) throw error;

package/src/index.ts

@@ -29,7 +29,7 @@ export const BLOG_RATE_LIMIT_BUCKETS = {
 export const blog = defineModule({
   manifest: {
     id: MODULE_ID,
-    version: "0.1.6",
+    version: "0.1.7",
     // seo is optional: with it the sitemap lists the texts and a publish pings IndexNow. security is
     // optional too: only the cache refresh route needs it, for its rate limit.
     dependsOn: { seo: "^0.1.0?", security: "^0.1.0?" },

package/src/options.ts

@@ -50,8 +50,12 @@ function isFieldsSchema(value: unknown): value is BlogFieldsSchema {
 
 function isBlockPlugin(value: unknown): value is BlockPlugin {
   if (typeof value !== "object" || value === null) return false;
-  const candidate = value as { type?: unknown; render?: unknown };
-  return typeof candidate.type === "string" && KEBAB.test(candidate.type) && typeof candidate.render === "function";
+  const candidate = value as { type?: unknown; syntax?: unknown; render?: unknown; markdown?: unknown };
+  return (
+    typeof candidate.type === "string" && KEBAB.test(candidate.type) && typeof candidate.render === "function" &&
+    (candidate.syntax === undefined || candidate.syntax === "fence" || candidate.syntax === "directive") &&
+    (candidate.markdown === undefined || typeof candidate.markdown === "function")
+  );
 }
 
 /** How long the pages cache their reads by default, in seconds; the app's `revalidate` should match. */

package/src/pages/accept.ts

@@ -0,0 +1,39 @@
+// Content negotiation for the Markdown representation: which requests ask for Markdown.
+
+interface MediaRange {
+  readonly type: string;
+  readonly subtype: string;
+  readonly q: number;
+}
+
+function parseAccept(accept: string): MediaRange[] {
+  return accept.split(",").flatMap((part) => {
+    const [range = "", ...params] = part.trim().toLowerCase().split(";");
+    const [type, subtype] = range.trim().split("/");
+    if (type === undefined || type === "" || subtype === undefined || subtype === "") return [];
+    const qParam = params.map((param) => param.trim()).find((param) => param.startsWith("q="));
+    const q = qParam === undefined ? 1 : Number(qParam.slice(2));
+    return Number.isFinite(q) ? [{ type, subtype, q }] : [];
+  });
+}
+
+/** The weight of a type by the most specific matching range (RFC 9110 §12.5.1); 0 without a match. */
+function getQuality(ranges: readonly MediaRange[], type: string, subtype: string): number {
+  const exact = ranges.find((range) => range.type === type && range.subtype === subtype);
+  const group = ranges.find((range) => range.type === type && range.subtype === "*");
+  const any = ranges.find((range) => range.type === "*" && range.subtype === "*");
+  return (exact ?? group ?? any)?.q ?? 0;
+}
+
+/**
+ * Whether an `Accept` header asks for Markdown rather than HTML. `text/markdown` must be named: `*\/*`
+ * (curl, most crawlers, browser prefetches) matches Markdown as well as HTML, and they want the page.
+ * A tie goes to Markdown: a client that names it next to HTML with the same weight is an agent.
+ */
+export function prefersMarkdown(accept: string | null): boolean {
+  if (accept === null) return false;
+  const ranges = parseAccept(accept);
+  const markdown = ranges.find((range) => range.type === "text" && range.subtype === "markdown");
+  if (markdown === undefined || markdown.q <= 0) return false;
+  return markdown.q >= getQuality(ranges, "text", "html");
+}

package/src/proxy/index.ts

@@ -8,12 +8,21 @@
 //   }
 //
 // Next 16 runs `proxy.ts` on Node.js, so the database handle is the process-wide one.
+//
+// `createBlogMarkdown` answers an article or term page asked for with `Accept: text/markdown` with the
+// text as Markdown; put it before the redirects so a moved or withdrawn text still answers as before:
+//
+//   return (await blogMarkdown(request)) ?? (await blogRedirects(request)) ?? …
 import { systemClock, type SoftureConfig } from "@softure-ai/core";
 import { getConfiguredDatabase } from "@softure-ai/db";
-import { findArticleBySlug, findSlugRedirect, type BlogContext } from "../db/articles.js";
+import { findArticleBySlug, findSlugRedirect, getPublishedArticle, type BlogContext } from "../db/articles.js";
+import { prefersMarkdown } from "../pages/accept.js";
+import { toArticleMarkdown } from "../render/article-markdown.js";
 import { matchBlogPath } from "../pages/paths.js";
 import { buildGonePage, createCachedBlogPathDecider, type BlogPathLookup, type CachedDeciderOptions } from "../pages/redirects.js";
-import { getBlogMessages, getBlogReservedSlugs, getBlogRoutes } from "../server/options.js";
+import { getBlogMessages, getBlogOptions, getBlogReservedSlugs, getBlogRoutes } from "../server/options.js";
+
+export { prefersMarkdown };
 
 export type BlogRedirects = (request: Request) => Promise<Response | null>;
 
@@ -64,3 +73,52 @@ export function createBlogRedirects(config: SoftureConfig, options: BlogRedirect
     return null;
   };
 }
+
+export type BlogMarkdown = (request: Request) => Promise<Response | null>;
+
+export interface BlogMarkdownOptions {
+  /** The store's context; the shared database handle of `config.database` by default (tests pass PGlite). */
+  readonly getContext?: () => Promise<BlogContext>;
+  /** Where a failed read is reported; `console.error` by default. The request then goes on to the page. */
+  readonly onError?: (message: string) => void;
+}
+
+const MARKDOWN_HEADERS = {
+  "content-type": "text/markdown; charset=utf-8",
+  // One address, two representations. `private`: a shared cache must not hand Markdown to a browser.
+  vary: "Accept",
+  "cache-control": "private, max-age=0, must-revalidate",
+};
+
+/**
+ * Answers a GET or HEAD of a published article or term whose `Accept` asks for Markdown
+ * (`prefersMarkdown`) with the text as Markdown (`toArticleMarkdown`, the app's block plugins giving
+ * their Markdown form). `null` for everything else, and when the read fails: the page answers then.
+ */
+export function createBlogMarkdown(config: SoftureConfig, options: BlogMarkdownOptions = {}): BlogMarkdown {
+  const routes = getBlogRoutes(config);
+  const reservedSlugs = getBlogReservedSlugs(config);
+  const getContext = options.getContext ?? createDefaultContext(config);
+  const onError = options.onError ?? ((message: string) => console.error(message));
+  const { blocks } = getBlogOptions(config);
+  const messages = getBlogMessages(config).pages;
+
+  return async (request) => {
+    if (request.method !== "GET" && request.method !== "HEAD") return null;
+    if (!prefersMarkdown(request.headers.get("accept"))) return null;
+    const url = new URL(request.url);
+    const match = matchBlogPath(url.pathname, routes, reservedSlugs);
+    if (match === null) return null;
+    let article;
+    try {
+      article = await getPublishedArticle(await getContext(), match.slug);
+    } catch (error) {
+      onError(`@softure-ai/blog: reading ${url.pathname} as Markdown failed: ${error instanceof Error ? error.message : String(error)}`);
+      return null;
+    }
+    if (article?.kind !== match.kind) return null;
+    const body = toArticleMarkdown(article, { blocks, messages });
+    const headers = { ...MARKDOWN_HEADERS, "x-markdown-tokens": String(Math.ceil(body.length / 4)) };
+    return new Response(request.method === "HEAD" ? null : body, { status: 200, headers });
+  };
+}

package/src/quality/catalog.ts

@@ -75,7 +75,10 @@ export function listQualityRules(settings: QualitySettings): QualityCatalogRule[
     ...ruleset.patterns.map((pattern) => rule("style", pattern.id, pattern.severity, pattern.message)),
     ...settings.voicePatterns.map((pattern) => rule("voice", pattern.id, pattern.severity, pattern.message)),
     ...(options.ymyl === null ? [] : YMYL_RULES),
-    ...(options.blocks.length === 0 ? [] : [rule("structure", "block-requires", "error", "a block plugin's fenced block has the frontmatter keys it requires")]),
+    ...(options.blocks.length === 0 ? [] : [rule("structure", "block-requires", "error", "a block plugin's block has the frontmatter keys it requires")]),
+    ...(options.blocks.some((plugin) => plugin.syntax === "directive")
+      ? [rule("structure", "block-directive", "error", "a ::directive line names a directive the blog renders, with readable key=\"value\" attributes")]
+      : []),
     ...(options.plugins.length === 0 ? [] : PLUGIN_RULES),
     ...options.plugins.flatMap((plugin) => plugin.rules.map((info) => rule("plugin", info.id, info.severity, info.description))),
   ];

package/src/quality/check-article.ts

@@ -8,7 +8,7 @@ import { parseArticleFile, type ParseArticleFileOptions } from "../content/artic
 import { splitArticleBody, splitBlocks } from "./blocks.js";
 import { sortFindings, type QualityFinding } from "./finding.js";
 import type { QualityPlugin } from "./plugin.js";
-import { checkBlockRequires } from "./rules/blocks.js";
+import { checkBlockRequires, checkDirectives } from "./rules/blocks.js";
 import { checkImages } from "./rules/images.js";
 import type { RuleInput } from "./rules/input.js";
 import { checkLinks, collectLinks, type InternalLinkResolver } from "./rules/links.js";
@@ -58,6 +58,7 @@ export function checkArticle(input: CheckArticleInput): QualityCheckResult {
     ...checkStyle(ruleInput),
     ...checkRhythm(ruleInput),
     ...checkBlockRequires(article, pluginBlocks),
+    ...checkDirectives(blocks, pluginBlocks, settings.options.blocks),
     ...checkImages(images, settings.images),
   ];
   const fromPlugins = settings.options.plugins.flatMap((plugin) => runPlugin(plugin, { article, blocks, pluginBlocks, today, ruleset: settings.ruleset }));

package/src/quality/options.ts

@@ -9,8 +9,12 @@ const KEBAB = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 
 function isBlockPlugin(value: unknown): value is BlockPlugin {
   if (typeof value !== "object" || value === null) return false;
-  const candidate = value as { type?: unknown; render?: unknown };
-  return typeof candidate.type === "string" && typeof candidate.render === "function";
+  const candidate = value as { type?: unknown; syntax?: unknown; render?: unknown; markdown?: unknown };
+  return (
+    typeof candidate.type === "string" && typeof candidate.render === "function" &&
+    (candidate.syntax === undefined || candidate.syntax === "fence" || candidate.syntax === "directive") &&
+    (candidate.markdown === undefined || typeof candidate.markdown === "function")
+  );
 }
 
 const range = (min: number, max: number) =>

package/src/quality/rules/blocks.ts

@@ -1,7 +1,8 @@
 // Block plugin needs (BL-3): a fenced block of a block plugin reads frontmatter keys (`requires`), and
 // an article that lacks one would render the block without its data.
 import type { BlogArticleInput } from "../../contract.js";
-import type { FoundBlock } from "../../render/render-article.js";
+import { parseDirectiveLine, type BlockPlugin, type FoundBlock } from "../../render/render-article.js";
+import type { Block } from "../blocks.js";
 import type { QualityFinding } from "../finding.js";
 
 export function checkBlockRequires(article: BlogArticleInput, pluginBlocks: readonly FoundBlock[]): QualityFinding[] {
@@ -41,3 +42,27 @@ function hasFrontmatterKey(article: BlogArticleInput, key: string): boolean {
       return article.fields[key] !== undefined;
   }
 }
+
+/**
+ * Directive lines the renderer would not turn into a block (BL-6 for directives): a name no directive
+ * plugin renders (it would show as a paragraph `::chrat{…}`), or attributes it cannot read. Checked
+ * only when the app registers a directive plugin; otherwise `::` lines are the app's own business.
+ */
+export function checkDirectives(blocks: readonly Block[], pluginBlocks: readonly FoundBlock[], plugins: readonly BlockPlugin[]): QualityFinding[] {
+  const names = plugins.filter((plugin) => plugin.syntax === "directive").map((plugin) => plugin.type);
+  if (names.length === 0) return [];
+  const unknown = blocks.flatMap((block) => {
+    if (block.kind !== "directive") return [];
+    const directive = parseDirectiveLine(block.text);
+    if (directive === null || names.includes(directive.name)) return [];
+    return [finding(`::${directive.name} is not a directive this blog renders; use one of: ${names.join(", ")}`, block.line)];
+  });
+  const unreadable = pluginBlocks
+    .filter((block) => block.syntax === "directive" && block.attributes === null)
+    .map((block) => finding(`the attributes of ::${block.type} cannot be read; write them as key="value" pairs, each key once`, block.line));
+  return [...unknown, ...unreadable].sort((a, b) => (a.line ?? 0) - (b.line ?? 0));
+}
+
+function finding(message: string, line: number): QualityFinding {
+  return { rule: "block-directive", severity: "error", message, line };
+}

package/src/render/article-markdown.ts

@@ -0,0 +1,34 @@
+// An article or term as Markdown for agents (`Accept: text/markdown`): the stored Markdown in a frame
+// that carries what the HTML page shows around it (title, description, the day the facts were checked,
+// the summary, sources and FAQ). Exact by construction: no HTML round trip.
+import type { BlogArticle } from "../contract.js";
+import { en } from "../messages/en.js";
+import { replaceArticleBlocks, type BlockPlugin } from "./render-article.js";
+
+export type ArticleMarkdownInput = Pick<BlogArticle, "title" | "description" | "summary" | "bodyMarkdown" | "sources" | "faq" | "currentAsOf" | "fields">;
+
+export interface ArticleMarkdownOptions {
+  /** The app's block plugins; a block whose plugin has `markdown` is replaced by its output. */
+  readonly blocks?: readonly BlockPlugin[];
+  /** The pages' copy for the frame's labels; English by default. */
+  readonly messages?: Pick<(typeof en)["pages"], "summary" | "sources" | "faq" | "currentAsOf">;
+}
+
+export function toArticleMarkdown(article: ArticleMarkdownInput, options: ArticleMarkdownOptions = {}): string {
+  const messages = options.messages ?? en.pages;
+  const body = replaceArticleBlocks(article.bodyMarkdown.trim(), options.blocks ?? [], { currentAsOf: article.currentAsOf, fields: article.fields });
+  const parts = [`# ${article.title}`, article.description, `${messages.currentAsOf}: ${article.currentAsOf}`];
+  if (article.summary !== null) parts.push(`> **${messages.summary}:** ${article.summary}`);
+  parts.push(body);
+  if (article.sources.length > 0) {
+    parts.push(`## ${messages.sources}`, article.sources.map((source) => `- [${escapeLinkText(source.name)}](${source.url})`).join("\n"));
+  }
+  if (article.faq.length > 0) {
+    parts.push(`## ${messages.faq}`, ...article.faq.flatMap((entry) => [`### ${entry.question}`, entry.answer]));
+  }
+  return `${parts.join("\n\n")}\n`;
+}
+
+function escapeLinkText(text: string): string {
+  return text.replace(/[[\]\\]/g, (char) => `\\${char}`);
+}

package/src/render/index.ts

@@ -11,11 +11,17 @@ export {
   type ImageProblem,
   type ImageVerdict,
 } from "./images.js";
+export { toArticleMarkdown, type ArticleMarkdownInput, type ArticleMarkdownOptions } from "./article-markdown.js";
 export { DEFAULT_WORDS_PER_MINUTE, getReadingMinutes } from "./reading-time.js";
 export {
   findArticleBlocks,
+  parseDirectiveAttributes,
+  parseDirectiveLine,
   renderArticle,
+  replaceArticleBlocks,
   type ArticleBlock,
+  type BlockAttributes,
+  type BlockSyntax,
   type ArticleHeading,
   type ArticleSegment,
   type BlockArticle,