@softure-ai/blog 0.1.5 → 0.1.7

package/src/cli/run.ts

@@ -9,11 +9,13 @@
 import { mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { parseArgs } from "node:util";
-import { systemClock, type Clock, type SoftureConfig } from "@softure-ai/core";
-import { createDatabase, type DatabaseHandle } from "@softure-ai/db";
-import { BLOG_REFRESH_SECRET_ENV, requestBlogRefresh, type BlogRefreshOutcome } from "../discovery/refresh.js";
-import { submitBlogChanges, type BlogIndexNowSubmit } from "../discovery/submit.js";
-import { runBlogPublish, type ArticleFile, type BlogPublishRun, type PublishedChange, type PublishGate, type PublishProblem } from "../db/publish-run.js";
+import { systemClock, type Clock, type SoftureConfig, type SoftureDatabaseConfig } from "@softure-ai/core";
+import { openCommandDatabase, type CommandDatabase, type DatabaseHandle } from "@softure-ai/db";
+import { z } from "zod";
+import { BLOG_REFRESH_SECRET_ENV, requestBlogRefresh } from "../discovery/refresh.js";
+import { submitBlogChanges } from "../discovery/submit.js";
+import { parseArticleHistory, type ArticleHistoryMap } from "../db/history.js";
+import { runBlogPublish, type ArticleFile, type PublishGate } from "../db/publish-run.js";
 import { checkArticleFiles, type FileCheckResult } from "../quality/check-files.js";
 import type { FetchLike } from "../quality/external-links.js";
 import { createQualityGate } from "../quality/gate.js";
@@ -22,12 +24,10 @@ import { getLocalDate } from "../quality/settings.js";
 import type { OgFontSource } from "../options.js";
 import { createOgFontLoader } from "../server/og-fonts.js";
 import { getBlogOptions, getBlogReservedSlugs, getQualitySettings } from "../server/options.js";
+import { createPublishReporter, type CliOutput, type PublishFormat } from "./report.js";
 import { DEFAULT_SKILL_COMMAND, DEFAULT_SKILL_DIR, renderBlogSkill, SKILL_MARKER, type SkillFile } from "./skill.js";
 
-export interface CliOutput {
-  readonly log: (line: string) => void;
-  readonly error: (line: string) => void;
-}
+export type { CliOutput };
 
 export interface RunBlogCliOptions {
   /** The app's config with `blog()` among its modules. */
@@ -37,7 +37,7 @@ export interface RunBlogCliOptions {
   /** Relative paths resolve against it. Default: `process.cwd()`. */
   readonly cwd?: string;
   readonly output?: CliOutput;
-  /** Opens the database connection. Default: `createDatabase(url, { max: 1 })`. */
+  /** Opens the database connection. Default: the config's `database.handle`, else `createDatabase(url, { max: 1 })`. */
   readonly openDatabase?: (url: string) => Promise<DatabaseHandle>;
   /** The gate for files going public. Default: the quality gate of `blog({ quality })`, none with `quality: false`. */
   readonly gate?: PublishGate;
@@ -52,6 +52,8 @@ export interface RunBlogCliOptions {
   readonly refreshFetch?: typeof fetch;
   /** Where `publish` reads BLOG_REFRESH_SECRET. Default: `process.env`. */
   readonly env?: Readonly<Record<string, string | undefined>>;
+  /** What `publish --stdin` reads. Default: the whole of `process.stdin`, as UTF-8. */
+  readonly readStdin?: () => Promise<string>;
 }
 
 export const EXIT_OK = 0;
@@ -60,6 +62,7 @@ export const EXIT_USAGE = 2;
 
 export const BLOG_USAGE = `Usage:
   softure-blog publish [<path>...] [--commit] [--withdraw] [--no-indexnow] [--app-url <origin>]
+                       [--stdin [--name <slug>.md]] [--history <file.json>] [--format text|lines]
   softure-blog check [<path>...] [--external] [--today <YYYY-MM-DD>]
   softure-blog skill install [--dir <path>] [--command <cmd>] [--check]
 
@@ -70,6 +73,12 @@ publish   Brings the blog's tables to the state of the article files. A <path> i
   --withdraw    publish the one given file as withdrawn, whatever its status
   --no-indexnow do not submit the changed addresses to IndexNow
   --app-url     the running app's origin for the cache refresh; default: appOrigin
+  --stdin       read the files from standard input instead of paths: one file named by
+                --name, or without --name a JSON bundle {"files":[{"name","text"}]}
+                (optionally with "history", the content of a --history file)
+  --history     a JSON file of the articles' earlier dates and old slugs, applied on the
+                first publish of each article (moving an existing blog in)
+  --format      text (default) or lines: a stable blog|<key>|... contract for scripts
           Files going public pass the quality gate first; an error writes nothing.
           With ${BLOG_REFRESH_SECRET_ENV} set, a commit that changed a text asks the running
           app (refreshBlogCache) to refresh its blog cache, before the IndexNow submit.
@@ -107,6 +116,11 @@ export type BlogCommand =
       readonly indexNow: boolean;
       /** The origin `--app-url` gives; `null`: `appOrigin`. */
       readonly appUrl: string | null;
+      /** Read the files from standard input; `name`: one file, `null`: a JSON bundle. */
+      readonly stdin: { readonly name: string | null } | null;
+      /** The `--history` file, as given. */
+      readonly history: string | null;
+      readonly format: PublishFormat;
     }
   | { readonly kind: "check"; readonly paths: readonly string[]; readonly external: boolean; readonly today: string | null }
   | { readonly kind: "skill-install"; readonly dir: string; readonly command: string; readonly check: boolean };
@@ -146,10 +160,28 @@ export function parseBlogCommand(argv: readonly string[]): BlogCommand | string
   const { values, positionals } = parsed;
   if (values.help === true) return { kind: "help" };
   const withdraw = values.withdraw === true;
-  if (withdraw && positionals.length !== 1) return "--withdraw takes exactly one article file";
+  const isStdin = values.stdin === true;
+  const stdinName = values.name ?? null;
+  if (isStdin && positionals.length > 0) return "--stdin reads the files from standard input; give no paths with it";
+  if (!isStdin && stdinName !== null) return "--name names the file --stdin reads; use it with --stdin";
+  if (stdinName !== null && !/^[^/\\]+\.md$/.test(stdinName)) return `--name needs a file name <slug>.md, not "${stdinName}"`;
+  if (withdraw && !(isStdin ? stdinName !== null : positionals.length === 1)) return "--withdraw takes exactly one article file";
   const appUrl = values["app-url"] === undefined ? null : parseOrigin(values["app-url"]);
   if (appUrl === undefined) return `--app-url needs an http or https origin, e.g. http://web:3000, not "${values["app-url"] ?? ""}"`;
-  return { kind: "publish", paths: positionals, commit: values.commit === true, withdraw, indexNow: values["no-indexnow"] !== true, appUrl };
+  const format = values.format ?? "text";
+  if (format !== "text" && format !== "lines") return `--format is text or lines, not "${format}"`;
+  if (values.history !== undefined && values.history.trim() === "") return "--history needs a JSON file";
+  return {
+    kind: "publish",
+    paths: positionals,
+    commit: values.commit === true,
+    withdraw,
+    indexNow: values["no-indexnow"] !== true,
+    appUrl,
+    stdin: isStdin ? { name: stdinName } : null,
+    history: values.history ?? null,
+    format,
+  };
 }
 
 /** The origin of an http(s) URL, or `undefined` for anything else. */
@@ -232,6 +264,10 @@ function parsePublishArgs(args: readonly string[]) {
       withdraw: { type: "boolean" },
       "no-indexnow": { type: "boolean" },
       "app-url": { type: "string" },
+      stdin: { type: "boolean" },
+      name: { type: "string" },
+      history: { type: "string" },
+      format: { type: "string" },
       help: { type: "boolean" },
     },
     strict: true,
@@ -242,27 +278,28 @@ function parsePublishArgs(args: readonly string[]) {
 async function runPublish(command: Extract<BlogCommand, { kind: "publish" }>, options: RunBlogCliOptions, output: CliOutput): Promise<number> {
   const cwd = options.cwd ?? process.cwd();
   const { config } = options;
+  const report = createPublishReporter(command.format, output);
+  const fail = (message: string): number => {
+    report.failed(message);
+    return EXIT_FAILED;
+  };
   let blogOptions: ReturnType<typeof getBlogOptions>;
   try {
     blogOptions = getBlogOptions(config);
   } catch (error) {
-    output.error(`softure-blog publish: ${describeError(error)}`);
-    return EXIT_FAILED;
-  }
-  const paths = command.paths.length > 0 ? command.paths : [blogOptions.contentDir];
-  const files = await readArticleFiles(paths.map((path) => resolve(cwd, path)));
-  if (typeof files === "string") {
-    output.error(`softure-blog publish: ${files}`);
-    return EXIT_FAILED;
-  }
-  if (command.withdraw && files.length !== 1) {
-    output.error("softure-blog publish: --withdraw takes exactly one article file, not a folder");
-    return EXIT_FAILED;
-  }
-  if (config.database === null) {
-    output.error("softure-blog publish: the config has no database; set database.url in softure.config");
-    return EXIT_FAILED;
+    return fail(describeError(error));
   }
+  const input = command.stdin === null
+    ? { files: await readArticleFiles((command.paths.length > 0 ? command.paths : [blogOptions.contentDir]).map((path) => resolve(cwd, path))), history: undefined }
+    : await readStdinBundle(command.stdin.name, options.readStdin ?? readProcessStdin);
+  if (typeof input === "string") return fail(input);
+  const { files } = input;
+  if (typeof files === "string") return fail(files);
+  if (command.withdraw && files.length !== 1) return fail("--withdraw takes exactly one article file, not a folder");
+  if (command.history !== null && input.history !== undefined) return fail("the bundle on standard input carries a history; drop --history");
+  const history = command.history === null ? input.history : await readHistoryFile(resolve(cwd, command.history));
+  if (typeof history === "string") return fail(history);
+  if (config.database === null) return fail("the config has no database; set database.url in softure.config");
 
   const clock = options.clock ?? systemClock;
   let gate = options.gate;
@@ -271,16 +308,15 @@ async function runPublish(command: Extract<BlogCommand, { kind: "publish" }>, op
     if (settings !== null) gate = createQualityGate(settings, clock);
   }
 
-  let handle: DatabaseHandle;
+  let opened: CommandDatabase;
   try {
-    handle = await (options.openDatabase ?? openDatabase)(config.database.url);
+    opened = await openDatabase(config.database, options.openDatabase);
   } catch (error) {
-    output.error(`softure-blog publish: ${describeError(error)}`);
-    return EXIT_FAILED;
+    return fail(describeError(error));
   }
   try {
     const run = await runBlogPublish(
-      { db: handle.db, clock, config },
+      { db: opened.handle.db, clock, config },
       files,
       {
         commit: command.commit,
@@ -288,9 +324,10 @@ async function runPublish(command: Extract<BlogCommand, { kind: "publish" }>, op
         reservedSlugs: getBlogReservedSlugs(config),
         ...(blogOptions.fields === undefined ? {} : { fields: blogOptions.fields }),
         ...(gate === undefined ? {} : { gate }),
+        ...(history === undefined ? {} : { history }),
       },
     );
-    const code = reportRun(run, output);
+    report.run(run);
     if (run.status === "done") {
       // Before the IndexNow submit: a crawler that answers the ping must find the new text.
       const refresh = await requestBlogRefresh(config, run.changes, {
@@ -299,18 +336,17 @@ async function runPublish(command: Extract<BlogCommand, { kind: "publish" }>, op
         ...(options.env === undefined ? {} : { env: options.env }),
         ...(options.refreshFetch === undefined ? {} : { fetchImpl: options.refreshFetch }),
       });
-      reportRefresh(refresh, output);
+      report.refresh(refresh);
     }
     if (run.status === "done" && command.indexNow) {
-      reportIndexNow(await submitBlogChanges(config, run.changes, { commit: run.committed, ...(options.indexNowFetch === undefined ? {} : { fetchImpl: options.indexNowFetch }) }), output);
+      report.indexNow(await submitBlogChanges(config, run.changes, { commit: run.committed, ...(options.indexNowFetch === undefined ? {} : { fetchImpl: options.indexNowFetch }) }));
     }
-    return code;
+    return run.status === "done" ? EXIT_OK : EXIT_FAILED;
   } catch (error) {
     // Driver errors: the message only, never a stack or the database URL.
-    output.error(`softure-blog publish: ${describeError(error)} (did softure migrate run?)`);
-    return EXIT_FAILED;
+    return fail(`${describeError(error)} (did softure migrate run?)`);
   } finally {
-    await handle.close();
+    await opened.close();
   }
 }
 
@@ -450,72 +486,66 @@ function reportCheck(results: readonly FileCheckResult[], files: readonly ReadAr
   return errors > 0 ? EXIT_FAILED : EXIT_OK;
 }
 
-function reportRun(run: BlogPublishRun, output: CliOutput): number {
-  for (const warning of run.warnings) output.error(`warning ${formatProblem(warning)}`);
-  if (run.status === "refused") {
-    for (const problem of run.problems) output.error(`error ${formatProblem(problem)}`);
-    output.error("refused: nothing written; fix the problems above");
-    return EXIT_FAILED;
-  }
-  for (const change of run.changes) {
-    output.log(formatChange(change));
-    if (change.previousSlug !== null) output.log(`moved ${change.id} ${change.previousSlug} -> ${change.slug}`);
-  }
-  const count = (action: PublishedChange["action"]) => String(run.changes.filter((change) => change.action === action).length);
-  output.log(`summary: added ${count("added")}, changed ${count("changed")}, unchanged ${count("unchanged")}`);
-  output.log(run.committed ? "written" : "dry run: nothing written; pass --commit to write");
-  return EXIT_OK;
-}
 
-/** One line about the cache refresh; a failure is a warning and never changes the exit code. */
-function reportRefresh(outcome: BlogRefreshOutcome, output: CliOutput): void {
-  switch (outcome.kind) {
-    case "not_configured":
-      output.log(`cache: the running app shows the change within revalidateSeconds (${String(outcome.revalidateSeconds)} s); set ${BLOG_REFRESH_SECRET_ENV} to refresh it now`);
-      return;
-    case "skipped":
-      output.log("cache: no text changed, nothing to refresh");
-      return;
-    case "dry_run":
-      output.log(`cache: dry run, a commit would refresh ${outcome.url}`);
-      return;
-    case "refreshed":
-      output.log(`cache: refreshed ${outcome.url}`);
-      return;
-    case "failed":
-      output.error(`warning cache: ${outcome.reason} (${outcome.code}); the publish is written, the app shows it within ${String(outcome.revalidateSeconds)} s`);
-      return;
-  }
+
+
+
+
+const stdinBundleSchema = z.strictObject({
+  files: z
+    .array(z.strictObject({ name: z.string().regex(/^[^/\\]+\.md$/, "must be a file name <slug>.md"), text: z.string() }))
+    .min(1, "must list at least one file"),
+  /** The `--history` file's content, for a publish whose only input is standard input. */
+  history: z.unknown().optional(),
+});
+
+interface StdinBundle {
+  readonly files: ArticleFile[];
+  readonly history: ArticleHistoryMap | undefined;
 }
 
-/** One line about the IndexNow submit; a failure is a warning and never changes the exit code. */
-function reportIndexNow({ paths, outcome }: BlogIndexNowSubmit, output: CliOutput): void {
-  switch (outcome.kind) {
-    case "not_configured":
-      output.log(`indexnow: off, ${outcome.reason}`);
-      return;
-    case "skipped":
-      output.log("indexnow: no public address changed, nothing to submit");
-      return;
-    case "dry_run":
-      output.log(`indexnow: dry run, a commit would submit ${String(outcome.urls.length)} URL(s): ${outcome.urls.join(" ")}`);
-      return;
-    case "submitted":
-      output.log(`indexnow: submitted ${String(outcome.count)} URL(s) (${String(outcome.status)}): ${paths.join(" ")}`);
-      return;
-    case "failed":
-      output.error(`warning indexnow: ${outcome.reason} (${outcome.code}); the publish is written, submit the addresses later: ${paths.join(" ")}`);
-      return;
+/** What `--stdin` gives: one file named by `--name`, or the JSON bundle (files, optional history); or why it cannot be read. */
+async function readStdinBundle(name: string | null, readStdin: () => Promise<string>): Promise<StdinBundle | string> {
+  let text: string;
+  try {
+    text = await readStdin();
+  } catch (error) {
+    return `cannot read standard input: ${describeError(error)}`;
+  }
+  if (name !== null) return text.trim() === "" ? `standard input is empty; pipe the text of ${name}` : { files: [{ name, text }], history: undefined };
+  let json: unknown;
+  try {
+    json = JSON.parse(text);
+  } catch {
+    // The parser's message names a position in a text nobody sees; say what was expected instead.
+    return 'standard input is not a JSON bundle {"files":[{"name":"<slug>.md","text":"..."}]}; pass --name <slug>.md for one file';
   }
+  const parsed = stdinBundleSchema.safeParse(json);
+  if (!parsed.success) return `the bundle on standard input: ${parsed.error.issues.map((issue) => `${issue.path.join(".") || "bundle"}: ${issue.message}`).join("; ")}`;
+  if (parsed.data.history === undefined) return { files: parsed.data.files, history: undefined };
+  const history = parseArticleHistory(parsed.data.history);
+  if (!history.ok) return `the bundle on standard input: history.${history.errors.join("; history.")}`;
+  return { files: parsed.data.files, history: history.history };
 }
 
-function formatChange(change: PublishedChange): string {
-  const before = change.statusBefore === null || change.slugBefore === null ? "none" : `${change.statusBefore}/${change.slugBefore}`;
-  return `${change.action} ${change.id} ${before} -> ${change.statusAfter}/${change.slug}`;
+async function readProcessStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : (chunk as Buffer));
+  return Buffer.concat(chunks).toString("utf8");
 }
 
-function formatProblem(problem: PublishProblem): string {
-  return `${problem.subject}: ${problem.message}`;
+/** The `--history` file, parsed; or why it cannot be used. */
+async function readHistoryFile(path: string): Promise<ArticleHistoryMap | string> {
+  const text = await readText(path);
+  if (text === null) return `cannot read ${path}`;
+  let json: unknown;
+  try {
+    json = JSON.parse(text);
+  } catch (error) {
+    return `${path} is not JSON: ${describeError(error)}`;
+  }
+  const parsed = parseArticleHistory(json);
+  return parsed.ok ? parsed.history : `${path}: ${parsed.errors.join("; ")}`;
 }
 
 interface ReadArticleFile extends ArticleFile {
@@ -578,8 +608,10 @@ async function readText(path: string): Promise<string | null> {
   }
 }
 
-function openDatabase(url: string): Promise<DatabaseHandle> {
-  return createDatabase(url, { max: 1 });
+async function openDatabase(database: SoftureDatabaseConfig, open: ((url: string) => Promise<DatabaseHandle>) | undefined): Promise<CommandDatabase> {
+  if (open === undefined) return openCommandDatabase(database, { max: 1 });
+  const handle = await open(database.url);
+  return { handle, close: handle.close };
 }
 
 /** The driver's own message; drizzle's "Failed query: … params: …" wrapper is dropped. */

package/src/contract.ts

@@ -84,5 +84,13 @@ export type BlogPublishResult =
       readonly after: BlogArticleState;
       /** The slug that has just entered the slug history. */
       readonly previousSlug: string | null;
+      /** Set when the article's history (`publishArticle({ history })`) was applied. */
+      readonly imported?: true;
     }
-  | { readonly ok: false; readonly error: BlogSlugErrorCode; readonly otherArticleId: string };
+  | {
+      readonly ok: false;
+      readonly error: BlogSlugErrorCode;
+      readonly otherArticleId: string;
+      /** Set when the slug is an old slug from the article's history, not its current one. */
+      readonly slug?: string;
+    };

package/src/db/articles.ts

@@ -5,6 +5,7 @@ import type { ModuleContext } from "@softure-ai/core";
 import type { Queryable } from "@softure-ai/db";
 import { and, asc, desc, eq, ne, type SQL } from "drizzle-orm";
 import type { BlogArticle, BlogArticleInput, BlogArticleKind, BlogArticleState, BlogPublishResult } from "../contract.js";
+import type { ArticleHistory } from "./history.js";
 import { articles, slugHistory } from "./schema.js";
 
 export type BlogContext = ModuleContext<Queryable>;
@@ -18,10 +19,14 @@ export type BlogContext = ModuleContext<Queryable>;
  *   text first becomes `published`. A draft gets none.
  * - `updated_at` moves only when the content hash of a text that already has `published_at` changes.
  *
+ * With `history` (an app moving its blog in, see history.ts), an article that has no row yet takes its
+ * `published_at` (unless the file sets one) and `updated_at` from it, and its old slugs enter the slug
+ * history; the result says `imported: true`. For an existing row the history is ignored.
+ *
  * Runs in a transaction that locks the row (`FOR UPDATE`), so two publishes of one article never
  * overwrite each other silently; inside an open transaction it becomes a savepoint.
  */
-export async function publishArticle(ctx: BlogContext, input: BlogArticleInput): Promise<BlogPublishResult> {
+export async function publishArticle(ctx: BlogContext, input: BlogArticleInput, options: PublishArticleOptions = {}): Promise<BlogPublishResult> {
   return ctx.db.transaction(async (tx) => {
     const [existing] = await tx.select().from(articles).where(eq(articles.id, input.id)).for("update");
 
@@ -61,12 +66,25 @@ export async function publishArticle(ctx: BlogContext, input: BlogArticleInput):
     };
 
     if (existing === undefined) {
-      const publishedAt = input.publishedAt ?? (input.status === "published" ? now : null);
+      const history = options.history;
+      const publishedAt = input.publishedAt ?? history?.publishedAt ?? (input.status === "published" ? now : null);
+      const updatedAt = publishedAt === null ? null : (history?.updatedAt ?? null);
+      if (history !== undefined) {
+        const taken = await findTakenOldSlug(tx, input, history);
+        if (taken !== null) return taken;
+      }
       const [inserted] = await tx
         .insert(articles)
-        .values({ id: input.id, ...content, publishedAt, updatedAt: null, createdAt: now })
+        .values({ id: input.id, ...content, publishedAt, updatedAt, createdAt: now })
         .returning();
-      return { ok: true, action: "added", before: null, after: readState(requireRow(inserted, input.id)), previousSlug: null };
+      const oldSlugs = history?.oldSlugs.filter((old) => old.slug !== input.slug) ?? [];
+      if (oldSlugs.length > 0) {
+        await tx.insert(slugHistory).values(oldSlugs.map((old) => ({ oldSlug: old.slug, articleId: input.id, changedAt: old.changedAt ?? now })));
+      }
+      const after = readState(requireRow(inserted, input.id));
+      return history === undefined
+        ? { ok: true, action: "added", before: null, after, previousSlug: null }
+        : { ok: true, action: "added", before: null, after, previousSlug: null, imported: true };
     }
 
     const before = readState(existing);
@@ -103,6 +121,23 @@ export async function publishArticle(ctx: BlogContext, input: BlogArticleInput):
   });
 }
 
+export interface PublishArticleOptions {
+  /** The article's earlier life, applied only when it has no row yet. */
+  readonly history?: ArticleHistory;
+}
+
+/** The refusal for the first old slug of `history` another article holds, current or old; `null` when all are free. */
+async function findTakenOldSlug(db: Queryable, input: BlogArticleInput, history: ArticleHistory): Promise<Extract<BlogPublishResult, { ok: false }> | null> {
+  for (const { slug } of history.oldSlugs) {
+    if (slug === input.slug) continue;
+    const [owner] = await db.select({ id: articles.id }).from(articles).where(and(eq(articles.slug, slug), ne(articles.id, input.id)));
+    if (owner !== undefined) return { ok: false, error: "blog.slug_taken", otherArticleId: owner.id, slug };
+    const [historyOwner] = await db.select({ articleId: slugHistory.articleId }).from(slugHistory).where(eq(slugHistory.oldSlug, slug));
+    if (historyOwner !== undefined) return { ok: false, error: "blog.slug_in_history", otherArticleId: historyOwner.articleId, slug };
+  }
+  return null;
+}
+
 /** The article under its current slug, in any status: a page tells 200 from 410 by it. */
 export async function findArticleBySlug(ctx: BlogContext, slug: string): Promise<BlogArticle | null> {
   const [row] = await ctx.db.select().from(articles).where(eq(articles.slug, slug));

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.5",
+    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/next/context.ts

@@ -2,7 +2,7 @@
 // wall clock; and what it hands the components: the copy, paths, brand and disclaimer.
 import { systemClock, type SoftureConfig } from "@softure-ai/core";
 import { getSoftureConfig } from "@softure-ai/core/next";
-import { getSharedDatabase } from "@softure-ai/db";
+import { getConfiguredDatabase } from "@softure-ai/db";
 import type { BlogContext } from "../db/articles.js";
 import { getBlogMessages, getBlogOptions, getBlogRoutes } from "../server/options.js";
 import type { BlogPageContext } from "../ui/page-context.js";
@@ -12,7 +12,7 @@ export async function getBlogContext(config: SoftureConfig = getSoftureConfig())
     // Unreachable for a validated config: the module has a database schema.
     throw new Error("@softure-ai/blog: softure.config.ts has no database; the blog needs one");
   }
-  const { db } = await getSharedDatabase(config.database.url);
+  const { db } = await getConfiguredDatabase(config.database);
   return { db, clock: systemClock, config };
 }