@johnhenry/sitefile 0.0.0-stage → 0.0.0

package/lib/src/oci.js

@@ -0,0 +1,380 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { gunzipSync } from 'node:zlib';
+import { gzipTar, writeTar } from './archive-writers.js';
+import { sha256 } from './digest.js';
+import { SitefileError } from './errors.js';
+import { normalizeVirtual } from './paths.js';
+import { parseRef } from './ref.js';
+import { extractArchive } from './resources/archive.js';
+import { makeFile, Tree } from './tree.js';
+/**
+ * OCI image-spec v1.1 writer and reader for Sitefile images.
+ *
+ * A Sitefile image has exactly one layer: a deterministic tar of the site's files placed under a
+ * root directory (default /srv/www), gzip-compressed. It carries files only: it has no entrypoint
+ * and is not runnable by itself (use it with `COPY --from=` in a Dockerfile). Everything that is
+ * hashed (config, manifest, index) is canonical JSON, so the same tree and options always give the
+ * same manifest digest.
+ *
+ * Layout (the on-disk image store is this layout; `save`/`EXPORT AS oci` write it standalone):
+ *   oci-layout            {"imageLayoutVersion":"1.0.0"}
+ *   index.json            image index; entries carry org.opencontainers.image.ref.name
+ *   blobs/sha256/<hex>    manifest, config and layer blobs
+ */
+export const DEFAULT_OCI_ROOT = '/srv/www';
+export const MEDIA = {
+    manifest: 'application/vnd.oci.image.manifest.v1+json',
+    config: 'application/vnd.oci.image.config.v1+json',
+    layer: 'application/vnd.oci.image.layer.v1.tar+gzip',
+    /** Uncompressed layer (`EXPORT ... COMPRESSION none`): the blob is the tar itself, digest = diff_id. */
+    layerTar: 'application/vnd.oci.image.layer.v1.tar',
+    index: 'application/vnd.oci.image.index.v1+json',
+    dockerManifest: 'application/vnd.docker.distribution.manifest.v2+json',
+    dockerList: 'application/vnd.docker.distribution.manifest.list.v2+json',
+    dockerConfig: 'application/vnd.docker.container.image.v1+json',
+    dockerLayer: 'application/vnd.docker.image.rootfs.diff.tar.gzip',
+};
+export const ANN_BASE_NAME = 'org.opencontainers.image.base.name';
+export const ANN_BASE_DIGEST = 'org.opencontainers.image.base.digest';
+export const ANN = {
+    refName: 'org.opencontainers.image.ref.name',
+    title: 'org.opencontainers.image.title',
+    source: 'org.opencontainers.image.source',
+    revision: 'org.opencontainers.image.revision',
+    root: 'dev.sitefile.root',
+    files: 'dev.sitefile.files',
+    size: 'dev.sitefile.size',
+    stored: 'dev.sitefile.created',
+};
+const EPOCH_ISO = '1970-01-01T00:00:00Z';
+/** JSON with sorted keys and no whitespace. */
+export function canonicalJson(v) {
+    if (v === null || typeof v !== 'object')
+        return JSON.stringify(v);
+    if (Array.isArray(v))
+        return `[${v.map(canonicalJson).join(',')}]`;
+    const o = v;
+    return `{${Object.keys(o)
+        .filter((k) => o[k] !== undefined)
+        .sort()
+        .map((k) => `${JSON.stringify(k)}:${canonicalJson(o[k])}`)
+        .join(',')}}`;
+}
+const enc = new TextEncoder();
+export function parsePlatform(p) {
+    if (p === undefined)
+        return { os: 'linux', arch: 'amd64' };
+    const m = /^([a-z0-9][a-z0-9._-]*)\/([a-z0-9][a-z0-9._-]*)$/.exec(p);
+    if (!m)
+        throw new SitefileError('E_USAGE', `platform must be os/arch (e.g. linux/amd64), got '${p}'`);
+    return { os: m[1], arch: m[2] };
+}
+/** Validate an in-image root path (absolute, no `..`); returns the normalized form. */
+export function normalizeOciRoot(raw) {
+    return normalizeVirtual(raw ?? DEFAULT_OCI_ROOT, undefined, 'OCI root').path;
+}
+function isoOf(epoch) {
+    return epoch === undefined ? EPOCH_ISO : new Date(epoch * 1000).toISOString().replace(/\.\d{3}Z$/, 'Z');
+}
+/** Build the single-layer image for `tree` (the site's files, rooted at `/`). */
+export function buildOciImage(tree, options = {}) {
+    const root = normalizeOciRoot(options.root);
+    const { os, arch } = parsePlatform(options.platform);
+    const layerTree = Tree.fromFiles(tree.mountedAt(root));
+    const segs = root === '/' ? [] : root.slice(1).split('/');
+    const dirs = segs.map((_, i) => segs.slice(0, i + 1).join('/'));
+    const tar = writeTar(layerTree, { epoch: options.epoch ?? 0, dirs });
+    const uncompressed = options.compression === 'none';
+    const layerBytes = uncompressed ? tar : gzipTar(tar);
+    const diffId = sha256(tar);
+    const layerDigest = uncompressed ? diffId : sha256(layerBytes);
+    const size = tree.entries().reduce((n, [, f]) => n + f.bytes.byteLength, 0);
+    const base = options.base;
+    const baseCfg = base?.config ?? {};
+    const baseInner = (isRecord(baseCfg.config) ? baseCfg.config : {});
+    const labels = {};
+    if (isRecord(baseInner.Labels))
+        for (const [k, v] of Object.entries(baseInner.Labels))
+            if (typeof v === 'string')
+                labels[k] = v;
+    labels[ANN.root] = root;
+    if (options.title)
+        labels[ANN.title] = options.title;
+    if (options.source)
+        labels[ANN.source] = options.source;
+    if (options.revision)
+        labels[ANN.revision] = options.revision;
+    if (base) {
+        labels[ANN_BASE_NAME] = base.name;
+        labels[ANN_BASE_DIGEST] = base.manifestDigest;
+    }
+    for (const [k, v] of Object.entries(options.labels ?? {}))
+        labels[k] = v;
+    // created: SOURCE_DATE_EPOCH when set; else the base's own timestamp (deterministic given the base
+    // digest) or the fixed epoch when there is no base.
+    const baseCreated = typeof baseCfg.created === 'string' ? baseCfg.created : undefined;
+    const created = options.epoch === undefined && baseCreated !== undefined ? baseCreated : isoOf(options.epoch);
+    const baseRootfs = isRecord(baseCfg.rootfs) ? baseCfg.rootfs : {};
+    const baseDiffIds = Array.isArray(baseRootfs.diff_ids) ? baseRootfs.diff_ids : [];
+    const baseHistory = Array.isArray(baseCfg.history) ? baseCfg.history : [];
+    const baseLayers = (base?.layers ?? []).map(normalizeLayer);
+    if (base && baseDiffIds.length !== baseLayers.length)
+        throw new SitefileError('E_STORE', `base image ${base.name}: config diff_ids do not match its layers`);
+    const configBytes = enc.encode(canonicalJson({
+        ...baseCfg,
+        architecture: base && typeof baseCfg.architecture === 'string' ? baseCfg.architecture : arch,
+        os: base && typeof baseCfg.os === 'string' ? baseCfg.os : os,
+        created,
+        config: { ...baseInner, Labels: labels },
+        rootfs: { type: 'layers', diff_ids: [...baseDiffIds, diffId] },
+        history: [...baseHistory, { created: isoOf(options.epoch), created_by: 'sitefile', comment: 'static site files', author: 'sitefile' }],
+    }));
+    const configDigest = sha256(configBytes);
+    const annotations = { [ANN.files]: String(tree.size), [ANN.size]: String(size) };
+    if (options.title)
+        annotations[ANN.title] = options.title;
+    if (base) {
+        annotations[ANN_BASE_NAME] = base.name;
+        annotations[ANN_BASE_DIGEST] = base.manifestDigest;
+    }
+    const manifestBytes = enc.encode(canonicalJson({
+        schemaVersion: 2,
+        mediaType: MEDIA.manifest,
+        config: { mediaType: MEDIA.config, digest: configDigest, size: configBytes.byteLength },
+        layers: [...baseLayers, { mediaType: uncompressed ? MEDIA.layerTar : MEDIA.layer, digest: layerDigest, size: layerBytes.byteLength }],
+        annotations,
+    }));
+    return { manifestBytes, manifestDigest: sha256(manifestBytes), configBytes, configDigest, layerBytes, layerDigest, diffId, root, baseLayers };
+}
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/** Docker layer media types become their OCI equivalents (same bytes, same digest). */
+function normalizeLayer(d) {
+    const mediaType = d.mediaType === MEDIA.dockerLayer ? MEDIA.layer : d.mediaType;
+    return { mediaType, digest: d.digest, size: d.size };
+}
+export const ANN_CONTAINERD_NAME = 'io.containerd.image.name';
+/**
+ * Index annotations for an exported image named `refName` (`blog:1`, `localhost:5000/blog:1`), in the
+ * convention `docker save` uses so Docker's containerd store finds the image by name after `docker load`:
+ * `io.containerd.image.name` is the full normalized reference and `org.opencontainers.image.ref.name` the tag.
+ * Single-component names live in docker.io/library/, other names without a registry host in docker.io/.
+ */
+export function exportNameAnnotations(refName) {
+    const r = parseRef(refName);
+    const tag = r.tag ?? 'latest';
+    const full = r.registry !== undefined ? r.name : r.name.includes('/') ? r.name : `library/${r.name}`;
+    const host = r.registry ?? 'docker.io';
+    return { [ANN_CONTAINERD_NAME]: `${host}/${full}:${tag}`, [ANN.refName]: tag };
+}
+export function encodeIndex(entries) {
+    const manifests = entries.map((e) => {
+        const annotations = {};
+        if (e.refName)
+            annotations[ANN.refName] = e.refName;
+        if (e.stored)
+            annotations[ANN.stored] = e.stored;
+        Object.assign(annotations, e.extra);
+        return { mediaType: MEDIA.manifest, digest: e.digest, size: e.size, artifactType: e.artifactType, ...(Object.keys(annotations).length ? { annotations } : {}) };
+    });
+    return enc.encode(canonicalJson({ schemaVersion: 2, mediaType: MEDIA.index, manifests }));
+}
+export const OCI_LAYOUT_BYTES = enc.encode('{"imageLayoutVersion":"1.0.0"}');
+const SHA = /^sha256:[0-9a-f]{64}$/;
+export function decodeIndex(bytes) {
+    const j = JSON.parse(Buffer.from(bytes).toString('utf8'));
+    if (j.schemaVersion !== 2 || !Array.isArray(j.manifests))
+        throw new Error('not an OCI image index');
+    return j.manifests.map((m) => {
+        if (typeof m.digest !== 'string' || !SHA.test(m.digest) || typeof m.size !== 'number')
+            throw new Error('bad index entry');
+        const a = (m.annotations ?? {});
+        const ref = a[ANN.refName];
+        const stored = a[ANN.stored];
+        return { digest: m.digest, size: m.size, refName: typeof ref === 'string' ? ref : undefined, stored: typeof stored === 'string' ? stored : undefined };
+    });
+}
+export function blobPathOf(digest) {
+    if (!SHA.test(digest))
+        throw new SitefileError('E_STORE', `invalid digest '${digest}'`);
+    return `/blobs/sha256/${digest.slice(7)}`;
+}
+/**
+ * A standalone OCI image layout holding one image, as a Tree (write it as a directory or tar it).
+ * `referrers` (attestations, `build --provenance/--sbom`) are listed in index.json after the image,
+ * without a name, and their blobs are included.
+ */
+export function layoutTree(img, refName, 
+/** Blobs of the layers below the site layer (digest -> bytes), for images built on a BASE. */
+baseBlobs = new Map(), referrers = []) {
+    const entries = [
+        { digest: img.manifestDigest, size: img.manifestBytes.byteLength, ...(refName ? { extra: exportNameAnnotations(refName) } : {}) },
+        ...referrers.map((r) => ({ digest: r.descriptor.digest, size: r.descriptor.size, artifactType: r.descriptor.artifactType, extra: r.descriptor.annotations })),
+    ];
+    const blobs = new Map([[img.manifestDigest, img.manifestBytes], [img.configDigest, img.configBytes], [img.layerDigest, img.layerBytes], ...baseBlobs]);
+    for (const r of referrers)
+        for (const [d, b] of r.blobs)
+            blobs.set(d, b);
+    const files = [
+        ['/oci-layout', makeFile(OCI_LAYOUT_BYTES, 'oci')],
+        ['/index.json', makeFile(encodeIndex(entries), 'oci')],
+        ...[...blobs].map(([d, b]) => [blobPathOf(d), makeFile(b, 'oci')]),
+    ];
+    return Tree.fromFiles(files);
+}
+/** Deterministic tar of {@link layoutTree}: an "OCI archive" (`.oci.tar`). */
+export function ociArchive(img, refName, epoch, baseBlobs, referrers = []) {
+    return writeTar(layoutTree(img, refName, baseBlobs, referrers), { epoch: epoch ?? 0 });
+}
+function desc(d, what) {
+    const o = d;
+    if (typeof o?.mediaType !== 'string' || typeof o.digest !== 'string' || !SHA.test(o.digest) || typeof o.size !== 'number' || !Number.isSafeInteger(o.size) || o.size < 0) {
+        throw new Error(`bad ${what} descriptor`);
+    }
+    return { mediaType: o.mediaType, digest: o.digest, size: o.size };
+}
+export function parseManifest(bytes) {
+    const m = JSON.parse(Buffer.from(bytes).toString('utf8'));
+    // OCI manifests may omit mediaType; Docker v2 manifests (pulled images) are read as-is.
+    if (m.schemaVersion !== 2 || (m.mediaType !== undefined && m.mediaType !== MEDIA.manifest && m.mediaType !== MEDIA.dockerManifest) || !Array.isArray(m.layers)) {
+        throw new Error('not an image manifest (OCI or Docker v2)');
+    }
+    const annotations = {};
+    for (const [k, v] of Object.entries((m.annotations ?? {})))
+        if (typeof v === 'string')
+            annotations[k] = v;
+    return { config: desc(m.config, 'config'), layers: m.layers.map((l) => desc(l, 'layer')), annotations };
+}
+export function parseConfig(bytes) {
+    const c = JSON.parse(Buffer.from(bytes).toString('utf8'));
+    const ids = c.rootfs?.diff_ids;
+    if (c.rootfs?.type !== 'layers' || !Array.isArray(ids) || !ids.every((d) => typeof d === 'string' && SHA.test(d)))
+        throw new Error('bad rootfs');
+    const labels = {};
+    for (const [k, v] of Object.entries(c.config?.Labels ?? {}))
+        if (typeof v === 'string')
+            labels[k] = v;
+    return { os: String(c.os ?? ''), architecture: String(c.architecture ?? ''), created: String(c.created ?? ''), labels, diffIds: ids };
+}
+/**
+ * Index of the layer holding the site's files: the only layer, or the last one of an image that
+ * carries the `dev.sitefile.root` label (built with BASE). -1 when the image is not a Sitefile image.
+ */
+export function siteLayerIndex(m, cfg) {
+    if (m.layers.length === 1)
+        return 0;
+    return m.layers.length > 1 && cfg.labels[ANN.root] !== undefined ? m.layers.length - 1 : -1;
+}
+/**
+ * Decode a site image's files, verifying the layer digest and diff_id.
+ * `layerBytes` are the compressed blob bytes. Returns the tree under the image's root (its
+ * `dev.sitefile.root` label, else `/`), or under `rootOverride` (`FROM image … AT <dir>`).
+ */
+export async function extractImageFiles(m, cfg, layerBytes, origin, rootOverride) {
+    const idx = siteLayerIndex(m, cfg);
+    const layer = m.layers[idx];
+    if (idx < 0 || !layer || (layer.mediaType !== MEDIA.layer && layer.mediaType !== MEDIA.layerTar)) {
+        throw new SitefileError('E_STORE', `${origin}: not a Sitefile image (only single-layer tar or tar+gzip images, or images built with BASE, hold site files)`);
+    }
+    if (sha256(layerBytes) !== layer.digest || layerBytes.byteLength !== layer.size) {
+        throw new SitefileError('E_STORE', `${origin}: layer blob does not match its digest`);
+    }
+    let tar = layerBytes;
+    if (layer.mediaType === MEDIA.layer) {
+        try {
+            tar = new Uint8Array(gunzipSync(layerBytes));
+        }
+        catch (e) {
+            throw new SitefileError('E_STORE', `${origin}: layer is not valid gzip`, undefined, { cause: e });
+        }
+    }
+    if (sha256(tar) !== cfg.diffIds[idx])
+        throw new SitefileError('E_STORE', `${origin}: layer content does not match the config diff_id`);
+    const root = rootOverride ?? cfg.labels[ANN.root] ?? '/';
+    const all = await extractArchive(tar, origin, { maxEntries: 1_000_000, maxTotalBytes: 8 * 2 ** 30, maxRatio: Number.MAX_SAFE_INTEGER });
+    return all.subtree(normalizeVirtual(root).path);
+}
+/**
+ * Label values for an image built from `contextDir`: the title (directory name),
+ * extra `--label`s, and, only with `--git-labels`, source/revision from a git
+ * checkout. Git labels are opt-in because they make the image ID change with
+ * every commit even when the files don't, and because finding the checkout
+ * reads outside the build context.
+ */
+export async function imageMeta(contextDir, opts = {}) {
+    const info = opts.git ? await gitInfo(contextDir) : {};
+    return { title: path.basename(path.resolve(contextDir)), ...info, ...(opts.labels ? { labels: opts.labels } : {}) };
+}
+const LABEL_KEY = /^[A-Za-z0-9][A-Za-z0-9._\/-]{0,254}$/;
+/** Parse `--label key=value` flags. */
+export function parseLabels(flags) {
+    const out = Object.create(null);
+    for (const f of flags) {
+        const eq = f.indexOf('=');
+        const key = eq === -1 ? f : f.slice(0, eq);
+        if (eq === -1 || !LABEL_KEY.test(key)) {
+            throw new SitefileError('E_USAGE', `--label expects key=value with a key like org.example.team, got '${f}'`);
+        }
+        out[key] = f.slice(eq + 1);
+    }
+    return out;
+}
+/** Best-effort `org.opencontainers.image.{source,revision}` from a git checkout (never runs git; credentials in URLs are dropped). */
+export async function gitInfo(contextDir) {
+    const out = {};
+    let dir = path.resolve(contextDir);
+    let gitDir;
+    for (let i = 0; i < 8; i++) {
+        const g = path.join(dir, '.git');
+        if (await readFile(path.join(g, 'HEAD'), 'utf8').then(() => true, () => false)) {
+            gitDir = g;
+            break;
+        }
+        const up = path.dirname(dir);
+        if (up === dir)
+            break;
+        dir = up;
+    }
+    if (!gitDir)
+        return out;
+    try {
+        const head = (await readFile(path.join(gitDir, 'HEAD'), 'utf8')).trim();
+        let rev = head;
+        const m = /^ref: (refs\/[\w./-]+)$/.exec(head);
+        if (m) {
+            rev = await readFile(path.join(gitDir, m[1]), 'utf8').then((t) => t.trim(), async () => {
+                const packed = await readFile(path.join(gitDir, 'packed-refs'), 'utf8').catch(() => '');
+                return packed.split('\n').find((l) => l.endsWith(` ${m[1]}`))?.split(' ')[0] ?? '';
+            });
+        }
+        if (/^[0-9a-f]{40,64}$/.test(rev))
+            out.revision = rev;
+    }
+    catch {
+        /* unknown */
+    }
+    try {
+        const cfg = await readFile(path.join(gitDir, 'config'), 'utf8');
+        const url = /\[remote "origin"\][^[]*?\burl\s*=\s*(\S+)/.exec(cfg)?.[1];
+        if (url) {
+            const u = /^[a-z+]+:\/\//.test(url) ? new URL(url) : undefined;
+            if (u) {
+                u.username = '';
+                u.password = '';
+                u.search = '';
+                u.hash = '';
+                out.source = u.toString();
+            }
+            else if (/^[\w.-]+@[\w.-]+:[\w./-]+$/.test(url)) {
+                out.source = url; // scp-style: user@host:path (no secret)
+            }
+        }
+    }
+    catch {
+        /* unknown */
+    }
+    return out;
+}
+//# sourceMappingURL=oci.js.map

package/lib/src/outdated.d.ts

@@ -0,0 +1,46 @@
+import { type BuildOptions } from './executor.js';
+/**
+ * `sitefile outdated` (issue #104): report, for every remote input, whether what it points at today
+ * differs from its pin. It never writes anything (no lockfile, no image store); `--update-lock`
+ * stays the way to change pins.
+ *
+ * What is checkable, honestly:
+ *   - an https IMPORT has no notion of "a newer version": the URL is fetched again (a full GET under
+ *     the build's network policy) and the body's sha256 is compared with the pin (INTEGRITY, else the
+ *     Sitefile.lock entry). Sitefile.lock records no ETag or Last-Modified, so there is nothing to make
+ *     a conditional request against, and a changed validator would not prove changed content anyway.
+ *     A version inside a URL (`.../lib@1.2.3/x.js`) is not interpreted.
+ *   - a BASE tag (`nginx:1.27-alpine`, with or without `@sha256:`) is resolved again (one manifest
+ *     GET) and compared with the digest pinned in the Sitefile or recorded in Sitefile.lock: "changed"
+ *     means the tag has moved. A digest-only reference (`nginx@sha256:...`) has no tag to follow.
+ *   - for a tag that looks like a version (`[v]N[.N[.N]][-suffix]`), the registry's tag list is read and
+ *     the highest tag of the same shape (same `v`, number of components and suffix) that is greater is
+ *     reported as `newerTag`. Registries that refuse to list tags just give no `newerTag`.
+ */
+export type OutdatedStatus = 'current' | 'changed' | 'unpinned' | 'digest-only' | 'error';
+export interface OutdatedEntry {
+    readonly kind: 'import' | 'image' | 'base';
+    /** The IMPORT name, the stage of a `FROM image` base (its name, or `#<n>`), or `BASE`. */
+    readonly name: string;
+    /** The URL, or the canonical image reference. */
+    readonly source: string;
+    /** The pinned digest, if any. */
+    readonly pin: string | null;
+    readonly pinnedBy: 'integrity' | 'lockfile' | 'digest' | 'commit' | null;
+    /** What the source resolves to now (body sha256, or the tag's manifest/index digest). */
+    readonly latest: string | null;
+    readonly status: OutdatedStatus;
+    /** Images only (BASE and FROM image): a greater version-like tag of the same shape. */
+    readonly newerTag: string | null;
+    readonly error: {
+        readonly code: string;
+        readonly message: string;
+    } | null;
+}
+export interface OutdatedReport {
+    readonly inputs: readonly OutdatedEntry[];
+    readonly summary: Readonly<Record<OutdatedStatus, number>>;
+}
+/** The greatest tag of `tags` with the same shape as `current` that is greater than it (ties: the first in byte order). */
+export declare function newerVersionTag(current: string, tags: readonly string[]): string | undefined;
+export declare function outdated(options: BuildOptions): Promise<OutdatedReport>;

package/lib/src/outdated.js

@@ -0,0 +1,195 @@
+import path from 'node:path';
+import { makeClient } from './base-image.js';
+import { sha256 } from './digest.js';
+import { isSitefileError } from './errors.js';
+import { loadProgram, readImportedSitefile, rootSitefileSource } from './executor.js';
+import { importedStageRefs, plan } from './planner.js';
+import { parseRef, withDefaultRegistry } from './ref.js';
+import { fetchRemote } from './resources/https.js';
+import { fetchGitCommit, resolveRef, selectGitPath } from './resources/git.js';
+import { redactError, redactSecrets, secretHeaders } from './secrets.js';
+import { Lockfile } from './resources/lockfile.js';
+import { DEFAULT_ARCHIVE_LIMITS, DEFAULT_FETCH_POLICY } from './resources/types.js';
+const VERSION_TAG = /^(v?)(\d+)(?:\.(\d+))?(?:\.(\d+))?(-[0-9A-Za-z][0-9A-Za-z._-]*)?$/;
+function versionTag(tag) {
+    const m = VERSION_TAG.exec(tag);
+    if (!m)
+        return undefined;
+    const parts = [m[2], m[3], m[4]].filter((x) => x !== undefined).map((x) => x.replace(/^0+(?=\d)/, ''));
+    return { prefix: m[1] ?? '', parts, suffix: m[5] ?? '' };
+}
+/** Numeric comparison of two digit strings without leading zeros. */
+function cmpNum(a, b) {
+    return a.length !== b.length ? a.length - b.length : a < b ? -1 : a > b ? 1 : 0;
+}
+function cmpVersion(a, b) {
+    for (let i = 0; i < a.parts.length; i++) {
+        const c = cmpNum(a.parts[i], b.parts[i]);
+        if (c !== 0)
+            return c;
+    }
+    return 0;
+}
+/** The greatest tag of `tags` with the same shape as `current` that is greater than it (ties: the first in byte order). */
+export function newerVersionTag(current, tags) {
+    const cur = versionTag(current);
+    if (!cur)
+        return undefined;
+    let best;
+    for (const t of [...tags].sort()) {
+        const v = versionTag(t);
+        if (!v || v.prefix !== cur.prefix || v.suffix !== cur.suffix || v.parts.length !== cur.parts.length)
+            continue;
+        if (cmpVersion(v, cur) <= 0)
+            continue;
+        if (!best || cmpVersion(v, best.v) > 0)
+            best = { tag: t, v };
+    }
+    return best?.tag;
+}
+function errorOf(e, secrets) {
+    if (isSitefileError(e))
+        return { code: e.code, message: redactSecrets(e.detail, secrets) };
+    throw redactError(e, secrets);
+}
+/** An entry with its keys in the documented order (the JSON output is compared across implementations). */
+function entry(e) {
+    return { kind: e.kind, name: e.name, source: e.source, pin: e.pin, pinnedBy: e.pinnedBy, latest: e.latest, status: e.status, newerTag: e.newerTag, error: e.error };
+}
+function statusOf(pin, latest) {
+    return pin === null ? 'unpinned' : pin === latest ? 'current' : 'changed';
+}
+export async function outdated(options) {
+    const { program, sitefilePath, label } = await loadProgram(options);
+    const p = plan(program, options.buildArgs ?? {});
+    p.warnings.forEach((m) => options.onWarning?.(m));
+    const policy = { ...DEFAULT_FETCH_POLICY, ...options.fetchPolicy };
+    const lockPath = options.lockfile === false ? undefined : (options.lockfile ?? path.join(path.dirname(sitefilePath), 'Sitefile.lock'));
+    const lock = lockPath ? await Lockfile.load(lockPath) : undefined;
+    const inputs = [];
+    const limits = { ...DEFAULT_ARCHIVE_LIMITS, ...options.archiveLimits };
+    /** Sitefiles imported AS sitefile, with the prefix their inputs are named by (`theme+`). */
+    const nested = [];
+    /** The rows of `sp`'s imports (`sp` read from `source`), then of the Sitefiles it imports, named `<prefix><name>`. */
+    const importRows = async (sp, source, prefix) => {
+        for (const spec of sp.imports) {
+            const name = prefix + spec.name;
+            let rowIndex = -1;
+            if (spec.location.kind === 'git') {
+                // A ref is resolved again (ls-refs, nothing is downloaded): changed = the ref moved since it was
+                // locked. A commit in the URL has no ref to follow.
+                const loc = spec.location;
+                const locked = lock?.getGit(loc.url)?.commit;
+                const pin = loc.commit ?? locked ?? null;
+                const pinnedBy = loc.commit !== undefined ? 'commit' : locked !== undefined ? 'lockfile' : null;
+                const row = { kind: 'import', name, source: loc.url, pin, pinnedBy, newerTag: null };
+                rowIndex = inputs.length;
+                if (loc.commit !== undefined) {
+                    inputs.push(entry({ ...row, latest: null, status: 'digest-only', error: null }));
+                }
+                else {
+                    try {
+                        const originHeaders = secretHeaders(spec, options.secrets);
+                        const latest = await resolveRef(loc.repo, loc.ref, { policy, span: spec.span, ...(originHeaders ? { originHeaders } : {}) });
+                        inputs.push(entry({ ...row, latest, status: statusOf(pin, latest), error: null }));
+                    }
+                    catch (e) {
+                        inputs.push(entry({ ...row, latest: null, status: 'error', error: errorOf(e, options.secrets) }));
+                    }
+                }
+            }
+            else if (spec.location.kind === 'remote') {
+                const url = spec.location.url;
+                const locked = lock?.get(url);
+                const pin = spec.integrity ?? locked?.integrity ?? null;
+                const pinnedBy = spec.integrity ? 'integrity' : locked ? 'lockfile' : null;
+                const row = { kind: 'import', name, source: url, pin, pinnedBy, newerTag: null };
+                try {
+                    const originHeaders = secretHeaders(spec, options.secrets);
+                    const { bytes } = await fetchRemote(url, policy, undefined, originHeaders ? { originHeaders } : {});
+                    const latest = sha256(bytes);
+                    inputs.push(entry({ ...row, latest, status: statusOf(pin, latest), error: null }));
+                }
+                catch (e) {
+                    inputs.push(entry({ ...row, latest: null, status: 'error', error: errorOf(e, options.secrets) }));
+                }
+            }
+            if (spec.as !== 'sitefile' || inputs[rowIndex]?.status === 'error')
+                continue;
+            // The inputs of an imported Sitefile, as pinned (a Git one is read at its pinned commit, else the ref's).
+            let sub;
+            try {
+                sub = await readImportedSitefile(spec, source, importedStageRefs(sp.stages), async (s, loc) => {
+                    const originHeaders = secretHeaders(s, options.secrets);
+                    const want = loc.commit ?? lock?.getGit(loc.url)?.commit;
+                    const objs = await fetchGitCommit(loc.repo, loc.ref, want, { policy, span: s.span, ...(originHeaders ? { originHeaders } : {}) }, limits);
+                    return { commit: objs.commit, selection: selectGitPath(objs, loc, limits, s.span) };
+                });
+            }
+            catch (e) {
+                const error = errorOf(e, options.secrets);
+                const prior = inputs[rowIndex];
+                const row = prior
+                    ? { ...prior, latest: null, status: 'error', error }
+                    : { kind: 'import', name, source: spec.uri, pin: null, pinnedBy: null, latest: null, status: 'error', newerTag: null, error };
+                if (prior)
+                    inputs[rowIndex] = entry(row);
+                else
+                    inputs.push(entry(row));
+                continue;
+            }
+            sub.plan.warnings.forEach((m) => options.onWarning?.(m));
+            nested.push({ prefix: `${name}+`, plan: sub.plan });
+            await importRows(sub.plan, sub.source, `${name}+`);
+        }
+    };
+    await importRows(p, await rootSitefileSource(options, label, sitefilePath), '');
+    /** A registry image (BASE or a FROM image base): resolve its tag again and compare with the pin. */
+    const imageRow = async (kind, name, input) => {
+        let source = input;
+        let pin = null;
+        let pinnedBy = null;
+        try {
+            const ref = withDefaultRegistry(parseRef(input));
+            const registry = ref.registry;
+            source = `${registry}/${ref.name}${ref.tag !== undefined ? `:${ref.tag}` : ''}${ref.digest !== undefined ? `@${ref.digest}` : ''}`;
+            const locked = lock?.getImage(`${registry}/${ref.name}:${ref.tag ?? 'latest'}`);
+            pin = ref.digest ?? locked?.digest ?? null;
+            pinnedBy = ref.digest !== undefined ? 'digest' : pin !== null ? 'lockfile' : null;
+            if (ref.tag === undefined && ref.digest !== undefined) {
+                return entry({ kind, name, source, pin, pinnedBy, latest: null, status: 'digest-only', newerTag: null, error: null });
+            }
+            const tag = ref.tag ?? 'latest';
+            const client = makeClient(registry, { ...options.registry, allowPrivateNetwork: options.registry?.allowPrivateNetwork ?? policy.allowPrivateNetwork });
+            const latest = (await client.getManifest(ref.name, tag)).digest;
+            let newerTag = null;
+            if (versionTag(tag)) {
+                try {
+                    newerTag = newerVersionTag(tag, await client.listTags(ref.name)) ?? null;
+                }
+                catch (e) {
+                    errorOf(e); // not listable: no newer tag
+                }
+            }
+            return entry({ kind, name, source, pin, pinnedBy, latest, status: statusOf(pin, latest), newerTag, error: null });
+        }
+        catch (e) {
+            return entry({ kind, name, source, pin, pinnedBy, latest: null, status: 'error', newerTag: null, error: errorOf(e) });
+        }
+    };
+    // FROM image stage bases with a registry (local-store images have no upstream), named by their stage.
+    for (const { prefix, plan: sp } of [{ prefix: '', plan: p }, ...nested]) {
+        for (const [i, st] of sp.stages.entries()) {
+            if (st.base.kind === 'image' && !st.base.local)
+                inputs.push(await imageRow('image', prefix + (st.name ?? `#${i + 1}`), st.base.ref));
+        }
+    }
+    const baseInput = options.baseImage ?? (p.exportFormat === 'oci' ? p.exportBase : undefined);
+    if (baseInput !== undefined)
+        inputs.push(await imageRow('base', 'BASE', baseInput));
+    const summary = { current: 0, changed: 0, unpinned: 0, 'digest-only': 0, error: 0 };
+    for (const i of inputs)
+        summary[i.status]++;
+    return { inputs, summary };
+}
+//# sourceMappingURL=outdated.js.map

package/lib/src/pages.d.ts

@@ -0,0 +1,10 @@
+import { type SourceSpan } from './errors.js';
+type Doc = Record<string, unknown>;
+/** Group documents by a field; `what` prefixes messages (`FOR tag IN posts BY tags`). */
+export declare function groupBy(items: readonly unknown[], key: string, what: string, span: SourceSpan): Doc[];
+/** Cut each group (or the whole list, as one group without a key) into pages of `size` items. */
+export declare function paginate(groups: ReadonlyArray<{
+    readonly key?: string;
+    readonly items: readonly unknown[];
+}>, size: number): Doc[][];
+export {};