@softure-ai/blog 0.0.0-stage → 0.1.5

package/dist/cli/skill.js

@@ -0,0 +1,221 @@
+// `softure-blog skill install`: the writing skill of `skill/`, rendered with the app's blog config.
+// The templates hold `{{name}}` values and `{{#flag}}…{{/flag}}` / `{{^flag}}…{{/flag}}` sections;
+// `references/rules.md` holds one table row per built-in rule, which gets the effective severity
+// and the catalog's description, or is dropped when the app's gate does not enforce the rule.
+import { readdirSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import { listQualityRules } from "../quality/catalog.js";
+import { getBlogOptions, getBlogReservedSlugs, getQualitySettings } from "../server/options.js";
+/** The folder the skill installs into, relative to the app's root. */
+export const DEFAULT_SKILL_DIR = ".claude/skills/blog-write";
+/** How the skill tells the agent to run the command. */
+export const DEFAULT_SKILL_COMMAND = "npx softure-blog";
+/** The line every generated `SKILL.md` holds; install overwrites only a folder whose `SKILL.md` has it. */
+export const SKILL_MARKER = "<!-- Generated by `softure-blog skill install`";
+/** `modules/blog/skill/`, from `src/cli/` and from `dist/cli/` alike. */
+const TEMPLATE_DIR = fileURLToPath(new URL("../../skill/", import.meta.url));
+const RULES_TEMPLATE = "references/rules.md";
+/** The file that holds the app's own sections (`blog({ skill: { sections } })`), written only when there are some. */
+export const APP_SECTIONS_FILE = "references/app.md";
+const LANGUAGE_NAMES = { en: "English", pl: "Polish" };
+/** The skill's files for the app's config. Throws when the gate is off: the skill is built on it. */
+export function renderBlogSkill(config, options = {}) {
+    const settings = getQualitySettings(config);
+    if (settings === null)
+        throw new Error("the quality gate is off (blog({ quality: false })); the writing skill is built on it");
+    const values = getSkillValues(config, settings, options);
+    const rules = listQualityRules(settings);
+    const files = listTemplateFiles().map((path) => {
+        const rendered = renderSkillTemplate(readFileSync(join(TEMPLATE_DIR, path), "utf8"), values);
+        return { path, text: path === RULES_TEMPLATE ? fillRulesTables(rendered, rules) : rendered };
+    });
+    const { sections } = getBlogOptions(config).skill;
+    if (sections.length === 0)
+        return files;
+    return [...files, { path: APP_SECTIONS_FILE, text: renderAppSections(sections) }].sort((a, b) => (a.path < b.path ? -1 : 1));
+}
+/** `references/app.md`: each section as `## <title>` with its body verbatim, never run through the template engine. */
+export function renderAppSections(sections) {
+    return [
+        "# The app's own sections",
+        "",
+        "Written by the app in its blog config (`blog({ skill: { sections } })`). They add to this skill where they name",
+        "the app's own data, blocks and fields; they never switch off a rule of the gate.",
+        "",
+        ...sections.flatMap((section) => [`## ${section.title}`, "", section.body, ""]),
+    ].join("\n");
+}
+/** The values the templates read. */
+export function getSkillValues(config, settings, options = {}) {
+    const blogOptions = getBlogOptions(config);
+    const { limits, ymyl, voice, paths, plugins } = settings.options;
+    const fieldKeys = Object.keys(blogOptions.fields?.shape ?? {});
+    const reservedSlugs = getBlogReservedSlugs(config);
+    return {
+        command: options.command ?? DEFAULT_SKILL_COMMAND,
+        language: settings.ruleset.language,
+        languageName: LANGUAGE_NAMES[settings.ruleset.language] ?? settings.ruleset.language,
+        contentDir: trimTrailingSlashes(blogOptions.contentDir),
+        articlesPath: paths.articles,
+        termsPath: paths.terms,
+        articleWordsMin: String(limits.words.article.min),
+        articleWordsMax: String(limits.words.article.max),
+        termWordsMin: String(limits.words.term.min),
+        termWordsMax: String(limits.words.term.max),
+        leadWordsArticle: String(limits.leadWords.article),
+        leadWordsTerm: String(limits.leadWords.term),
+        answerWords: String(limits.answerWords),
+        internalLinksArticle: String(limits.internalLinks.article),
+        internalLinksTerm: String(limits.internalLinks.term),
+        staleAfterDays: String(limits.staleAfterDays),
+        titleChars: String(limits.titleChars),
+        descriptionCharsMin: String(limits.descriptionChars.min),
+        descriptionCharsMax: String(limits.descriptionChars.max),
+        wordsPerDash: String(limits.wordsPerDash),
+        wordsPerBold: String(limits.wordsPerBold),
+        sentenceWords: String(limits.sentenceWords),
+        ymyl: ymyl !== null,
+        ownCalculationMark: ymyl?.ownCalculationMark ?? false,
+        firstPersonSingular: voice.forbidFirstPersonSingular,
+        plugins: plugins.length > 0,
+        fields: fieldKeys.length > 0,
+        fieldKeys: fieldKeys.map((key) => `\`${key}\``).join(", "),
+        reservedSlugs: reservedSlugs.length > 0,
+        reservedSlugList: reservedSlugs.map((slug) => `\`${slug}\``).join(", "),
+        appRules: "",
+        appSections: blogOptions.skill.sections.length > 0,
+        appSectionTitles: blogOptions.skill.sections.map((section) => section.title).join(", "),
+    };
+}
+/** Without trailing slashes; a loop, not a regular expression, so a long run of slashes stays linear. */
+function trimTrailingSlashes(path) {
+    let end = path.length;
+    while (end > 1 && path[end - 1] === "/")
+        end -= 1;
+    return path.slice(0, end);
+}
+const STANDALONE_SECTION_TAG = /^[ \t]*(\{\{[#^/][A-Za-z]+\}\})[ \t]*\r?\n/gm;
+const TAG = /\{\{([#^/]?)([A-Za-z]+)\}\}/g;
+/**
+ * Fills `{{name}}` with a value and keeps `{{#flag}}…{{/flag}}` when the value is truthy (a non-empty
+ * string or `true`), `{{^flag}}…{{/flag}}` when it is not. A tag alone on its line takes the line with
+ * it. Throws on a name without a value and on a section that does not close, naming it.
+ */
+export function renderSkillTemplate(template, values) {
+    const source = template.replace(STANDALONE_SECTION_TAG, "$1");
+    const getValue = (name) => {
+        const value = values[name];
+        if (value === undefined)
+            throw new Error(`skill template: no value for {{${name}}}`);
+        return value;
+    };
+    const stack = [];
+    let output = "";
+    let last = 0;
+    const isKept = () => stack.every((section) => section.keep);
+    for (const match of source.matchAll(TAG)) {
+        const [tag, kind = "", name = ""] = match;
+        if (isKept())
+            output += source.slice(last, match.index);
+        last = match.index + tag.length;
+        if (kind === "#" || kind === "^") {
+            const truthy = isTruthy(getValue(name));
+            stack.push({ name, inverted: kind === "^", keep: kind === "^" ? !truthy : truthy });
+        }
+        else if (kind === "/") {
+            const open = stack.pop();
+            if (open?.name !== name)
+                throw new Error(`skill template: {{/${name}}} closes ${open === undefined ? "nothing" : `{{${open.inverted ? "^" : "#"}${open.name}}}`}`);
+        }
+        else if (isKept()) {
+            const value = getValue(name);
+            if (typeof value !== "string")
+                throw new Error(`skill template: {{${name}}} is a flag; use it as a section`);
+            output += value;
+        }
+    }
+    const unclosed = stack.at(-1);
+    if (unclosed !== undefined)
+        throw new Error(`skill template: {{${unclosed.inverted ? "^" : "#"}${unclosed.name}}} is not closed`);
+    return output + source.slice(last);
+}
+function isTruthy(value) {
+    return typeof value === "string" ? value.length > 0 : value;
+}
+/** A row of a rules table in the template: `` | `rule-id` | | | guidance | ``. */
+const TEMPLATE_RULE_ROW = /^\| `([a-z0-9-]+)` \| \| \| (.*) \|$/;
+const RULES_TABLE_HEADER = "| Rule | Severity | What the gate looks for | What to write instead |";
+const APP_RULES_SLOT = "## The app's own rules\n\n";
+/** The rule ids the template's tables name. */
+export function findTemplateRuleIds(rulesTemplate) {
+    return rulesTemplate.split("\n").flatMap((line) => {
+        const match = TEMPLATE_RULE_ROW.exec(line);
+        return match?.[1] === undefined ? [] : [match[1]];
+    });
+}
+/**
+ * Fills the rows of rules the gate enforces with their severity and description, drops the rows of
+ * rules it does not, drops a table (and its heading) left without rows, and lists every catalog rule
+ * the template has no row for (the app's voice phrases and plugin rules) under the app's own rules.
+ */
+export function fillRulesTables(text, rules) {
+    const byId = new Map(rules.map((rule) => [rule.id, rule]));
+    const filled = text.split("\n").flatMap((line) => {
+        const match = TEMPLATE_RULE_ROW.exec(line);
+        if (match === null)
+            return [line];
+        const [, id = "", guidance = ""] = match;
+        const rule = byId.get(id);
+        return rule === undefined ? [] : [`| \`${id}\` | ${formatSeverity(rule)} | ${escapeCell(rule.description)} | ${guidance} |`];
+    });
+    const named = new Set(findTemplateRuleIds(text));
+    const appRules = rules.filter((rule) => !named.has(rule.id));
+    const appTable = appRules.length === 0
+        ? "None: the gate enforces only the rules above."
+        : [
+            "Rules of the app's voice and its plugins; the description is the app's own.",
+            "",
+            "| Rule | Severity | What the gate looks for |",
+            "| --- | --- | --- |",
+            ...appRules.map((rule) => `| \`${rule.id}\` | ${formatSeverity(rule)} | ${escapeCell(rule.description)} |`),
+        ].join("\n");
+    return dropEmptyTables(filled.join("\n")).replace(APP_RULES_SLOT, `${APP_RULES_SLOT}${appTable}`);
+}
+function formatSeverity(rule) {
+    return rule.severity === "error" ? "**error**" : "warning";
+}
+function escapeCell(text) {
+    return text.replaceAll("|", "\\|").replaceAll("\n", " ");
+}
+/** Removes a `## ` section whose rules table has no rows left. */
+function dropEmptyTables(text) {
+    return text
+        .split(/\n(?=## )/)
+        .filter((section) => {
+        if (!section.includes(RULES_TABLE_HEADER))
+            return true;
+        return section.split("\n").some((line) => line.startsWith("| `"));
+    })
+        .join("\n");
+}
+/** The template files, relative to `skill/`. */
+export function listTemplateFiles() {
+    const files = [];
+    const walk = (dir) => {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const path = join(dir, entry.name);
+            if (entry.isDirectory())
+                walk(path);
+            else if (entry.name.endsWith(".md"))
+                files.push(relative(TEMPLATE_DIR, path).split("\\").join("/"));
+        }
+    };
+    walk(TEMPLATE_DIR);
+    return files.sort();
+}
+/** The text of one template file, as shipped. */
+export function readSkillTemplate(path) {
+    return readFileSync(join(TEMPLATE_DIR, path), "utf8");
+}
+//# sourceMappingURL=skill.js.map

package/dist/cli/skill.js.map

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

package/dist/content/article-file.d.ts

@@ -0,0 +1,27 @@
+import { type BlogArticleContent, type BlogArticleInput } from "../contract.js";
+import { type BlogFieldsSchema } from "../options.js";
+export interface ParseArticleFileOptions {
+    /** Slugs taken by static pages (`blog({ reservedSlugs })`). */
+    readonly reservedSlugs?: readonly string[];
+    /** The app's own frontmatter fields (`blog({ fields })`). */
+    readonly fields?: BlogFieldsSchema;
+}
+export type ArticleFileResult = {
+    readonly ok: true;
+    readonly article: BlogArticleInput;
+} | {
+    readonly ok: false;
+    readonly errors: readonly string[];
+};
+/**
+ * Reads an article file. `fileName` is a path or a bare name; it must read `<slug>.md`, so the file
+ * and the address cannot drift apart.
+ */
+export declare function parseArticleFile(text: string, fileName: string, options?: ParseArticleFileOptions): ArticleFileResult;
+/**
+ * The hash of what a reader sees, without status, slug, publication date and pillar: it moves
+ * `updated_at`. A fixed array, so the order of keys in the file does not change it. Fields added
+ * later join only when present, so the hash of an existing text does not change with the format.
+ */
+export declare function computeContentHash(content: BlogArticleContent): string;
+//# sourceMappingURL=article-file.d.ts.map

package/dist/content/article-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"article-file.d.ts","sourceRoot":"","sources":["../../src/content/article-file.ts"],"names":[],"mappings":"AAQA,OAAO,EAA6C,KAAK,kBAAkB,EAAE,KAAK,gBAAgB,EAAmB,MAAM,gBAAgB,CAAC;AAC5I,OAAO,EAAoB,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAExE,MAAM,WAAW,uBAAuB;IACtC,+DAA+D;IAC/D,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,CAAC,EAAE,gBAAgB,CAAC;CACpC;AAED,MAAM,MAAM,iBAAiB,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAC;AA6BvJ;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,uBAA4B,GAAG,iBAAiB,CAsDzH;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,CAetE"}

package/dist/content/article-file.js

@@ -0,0 +1,179 @@
+// An article file `<slug>.md` → the input of `publishArticle` (FIRE_TRACKER `src/lib/blog-article-file.ts`).
+// A YAML frontmatter between `---` lines, then the Markdown body. The frontmatter is strict: an
+// unknown key is an error, so a typo in `current_as_of` cannot pass as a missing date. The app's
+// own keys (`blog({ fields })`) are checked by its schema.
+import { createHash } from "node:crypto";
+import { basename } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { z } from "zod";
+import { BLOG_ARTICLE_KINDS, BLOG_ARTICLE_STATUSES } from "../contract.js";
+import { FRONTMATTER_KEYS } from "../options.js";
+const KEBAB = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const FENCE = "---";
+const kebab = () => z.string().max(100).regex(KEBAB, "lowercase letters, digits and single hyphens, e.g. index-funds-basics");
+const httpUrl = z.url({ protocol: /^https?$/, error: "must be an http(s) address" });
+const frontmatterSchema = z.strictObject({
+    id: kebab(),
+    slug: kebab(),
+    kind: z.enum(BLOG_ARTICLE_KINDS).default("article"),
+    cluster: kebab().optional(),
+    /** The main text of its cluster: other texts of the cluster always recommend it. Needs `cluster`. */
+    pillar: z.boolean().default(false),
+    title: z.string().trim().min(1).max(200),
+    description: z.string().trim().min(1).max(320),
+    /** The "in short" box above the body: a few sentences an AI assistant can quote. */
+    summary: z.string().trim().min(1).max(600).optional(),
+    status: z.enum(BLOG_ARTICLE_STATUSES),
+    current_as_of: z.iso.date(),
+    /** A day (`YYYY-MM-DD`, read as midnight UTC) or a moment with an offset. */
+    published_at: z.union([z.iso.date(), z.iso.datetime({ offset: true })]).optional(),
+    sources: z.array(z.strictObject({ name: z.string().trim().min(1), url: httpUrl })).default([]),
+    faq: z.array(z.strictObject({ question: z.string().trim().min(1), answer: z.string().trim().min(1) })).default([]),
+    /** Only for a term: the phrases, as they stand in texts, that link to its definition. */
+    forms: z.array(z.string().trim().min(2).max(80)).optional(),
+});
+/**
+ * Reads an article file. `fileName` is a path or a bare name; it must read `<slug>.md`, so the file
+ * and the address cannot drift apart.
+ */
+export function parseArticleFile(text, fileName, options = {}) {
+    const parts = splitFrontmatter(text);
+    if (parts === null)
+        return { ok: false, errors: ["no frontmatter: the file starts with a --- line, the metadata, then a --- line"] };
+    let raw;
+    try {
+        raw = parseYaml(parts.frontmatter);
+    }
+    catch (error) {
+        return { ok: false, errors: [`the frontmatter is not valid YAML: ${error instanceof Error ? error.message : String(error)}`] };
+    }
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+        return { ok: false, errors: ["the frontmatter must be a YAML mapping of keys to values"] };
+    const { core, fields: fieldsInput } = splitKeys(raw, options.fields);
+    const errors = [];
+    const parsed = frontmatterSchema.safeParse(core);
+    if (!parsed.success)
+        errors.push(...parsed.error.issues.map((issue) => `${formatPath(issue.path)}: ${issue.message}`));
+    const fields = parseFields(fieldsInput, options.fields, errors);
+    if (!parsed.success || fields === null)
+        return { ok: false, errors };
+    const meta = parsed.data;
+    const bodyMarkdown = parts.body.trim();
+    if (bodyMarkdown === "")
+        errors.push("the body under the frontmatter is empty");
+    if (meta.pillar && meta.cluster === undefined)
+        errors.push("pillar: true needs a cluster; a pillar is the main text of one topic");
+    if (options.reservedSlugs?.includes(meta.slug) === true)
+        errors.push(`slug ${meta.slug} is taken by a static page of the blog; choose another`);
+    if (meta.kind === "term" && (meta.forms === undefined || meta.forms.length === 0))
+        errors.push("forms: a term needs at least one form, or no article links to it");
+    if (meta.kind === "article" && meta.forms !== undefined)
+        errors.push("forms: only for kind: term; an article is not a link target");
+    if (basename(fileName) !== `${meta.slug}.md`)
+        errors.push(`the file name ${basename(fileName)} differs from the slug plus .md (${meta.slug}.md)`);
+    if (errors.length > 0)
+        return { ok: false, errors };
+    const content = {
+        kind: meta.kind,
+        cluster: meta.cluster ?? null,
+        title: meta.title,
+        description: meta.description,
+        summary: meta.summary ?? null,
+        bodyMarkdown,
+        currentAsOf: meta.current_as_of,
+        sources: meta.sources,
+        faq: meta.faq,
+        termForms: meta.forms ?? [],
+        fields,
+    };
+    return {
+        ok: true,
+        article: {
+            id: meta.id,
+            slug: meta.slug,
+            status: meta.status,
+            publishedAt: readPublishedAt(meta.published_at),
+            isPillar: meta.pillar,
+            ...content,
+            contentSha256: computeContentHash(content),
+        },
+    };
+}
+/**
+ * The hash of what a reader sees, without status, slug, publication date and pillar: it moves
+ * `updated_at`. A fixed array, so the order of keys in the file does not change it. Fields added
+ * later join only when present, so the hash of an existing text does not change with the format.
+ */
+export function computeContentHash(content) {
+    const canonical = JSON.stringify([
+        content.kind,
+        content.cluster,
+        content.title,
+        content.description,
+        content.summary,
+        content.bodyMarkdown,
+        content.currentAsOf,
+        content.sources.map((source) => [source.name, source.url]),
+        content.faq.map((entry) => [entry.question, entry.answer]),
+        ...(content.termForms.length > 0 ? [content.termForms] : []),
+        ...(Object.keys(content.fields).length > 0 ? [sortKeys(content.fields)] : []),
+    ]);
+    return createHash("sha256").update(canonical).digest("hex");
+}
+function splitFrontmatter(text) {
+    const lines = text.replace(/^\uFEFF/, "").replace(/\r\n?/g, "\n").split("\n");
+    if (lines[0] !== FENCE)
+        return null;
+    const end = lines.indexOf(FENCE, 1);
+    if (end === -1)
+        return null;
+    return { frontmatter: lines.slice(1, end).join("\n"), body: lines.slice(end + 1).join("\n") };
+}
+/** The module's keys and unknown keys go to the strict schema (which names the unknown ones); the app's keys to its schema. */
+function splitKeys(raw, fields) {
+    const appKeys = new Set(Object.keys(fields?.shape ?? {}).filter((key) => !FRONTMATTER_KEYS.includes(key)));
+    const core = {};
+    const app = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (appKeys.has(key))
+            app[key] = value;
+        else
+            core[key] = value;
+    }
+    return { core, fields: app };
+}
+function parseFields(input, schema, errors) {
+    if (schema === undefined)
+        return {};
+    const result = schema.safeParse(input);
+    if (!result.success) {
+        errors.push(...result.error.issues.map((issue) => `${formatPath(issue.path)}: ${issue.message}`));
+        return null;
+    }
+    const data = result.data;
+    if (typeof data !== "object" || data === null || Array.isArray(data)) {
+        errors.push("the app's fields schema must parse to an object");
+        return null;
+    }
+    // Undefined optional fields are not stored: an absent key and a missing one read the same.
+    return Object.fromEntries(Object.entries(data).filter(([, value]) => value !== undefined));
+}
+function readPublishedAt(value) {
+    if (value === undefined)
+        return null;
+    return new Date(value.length === 10 ? `${value}T00:00:00Z` : value);
+}
+function formatPath(path) {
+    return path.length === 0 ? "frontmatter" : path.map(String).join(".");
+}
+/** A copy with object keys sorted at every level, so the hash does not depend on key order. */
+function sortKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (typeof value !== "object" || value === null)
+        return value;
+    return Object.fromEntries(Object.keys(value)
+        .sort()
+        .map((key) => [key, sortKeys(value[key])]));
+}
+//# sourceMappingURL=article-file.js.map

package/dist/content/article-file.js.map

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

package/dist/contract.d.ts

@@ -0,0 +1,77 @@
+export declare const BLOG_ARTICLE_KINDS: readonly ["article", "term"];
+/** `article`: a text in the blog; `term`: a glossary definition that articles link to. */
+export type BlogArticleKind = (typeof BLOG_ARTICLE_KINDS)[number];
+export declare const BLOG_ARTICLE_STATUSES: readonly ["draft", "published", "withdrawn"];
+/** `withdrawn` keeps the row: its address answers 410 Gone, not 404. */
+export type BlogArticleStatus = (typeof BLOG_ARTICLE_STATUSES)[number];
+export interface BlogSource {
+    readonly name: string;
+    readonly url: string;
+}
+export interface BlogFaqEntry {
+    readonly question: string;
+    readonly answer: string;
+}
+/** The app's own frontmatter fields (`blog({ fields })`), as its schema parsed them. */
+export type BlogFields = Readonly<Record<string, unknown>>;
+/** The content a reader sees; the content hash covers exactly these fields. */
+export interface BlogArticleContent {
+    readonly kind: BlogArticleKind;
+    readonly cluster: string | null;
+    readonly title: string;
+    readonly description: string;
+    /** The "in short" box above the body; `null` for none. */
+    readonly summary: string | null;
+    readonly bodyMarkdown: string;
+    /** `YYYY-MM-DD`: the day the facts were checked. */
+    readonly currentAsOf: string;
+    readonly sources: readonly BlogSource[];
+    readonly faq: readonly BlogFaqEntry[];
+    /** Phrases that link to a term's definition; empty for an article. */
+    readonly termForms: readonly string[];
+    readonly fields: BlogFields;
+}
+/** An article as a file gives it: what `publishArticle` stores. */
+export interface BlogArticleInput extends BlogArticleContent {
+    readonly id: string;
+    readonly slug: string;
+    readonly status: BlogArticleStatus;
+    /** From the file; `null`: the moment it is first published. */
+    readonly publishedAt: Date | null;
+    /** The main text of its cluster; outside the content hash (it changes other pages, not this one). */
+    readonly isPillar: boolean;
+    readonly contentSha256: string;
+}
+/** A stored article. */
+export interface BlogArticle extends BlogArticleInput {
+    /** Set when the content of an already published text changes. */
+    readonly updatedAt: Date | null;
+    readonly createdAt: Date;
+}
+/** A row before or after a publish. */
+export interface BlogArticleState {
+    readonly slug: string;
+    readonly status: BlogArticleStatus;
+    readonly publishedAt: Date | null;
+    readonly updatedAt: Date | null;
+    readonly contentSha256: string;
+}
+export type BlogPublishAction = "added" | "changed" | "unchanged";
+/**
+ * `blog.slug_taken`: another article has the slug now. `blog.slug_in_history`: another article had
+ * it before and the old address redirects there (a 301 would have two targets).
+ */
+export type BlogSlugErrorCode = "blog.slug_taken" | "blog.slug_in_history";
+export type BlogPublishResult = {
+    readonly ok: true;
+    readonly action: BlogPublishAction;
+    readonly before: BlogArticleState | null;
+    readonly after: BlogArticleState;
+    /** The slug that has just entered the slug history. */
+    readonly previousSlug: string | null;
+} | {
+    readonly ok: false;
+    readonly error: BlogSlugErrorCode;
+    readonly otherArticleId: string;
+};
+//# sourceMappingURL=contract.d.ts.map

package/dist/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,kBAAkB,8BAA+B,CAAC;AAC/D,0FAA0F;AAC1F,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAElE,eAAO,MAAM,qBAAqB,8CAA+C,CAAC;AAClF,wEAAwE;AACxE,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,wFAAwF;AACxF,MAAM,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAE3D,+EAA+E;AAC/E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,oDAAoD;IACpD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,CAAC;IACxC,QAAQ,CAAC,GAAG,EAAE,SAAS,YAAY,EAAE,CAAC;IACtC,sEAAsE;IACtE,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;CAC7B;AAED,mEAAmE;AACnE,MAAM,WAAW,gBAAiB,SAAQ,kBAAkB;IAC1D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,+DAA+D;IAC/D,QAAQ,CAAC,WAAW,EAAE,IAAI,GAAG,IAAI,CAAC;IAClC,qGAAqG;IACrG,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED,wBAAwB;AACxB,MAAM,WAAW,WAAY,SAAQ,gBAAgB;IACnD,iEAAiE;IACjE,QAAQ,CAAC,SAAS,EAAE,IAAI,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;CAC1B;AAED,uCAAuC;AACvC,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,QAAQ,CAAC,WAAW,EAAE,IAAI,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,IAAI,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,SAAS,GAAG,WAAW,CAAC;AAElE;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,iBAAiB,GAAG,sBAAsB,CAAC;AAE3E,MAAM,MAAM,iBAAiB,GACzB;IACE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACzC,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;IACjC,uDAAuD;IACvD,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CACtC,GACD;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;IAAC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;CAAE,CAAC"}

package/dist/contract.js

@@ -0,0 +1,5 @@
+// Types and codes of the blog's content contract: what a file holds, what a row holds, what the
+// store answers. No user-facing copy here: labels come from `messages`.
+export const BLOG_ARTICLE_KINDS = ["article", "term"];
+export const BLOG_ARTICLE_STATUSES = ["draft", "published", "withdrawn"];
+//# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAChG,wEAAwE;AAExE,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,SAAS,EAAE,MAAM,CAAU,CAAC;AAI/D,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,OAAO,EAAE,WAAW,EAAE,WAAW,CAAU,CAAC"}

package/dist/db/articles.d.ts

@@ -0,0 +1,30 @@
+import type { ModuleContext } from "@softure-ai/core";
+import type { Queryable } from "@softure-ai/db";
+import type { BlogArticle, BlogArticleInput, BlogArticleKind, BlogPublishResult } from "../contract.js";
+export type BlogContext = ModuleContext<Queryable>;
+/**
+ * Inserts or updates the article by its `id`. Idempotent: the same file again is `unchanged` and
+ * writes nothing, so a release can publish every file on every deploy.
+ *
+ * Dates:
+ * - `published_at` is the file's date when given; otherwise the row's; otherwise the moment the
+ *   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.
+ *
+ * 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 declare function publishArticle(ctx: BlogContext, input: BlogArticleInput): Promise<BlogPublishResult>;
+/** The article under its current slug, in any status: a page tells 200 from 410 by it. */
+export declare function findArticleBySlug(ctx: BlogContext, slug: string): Promise<BlogArticle | null>;
+/** The published article under its current slug, or `null` (a draft, a withdrawn text, no text). */
+export declare function getPublishedArticle(ctx: BlogContext, slug: string): Promise<BlogArticle | null>;
+/** The current slug of the article that once had `oldSlug`: the target of a 301. */
+export declare function findSlugRedirect(ctx: BlogContext, oldSlug: string): Promise<string | null>;
+export interface ListArticlesFilter {
+    readonly kind?: BlogArticleKind;
+    readonly cluster?: string;
+}
+/** Published texts, newest first; ties by slug. Without a filter, both kinds. */
+export declare function listArticles(ctx: BlogContext, filter?: ListArticlesFilter): Promise<BlogArticle[]>;
+//# sourceMappingURL=articles.d.ts.map

package/dist/db/articles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"articles.d.ts","sourceRoot":"","sources":["../../src/db/articles.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,eAAe,EAAoB,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAG1H,MAAM,MAAM,WAAW,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;AAEnD;;;;;;;;;;;GAWG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAAE,WAAW,EAAE,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAgF1G;AAED,0FAA0F;AAC1F,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAGnG;AAED,oGAAoG;AACpG,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAMrG;AAED,oFAAoF;AACpF,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAOhG;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,CAAC,EAAE,eAAe,CAAC;IAChC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,iFAAiF;AACjF,wBAAsB,YAAY,CAAC,GAAG,EAAE,WAAW,EAAE,MAAM,GAAE,kBAAuB,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAS5G"}