dsh-gh-pages-artifacts 0.1.0

package/lib/manifest.js

@@ -0,0 +1,172 @@
+/** Artifact manifest stored on the Pages branch, plus id and asset-name rules. */
+/** Repository-root path of the manifest. It sits outside the artifact folders. */
+export const MANIFEST_PATH = '.dsh-artifacts.json';
+/** File holding the served page. */
+export const PAGE_FILE = 'index.html';
+/** File holding the Markdown source of a markdown artifact. */
+export const SOURCE_FILE = 'source.md';
+/** Valid artifact id: lowercase letters, digits, and inner hyphens, 1-64 characters. */
+export const ID_PATTERN = /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/;
+/** Ids that would collide with site-level files or common folders. */
+export const RESERVED_IDS = new Set([
+    '404', 'index', 'assets', 'static', 'api', 'robots', 'sitemap', 'favicon', 'cname',
+]);
+const ASSET_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
+/** Error for a manifest that cannot be read safely. */
+export class ManifestError extends Error {
+    name = 'ManifestError';
+}
+/** @returns an empty manifest. */
+export function emptyManifest() {
+    return { version: 1, artifacts: {}, tombstones: [] };
+}
+/**
+ * Parse and validate manifest text. A malformed manifest is never overwritten silently.
+ * @param text - file content.
+ * @returns the manifest.
+ * @throws ManifestError when the content is not a version-1 manifest.
+ */
+export function parseManifest(text) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (error) {
+        throw new ManifestError(`${MANIFEST_PATH} is not valid JSON (${error.message}); fix or remove it on the Pages branch`);
+    }
+    if (!isRecord(raw) || raw['version'] !== 1 || !isRecord(raw['artifacts'])) {
+        throw new ManifestError(`${MANIFEST_PATH} is not a version 1 artifact manifest; fix or remove it on the Pages branch`);
+    }
+    const artifacts = {};
+    for (const [id, value] of Object.entries(raw['artifacts'])) {
+        artifacts[id] = parseRecord(id, value);
+    }
+    const tombstonesRaw = raw['tombstones'] ?? [];
+    if (!Array.isArray(tombstonesRaw) || !tombstonesRaw.every(item => typeof item === 'string')) {
+        throw new ManifestError(`${MANIFEST_PATH} has an invalid "tombstones" list`);
+    }
+    return { version: 1, artifacts, tombstones: [...new Set(tombstonesRaw)] };
+}
+function parseRecord(id, value) {
+    const fail = (what) => {
+        throw new ManifestError(`${MANIFEST_PATH} entry "${id}" has an invalid ${what}`);
+    };
+    if (!isRecord(value))
+        return fail('record');
+    if (value['id'] !== id || !ID_PATTERN.test(id))
+        fail('id');
+    if (typeof value['title'] !== 'string')
+        fail('title');
+    if (value['kind'] !== 'html' && value['kind'] !== 'markdown')
+        fail('kind');
+    if (typeof value['createdAt'] !== 'string' || typeof value['updatedAt'] !== 'string')
+        fail('timestamp');
+    if (typeof value['rev'] !== 'number' || !Number.isSafeInteger(value['rev']) || value['rev'] < 1)
+        fail('rev');
+    const files = value['files'];
+    if (!Array.isArray(files) || !files.every(file => typeof file === 'string' && isSafeRelativePath(file)))
+        fail('files list');
+    if (value['description'] !== undefined && typeof value['description'] !== 'string')
+        fail('description');
+    const record = {
+        id,
+        title: value['title'],
+        kind: value['kind'],
+        createdAt: value['createdAt'],
+        updatedAt: value['updatedAt'],
+        rev: value['rev'],
+        files: [...files].sort(),
+    };
+    if (typeof value['description'] === 'string')
+        record.description = value['description'];
+    return record;
+}
+/**
+ * Serialize a manifest deterministically so diffs stay readable.
+ * @param manifest - manifest to write.
+ * @returns JSON text with a trailing newline.
+ */
+export function serializeManifest(manifest) {
+    const artifacts = {};
+    for (const id of Object.keys(manifest.artifacts).sort()) {
+        const record = manifest.artifacts[id];
+        if (record === undefined)
+            continue;
+        const ordered = {
+            id: record.id,
+            title: record.title,
+            kind: record.kind,
+            createdAt: record.createdAt,
+            updatedAt: record.updatedAt,
+            rev: record.rev,
+            files: [...record.files].sort(),
+        };
+        if (record.description !== undefined)
+            ordered.description = record.description;
+        artifacts[id] = ordered;
+    }
+    const tombstones = [...new Set(manifest.tombstones)].sort();
+    return `${JSON.stringify({ version: 1, artifacts, tombstones }, null, 2)}\n`;
+}
+/**
+ * Turn a title into a URL slug: lowercase ASCII letters and digits joined by hyphens.
+ * @param title - free text.
+ * @param maxLength - longest result.
+ * @returns the slug, or 'artifact' when nothing usable remains.
+ */
+export function slugify(title, maxLength = 40) {
+    const slug = title
+        .normalize('NFKD')
+        .replace(/[̀-ͯ]/g, '')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, maxLength)
+        .replace(/-+$/g, '');
+    return slug === '' ? 'artifact' : slug;
+}
+/**
+ * Build a fresh id from a title plus a random suffix, so URLs are readable but not guessable.
+ * @param title - artifact title.
+ * @param suffix - random lowercase base32 text.
+ */
+export function idFromTitle(title, suffix) {
+    return `${slugify(title)}-${suffix}`;
+}
+/**
+ * Check a caller-chosen id.
+ * @param id - candidate id.
+ * @returns an error message, or undefined when valid.
+ */
+export function idProblem(id) {
+    if (!ID_PATTERN.test(id)) {
+        return `"${id}" is not a valid artifact id: use 1-64 lowercase letters, digits, and inner hyphens`;
+    }
+    if (RESERVED_IDS.has(id))
+        return `"${id}" is reserved; choose another id`;
+    return undefined;
+}
+/**
+ * Check an asset name, the path of an extra file relative to the artifact folder.
+ * @param name - candidate name such as `chart.png` or `img/logo.svg`.
+ * @returns an error message, or undefined when valid.
+ */
+export function assetNameProblem(name) {
+    if (!isSafeRelativePath(name)) {
+        return `asset name "${name}" must be a relative path of segments made of letters, digits, '.', '_' or '-', each starting with a letter or digit (at most 4 levels)`;
+    }
+    if (name === PAGE_FILE || name === SOURCE_FILE)
+        return `asset name "${name}" is reserved for the page itself`;
+    return undefined;
+}
+/**
+ * @param path - candidate relative path.
+ * @returns whether it is 1-4 safe segments with no dot-segments.
+ */
+export function isSafeRelativePath(path) {
+    const segments = path.split('/');
+    return segments.length >= 1 && segments.length <= 4 && segments.every(segment => ASSET_SEGMENT.test(segment) && segment !== '.' && segment !== '..');
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/lib/names.d.ts

@@ -0,0 +1,17 @@
+/** Tool names shared by the tool definitions, the runtime, and visibility rules. */
+/** Tool that creates or updates an artifact. */
+export declare const PUBLISH_TOOL = "artifact_publish";
+/** Tool that lists artifacts. */
+export declare const LIST_TOOL = "artifact_list";
+/** Tool that reads an artifact back. */
+export declare const READ_TOOL = "artifact_read";
+/** Tool that deletes an artifact. */
+export declare const DELETE_TOOL = "artifact_delete";
+/** Tool that checks setup and deployment. */
+export declare const STATUS_TOOL = "artifact_status";
+/** Tool that shows or changes where new artifacts go. */
+export declare const REPOSITORY_TOOL = "artifact_repository";
+/** Every tool, in registration order. */
+export declare const ALL_TOOLS: readonly ["artifact_publish", "artifact_list", "artifact_read", "artifact_delete", "artifact_status", "artifact_repository"];
+/** Tools that change what is published. */
+export declare const MUTATING_TOOLS: readonly ["artifact_publish", "artifact_delete"];

package/lib/names.js

@@ -0,0 +1,17 @@
+/** Tool names shared by the tool definitions, the runtime, and visibility rules. */
+/** Tool that creates or updates an artifact. */
+export const PUBLISH_TOOL = 'artifact_publish';
+/** Tool that lists artifacts. */
+export const LIST_TOOL = 'artifact_list';
+/** Tool that reads an artifact back. */
+export const READ_TOOL = 'artifact_read';
+/** Tool that deletes an artifact. */
+export const DELETE_TOOL = 'artifact_delete';
+/** Tool that checks setup and deployment. */
+export const STATUS_TOOL = 'artifact_status';
+/** Tool that shows or changes where new artifacts go. */
+export const REPOSITORY_TOOL = 'artifact_repository';
+/** Every tool, in registration order. */
+export const ALL_TOOLS = [PUBLISH_TOOL, LIST_TOOL, READ_TOOL, DELETE_TOOL, STATUS_TOOL, REPOSITORY_TOOL];
+/** Tools that change what is published. */
+export const MUTATING_TOOLS = [PUBLISH_TOOL, DELETE_TOOL];

package/lib/prompt.d.ts

@@ -0,0 +1,15 @@
+/** Short, static system-prompt guidance, shown only to Agents that can see the publish tool. */
+import type { Context } from '@deepseek-ai/cordis';
+/** Order between first-party tool guidance (up to 3100) and the tools SDK (5000). */
+export declare const PROMPT_ORDER = 3250;
+/**
+ * Guidance text. Static per configuration so the provider prefix cache stays warm.
+ * @param withSkill - whether the bundled artifact-pages skill is registered.
+ */
+export declare function promptText(withSkill: boolean): string;
+/**
+ * Register the guidance section.
+ * @param ctx - context exposing `systemPrompt` and `tools`.
+ * @param withSkill - whether to point at the bundled skill.
+ */
+export declare function registerPrompt(ctx: Context, withSkill: boolean): void;

package/lib/prompt.js

@@ -0,0 +1,33 @@
+import { PUBLISH_TOOL } from './names.js';
+/** Order between first-party tool guidance (up to 3100) and the tools SDK (5000). */
+export const PROMPT_ORDER = 3250;
+/**
+ * Guidance text. Static per configuration so the provider prefix cache stays warm.
+ * @param withSkill - whether the bundled artifact-pages skill is registered.
+ */
+export function promptText(withSkill) {
+    return [
+        '# Shareable artifacts',
+        'You can publish web pages and documents as shareable links on GitHub Pages with artifact_publish, and manage them with artifact_list, artifact_read, artifact_delete, artifact_status, and artifact_repository.',
+        '- Use them when the user wants something they can open in a browser or share: a report, dashboard, visualization, demo, or long document.',
+        '- Published artifacts are public. Never publish secrets, credentials, or private data unless the user explicitly asks to share them.',
+        '- Write the page to a workspace file first and pass path. Update an existing artifact by passing its id, so the link stays the same.',
+        ...withSkill ? ['- For design and structure guidance, load the artifact-pages skill before writing the page.'] : [],
+        '- After publishing, give the user the link as Markdown, e.g. [Title](url). When asked what was published, use artifact_list and show the links.',
+        '- When the user wants to choose where artifacts go (one new repository per artifact, or a repository they name), use artifact_repository.',
+    ].join('\n');
+}
+/**
+ * Register the guidance section.
+ * @param ctx - context exposing `systemPrompt` and `tools`.
+ * @param withSkill - whether to point at the bundled skill.
+ */
+export function registerPrompt(ctx, withSkill) {
+    const text = promptText(withSkill);
+    ctx.systemPrompt.section({
+        name: 'gh-pages-artifacts',
+        order: PROMPT_ORDER,
+        interpolate: false,
+        text: ({ scope }) => ctx.tools.get(PUBLISH_TOOL, scope) === undefined ? '' : text,
+    });
+}

package/lib/registry.d.ts

@@ -0,0 +1,70 @@
+import type { RepoRef, RepoStrategy } from './config.js';
+import type { ArtifactKind } from './manifest.js';
+/** Where one artifact lives. */
+export interface ArtifactLocation {
+    readonly owner: string;
+    readonly repo: string;
+    readonly branch: string;
+    readonly siteDir: string;
+    readonly pathPrefix: string;
+    readonly layout: 'folder' | 'root';
+}
+/** One tracked artifact. */
+export interface RegistryEntry {
+    id: string;
+    title: string;
+    kind: ArtifactKind;
+    description?: string;
+    url: string;
+    location: ArtifactLocation;
+    createdAt: string;
+    updatedAt: string;
+    rev: number;
+    status: 'published' | 'deleted';
+    deletedAt?: string;
+}
+/** A shared repository the user linked at runtime. */
+export interface RepositoryLink extends RepoRef {
+    readonly linkedAt: string;
+}
+/** Registry file contents. */
+export interface RegistryData {
+    version: 1;
+    /** Runtime choices that override the plugin configuration. */
+    settings: {
+        strategy?: RepoStrategy;
+        link?: RepositoryLink;
+    };
+    artifacts: Record<string, RegistryEntry>;
+}
+/** File names inside the registry folder. */
+export declare const REGISTRY_FILE = "registry.json";
+export declare const INDEX_FILE = "index.html";
+/** Reads and updates the registry file. */
+export declare class Registry {
+    readonly dir: string;
+    private readonly log?;
+    private queue;
+    constructor(dir: string, log?: ((message: string) => void) | undefined);
+    /** Path of the registry JSON file. */
+    get file(): string;
+    /** Path of the generated index page. */
+    get indexFile(): string;
+    /** @returns the current registry contents (empty when the file does not exist yet). */
+    read(): Promise<RegistryData>;
+    /**
+     * Apply a change and write the file and the index page atomically.
+     * @param change - mutates the freshly read data.
+     * @returns the written data.
+     */
+    update(change: (data: RegistryData) => void): Promise<RegistryData>;
+}
+/** @returns an empty registry. */
+export declare function emptyRegistry(): RegistryData;
+/** @returns the `owner/name` label of a location. */
+export declare function repositoryName(location: RepoRef): string;
+/**
+ * Render the index page: every tracked artifact with a clickable link, newest first.
+ * @param data - registry contents.
+ */
+export declare function renderIndex(data: RegistryData): string;

package/lib/registry.js

@@ -0,0 +1,151 @@
+/**
+ * Local registry of everything this plugin published, across every repository, plus the user's
+ * runtime choices (strategy and linked repository). It lives in one JSON file next to a generated
+ * index.html with clickable links to every page. Writes are atomic (temp file + rename) and
+ * re-read the file first, so several dsh processes sharing a home do not lose each other's entries.
+ */
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { escapeAttribute, escapeText } from './render.js';
+/** File names inside the registry folder. */
+export const REGISTRY_FILE = 'registry.json';
+export const INDEX_FILE = 'index.html';
+/** Reads and updates the registry file. */
+export class Registry {
+    dir;
+    log;
+    queue = Promise.resolve();
+    constructor(dir, log) {
+        this.dir = dir;
+        this.log = log;
+    }
+    /** Path of the registry JSON file. */
+    get file() {
+        return join(this.dir, REGISTRY_FILE);
+    }
+    /** Path of the generated index page. */
+    get indexFile() {
+        return join(this.dir, INDEX_FILE);
+    }
+    /** @returns the current registry contents (empty when the file does not exist yet). */
+    async read() {
+        let text;
+        try {
+            text = await readFile(this.file, 'utf8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return emptyRegistry();
+            throw error;
+        }
+        try {
+            return parseRegistry(JSON.parse(text));
+        }
+        catch (error) {
+            // Keep the unreadable file for the user instead of overwriting it.
+            const aside = `${this.file}.unreadable-${Date.now()}`;
+            await rename(this.file, aside).catch(() => undefined);
+            this.log?.(`gh-pages-artifacts: ${this.file} was unreadable (${error.message}); moved it to ${aside} and started a new registry`);
+            return emptyRegistry();
+        }
+    }
+    /**
+     * Apply a change and write the file and the index page atomically.
+     * @param change - mutates the freshly read data.
+     * @returns the written data.
+     */
+    async update(change) {
+        const run = this.queue.then(async () => {
+            const data = await this.read();
+            change(data);
+            await mkdir(this.dir, { recursive: true, mode: 0o700 });
+            await writeAtomic(this.file, `${JSON.stringify(data, null, 2)}\n`);
+            await writeAtomic(this.indexFile, renderIndex(data));
+            return data;
+        });
+        this.queue = run.catch(() => undefined);
+        return await run;
+    }
+}
+async function writeAtomic(path, text) {
+    const temp = `${path}.${process.pid}.tmp`;
+    await writeFile(temp, text, { mode: 0o600 });
+    await rename(temp, path);
+}
+/** @returns an empty registry. */
+export function emptyRegistry() {
+    return { version: 1, settings: {}, artifacts: {} };
+}
+function parseRegistry(raw) {
+    if (typeof raw !== 'object' || raw === null || raw.version !== 1)
+        throw new Error('not a version 1 registry');
+    const data = raw;
+    if (typeof data.artifacts !== 'object' || data.artifacts === null)
+        throw new Error('missing artifacts');
+    return { version: 1, settings: data.settings ?? {}, artifacts: data.artifacts };
+}
+/** @returns the `owner/name` label of a location. */
+export function repositoryName(location) {
+    return `${location.owner}/${location.repo}`;
+}
+/**
+ * Render the index page: every tracked artifact with a clickable link, newest first.
+ * @param data - registry contents.
+ */
+export function renderIndex(data) {
+    const entries = Object.values(data.artifacts).sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+    const published = entries.filter(entry => entry.status === 'published');
+    const rows = entries.map(entry => {
+        const repo = repositoryName(entry.location);
+        const title = entry.status === 'published'
+            ? `<a href="${escapeAttribute(entry.url)}" target="_blank" rel="noopener">${escapeText(entry.title)}</a>`
+            : `<s>${escapeText(entry.title)}</s>`;
+        return `<tr class="${entry.status}">
+<td>${title}${entry.description === undefined ? '' : `<div class="desc">${escapeText(entry.description)}</div>`}</td>
+<td>${entry.kind}</td>
+<td><a href="https://github.com/${escapeAttribute(repo)}" target="_blank" rel="noopener">${escapeText(repo)}</a></td>
+<td>${entry.rev}</td>
+<td><time datetime="${escapeAttribute(entry.updatedAt)}">${escapeText(entry.updatedAt.slice(0, 16).replace('T', ' '))}</time></td>
+<td>${entry.status === 'published' ? 'live' : 'deleted'}</td>
+</tr>`;
+    });
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Published artifacts</title>
+<style>
+:root{color-scheme:light dark;--bg:#fff;--fg:#1f2328;--muted:#59636e;--border:#d1d9e0;--link:#0969da;--head:#f6f8fa}
+@media (prefers-color-scheme:dark){:root{--bg:#0d1117;--fg:#e6edf3;--muted:#9198a1;--border:#3d444d;--link:#4493f8;--head:#151b23}}
+body{margin:0;background:var(--bg);color:var(--fg);font:15px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif}
+main{max-width:72rem;margin:0 auto;padding:2rem 1rem}
+h1{font-size:1.6rem;margin:0 0 .25rem}
+p{color:var(--muted);margin:0 0 1.5rem}
+.wrap{overflow-x:auto}
+table{border-collapse:collapse;width:100%}
+th,td{text-align:left;padding:.5rem .75rem;border-bottom:1px solid var(--border);vertical-align:top}
+th{background:var(--head);font-weight:600;white-space:nowrap}
+a{color:var(--link);text-decoration:none}
+a:hover{text-decoration:underline}
+.desc{color:var(--muted);font-size:.875rem}
+tr.deleted td{color:var(--muted)}
+</style>
+</head>
+<body>
+<main>
+<h1>Published artifacts</h1>
+<p>${published.length} live, ${entries.length - published.length} deleted. Generated by dsh-gh-pages-artifacts.</p>
+<div class="wrap">
+<table>
+<thead><tr><th>Artifact</th><th>Kind</th><th>Repository</th><th>Rev</th><th>Updated (UTC)</th><th>Status</th></tr></thead>
+<tbody>
+${rows.length === 0 ? '<tr><td colspan="6">Nothing published yet.</td></tr>' : rows.join('\n')}
+</tbody>
+</table>
+</div>
+</main>
+</body>
+</html>
+`;
+}

package/lib/render.d.ts

@@ -0,0 +1,43 @@
+/** Page decorations controlled by configuration. */
+export interface PageOptions {
+    /** Add a robots noindex meta tag. */
+    readonly noindex: boolean;
+    /** Content-Security-Policy for a meta tag; '' for none. */
+    readonly csp: string;
+}
+/**
+ * Render a Markdown document into a complete, styled HTML page. Raw HTML in the Markdown is
+ * escaped and unsafe link protocols are dropped (micromark defaults).
+ * @param input - title, optional description, Markdown source.
+ * @param options - page decorations.
+ * @returns the HTML document.
+ */
+export declare function renderMarkdownPage(input: {
+    title: string;
+    description?: string | undefined;
+    markdown: string;
+}, options: PageOptions): string;
+/** Attribute that marks the tags this plugin injects, so they can be removed again. */
+export declare const INJECTED_ATTRIBUTE = "data-dsh-artifacts";
+/**
+ * Remove tags a previous publish injected, giving back the page as its author wrote it.
+ * @param html - served page.
+ * @returns the page without plugin-injected meta tags.
+ */
+export declare function stripInjected(html: string): string;
+/**
+ * Prepare an HTML page for publishing: complete a fragment into a document and add the
+ * configured meta tags right after `<head>` so they apply before any other content. Tags from
+ * earlier publishes are removed first, so read-modify-publish cycles do not pile them up.
+ * @param input - title used when the source is a fragment, and the HTML source.
+ * @param options - page decorations.
+ * @returns the HTML document.
+ */
+export declare function prepareHtmlPage(input: {
+    title: string;
+    html: string;
+}, options: PageOptions): string;
+/** @param text - text for an HTML text node. */
+export declare function escapeText(text: string): string;
+/** @param text - text for a double-quoted HTML attribute. */
+export declare function escapeAttribute(text: string): string;

package/lib/render.js

@@ -0,0 +1,128 @@
+/** Turn artifact sources into the HTML that GitHub Pages serves. */
+import { micromark } from 'micromark';
+import { gfm, gfmHtml } from 'micromark-extension-gfm';
+const GENERATOR = 'dsh-gh-pages-artifacts';
+/**
+ * Render a Markdown document into a complete, styled HTML page. Raw HTML in the Markdown is
+ * escaped and unsafe link protocols are dropped (micromark defaults).
+ * @param input - title, optional description, Markdown source.
+ * @param options - page decorations.
+ * @returns the HTML document.
+ */
+export function renderMarkdownPage(input, options) {
+    const body = micromark(input.markdown, { extensions: [gfm()], htmlExtensions: [gfmHtml()] });
+    const head = [
+        '<meta charset="utf-8">',
+        ...securityMeta(options),
+        '<meta name="viewport" content="width=device-width, initial-scale=1">',
+        `<meta name="generator" content="${GENERATOR}">`,
+        ...input.description === undefined ? [] : [`<meta name="description" content="${escapeAttribute(input.description)}">`],
+        `<title>${escapeText(input.title)}</title>`,
+        `<style>${DOCUMENT_CSS}</style>`,
+    ];
+    return `<!doctype html>\n<html lang="en">\n<head>\n${head.join('\n')}\n</head>\n<body>\n<main class="doc">\n${body}</main>\n</body>\n</html>\n`;
+}
+/** Attribute that marks the tags this plugin injects, so they can be removed again. */
+export const INJECTED_ATTRIBUTE = 'data-dsh-artifacts';
+const INJECTED_TAG = new RegExp(`\\r?\\n?[ \\t]*<meta\\b[^>]*\\b${INJECTED_ATTRIBUTE}\\b[^>]*>`, 'gi');
+/**
+ * Remove tags a previous publish injected, giving back the page as its author wrote it.
+ * @param html - served page.
+ * @returns the page without plugin-injected meta tags.
+ */
+export function stripInjected(html) {
+    return html.replace(INJECTED_TAG, '');
+}
+/**
+ * Prepare an HTML page for publishing: complete a fragment into a document and add the
+ * configured meta tags right after `<head>` so they apply before any other content. Tags from
+ * earlier publishes are removed first, so read-modify-publish cycles do not pile them up.
+ * @param input - title used when the source is a fragment, and the HTML source.
+ * @param options - page decorations.
+ * @returns the HTML document.
+ */
+export function prepareHtmlPage(input, options) {
+    const html = stripInjected(input.html.replace(/^\uFEFF/, ''));
+    const additions = securityMeta(options);
+    const headOpen = firstTagOutsideComments(html, /<head(?:\s[^>]*)?>/gi);
+    if (headOpen !== undefined) {
+        const at = headOpen.index + headOpen.length;
+        return additions.length === 0 ? html : `${html.slice(0, at)}\n${additions.join('\n')}${html.slice(at)}`;
+    }
+    const htmlOpen = firstTagOutsideComments(html, /<html(?:\s[^>]*)?>/gi);
+    if (htmlOpen !== undefined) {
+        const at = htmlOpen.index + htmlOpen.length;
+        const head = ['<meta charset="utf-8">', ...additions];
+        if (!/<title[\s>]/i.test(html))
+            head.push(`<title>${escapeText(input.title)}</title>`);
+        return `${html.slice(0, at)}\n<head>\n${head.join('\n')}\n</head>${html.slice(at)}`;
+    }
+    const head = [
+        '<meta charset="utf-8">',
+        ...additions,
+        '<meta name="viewport" content="width=device-width, initial-scale=1">',
+        `<meta name="generator" content="${GENERATOR}">`,
+        `<title>${escapeText(input.title)}</title>`,
+    ];
+    const doctype = /^\s*<!doctype html[^>]*>/i.exec(html);
+    const content = doctype === null ? html : html.slice(doctype[0].length);
+    return `<!doctype html>\n<html lang="en">\n<head>\n${head.join('\n')}\n</head>\n<body>\n${content.trim()}\n</body>\n</html>\n`;
+}
+/** Find the first match of a tag pattern that is not inside an HTML comment. */
+function firstTagOutsideComments(html, pattern) {
+    const comments = [];
+    for (const match of html.matchAll(/<!--[\s\S]*?(?:-->|$)/g))
+        comments.push([match.index, match.index + match[0].length]);
+    for (const match of html.matchAll(pattern)) {
+        if (!comments.some(([start, end]) => match.index >= start && match.index < end))
+            return { index: match.index, length: match[0].length };
+    }
+    return undefined;
+}
+function securityMeta(options) {
+    const tags = [];
+    if (options.csp !== '')
+        tags.push(`<meta http-equiv="Content-Security-Policy" content="${escapeAttribute(options.csp)}" ${INJECTED_ATTRIBUTE}>`);
+    // Crawlers apply the most restrictive robots directive, so this wins over any the page sets.
+    if (options.noindex)
+        tags.push(`<meta name="robots" content="noindex, nofollow" ${INJECTED_ATTRIBUTE}>`);
+    return tags;
+}
+/** @param text - text for an HTML text node. */
+export function escapeText(text) {
+    return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+/** @param text - text for a double-quoted HTML attribute. */
+export function escapeAttribute(text) {
+    return escapeText(text).replace(/"/g, '&quot;');
+}
+const DOCUMENT_CSS = `
+:root{color-scheme:light dark;--bg:#ffffff;--fg:#1f2328;--muted:#59636e;--border:#d1d9e0;--code-bg:#f6f8fa;--link:#0969da;--accent-bg:#f6f8fa}
+@media (prefers-color-scheme:dark){:root{--bg:#0d1117;--fg:#e6edf3;--muted:#9198a1;--border:#3d444d;--code-bg:#151b23;--link:#4493f8;--accent-bg:#151b23}}
+*{box-sizing:border-box}
+html{-webkit-text-size-adjust:100%}
+body{margin:0;background:var(--bg);color:var(--fg);font:16px/1.65 -apple-system,BlinkMacSystemFont,"Segoe UI","Noto Sans",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji";overflow-wrap:break-word}
+.doc{max-width:46rem;margin:0 auto;padding:3rem 1rem 4rem}
+h1,h2,h3,h4,h5,h6{line-height:1.25;margin:2rem 0 1rem;font-weight:600}
+h1{font-size:2rem;margin-top:0;padding-bottom:.3em;border-bottom:1px solid var(--border)}
+h2{font-size:1.5rem;padding-bottom:.3em;border-bottom:1px solid var(--border)}
+h3{font-size:1.25rem}
+p,ul,ol,dl,table,pre,blockquote{margin:0 0 1rem}
+a{color:var(--link);text-decoration:none}
+a:hover{text-decoration:underline}
+img,video{max-width:100%;height:auto}
+hr{border:0;border-top:1px solid var(--border);margin:2rem 0}
+blockquote{padding:0 1em;color:var(--muted);border-left:.25em solid var(--border)}
+code,pre{font-family:ui-monospace,SFMono-Regular,"SF Mono",Menlo,Consolas,"Liberation Mono",monospace;font-size:.875em}
+code{padding:.2em .4em;background:var(--code-bg);border-radius:6px}
+pre{padding:1rem;overflow:auto;background:var(--code-bg);border-radius:6px;line-height:1.45}
+pre code{padding:0;background:transparent;font-size:inherit}
+table{display:block;width:max-content;max-width:100%;overflow:auto;border-collapse:collapse}
+th,td{padding:.4rem .8rem;border:1px solid var(--border)}
+th{font-weight:600;background:var(--accent-bg)}
+li+li{margin-top:.25em}
+ul.contains-task-list{list-style:none;padding-left:1.2em}
+input[type=checkbox]{margin:0 .4em 0 -1.2em;vertical-align:middle}
+.footnotes{font-size:.875rem;color:var(--muted)}
+@media print{body{background:#fff;color:#000}.doc{padding:0}}
+`.trim();