openbriefing 0.3.0 → 0.4.0

package/README.md

@@ -21,6 +21,47 @@ npx openbriefing check https://example.com/sitemap.xml --sitemap
 
 Fetching is bounded: `http` and `https` only, 10 seconds, 5 MB, 5 redirects, and it names itself `openbriefing-check/<version>`.
 
+## Write your tags
+
+A briefing file is a few lines of YAML that you, or your assistant, write for a post. `tags` turns it into escaped tags.
+
+```yaml
+url: https://example.com/a-post/
+headline: One or two lines to hear before going further.
+summary: |
+  Your summary, in plain text. Around 200 to 350 words.
+
+  A blank line is a paragraph break.
+keep:
+  - The one sentence every version must get across.
+highlights:
+  - text: A passage from the post, word for word.
+    label: On control
+attribution: From Example Blog
+status: approved
+```
+
+```sh
+npx openbriefing tags a-post.yaml                 # meta tags for the page's head
+npx openbriefing tags a-post.yaml --format feed   # elements for an RSS item or Atom entry
+npx openbriefing tags content/a-post.md           # the same keys under obs: in a post's front matter
+```
+
+A file whose `status` is not `approved` is refused (exit 1) unless you pass `--allow-draft`, so a build cannot publish a draft by accident. A drafting prompt for your assistant, and a builder that does the same in the browser, are at [openbriefingstandard.org/publish](https://openbriefingstandard.org/publish).
+
+### Ghost
+
+```sh
+export GHOST_URL=https://your-site.example
+export GHOST_ADMIN_API_KEY=…   # Ghost Admin → Integrations → add a custom integration
+
+npx openbriefing ghost pull posts/             # one file per published post, with its text
+npx openbriefing ghost push posts/ --dry-run   # say what would be written
+npx openbriefing ghost push posts/             # write the approved ones
+```
+
+`pull` never changes Ghost and never overwrites a file. `push` writes only approved files, only between `<!-- obs:start -->` and `<!-- obs:end -->` in the post's Code injection header, and skips a post whose tags have not changed. The folder holds your posts: keep it out of public repositories.
+
 ## Use the parser
 
 ```ts

package/dist/briefing.d.ts

@@ -0,0 +1,46 @@
+import { type ObsBrief } from "./obs.js";
+export type BriefingStatus = "draft" | "approved";
+export interface Briefing {
+    /** "draft" unless the file says `status: approved`. */
+    status: BriefingStatus;
+    /** Absent when the file has no usable summary. */
+    brief?: ObsBrief;
+    errors: string[];
+    warnings: string[];
+    /** The post's slug, from the file's front matter, when given. */
+    slug?: string;
+    /** The post's own text, when the file is a post with front matter. */
+    body?: string;
+}
+/** Reads a briefing file, or a post whose front matter has an `obs:` key. Never throws. */
+export declare function parseBriefing(text: string): Briefing;
+/** Marks each highlight found or not found in the post's text, as `check` does for a page (§7). */
+export declare function checkHighlights(brief: ObsBrief, postText: string, warnings: string[]): void;
+export declare function escapeAttr(value: string): string;
+export type TagFormat = "html" | "feed";
+/**
+ * A brief written as tags, every character escaped: meta tags for a page's
+ * head, or the elements of §14 for an RSS item or Atom entry.
+ */
+export declare function renderTags(brief: ObsBrief, format?: TagFormat): string;
+export declare const MARK_START = "<!-- obs:start -->";
+export declare const MARK_END = "<!-- obs:end -->";
+export declare const DRAFT_NOTE = "<!-- obs: a draft, not yet approved by the author -->";
+/** Tags between the obs:start and obs:end comments. */
+export declare function markTags(tags: string, draft?: boolean): string;
+/** The marked block in a field, markers included, when there is one. */
+export declare function readMarked(field: string): string | undefined;
+/**
+ * Puts a marked block into a field. An existing block is replaced where it
+ * stands; otherwise the block goes at the end. Nothing outside the markers
+ * changes.
+ */
+export declare function replaceMarked(field: string, block: string): string;
+/** The briefing-file keys for a brief, in the order a person reads them. */
+export declare function briefingFields(brief: ObsBrief, status: BriefingStatus): Record<string, unknown>;
+/** A briefing file's YAML for the given keys. */
+export declare function briefingYaml(fields: Record<string, unknown>): string;
+/** A post file: front matter with the post's details and an `obs:` key, then the post's text. */
+export declare function postFile(front: Record<string, unknown>, body: string): string;
+/** The same keys as front matter for a static site: an `obs:` block to paste into a post. */
+export declare function frontMatterBlock(brief: ObsBrief): string;

package/dist/briefing.js

@@ -0,0 +1,343 @@
+/**
+ * The briefing file: a small YAML file (or the same keys under `obs:` in a
+ * post's front matter) that a person or an assistant writes, and the tags it
+ * turns into. A tool convention, not part of the standard.
+ *
+ * Browser-safe: no platform API, so the site's tag builder runs the same code.
+ */
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { looseText, validateObs } from "./obs.js";
+const KEYS = new Set([
+    "url",
+    "title",
+    "headline",
+    "summary",
+    "summary_short",
+    "summary_medium",
+    "summary_long",
+    "keep",
+    "highlights",
+    "attribution",
+    "derive",
+    "translate",
+    "combine",
+    "preference",
+    "lang",
+    "modified",
+    "status",
+]);
+const FRONT_MATTER = /^?---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n([\s\S]*))?$/u;
+/** A block of text as one value: a wrapped line is a space, a blank line is a paragraph break. */
+function paragraphs(v) {
+    return v
+        .replace(/\r\n?/gu, "\n")
+        .split(/\n[ \t]*\n+/u)
+        .map((p) => p.replace(/\s*\n\s*/gu, " ").trim())
+        .filter((p) => p !== "")
+        .join("\n\n");
+}
+const yesNo = (v) => {
+    if (typeof v === "boolean")
+        return v;
+    if (typeof v === "string") {
+        const s = v.trim().toLowerCase();
+        if (s === "yes" || s === "true")
+            return true;
+        if (s === "no" || s === "false")
+            return false;
+    }
+    return undefined;
+};
+/** Reads a briefing file, or a post whose front matter has an `obs:` key. Never throws. */
+export function parseBriefing(text) {
+    const out = { status: "draft", errors: [], warnings: [] };
+    let data;
+    let fields;
+    try {
+        const fm = FRONT_MATTER.exec(text);
+        if (fm) {
+            data = parseYaml(fm[1]);
+            const body = (fm[2] ?? "").trim();
+            if (body !== "")
+                out.body = body;
+            const rec = data !== null && typeof data === "object" ? data : {};
+            if (rec.obs === undefined || rec.obs === null) {
+                out.errors.push("The front matter has no obs: key");
+                return out;
+            }
+            fields = rec.obs;
+            if (typeof rec.slug === "string" && rec.slug.trim() !== "")
+                out.slug = rec.slug.trim();
+        }
+        else {
+            data = parseYaml(text);
+            fields = data !== null && typeof data === "object" && !Array.isArray(data) && "obs" in data && Object.keys(data).length === 1 ? data.obs : data;
+        }
+    }
+    catch (err) {
+        out.errors.push(`The file is not valid YAML: ${err instanceof Error ? (err.message.split("\n")[0] ?? err.message) : String(err)}`);
+        return out;
+    }
+    if (fields === null || typeof fields !== "object" || Array.isArray(fields)) {
+        out.errors.push("Expected keys such as summary: and headline:");
+        return out;
+    }
+    const f = fields;
+    for (const key of Object.keys(f))
+        if (!KEYS.has(key))
+            out.warnings.push(`${key}: is not a briefing file key; it is ignored`);
+    const status = typeof f.status === "string" ? f.status.trim().toLowerCase() : undefined;
+    if (status === "approved")
+        out.status = "approved";
+    else if (status !== undefined && status !== "draft")
+        out.warnings.push(`status: "${String(f.status)}" is not draft or approved; the file is treated as a draft`);
+    const text1 = (key) => {
+        const v = f[key];
+        if (v === undefined || v === null)
+            return undefined;
+        if (typeof v === "string")
+            return paragraphs(v);
+        if (typeof v === "number" || typeof v === "boolean")
+            return String(v);
+        if (v instanceof Date)
+            return v.toISOString();
+        out.warnings.push(`${key}: is not text; it is ignored`);
+        return undefined;
+    };
+    const shape = { version: 1 };
+    for (const key of ["url", "title", "headline", "attribution", "preference", "lang", "modified"]) {
+        const v = text1(key);
+        if (v !== undefined && v !== "")
+            shape[key] = v;
+    }
+    const summaries = [];
+    const plain = text1("summary");
+    if (plain)
+        summaries.push({ text: plain, from: "inferred" });
+    for (const tier of ["short", "medium", "long"]) {
+        const v = text1(`summary_${tier}`);
+        if (v)
+            summaries.push({ tier, text: v, from: "tiered" });
+    }
+    shape.summaries = summaries;
+    const keep = f.keep;
+    if (typeof keep === "string")
+        shape.keep = [paragraphs(keep)];
+    else if (Array.isArray(keep))
+        shape.keep = keep.filter((k) => typeof k === "string").map(paragraphs);
+    else if (keep !== undefined && keep !== null)
+        out.warnings.push("keep: is not a list of lines; it is ignored");
+    const highlights = f.highlights;
+    if (Array.isArray(highlights)) {
+        shape.highlights = highlights.flatMap((h) => {
+            if (typeof h === "string")
+                return [{ text: paragraphs(h) }];
+            if (h !== null && typeof h === "object" && typeof h.text === "string") {
+                const rec = h;
+                return [typeof rec.label === "string" ? { text: paragraphs(rec.text), label: paragraphs(rec.label) } : { text: paragraphs(rec.text) }];
+            }
+            out.warnings.push("A highlight has no text; it is ignored");
+            return [];
+        });
+    }
+    else if (highlights !== undefined && highlights !== null)
+        out.warnings.push("highlights: is not a list; it is ignored");
+    const derive = {};
+    const mode = text1("derive");
+    if (mode !== undefined)
+        derive.mode = mode;
+    for (const key of ["translate", "combine"]) {
+        if (f[key] === undefined || f[key] === null)
+            continue;
+        const v = yesNo(f[key]);
+        if (v === undefined)
+            out.warnings.push(`${key}: is not yes or no; it is ignored`);
+        else
+            derive[key] = v;
+    }
+    if (Object.keys(derive).length > 0)
+        shape.derive = derive;
+    const result = validateObs(shape);
+    out.errors.push(...result.errors);
+    out.warnings.push(...result.warnings);
+    if (result.brief) {
+        out.brief = result.brief;
+        // The briefing file states the language or leaves it out; there is no page to fall back on.
+        if (shape.lang === undefined)
+            delete out.brief.lang;
+        if (out.body !== undefined)
+            checkHighlights(out.brief, out.body, out.warnings);
+    }
+    return out;
+}
+/** Marks each highlight found or not found in the post's text, as `check` does for a page (§7). */
+export function checkHighlights(brief, postText, warnings) {
+    const body = looseText(postText);
+    if (body === "")
+        return;
+    for (const h of brief.highlights) {
+        h.inContent = body.includes(looseText(h.text));
+        if (!h.inContent) {
+            const head = h.text.split(/\s+/u).slice(0, 6).join(" ");
+            warnings.push(`obs:highlight "${head}…" is not in the post's text (§7)`);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Writing tags
+export function escapeAttr(value) {
+    return value.replace(/&/gu, "&amp;").replace(/"/gu, "&quot;").replace(/</gu, "&lt;").replace(/>/gu, "&gt;").replace(/\n/gu, "&#10;");
+}
+const escapeXml = (value) => value.replace(/&/gu, "&amp;").replace(/</gu, "&lt;").replace(/>/gu, "&gt;");
+const escapeXmlAttr = (value) => escapeXml(value).replace(/"/gu, "&quot;").replace(/\n/gu, "&#10;");
+/** One [property, value] pair per tag, in the order the tags are written. Defaults are left out. */
+function pairs(brief) {
+    const out = [];
+    if (brief.version !== 1)
+        out.push(["obs:version", String(brief.version)]);
+    if (brief.title !== undefined)
+        out.push(["obs:title", brief.title]);
+    if (brief.headline !== undefined)
+        out.push(["obs:headline", brief.headline]);
+    for (const s of brief.summaries)
+        out.push([s.from === "tiered" ? `obs:summary:${s.tier}` : "obs:summary", s.text]);
+    for (const k of brief.keep)
+        out.push(["obs:keep", k]);
+    for (const h of brief.highlights) {
+        out.push(["obs:highlight", h.text]);
+        if (h.label !== undefined)
+            out.push(["obs:highlight:label", h.label]);
+    }
+    if (brief.derive.mode !== "anchor")
+        out.push(["obs:derive", brief.derive.mode]);
+    if (!brief.derive.translate)
+        out.push(["obs:derive:translate", "no"]);
+    if (!brief.derive.combine)
+        out.push(["obs:derive:combine", "no"]);
+    if (brief.attribution !== undefined)
+        out.push(["obs:attribution", brief.attribution]);
+    if (brief.preference !== "summary")
+        out.push(["obs:preference", brief.preference]);
+    if (brief.lang !== undefined)
+        out.push(["obs:lang", brief.lang]);
+    if (brief.url !== undefined)
+        out.push(["obs:url", brief.url]);
+    if (brief.modified !== undefined && brief.modifiedFrom === "obs")
+        out.push(["obs:modified", brief.modified]);
+    return out;
+}
+/**
+ * A brief written as tags, every character escaped: meta tags for a page's
+ * head, or the elements of §14 for an RSS item or Atom entry.
+ */
+export function renderTags(brief, format = "html") {
+    const list = pairs(brief);
+    if (format === "html")
+        return list.map(([k, v]) => `<meta property="${k}" content="${escapeAttr(v)}">`).join("\n");
+    const out = [];
+    const derive = [];
+    let mode = "";
+    for (let i = 0; i < list.length; i++) {
+        const [k, v] = list[i];
+        const name = k.slice(4);
+        if (k === "obs:highlight") {
+            const next = list[i + 1];
+            const label = next && next[0] === "obs:highlight:label" ? ` label="${escapeXmlAttr(next[1])}"` : "";
+            out.push(`<obs:highlight${label}>${escapeXml(v)}</obs:highlight>`);
+        }
+        else if (k === "obs:highlight:label")
+            continue;
+        else if (k.startsWith("obs:summary:"))
+            out.push(`<obs:summary length="${k.slice(12)}">${escapeXml(v)}</obs:summary>`);
+        else if (k === "obs:derive")
+            mode = v;
+        else if (k === "obs:derive:translate" || k === "obs:derive:combine")
+            derive.push(` ${k.slice(11)}="${v}"`);
+        else
+            out.push(`<obs:${name}>${escapeXml(v)}</obs:${name}>`);
+    }
+    if (mode !== "" || derive.length > 0) {
+        const at = out.findIndex((l) => l.startsWith("<obs:attribution>") || l.startsWith("<obs:preference>") || l.startsWith("<obs:lang>") || l.startsWith("<obs:url>") || l.startsWith("<obs:modified>"));
+        const line = `<obs:derive${derive.join("")}>${mode === "" ? "anchor" : mode}</obs:derive>`;
+        if (at === -1)
+            out.push(line);
+        else
+            out.splice(at, 0, line);
+    }
+    return out.join("\n");
+}
+// ---------------------------------------------------------------------------
+// The marked block, for a CMS field that holds other code too
+export const MARK_START = "<!-- obs:start -->";
+export const MARK_END = "<!-- obs:end -->";
+export const DRAFT_NOTE = "<!-- obs: a draft, not yet approved by the author -->";
+const MARKED = /<!--\s*obs:start\s*-->[\s\S]*?<!--\s*obs:end\s*-->/u;
+/** Tags between the obs:start and obs:end comments. */
+export function markTags(tags, draft = false) {
+    return [MARK_START, ...(draft ? [DRAFT_NOTE] : []), tags, MARK_END].join("\n");
+}
+/** The marked block in a field, markers included, when there is one. */
+export function readMarked(field) {
+    return MARKED.exec(field)?.[0];
+}
+/**
+ * Puts a marked block into a field. An existing block is replaced where it
+ * stands; otherwise the block goes at the end. Nothing outside the markers
+ * changes.
+ */
+export function replaceMarked(field, block) {
+    if (MARKED.test(field))
+        return field.replace(MARKED, () => block);
+    if (field.trim() === "")
+        return block;
+    return `${field.replace(/\s+$/u, "")}\n${block}`;
+}
+// ---------------------------------------------------------------------------
+// Writing a briefing file
+/** The briefing-file keys for a brief, in the order a person reads them. */
+export function briefingFields(brief, status) {
+    const f = {};
+    if (brief.url !== undefined)
+        f.url = brief.url;
+    if (brief.title !== undefined)
+        f.title = brief.title;
+    if (brief.headline !== undefined)
+        f.headline = brief.headline;
+    for (const s of brief.summaries)
+        f[s.from === "tiered" ? `summary_${s.tier}` : "summary"] = s.text;
+    if (brief.keep.length > 0)
+        f.keep = [...brief.keep];
+    if (brief.highlights.length > 0)
+        f.highlights = brief.highlights.map((h) => (h.label === undefined ? { text: h.text } : { text: h.text, label: h.label }));
+    if (brief.attribution !== undefined)
+        f.attribution = brief.attribution;
+    if (brief.derive.mode !== "anchor")
+        f.derive = brief.derive.mode;
+    if (!brief.derive.translate)
+        f.translate = false;
+    if (!brief.derive.combine)
+        f.combine = false;
+    if (brief.preference !== "summary")
+        f.preference = brief.preference;
+    if (brief.lang !== undefined)
+        f.lang = brief.lang;
+    if (brief.modified !== undefined && brief.modifiedFrom === "obs")
+        f.modified = brief.modified;
+    f.status = status;
+    return f;
+}
+const YAML_OPTIONS = { lineWidth: 0, blockQuote: "literal" };
+/** A briefing file's YAML for the given keys. */
+export function briefingYaml(fields) {
+    return stringifyYaml(fields, YAML_OPTIONS);
+}
+/** A post file: front matter with the post's details and an `obs:` key, then the post's text. */
+export function postFile(front, body) {
+    return `---\n${stringifyYaml(front, YAML_OPTIONS)}---\n\n${body.trim()}\n`;
+}
+/** The same keys as front matter for a static site: an `obs:` block to paste into a post. */
+export function frontMatterBlock(brief) {
+    const fields = briefingFields(brief, "approved");
+    delete fields.status;
+    return stringifyYaml({ obs: fields }, YAML_OPTIONS).trimEnd();
+}

package/dist/cli.js

@@ -1,5 +1,8 @@
 #!/usr/bin/env node
 /**
+ * openbriefing tags <file.yaml | post.md | -> [--format html | feed | json] [--marked] [--allow-draft]
+ * openbriefing ghost pull <folder> [--slug <slug>]
+ * openbriefing ghost push <folder> [--slug <slug>] [--dry-run]
  * openbriefing check <url | file | -> [--url <page url>] [--json]
  * openbriefing check <feed url | file> --feed [--pages]
  * openbriefing check <sitemap url | file> --sitemap [--limit <n>]
@@ -11,6 +14,7 @@ import { readFileSync } from "node:fs";
 import { basename, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { JSDOM } from "jsdom";
+import { markTags, parseBriefing, renderTags } from "./briefing.js";
 import { DEFAULT_LIMITS, fetchText, isHttpUrl, mapLimit, userAgent } from "./fetch.js";
 import { countWords, fingerprint, mergeObs, parseFeedObs, parseObs, SIZES } from "./obs.js";
 const VERSION = (() => {
@@ -23,11 +27,22 @@ const VERSION = (() => {
 })();
 const LIMITS = { ...DEFAULT_LIMITS, userAgent: userAgent(VERSION) };
 const USAGE = `Usage:
+  openbriefing tags <file.yaml | post.md | -> [--format html | feed | json] [--marked] [--allow-draft]
+  openbriefing ghost pull <folder> [--slug <slug>]
+  openbriefing ghost push <folder> [--slug <slug>] [--dry-run]
   openbriefing check <url | file | -> [--url <page url>] [--json]
   openbriefing check <feed url | file> --feed [--pages]
   openbriefing check <sitemap url | file> --sitemap [--limit <n>]
 
-Checks a page, a feed or a sitemap for Open Briefing Standard tags.
+tags turns a briefing file into escaped tags. ghost pull writes one file per
+published post; ghost push writes each approved file's tags into its post
+(GHOST_URL and GHOST_ADMIN_API_KEY in the environment). check reads a page,
+a feed or a sitemap and prints what a reader sees.
+  --format   html (meta tags, the default), feed (RSS and Atom elements) or json
+  --marked   wrap the tags in the obs:start and obs:end comments
+  --allow-draft  write tags for a file whose status is not approved
+  --slug     with ghost: one post only
+  --dry-run  with ghost push: say what would be written, and write nothing
   --url      the page's address, when checking a file with no canonical link
   --feed     treat the input as an RSS or Atom feed (detected when omitted)
   --pages    with a feed: also fetch each item's page and say which one stands
@@ -36,7 +51,7 @@ Checks a page, a feed or a sitemap for Open Briefing Standard tags.
   --json     print the parsed result as JSON
 Spec: https://openbriefingstandard.org`;
 function parseArgs(argv) {
-    const args = { json: false, feed: false, pages: false, sitemap: false };
+    const args = { json: false, feed: false, pages: false, sitemap: false, rest: [], marked: false, allowDraft: false, dryRun: false };
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
         if (a === "--json")
@@ -47,6 +62,21 @@ function parseArgs(argv) {
             args.pages = true;
         else if (a === "--sitemap")
             args.sitemap = true;
+        else if (a === "--marked")
+            args.marked = true;
+        else if (a === "--allow-draft")
+            args.allowDraft = true;
+        else if (a === "--dry-run")
+            args.dryRun = true;
+        else if (a === "--format" || a === "--slug") {
+            const v = argv[++i];
+            if (v === undefined)
+                args.bad = `${a} needs a value`;
+            else if (a === "--format")
+                args.format = v;
+            else
+                args.slug = v;
+        }
         else if (a === "--url") {
             const v = argv[++i];
             if (v === undefined)
@@ -71,6 +101,8 @@ function parseArgs(argv) {
             args.command = a;
         else if (args.target === undefined)
             args.target = a;
+        else
+            args.rest.push(a);
     }
     return args;
 }
@@ -303,10 +335,82 @@ async function check(args) {
     console.log(args.json ? JSON.stringify(r, null, 2) : describe(loaded.label, r));
     return r.brief ? 0 : 1;
 }
+function usage(args) {
+    if (args.bad)
+        console.error(`${args.bad}\n`);
+    console.error(USAGE);
+    return 2;
+}
+function tags(args) {
+    const format = args.format ?? "html";
+    if (!args.target || args.bad || !["html", "feed", "json"].includes(format)) {
+        if (!args.bad && args.target)
+            args.bad = `--format is html, feed or json, not ${format}`;
+        return usage(args);
+    }
+    let text;
+    try {
+        text = readFileSync(args.target === "-" ? 0 : args.target, "utf8");
+    }
+    catch (err) {
+        console.error(`Cannot read ${safe(args.target)}: ${err instanceof Error ? err.message : String(err)}`);
+        return 2;
+    }
+    const b = parseBriefing(text);
+    for (const e of b.errors)
+        console.error(`error    ${safe(e)}`);
+    for (const w of b.warnings)
+        console.error(`warning  ${safe(w)}`);
+    if (!b.brief)
+        return 1;
+    if (b.status !== "approved" && !args.allowDraft) {
+        console.error("This file is a draft. Set status: approved once the author has read every line, or pass --allow-draft.");
+        return 1;
+    }
+    if (format === "json") {
+        console.log(JSON.stringify({ status: b.status, fingerprint: fingerprint(b.brief), brief: b.brief, warnings: b.warnings }, null, 2));
+        return 0;
+    }
+    const draft = b.status !== "approved";
+    const out = renderTags(b.brief, format);
+    if (args.marked && format === "html")
+        console.log(markTags(out, draft));
+    else
+        console.log(draft ? `<!-- obs: a draft, not yet approved by the author -->\n${out}` : out);
+    return 0;
+}
+async function ghost(args) {
+    const action = args.target;
+    const folder = args.rest[0];
+    if (args.bad || (action !== "pull" && action !== "push") || !folder)
+        return usage(args);
+    const url = process.env.GHOST_URL;
+    const key = process.env.GHOST_ADMIN_API_KEY;
+    if (!url || !key) {
+        console.error("Set GHOST_URL (the site's address) and GHOST_ADMIN_API_KEY (Ghost Admin, Integrations, a custom integration's Admin API key).");
+        return 2;
+    }
+    const { Ghost, pull, push } = await import("./ghost.js");
+    const client = new Ghost({ url, key });
+    const opts = { dryRun: args.dryRun };
+    if (args.slug !== undefined)
+        opts.slug = args.slug;
+    const lines = action === "pull" ? await pull(client, folder, args.slug) : await push(client, folder, opts);
+    for (const l of lines)
+        console.log(`${l.state.padEnd(12)} ${safe(l.slug)}${l.note ? `  (${safe(l.note)})` : ""}`);
+    const count = (s) => lines.filter((l) => l.state === s).length;
+    const states = [...new Set(lines.map((l) => l.state))];
+    console.log(lines.length === 0 ? "Nothing to do." : `\n${states.map((s) => `${count(s)} ${s}`).join(", ")}`);
+    return count("error") > 0 ? 1 : 0;
+}
 async function main(argv) {
     const args = parseArgs(argv);
     if (args.command === "check")
         return check(args);
+    if (args.command === "tags")
+        return tags(args);
+    if (args.command === "ghost")
+        return ghost(args);
     if (args.command === "version") {
         console.log(VERSION);
         return 0;

package/dist/ghost.d.ts

@@ -0,0 +1,61 @@
+import { type ObsBrief } from "./obs.js";
+export interface GhostPost {
+    id: string;
+    slug: string;
+    title: string;
+    url: string;
+    updated_at: string;
+    codeinjection_head: string | null;
+    plaintext?: string | null;
+}
+export type FetchLike = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    json(): Promise<unknown>;
+    text(): Promise<string>;
+}>;
+export interface GhostConfig {
+    /** The site's address, such as https://example.com. */
+    url: string;
+    /** An Admin API key, "id:secret". */
+    key: string;
+    fetch?: FetchLike;
+    now?: () => number;
+}
+/** A short-lived token for Ghost's Admin API, signed with the key's secret. */
+export declare function ghostToken(key: string, nowMs?: number): string;
+export declare class Ghost {
+    private readonly config;
+    private readonly base;
+    private readonly fetcher;
+    constructor(config: GhostConfig);
+    private call;
+    /** Every published post, with its plain text. */
+    posts(slug?: string): Promise<GhostPost[]>;
+    /** Writes a post's Code injection header and nothing else. `updated_at` is Ghost's guard against overwriting a newer edit. */
+    setHead(post: GhostPost, head: string): Promise<void>;
+}
+/** The brief a post's Code injection header carries now, when it has usable tags. */
+export declare function briefInHead(head: string, url: string): ObsBrief | undefined;
+/**
+ * The header with the new block in place. Tags written by hand outside the
+ * markers are taken out first, so the page never carries two sets. Returns
+ * undefined when hand-written tags remain that this cannot safely move.
+ */
+export declare function headWith(head: string, block: string): string | undefined;
+export interface Line {
+    slug: string;
+    state: "written" | "would write" | "unchanged" | "draft" | "skipped" | "pulled" | "kept" | "error";
+    note?: string;
+}
+/** Writes one file per published post into `folder`. A file that already exists is never touched. */
+export declare function pull(ghost: Ghost, folder: string, slug?: string): Promise<Line[]>;
+/** Writes each approved file's tags into its post. A draft is never written. */
+export declare function push(ghost: Ghost, folder: string, options?: {
+    slug?: string;
+    dryRun?: boolean;
+}): Promise<Line[]>;

package/dist/ghost.js

@@ -0,0 +1,182 @@
+/**
+ * `openbriefing ghost pull` and `ghost push`: briefing files to and from a
+ * Ghost site, through its Admin API. Push writes one thing, the block between
+ * the obs:start and obs:end comments in a post's Code injection header.
+ *
+ * The key comes from the environment and is never printed.
+ */
+import { createHmac } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { JSDOM } from "jsdom";
+import { briefingFields, markTags, parseBriefing, postFile, readMarked, renderTags, replaceMarked } from "./briefing.js";
+import { fingerprint, parseObs } from "./obs.js";
+const b64url = (input) => Buffer.from(input).toString("base64url");
+/** A short-lived token for Ghost's Admin API, signed with the key's secret. */
+export function ghostToken(key, nowMs = Date.now()) {
+    const [id, secret] = key.split(":");
+    if (!id || !secret || !/^[0-9a-f]+$/iu.test(secret))
+        throw new Error("GHOST_ADMIN_API_KEY should look like id:secret, as Ghost shows it");
+    const iat = Math.floor(nowMs / 1000);
+    const head = b64url(JSON.stringify({ alg: "HS256", typ: "JWT", kid: id }));
+    const body = b64url(JSON.stringify({ iat, exp: iat + 300, aud: "/admin/" }));
+    const sig = createHmac("sha256", Buffer.from(secret, "hex")).update(`${head}.${body}`).digest("base64url");
+    return `${head}.${body}.${sig}`;
+}
+export class Ghost {
+    config;
+    base;
+    fetcher;
+    constructor(config) {
+        this.config = config;
+        this.base = `${config.url.replace(/\/+$/u, "")}/ghost/api/admin`;
+        this.fetcher = config.fetch ?? ((url, init) => fetch(url, init));
+    }
+    async call(method, path, body) {
+        const headers = {
+            authorization: `Ghost ${ghostToken(this.config.key, this.config.now?.() ?? Date.now())}`,
+            "accept-version": "v5.0",
+            accept: "application/json",
+        };
+        const init = { method, headers };
+        if (body !== undefined) {
+            headers["content-type"] = "application/json";
+            init.body = JSON.stringify(body);
+        }
+        const res = await this.fetcher(`${this.base}${path}`, init);
+        if (!res.ok) {
+            let detail = "";
+            try {
+                const err = (await res.json());
+                detail = err.errors?.[0]?.message ?? "";
+            }
+            catch {
+                /* the status says enough */
+            }
+            throw new Error(`Ghost answered ${res.status}${detail ? `: ${detail}` : ""}`);
+        }
+        return res.json();
+    }
+    /** Every published post, with its plain text. */
+    async posts(slug) {
+        const out = [];
+        const filter = slug ? `status:published+slug:${slug}` : "status:published";
+        for (let page = 1; page <= 200; page++) {
+            const res = (await this.call("GET", `/posts/?filter=${encodeURIComponent(filter)}&formats=plaintext&limit=50&page=${page}&order=${encodeURIComponent("published_at desc")}`));
+            out.push(...(res.posts ?? []));
+            if (page >= (res.meta?.pagination?.pages ?? 1))
+                break;
+        }
+        return out;
+    }
+    /** Writes a post's Code injection header and nothing else. `updated_at` is Ghost's guard against overwriting a newer edit. */
+    async setHead(post, head) {
+        await this.call("PUT", `/posts/${post.id}/`, { posts: [{ codeinjection_head: head, updated_at: post.updated_at }] });
+    }
+}
+const META_OBS = /[ \t]*<meta\s+(?:property|name)\s*=\s*"obs:[^"]*"\s+content\s*=\s*"[^"]*"\s*\/?>[ \t]*\r?\n?/giu;
+/** The brief a post's Code injection header carries now, when it has usable tags. */
+export function briefInHead(head, url) {
+    if (!/obs:/u.test(head))
+        return undefined;
+    return parseObs(new JSDOM(`<!doctype html><html><head>${head}</head><body></body></html>`, { url }).window.document, url).brief;
+}
+/**
+ * The header with the new block in place. Tags written by hand outside the
+ * markers are taken out first, so the page never carries two sets. Returns
+ * undefined when hand-written tags remain that this cannot safely move.
+ */
+export function headWith(head, block) {
+    const marked = readMarked(head);
+    if (marked !== undefined) {
+        const outside = head.replace(marked, "");
+        if (/obs:(?!start|end)/u.test(outside.replace(META_OBS, "")))
+            return undefined;
+        return replaceMarked(head.replace(marked, "\u0000").replace(META_OBS, "").replace("\u0000", () => marked), block);
+    }
+    const cleaned = head.replace(META_OBS, "");
+    if (/obs:/u.test(cleaned))
+        return undefined;
+    return replaceMarked(cleaned, block);
+}
+/** Ghost's slug shape. Anything else is never used as a file name or in a query. */
+const SLUG = /^[a-z0-9][a-z0-9_-]*$/iu;
+const briefingFiles = (folder) => readdirSync(folder)
+    .filter((f) => /\.(md|markdown|ya?ml)$/iu.test(f))
+    .sort();
+/** Writes one file per published post into `folder`. A file that already exists is never touched. */
+export async function pull(ghost, folder, slug) {
+    mkdirSync(folder, { recursive: true });
+    const lines = [];
+    if (slug !== undefined && !SLUG.test(slug))
+        return [{ slug, state: "error", note: "not a post slug" }];
+    for (const post of await ghost.posts(slug)) {
+        if (typeof post.slug !== "string" || !SLUG.test(post.slug)) {
+            lines.push({ slug: String(post.slug), state: "error", note: "the post's slug is not a plain slug, so no file is written" });
+            continue;
+        }
+        const path = join(folder, `${post.slug}.md`);
+        if (existsSync(path)) {
+            lines.push({ slug: post.slug, state: "kept", note: "the file is already here" });
+            continue;
+        }
+        // Tags already live on the post were approved by whoever put them there.
+        const live = briefInHead(post.codeinjection_head ?? "", post.url);
+        const obs = live ? briefingFields({ ...live, url: live.url ?? post.url }, "approved") : { url: post.url, status: "draft" };
+        writeFileSync(path, postFile({ slug: post.slug, title: post.title, obs }, post.plaintext ?? ""));
+        lines.push({ slug: post.slug, state: "pulled", note: live ? "with the tags the post already carries, as approved" : "a draft to fill in" });
+    }
+    return lines;
+}
+/** Writes each approved file's tags into its post. A draft is never written. */
+export async function push(ghost, folder, options = {}) {
+    const lines = [];
+    const files = briefingFiles(folder).filter((f) => options.slug === undefined || f.replace(/\.[^.]+$/u, "") === options.slug);
+    if (files.length === 0)
+        return lines;
+    const only = files.length === 1 ? files[0].replace(/\.[^.]+$/u, "") : undefined;
+    const posts = new Map((await ghost.posts(only !== undefined && SLUG.test(only) ? only : undefined)).map((p) => [p.slug, p]));
+    for (const file of files) {
+        const briefing = parseBriefing(readFileSync(join(folder, file), "utf8"));
+        const slug = briefing.slug ?? file.replace(/\.[^.]+$/u, "");
+        if (briefing.status !== "approved") {
+            lines.push({ slug, state: "draft", note: "not approved, so not written" });
+            continue;
+        }
+        if (!briefing.brief) {
+            lines.push({ slug, state: "error", note: briefing.errors.join("; ") });
+            continue;
+        }
+        const post = posts.get(slug);
+        if (!post) {
+            lines.push({ slug, state: "error", note: "no published post has this slug" });
+            continue;
+        }
+        const head = post.codeinjection_head ?? "";
+        const marked = readMarked(head);
+        const live = marked === undefined ? undefined : briefInHead(marked, post.url);
+        const next = headWith(head, markTags(renderTags(briefing.brief)));
+        if (next === undefined) {
+            lines.push({ slug, state: "skipped", note: "the post has obs: code outside the markers that is not a plain meta tag; move it by hand" });
+            continue;
+        }
+        const outside = marked === undefined ? head : head.replace(marked, "");
+        const stray = outside.replace(META_OBS, "") !== outside;
+        if (live && !stray && fingerprint(live) === fingerprint(briefing.brief)) {
+            lines.push({ slug, state: "unchanged" });
+            continue;
+        }
+        if (options.dryRun) {
+            lines.push({ slug, state: "would write" });
+            continue;
+        }
+        try {
+            await ghost.setHead(post, next);
+            lines.push({ slug, state: "written" });
+        }
+        catch (err) {
+            lines.push({ slug, state: "error", note: err instanceof Error ? err.message : String(err) });
+        }
+    }
+    return lines;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "openbriefing",
-  "version": "0.3.0",
-  "description": "Open Briefing Standard (OBS): the reference parser and checker for publishers' own summaries.",
+  "version": "0.4.0",
+  "description": "Open Briefing Standard (OBS): the reference parser, the checker and the publisher's tag tools for publishers' own summaries.",
   "keywords": [
     "open-briefing-standard",
     "obs",
@@ -26,6 +26,10 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./briefing": {
+      "types": "./dist/briefing.d.ts",
+      "import": "./dist/briefing.js"
+    },
     "./fetch": {
       "types": "./dist/fetch.d.ts",
       "import": "./dist/fetch.js"
@@ -52,7 +56,8 @@
     "prepack": "rm -rf fixtures && cp -R ../../spec/fixtures fixtures && npm run build"
   },
   "dependencies": {
-    "jsdom": "^26.1.0"
+    "jsdom": "^26.1.0",
+    "yaml": "^2.9.1"
   },
   "devDependencies": {
     "@types/jsdom": "^21.1.7",