@hadoku/service-kernel 0.0.0-stage → 0.1.4

package/dist/erase/erase.js

@@ -0,0 +1,72 @@
+/**
+ * Account deletion's erase hook (hadoku_site IDENTITY_MODEL R12, "Erase hooks"; the caller is
+ * edge-router's `eraseMemberData`, which runs it on account delete and on the merged-away side of
+ * an account merge).
+ *
+ * The edge calls it with its own seal and `X-User-Id`, and wants 200 `{ erased: { <what>: <count> } }`
+ * back, zeros on a second call. Anything else fails the whole delete, which the edge retries, so a
+ * step that throws answers 500 rather than a partial count.
+ *
+ * Only the seal admits it — `edgeSealed` is an injected check, never a tier: this module knows no
+ * app's edge-auth binding. `deriveParticipantId` is likewise injected: the id a person is also
+ * known by (the `fk:`/`dev:`/`eph:` scheme, whichever app provides it) is platform but app-bound,
+ * not this kernel's to import.
+ *
+ * What is erased is a list of steps each store registers where it is built (`register`), so a
+ * store and its erase live side by side in the app. Steps run one at a time, in registration
+ * order, so two never rewrite one file at once.
+ */
+import { placeholderId } from "./anonymise.js";
+import { reportSealRefused } from "../telemetry/telemetry.js";
+/** `/api/_account/erase` — the one path every app answers this hook on. */
+export const ERASE_PATH = '/api/_account/erase';
+export function personOf(userId, deriveParticipantId) {
+    const participantId = deriveParticipantId(userId);
+    return { userId, participantId, ids: new Set([userId, participantId]), placeholder: placeholderId() };
+}
+export function createAccountErase(opts) {
+    const steps = [];
+    const erase = async (userId) => {
+        const person = personOf(userId, opts.deriveParticipantId);
+        const erased = {};
+        for (const step of steps) {
+            const counts = await step.erase(person);
+            if (typeof counts === 'number')
+                erased[step.what] = counts;
+            else
+                Object.assign(erased, counts);
+        }
+        return erased;
+    };
+    return {
+        register(step) {
+            if (steps.some((s) => s.what === step.what))
+                throw new Error(`erase step '${step.what}' is registered twice`);
+            steps.push(step);
+        },
+        erase,
+        async handle(req, res) {
+            if (!opts.edgeSealed(req)) {
+                reportSealRefused('http', req.headers, req.path);
+                res.status(401).json({ error: "erase needs the edge's seal" });
+                return;
+            }
+            const raw = req.headers['x-user-id'];
+            const userId = typeof raw === 'string' ? raw.trim() : '';
+            if (userId === '') {
+                res.status(400).json({ error: 'X-User-Id: whose data to erase' });
+                return;
+            }
+            try {
+                const erased = await erase(userId);
+                opts.log({ evt: 'account-erased', userId, erased });
+                res.json({ erased });
+            }
+            catch (err) {
+                const reason = err instanceof Error ? err.message : String(err);
+                opts.log({ evt: 'account-erase-failed', userId, reason });
+                res.status(500).json({ error: reason });
+            }
+        },
+    };
+}

package/dist/erase/index.d.ts

@@ -0,0 +1,2 @@
+export { placeholderId, replaceIds } from './anonymise.js';
+export { createAccountErase, ERASE_PATH, personOf, type AccountErase, type AccountEraseOptions, type EraseCounts, type ErasedPerson, type EraseStep, } from './erase.js';

package/dist/erase/index.js

@@ -0,0 +1,2 @@
+export { placeholderId, replaceIds } from "./anonymise.js";
+export { createAccountErase, ERASE_PATH, personOf, } from "./erase.js";

package/dist/health/health.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The `/health` body, hadoku health v1: `status` ("ok" | "degraded"), `service`
+ * (this app's id in hadoku_site's scripts/child-apps.json) and `commit` (the git
+ * sha of the running code). mgmt-api's deploy probe compares `commit` with the
+ * sha it just deployed, so it must be the checkout's HEAD, never a guess.
+ */
+/** The commit, or null plus why it could not be read. Never a placeholder sha. */
+export type Commit = {
+    commit: string;
+    commit_error?: undefined;
+} | {
+    commit: null;
+    commit_error: string;
+};
+/**
+ * `git rev-parse HEAD` in `repoRoot`, read once at boot by the caller: a deploy
+ * restarts the process, so the checkout cannot move under a running server.
+ * Each instance reads its OWN checkout (an app's prod and its PPE are two).
+ */
+export declare function readCommit(repoRoot: string): Commit;
+/**
+ * The instance's child-apps id, from the prefix the edge serves it under:
+ * `/cardtable` is `cardtable`, `/cardtable-ppe` is `cardtable-ppe`. Both
+ * instances run this same code, and the prefix is the one setting that
+ * child-apps.json gives each of them differently. `fallback` is the app's own
+ * id, used only when the prefix is empty (dev, or a misconfigured deploy).
+ */
+export declare function serviceIdOf(basePrefix: string, fallback: string): string;
+export interface HealthInput {
+    service: string;
+    commit: Commit;
+    /** The base-path verdict (the app's own bundle/base-path check); `ok: false` is the one not-ready state. */
+    bundle: {
+        ok: boolean;
+        reason: string;
+    };
+}
+/** The HTTP status and body `/health` answers. */
+export declare function healthResponse({ service, commit, bundle }: HealthInput, now?: Date): {
+    code: number;
+    body: Record<string, unknown>;
+};

package/dist/health/health.js

@@ -0,0 +1,52 @@
+/**
+ * The `/health` body, hadoku health v1: `status` ("ok" | "degraded"), `service`
+ * (this app's id in hadoku_site's scripts/child-apps.json) and `commit` (the git
+ * sha of the running code). mgmt-api's deploy probe compares `commit` with the
+ * sha it just deployed, so it must be the checkout's HEAD, never a guess.
+ */
+import { execFileSync } from 'node:child_process';
+/**
+ * `git rev-parse HEAD` in `repoRoot`, read once at boot by the caller: a deploy
+ * restarts the process, so the checkout cannot move under a running server.
+ * Each instance reads its OWN checkout (an app's prod and its PPE are two).
+ */
+export function readCommit(repoRoot) {
+    try {
+        const sha = execFileSync('git', ['-C', repoRoot, 'rev-parse', 'HEAD'], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+            timeout: 5_000,
+        }).trim();
+        if (/^[0-9a-f]{40,64}$/.test(sha))
+            return { commit: sha };
+        return { commit: null, commit_error: `git rev-parse HEAD in ${repoRoot} printed ${JSON.stringify(sha.slice(0, 80))}, not a sha` };
+    }
+    catch (err) {
+        const stderr = err.stderr;
+        const why = typeof stderr === 'string' && stderr.trim() ? stderr.trim() : err instanceof Error ? err.message : String(err);
+        return { commit: null, commit_error: `git rev-parse HEAD in ${repoRoot} failed: ${why.slice(0, 200)}` };
+    }
+}
+/**
+ * The instance's child-apps id, from the prefix the edge serves it under:
+ * `/cardtable` is `cardtable`, `/cardtable-ppe` is `cardtable-ppe`. Both
+ * instances run this same code, and the prefix is the one setting that
+ * child-apps.json gives each of them differently. `fallback` is the app's own
+ * id, used only when the prefix is empty (dev, or a misconfigured deploy).
+ */
+export function serviceIdOf(basePrefix, fallback) {
+    return basePrefix.replace(/^\/+|\/+$/g, '') || fallback;
+}
+/** The HTTP status and body `/health` answers. */
+export function healthResponse({ service, commit, bundle }, now = new Date()) {
+    const body = {
+        status: bundle.ok ? 'ok' : 'degraded',
+        service,
+        commit: commit.commit,
+        ...(commit.commit === null ? { commit_error: commit.commit_error } : {}),
+        ...(bundle.ok ? {} : { reason: `the UI bundle is not servable (bundle: ${bundle.reason})` }),
+        bundle: bundle.reason,
+        timestamp: now.toISOString(),
+    };
+    return { code: bundle.ok ? 200 : 503, body };
+}

package/dist/health/index.d.ts

@@ -0,0 +1 @@
+export { healthResponse, readCommit, serviceIdOf, type Commit, type HealthInput } from './health.js';

package/dist/health/index.js

@@ -0,0 +1 @@
+export { healthResponse, readCommit, serviceIdOf } from "./health.js";

package/dist/http/index.d.ts

@@ -0,0 +1,123 @@
+/**
+ * The one handshake gate, the base-path contract, and the origin stamp — the
+ * HTTP-and-sockets half of the platform's edge auth. Knows no game: the
+ * surface label a refusal is reported under, the app's display name and
+ * embed-bundle filenames, and the functions that read its tier ladder and its
+ * secret are all supplied by the app that binds this module.
+ */
+import type { IncomingMessage, Server } from 'node:http';
+import type { NextFunction, Request, Response } from 'express';
+import type { Server as SocketIOServer } from 'socket.io';
+/** The app's own label for a `seal-refused` report, e.g. `'http' | 'draft-socket'`. */
+export type GateSurface = string;
+/** `minTier`: the app's configured floor. `surface`: the `reportSealRefused` label. */
+export interface GateOptions {
+    minTier: string;
+    surface: GateSurface;
+}
+/** `reportSealRefused`'s own shape — the app supplies the implementation. */
+export type SealRefusedReporter = (surface: GateSurface, headers: Record<string, unknown>, path: string | null) => void;
+export interface GateDeps {
+    /** Sanitize `headers` in place against edge provenance (the app's `createEdgeAuth(...).sanitizeHeaders`). */
+    sanitizeHeaders(headers: Record<string, unknown>): void;
+    /** Express/engine.io middleware that does the same, for a socket's handshake (the app's `createEdgeAuth(...).edgeProvenance`). */
+    edgeProvenance(req: Request, res: Response, next: NextFunction): void;
+    /** The app's own `tierOf` (its auth binding's, so a verified-member promotion if any applies). */
+    tierOf(req: Request): string;
+    rankOf(tier: string): number;
+    reportSealRefused: SealRefusedReporter;
+    /** The app's configured floor for `requireMinTier`, read live (HTTP has one fixed floor; sockets and upgrades take their own per call). */
+    minTier(): string;
+}
+export interface Gate {
+    /** Sanitize `headers` in place against edge provenance, then rank the result against `minTier`. */
+    floor(headers: Record<string, unknown>, minTier: string): {
+        ok: boolean;
+        tier: string;
+    };
+    /** Provenance + the floor on a socket.io handshake. `next(new Error('not found'))` is the client's `connect_error`. */
+    gateSocketIo(io: SocketIOServer, opts: GateOptions): void;
+    /** The floor for a raw upgrade: no middleware chain runs, so the caller answers the refusal itself. */
+    gateUpgrade(req: IncomingMessage, opts: GateOptions): {
+        ok: boolean;
+        tier: string;
+    };
+    /**
+     * Express middleware: refuse anything below the configured floor. 404, not
+     * 403 — a private app should not confirm its own existence to a caller who
+     * was never meant to reach it.
+     */
+    requireMinTier(req: Request, res: Response, next: NextFunction): void;
+}
+/** One gate, bound to an app's auth functions and its `reportSealRefused`. */
+export declare function createGate(deps: GateDeps): Gate;
+/**
+ * This is the one thing about a loopback-UI app that breaks SILENTLY, so it is
+ * the one thing a server built this way refuses to guess about.
+ *
+ * The edge gives us stripPrefix: hadoku.me/<app>/assets/x.js arrives here as
+ * /assets/x.js, which we serve happily. But the BROWSER is at
+ * hadoku.me/<app>/, so a bundle built with the default base emits
+ * `src="/assets/x.js"` — an absolute URL with no prefix. The browser asks the
+ * edge for hadoku.me/assets/x.js, which is not this app's route, and the page
+ * renders blank with a 404 in the console and a 200 on every server-side probe.
+ *
+ * So: compare them here, once, at boot, and say precisely what to change.
+ *
+ * ## Reading the file is not serving it
+ *
+ * `checkBasePath` proves index.html exists and is built right. It does not
+ * prove the server can HAND IT OUT, and those came apart in practice: express's
+ * `res.sendFile` goes through `send`, whose default `dotfiles: 'ignore'` refuses
+ * any absolute path with a segment starting with `.` — so a server started from
+ * a dot-segment path (every agent worktree) answered every page with a 404
+ * while `readFileSync` read the same file happily and `/health` said `healthy`.
+ *
+ * So `checkBundle` finishes by asking the serving mechanism itself: it mounts
+ * `sendIndex` — the exact function the SPA fallback uses — on a throwaway
+ * loopback server and fetches it. If that is not a 200, the verdict is
+ * `unservable`. It deliberately does not special-case dot segments: any future
+ * reason `sendFile` refuses the file fails the same way.
+ */
+export interface BasePathVerdict {
+    ok: boolean;
+    /** 'ok' | 'missing' | 'unprefixed' | 'unservable' — machine-readable for /health. */
+    reason: 'ok' | 'missing' | 'unprefixed' | 'unservable';
+    /** Root-relative URLs in index.html that do not carry the prefix. */
+    offenders: string[];
+    detail: string;
+}
+/**
+ * @param indexHtmlPath absolute path to the built index.html
+ * @param basePrefix e.g. `/cardtable` (no trailing slash)
+ */
+export declare function checkBasePath(indexHtmlPath: string, basePrefix: string): BasePathVerdict;
+export declare function isEmbedEntry(filePath: string, embedEntries: readonly string[]): boolean;
+/**
+ * Serve index.html. The ONE place a page leaves this server, shared by the SPA
+ * fallback and by `probeIndex`, so the probe cannot drift from what it vouches
+ * for: change an option here and the boot check changes with it.
+ */
+export declare function sendIndex(res: Response, indexHtmlPath: string, done: (err?: Error) => void): void;
+/**
+ * The HTTP status `sendIndex` actually produces for this file, measured over a
+ * real loopback request rather than predicted — `send`'s refusals are decided
+ * inside `send`, and re-deriving its rules here would be a second copy of them.
+ */
+export declare function probeIndex(indexHtmlPath: string): Promise<number>;
+/**
+ * The whole boot verdict: built right (`checkBasePath`) AND servable
+ * (`probeIndex`). This, not `checkBasePath` alone, is what `/health` should report.
+ */
+export declare function checkBundle(indexHtmlPath: string, basePrefix: string): Promise<BasePathVerdict>;
+/** The page served in place of a bundle that would render blank. */
+export declare function diagnosticPage(verdict: BasePathVerdict, basePrefix: string, appName: string): string;
+/**
+ * Every response a server built this way sends carries this header, so the
+ * edge can tell "nothing is listening yet" (a 502 worth holding through a
+ * restart) from an answer the app itself produced (a 502 of its own, which
+ * must reach the browser at once). Set at the socket level so it covers
+ * express, socket.io's polling and every error path alike.
+ */
+export declare const ORIGIN_HEADER = "X-Hadoku-Origin";
+export declare function stampOrigin(server: Server, originValue: string): void;

package/dist/http/index.js

@@ -0,0 +1,192 @@
+/**
+ * The one handshake gate, the base-path contract, and the origin stamp — the
+ * HTTP-and-sockets half of the platform's edge auth. Knows no game: the
+ * surface label a refusal is reported under, the app's display name and
+ * embed-bundle filenames, and the functions that read its tier ladder and its
+ * secret are all supplied by the app that binds this module.
+ */
+import { readFileSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { sep } from 'node:path';
+import express from 'express';
+/** One gate, bound to an app's auth functions and its `reportSealRefused`. */
+export function createGate(deps) {
+    function floor(headers, minTier) {
+        deps.sanitizeHeaders(headers);
+        const tier = deps.tierOf({ headers });
+        return { ok: deps.rankOf(tier) >= deps.rankOf(minTier), tier };
+    }
+    function gateSocketIo(io, opts) {
+        io.engine.use(deps.edgeProvenance);
+        io.use((socket, next) => {
+            const result = floor(socket.request.headers, opts.minTier);
+            if (!result.ok) {
+                deps.reportSealRefused(opts.surface, socket.request.headers, null);
+                next(new Error('not found'));
+                return;
+            }
+            next();
+        });
+    }
+    function gateUpgrade(req, opts) {
+        const result = floor(req.headers, opts.minTier);
+        if (!result.ok)
+            deps.reportSealRefused(opts.surface, req.headers, req.url ?? null);
+        return result;
+    }
+    function requireMinTier(req, res, next) {
+        if (floor(req.headers, deps.minTier()).ok)
+            return next();
+        deps.reportSealRefused('http', req.headers, req.path);
+        res.status(404).type('text/plain').send('not found');
+    }
+    return { floor, gateSocketIo, gateUpgrade, requireMinTier };
+}
+/** `src="/…"` / `href="/…"` — root-relative only. Protocol-relative `//` is not ours. */
+const ROOT_RELATIVE = /(?:src|href)\s*=\s*"(\/(?!\/)[^"]*)"/g;
+const BASE_HREF = /<base\b[^>]*\bhref\s*=\s*"([^"]*)"/i;
+/**
+ * Root-relative URLs that are MEANT for the site root: hadoku.me itself serves
+ * them, for every app, so resolving them against the root is the intent rather
+ * than the drift this check exists to catch. Exact paths, never a prefix — a
+ * pattern here would wave through the very assets this guards.
+ */
+const SITE_ROOT_URLS = new Set(['/favicon.svg']);
+/**
+ * @param indexHtmlPath absolute path to the built index.html
+ * @param basePrefix e.g. `/cardtable` (no trailing slash)
+ */
+export function checkBasePath(indexHtmlPath, basePrefix) {
+    let html;
+    try {
+        html = readFileSync(indexHtmlPath, 'utf8');
+    }
+    catch {
+        return {
+            ok: false,
+            reason: 'missing',
+            offenders: [],
+            detail: `No built bundle at ${indexHtmlPath}. Run the child repo's build (it must emit index.html plus its assets into this directory).`,
+        };
+    }
+    const wanted = basePrefix.endsWith('/') ? basePrefix : `${basePrefix}/`;
+    // A <base href> that already points at the prefix rebases every relative URL
+    // in the document, so root-relative stragglers are the only remaining risk —
+    // and <base> does NOT rebase those. Check them either way.
+    const declaredBase = BASE_HREF.exec(html)?.[1];
+    const offenders = [];
+    for (const m of html.matchAll(ROOT_RELATIVE)) {
+        const url = m[1];
+        if (url === wanted || url.startsWith(wanted) || SITE_ROOT_URLS.has(url))
+            continue;
+        offenders.push(url);
+    }
+    if (offenders.length > 0) {
+        return {
+            ok: false,
+            reason: 'unprefixed',
+            offenders,
+            detail: `index.html emits ${offenders.length} root-relative URL(s) that do not start with "${wanted}". ` +
+                `The browser is at hadoku.me${wanted} and will resolve them against the site root, not this app. ` +
+                `Fix it where the bundle is BUILT — for Vite that is \`base: '${wanted}'\` in vite.config.ts — ` +
+                `not by adding a rewrite here.` +
+                (declaredBase && declaredBase !== wanted
+                    ? ` (index.html also declares <base href="${declaredBase}">, which disagrees with the edge's stripPrefix "${basePrefix}".)`
+                    : ''),
+        };
+    }
+    return { ok: true, reason: 'ok', offenders: [], detail: `base path "${wanted}" verified` };
+}
+export function isEmbedEntry(filePath, embedEntries) {
+    return embedEntries.some((name) => filePath.endsWith(`${sep}embed${sep}${name}`));
+}
+/**
+ * Serve index.html. The ONE place a page leaves this server, shared by the SPA
+ * fallback and by `probeIndex`, so the probe cannot drift from what it vouches
+ * for: change an option here and the boot check changes with it.
+ */
+export function sendIndex(res, indexHtmlPath, done) {
+    res.set('Cache-Control', 'no-store').type('html').sendFile(indexHtmlPath, (err) => done(err));
+}
+/**
+ * The HTTP status `sendIndex` actually produces for this file, measured over a
+ * real loopback request rather than predicted — `send`'s refusals are decided
+ * inside `send`, and re-deriving its rules here would be a second copy of them.
+ */
+export async function probeIndex(indexHtmlPath) {
+    const probe = express();
+    probe.get('/', (_req, res, next) => sendIndex(res, indexHtmlPath, (err) => err && next(err)));
+    // A refusal is the expected outcome being measured, not a fault: answer with
+    // send's status and keep express's default handler from printing a stack.
+    probe.use((err, _req, res, _next) => {
+        res.status(err.status ?? 500).end();
+    });
+    const server = createServer(probe);
+    await new Promise((resolveListen) => server.listen(0, '127.0.0.1', resolveListen));
+    try {
+        const { port } = server.address();
+        const answer = await fetch(`http://127.0.0.1:${port}/`);
+        await answer.arrayBuffer();
+        return answer.status;
+    }
+    finally {
+        await new Promise((resolveClose) => server.close(() => resolveClose()));
+    }
+}
+/**
+ * The whole boot verdict: built right (`checkBasePath`) AND servable
+ * (`probeIndex`). This, not `checkBasePath` alone, is what `/health` should report.
+ */
+export async function checkBundle(indexHtmlPath, basePrefix) {
+    const built = checkBasePath(indexHtmlPath, basePrefix);
+    if (!built.ok)
+        return built;
+    const status = await probeIndex(indexHtmlPath);
+    if (status === 200)
+        return built;
+    const dotSegments = indexHtmlPath.split(sep).filter((part) => part.startsWith('.') && part.length > 1);
+    return {
+        ok: false,
+        reason: 'unservable',
+        offenders: [],
+        detail: `index.html is at ${indexHtmlPath} and reads fine, but serving it answered ${status}. ` +
+            (dotSegments.length > 0
+                ? `The path has a dot-segment (${dotSegments.join(', ')}), and express's sendFile refuses those ` +
+                    `(send's dotfiles: 'ignore'). Run the server from a copy outside it — an e2e harness usually does.`
+                : `express's sendFile refused a file that exists; check its permissions and sendIndex's options.`),
+    };
+}
+/** The page served in place of a bundle that would render blank. */
+export function diagnosticPage(verdict, basePrefix, appName) {
+    const list = verdict.offenders.length > 0
+        ? `<ul>${verdict.offenders
+            .slice(0, 12)
+            .map((u) => `<li><code>${escapeHtml(u)}</code></li>`)
+            .join('')}</ul>`
+        : '';
+    return `<!doctype html><meta charset=utf-8><title>${escapeHtml(appName)} — not serving</title>
+<style>body{font:15px/1.6 system-ui,Segoe UI,Roboto,sans-serif;background:#15171c;color:#e7e9ee;margin:0;padding:40px;display:flex;justify-content:center}
+main{max-width:720px}h1{font-size:19px;font-weight:600}code{background:#22252c;padding:2px 6px;border-radius:4px}
+p.why{color:#9aa3b2}</style>
+<main><h1>${escapeHtml(appName)} is running, but its bundle would not load</h1>
+<p>${escapeHtml(verdict.detail)}</p>${list}
+<p class=why>Served by the ${escapeHtml(appName.toLowerCase())} loopback server on behalf of <code>${escapeHtml(basePrefix)}/</code>.
+This page exists so the failure is visible: the alternative is a blank page and a green health check.</p></main>`;
+}
+function escapeHtml(s) {
+    return s.replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]);
+}
+/* ── The origin stamp ──────────────────────────────────────────────────── */
+/**
+ * Every response a server built this way sends carries this header, so the
+ * edge can tell "nothing is listening yet" (a 502 worth holding through a
+ * restart) from an answer the app itself produced (a 502 of its own, which
+ * must reach the browser at once). Set at the socket level so it covers
+ * express, socket.io's polling and every error path alike.
+ */
+export const ORIGIN_HEADER = 'X-Hadoku-Origin';
+export function stampOrigin(server, originValue) {
+    server.prependListener('request', (_req, res) => {
+        res.setHeader(ORIGIN_HEADER, originValue);
+    });
+}

package/dist/lifecycle/announce.d.ts

@@ -0,0 +1,74 @@
+import type { JsonLog } from '../log/log.js';
+export interface ReleaseNotes {
+    version: string;
+    title: string;
+    body: string;
+}
+export interface Embed {
+    title?: string;
+    description: string;
+    url: string;
+    color: number;
+}
+/**
+ * How release-notes file names are ordered: the kernel knows no directory layout of its own, so
+ * the app supplies this (cardtable's adapter binds `scripts/release/build-version.ts`).
+ */
+export interface ReleaseOrdering {
+    /** The newest release file name among `names`, or null when there is none. */
+    newest(names: readonly string[]): string | null;
+    /** Every release file name among `names`, newest first. */
+    newestFirst(names: readonly string[]): string[];
+}
+/** The newest release notes in `dir`, by `ordering`, or null when there are none. */
+export declare function latestRelease(dir: string, ordering: ReleaseOrdering): Promise<ReleaseNotes | null>;
+/**
+ * How many releases, newest first, a boot re-sends as edits. ArchiveBot keeps a post's record for 7
+ * days and refuses an edit it has no record of, so older notes cannot be changed this way anyway.
+ */
+export declare const EDITABLE_RELEASES = 3;
+/** The newest `count` release notes in `dir`, newest first, by `ordering`. */
+export declare function recentReleases(dir: string, ordering: ReleaseOrdering, count?: number): Promise<ReleaseNotes[]>;
+/** The `# ` heading is the title; everything after it is the body. */
+export declare function parseNotes(version: string, text: string): ReleaseNotes;
+/**
+ * The body cut into descriptions of at most 4096 characters: whole `## ` sections packed in order,
+ * and a section that alone is too long cut at line breaks. Never truncated.
+ */
+export declare function splitBody(body: string, max?: number): string[];
+/**
+ * The body as Discord should get it. Discord breaks the line at every newline it is sent, and a
+ * notes file is wrapped at about a hundred columns, so a line that continues the one above is
+ * joined to it. Discord also spaces a heading by itself, so a blank line beside one would double
+ * the gap: those go. Other blank lines, block starts and anything inside a code fence stay.
+ */
+export declare function forDiscord(body: string): string;
+/**
+ * Who a release thanks: every `@name` in its notes, the hadoku name of whoever reported a bug the
+ * release fixes (docs/RELEASE.md § "Attribution"), each once, in the order the notes first name them.
+ * A sentence's closing full stop is not part of a name.
+ */
+export declare function mentionsIn(body: string): string[];
+export declare function releaseEmbeds(notes: ReleaseNotes, appUrl: string): Embed[];
+export interface AnnounceOptions {
+    /** This app's id: the idempotency key and `source` field are `<service>-release-<version>` / `service`. */
+    service: string;
+    ordering: ReleaseOrdering;
+    releasesDir: string;
+    /** The app's webhook secret; empty = skip. */
+    secret: string;
+    /** The secret's env var name, used only in the "no secret" skip log line. */
+    secretEnvName: string;
+    archivebotUrl: string;
+    appUrl: string;
+    log: JsonLog;
+    fetch?: typeof fetch;
+    now?: () => Date;
+}
+/**
+ * Post the current release's notes, then re-send the newest few as edits, so a corrected notes file
+ * (a credit added to a bullet, a typo) changes its post at the next boot. ArchiveBot edits only a post
+ * whose shown text differs and never posts from an edit. Resolves on every outcome; the outcome is
+ * logged, never thrown.
+ */
+export declare function announceRelease(options: AnnounceOptions): Promise<void>;