@geekity/cms 0.3.0 → 0.5.0

package/dist/web/themes.d.ts

@@ -0,0 +1,226 @@
+/**
+ * Where a theme is, and what makes a directory one.
+ *
+ * This module is the only place that knows the packaged theme's path and the
+ * order the directories are searched in. The template environment, the
+ * `/theme/` asset finder, the mail environment and the per-render probe for
+ * the optional front-page and posts-page layouts all ask here, so there is one
+ * answer to "which theme is this render reading from" rather than four copies
+ * of the same two-element array (decision-15).
+ *
+ * The admin is deliberately not a theme. Its templates and its static files
+ * live at `admin/` with a loader of their own and are never on this path, so a
+ * site theme cannot shadow the login form or the CSRF field inside it
+ * (decision-4).
+ */
+/**
+ * The theme that ships inside the package, resolved from this module rather
+ * than from the working directory, so it is found whether the CMS is running
+ * from `src/` under tsx or from `dist/` as an installed dependency.
+ */
+export declare const PACKAGED_THEME_DIR: string;
+/** The file a directory declares itself a theme with. */
+export declare const THEME_MANIFEST_FILE = "theme.json";
+/**
+ * The only kind of theme there is.
+ *
+ * The field exists so a second kind — the admin, if it is ever made
+ * overridable — can slot in without the manifest format changing, and so a
+ * manifest that names a kind this CMS does not have is refused rather than
+ * loaded as a site theme by accident.
+ */
+export declare const SITE_THEME_KIND = "site";
+/** What kinds of theme a manifest may declare. One, today. */
+export type ThemeKind = typeof SITE_THEME_KIND;
+/**
+ * One place a theme renders a menu, as its `theme.json` declares it.
+ *
+ * A theme decides where a menu can go, and the screen that edits menus cannot
+ * know what a theme wants (TASK-107). So the theme says: a `name`, which is
+ * the key a site stores that menu under in `site.json` and the key the
+ * template context carries it as, and a `label` for the person choosing which
+ * menu to fill in.
+ */
+export interface ThemeArea {
+    /** The menu's name: what `menus` is keyed by in `site.json` and in a render. */
+    readonly name: string;
+    /** What the Navigation screen calls this place, for a person to read. */
+    readonly label: string;
+}
+/** One theme directory, read and validated. */
+export interface Theme {
+    /** The directory name, which is the theme's id and what a site.json names. */
+    readonly id: string;
+    /** Absolute path to the directory the manifest was read from. */
+    readonly dir: string;
+    /** The display name, for the admin's list. */
+    readonly name: string;
+    /** What the theme themes. Always {@link SITE_THEME_KIND} today. */
+    readonly kind: ThemeKind;
+    /** One line about the theme, when the manifest wrote one. */
+    readonly description?: string | undefined;
+    /**
+     * Where this theme renders a menu, in the order the manifest names them.
+     * Empty for a theme that declares none, which is every theme written before
+     * areas existed and every theme that renders no menu at all.
+     */
+    readonly areas: readonly ThemeArea[];
+}
+/** A theme, or the reason the directory is not one. */
+export type ThemeRead = {
+    readonly ok: true;
+    readonly theme: Theme;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * Read one directory as a theme.
+ *
+ * Every way of not being a theme comes back the same way — `ok: false` and a
+ * sentence saying why — because every caller has the same job with it: a
+ * listing greys the directory out, a chosen theme that stopped being one falls
+ * back to the packaged default with the reason logged, and the admin refuses
+ * to save it. None of them wants an exception, and a directory that is simply
+ * not a theme is not exceptional: a site's `themes/` will have a `.DS_Store`
+ * in it soon enough.
+ */
+export declare function readTheme(dir: string): ThemeRead;
+/** A directory under the themes directory that turned out not to be a theme. */
+export interface UnreadableTheme {
+    /** The directory name, as it sits on disk. */
+    readonly id: string;
+    /** Absolute path to it, so the screen can say where to go and look. */
+    readonly dir: string;
+    /** Why it is not a theme: {@link ThemeRead}'s reason. */
+    readonly reason: string;
+}
+/** What is in a site's themes directory: the themes, and the near misses. */
+export interface SiteThemes {
+    /** Every directory that is a theme, by directory name. */
+    readonly themes: readonly Theme[];
+    /** Every directory that was meant to be one and is not. */
+    readonly unreadable: readonly UnreadableTheme[];
+}
+/**
+ * Everything in one site's themes directory.
+ *
+ * Both halves come back because the Appearance screen draws both: a folder
+ * with a typo in its `theme.json` is listed with the reason rather than
+ * silently skipped, because a theme that has quietly vanished from the list is
+ * the hardest kind of mistake to find. The screen is the only caller —
+ * rendering asks {@link chooseTheme} about one name instead, and never reads
+ * the directory.
+ *
+ * Only a subdirectory is a candidate, and a hidden one is not even that: a
+ * `themes/` with a `.DS_Store`, a `README.md` or a `.git` in it is a site with
+ * no broken themes, not a site with three of them.
+ *
+ * A themes directory that is not there is an empty one. Nothing scaffolds it
+ * (decision-15), so a site that has never written a theme has no directory,
+ * and that is the ordinary state rather than a problem to report.
+ */
+export declare function listSiteThemes(themesDir: string): SiteThemes;
+/**
+ * The theme directories one render reads from, in order: the theme the site
+ * has chosen first, the theme that ships in this package second.
+ *
+ * That is the whole override mechanism. A theme that ships only
+ * `layouts/post.njk` replaces the post layout and keeps receiving updates to
+ * every other template, and the same order decides a `/theme/` asset and a
+ * mail template. The chosen directory need not exist.
+ *
+ * A site that has chosen nothing passes nothing, and reads the packaged theme
+ * alone: an unchosen theme is never on the path, and the packaged one is never
+ * on it twice (decision-15).
+ */
+export declare function themeSearchPath(chosenThemeDir?: string): string[];
+/**
+ * What a `theme` in `site.json` may be: the name of one directory inside the
+ * themes directory, and nothing that would reach outside it.
+ *
+ * The setting is a word somebody picks off a list, so this is about a
+ * hand-edited file rather than about an attacker — but the value decides a
+ * directory every template is then read out of, so it is checked before it is
+ * joined to a path rather than after.
+ */
+export declare function themeNameProblem(name: string): string | undefined;
+/** Which theme a render reads from, and why it is that one. */
+export interface ChosenTheme {
+    /** The site theme in use, or `undefined` when the packaged one is. */
+    readonly theme: Theme | undefined;
+    /** The directories to read, in order: {@link themeSearchPath}. */
+    readonly dirs: readonly string[];
+    /**
+     * Why the theme the site named is not the one in use, when it named one that
+     * is not there or is not a theme. `undefined` both for a site running the
+     * packaged theme on purpose and for one whose choice is working.
+     */
+    readonly problem: string | undefined;
+}
+/**
+ * The theme one site has chosen, resolved against its themes directory.
+ *
+ * A choice that cannot be honoured is the packaged theme and a sentence saying
+ * why, never an exception: a theme deleted from disk, or a `theme.json` broken
+ * by a hand edit, has to leave the site up and answering — the alternative is
+ * a site that 500s on every page because of a directory rename.
+ */
+export declare function chooseTheme(options: {
+    themesDir: string;
+    name: string;
+}): ChosenTheme;
+/** Where {@link createThemeSource} says what it could not do. */
+export interface ThemeLogger {
+    warn(message: string): void;
+}
+/** The theme in use right now, asked afresh whenever anything renders. */
+export interface ThemeSource {
+    /**
+     * The theme this render reads from.
+     *
+     * Cheap enough to call per render: it costs one read of the site's choice —
+     * which is itself cached against the `stat` of `site.json` — and one `stat`
+     * of the chosen theme's manifest.
+     */
+    current(): ChosenTheme;
+}
+/**
+ * The one thing that knows which theme a site is rendering through.
+ *
+ * It is a source rather than a value because the choice is a setting in
+ * `content/_data/site.json` (decision-9, decision-15): the Appearance screen
+ * writes that file, a hand edit writes the same file, and both have to reach
+ * the next request without a restart. So every consumer — the template
+ * environment, the `/theme/` assets, the mail templates — asks here per render
+ * instead of being handed a directory at boot.
+ *
+ * The result is cached against the choice and the `stat` of the chosen theme's
+ * manifest, so an unchanged site pays one `stat` per render and a theme
+ * edited, replaced or deleted under the running process is noticed on the next
+ * one. A choice that cannot be honoured is logged once, when the answer
+ * changes, rather than on every render: a site whose theme has been deleted
+ * should say so in the log and then serve pages, not fill the log with the
+ * same line.
+ */
+export declare function createThemeSource(options: {
+    /** Where the site's themes are: {@link ResolvedConfig.themesDir}. */
+    themesDir: string;
+    /** The site's choice, read per call. The empty string is the packaged theme. */
+    chosen: () => string;
+    /** Where a choice that could not be honoured is reported. Defaults to `console`. */
+    logger?: ThemeLogger | undefined;
+}): ThemeSource;
+/**
+ * The first theme on the path that ships one file, by absolute path, or
+ * `undefined` when none of them does.
+ *
+ * Nunjucks resolves its own templates through the same order, so this is for
+ * the two questions asked outside a render: whether a theme has written the
+ * optional front-page or posts-page layout, and which halves of a mail message
+ * exist. A path that climbs out of a theme directory finds nothing, so a
+ * caller passing a name through from a request cannot reach the file system
+ * around it.
+ */
+export declare function findThemeFile(themeDirs: readonly string[], relative: string): string | undefined;
+//# sourceMappingURL=themes.d.ts.map

package/dist/web/themes.d.ts.map

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

package/dist/web/themes.js

@@ -0,0 +1,314 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * Where a theme is, and what makes a directory one.
+ *
+ * This module is the only place that knows the packaged theme's path and the
+ * order the directories are searched in. The template environment, the
+ * `/theme/` asset finder, the mail environment and the per-render probe for
+ * the optional front-page and posts-page layouts all ask here, so there is one
+ * answer to "which theme is this render reading from" rather than four copies
+ * of the same two-element array (decision-15).
+ *
+ * The admin is deliberately not a theme. Its templates and its static files
+ * live at `admin/` with a loader of their own and are never on this path, so a
+ * site theme cannot shadow the login form or the CSRF field inside it
+ * (decision-4).
+ */
+/**
+ * The theme that ships inside the package, resolved from this module rather
+ * than from the working directory, so it is found whether the CMS is running
+ * from `src/` under tsx or from `dist/` as an installed dependency.
+ */
+export const PACKAGED_THEME_DIR = fileURLToPath(new URL('../../themes/default/', import.meta.url));
+/** The file a directory declares itself a theme with. */
+export const THEME_MANIFEST_FILE = 'theme.json';
+/**
+ * The only kind of theme there is.
+ *
+ * The field exists so a second kind — the admin, if it is ever made
+ * overridable — can slot in without the manifest format changing, and so a
+ * manifest that names a kind this CMS does not have is refused rather than
+ * loaded as a site theme by accident.
+ */
+export const SITE_THEME_KIND = 'site';
+/**
+ * Read one directory as a theme.
+ *
+ * Every way of not being a theme comes back the same way — `ok: false` and a
+ * sentence saying why — because every caller has the same job with it: a
+ * listing greys the directory out, a chosen theme that stopped being one falls
+ * back to the packaged default with the reason logged, and the admin refuses
+ * to save it. None of them wants an exception, and a directory that is simply
+ * not a theme is not exceptional: a site's `themes/` will have a `.DS_Store`
+ * in it soon enough.
+ */
+export function readTheme(dir) {
+    const directory = path.resolve(dir);
+    const manifestFile = path.join(directory, THEME_MANIFEST_FILE);
+    let source;
+    try {
+        source = readFileSync(manifestFile, 'utf8');
+    }
+    catch {
+        return { ok: false, reason: `There is no ${THEME_MANIFEST_FILE} in ${directory}.` };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(source);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        return { ok: false, reason: `${manifestFile} is not valid JSON: ${detail}` };
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        return { ok: false, reason: `${manifestFile} is not a JSON object.` };
+    }
+    const manifest = parsed;
+    const name = manifest['name'];
+    if (typeof name !== 'string' || name.trim() === '') {
+        return { ok: false, reason: `${manifestFile} has no name.` };
+    }
+    const kind = manifest['kind'];
+    if (kind !== SITE_THEME_KIND) {
+        const named = typeof kind === 'string' ? `"${kind}"` : 'nothing';
+        return {
+            ok: false,
+            reason: `${manifestFile} declares kind ${named}, and the only theme kind is "${SITE_THEME_KIND}".`,
+        };
+    }
+    const description = manifest['description'];
+    return {
+        ok: true,
+        theme: {
+            id: path.basename(directory),
+            dir: directory,
+            name: name.trim(),
+            kind: SITE_THEME_KIND,
+            ...(typeof description === 'string' && description.trim() !== ''
+                ? { description: description.trim() }
+                : {}),
+            areas: themeAreasOf(manifest['areas']),
+        },
+    };
+}
+/**
+ * An `areas` value as the areas it declares, ignoring anything that is not
+ * one.
+ *
+ * Tolerant where the name and the kind are strict, and deliberately so: a
+ * theme that got its areas wrong still renders a site, whereas one with no
+ * name or the wrong kind is not a theme at all. A declaration that cannot be
+ * read leaves the theme with no areas — the Navigation screen then offers
+ * nowhere to put a menu, which is visibly wrong and fixable, rather than the
+ * site 500ing over a typo in a manifest.
+ *
+ * A label is optional and falls back to the name, because an area with a name
+ * and no label is a theme that said where a menu goes and forgot to say it
+ * nicely. A name declared twice is one area: the manifest is a list only so
+ * that the order is the theme's to choose.
+ */
+function themeAreasOf(value) {
+    if (!Array.isArray(value))
+        return [];
+    const areas = [];
+    const seen = new Set();
+    for (const entry of value) {
+        if (typeof entry !== 'object' || entry === null)
+            continue;
+        const { name, label } = entry;
+        if (typeof name !== 'string')
+            continue;
+        const area = name.trim();
+        if (area === '' || seen.has(area))
+            continue;
+        seen.add(area);
+        const words = typeof label === 'string' ? label.trim() : '';
+        areas.push({ name: area, label: words === '' ? area : words });
+    }
+    return areas;
+}
+/**
+ * Everything in one site's themes directory.
+ *
+ * Both halves come back because the Appearance screen draws both: a folder
+ * with a typo in its `theme.json` is listed with the reason rather than
+ * silently skipped, because a theme that has quietly vanished from the list is
+ * the hardest kind of mistake to find. The screen is the only caller —
+ * rendering asks {@link chooseTheme} about one name instead, and never reads
+ * the directory.
+ *
+ * Only a subdirectory is a candidate, and a hidden one is not even that: a
+ * `themes/` with a `.DS_Store`, a `README.md` or a `.git` in it is a site with
+ * no broken themes, not a site with three of them.
+ *
+ * A themes directory that is not there is an empty one. Nothing scaffolds it
+ * (decision-15), so a site that has never written a theme has no directory,
+ * and that is the ordinary state rather than a problem to report.
+ */
+export function listSiteThemes(themesDir) {
+    const root = path.resolve(themesDir);
+    let entries;
+    try {
+        entries = readdirSync(root, { withFileTypes: true });
+    }
+    catch {
+        return { themes: [], unreadable: [] };
+    }
+    const themes = [];
+    const unreadable = [];
+    for (const entry of [...entries].sort((left, right) => left.name.localeCompare(right.name))) {
+        if (!entry.isDirectory() || entry.name.startsWith('.'))
+            continue;
+        const dir = path.join(root, entry.name);
+        const read = readTheme(dir);
+        if (read.ok)
+            themes.push(read.theme);
+        else
+            unreadable.push({ id: entry.name, dir, reason: read.reason });
+    }
+    return { themes, unreadable };
+}
+/**
+ * The theme directories one render reads from, in order: the theme the site
+ * has chosen first, the theme that ships in this package second.
+ *
+ * That is the whole override mechanism. A theme that ships only
+ * `layouts/post.njk` replaces the post layout and keeps receiving updates to
+ * every other template, and the same order decides a `/theme/` asset and a
+ * mail template. The chosen directory need not exist.
+ *
+ * A site that has chosen nothing passes nothing, and reads the packaged theme
+ * alone: an unchosen theme is never on the path, and the packaged one is never
+ * on it twice (decision-15).
+ */
+export function themeSearchPath(chosenThemeDir) {
+    return chosenThemeDir === undefined ? [PACKAGED_THEME_DIR] : [chosenThemeDir, PACKAGED_THEME_DIR];
+}
+/**
+ * What a `theme` in `site.json` may be: the name of one directory inside the
+ * themes directory, and nothing that would reach outside it.
+ *
+ * The setting is a word somebody picks off a list, so this is about a
+ * hand-edited file rather than about an attacker — but the value decides a
+ * directory every template is then read out of, so it is checked before it is
+ * joined to a path rather than after.
+ */
+export function themeNameProblem(name) {
+    const chosen = name.trim();
+    if (chosen === '')
+        return undefined;
+    if (chosen === '.' || chosen === '..' || /[/\\\0]/.test(chosen)) {
+        return `"${chosen}" is not a theme name: a theme is one directory inside the themes directory.`;
+    }
+    return undefined;
+}
+/**
+ * The theme one site has chosen, resolved against its themes directory.
+ *
+ * A choice that cannot be honoured is the packaged theme and a sentence saying
+ * why, never an exception: a theme deleted from disk, or a `theme.json` broken
+ * by a hand edit, has to leave the site up and answering — the alternative is
+ * a site that 500s on every page because of a directory rename.
+ */
+export function chooseTheme(options) {
+    const name = options.name.trim();
+    if (name === '')
+        return { theme: undefined, dirs: themeSearchPath(), problem: undefined };
+    const badName = themeNameProblem(name);
+    if (badName !== undefined) {
+        return { theme: undefined, dirs: themeSearchPath(), problem: badName };
+    }
+    const read = readTheme(path.join(options.themesDir, name));
+    if (!read.ok) {
+        return {
+            theme: undefined,
+            dirs: themeSearchPath(),
+            problem: `The theme "${name}" is not there: ${read.reason}`,
+        };
+    }
+    return { theme: read.theme, dirs: themeSearchPath(read.theme.dir), problem: undefined };
+}
+/**
+ * The one thing that knows which theme a site is rendering through.
+ *
+ * It is a source rather than a value because the choice is a setting in
+ * `content/_data/site.json` (decision-9, decision-15): the Appearance screen
+ * writes that file, a hand edit writes the same file, and both have to reach
+ * the next request without a restart. So every consumer — the template
+ * environment, the `/theme/` assets, the mail templates — asks here per render
+ * instead of being handed a directory at boot.
+ *
+ * The result is cached against the choice and the `stat` of the chosen theme's
+ * manifest, so an unchanged site pays one `stat` per render and a theme
+ * edited, replaced or deleted under the running process is noticed on the next
+ * one. A choice that cannot be honoured is logged once, when the answer
+ * changes, rather than on every render: a site whose theme has been deleted
+ * should say so in the log and then serve pages, not fill the log with the
+ * same line.
+ */
+export function createThemeSource(options) {
+    const logger = options.logger ?? console;
+    let cached;
+    let cachedKey;
+    let reported;
+    /**
+     * What would make the answer different: the name chosen, and the state of
+     * that theme's manifest. The modification time alone is not enough, for the
+     * reason it is not in {@link createSiteDataSource}: a filesystem rounds it,
+     * and a theme replaced wholesale changes the inode rather than the time.
+     */
+    function key(name) {
+        if (name === '')
+            return '';
+        try {
+            const stats = statSync(path.join(options.themesDir, name, THEME_MANIFEST_FILE));
+            return `${name}:${String(stats.mtimeMs)}:${String(stats.size)}:${String(stats.ino)}`;
+        }
+        catch {
+            return `${name}:missing`;
+        }
+    }
+    return {
+        current() {
+            const name = options.chosen().trim();
+            const current = key(name);
+            if (cached !== undefined && current === cachedKey)
+                return cached;
+            cachedKey = current;
+            cached = chooseTheme({ themesDir: options.themesDir, name });
+            if (cached.problem !== undefined && cached.problem !== reported) {
+                logger.warn(`${cached.problem} The packaged theme is being used instead.`);
+            }
+            reported = cached.problem;
+            return cached;
+        },
+    };
+}
+/**
+ * The first theme on the path that ships one file, by absolute path, or
+ * `undefined` when none of them does.
+ *
+ * Nunjucks resolves its own templates through the same order, so this is for
+ * the two questions asked outside a render: whether a theme has written the
+ * optional front-page or posts-page layout, and which halves of a mail message
+ * exist. A path that climbs out of a theme directory finds nothing, so a
+ * caller passing a name through from a request cannot reach the file system
+ * around it.
+ */
+export function findThemeFile(themeDirs, relative) {
+    if (relative === '' || relative.includes('\0'))
+        return undefined;
+    const segments = relative.split('/').filter((segment) => segment !== '');
+    for (const directory of themeDirs) {
+        const root = path.resolve(directory);
+        const file = path.resolve(root, ...segments);
+        if (file !== root && !file.startsWith(root + path.sep))
+            continue;
+        if (existsSync(file))
+            return file;
+    }
+    return undefined;
+}
+//# sourceMappingURL=themes.js.map

package/dist/web/themes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"themes.js","sourceRoot":"","sources":["../../src/web/themes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC1E,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC;;;;;;;;;;;;;;GAcG;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAW,aAAa,CACrD,IAAI,GAAG,CAAC,uBAAuB,EAAE,OAAO,IAAI,CAAC,GAAG,CAAC,CAClD,CAAC;AAEF,yDAAyD;AACzD,MAAM,CAAC,MAAM,mBAAmB,GAAG,YAAY,CAAC;AAEhD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC;AA6CtC;;;;;;;;;;GAUG;AACH,MAAM,UAAU,SAAS,CAAC,GAAW;IACnC,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACpC,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,mBAAmB,CAAC,CAAC;IAE/D,IAAI,MAAc,CAAC;IACnB,IAAI,CAAC;QACH,MAAM,GAAG,YAAY,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;IAC9C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,mBAAmB,OAAO,SAAS,GAAG,EAAE,CAAC;IACtF,CAAC;IAED,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,MAAM,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACtE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,YAAY,uBAAuB,MAAM,EAAE,EAAE,CAAC;IAC/E,CAAC;IAED,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3E,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,YAAY,wBAAwB,EAAE,CAAC;IACxE,CAAC;IAED,MAAM,QAAQ,GAAG,MAAiC,CAAC;IAEnD,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC9B,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACnD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,YAAY,eAAe,EAAE,CAAC;IAC/D,CAAC;IAED,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC9B,IAAI,IAAI,KAAK,eAAe,EAAE,CAAC;QAC7B,MAAM,KAAK,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;QACjE,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,GAAG,YAAY,kBAAkB,KAAK,iCAAiC,eAAe,IAAI;SACnG,CAAC;IACJ,CAAC;IAED,MAAM,WAAW,GAAG,QAAQ,CAAC,aAAa,CAAC,CAAC;IAE5C,OAAO;QACL,EAAE,EAAE,IAAI;QACR,KAAK,EAAE;YACL,EAAE,EAAE,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC;YAC5B,GAAG,EAAE,SAAS;YACd,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE;YACjB,IAAI,EAAE,eAAe;YACrB,GAAG,CAAC,OAAO,WAAW,KAAK,QAAQ,IAAI,WAAW,CAAC,IAAI,EAAE,KAAK,EAAE;gBAC9D,CAAC,CAAC,EAAE,WAAW,EAAE,WAAW,CAAC,IAAI,EAAE,EAAE;gBACrC,CAAC,CAAC,EAAE,CAAC;YACP,KAAK,EAAE,YAAY,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;SACvC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,SAAS,YAAY,CAAC,KAAc;IAClC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAErC,MAAM,KAAK,GAAgB,EAAE,CAAC;IAC9B,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAE/B,KAAK,MAAM,KAAK,IAAI,KAAK,EAAE,CAAC;QAC1B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;YAAE,SAAS;QAC1D,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,KAAgC,CAAC;QACzD,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,SAAS;QAEvC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QACzB,IAAI,IAAI,KAAK,EAAE,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,SAAS;QAC5C,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAEf,MAAM,KAAK,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5D,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;IACjE,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAoBD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,cAAc,CAAC,SAAiB;IAC9C,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAErC,IAAI,OAAO,CAAC;IACZ,IAAI,CAAC;QACH,OAAO,GAAG,WAAW,CAAC,IAAI,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IACvD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC;IACxC,CAAC;IAED,MAAM,MAAM,GAAY,EAAE,CAAC;IAC3B,MAAM,UAAU,GAAsB,EAAE,CAAC;IAEzC,KAAK,MAAM,KAAK,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;QAC5F,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,IAAI,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,SAAS;QAEjE,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QACxC,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,IAAI,CAAC,EAAE;YAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;;YAChC,UAAU,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,KAAK,CAAC,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IACrE,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;AAChC,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,eAAe,CAAC,cAAuB;IACrD,OAAO,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC,cAAc,EAAE,kBAAkB,CAAC,CAAC;AACpG,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAC3B,IAAI,MAAM,KAAK,EAAE;QAAE,OAAO,SAAS,CAAC;IACpC,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,IAAI,IAAI,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QAChE,OAAO,IAAI,MAAM,8EAA8E,CAAC;IAClG,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAgBD;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,OAA4C;IACtE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;IACjC,IAAI,IAAI,KAAK,EAAE;QAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,eAAe,EAAE,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;IAE1F,MAAM,OAAO,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;IACvC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,eAAe,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;IACzE,CAAC;IAED,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC,CAAC;IAC3D,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;QACb,OAAO;YACL,KAAK,EAAE,SAAS;YAChB,IAAI,EAAE,eAAe,EAAE;YACvB,OAAO,EAAE,cAAc,IAAI,mBAAmB,IAAI,CAAC,MAAM,EAAE;SAC5D,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;AAC1F,CAAC;AAmBD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAOjC;IACC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC;IAEzC,IAAI,MAA+B,CAAC;IACpC,IAAI,SAA6B,CAAC;IAClC,IAAI,QAA4B,CAAC;IAEjC;;;;;OAKG;IACH,SAAS,GAAG,CAAC,IAAY;QACvB,IAAI,IAAI,KAAK,EAAE;YAAE,OAAO,EAAE,CAAC;QAC3B,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,mBAAmB,CAAC,CAAC,CAAC;YAChF,OAAO,GAAG,IAAI,IAAI,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACvF,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,GAAG,IAAI,UAAU,CAAC;QAC3B,CAAC;IACH,CAAC;IAED,OAAO;QACL,OAAO;YACL,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC;YACrC,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC;YAC1B,IAAI,MAAM,KAAK,SAAS,IAAI,OAAO,KAAK,SAAS;gBAAE,OAAO,MAAM,CAAC;YAEjE,SAAS,GAAG,OAAO,CAAC;YACpB,MAAM,GAAG,WAAW,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAE7D,IAAI,MAAM,CAAC,OAAO,KAAK,SAAS,IAAI,MAAM,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;gBAChE,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,OAAO,4CAA4C,CAAC,CAAC;YAC7E,CAAC;YACD,QAAQ,GAAG,MAAM,CAAC,OAAO,CAAC;YAE1B,OAAO,MAAM,CAAC;QAChB,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa,CAAC,SAA4B,EAAE,QAAgB;IAC1E,IAAI,QAAQ,KAAK,EAAE,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IACjE,MAAM,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,KAAK,EAAE,CAAC,CAAC;IAEzE,KAAK,MAAM,SAAS,IAAI,SAAS,EAAE,CAAC;QAClC,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QACrC,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,QAAQ,CAAC,CAAC;QAC7C,IAAI,IAAI,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC;YAAE,SAAS;QACjE,IAAI,UAAU,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;IACpC,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/webmention/discovery.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Finding out where to send a webmention.
+ *
+ * The W3C spec fixes the order and it matters, because a page may advertise
+ * two: the HTTP `Link` header first, then the first `<link>` **or** `<a>`
+ * carrying `rel="webmention"` in document order — one search over both, not
+ * one search each. Whatever is found is resolved against the URL the request
+ * actually ended at, so a target that redirects to its canonical home
+ * advertises that home's endpoint rather than a path under the old one.
+ */
+/** How long one discovery request is given before it is abandoned. */
+export declare const DISCOVERY_TIMEOUT_MS = 10000;
+/** How much of a target page is read while looking for its endpoint. */
+export declare const DISCOVERY_MAX_BYTES = 1000000;
+/** What a sender says it is. */
+export declare const WEBMENTION_USER_AGENT = "Geekity/1.0 (+https://github.com/andrewshell/geekity)";
+/**
+ * The Webmention endpoint a page advertises, or `undefined` when it advertises
+ * none — which is most pages, and is not an error.
+ *
+ * Nothing throws: a target that times out, refuses the connection or answers
+ * an error is a target with no endpoint as far as the sender is concerned, and
+ * the caller records that rather than stopping.
+ */
+export declare function discoverEndpoint(target: string): Promise<string | undefined>;
+/**
+ * The endpoint one or more `Link` headers name, or `undefined`.
+ *
+ * A header may carry several links separated by commas and each may name
+ * several relations, so both are split. Splitting on commas that are not
+ * inside angle brackets or quotes is what keeps a URL holding a comma — which
+ * is legal — from being torn in half.
+ */
+export declare function endpointInHeader(header: string | null, base: string): string | undefined;
+/**
+ * The endpoint a page's markup names, or `undefined`.
+ *
+ * One walk over every element rather than one for `<link>` and another for
+ * `<a>`: the spec asks for the first of either in document order, and two
+ * walks would answer with whichever kind was searched for first.
+ */
+export declare function endpointInHtml(html: string, base: string): string | undefined;
+/**
+ * A response body, up to {@link DISCOVERY_MAX_BYTES}.
+ *
+ * A cap rather than `response.text()`, because the page at the other end is a
+ * stranger's and nothing stops it being a gigabyte. What is read is more than
+ * enough markup for a `<link>` in the head.
+ */
+export declare function readCapped(response: Response): Promise<string>;
+//# sourceMappingURL=discovery.d.ts.map

package/dist/webmention/discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../src/webmention/discovery.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AAEH,sEAAsE;AACtE,eAAO,MAAM,oBAAoB,QAAS,CAAC;AAE3C,wEAAwE;AACxE,eAAO,MAAM,mBAAmB,UAAY,CAAC;AAE7C,gCAAgC;AAChC,eAAO,MAAM,qBAAqB,0DAA0D,CAAC;AAE7F;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAkClF;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAexF;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAW7E;AAsCD;;;;;;GAMG;AACH,wBAAsB,UAAU,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CA0BpE"}