@johnhenry/sitefile 0.0.0-stage → 0.0.1

package/lib/src/wbn.js

@@ -0,0 +1,241 @@
+import { SitefileError } from './errors.js';
+import { cborArray, cborBytes, cborMap, cborText, cborUint } from './cbor.js';
+import { headersFor, matchRedirect, parseHeaderRules, parseRedirectRules } from './serve-rules.js';
+/**
+ * Unsigned Web Bundle, format version "b2"
+ * (draft-ietf-wpack-bundled-responses). Layout, as one CBOR array:
+ *
+ *   [ magic h'F09F8C90F09F93A6' ("🌐📦"), version h'62320000' ("b2\0\0"),
+ *     section-lengths (bstr holding a CBOR array of name, length, ...),
+ *     sections (array: index, [primary,] responses),
+ *     length (8-byte big-endian bstr: size of the whole bundle) ]
+ *
+ * (b1 had six items with the primary URL in the header and variants in the
+ * index; b2 has five, so the header starts 0x85.) Verified against the WICG
+ * reference reader `dump-bundle` (see test/export-formats.test.ts).
+ *
+ * index    = { url => [ offset, length ] }; offset/length
+ *            locate the response inside the responses section, counted from
+ *            the first byte of that section's CBOR encoding.
+ * responses = [ [ headers (bstr holding { h':status' => h'200', h'content-type' => ... }), payload bstr ] ... ]
+ *
+ * primary  = text URL, present only when /index.html exists. No signatures.
+ *
+ * The tree's own `/_headers` and `/_redirects` (what HEADER and REDIRECT
+ * write) are applied the way `sitefile serve` applies them (serve-rules.ts):
+ * see {@link bundleResponses}.
+ */
+const MAGIC = Buffer.from('f09f8c90f09f93a6', 'hex');
+const VERSION = Buffer.from([0x62, 0x32, 0x00, 0x00]);
+const TEXT_CHARSET = '; charset=utf-8';
+const MIME = {
+    html: 'text/html' + TEXT_CHARSET,
+    htm: 'text/html' + TEXT_CHARSET,
+    css: 'text/css' + TEXT_CHARSET,
+    js: 'text/javascript' + TEXT_CHARSET,
+    mjs: 'text/javascript' + TEXT_CHARSET,
+    json: 'application/json' + TEXT_CHARSET,
+    svg: 'image/svg+xml' + TEXT_CHARSET,
+    txt: 'text/plain' + TEXT_CHARSET,
+    xml: 'application/xml' + TEXT_CHARSET,
+    webmanifest: 'application/manifest+json' + TEXT_CHARSET,
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    gif: 'image/gif',
+    webp: 'image/webp',
+    avif: 'image/avif',
+    ico: 'image/x-icon',
+    wasm: 'application/wasm',
+    woff: 'font/woff',
+    woff2: 'font/woff2',
+    pdf: 'application/pdf',
+    mp4: 'video/mp4',
+    webm: 'video/webm',
+    mp3: 'audio/mpeg',
+};
+export function mimeTypeFor(path) {
+    const base = path.slice(path.lastIndexOf('/') + 1);
+    const dot = base.lastIndexOf('.');
+    const ext = dot < 0 ? '' : base.slice(dot + 1).toLowerCase();
+    return MIME[ext] ?? 'application/octet-stream';
+}
+/** An absolute https URL ending in `/`, without credentials, query or fragment. Returns its normalized form. */
+export function validateBaseUrl(raw) {
+    if (raw === undefined || raw === '') {
+        throw new SitefileError('E_VALIDATION', "wbn export needs a base URL: use 'EXPORT <path> AS wbn BASE https://example.com/' or --base-url");
+    }
+    let u;
+    try {
+        u = new URL(raw);
+    }
+    catch {
+        throw new SitefileError('E_VALIDATION', `invalid base URL '${raw}': not an absolute URL`);
+    }
+    if (u.protocol !== 'https:')
+        throw new SitefileError('E_VALIDATION', `invalid base URL '${raw}': must be https`);
+    if (u.username || u.password)
+        throw new SitefileError('E_VALIDATION', `invalid base URL '${raw}': must not contain credentials`);
+    if (u.search || u.hash || raw.includes('?') || raw.includes('#')) {
+        throw new SitefileError('E_VALIDATION', `invalid base URL '${raw}': must not have a query or fragment`);
+    }
+    if (!raw.endsWith('/'))
+        throw new SitefileError('E_VALIDATION', `invalid base URL '${raw}': must end with '/'`);
+    return u.href;
+}
+function encodePath(p) {
+    return p
+        .slice(1)
+        .split('/')
+        .map((seg) => encodeURIComponent(seg))
+        .join('/');
+}
+const enc = new TextEncoder();
+const bstr = (s) => cborBytes(enc.encode(s));
+export function writeWebBundle(tree, baseUrl) {
+    const base = validateBaseUrl(baseUrl);
+    const { responses, urls } = bundleResponses(tree);
+    const index = [];
+    // Offset of the first response = size of the responses array head.
+    const offsets = [];
+    let offset = headSize(responses.length);
+    for (const r of responses) {
+        offsets.push(offset);
+        offset += r.length;
+    }
+    for (const [path, i] of urls) {
+        // b2 index entries are [offset, length]; b1's leading variants value is gone.
+        index.push([cborText(base + encodePath(path)), cborArray([cborUint(offsets[i]), cborUint(responses[i].length)])]);
+    }
+    const responsesSection = cborArray(responses);
+    const indexSection = cborMap(index);
+    // b2 moves the primary URL out of the header into an optional "primary"
+    // section; sections are ordered index, primary, responses (always last).
+    const sections = [['index', indexSection]];
+    if (tree.isFile('/index.html'))
+        sections.push(['primary', cborText(base)]);
+    sections.push(['responses', responsesSection]);
+    const sectionLengths = cborArray(sections.flatMap(([name, bytes]) => [cborText(name), cborUint(bytes.length)]));
+    // The trailing length field is fixed-size, so the total is computable first.
+    const parts = [
+        Buffer.from([0x85]), // b2: array(5) = magic, version, section-lengths, sections, length
+        cborBytes(MAGIC),
+        cborBytes(VERSION),
+        cborBytes(sectionLengths),
+        cborArray(sections.map(([, bytes]) => bytes)),
+    ];
+    const lenField = 1 + 8; // bstr(8) head + 8 bytes
+    const total = parts.reduce((n, b) => n + b.length, 0) + lenField;
+    const len = Buffer.alloc(8);
+    len.writeBigUInt64BE(BigInt(total));
+    return Buffer.concat([...parts, cborBytes(len)]);
+}
+/** One encoded response: `[headers bstr, payload bstr]`, header names in CBOR map (bytewise) order. */
+function encodeResponse(status, headers, body) {
+    const map = cborMap([[bstr(':status'), bstr(String(status))], ...[...headers].map(([k, v]) => [bstr(k), bstr(v)])]);
+    return cborArray([cborBytes(map), cborBytes(body)]);
+}
+const isRedirectStatus = (s) => s >= 301 && s <= 308;
+/** The rule `serve` would apply first in one pass (forced or not), when it is an exact-path 3xx redirect. */
+function exactRedirect(rules, forced, path) {
+    const i = rules.findIndex((r) => r.force === forced && matchRedirect(r, path) !== undefined);
+    return i >= 0 && !rules[i].splat && isRedirectStatus(rules[i].status) ? i : undefined;
+}
+/**
+ * The responses section and its URLs (tree paths, percent-encoded by the caller), as `sitefile
+ * serve` would answer them:
+ *
+ * - Each file is a 200 with `content-type` and the `/_headers` blocks whose pattern matches its
+ *   URL path (`headersFor`; a `content-type` there replaces the inferred one). A directory URL
+ *   (`/docs/` for `/docs/index.html`) matches with its trailing slash, so it gets its own
+ *   response when its headers differ from the file URL's.
+ * - An exact-path `/_redirects` rule with a 3xx status becomes a response with that `:status`, a
+ *   `location` of the rule's target as written, and an empty body: at its path when no file
+ *   would be served there, and over the file when forced (`301!`). Like `serve`, the first rule
+ *   matching the path decides; when that is a splat or a 200/404 rewrite, the bundle leaves the
+ *   path to `/_redirects`. Splat rules and rewrites are not baked in.
+ *
+ * `/_headers` and `/_redirects` stay in the bundle as files. Responses are deduplicated (both URLs
+ * of an index page share one when their headers agree; identical redirects share one).
+ */
+export function bundleResponses(tree) {
+    const text = (p) => {
+        const f = tree.get(p);
+        return f ? new TextDecoder().decode(f.bytes) : '';
+    };
+    const redirects = parseRedirectRules(text('/_redirects'));
+    const headerRules = parseHeaderRules(text('/_headers'));
+    const responses = [];
+    const urls = [];
+    const taken = new Set();
+    const redirectResponse = new Map();
+    const redirectTo = (rule) => {
+        const r = redirects[rule];
+        const key = `${r.status} ${r.to}`;
+        let i = redirectResponse.get(key);
+        if (i === undefined) {
+            i = responses.push(encodeResponse(r.status, [['location', r.to]], new Uint8Array(0))) - 1;
+            redirectResponse.set(key, i);
+        }
+        return i;
+    };
+    const fileResponse = (p, bytes, urlPath) => {
+        const headers = new Map([['content-type', mimeTypeFor(p)]]);
+        for (const [k, v] of Object.entries(headersFor(headerRules, urlPath)))
+            headers.set(k, v);
+        return encodeResponse(200, headers, bytes);
+    };
+    for (const [p, node] of tree.entries()) {
+        // [URL path, the path `serve` matches redirects against (no trailing slash)]
+        const targets = [[p, p]];
+        if (p === '/index.html' || p.endsWith('/index.html')) {
+            const dir = p.slice(0, -'index.html'.length);
+            targets.push([dir, dir === '/' ? '/' : dir.slice(0, -1)]);
+        }
+        let last;
+        for (const [urlPath, matchPath] of targets) {
+            taken.add(urlPath);
+            const forced = exactRedirect(redirects, true, matchPath);
+            if (forced !== undefined) {
+                urls.push([urlPath, redirectTo(forced)]);
+                continue;
+            }
+            const r = fileResponse(p, node.bytes, urlPath);
+            if (last === undefined || !Buffer.from(last.bytes).equals(r))
+                last = { bytes: r, i: responses.push(r) - 1 };
+            urls.push([urlPath, last.i]);
+        }
+    }
+    // Redirects at paths without a file: `serve` applies a forced rule first, then (when nothing
+    // is served there: no file, no `<path>.html`, no directory) the first other matching rule.
+    const servable = (p) => tree.isFile(p) && p !== '/_redirects' && p !== '/_headers';
+    for (const r of redirects) {
+        if (r.splat || !isRedirectStatus(r.status) || taken.has(r.from))
+            continue;
+        const path = r.from;
+        taken.add(path);
+        let rule = exactRedirect(redirects, true, path);
+        if (rule === undefined) {
+            const firstForced = redirects.some((x) => x.force && matchRedirect(x, path) !== undefined);
+            const served = path === '/' ? servable('/index.html') : servable(path) || servable(`${path}.html`) || tree.isDirectory(path);
+            if (firstForced || served)
+                continue;
+            rule = exactRedirect(redirects, false, path);
+        }
+        if (rule !== undefined)
+            urls.push([path, redirectTo(rule)]);
+    }
+    return { responses, urls };
+}
+function headSize(n) {
+    if (n < 24)
+        return 1;
+    if (n < 0x100)
+        return 2;
+    if (n < 0x10000)
+        return 3;
+    if (n < 0x100000000)
+        return 5;
+    return 9;
+}
+//# sourceMappingURL=wbn.js.map

package/lib/src/yaml.d.ts

@@ -0,0 +1,34 @@
+/**
+ * A small, safe YAML subset parser (no dependencies, no code execution).
+ *
+ * Supported:
+ * - Block style by indentation (spaces only; a tab in indentation is an error).
+ * - Mappings `key: value`, nested mappings, sequences `- item`, sequences of
+ *   mappings (`- name: a` / `  url: /a`), mappings of sequences (including
+ *   the indentless form), arbitrary nesting up to 64 levels.
+ * - Scalars: "double" quoted (escapes \" \\ \n \t), 'single' quoted ('' escape),
+ *   plain strings (trimmed; ` #` begins a comment), `true`/`false`, integers
+ *   and decimals (numbers), `null` / `~` / empty (null). Dates such as
+ *   2026-01-02 stay strings.
+ * - Flow collections on a single line: `[a, b, {x: 1}]`, `{a: 1, b: [2, 3]}`.
+ * - Block scalars `|` (literal) and `>` (folded) with optional `-` / `+`
+ *   chomping; the indentation comes from the first content line.
+ * - Comments, blank lines, an optional leading `---` and a trailing `...`.
+ * - Keys are plain or quoted scalars and are always strings. Duplicate keys
+ *   are an error. A `__proto__` key is stored as ordinary own data.
+ * - An empty document is `null`.
+ *
+ * Not supported (E_DATA at the offending line and column): anchors and aliases
+ * (`&` `*`), tags (`!`), multiple documents, complex keys (`? `), merge keys
+ * (`<<`), multi-line flow collections, multi-line plain or quoted scalars,
+ * block scalar indentation indicators, tabs for indentation.
+ *
+ * `firstLine` is the 1-based file line of the first line of `text`, so errors
+ * point at the right place when the YAML is embedded in another file.
+ */
+export declare function parseYaml(text: string, file: string, firstLine?: number): unknown;
+/**
+ * Like parseYaml; with `rootMapping` the document must be a mapping (or empty)
+ * and indented content at the top is rejected. Used by frontmatter.
+ */
+export declare function parseYamlDocument(text: string, file: string, firstLine: number, rootMapping: boolean): unknown;