@johnhenry/sitefile 0.0.0-stage → 0.0.1

package/lib/src/bake.js

@@ -0,0 +1,372 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { SitefileError } from './errors.js';
+import { defaultOutName } from './export-formats.js';
+import { EXPORT_FORMATS, parseExportFormat } from './language/ast.js';
+import { parseYaml } from './yaml.js';
+/**
+ * `sitefile bake`: build several variants of a site from one bake file
+ * (`sitefile.bake.yaml`, `.yml` or `.json`), like `docker buildx bake`.
+ *
+ * The bake file names targets (each one a `sitefile build`: context, Sitefile,
+ * build args, arg files, `--target` stage, output, format, tags), optional
+ * `matrix` values that expand one target into several, `inherits` and groups.
+ * This module only reads and resolves the file into a {@link BakePlan}; the CLI
+ * (src/cli/bake.ts) runs the builds. No IO besides reading the bake file.
+ */
+/** The default bake file names, looked up in this order in the current directory. */
+export const BAKE_FILES = ['sitefile.bake.yaml', 'sitefile.bake.yml', 'sitefile.bake.json'];
+const NAME_RE = /^[A-Za-z0-9_][A-Za-z0-9._-]*$/;
+const KEY_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const TARGET_KEYS = ['context', 'file', 'args', 'arg-files', 'target', 'output', 'format', 'tags', 'matrix', 'inherits'];
+function fail(label, detail) {
+    throw new SitefileError('E_DATA', `${label}: ${detail}`);
+}
+const isMapping = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const isScalar = (v) => typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean';
+/** Find the bake file: `file` when given, else the first of {@link BAKE_FILES} in the current directory. */
+export async function findBakeFile(file) {
+    if (file !== undefined)
+        return file;
+    for (const name of BAKE_FILES) {
+        const found = await readFile(name).then(() => true, () => false);
+        if (found)
+            return name;
+    }
+    throw new SitefileError('E_NOT_FOUND', `no bake file: ${BAKE_FILES.join(', ')} not found in the current directory (or pass -f)`);
+}
+/** Read and parse a bake file into its definition (no resolution yet). */
+export async function loadBakeFile(file) {
+    const base = path.basename(file).toLowerCase();
+    const json = base.endsWith('.json');
+    if (!json && !base.endsWith('.yaml') && !base.endsWith('.yml')) {
+        throw new SitefileError('E_USAGE', `bake file '${file}': unknown format (use a .yaml, .yml or .json file)`);
+    }
+    let text;
+    try {
+        text = await readFile(file, 'utf8');
+    }
+    catch (e) {
+        throw new SitefileError('E_NOT_FOUND', `cannot read bake file '${file}'`, undefined, { cause: e });
+    }
+    if (!json)
+        return parseYaml(text, file);
+    try {
+        return JSON.parse(text.replace(/^/, ''));
+    }
+    catch (e) {
+        throw new SitefileError('E_DATA', `${file} is not valid JSON: ${e.message}`, undefined, { cause: e });
+    }
+}
+function stringField(label, where, key, v) {
+    if (typeof v !== 'string')
+        fail(label, `${where}: ${key} must be a string`);
+    return v;
+}
+function stringList(label, where, key, v) {
+    if (!Array.isArray(v) || !v.every((x) => typeof x === 'string'))
+        fail(label, `${where}: ${key} must be a list of strings`);
+    return v;
+}
+function parseTarget(label, name, v) {
+    const where = `target '${name}'`;
+    if (v === null)
+        return { inherits: [] };
+    if (!isMapping(v))
+        fail(label, `${where} must be a mapping`);
+    const t = { inherits: [] };
+    for (const [key, value] of Object.entries(v)) {
+        switch (key) {
+            case 'context':
+            case 'file':
+            case 'target':
+            case 'output':
+            case 'format':
+                t[key] = stringField(label, where, key, value);
+                break;
+            case 'arg-files':
+            case 'tags':
+                t[key] = stringList(label, where, key, value);
+                break;
+            case 'inherits':
+                t.inherits = typeof value === 'string' ? [value] : stringList(label, where, key, value);
+                break;
+            case 'args': {
+                if (!isMapping(value))
+                    fail(label, `${where}: args must be a mapping of NAME: value`);
+                const args = {};
+                for (const [k, a] of Object.entries(value)) {
+                    if (!KEY_RE.test(k))
+                        fail(label, `${where}: '${k}' is not a valid ARG name`);
+                    if (!isScalar(a))
+                        fail(label, `${where}: args.${k} must be a string, number or boolean`);
+                    args[k] = String(a);
+                }
+                t.args = args;
+                break;
+            }
+            case 'matrix': {
+                if (!isMapping(value) || Object.keys(value).length === 0)
+                    fail(label, `${where}: matrix must be a mapping of name: [values]`);
+                const m = [];
+                for (const [k, list] of Object.entries(value)) {
+                    if (!KEY_RE.test(k))
+                        fail(label, `${where}: '${k}' is not a valid matrix variable name`);
+                    if (!Array.isArray(list) || list.length === 0 || !list.every(isScalar)) {
+                        fail(label, `${where}: matrix.${k} must be a non-empty list of strings, numbers or booleans`);
+                    }
+                    m.push([k, list.map((x) => String(x))]);
+                }
+                t.matrix = m;
+                break;
+            }
+            default:
+                fail(label, `${where}: unknown key '${key}' (expected ${TARGET_KEYS.join(', ')})`);
+        }
+    }
+    return t;
+}
+/** Check the shape of a parsed bake file. */
+export function parseBakeDefinition(value, label) {
+    if (!isMapping(value))
+        fail(label, 'a bake file must be a mapping with targets (and optional groups)');
+    for (const key of Object.keys(value)) {
+        if (key !== 'targets' && key !== 'groups')
+            fail(label, `unknown key '${key}' (expected targets, groups)`);
+    }
+    const rawTargets = value['targets'];
+    if (!isMapping(rawTargets) || Object.keys(rawTargets).length === 0)
+        fail(label, 'targets must be a non-empty mapping of name: target');
+    const targets = new Map();
+    for (const [name, t] of Object.entries(rawTargets)) {
+        if (!NAME_RE.test(name))
+            fail(label, `'${name}' is not a valid target name (letters, digits, '.', '_', '-')`);
+        targets.set(name, parseTarget(label, name, t));
+    }
+    const groups = new Map();
+    const rawGroups = value['groups'];
+    if (rawGroups !== undefined && rawGroups !== null) {
+        if (!isMapping(rawGroups))
+            fail(label, 'groups must be a mapping of name: [targets]');
+        for (const [name, list] of Object.entries(rawGroups)) {
+            if (!NAME_RE.test(name))
+                fail(label, `'${name}' is not a valid group name (letters, digits, '.', '_', '-')`);
+            if (targets.has(name))
+                fail(label, `'${name}' is both a target and a group`);
+            groups.set(name, stringList(label, `group '${name}'`, 'the group', list));
+        }
+    }
+    return { label, targets, groups };
+}
+function merge(into, from) {
+    for (const key of ['context', 'file', 'target', 'output', 'format', 'arg-files', 'tags']) {
+        if (from[key] !== undefined)
+            into[key] = from[key];
+    }
+    if (from.args)
+        into.args = Object.assign(into.args ?? {}, from.args);
+}
+/** A target's fields with its `inherits` applied (parents in order, then its own fields). */
+function inherited(def, name, stack) {
+    const t = def.targets.get(name);
+    const out = {};
+    for (const parent of t.inherits) {
+        if (!def.targets.has(parent))
+            fail(def.label, `target '${name}' inherits unknown target '${parent}'`);
+        if (parent === name || stack.includes(parent))
+            fail(def.label, `inherits cycle: ${[...stack, name, parent].join(' -> ')}`);
+        merge(out, inherited(def, parent, [...stack, name]));
+    }
+    merge(out, t); // matrix and inherits are not inherited
+    if (out.args)
+        out.args = { ...out.args };
+    return out;
+}
+/** Every combination of the matrix values, the first variable varying slowest. */
+function combinations(matrix) {
+    let out = [[]];
+    for (const [k, values] of matrix)
+        out = out.flatMap((c) => values.map((v) => [...c, [k, v]]));
+    return out;
+}
+function interpolate(def, name, field, s, vars) {
+    return s.replace(/\$\{([^}]*)\}/g, (whole, v) => {
+        const value = vars.get(v);
+        if (value === undefined)
+            fail(def.label, `target '${name}': ${field}: '${whole}' is not a matrix variable (${[...vars.keys()].join(', ')})`);
+        return value;
+    });
+}
+const joinTo = (dir, p) => (path.isAbsolute(p) ? path.normalize(p) : path.join(dir, p));
+/** Expand and resolve every target of the definition, in file order (matrix targets in place). */
+function expand(def, bakeDir) {
+    const out = new Map();
+    const seen = new Map();
+    for (const [base, raw] of def.targets) {
+        const fields = inherited(def, base, []);
+        const combos = raw.matrix ? combinations(raw.matrix) : [[]];
+        const list = [];
+        for (const combo of combos) {
+            const name = [base, ...combo.map(([, v]) => v.replace(/[^A-Za-z0-9._-]/g, '_'))].join('-');
+            const prior = seen.get(name);
+            if (prior !== undefined)
+                fail(def.label, `two targets are named '${name}' (from '${prior}' and '${base}')`);
+            seen.set(name, base);
+            const vars = new Map(combo);
+            const sub = (field, s) => (raw.matrix ? interpolate(def, name, field, s, vars) : s);
+            const format = fields.format !== undefined ? sub('format', fields.format) : null;
+            if (format !== null && !parseExportFormat(format)) {
+                fail(def.label, `target '${name}': format must be one of ${EXPORT_FORMATS.join(', ')} (or tar.gz), got '${format}'`);
+            }
+            const context = joinTo(bakeDir, sub('context', fields.context ?? '.'));
+            const args = {};
+            for (const [k, v] of Object.entries(fields.args ?? {}))
+                args[k] = sub(`args.${k}`, v);
+            const defaultOut = path.join('dist', name + defaultOutName(format !== null ? parseExportFormat(format) : 'directory').slice('dist'.length));
+            list.push({
+                name,
+                context,
+                file: fields.file !== undefined ? joinTo(bakeDir, sub('file', fields.file)) : path.join(context, 'Sitefile'),
+                args,
+                argFiles: (fields['arg-files'] ?? []).map((f) => joinTo(bakeDir, sub('arg-files', f))),
+                target: fields.target !== undefined ? sub('target', fields.target) : null,
+                output: joinTo(bakeDir, fields.output !== undefined ? sub('output', fields.output) : defaultOut),
+                format,
+                tags: (fields.tags ?? []).map((t) => sub('tags', t)),
+                matrix: raw.matrix ? Object.fromEntries(combo) : null,
+            });
+        }
+        out.set(base, list);
+    }
+    return out;
+}
+/**
+ * Resolve a bake definition into the targets to build: `selected` names targets
+ * (a matrix target's name selects all its variants; a variant's own name selects
+ * it) and groups, in order, without duplicates. With none, the `default` group if
+ * there is one, else every target in file order. Unknown names are usage errors;
+ * targets whose outputs overlap, or that share a tag, are E_CONFLICT.
+ */
+export function resolveBake(def, file, selected) {
+    const bakeDir = path.dirname(file);
+    const all = expand(def, bakeDir);
+    const byName = new Map();
+    for (const list of all.values())
+        for (const t of list)
+            byName.set(t.name, t);
+    const picked = [];
+    const add = (t) => {
+        if (!picked.includes(t))
+            picked.push(t);
+    };
+    const visit = (name, stack, fromGroup) => {
+        const group = def.groups.get(name);
+        if (group) {
+            if (stack.includes(name))
+                fail(def.label, `group '${name}' includes itself (${[...stack, name].join(' -> ')})`);
+            for (const member of group)
+                visit(member, [...stack, name], name);
+            return;
+        }
+        const list = all.get(name);
+        if (list)
+            return list.forEach(add);
+        const one = byName.get(name);
+        if (one)
+            return add(one);
+        if (fromGroup !== undefined)
+            fail(def.label, `group '${fromGroup}': no target or group named '${name}'`);
+        const groups = [...def.groups.keys()];
+        throw new SitefileError('E_USAGE', `bake: no target or group named '${name}' (targets: ${[...def.targets.keys()].join(', ')}${groups.length ? `; groups: ${groups.join(', ')}` : ''})`);
+    };
+    if (selected.length)
+        for (const n of selected)
+            visit(n, [], undefined);
+    else if (def.groups.has('default'))
+        visit('default', [], undefined);
+    else
+        for (const list of all.values())
+            list.forEach(add);
+    checkConflicts(picked);
+    return { file, targets: picked };
+}
+function checkConflicts(targets) {
+    const abs = targets.map((t) => path.resolve(t.output));
+    const under = (a, b) => a.startsWith(b.endsWith(path.sep) ? b : b + path.sep);
+    for (let i = 0; i < targets.length; i++) {
+        for (let j = i + 1; j < targets.length; j++) {
+            const [a, b] = [targets[i], targets[j]];
+            if (abs[i] === abs[j])
+                throw new SitefileError('E_CONFLICT', `bake targets '${a.name}' and '${b.name}' both write '${a.output}'`);
+            if (under(abs[j], abs[i]) || under(abs[i], abs[j])) {
+                throw new SitefileError('E_CONFLICT', `bake targets '${a.name}' and '${b.name}' write overlapping outputs '${a.output}' and '${b.output}'`);
+            }
+            const tag = a.tags.find((t) => b.tags.includes(t));
+            if (tag !== undefined)
+                throw new SitefileError('E_CONFLICT', `bake targets '${a.name}' and '${b.name}' both tag '${tag}'`);
+        }
+    }
+}
+/** Read, check and resolve a bake file. */
+export async function bakePlan(file, selected) {
+    return resolveBake(parseBakeDefinition(await loadBakeFile(file), file), file, selected);
+}
+/** `--print --json`. */
+export function bakePlanJson(plan) {
+    return {
+        file: plan.file,
+        targets: plan.targets.map((t) => ({
+            name: t.name,
+            context: t.context,
+            file: t.file,
+            args: t.args,
+            argFiles: t.argFiles,
+            target: t.target,
+            output: t.output,
+            format: t.format,
+            tags: t.tags,
+            matrix: t.matrix,
+        })),
+    };
+}
+/** `--print`: one block per target, then a count. */
+export function bakePlanText(plan) {
+    const line = (label, value) => `  ${label.padEnd(10)}${value}\n`;
+    let s = '';
+    for (const t of plan.targets) {
+        s += `${t.name}\n`;
+        s += line('context', t.context);
+        s += line('file', t.file);
+        if (t.target !== null)
+            s += line('target', t.target);
+        s += line('output', t.output);
+        if (t.format !== null)
+            s += line('format', t.format);
+        for (const [k, v] of Object.entries(t.args))
+            s += line('arg', `${k}=${v}`);
+        for (const f of t.argFiles)
+            s += line('arg-file', f);
+        for (const tag of t.tags)
+            s += line('tag', tag);
+        if (t.matrix)
+            s += line('matrix', Object.entries(t.matrix).map(([k, v]) => `${k}=${v}`).join(' '));
+    }
+    return s + `${plan.targets.length} target${plan.targets.length === 1 ? '' : 's'} from ${plan.file}\n`;
+}
+/** The `sitefile build` arguments of one target (before the CLI's pass-through flags). */
+export function buildArgv(t) {
+    return [
+        'build',
+        t.context,
+        '-f',
+        t.file,
+        '-o',
+        t.output,
+        ...(t.target !== null ? ['--target', t.target] : []),
+        ...(t.format !== null ? ['--format', t.format] : []),
+        ...t.argFiles.flatMap((f) => ['--build-arg-file', f]),
+        ...Object.entries(t.args).flatMap(([k, v]) => ['--build-arg', `${k}=${v}`]),
+        ...t.tags.flatMap((tag) => ['-t', tag]),
+    ];
+}
+//# sourceMappingURL=bake.js.map

package/lib/src/base-image.d.ts

@@ -0,0 +1,76 @@
+import { type SourceSpan } from './errors.js';
+import type { BaseImage, Descriptor } from './oci.js';
+import { type ImageRef } from './ref.js';
+import { type Credentials } from './registry-auth.js';
+import { RegistryClient, type RegistryOptions } from './registry.js';
+import type { Lockfile } from './resources/lockfile.js';
+import type { Vendor } from './resources/vendor.js';
+import type { Store } from './store.js';
+import type { Tree } from './tree.js';
+/** Registries reachable over plain http: `--insecure-registry` flags plus $SITEFILE_INSECURE_REGISTRIES (comma-separated). */
+export declare function insecureRegistriesFromEnv(extra?: readonly string[], env?: NodeJS.ProcessEnv): string[];
+/** Build a client for a (canonical) registry name, with credentials resolved lazily. */
+export declare function makeClient(registry: string, options?: RegistryOptions & {
+    readonly explicitCredentials?: Credentials | undefined;
+}): RegistryClient;
+export interface ResolveBaseOptions {
+    readonly store: Store;
+    /** `os/arch` of the base to use (default linux/amd64). */
+    readonly platform?: string | undefined;
+    readonly lock?: Lockfile | undefined;
+    /** `--frozen-lockfile`: never resolve a tag; it must be in the lockfile (or pinned by digest). */
+    readonly frozen?: boolean | undefined;
+    /** `--update-lock`: re-resolve the tag and re-record it. */
+    readonly update?: boolean | undefined;
+    /** `sitefile vendor`'s directory: a tag it recorded is used when the lockfile has none, and its blobs seed the store. */
+    readonly vendor?: Vendor | undefined;
+    readonly registry?: RegistryOptions | undefined;
+    readonly warn?: ((message: string) => void) | undefined;
+    readonly span?: SourceSpan | undefined;
+    /** How messages name the reference (default `BASE`; `FROM image` for a stage base). */
+    readonly lead?: string | undefined;
+    /** Fail when the image's platform differs from `platform` (default true; FROM image reads only files). */
+    readonly enforcePlatform?: boolean | undefined;
+}
+/** A BASE reference (a bare name means Docker Hub), how it is shown, and its `Sitefile.lock` `images` key. */
+export declare function baseRef(input: string, span?: SourceSpan, lead?: string): {
+    ref: ImageRef;
+    registry: string;
+    display: string;
+    lockKey: string;
+};
+/**
+ * Resolve `EXPORT ... AS oci BASE <image>` to a base image whose blobs are in the local store.
+ *
+ *   - `image@sha256:...` is pinned by the Sitefile itself and used as is;
+ *   - `image:tag` is looked up in Sitefile.lock (`images`) and fetched BY DIGEST, so a tag that has
+ *     moved on the registry does not change the build; without a lock entry the tag is resolved once and
+ *     recorded (an error with --frozen-lockfile; re-resolved with --update-lock);
+ *   - a base already in the store (matching manifest and blobs) is used without any network access.
+ * A bare name (`nginx:alpine`) means Docker Hub (`docker.io/library/nginx`).
+ */
+export declare function resolveBase(input: string, o: ResolveBaseOptions): Promise<BaseImage>;
+/** A `FROM image` stage base, resolved: its files and the image (manifest) digest they came from. */
+export interface FromImage {
+    readonly tree: Tree;
+    /** The platform manifest digest (the image ID). */
+    readonly digest: string;
+    /** `registry/name:tag` (or the local name as written), without a digest. */
+    readonly name: string;
+}
+/**
+ * Resolve `FROM image <ref> [AT <dir>]` to the image's files.
+ *
+ *   - A reference with a registry host is resolved exactly like a BASE (see {@link resolveBase}): pinned by
+ *     `@sha256:` or a Sitefile.lock `images` entry, fetched by digest, honouring --frozen-lockfile,
+ *     --update-lock, the vendor directory and the registry's auth/TLS/network rules. Any platform is accepted
+ *     (an index is narrowed to `platform`): only the files are read.
+ *   - A reference without a registry host (`theme:1`, `theme@sha256:...`, an image ID) names an image in the
+ *     local store (`sitefile build -t`, `pull`, `load`) and never touches the network or the lockfile.
+ *
+ * The files are the image's site layer under its `dev.sitefile.root` label (`/` without one), or under `at`.
+ * Their origins read `image <name>@<digest>:<path in the layer>`.
+ */
+export declare function resolveFromImage(input: string, at: string | undefined, local: boolean, o: ResolveBaseOptions): Promise<FromImage>;
+/** Read the blobs of `layers` from the store (verifying each digest), for writing a self-contained layout. */
+export declare function readLayerBlobs(store: Store, layers: readonly Descriptor[]): Promise<Map<string, Uint8Array>>;

package/lib/src/base-image.js

@@ -0,0 +1,138 @@
+import { SitefileError } from './errors.js';
+import { parseRef, withDefaultRegistry } from './ref.js';
+import { resolveCredentials } from './registry-auth.js';
+import { pullImage, resolveDigest } from './registry-ops.js';
+import { RegistryClient } from './registry.js';
+/** Registries reachable over plain http: `--insecure-registry` flags plus $SITEFILE_INSECURE_REGISTRIES (comma-separated). */
+export function insecureRegistriesFromEnv(extra = [], env = process.env) {
+    const fromEnv = (env.SITEFILE_INSECURE_REGISTRIES ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+    return [...new Set([...extra, ...fromEnv])];
+}
+/** Build a client for a (canonical) registry name, with credentials resolved lazily. */
+export function makeClient(registry, options = {}) {
+    const { explicitCredentials, ...rest } = options;
+    return new RegistryClient(registry, {
+        ...rest,
+        credentials: rest.credentials ?? (() => resolveCredentials(registry, { explicit: explicitCredentials })),
+    });
+}
+/** A BASE reference (a bare name means Docker Hub), how it is shown, and its `Sitefile.lock` `images` key. */
+export function baseRef(input, span, lead = 'BASE') {
+    let ref;
+    try {
+        ref = withDefaultRegistry(parseRef(input));
+    }
+    catch (e) {
+        if (e instanceof SitefileError)
+            throw new SitefileError(e.code, `${lead}: ${e.detail}`, span, { cause: e });
+        throw e;
+    }
+    const registry = ref.registry;
+    const display = `${registry}/${ref.name}${ref.tag !== undefined || ref.digest === undefined ? `:${ref.tag ?? 'latest'}` : ''}`;
+    const lockKey = `${registry}/${ref.name}:${ref.tag ?? 'latest'}`;
+    return { ref, registry, display, lockKey };
+}
+/**
+ * Resolve `EXPORT ... AS oci BASE <image>` to a base image whose blobs are in the local store.
+ *
+ *   - `image@sha256:...` is pinned by the Sitefile itself and used as is;
+ *   - `image:tag` is looked up in Sitefile.lock (`images`) and fetched BY DIGEST, so a tag that has
+ *     moved on the registry does not change the build; without a lock entry the tag is resolved once and
+ *     recorded (an error with --frozen-lockfile; re-resolved with --update-lock);
+ *   - a base already in the store (matching manifest and blobs) is used without any network access.
+ * A bare name (`nginx:alpine`) means Docker Hub (`docker.io/library/nginx`).
+ */
+export async function resolveBase(input, o) {
+    const lead = o.lead ?? 'BASE';
+    const { ref, registry, display, lockKey } = baseRef(input, o.span, lead);
+    const client = makeClient(registry, o.registry ?? {});
+    let rootDigest = ref.digest;
+    let fresh = false;
+    if (rootDigest === undefined) {
+        const locked = o.update ? undefined : o.lock?.getImage(lockKey);
+        const vendored = locked || o.update || o.frozen ? undefined : o.vendor?.image(lockKey);
+        if (locked) {
+            rootDigest = locked.digest;
+            o.lock?.markImageUsed(lockKey);
+        }
+        else if (vendored) {
+            rootDigest = vendored.digest;
+            o.lock?.recordImage(lockKey, { digest: rootDigest });
+        }
+        else if (o.frozen) {
+            throw new SitefileError('E_LOCK_MISSING', `${lead} ${input}: '${lockKey}' is not in the lockfile (--frozen-lockfile); pin it with @sha256:... or run a build without --frozen-lockfile to record it`, o.span);
+        }
+        else {
+            rootDigest = await resolveDigest(o.store, client, ref);
+            fresh = true;
+            if (o.lock)
+                o.lock.recordImage(lockKey, { digest: rootDigest });
+            else
+                o.warn?.(`${lead} ${input} is not pinned and there is no lockfile: the build is not reproducible (use ${display}@sha256:... or a Sitefile.lock)`);
+        }
+    }
+    // Vendored blobs go into the store first, so the pull below finds them and needs no network.
+    if (o.vendor)
+        await o.vendor.seedStore(o.store, rootDigest, o.platform ?? 'linux/amd64');
+    const pulled = await pullImage(o.store, client, ref, {
+        platform: o.platform,
+        enforcePlatform: o.enforcePlatform ?? true,
+        rootDigest,
+        tag: fresh,
+    });
+    return { name: display, manifestDigest: pulled.id, layers: pulled.manifest.layers, config: pulled.config };
+}
+/**
+ * Resolve `FROM image <ref> [AT <dir>]` to the image's files.
+ *
+ *   - A reference with a registry host is resolved exactly like a BASE (see {@link resolveBase}): pinned by
+ *     `@sha256:` or a Sitefile.lock `images` entry, fetched by digest, honouring --frozen-lockfile,
+ *     --update-lock, the vendor directory and the registry's auth/TLS/network rules. Any platform is accepted
+ *     (an index is narrowed to `platform`): only the files are read.
+ *   - A reference without a registry host (`theme:1`, `theme@sha256:...`, an image ID) names an image in the
+ *     local store (`sitefile build -t`, `pull`, `load`) and never touches the network or the lockfile.
+ *
+ * The files are the image's site layer under its `dev.sitefile.root` label (`/` without one), or under `at`.
+ * Their origins read `image <name>@<digest>:<path in the layer>`.
+ */
+export async function resolveFromImage(input, at, local, o) {
+    const lead = o.lead ?? 'FROM image';
+    let id;
+    let name;
+    if (local) {
+        name = input.split('@')[0];
+        try {
+            id = await o.store.resolve(input);
+        }
+        catch (e) {
+            if (e instanceof SitefileError && e.code === 'E_NOT_FOUND') {
+                throw new SitefileError('E_NOT_FOUND', `${lead} ${input}: no such image in the local store; build it with -t ${name}, pull it, or name its registry (registry.example/${name})`, o.span, { cause: e });
+            }
+            throw e;
+        }
+    }
+    else {
+        name = baseRef(input, o.span, lead).display;
+        id = (await resolveBase(input, { ...o, lead, enforcePlatform: false })).manifestDigest;
+    }
+    let tree;
+    try {
+        tree = await o.store.loadTree(id, { origin: `image ${name}@${id}`, ...(at !== undefined ? { root: at } : {}) });
+    }
+    catch (e) {
+        // Name the FROM line in errors about the image's content (not a Sitefile image, corrupt blobs).
+        if (e instanceof SitefileError && e.span === undefined && o.span)
+            throw new SitefileError(e.code, e.detail, o.span, { cause: e });
+        throw e;
+    }
+    return { tree, digest: id, name };
+}
+/** Read the blobs of `layers` from the store (verifying each digest), for writing a self-contained layout. */
+export async function readLayerBlobs(store, layers) {
+    const out = new Map();
+    for (const l of layers)
+        if (!out.has(l.digest))
+            out.set(l.digest, await store.readBlob(l.digest, l.size));
+    return out;
+}
+//# sourceMappingURL=base-image.js.map

package/lib/src/build-args.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Read build-arg values from a file, by extension:
+ *
+ * - `.json`: a flat object, `{"TITLE": "Docs", "PORT": 8080}`
+ * - `.yaml` / `.yml`: a flat mapping, `TITLE: Docs`
+ * - `.env` (or a file named `.env`, `.env.*`, `*.env`): `KEY=value` lines
+ *
+ * Values must be strings, numbers or booleans; they become strings and are
+ * checked against each ARG's declared type later, like `--build-arg`.
+ * `.env` files are parsed, never executed: no `$VAR` or `$(…)` expansion.
+ */
+export declare function loadBuildArgFile(file: string): Promise<Record<string, string>>;
+export declare function buildArgFileKind(file: string): 'json' | 'yaml' | 'env';
+/**
+ * `.env` syntax: one `KEY=value` per line, optional `export ` prefix, `#`
+ * comment lines and blank lines. Unquoted values are trimmed and a ` #` starts
+ * a comment; `'single'` quotes are literal; `"double"` quotes understand
+ * `\n \t \r \" \\` and may span lines. Nothing is expanded or executed.
+ */
+export declare function parseEnvFile(text: string, label: string): Record<string, string>;
+/**
+ * The CLI's build args: `--build-arg-file` files in order (later files win), then
+ * `--build-arg NAME=value` (or `NAME`, read from the environment), which win over files.
+ * Malformed flags are E_USAGE errors.
+ */
+export declare function collectBuildArgs(files: readonly string[], flags: readonly string[], env?: NodeJS.ProcessEnv): Promise<Record<string, string>>;