@softure-ai/blog 0.1.6 → 0.1.8

package/dist/server/options.js

@@ -50,7 +50,7 @@ export function getQualitySettings(config) {
     const { quality, images } = getBlogOptions(config);
     if (quality === false)
         return null;
-    const site = { appOrigin: config.appOrigin, siteOrigin: getSiteUrls(config).origin, timezone: config.timezone };
+    const site = { appOrigin: config.appOrigin, siteOrigin: getSiteUrls(config).origin, timezone: config.timezone, routes: getBlogRoutes(config) };
     return resolveQualitySettings(quality, site, images ?? null);
 }
 //# sourceMappingURL=options.js.map

package/dist/server/options.js.map

@@ -1 +1 @@
-{"version":3,"file":"options.js","sourceRoot":"","sources":["../../src/server/options.ts"],"names":[],"mappings":"AAAA,qFAAqF;AACrF,OAAO,EAAE,SAAS,EAAE,WAAW,EAA6C,MAAM,kBAAkB,CAAC;AAGrG,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAmB,MAAM,mBAAmB,CAAC;AACtF,OAAO,EAAE,sBAAsB,EAAwB,MAAM,wBAAwB,CAAC;AAEtF,MAAM,SAAS,GAAG,MAAM,CAAC;AAEzB,sGAAsG;AACtG,SAAS,aAAa,CAAC,MAAqB;IAC1C,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAC5C,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,yFAAyF,CAAC,CAAC;IAC7G,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,MAAqB;IAClD,kEAAkE;IAClE,OAAO,aAAa,CAAC,MAAM,CAAC,CAAC,OAAsB,CAAC;AACtD,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,eAAe,CAAC,MAAqB;IACnD,+EAA+E;IAC/E,OAAO,aAAa,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAiB,CAAC;AACvE,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,aAAa,CAAC,MAAqB;IACjD,MAAM,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC;IAC5C,MAAM,IAAI,GAAG,CAAC,IAAsB,EAAU,EAAE;QAC9C,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;QAC1B,wFAAwF;QACxF,IAAI,IAAI,KAAK,SAAS;YAAE,MAAM,IAAI,KAAK,CAAC,4BAA4B,IAAI,uCAAuC,CAAC,CAAC;QACjH,OAAO,cAAc,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC,CAAC;IACF,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;AACxG,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,kBAAkB,CAAC,MAAqB;IACtD,MAAM,IAAI,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC;IAClD,sFAAsF;IACtF,IAAI,IAAI,KAAK,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,uEAAuE,CAAC,CAAC;IACjH,OAAO,cAAc,CAAC,IAAI,CAAC,CAAC;AAC9B,CAAC;AAED,uGAAuG;AACvG,MAAM,UAAU,oBAAoB,CAAC,MAAqB;IACxD,MAAM,OAAO,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;IACvC,OAAO,gBAAgB,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC;AAC1D,CAAC;AAED,kGAAkG;AAClG,MAAM,UAAU,kBAAkB,CAAC,MAAqB;IACtD,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;IACnD,IAAI,OAAO,KAAK,KAAK;QAAE,OAAO,IAAI,CAAC;IACnC,MAAM,IAAI,GAAG,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC;IAChH,OAAO,sBAAsB,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,IAAI,IAAI,CAAC,CAAC;AAC/D,CAAC"}
+{"version":3,"file":"options.js","sourceRoot":"","sources":["../../src/server/options.ts"],"names":[],"mappings":"AAAA,qFAAqF;AACrF,OAAO,EAAE,SAAS,EAAE,WAAW,EAA6C,MAAM,kBAAkB,CAAC;AAGrG,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAmB,MAAM,mBAAmB,CAAC;AACtF,OAAO,EAAE,sBAAsB,EAAwB,MAAM,wBAAwB,CAAC;AAEtF,MAAM,SAAS,GAAG,MAAM,CAAC;AAEzB,sGAAsG;AACtG,SAAS,aAAa,CAAC,MAAqB;IAC1C,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAC5C,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,yFAAyF,CAAC,CAAC;IAC7G,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,MAAqB;IAClD,kEAAkE;IAClE,OAAO,aAAa,CAAC,MAAM,CAAC,CAAC,OAAsB,CAAC;AACtD,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,eAAe,CAAC,MAAqB;IACnD,+EAA+E;IAC/E,OAAO,aAAa,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAiB,CAAC;AACvE,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,aAAa,CAAC,MAAqB;IACjD,MAAM,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC;IAC5C,MAAM,IAAI,GAAG,CAAC,IAAsB,EAAU,EAAE;QAC9C,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;QAC1B,wFAAwF;QACxF,IAAI,IAAI,KAAK,SAAS;YAAE,MAAM,IAAI,KAAK,CAAC,4BAA4B,IAAI,uCAAuC,CAAC,CAAC;QACjH,OAAO,cAAc,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC,CAAC;IACF,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;AACxG,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,kBAAkB,CAAC,MAAqB;IACtD,MAAM,IAAI,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC;IAClD,sFAAsF;IACtF,IAAI,IAAI,KAAK,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,uEAAuE,CAAC,CAAC;IACjH,OAAO,cAAc,CAAC,IAAI,CAAC,CAAC;AAC9B,CAAC;AAED,uGAAuG;AACvG,MAAM,UAAU,oBAAoB,CAAC,MAAqB;IACxD,MAAM,OAAO,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;IACvC,OAAO,gBAAgB,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC;AAC1D,CAAC;AAED,kGAAkG;AAClG,MAAM,UAAU,kBAAkB,CAAC,MAAqB;IACtD,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;IACnD,IAAI,OAAO,KAAK,KAAK;QAAE,OAAO,IAAI,CAAC;IACnC,MAAM,IAAI,GAAG,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC;IAC/I,OAAO,sBAAsB,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,IAAI,IAAI,CAAC,CAAC;AAC/D,CAAC"}

package/module.json

@@ -1,6 +1,6 @@
 {
   "id": "blog",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "dependsOn": { "seo": "^0.1.0?", "security": "^0.1.0?" },
   "dbSchema": "blog",
   "tables": ["articles", "slug_history"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softure-ai/blog",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "SOFTURE AI blog module: articles and glossary terms kept as Markdown files with a strict YAML frontmatter (extendable by the app's own fields), stored in the module's Postgres schema by the softure-blog publish command (dry run by default, all or nothing, content hash, slug history, one pillar per cluster), a server-side Markdown renderer (no raw HTML, safe links, glossary links, block plugins), a text quality gate (softure-blog check, run before every publish) with language rulesets and rule plugins, the blog's pages ready to mount in Next.js (listing, article, glossary, method page, OG image, JSON-LD) with a proxy piece for 301 and 410, an article writing skill (softure-blog skill install) generated from the gate's rules, and discovery: an RSS feed, read next, sitemap entries and an IndexNow submit on publish through the optional @softure-ai/seo, with a rate-limited cache refresh route the publish calls first (through the optional @softure-ai/security).",
   "license": "MIT",
   "type": "module",

package/skill/references/rules.md

@@ -31,7 +31,8 @@ rewrite the paragraph around its one thought; do not swap a word for a synonym.
 | `length` | | | An article of {{articleWordsMin}} to {{articleWordsMax}} words, a term of {{termWordsMin}} to {{termWordsMax}}. |
 | `footnote-undefined` | | | Define every `[^id]` at the end of the file. |
 | `footnote-unused` | | | Remove a footnote definition nothing refers to, or refer to it. |
-| `block-requires` | | | A fenced block of the app's block plugins needs its frontmatter keys; add them. |
+| `block-requires` | | | A block of the app's block plugins (a fence or a `::directive`) needs its frontmatter keys; add them. |
+| `block-directive` | | | A `::directive` line names a directive the blog renders and writes its attributes as `key="value"` pairs, each key once. |
 
 ## Links
 

package/src/cli/report.ts

@@ -0,0 +1,182 @@
+// How `softure-blog publish` prints its result: for a person (the default) or as a line contract a
+// release script parses (`--format lines`). Both get the same events; only the wording differs.
+//
+// The line contract: every line starts `blog|`, fields are separated by `|`, and a `|` or a line break
+// inside a value becomes a space. Keys are stable English words; a new key may be added, an existing
+// one never changes meaning. A run prints exactly one outcome line: `blog|written`, `blog|dry-run`,
+// `blog|refused` or `blog|failed|<message>`.
+//
+//   blog|warning|<subject>|<message>
+//   blog|error|<subject>|<message>                    (before blog|refused)
+//   blog|change|<added|changed|unchanged>|<id>|<status/slug before or none>|<status/slug after>
+//   blog|moved|<id>|<old slug>|<new slug>
+//   blog|imported|<id>|<published_at ISO or none>|<old slugs>
+//   blog|summary|<added>|<changed>|<unchanged>
+//   blog|cache|<off|skipped|dry-run|refreshed|failed>|…
+//   blog|indexnow|<off|skipped|dry-run|submitted|failed>|…
+import type { BlogRefreshOutcome } from "../discovery/refresh.js";
+import { BLOG_REFRESH_SECRET_ENV } from "../discovery/refresh.js";
+import type { BlogIndexNowSubmit } from "../discovery/submit.js";
+import type { BlogPublishRun, PublishedChange, PublishProblem } from "../db/publish-run.js";
+
+export interface CliOutput {
+  readonly log: (line: string) => void;
+  readonly error: (line: string) => void;
+}
+
+export type PublishFormat = "text" | "lines";
+
+export interface PublishReporter {
+  /** A problem before or outside the run (a file it cannot read, the database); the run's outcome. */
+  readonly failed: (message: string) => void;
+  readonly run: (run: BlogPublishRun) => void;
+  readonly refresh: (outcome: BlogRefreshOutcome) => void;
+  readonly indexNow: (submit: BlogIndexNowSubmit) => void;
+}
+
+export function createPublishReporter(format: PublishFormat, output: CliOutput): PublishReporter {
+  return format === "lines" ? createLineReporter(output) : createTextReporter(output);
+}
+
+function countActions(run: Extract<BlogPublishRun, { status: "done" }>): Record<PublishedChange["action"], number> {
+  const count = (action: PublishedChange["action"]) => run.changes.filter((change) => change.action === action).length;
+  return { added: count("added"), changed: count("changed"), unchanged: count("unchanged") };
+}
+
+function formatBefore(change: PublishedChange): string {
+  return change.statusBefore === null || change.slugBefore === null ? "none" : `${change.statusBefore}/${change.slugBefore}`;
+}
+
+function formatDate(date: Date | null): string {
+  return date === null ? "none" : date.toISOString();
+}
+
+function createTextReporter(output: CliOutput): PublishReporter {
+  const formatProblem = (problem: PublishProblem) => `${problem.subject}: ${problem.message}`;
+  return {
+    failed: (message) => output.error(`softure-blog publish: ${message}`),
+    run: (run) => {
+      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;
+      }
+      for (const change of run.changes) {
+        output.log(`${change.action} ${change.id} ${formatBefore(change)} -> ${change.statusAfter}/${change.slug}`);
+        if (change.previousSlug !== null) output.log(`moved ${change.id} ${change.previousSlug} -> ${change.slug}`);
+        if (change.imported !== undefined) {
+          output.log(`imported ${change.id} published_at=${formatDate(change.imported.publishedAt)} old_slugs=${String(change.imported.oldSlugs)}`);
+        }
+      }
+      const counts = countActions(run);
+      output.log(`summary: added ${String(counts.added)}, changed ${String(counts.changed)}, unchanged ${String(counts.unchanged)}`);
+      output.log(run.committed ? "written" : "dry run: nothing written; pass --commit to write");
+    },
+    refresh: (outcome) => {
+      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;
+      }
+    },
+    indexNow: ({ paths, outcome }) => {
+      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;
+      }
+    },
+  };
+}
+
+/** A value inside a contract line: no field separator, no line break. */
+function toField(value: string | number): string {
+  return String(value).replace(/[|\r\n]+/g, " ");
+}
+
+function createLineReporter(output: CliOutput): PublishReporter {
+  // Every contract line goes to standard output, so `2>&1` is not needed to read them.
+  const line = (...fields: readonly (string | number)[]) => output.log(["blog", ...fields.map(toField)].join("|"));
+  return {
+    failed: (message) => line("failed", message),
+    run: (run) => {
+      for (const warning of run.warnings) line("warning", warning.subject, warning.message);
+      if (run.status === "refused") {
+        for (const problem of run.problems) line("error", problem.subject, problem.message);
+        line("refused");
+        return;
+      }
+      for (const change of run.changes) {
+        line("change", change.action, change.id, formatBefore(change), `${change.statusAfter}/${change.slug}`);
+        if (change.previousSlug !== null) line("moved", change.id, change.previousSlug, change.slug);
+        if (change.imported !== undefined) line("imported", change.id, formatDate(change.imported.publishedAt), change.imported.oldSlugs);
+      }
+      const counts = countActions(run);
+      line("summary", counts.added, counts.changed, counts.unchanged);
+      line(run.committed ? "written" : "dry-run");
+    },
+    refresh: (outcome) => {
+      switch (outcome.kind) {
+        case "not_configured":
+          line("cache", "off", outcome.revalidateSeconds);
+          return;
+        case "skipped":
+          line("cache", "skipped");
+          return;
+        case "dry_run":
+          line("cache", "dry-run", outcome.url);
+          return;
+        case "refreshed":
+          line("cache", "refreshed", outcome.url);
+          return;
+        case "failed":
+          line("cache", "failed", outcome.code, outcome.reason);
+          return;
+      }
+    },
+    indexNow: ({ paths, outcome }) => {
+      switch (outcome.kind) {
+        case "not_configured":
+          line("indexnow", "off", outcome.reason);
+          return;
+        case "skipped":
+          line("indexnow", "skipped");
+          return;
+        case "dry_run":
+          line("indexnow", "dry-run", outcome.urls.length, outcome.urls.join(" "));
+          return;
+        case "submitted":
+          line("indexnow", "submitted", outcome.count, outcome.status, paths.join(" "));
+          return;
+        case "failed":
+          line("indexnow", "failed", outcome.code, outcome.reason, paths.join(" "));
+          return;
+      }
+    },
+  };
+}

package/src/cli/run.ts

@@ -11,9 +11,11 @@ import { basename, dirname, join, relative, resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { systemClock, type Clock, type SoftureConfig, type SoftureDatabaseConfig } from "@softure-ai/core";
 import { openCommandDatabase, type CommandDatabase, 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 { 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. */
@@ -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;
@@ -275,8 +312,7 @@ async function runPublish(command: Extract<BlogCommand, { kind: "publish" }>, op
   try {
     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(
@@ -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,16 +336,15 @@ 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 opened.close();
   }
@@ -353,7 +389,7 @@ async function runCheck(command: Extract<BlogCommand, { kind: "check" }>, option
   const resolveInternalLink = createInternalLinkResolver({
     appDir: findAppDir(cwd, settings.options.appDir),
     privateRouteSegments: settings.options.privateRouteSegments,
-    paths: settings.options.paths,
+    paths: settings.paths,
     content,
   });
   const results = await checkArticleFiles(files, {
@@ -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 {

package/src/cli/skill.ts

@@ -69,7 +69,8 @@ export function renderAppSections(sections: readonly BlogSkillSection[]): string
 /** The values the templates read. */
 export function getSkillValues(config: SoftureConfig, settings: QualitySettings, options: RenderBlogSkillOptions = {}): SkillValues {
   const blogOptions = getBlogOptions(config);
-  const { limits, ymyl, voice, paths, plugins } = settings.options;
+  const { limits, ymyl, voice, plugins } = settings.options;
+  const { paths } = settings;
   const fieldKeys = Object.keys(blogOptions.fields?.shape ?? {});
   const reservedSlugs = getBlogReservedSlugs(config);
   return {

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;
+    };