@softure-ai/blog 0.1.6 → 0.1.8

package/CHANGELOG.md

@@ -4,6 +4,36 @@ Newest first. Each version lists what changed for an app that uses `@softure-ai/
 production, the version gets a line `verified in: <app>@<commit>` ([docs/05](../../docs/05-adoption-playbook.md),
 "Definition of done"). Versions before the first one below are described in their GitHub Releases (`blog@x.y.z`).
 
+## 0.1.8
+
+- `externalLinkMarker` (`blog({ ... })`) and `renderArticle({ externalMarker })`: `"icon-and-text"`
+  (default, as before), `"text"` (the visually hidden "opens in a new tab" only) or `"none"`. External
+  links keep `target`, `rel` and the `blog-external` class either way.
+- The quality gate takes the paths of articles and terms from the blog's `routes`; `quality.paths`
+  (each key optional now) only overrides them. `QualitySettings.paths` holds the resolved pair;
+  `QualityOptions.paths` is the override alone.
+- `/next` exports `buildArticleMetadata`, `buildTermMetadata`, `buildBlogIndexMetadata`,
+  `buildGlossaryIndexMetadata`, `buildMethodMetadata`, `buildArticleJsonLd`, `buildTermJsonLd`,
+  `buildGlossaryJsonLd` and `getCrumbLabels`: the ready-made pages' metadata and JSON-LD for an app
+  with its own page components, without a database read.
+- `gonePage` (`blog({ ... })`): `links` add further ways on to the 410 page, `render` writes its whole
+  body. `buildGonePage` takes `links`.
+- An imported history keeps its timestamps to the microsecond. Breaking for code that builds an
+  `ArticleHistory` by hand: its timestamps are ISO strings now, not `Date` (`parseArticleHistory`
+  callers see no change).
+
+## 0.1.7
+
+- Block plugins with `syntax: "directive"` render top-level `::name{key="value"}` lines with parsed
+  `attributes`; the quality gate checks their `requires` and reports an unknown directive or unreadable
+  attributes (`block-directive`). `ArticleBlock` and `FoundBlock` carry `syntax` and `attributes`.
+- `createBlogMarkdown` (`/proxy`) answers an article or term asked for with `Accept: text/markdown` with
+  `toArticleMarkdown`; a block plugin may give its Markdown form (`markdown`).
+- `softure-blog publish --stdin` reads one file (`--name`) or a JSON bundle (files and an optional
+  history) from standard input; `--format lines` prints a stable `blog|<key>|…` contract.
+- `publish --history <file.json>` (and `runBlogPublish({ history })`) imports `published_at`, `updated_at`
+  and old slugs on the first publish of each article, for an app moving its existing blog in.
+
 ## 0.1.6
 
 - Adapters and commands use the configured database handle.

package/README.md

@@ -11,12 +11,15 @@ editor and no CMS, a text changes only through a commit and `softure-blog publis
 - `blog.articles` and `blog.slug_history` with database constraints for every invariant that fits one.
 - `softure-blog publish`: a dry run by default; with `--commit`, all files or none; unchanged files are
   skipped by their content hash; a slug change keeps the old slug as a redirect; one pillar per cluster.
+  Files from paths or from standard input (`--stdin`, for a release through an ssh pipe), a line
+  contract for scripts (`--format lines`), and the dates and old slugs of an existing blog imported on
+  the first publish (`--history`).
 - Read functions for the pages: `getPublishedArticle`, `findArticleBySlug`, `findSlugRedirect`,
   `listArticles`.
 - `renderArticle(markdown, options)`: the body as safe HTML on the server (no raw HTML, safe link
   schemes only, marked external links, images under the app's image policy), heading ids and an
   optional table of contents, glossary links on the first mention of a term, block plugins for the
-  app's own fenced blocks, reading time.
+  app's own fenced blocks and `::directive{…}` lines, reading time.
 - Pages, each mounted with one re-export line (`@softure-ai/blog/next`): the listing grouped by cluster
   with the pillar first, an article (dates, summary, contents, FAQ, sources, signature, disclaimer,
   `BlogPosting`/`BreadcrumbList`/`FAQPage` JSON-LD), the glossary index and a term page (`DefinedTerm`,
@@ -24,7 +27,8 @@ editor and no CMS, a text changes only through a commit and `softure-blog publis
   Their canonical, Open Graph, JSON-LD and feed URLs follow `@softure-ai/seo`'s origin, host and
   trailing-slash rule when the app lists `seo()` (core's `getSiteUrls`), and `appOrigin` otherwise.
 - `createBlogRedirects` (`@softure-ai/blog/proxy`): 301 from an old slug, 410 for a withdrawn text,
-  in the app's `proxy.ts`.
+  in the app's `proxy.ts`; `createBlogMarkdown` answers an article or term asked for with
+  `Accept: text/markdown` with its Markdown (`toArticleMarkdown`), for agents.
 - `@softure-ai/blog/styles.css`: the pages and the rendered body on the `--sft-*` tokens.
 - Discovery: an RSS 2.0 feed (`serveBlogRss`), "read next" under every article (its cluster first, the
   pillar on top), and, with `@softure-ai/seo` (optional): sitemap entries with each text's real
@@ -69,7 +73,7 @@ blog({
   fields: z.object({ scenario: z.string().regex(/^[a-z]=\d+(&[a-z]=\d+)*$/).optional() }),
   // The pages' brand: title suffix, signature, JSON-LD author and publisher, OG card colours (hex)
   // and fonts (§8). Default: none (no suffix, no author, the ui theme's dark colours, next/og's font).
-  brand: { name: "FIRE Tracker", colors: { background: "#0b0b0c", foreground: "#f5f5f5", accent: "#7aa2f7" } },
+  brand: { name: "Example", colors: { background: "#0b0b0c", foreground: "#f5f5f5", accent: "#7aa2f7" } },
   // Mount the method page at routes.method. Default: false (the route answers 404).
   methodPage: true,
   // A note under every article and term, per locale (en required). Default: none.
@@ -80,6 +84,11 @@ blog({
   blocks: [],
   // Hosts of the app besides APP_ORIGIN's and seo's canonical host, whose links are not external. Default: [].
   siteHosts: ["www.example.com"],
+  // What follows an external link in a body: "icon-and-text" (a ↗ hidden from screen readers and a
+  // visually hidden "opens in a new tab"), "text" (the hidden words only) or "none". Default: "icon-and-text".
+  externalLinkMarker: "icon-and-text",
+  // The 410 page of a withdrawn text: extra links, or the app's own body (§4). Default: one link to the listing.
+  gonePage: { links: [] },
   // Which images bodies may show: site paths and https images on these hosts (subdomains included),
   // with a width and height the app knows. Used by the pages and the quality gate. Default: none
   // (every image renders as its alt text and the gate refuses it).
@@ -112,9 +121,9 @@ blog({
       // a global RegExp; wordPattern (from @softure-ai/blog) adds the i flag and word edges in any alphabet
       phrases: [{ id: "finance-cliche", pattern: wordPattern("in the world of finance"), message: "say what happens instead" }],
     },
-    limits: { words: { article: { min: 600, max: 4000 } }, answerWords: 70 }, // FIRE's values are the defaults
+    limits: { words: { article: { min: 600, max: 4000 } }, answerWords: 70 }, // the defaults
     severity: { exclamation: "error", "lead-number": "off" }, // per rule: "error", "warning" or "off"
-    paths: { articles: "/blog", terms: "/blog/glossary" },    // where internal links to texts point
+    paths: { terms: "/glossary" },  // only to override the routes: articles default to routes.index, terms to routes.glossary
     ownOrigins: ["https://www.example.com"], // absolute links that count as internal, besides appOrigin and seo's origin
     appDir: "src/app",                     // routes for internal links; default src/app, else app
     privateRouteSegments: ["api", "(app)"], // route folders that are no link target; default ["api"]
@@ -274,13 +283,65 @@ decision for 60 s (`ttlMs`) and passes a request on when the database fails. Imp
 ui's: `@import "@softure-ai/blog/styles.css";`. A data change shows after `revalidateSeconds`, or at
 once with `revalidateTag(BLOG_CACHE_TAG, { expire: 0 })` (the refresh route above, for the command). Custom OG fonts: an own `opengraph-image.tsx` calling `renderArticleOgImage({ title, label, brand, fonts })`.
 
-The quality gate resolves internal links through `quality.paths` (default `/blog` and
-`/blog/glossary`, the default routes); an app that moves `routes` sets `quality.paths` to match.
+The quality gate resolves internal links under the blog's `routes` (`index` for articles, `glossary`
+for terms), so moving a route moves the check with it; `quality.paths` only overrides them.
+
+The 410 page carries the module's copy (`gone.*`) and one link to the listing. `gonePage.links` adds
+further ways on (a path from the site root or an https URL, a label per locale, at most five), and
+`gonePage.render` writes the whole body with the app's own HTML and styles; the proxy still answers 410
+with `text/html`:
+
+```ts
+blog({
+  gonePage: {
+    links: [{ href: "/calculator", label: { en: "Try the calculator", pl: pl.blog.goneCalculator } }],
+    // or the whole page: (input) => html, with input.copy, input.lang, input.indexPath, input.links
+    render: ({ copy, lang, indexPath, links }) => renderMyGonePage({ copy, lang, indexPath, links }),
+  },
+});
+```
+
+**Own page components.** An app whose blog keeps its own look mounts its own pages and keeps the rest.
+`generate*Metadata`, `generateBlogStaticParams` and `BlogArticleOgImage` mount next to its own page as
+above. For a text the app already read (`getTextBySlug`), `/next` builds the same metadata and JSON-LD
+the ready-made pages use, with no database read, so the app can extend them:
+
+```tsx
+// app/blog/[slug]/page.tsx with the app's own view
+import { buildArticleJsonLd, buildArticleMetadata, getTextBySlug } from "@softure-ai/blog/next";
+import { getSoftureConfig } from "@softure-ai/core/next";
+import { notFound } from "next/navigation";
+
+export async function generateMetadata({ params }: { params: Promise<{ slug: string }> }) {
+  const config = getSoftureConfig();
+  const article = await getTextBySlug(config, (await params).slug);
+  return article?.status === "published" && article.kind === "article" ? buildArticleMetadata(config, article) : {};
+}
+
+export default async function Page({ params }: { params: Promise<{ slug: string }> }) {
+  const config = getSoftureConfig();
+  const article = await getTextBySlug(config, (await params).slug);
+  if (article?.status !== "published" || article.kind !== "article") notFound();
+  return (
+    <MyArticleView article={article}>
+      <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: buildArticleJsonLd(config, article) }} />
+    </MyArticleView>
+  );
+}
+```
+
+The builders: `buildBlogIndexMetadata(config, { isEmpty })`, `buildArticleMetadata(config, article)`,
+`buildGlossaryIndexMetadata(config, { isEmpty })`, `buildTermMetadata(config, term)`,
+`buildMethodMetadata(config)`, `buildArticleJsonLd(config, article)`, `buildTermJsonLd(config, term)` and
+`buildGlossaryJsonLd(config, terms)` (`null` without terms); the JSON-LD comes serialized, safe inside a
+`<script>`. `getCrumbLabels(config)` gives the breadcrumb names for `getArticleCrumbs`/`getTermCrumbs`
+(`/server`); `getPageContext`, `renderPageBody` and `getRelatedArticles` render the rest.
 
 The commands:
 
 ```bash
-softure-blog publish [<path>...] [--commit] [--withdraw] [--no-indexnow] [--app-url <origin>] [--config <file>]
+softure-blog publish [<path>...] [--commit] [--withdraw] [--no-indexnow] [--app-url <origin>]
+                     [--stdin [--name <slug>.md]] [--history <file.json>] [--format text|lines] [--config <file>]
 softure-blog check [<path>...] [--external] [--today <YYYY-MM-DD>] [--config <file>]
 softure-blog skill install [--dir <path>] [--command <cmd>] [--check] [--config <file>]
 ```
@@ -300,6 +361,13 @@ softure-blog skill install [--dir <path>] [--command <cmd>] [--check] [--config
   listing or the glossary of its kind) as canonical URLs on seo's origin; a dry run prints them;
   `--no-indexnow` skips the submit (e.g. a local or CI database). A failed submit is a warning: the
   publish stays written and the exit code stays 0.
+- `--stdin` reads the files from standard input instead of paths: with `--name <slug>.md`, the one file's
+  text; without it, a JSON bundle `{"files":[{"name":"<slug>.md","text":"…"}]}` (a whole folder, and
+  optionally `"history"`, the content of a `--history` file, so a container needs no file for it). A
+  release that publishes inside a container through an ssh gateway pipes the content in, so the image
+  needs no copy of `content/`. `--stdin` takes no paths; `--withdraw` with it needs `--name`.
+- `--history <file.json>` imports the earlier life of an existing blog (see "Moving an existing blog in").
+- `--format lines` prints the line contract below instead of the text for people.
 - Exit codes: 0 done, 1 refused or failed (nothing written), 2 usage error.
 
 Output, one line per text, then a summary:
@@ -312,6 +380,73 @@ summary: added 1, changed 1, unchanged 12
 dry run: nothing written; pass --commit to write
 ```
 
+**The line contract** (`--format lines`), for a release script that greps the output. Every line goes to
+standard output and starts `blog|`; fields are separated by `|`, and a `|` or a line break inside a value
+becomes a space. Keys are stable: a new one 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>`.
+
+```text
+blog|warning|<subject>|<message>
+blog|error|<subject>|<message>
+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|written
+blog|cache|off|<revalidateSeconds>         | skipped | dry-run|<url> | refreshed|<url> | failed|<code>|<reason>
+blog|indexnow|off|<reason>                 | skipped | dry-run|<count>|<urls> | submitted|<count>|<status>|<paths> | failed|<code>|<reason>|<paths>
+```
+
+```bash
+# A release step: the content goes in on stdin, the contract comes back.
+node -e 'const fs = require("fs"); const dir = "content/blog";
+  const files = fs.readdirSync(dir).filter((n) => n.endsWith(".md") && n !== "README.md").sort()
+    .map((name) => ({ name, text: fs.readFileSync(`${dir}/${name}`, "utf8") }));
+  process.stdout.write(JSON.stringify({ files }))' > bundle.json
+OUT="$(ssh deploy@host 'docker compose exec -T app node blog.cjs publish --stdin --commit --format lines' < bundle.json)"
+grep -q '^blog|written$' <<< "$OUT" || { grep '^blog|\(error\|failed\)' <<< "$OUT"; exit 1; }
+```
+
+**Moving an existing blog in.** An app that already published its texts from its own tables keeps their
+`published_at` (often only in its database, not in the files), their `updated_at` and their old slugs
+with `--history <file.json>`. On the first publish of each article (no row in `blog.articles` yet), the
+article takes `published_at` from the history unless its file sets one, `updated_at` from the history,
+and its old slugs enter `blog.slug_history` (301s keep working); the run prints `imported` for it. An
+article that already has a row ignores its entry, so the same file can stay in a release script; an
+entry for an article outside the run is a warning. An old slug another article holds refuses the run.
+
+```json
+{
+  "articles": [
+    {
+      "id": "index-funds",
+      "published_at": "2026-03-01T08:00:00+01:00",
+      "updated_at": "2026-06-15T10:30:00Z",
+      "old_slugs": [{ "slug": "what-is-an-index-fund", "changed_at": "2026-04-01T00:00:00Z" }]
+    },
+    { "id": "draft-text", "published_at": null }
+  ]
+}
+```
+
+`published_at` is required (`null` for a text never published), `updated_at` needs it, ids and slugs are
+kebab-case, each article and old slug appears once. Timestamps reach Postgres as the text given, so a
+`timestamptz` copied to the microsecond (`…:12.421579Z`) is stored to the microsecond and an import can be
+checked by equality in SQL; Postgres rounds digits past the sixth. One query over
+an app's own tables (here `blog_articles(id, published_at, updated_at)` and
+`blog_slug_history(old_slug, article_id, changed_at)`) writes the file:
+
+```sql
+\copy (SELECT json_build_object('articles', coalesce(json_agg(json_build_object(
+  'id', a.id, 'published_at', a.published_at, 'updated_at', a.updated_at,
+  'old_slugs', coalesce((SELECT json_agg(json_build_object('slug', h.old_slug, 'changed_at', h.changed_at))
+                         FROM blog_slug_history h WHERE h.article_id = a.id), '[]'::json))), '[]'::json))
+  FROM blog_articles a) TO 'history.json'
+```
+
+`publishArticle(ctx, input, { history })` and `runBlogPublish(ctx, files, { history })` (with
+`parseArticleHistory(json)`) are the same import without the command line.
+
 Like `softure migrate`, the bin loads `softure.config.(ts|mts|js|mjs)` with Node and opens
 `database.handle` when the config sets one, otherwise `database.url`. When Node cannot load the config (path aliases, a bundled container), call
 `runBlogCli` from an app script:
@@ -432,7 +567,9 @@ const body = renderArticle(article.bodyMarkdown, {
   `%20`). A throwing `dimensions` fails the render (a bug); the gate reports it as `image-dimensions`.
   `checkArticleImage` and `findArticleImages` give the same verdict and the images of a text.
 - **External links** (`http(s)` or `//` to a host outside `siteHosts`) get `rel="noopener noreferrer"`,
-  `target="_blank"`, a `↗` marker hidden from screen readers and a visually hidden "(opens in a new tab)".
+  `target="_blank"`, the class `blog-external`, a `↗` marker hidden from screen readers and a visually
+  hidden "(opens in a new tab)". `externalMarker: "text"` keeps only the hidden words, `"none"` neither
+  (the pages: `blog({ externalLinkMarker })`).
 - **Headings** get ids from their text (letters folded to ASCII, `-2` for a repeat, `section` without
   letters); `toc` renders `<nav class="blog-toc">` with nested lists.
 - **Glossary:** the first mention of each term form links to its definition; never inside headings,
@@ -459,9 +596,56 @@ const chartBlock: BlockPlugin = {
 
 Plugin output is the app's own code and is trusted as is: escape what goes into its HTML. A plugin
 that throws fails the render (a bug, not content). Without the plugin the same fence renders as a code
-block. `findArticleBlocks(markdown, plugins)` lists the blocks a text uses with their line and
-`requires`, without rendering. When any block returns a node, `html` is `null`: render `segments` in
-order (`html` segments as HTML, `node` segments as they are).
+block. `findArticleBlocks(markdown, plugins)` lists the blocks a text uses with their line, syntax,
+attributes and `requires`, without rendering. When any block returns a node, `html` is `null`: render
+`segments` in order (`html` segments as HTML, `node` segments as they are).
+
+**Directive plugins.** A plugin with `syntax: "directive"` renders a top-level line `::name{…}` instead
+of a fence, the way many Markdown blogs embed a chart or a tool:
+
+```md
+Paragraph before.
+::chart{type="wealth" scenario="w=35&d=300000" title="Your wealth"}
+```
+
+```ts
+const chartDirective: BlockPlugin = {
+  type: "chart",
+  syntax: "directive",
+  requires: ["current_as_of"],
+  render: ({ attributes, article }) =>
+    attributes === null
+      ? { kind: "html", html: '<figure class="chart-error">…</figure>' }
+      : { kind: "html", html: renderChart(attributes, article) },
+  markdown: ({ attributes }) => chartAsTable(attributes), // optional, for Accept: text/markdown
+};
+```
+
+- The line stands alone (it may follow a paragraph line directly); the braces are optional; values are
+  double-quoted and hold no `"`; each key appears once. `attributes` holds them, `info` the raw text
+  inside the braces, `content` the whole line. Attributes that cannot be read reach the plugin as `null`
+  (show an error frame) and the gate refuses them.
+- Only top-level lines count: a directive in a list, a quote, a fence or indented code stays text, and
+  so does a name no directive plugin registers. One type may have a fence plugin and a directive plugin.
+- Register the same plugins in `quality.blocks`: the gate reports a directive's missing `requires`, and
+  with any directive plugin registered `block-directive` reports a `::name` line no plugin renders (a
+  typo would show as a paragraph) or one whose attributes cannot be read.
+- `parseDirectiveLine` and `parseDirectiveAttributes` (`@softure-ai/blog/server`) are the parser.
+
+**Markdown for agents.** `createBlogMarkdown(config)` (`@softure-ai/blog/proxy`) answers a GET or HEAD
+of a published article or term whose `Accept` names `text/markdown` with at least the weight of
+`text/html` (never `*/*`: browsers and crawlers keep the page) with `toArticleMarkdown(article)`: the
+title, description, the day the facts were checked, the summary, the stored body, sources and FAQ.
+Plugin blocks keep their source unless the plugin has `markdown`. The answer carries `Vary: Accept` and
+`cache-control: private`, so a shared cache never hands Markdown to a browser. Put it before the redirects:
+
+```ts
+const blogMarkdown = createBlogMarkdown(softureConfig);
+const blogRedirects = createBlogRedirects(softureConfig);
+export async function proxy(request: NextRequest) {
+  return (await blogMarkdown(request)) ?? (await blogRedirects(request)) ?? NextResponse.next();
+}
+```
 
 ## 5. Migrations and tables
 
@@ -506,7 +690,7 @@ The OG card writes in `brand.fonts`, else in `next/og`'s default font:
 ```ts
 blog({
   brand: {
-    name: "FIRE Tracker",
+    name: "Example",
     fonts: [
       // weight: 100…900 (default 400), style: "normal" | "italic" (default "normal")
       { name: "Inter", weight: 400, src: "assets/fonts/inter-latin-400-normal.woff" },
@@ -541,7 +725,7 @@ with `blog({ messages: { pl: { pages: { readMore: "..." } } } })`. Command outpu
 
 ## 10. Hooks
 
-- `blog({ fields })`: the app's frontmatter schema (FIRE_TRACKER's calculator scenario lives here).
+- `blog({ fields })`: the app's frontmatter schema (e.g. a calculator scenario per article).
 - `gate` of `runBlogPublish` and `runBlogCli`: `(file, article) => problems`, called only for files
   going public; any problem refuses the whole run. Default in `runBlogCli`: `createQualityGate`.
 - `blog({ quality: { plugins } })`: the app's domain rules. A plugin declares its rules and checks one
@@ -567,8 +751,8 @@ export const tickerPlugin: QualityPlugin = {
   plugins in `quality.blocks` (type, info, fence line, `requires`), `today` and the language `ruleset` (for
   its number notation); the text helpers (`toProse`, `splitSentences`, `findSignificantNumbers`, …) are
   exported from `@softure-ai/blog/server`.
-- `renderArticle({ blocks })` and `blog({ blocks })`: block plugins for the app's fenced blocks
-  (FIRE_TRACKER's engine chart).
+- `renderArticle({ blocks })` and `blog({ blocks })`: block plugins for the app's fenced blocks and
+  `::directive` lines (an engine chart), with an optional Markdown form for agents.
 - The pages' `cta` and `afterArticle` slots: the app's call to action and blocks (a waitlist form).
 
 ## 11. GDPR
@@ -580,23 +764,24 @@ Articles hold editorial content, no personal data: nothing to export or delete.
 - Two runs that rename one article away from a slug and give it to another at the same moment can leave the
   slug both current and in the slug history (BF-12).
 - The content hash is part of the contract: a field added later enters it only when present.
-- No `--stdin` (a deploy transport).
 - The refresh route expires the cache of the instance that answers it. With several instances and Next's
   default (in-memory) cache handler, the others show a publish after `revalidateSeconds`; a shared cache
   handler covers them.
 - The renderer has no raw HTML and no figures: an image has no caption, and the app hosts and sizes its
   images itself (no `next/image`). A plugin fence inside a list or a quote stays a code
-  block (a block node cannot sit inside a list's HTML).
+  block (a block node cannot sit inside a list's HTML), and a `::directive` there stays text; the gate
+  does not report a registered directive in such a place.
+- Only leaf directives (`::name{…}`, one line): no container (`:::name … :::`) or inline (`:name[…]`) ones.
 - The gate reads Markdown line by line (blocks, not a syntax tree): enough for the rules, not a
   renderer. Fenced code and HTML comments are skipped.
-- **Adopting FIRE_TRACKER's gate:** `language: "pl"`, `ymyl: { ownCalculationMark }` with its calculation
-  footnote's phrase, `voice.forbidFirstPersonSingular: true` plus its finance phrases, its domain as
-  `ownOrigins`, `privateRouteSegments: ["api", "(app)"]`, and `rules-facts.ts` and `rules-chart.ts`
-  as plugins (the package's tests hold stand-ins of both). Rule ids are English now (`kluczowy` →
-  `crucial`, `myslniki` → `dashes`, …; the map is in the change archive), and the writing skill
-  (`skill install`, replacing FIRE's `blog-pisz`) names them; FIRE's engine numbers, calculator scenario
-  and chart block go into `blog({ skill: { sections } })`.
-- **Adopting from FIRE_TRACKER:** rename the frontmatter keys once (`typ` → `kind` with `artykul` →
+- **Adopting an app's own Polish gate:** `language: "pl"`, `ymyl: { ownCalculationMark }` with its calculation
+  footnote's phrase, `voice.forbidFirstPersonSingular: true` plus its own phrases, its domain as
+  `ownOrigins`, `privateRouteSegments: ["api", "(app)"]`, and its own fact and chart rules as plugins
+  (the package's tests hold stand-ins of both). Rule ids are English (`kluczowy` → `crucial`,
+  `myslniki` → `dashes`, …; the map is in the change archive), and the writing skill (`skill install`,
+  replacing an app's own writing skill) names them; the app's own numbers, calculator scenario and chart
+  block go into `blog({ skill: { sections } })`.
+- **Adopting Polish frontmatter keys:** rename the frontmatter keys once (`typ` → `kind` with `artykul` →
   `article` and `termin` → `term`, `formy` → `forms`, `klaster` → `cluster`, `filar` → `pillar`,
   `tytul` → `title`, `opis` → `description`, `w_skrocie` → `summary`, `aktualne_na` →
   `current_as_of`, `opublikowano` → `published_at`, `zrodla` → `sources` with `nazwa` → `name`,

package/dist/cli/report.d.ts

@@ -0,0 +1,17 @@
+import type { BlogRefreshOutcome } from "../discovery/refresh.js";
+import type { BlogIndexNowSubmit } from "../discovery/submit.js";
+import type { BlogPublishRun } 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 declare function createPublishReporter(format: PublishFormat, output: CliOutput): PublishReporter;
+//# sourceMappingURL=report.d.ts.map

package/dist/cli/report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../src/cli/report.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAElE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,KAAK,EAAE,cAAc,EAAmC,MAAM,sBAAsB,CAAC;AAE5F,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACxC;AAED,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,OAAO,CAAC;AAE7C,MAAM,WAAW,eAAe;IAC9B,oGAAoG;IACpG,QAAQ,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3C,QAAQ,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,IAAI,CAAC;IAC5C,QAAQ,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,kBAAkB,KAAK,IAAI,CAAC;IACxD,QAAQ,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,kBAAkB,KAAK,IAAI,CAAC;CACzD;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,SAAS,GAAG,eAAe,CAE/F"}

package/dist/cli/report.js

@@ -0,0 +1,149 @@
+import { BLOG_REFRESH_SECRET_ENV } from "../discovery/refresh.js";
+export function createPublishReporter(format, output) {
+    return format === "lines" ? createLineReporter(output) : createTextReporter(output);
+}
+function countActions(run) {
+    const count = (action) => run.changes.filter((change) => change.action === action).length;
+    return { added: count("added"), changed: count("changed"), unchanged: count("unchanged") };
+}
+function formatBefore(change) {
+    return change.statusBefore === null || change.slugBefore === null ? "none" : `${change.statusBefore}/${change.slugBefore}`;
+}
+function formatDate(date) {
+    return date === null ? "none" : date.toISOString();
+}
+function createTextReporter(output) {
+    const formatProblem = (problem) => `${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) {
+    return String(value).replace(/[|\r\n]+/g, " ");
+}
+function createLineReporter(output) {
+    // Every contract line goes to standard output, so `2>&1` is not needed to read them.
+    const line = (...fields) => 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;
+            }
+        },
+    };
+}
+//# sourceMappingURL=report.js.map

package/dist/cli/report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../../src/cli/report.ts"],"names":[],"mappings":"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"}

package/dist/cli/run.d.ts

@@ -2,10 +2,8 @@ import { type Clock, type SoftureConfig } from "@softure-ai/core";
 import { type DatabaseHandle } from "@softure-ai/db";
 import { type PublishGate } from "../db/publish-run.js";
 import type { FetchLike } from "../quality/external-links.js";
-export interface CliOutput {
-    readonly log: (line: string) => void;
-    readonly error: (line: string) => void;
-}
+import { type CliOutput, type PublishFormat } from "./report.js";
+export type { CliOutput };
 export interface RunBlogCliOptions {
     /** The app's config with `blog()` among its modules. */
     readonly config: SoftureConfig;
@@ -29,11 +27,13 @@ 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 declare const EXIT_OK = 0;
 export declare const EXIT_FAILED = 1;
 export declare const EXIT_USAGE = 2;
-export declare const BLOG_USAGE = "Usage:\n  softure-blog publish [<path>...] [--commit] [--withdraw] [--no-indexnow] [--app-url <origin>]\n  softure-blog check [<path>...] [--external] [--today <YYYY-MM-DD>]\n  softure-blog skill install [--dir <path>] [--command <cmd>] [--check]\n\npublish   Brings the blog's tables to the state of the article files. A <path> is a file or a\n          folder (every *.md in it except README.md); without one, blog({ contentDir }).\n          Every file is checked before the first write, and one problem writes nothing.\n  --commit      write the changes; without it, a dry run that shows them and writes nothing\n  --withdraw    publish the one given file as withdrawn, whatever its status\n  --no-indexnow do not submit the changed addresses to IndexNow\n  --app-url     the running app's origin for the cache refresh; default: appOrigin\n          Files going public pass the quality gate first; an error writes nothing.\n          With BLOG_REFRESH_SECRET set, a commit that changed a text asks the running\n          app (refreshBlogCache) to refresh its blog cache, before the IndexNow submit.\n          With seo({ indexNow }) enabled, a commit submits the addresses whose answer\n          changed (the text, its old slug, its listing) to IndexNow; a dry run prints them.\n\ncheck     Runs the quality gate of blog({ quality }) over the files, without a database, and\n          prints every finding as file:line: severity [rule] message. Exits 1 on any error.\n  --external    also request every external link (2xx after redirects)\n  --today       the date to check freshness against; default: today in the app's time zone\n\nskill install\n          Writes the article writing skill, filled from blog({ quality, skill }),\n          into .claude/skills/blog-write. Overwrites only a skill it generated before.\n  --dir         the skill folder; default .claude/skills/blog-write\n  --command     how the skill runs this command; default \"npx softure-blog\"\n  --check       write nothing; exit 1 when the folder differs from what install would write\n\nOptions:\n  --config <file>    the app's softure.config file (bin only)\n  --help             show this help";
+export declare const BLOG_USAGE = "Usage:\n  softure-blog publish [<path>...] [--commit] [--withdraw] [--no-indexnow] [--app-url <origin>]\n                       [--stdin [--name <slug>.md]] [--history <file.json>] [--format text|lines]\n  softure-blog check [<path>...] [--external] [--today <YYYY-MM-DD>]\n  softure-blog skill install [--dir <path>] [--command <cmd>] [--check]\n\npublish   Brings the blog's tables to the state of the article files. A <path> is a file or a\n          folder (every *.md in it except README.md); without one, blog({ contentDir }).\n          Every file is checked before the first write, and one problem writes nothing.\n  --commit      write the changes; without it, a dry run that shows them and writes nothing\n  --withdraw    publish the one given file as withdrawn, whatever its status\n  --no-indexnow do not submit the changed addresses to IndexNow\n  --app-url     the running app's origin for the cache refresh; default: appOrigin\n  --stdin       read the files from standard input instead of paths: one file named by\n                --name, or without --name a JSON bundle {\"files\":[{\"name\",\"text\"}]}\n                (optionally with \"history\", the content of a --history file)\n  --history     a JSON file of the articles' earlier dates and old slugs, applied on the\n                first publish of each article (moving an existing blog in)\n  --format      text (default) or lines: a stable blog|<key>|... contract for scripts\n          Files going public pass the quality gate first; an error writes nothing.\n          With BLOG_REFRESH_SECRET set, a commit that changed a text asks the running\n          app (refreshBlogCache) to refresh its blog cache, before the IndexNow submit.\n          With seo({ indexNow }) enabled, a commit submits the addresses whose answer\n          changed (the text, its old slug, its listing) to IndexNow; a dry run prints them.\n\ncheck     Runs the quality gate of blog({ quality }) over the files, without a database, and\n          prints every finding as file:line: severity [rule] message. Exits 1 on any error.\n  --external    also request every external link (2xx after redirects)\n  --today       the date to check freshness against; default: today in the app's time zone\n\nskill install\n          Writes the article writing skill, filled from blog({ quality, skill }),\n          into .claude/skills/blog-write. Overwrites only a skill it generated before.\n  --dir         the skill folder; default .claude/skills/blog-write\n  --command     how the skill runs this command; default \"npx softure-blog\"\n  --check       write nothing; exit 1 when the folder differs from what install would write\n\nOptions:\n  --config <file>    the app's softure.config file (bin only)\n  --help             show this help";
 export type BlogCommand = {
     readonly kind: "help";
 } | {
@@ -44,6 +44,13 @@ 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[];