@johnhenry/sitefile 0.0.0-stage → 0.0.1

package/lib/src/fingerprint.d.ts

@@ -0,0 +1,40 @@
+import { type SourceSpan } from './errors.js';
+import { Tree } from './tree.js';
+/** Hex digits of the SHA-256 of the content in a fingerprinted name. */
+export declare const HASH_LENGTH = 10;
+/**
+ * Check a FINGERPRINT pattern: an absolute path (NFC) with no control characters. A trailing `/`
+ * means everything below that directory (`/assets/` is `/assets/**`).
+ */
+export declare function checkPattern(raw: string, span: SourceSpan): string;
+/**
+ * Whether a tree path matches a pattern. Segments are compared one by one; a `**` segment matches any
+ * number of segments (also none). Matching is by code point and case-sensitive.
+ */
+export declare function globMatches(pattern: string, path: string): boolean;
+/** `name.<hash>.ext`: the hash goes before the last extension (`app.min.<hash>.js`), or at the end (`LICENSE.<hash>`, `.env.<hash>`). */
+export declare function hashedName(path: string, hash: string): string;
+export interface FingerprintOp {
+    readonly patterns: readonly string[];
+    readonly manifest?: string;
+    /** The directory the site is served from (the EXPORT path): absolute references resolve below it. */
+    readonly root: string;
+    readonly overwrite: boolean;
+    readonly span: SourceSpan;
+}
+export interface Fingerprinted {
+    readonly tree: Tree;
+    /** Old path -> new path, sorted by old path. */
+    readonly renames: ReadonlyArray<readonly [string, string]>;
+}
+/** The manifest: a JSON object of old path -> new path, sorted, two-space indented, with a final newline. */
+export declare function manifestJson(renames: ReadonlyArray<readonly [string, string]>): string;
+/**
+ * Fingerprint the files of `tree` that match the patterns. Each is renamed to `name.<hash>.ext`, where the
+ * hash is of its final content: a CSS file's references to other fingerprinted files are rewritten first, so
+ * its hash covers them (a cycle of such references is an error). Then every HTML and CSS file in the tree has
+ * its references to renamed files rewritten. The renamed and rewritten files get the origin `origin`.
+ */
+export declare function fingerprint(tree: Tree, op: FingerprintOp, origin: string, warn: (m: string) => void): Fingerprinted;
+/** Compose rename maps: `earlier` then `later` (a renamed file renamed again maps to its last name). */
+export declare function composeRenames(earlier: ReadonlyMap<string, string>, later: ReadonlyArray<readonly [string, string]>): Map<string, string>;

package/lib/src/fingerprint.js

@@ -0,0 +1,168 @@
+// FINGERPRINT (docs/LANGUAGE.md, "Fingerprinting"): rename assets to content-hashed names and rewrite
+// the HTML and CSS that reference them. Ported as rust/src/fingerprint.rs: both must produce the same
+// tree, manifest and messages.
+import { createHash } from 'node:crypto';
+import { SitefileError } from './errors.js';
+import { referenceKind, resolveReference, rewriteReferences, scanFile } from './links.js';
+import { nfc } from './paths.js';
+import { makeFile, Tree } from './tree.js';
+/** Hex digits of the SHA-256 of the content in a fingerprinted name. */
+export const HASH_LENGTH = 10;
+/** Names FINGERPRINT never renames (besides HTML pages): files hosts look up by name. */
+const FIXED_NAMES = new Set(['_redirects', '_headers']);
+// ---------------------------------------------------------------- patterns
+/**
+ * Check a FINGERPRINT pattern: an absolute path (NFC) with no control characters. A trailing `/`
+ * means everything below that directory (`/assets/` is `/assets/**`).
+ */
+export function checkPattern(raw, span) {
+    if (/[\u0000-\u001f\u007f]/.test(raw))
+        throw new SitefileError('E_VALIDATION', 'FINGERPRINT pattern must not contain control characters', span);
+    if (!raw.startsWith('/'))
+        throw new SitefileError('E_VALIDATION', `FINGERPRINT pattern '${raw}' must be an absolute path starting with '/' (e.g. /assets/ or /**/*.css)`, span);
+    const p = nfc(raw);
+    return p.endsWith('/') ? p + '**' : p;
+}
+/** One path segment against one pattern segment: `*` is any run of characters, `?` any one. */
+function segmentMatches(pat, s, pi = 0, si = 0) {
+    while (pi < pat.length) {
+        const c = pat[pi];
+        if (c === '*') {
+            for (let k = si; k <= s.length; k++)
+                if (segmentMatches(pat, s, pi + 1, k))
+                    return true;
+            return false;
+        }
+        if (si >= s.length || (c !== '?' && c !== s[si]))
+            return false;
+        pi++;
+        si++;
+    }
+    return si === s.length;
+}
+/**
+ * Whether a tree path matches a pattern. Segments are compared one by one; a `**` segment matches any
+ * number of segments (also none). Matching is by code point and case-sensitive.
+ */
+export function globMatches(pattern, path) {
+    const pat = pattern.split('/').slice(1).map((s) => [...s]);
+    const segs = path.split('/').slice(1).map((s) => [...s]);
+    const go = (pi, si) => {
+        if (pi === pat.length)
+            return si === segs.length;
+        const p = pat[pi];
+        if (p.length === 2 && p[0] === '*' && p[1] === '*') {
+            for (let k = si; k <= segs.length; k++)
+                if (go(pi + 1, k))
+                    return true;
+            return false;
+        }
+        return si < segs.length && segmentMatches(p, segs[si]) && go(pi + 1, si + 1);
+    };
+    return go(0, 0);
+}
+// ---------------------------------------------------------------- names
+/** `name.<hash>.ext`: the hash goes before the last extension (`app.min.<hash>.js`), or at the end (`LICENSE.<hash>`, `.env.<hash>`). */
+export function hashedName(path, hash) {
+    const slash = path.lastIndexOf('/');
+    const base = path.slice(slash + 1);
+    const dot = base.lastIndexOf('.');
+    const named = dot > 0 ? `${base.slice(0, dot)}.${hash}${base.slice(dot)}` : `${base}.${hash}`;
+    return path.slice(0, slash + 1) + named;
+}
+function contentHash(bytes) {
+    return createHash('sha256').update(bytes).digest('hex').slice(0, HASH_LENGTH);
+}
+/** Whether FINGERPRINT may rename this path: not an HTML page and not a host file such as `_redirects`. */
+function renamable(path) {
+    return referenceKind(path) !== 'html' && !FIXED_NAMES.has(path.slice(path.lastIndexOf('/') + 1));
+}
+function utf8Compare(a, b) {
+    return Buffer.compare(Buffer.from(a, 'utf8'), Buffer.from(b, 'utf8'));
+}
+/** The manifest: a JSON object of old path -> new path, sorted, two-space indented, with a final newline. */
+export function manifestJson(renames) {
+    if (renames.length === 0)
+        return '{}\n';
+    return '{\n' + renames.map(([a, b]) => `  ${JSON.stringify(a)}: ${JSON.stringify(b)}`).join(',\n') + '\n}\n';
+}
+/**
+ * Fingerprint the files of `tree` that match the patterns. Each is renamed to `name.<hash>.ext`, where the
+ * hash is of its final content: a CSS file's references to other fingerprinted files are rewritten first, so
+ * its hash covers them (a cycle of such references is an error). Then every HTML and CSS file in the tree has
+ * its references to renamed files rewritten. The renamed and rewritten files get the origin `origin`.
+ */
+export function fingerprint(tree, op, origin, warn) {
+    const policy = op.overwrite ? 'overwrite' : 'error';
+    const entries = tree.entries().sort(([a], [b]) => utf8Compare(a, b));
+    const selected = entries.filter(([p]) => renamable(p) && p !== op.manifest && op.patterns.some((pat) => globMatches(pat, p)));
+    if (selected.length === 0)
+        warn(`${origin}: no files match ${op.patterns.join(' ')}`);
+    const isSelected = new Set(selected.map(([p]) => p));
+    const scans = new Map();
+    const scan = (p, node) => {
+        if (!scans.has(p))
+            scans.set(p, scanFile(p, node.bytes));
+        return scans.get(p);
+    };
+    // Hash in dependency order: a CSS file after the fingerprinted files it references.
+    const renamed = new Map();
+    const content = new Map();
+    const state = new Map();
+    const byPath = new Map(entries);
+    const visit = (p, stack) => {
+        const st = state.get(p);
+        if (st === 'done')
+            return;
+        if (st === 'visiting') {
+            const cycle = [...stack.slice(stack.indexOf(p)), p].join(' -> ');
+            throw new SitefileError('E_VALIDATION', `FINGERPRINT: ${cycle} is a cycle of references, so no file's name can include the hash of the files it references; leave one of them out of FINGERPRINT`, op.span);
+        }
+        state.set(p, 'visiting');
+        const node = byPath.get(p);
+        const s = referenceKind(p) === 'css' ? scan(p, node) : undefined;
+        let bytes = node.bytes;
+        if (s) {
+            for (const r of s.refs) {
+                const t = resolveReference(r.url, p, op.root);
+                if (t.kind === 'internal' && !t.dir && isSelected.has(t.path))
+                    visit(t.path, [...stack, p]);
+            }
+            const text = rewriteReferences(s.text, s.refs, p, op.root, (q) => renamed.get(q));
+            if (text !== undefined)
+                bytes = new TextEncoder().encode(text);
+        }
+        renamed.set(p, hashedName(p, contentHash(bytes)));
+        content.set(p, bytes);
+        state.set(p, 'done');
+    };
+    for (const [p] of selected)
+        visit(p, []);
+    const files = [];
+    for (const [p, node] of entries) {
+        if (isSelected.has(p))
+            continue;
+        const s = referenceKind(p) !== undefined ? scan(p, node) : undefined;
+        const text = s ? rewriteReferences(s.text, s.refs, p, op.root, (q) => renamed.get(q)) : undefined;
+        files.push([p, text === undefined ? node : makeFile(new TextEncoder().encode(text), origin, node.mode)]);
+    }
+    const renames = selected.map(([p]) => [p, renamed.get(p)]);
+    let out = Tree.fromFiles(files);
+    out = out.withFiles(selected.map(([p, node]) => [renamed.get(p), makeFile(content.get(p), origin, node.mode)]), policy, op.span);
+    if (op.manifest !== undefined)
+        out = out.withFiles([[op.manifest, makeFile(new TextEncoder().encode(manifestJson(renames)), origin)]], policy, op.span);
+    return { tree: out, renames };
+}
+/** Compose rename maps: `earlier` then `later` (a renamed file renamed again maps to its last name). */
+export function composeRenames(earlier, later) {
+    const next = new Map(later);
+    const intermediate = new Set(earlier.values());
+    const out = new Map();
+    for (const [a, b] of earlier)
+        out.set(a, next.get(b) ?? b);
+    for (const [a, b] of later)
+        if (!intermediate.has(a))
+            out.set(a, b);
+    return out;
+}
+//# sourceMappingURL=fingerprint.js.map

package/lib/src/frontmatter.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Frontmatter parser. The block between the `---` lines is parsed with the
+ * YAML subset documented in `yaml.ts` (nested maps and lists, flow collections,
+ * block scalars, quoted strings, ...), but it must be a mapping at the top level.
+ *
+ * Frontmatter exists only when the text starts (after an optional BOM) with a
+ * `---` line. It ends at the next line that is exactly `---` or `...`.
+ *
+ * Every error is reported as E_FRONTMATTER with the Sitefile-file line and column.
+ */
+export type FrontmatterValue = string | number | boolean | null | FrontmatterValue[] | {
+    [key: string]: FrontmatterValue;
+};
+export interface ParsedFrontmatter {
+    data: {
+        [key: string]: FrontmatterValue;
+    };
+    body: string;
+    /** 1-based line of the file on which `body` starts. */
+    bodyLine: number;
+}
+export declare function parseFrontmatter(text: string, file: string): ParsedFrontmatter;

package/lib/src/frontmatter.js

@@ -0,0 +1,45 @@
+import { SitefileError } from './errors.js';
+import { parseYamlDocument } from './yaml.js';
+export function parseFrontmatter(text, file) {
+    const src = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+    // Split into lines, remembering where each starts so the body can be sliced.
+    const lines = [];
+    const starts = [];
+    for (let pos = 0; pos <= src.length;) {
+        let nl = src.indexOf('\n', pos);
+        if (nl === -1)
+            nl = src.length;
+        starts.push(pos);
+        lines.push(src.slice(pos, nl).replace(/\r$/, ''));
+        pos = nl + 1;
+    }
+    if (lines[0] !== '---')
+        return { data: {}, body: text, bodyLine: 1 };
+    let close = -1;
+    for (let i = 1; i < lines.length; i++) {
+        if (lines[i] === '---' || lines[i] === '...') {
+            close = i;
+            break;
+        }
+    }
+    if (close === -1) {
+        throw new SitefileError('E_FRONTMATTER', "unterminated frontmatter: missing closing '---'", { file, line: 1, column: 1 });
+    }
+    const data = parseBlock(lines.slice(1, close).join('\n'), file);
+    const bodyStart = close + 1 < starts.length ? (starts[close + 1] ?? src.length) : src.length;
+    return { data, body: src.slice(bodyStart), bodyLine: close + 2 };
+}
+function parseBlock(block, file) {
+    try {
+        // The block starts on file line 2 (line 1 is the opening '---').
+        const value = parseYamlDocument(block, file, 2, true);
+        return (value ?? {});
+    }
+    catch (e) {
+        if (e instanceof SitefileError && e.code === 'E_DATA') {
+            throw new SitefileError('E_FRONTMATTER', e.detail, e.span, { cause: e });
+        }
+        throw e;
+    }
+}
+//# sourceMappingURL=frontmatter.js.map

package/lib/src/index.d.ts

@@ -0,0 +1,13 @@
+export { SitefileError, isSitefileError, formatSpan, needsPlugin, needsTool, type ErrorCode, type Needs, type SourceSpan } from './errors.js';
+export type * from './language/ast.js';
+export { parseSitefile } from './language/parser.js';
+export { validate, parseProgram } from './language/validate.js';
+export { plan, type Plan, type Operation, type ImportSpec, type SourceRef } from './planner.js';
+export { build, buildToDirectory, planBuild, loadProgram, type BuildOptions, type BuildResult } from './executor.js';
+export { exportDirectory } from './exporter.js';
+export { BuildMemo, type MemoStats } from './memo.js';
+export { Profiler } from './profile.js';
+export { Tree, makeFile, type FileNode, type ConflictPolicy } from './tree.js';
+export { DEFAULT_ARCHIVE_LIMITS, DEFAULT_FETCH_POLICY, type ArchiveLimits, type FetchPolicy, type Resource } from './resources/types.js';
+export { networkFromEnv, mergeNetwork, networkProblem, hostMatches, type NetworkSettings } from './resources/network.js';
+export { extractArchive } from './resources/archive.js';

package/lib/src/index.js

@@ -0,0 +1,13 @@
+export { SitefileError, isSitefileError, formatSpan, needsPlugin, needsTool } from './errors.js';
+export { parseSitefile } from './language/parser.js';
+export { validate, parseProgram } from './language/validate.js';
+export { plan } from './planner.js';
+export { build, buildToDirectory, planBuild, loadProgram } from './executor.js';
+export { exportDirectory } from './exporter.js';
+export { BuildMemo } from './memo.js';
+export { Profiler } from './profile.js';
+export { Tree, makeFile } from './tree.js';
+export { DEFAULT_ARCHIVE_LIMITS, DEFAULT_FETCH_POLICY } from './resources/types.js';
+export { networkFromEnv, mergeNetwork, networkProblem, hostMatches } from './resources/network.js';
+export { extractArchive } from './resources/archive.js';
+//# sourceMappingURL=index.js.map

package/lib/src/language/ast.d.ts

@@ -0,0 +1,360 @@
+import type { SourceSpan } from '../errors.js';
+/**
+ * A string with `${...}` interpolations, split into parts.
+ * In Sitefile operands `path` is always empty (only ARG/LET names are allowed);
+ * in RENDER templates `path` holds dotted JSON access (`${data.site.title}`).
+ */
+export type TemplatePart = {
+    readonly kind: 'text';
+    readonly value: string;
+} | {
+    readonly kind: 'var';
+    readonly name: string;
+    readonly path: readonly string[];
+    readonly span: SourceSpan;
+};
+/** One instruction argument: a quoted or bare string, possibly interpolated. */
+export interface Operand {
+    readonly parts: readonly TemplatePart[];
+    readonly span: SourceSpan;
+}
+export type ValueType = 'string' | 'number' | 'boolean';
+export type ImportKind = 'file' | 'text' | 'json' | 'tree' | 'markdown' | 'yaml' | 'csv' | 'wbn' | 'html' | 'sitefile';
+export type EscapeMode = 'none' | 'html';
+export interface FromInstruction {
+    readonly kind: 'FROM';
+    readonly span: SourceSpan;
+    /**
+     * `scratch` keyword, an operand (an earlier stage name or a context-relative
+     * directory; the planner decides, see docs/LANGUAGE.md), or `image <ref> [AT <dir>]`.
+     */
+    readonly base: FromBase;
+    readonly alias?: string;
+    /** Set when written as `STAGE <name> [FROM <base>]`; otherwise the instruction is `FROM … [AS name]`. Only used in error messages. */
+    readonly keyword?: 'STAGE';
+}
+/** `FROM image <ref> [AT <dir>]`: start from the files of an OCI site image (a registry or the local store). */
+export interface ImageBase {
+    readonly kind: 'image';
+    readonly ref: Operand;
+    /** `AT <dir>`: the directory inside the image to start from (default: the image's `dev.sitefile.root` label). */
+    readonly at?: Operand;
+}
+export type FromBase = 'scratch' | Operand | ImageBase;
+/** Whether a FROM base is `image <ref>`. */
+export declare function isImageBase(b: FromBase): b is ImageBase;
+export interface ArgInstruction {
+    readonly kind: 'ARG';
+    readonly span: SourceSpan;
+    readonly name: string;
+    /** Defaults to 'string'. */
+    readonly type: ValueType;
+    readonly defaultValue?: Operand;
+}
+export interface LetInstruction {
+    readonly kind: 'LET';
+    readonly span: SourceSpan;
+    readonly name: string;
+    readonly type: ValueType;
+    readonly value: Operand;
+}
+/**
+ * `LET name: html = <markup>` or `LET name: html <<HTML … HTML`: an HTML fragment, a template that
+ * is not evaluated where it is declared but where a RENDER template uses it (`${name}`), against
+ * that RENDER's tree, loop variables and escape mode. Its markup is inserted as written.
+ */
+export interface FragmentInstruction {
+    readonly kind: 'LET';
+    readonly span: SourceSpan;
+    readonly name: string;
+    readonly type: 'html';
+    readonly body: FragmentBody;
+}
+/** The template of an html LET: the rest of its line (`span` is its first character), or a heredoc. */
+export type FragmentBody = {
+    readonly kind: 'line';
+    readonly text: string;
+    readonly span: SourceSpan;
+} | InlineBody;
+/** Whether a LET is an html fragment. */
+export declare function isFragment(ins: Instruction): ins is FragmentInstruction;
+export interface ImportInstruction {
+    readonly kind: 'IMPORT';
+    readonly span: SourceSpan;
+    readonly name: string;
+    readonly uri: Operand;
+    /** Omitted: inferred (local directory -> tree, everything else -> file). */
+    readonly as?: ImportKind;
+    /** `sha256:<64 lowercase hex>` */
+    readonly integrity?: string;
+    /** `SORT BY key [ASC|DESC]`, for `AS markdown` collections. */
+    readonly sort?: {
+        readonly key: string;
+        readonly descending: boolean;
+        readonly span: SourceSpan;
+    };
+    /** `SCHEMA <path>`: a local YAML/JSON schema every document (or list element) must match. */
+    readonly schema?: {
+        readonly path: Operand;
+        readonly span: SourceSpan;
+    };
+    /** `DRAFTS <true|false>`: whether elements with `draft: true` are kept (evaluated by the planner). */
+    readonly drafts?: {
+        readonly value: Operand;
+        readonly span: SourceSpan;
+    };
+    /** `SECRET <id> AS HEADER <Name>` / `SECRET <id> AS BEARER` (build secrets, sent with remote requests). */
+    readonly secrets?: readonly ImportSecret[];
+    /** `ARG NAME=value` (repeatable): build args passed to a Sitefile imported `AS sitefile`. */
+    readonly args?: readonly ImportArg[];
+}
+/** `ARG NAME=value` on an `IMPORT … AS sitefile`: sets an ARG of the imported Sitefile. */
+export interface ImportArg {
+    readonly name: string;
+    readonly value: Operand;
+    readonly span: SourceSpan;
+}
+/** A build secret sent as an HTTP request header of a remote IMPORT. */
+export interface ImportSecret {
+    /** The `--secret id=…` it names. */
+    readonly id: string;
+    /** Header name as written (`Authorization` for BEARER). */
+    readonly header: string;
+    /** `AS BEARER`: the header value is `Bearer <secret>`. */
+    readonly bearer: boolean;
+    readonly span: SourceSpan;
+}
+/**
+ * Content written inline in the Sitefile with a heredoc (`COPY <<CSS /a.css`,
+ * `RENDER <<HTML TO /index.html`): the lines after the instruction, up to a line
+ * that is exactly the delimiter.
+ */
+export interface InlineBody {
+    readonly kind: 'inline';
+    /** The delimiter word, e.g. `HTML`. */
+    readonly delimiter: string;
+    /** The body, each line ending in `\n` (empty string for an empty body). */
+    readonly text: string;
+    /** Span of the `<<` marker. */
+    readonly span: SourceSpan;
+    /** 1-based Sitefile line of the body's first line. */
+    readonly bodyLine: number;
+}
+export declare function isInline(x: Operand | InlineBody): x is InlineBody;
+/** `--from=<stage>`: read the source from an earlier stage's final tree. */
+export interface StageRef {
+    readonly name: string;
+    readonly span: SourceSpan;
+}
+export interface CopyInstruction {
+    readonly kind: 'COPY';
+    readonly span: SourceSpan;
+    readonly source: Operand | InlineBody;
+    readonly dest: Operand;
+    readonly from?: StageRef;
+    /** `--overwrite`: replace files that differ instead of failing. */
+    readonly overwrite: boolean;
+    /** `--exclude=<pattern>` (repeatable): `.sitefileignore` patterns, relative to the source directory. */
+    readonly exclude?: readonly string[];
+    /** `--chmod=644|755`: the mode of every copied file (0o644 or 0o755). */
+    readonly chmod?: number;
+    /** `--parents`: keep the source's path under the destination. */
+    readonly parents?: true;
+}
+export interface RenderInstruction {
+    readonly kind: 'RENDER';
+    readonly span: SourceSpan;
+    readonly template: Operand | InlineBody;
+    readonly dest: Operand;
+    readonly from?: StageRef;
+    /** `--escape=html|none`, default none. */
+    readonly escape: EscapeMode;
+    /** `FOR item IN list [BY key] [PAGE n [FIRST <dest>]]`: render once per element, group or page of an imported list. */
+    readonly each?: RenderEach;
+    readonly overwrite: boolean;
+    /** `--inline-svg`: the template's `${file … | svg}` may paste SVG markup into the page. */
+    readonly inlineSvg?: true;
+}
+/** `FOR item IN list [BY key] [PAGE n [FIRST <dest>]]` of a RENDER. */
+export interface RenderEach {
+    readonly as: string;
+    readonly list: string;
+    readonly span: SourceSpan;
+    /** `BY key`: one element per distinct value of the field (tag pages). */
+    readonly by?: {
+        readonly key: string;
+        readonly span: SourceSpan;
+    };
+    /** `PAGE n [FIRST <dest>]`: pages of n items; FIRST is the first page's destination. */
+    readonly page?: {
+        readonly size: Operand;
+        readonly first?: Operand;
+        readonly span: SourceSpan;
+    };
+}
+export interface ExportInstruction {
+    readonly kind: 'EXPORT';
+    readonly span: SourceSpan;
+    readonly path: Operand;
+    readonly format: ExportFormat;
+    /** `BASE <https-url>`: the URL the exported tree is mounted at (required for `wbn`). */
+    readonly base?: Operand;
+    /** `AT </srv/www>`: where the files live inside the layer (`oci` only). */
+    readonly at?: Operand;
+    /**
+     * `COMPRESSION gzip|none` (`oci` and `wbn` only): how the oci site layer is stored (default gzip),
+     * or whether the whole Web Bundle is gzipped (default none).
+     */
+    readonly compression?: {
+        readonly value: OciCompression;
+        readonly span: SourceSpan;
+    };
+}
+/**
+ * `EXPORT ... COMPRESSION`: for `oci`, the site layer encoding, `gzip` (tar+gzip, the default) or `none`
+ * (plain tar); for `wbn`, `gzip` wraps the bundle in gzip (the family's `.wbn.gz`) and `none` (the default)
+ * writes the plain bundle.
+ */
+export type OciCompression = 'gzip' | 'none';
+export declare const OCI_COMPRESSIONS: readonly OciCompression[];
+/** Parse a compression name (case-insensitive); undefined if unknown. */
+export declare function parseOciCompression(name: string): OciCompression | undefined;
+export type ExportFormat = 'directory' | 'zip' | 'tar' | 'tgz' | 'wbn' | 'oci';
+export declare const EXPORT_FORMATS: readonly ExportFormat[];
+/** Parse a format name (`tar.gz` is an alias for `tgz`); undefined if unknown. */
+export declare function parseExportFormat(name: string): ExportFormat | undefined;
+/** `PLUGIN name FROM ./plugins/x.mjs [INTEGRITY sha256:…]`: declare a renderer. */
+export interface PluginInstruction {
+    readonly kind: 'PLUGIN';
+    readonly span: SourceSpan;
+    readonly name: string;
+    readonly uri: Operand;
+    readonly integrity?: string;
+}
+/** `TOOL name`: declare an external program (run only when the CLI allows it with `--allow-exec name`). */
+export interface ToolInstruction {
+    readonly kind: 'TOOL';
+    readonly span: SourceSpan;
+    readonly name: string;
+}
+/** One `key=value` of a TRANSFORM's `OPTIONS` clause. */
+export interface TransformOption {
+    readonly key: string;
+    readonly value: Operand;
+    readonly span: SourceSpan;
+}
+/**
+ * `TRANSFORM [--overwrite] [--from=stage] [--include=<pattern>…] [--exclude=<pattern>…] [<source>]
+ *   WITH <plugin> TO <dest> [OPTIONS key=value …] [FOR item IN list] [ARGS <argument> …]`
+ * ARGS (last on the line) is the argv template when `<plugin>` is a TOOL. A directory source runs
+ * the plugin once per file (`--include`/`--exclude` pick the files).
+ */
+export interface TransformInstruction {
+    readonly kind: 'TRANSFORM';
+    readonly span: SourceSpan;
+    /** Omitted only with FOR: the plugin then gets just the element. */
+    readonly source?: Operand | InlineBody;
+    readonly from?: StageRef;
+    readonly plugin: string;
+    readonly pluginSpan: SourceSpan;
+    readonly dest: Operand;
+    readonly options: readonly TransformOption[];
+    readonly each?: {
+        readonly as: string;
+        readonly list: string;
+        readonly span: SourceSpan;
+    };
+    /** argv template of a TOOL: `{input}`, `{output}` and `{option.key}` are replaced by the host. */
+    readonly args?: readonly Operand[];
+    /** `--include` patterns (`.sitefileignore` syntax): a directory source's files to keep. */
+    readonly include?: readonly string[];
+    /** `--exclude` patterns (`.sitefileignore` syntax): a directory source's files to leave out. */
+    readonly exclude?: readonly string[];
+    readonly overwrite: boolean;
+}
+/** `SITEMAP [--overwrite] BASE <url> [TO <dest>]`: write a sitemaps.org file listing the stage's `.html` files. */
+export interface SitemapInstruction {
+    readonly kind: 'SITEMAP';
+    readonly span: SourceSpan;
+    readonly base: Operand;
+    /** Default `/sitemap.xml`. */
+    readonly dest?: Operand;
+    readonly overwrite: boolean;
+}
+/**
+ * `FEED [--overwrite] <import> BASE <url> LINK <path> [TO <dest>] [TITLE <text>]`: an Atom feed
+ * from a list import. LINK is evaluated per element, with the element as `${item…}`.
+ */
+export interface FeedInstruction {
+    readonly kind: 'FEED';
+    readonly span: SourceSpan;
+    readonly list: string;
+    readonly listSpan: SourceSpan;
+    readonly base: Operand;
+    readonly link: Operand;
+    /** Default `/feed.xml`. */
+    readonly dest?: Operand;
+    readonly title?: Operand;
+    readonly overwrite: boolean;
+}
+/** The loop variable LINK of a FEED uses for the current element. */
+export declare const FEED_ITEM = "item";
+/** `REDIRECT [--overwrite] <from> <to> [STATUS 301|302|303|307|308]`: a line of `/_redirects`. */
+export interface RedirectInstruction {
+    readonly kind: 'REDIRECT';
+    readonly span: SourceSpan;
+    readonly from: Operand;
+    readonly to: Operand;
+    readonly status: RedirectStatus;
+    readonly overwrite: boolean;
+}
+export type RedirectStatus = 301 | 302 | 303 | 307 | 308;
+export declare const REDIRECT_STATUSES: readonly RedirectStatus[];
+/** `HEADER [--overwrite] <path-pattern> <Name>: <value …>`: a header in `/_headers`. */
+export interface HeaderInstruction {
+    readonly kind: 'HEADER';
+    readonly span: SourceSpan;
+    readonly pattern: Operand;
+    /** The header name without its trailing `:`. */
+    readonly name: Operand;
+    /** The rest of the line; the words are joined with one space. */
+    readonly value: readonly Operand[];
+    readonly overwrite: boolean;
+}
+/** `FINGERPRINT [--overwrite] <pattern>… [MANIFEST <dest>]`: rename matching files to `name.<hash>.ext` and rewrite the HTML and CSS that reference them. */
+export interface FingerprintInstruction {
+    readonly kind: 'FINGERPRINT';
+    readonly span: SourceSpan;
+    /** Absolute path patterns (`*`, `?`, `**`; a trailing `/` means everything below). */
+    readonly patterns: readonly Operand[];
+    /** `MANIFEST <dest>`: where to write the JSON map of old to new paths. */
+    readonly manifest?: Operand;
+    readonly overwrite: boolean;
+}
+/** `CHECKLINKS [--warn] [--external]`: report references in the stage's HTML and CSS that point at nothing. */
+export interface CheckLinksInstruction {
+    readonly kind: 'CHECKLINKS';
+    readonly span: SourceSpan;
+    /** `--warn`: print each broken link as a warning instead of failing. */
+    readonly warn: boolean;
+    /** `--external`: also request http(s) links (under the network policy). */
+    readonly external: boolean;
+}
+export type Instruction = FromInstruction | ArgInstruction | LetInstruction | FragmentInstruction | ImportInstruction | CopyInstruction | RenderInstruction | PluginInstruction | ToolInstruction | TransformInstruction | SitemapInstruction | FeedInstruction | RedirectInstruction | HeaderInstruction | FingerprintInstruction | CheckLinksInstruction | ExportInstruction;
+/** A parsed and semantically validated Sitefile. */
+export interface Program {
+    readonly file: string;
+    readonly instructions: readonly Instruction[];
+}
+export declare function literalText(op: Operand | InlineBody): string | undefined;
+/** Names of ARG, LET, IMPORT and stages (`FROM … AS name`, `--from=name`). */
+export declare const IDENT_RE: RegExp;
+/** A stage of an imported Sitefile: `<import>+<stage>` (`IMPORT theme … AS sitefile`, then `FROM theme+assets`). */
+export declare const IMPORTED_STAGE_RE: RegExp;
+/** `theme+assets` -> `{ import: 'theme', stage: 'assets' }`; undefined for anything else. */
+export declare function importedStage(name: string): {
+    readonly import: string;
+    readonly stage: string;
+} | undefined;
+/** Every stage alias declared anywhere in the file. */
+export declare function stageNames(instructions: readonly Instruction[]): Set<string>;