openbriefing 0.2.0 → 0.4.0

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/dist/obs.d.ts

@@ -11,6 +11,8 @@ export declare const OBS_NS = "https://openbriefingstandard.org/ns#";
 export type ObsTier = "short" | "medium" | "long";
 export type DeriveMode = "verbatim" | "anchor" | "open";
 export type Preference = "summary" | "full";
+/** Where a brief's modified time came from (§13). */
+export type ModifiedFrom = "obs" | "article" | "feed" | "none";
 export interface ObsSummary {
     tier: ObsTier;
     text: string;
@@ -29,8 +31,10 @@ export interface ObsHighlight {
 }
 export interface ObsBrief {
     version: number;
-    /** obs:modified, as given (ISO 8601). */
-    modified: string;
+    /** The effective modified time, ISO 8601 (§13). Absent when no source gave one. */
+    modified?: string;
+    /** Where `modified` came from: obs:modified, article:modified_time, the feed item's date, or nowhere. */
+    modifiedFrom: ModifiedFrom;
     /** obs:url, normalized, when given. */
     url?: string;
     /** False when obs:url names content other than this page (§11). */
@@ -101,5 +105,19 @@ export declare function parseObs(doc: Document, pageUrl: string): ParseResult;
 export declare function parseFeedObs(item: Element, itemUrl?: string): ParseResult;
 /** Checks an object in the ObsBrief shape and rebuilds it under the same rules. */
 export declare function validateObs(input: unknown): ParseResult;
-/** The later obs:modified stands; on a tie, the page stands. */
+/**
+ * The later effective modified time stands. When the two are equal, or either
+ * side has none, the page stands.
+ */
 export declare function mergeObs(page?: ObsBrief, feed?: ObsBrief): ObsBrief | undefined;
+/**
+ * A stable hash of what a brief says: every text value and every setting, in a
+ * fixed order. Two briefs with the same fingerprint present the same. It leaves
+ * out the modified time, and everything that depends on where the tags were
+ * read rather than on what they say (the language fallback, describesThisPage,
+ * a highlight's inContent), so a page and its feed item agree. Readers compare
+ * fingerprints to tell a change, above all when there is no modified time.
+ *
+ * SHA-256 of the canonical JSON below, in hex, first 16 characters.
+ */
+export declare function fingerprint(brief: ObsBrief): string;

package/dist/obs.js

@@ -183,13 +183,22 @@ function build(bag, ctx, extraWarnings = []) {
                 warnings.push(`obs:version ${n} is newer than this reader (v1); unknown tags are ignored`);
         }
     }
-    // obs:modified (required)
-    const modified = first(bag, "obs:modified", warnings)?.trim();
-    if (modified === undefined || modified === "") {
-        errors.push("obs:modified is missing; it is required (§3)");
+    // The effective modified time (§13): obs:modified, else the carrier's own date, else none.
+    let modified;
+    let modifiedFrom = "none";
+    const rawModified = first(bag, "obs:modified", warnings)?.trim();
+    if (rawModified !== undefined && rawModified !== "") {
+        if (validModified(rawModified)) {
+            modified = rawModified;
+            modifiedFrom = "obs";
+        }
+        else {
+            warnings.push(`obs:modified: "${rawModified}" is not an ISO 8601 date and time; it is ignored (§13)`);
+        }
     }
-    else if (!validModified(modified)) {
-        errors.push(`obs:modified: "${modified}" is not an ISO 8601 date and time (§3)`);
+    if (modified === undefined && ctx.alt !== undefined && validModified(ctx.alt.value)) {
+        modified = ctx.alt.value;
+        modifiedFrom = ctx.alt.from;
     }
     // Summaries (§4)
     const tiered = new Map();
@@ -283,7 +292,8 @@ function build(bag, ctx, extraWarnings = []) {
     }
     const brief = {
         version,
-        modified: modified,
+        ...(modified !== undefined ? { modified } : {}),
+        modifiedFrom,
         describesThisPage,
         summaries,
         keep,
@@ -341,6 +351,17 @@ function guard(fn) {
 }
 // ---------------------------------------------------------------------------
 // Pages (§3.1)
+function metaContent(doc, key) {
+    for (const meta of Array.from(doc.getElementsByTagName("meta"))) {
+        const k = (meta.getAttribute("property") ?? meta.getAttribute("name") ?? "").trim().toLowerCase();
+        if (k !== key)
+            continue;
+        const v = meta.getAttribute("content")?.trim();
+        if (v)
+            return v;
+    }
+    return undefined;
+}
 /**
  * Reads a page's obs: meta tags. `pageUrl` is where the page was fetched
  * from; the page's <link rel="canonical"> takes precedence for §11.
@@ -361,6 +382,10 @@ export function parseObs(doc, pageUrl) {
                 continue;
             if (!inBody && doc.body && doc.body.contains(meta))
                 inBody = true;
+            // An unescaped double quote ends the attribute early; the rest becomes attributes with a quote in their names.
+            if (Array.from(meta.attributes).some((a) => a.name.includes('"'))) {
+                warnings.push(`${key}: the value is cut short at a double quote; write a double quote inside a value as &quot; (§9)`);
+            }
             collect(bag, key, content, warnings);
         }
         if (isEmpty(bag))
@@ -375,6 +400,9 @@ export function parseObs(doc, pageUrl) {
             ctx.canonical = canonical;
         if (lang !== undefined)
             ctx.lang = lang;
+        const articleModified = metaContent(doc, "article:modified_time");
+        if (articleModified !== undefined)
+            ctx.alt = { value: articleModified, from: "article" };
         const result = build(bag, ctx, warnings);
         if (result.brief)
             checkContent(result.brief, doc.body?.textContent ?? undefined, result.warnings);
@@ -413,6 +441,24 @@ function itemLink(item) {
     }
     return undefined;
 }
+/** The item's own date (§13): Atom <updated>, or RSS <pubDate> turned into ISO 8601. */
+function itemDate(item) {
+    for (const el of Array.from(item.children)) {
+        if (el.namespaceURI === OBS_NS)
+            continue;
+        const text = el.textContent?.trim();
+        if (!text)
+            continue;
+        if (el.localName === "updated" && validModified(text))
+            return text;
+        if (el.localName === "pubDate") {
+            const ms = Date.parse(text);
+            if (!Number.isNaN(ms))
+                return new Date(ms).toISOString();
+        }
+    }
+    return undefined;
+}
 /**
  * Reads the OBS elements of one RSS <item> or Atom <entry>. `itemUrl`
  * overrides the item's own link when given.
@@ -460,6 +506,9 @@ export function parseFeedObs(item, itemUrl) {
         const ctx = {};
         if (canonical !== undefined)
             ctx.canonical = canonical;
+        const date = itemDate(item);
+        if (date !== undefined)
+            ctx.alt = { value: date, from: "feed" };
         return build(bag, ctx, warnings);
     });
 }
@@ -482,7 +531,14 @@ export function validateObs(input) {
             else if (v !== undefined && v !== null)
                 warnings.push(`${key} is not a string; it is ignored`);
         };
-        set("obs:modified", o.modified);
+        // A modified time that came from the carrier is carried through with its source.
+        const ctx = {};
+        if ((o.modifiedFrom === "article" || o.modifiedFrom === "feed") && typeof o.modified === "string") {
+            ctx.alt = { value: o.modified, from: o.modifiedFrom };
+        }
+        else {
+            set("obs:modified", o.modified);
+        }
         if (typeof o.version === "number")
             put(bag, "obs:version", String(o.version));
         set("obs:url", o.url);
@@ -540,7 +596,9 @@ export function validateObs(input) {
             if (typeof d.combine === "boolean")
                 put(bag, "obs:derive:combine", d.combine ? "yes" : "no");
         }
-        const result = build(bag, {}, warnings);
+        if (isEmpty(bag))
+            return { errors: ["No summary: obs:summary or a tiered summary is required (§3)"], warnings };
+        const result = build(bag, ctx, warnings);
         if (result.brief && typeof o.describesThisPage === "boolean") {
             result.brief.describesThisPage = o.describesThisPage;
         }
@@ -549,11 +607,121 @@ export function validateObs(input) {
 }
 // ---------------------------------------------------------------------------
 // Feed against page (§14)
-/** The later obs:modified stands; on a tie, the page stands. */
+/**
+ * The later effective modified time stands. When the two are equal, or either
+ * side has none, the page stands.
+ */
 export function mergeObs(page, feed) {
     if (!page)
         return feed;
     if (!feed)
         return page;
+    if (page.modified === undefined || feed.modified === undefined)
+        return page;
     return Date.parse(feed.modified) > Date.parse(page.modified) ? feed : page;
 }
+// ---------------------------------------------------------------------------
+// Change detection (§13)
+/**
+ * A stable hash of what a brief says: every text value and every setting, in a
+ * fixed order. Two briefs with the same fingerprint present the same. It leaves
+ * out the modified time, and everything that depends on where the tags were
+ * read rather than on what they say (the language fallback, describesThisPage,
+ * a highlight's inContent), so a page and its feed item agree. Readers compare
+ * fingerprints to tell a change, above all when there is no modified time.
+ *
+ * SHA-256 of the canonical JSON below, in hex, first 16 characters.
+ */
+export function fingerprint(brief) {
+    const canonical = JSON.stringify([
+        "obs1",
+        brief.version,
+        brief.url ?? null,
+        brief.title ?? null,
+        brief.headline ?? null,
+        brief.summaries.map((s) => [s.tier, s.text]),
+        brief.keep,
+        brief.highlights.map((h) => [h.text, h.label ?? null]),
+        [brief.derive.mode, brief.derive.translate, brief.derive.combine],
+        brief.attribution ?? null,
+        brief.preference,
+    ]);
+    return sha256Hex(utf8(canonical)).slice(0, 16);
+}
+/** UTF-8 bytes, without TextEncoder so the module needs no platform API. */
+function utf8(text) {
+    const out = [];
+    for (const ch of text) {
+        const c = ch.codePointAt(0);
+        if (c < 0x80)
+            out.push(c);
+        else if (c < 0x800)
+            out.push(0xc0 | (c >> 6), 0x80 | (c & 63));
+        else if (c < 0x10000)
+            out.push(0xe0 | (c >> 12), 0x80 | ((c >> 6) & 63), 0x80 | (c & 63));
+        else
+            out.push(0xf0 | (c >> 18), 0x80 | ((c >> 12) & 63), 0x80 | ((c >> 6) & 63), 0x80 | (c & 63));
+    }
+    return out;
+}
+const SHA_K = [
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+    0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+    0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+    0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+    0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+    0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+    0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+];
+/** SHA-256 (FIPS 180-4), synchronous, so fingerprint() is too. */
+function sha256Hex(bytes) {
+    const h = [0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19];
+    const bits = bytes.length * 8;
+    const msg = bytes.slice();
+    msg.push(0x80);
+    while (msg.length % 64 !== 56)
+        msg.push(0);
+    const hi = Math.floor(bits / 0x100000000);
+    const lo = bits >>> 0;
+    msg.push((hi >>> 24) & 255, (hi >>> 16) & 255, (hi >>> 8) & 255, hi & 255, (lo >>> 24) & 255, (lo >>> 16) & 255, (lo >>> 8) & 255, lo & 255);
+    const w = new Array(64).fill(0);
+    const rotr = (x, n) => (x >>> n) | (x << (32 - n));
+    for (let i = 0; i < msg.length; i += 64) {
+        for (let t = 0; t < 16; t++)
+            w[t] = ((msg[i + t * 4] << 24) | (msg[i + t * 4 + 1] << 16) | (msg[i + t * 4 + 2] << 8) | msg[i + t * 4 + 3]) >>> 0;
+        for (let t = 16; t < 64; t++) {
+            const a = w[t - 15];
+            const b = w[t - 2];
+            const s0 = rotr(a, 7) ^ rotr(a, 18) ^ (a >>> 3);
+            const s1 = rotr(b, 17) ^ rotr(b, 19) ^ (b >>> 10);
+            w[t] = (w[t - 16] + s0 + w[t - 7] + s1) >>> 0;
+        }
+        let [a, b, c, d, e, f, g, k] = h;
+        for (let t = 0; t < 64; t++) {
+            const S1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+            const ch = (e & f) ^ (~e & g);
+            const t1 = (k + S1 + ch + SHA_K[t] + w[t]) >>> 0;
+            const S0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+            const maj = (a & b) ^ (a & c) ^ (b & c);
+            const t2 = (S0 + maj) >>> 0;
+            k = g;
+            g = f;
+            f = e;
+            e = (d + t1) >>> 0;
+            d = c;
+            c = b;
+            b = a;
+            a = (t1 + t2) >>> 0;
+        }
+        h[0] = (h[0] + a) >>> 0;
+        h[1] = (h[1] + b) >>> 0;
+        h[2] = (h[2] + c) >>> 0;
+        h[3] = (h[3] + d) >>> 0;
+        h[4] = (h[4] + e) >>> 0;
+        h[5] = (h[5] + f) >>> 0;
+        h[6] = (h[6] + g) >>> 0;
+        h[7] = (h[7] + k) >>> 0;
+    }
+    return h.map((x) => x.toString(16).padStart(8, "0")).join("");
+}