@johnhenry/sitefile 0.0.0-stage → 0.0.1

package/lib/src/errors.js

@@ -0,0 +1,29 @@
+export function needsPlugin(name) {
+    return { kind: 'plugin', name, flag: '--allow-plugin' };
+}
+export function needsTool(name) {
+    return { kind: 'tool', name, flag: '--allow-exec' };
+}
+export class SitefileError extends Error {
+    code;
+    span;
+    /** The message without the location prefix. */
+    detail;
+    /** For a permission error (`E_UNSUPPORTED` at a PLUGIN or TOOL line): what must be allowed. Not part of the message. */
+    needs;
+    constructor(code, detail, span, options) {
+        super(span ? `${formatSpan(span)}: ${detail}` : detail, options);
+        this.name = 'SitefileError';
+        this.code = code;
+        this.span = span;
+        this.detail = detail;
+        this.needs = options?.needs;
+    }
+}
+export function formatSpan(span) {
+    return `${span.file}:${span.line}:${span.column}`;
+}
+export function isSitefileError(e, code) {
+    return e instanceof SitefileError && (code === undefined || e.code === code);
+}
+//# sourceMappingURL=errors.js.map

package/lib/src/executor.d.ts

@@ -0,0 +1,393 @@
+import { type ExportFormat, type OciCompression, type Program } from './language/ast.js';
+import { type ImageStageBase, type ImportedStageRef, type ImportSpec, type Plan } from './planner.js';
+import { type PluginPolicy } from './plugins/host.js';
+import { type CacheStats, type RemoteCache } from './plugins/cache.js';
+import { type ResolvedTool, type ToolPolicy } from './plugins/exec.js';
+import { type Secrets } from './secrets.js';
+import { type GitLocation, type GitSelection } from './resources/git.js';
+import { LocalContext } from './resources/local.js';
+import { Lockfile } from './resources/lockfile.js';
+import { Vendor } from './resources/vendor.js';
+import { type ArchiveLimits, type FetchPolicy, type Resource } from './resources/types.js';
+import { Tree } from './tree.js';
+import { type AttestRequest, type Referrer } from './attest.js';
+import { type BaseImage, type OciImage } from './oci.js';
+import type { Credentials } from './registry-auth.js';
+import type { RegistryOptions } from './registry.js';
+import { Store } from './store.js';
+import { type Profiler } from './profile.js';
+import { BuildMemo, type MemoStats } from './memo.js';
+import type { TemplateNode } from './render.js';
+export interface BuildOptions {
+    /** Build context directory; local paths resolve from here. */
+    readonly contextDir: string;
+    /** Sitefile path. Default: `<contextDir>/Sitefile`. */
+    readonly sitefile?: string;
+    /** How messages name the Sitefile (default: its path relative to the working directory). */
+    readonly label?: string;
+    /**
+     * Build secrets by id (`--secret id=…,env=…|src=…`, see src/secrets.ts): sent only as the request
+     * headers that `IMPORT … SECRET` clauses name, and redacted from every warning and error.
+     */
+    readonly secrets?: Secrets;
+    readonly buildArgs?: Readonly<Record<string, string>>;
+    /** `--target <stage>`: build up to this named stage and export its whole tree (planner `targetPlan`). */
+    readonly target?: string;
+    /** Export destination; skipped when walking the context if it lies inside it. */
+    readonly outDir?: string;
+    readonly fetchPolicy?: Partial<FetchPolicy>;
+    /** Limits for extracting archives imported AS tree. */
+    readonly archiveLimits?: Partial<ArchiveLimits>;
+    /** Lockfile path, or false to disable. Default: `Sitefile.lock` next to the Sitefile. */
+    readonly lockfile?: string | false;
+    /** Fail instead of adding or changing lockfile entries. */
+    readonly frozenLockfile?: boolean;
+    /** Re-record unpinned URLs whose content changed. */
+    readonly updateLock?: boolean;
+    /**
+     * Context-relative vendor directory written by `sitefile vendor` (default `vendor/sitefile`, used when
+     * its manifest.json exists; a directory given here must exist). Remote IMPORTs and BASE blobs found
+     * there are read from it instead of the network, verified as usual. It is never part of a directory copy.
+     */
+    readonly vendorDir?: string;
+    /**
+     * `--strict-pins`: fail (E_UNPINNED) before fetching anything when a remote IMPORT has neither
+     * INTEGRITY nor a lockfile entry, or the BASE image is neither `@sha256:`-pinned nor locked.
+     */
+    readonly strictPins?: boolean;
+    /** Maximum imports resolved at once (default 4). */
+    readonly concurrency?: number;
+    /** Plugin process limits (per-call timeout, maximum result size). */
+    readonly pluginPolicy?: Partial<PluginPolicy>;
+    /** Permit hard-linked files in the context (you assert they are safe). Default false. */
+    readonly allowHardlinks?: boolean;
+    /**
+     * External programs TOOL may use: `name` (looked up on PATH) or `name=/absolute/path`,
+     * like the CLI's `--allow-exec`. A TOOL not listed here fails the build.
+     */
+    readonly allowExec?: readonly string[];
+    /**
+     * JavaScript PLUGINs allowed to run, by declared name, like the CLI's `--allow-plugin`.
+     * A JS PLUGIN not listed here (and without `allowAllPlugins`) fails the build.
+     * WebAssembly plugins need no permission.
+     */
+    readonly allowPlugin?: readonly string[];
+    /** Allow every JavaScript PLUGIN, like the CLI's `--allow-plugins`. */
+    readonly allowAllPlugins?: boolean;
+    /** External tool limits (per-call timeout, maximum output size). */
+    readonly toolPolicy?: Partial<ToolPolicy>;
+    /** Directory of the TRANSFORM result cache. Omit to disable caching (the CLI sets `$SITEFILE_HOME/cache/transform`). */
+    readonly cacheDir?: string;
+    /** Consulted on a local cache miss and told about every entry used (`--cache-from` / `--cache-to`). Needs `cacheDir`. */
+    readonly remoteCache?: RemoteCache;
+    readonly onWarning?: (message: string) => void;
+    /** oci: `os/arch` of the image (and of the BASE to pull); default linux/amd64. */
+    readonly platform?: string;
+    /** `--base`: build the oci image on this image, overriding the Sitefile's `AS oci BASE`. */
+    readonly baseImage?: string;
+    /** Do not resolve a BASE (the output will not be an oci image). */
+    readonly skipBase?: boolean;
+    /** Registry transport/auth options for pulling the BASE. */
+    readonly registry?: RegistryOptions & {
+        readonly explicitCredentials?: Credentials;
+    };
+    /** The image store used for BASE pulls (default: $SITEFILE_HOME). */
+    readonly store?: Store;
+    /** Informational lines (e.g. the path each allowed tool resolved to). */
+    readonly onNotice?: (message: string) => void;
+    /** `--profile`: record a timing trace of the build here (src/profile.ts). */
+    readonly profiler?: Profiler;
+    /** Other paths this command writes (e.g. the --profile file): skipped when walking the context, like `outDir`. */
+    readonly alsoWrites?: readonly string[];
+    /**
+     * Incremental rebuilds: reuse the results of steps whose inputs did not change since an
+     * earlier build with the same memo (watch mode keeps one per session; src/memo.ts).
+     */
+    readonly memo?: BuildMemo;
+    /** Keep every intermediate tree in {@link BuildResult.steps} (for `sitefile why`). */
+    readonly recordSteps?: boolean;
+}
+export interface BuildResult {
+    readonly plan: Plan;
+    /** The final stage's whole tree. */
+    readonly tree: Tree;
+    /** The exported subtree. */
+    readonly output: Tree;
+    readonly resources: ReadonlyMap<string, Resource>;
+    readonly warnings: readonly string[];
+    readonly lockfileWritten: boolean;
+    /** The resolved BASE image (EXPORT ... AS oci BASE <image> or --base), whose blobs are in the store. */
+    readonly base?: BaseImage;
+    /** The `FROM image` stage bases this build read, in stage order (name and image digest). */
+    readonly images?: readonly FromImageUse[];
+    /** Allow-listed tools this build resolved. */
+    readonly tools: readonly ResolvedTool[];
+    /** What the TRANSFORMs did: processes started, calls made, cache activity. */
+    readonly transformStats: TransformStats;
+    /** With `memo`: how many steps were reused and how many ran. */
+    readonly memoStats?: MemoStats;
+    /**
+     * With `recordSteps`: per stage of `plan.stages`, the tree it starts from, then the tree after each of its
+     * operations (`steps[s][i + 1]` follows `operations[i]`). `tree` is the last one plus the EXPORT site files.
+     */
+    readonly steps?: readonly (readonly Tree[])[];
+    /** `--strict-pins`: how each remote input was pinned (recorded in the provenance). */
+    readonly pins?: Pins;
+    /** The Sitefiles imported AS sitefile, by import name (each with its own imports, plan and, with `recordSteps`, steps). */
+    readonly imported?: ReadonlyMap<string, ImportedSitefile>;
+    /** What each FINGERPRINT renamed (old path, new path), by its line. */
+    readonly renames?: ReadonlyMap<number, ReadonlyArray<readonly [string, string]>>;
+}
+/** A `FROM image` base a build used. */
+export interface FromImageUse {
+    /** `registry/name:tag`, or the local name as written. */
+    readonly name: string;
+    readonly digest: string;
+    /** The FROM line. */
+    readonly line: number;
+    readonly local: boolean;
+    /** Set for a stage of an imported Sitefile: the import's qualified name (`theme`). */
+    readonly import?: string;
+}
+export interface TransformStats extends CacheStats {
+    /** Plugin processes started (0 when every result came from the cache). */
+    pluginsSpawned: number;
+    /** transform() calls made to plugin processes. */
+    pluginCalls: number;
+    /** External tool invocations. */
+    toolRuns: number;
+}
+interface Loaded {
+    readonly program: Program;
+    readonly sitefilePath: string;
+    readonly label: string;
+    readonly source: string;
+}
+/** Read, parse and validate a Sitefile. */
+export declare function loadProgram(options: Pick<BuildOptions, 'contextDir' | 'sitefile' | 'label'>): Promise<Loaded>;
+/** Parse, validate and evaluate variables, without reading any sources. */
+export declare function planBuild(options: BuildOptions): Promise<Plan>;
+/** `validate`'s lint warnings (src/lint.ts) for the whole Sitefile (a `--target` does not narrow them). */
+export declare function lintBuild(options: BuildOptions, disabled?: readonly string[]): Promise<string[]>;
+/** `validate --strict-pins`: check the pins of `p` against the lockfile without building or fetching. */
+export declare function checkPlanPins(options: BuildOptions, p: Plan): Promise<void>;
+/** Run a build in memory. */
+export declare function build(options: BuildOptions): Promise<BuildResult>;
+/** How the remote inputs of a `--strict-pins` build are pinned: remote IMPORTs by name, and the BASE. */
+export interface Pins {
+    readonly imports: Readonly<Record<string, 'integrity' | 'lockfile' | 'commit'>>;
+    readonly base?: 'digest' | 'lockfile';
+    /** `FROM image` bases with a registry, by FROM line. */
+    readonly images?: Readonly<Record<number, 'digest' | 'lockfile'>>;
+}
+/** The Sitefile.lock `images` key of a registry `FROM image` reference. */
+export declare function imageLockKey(b: ImageStageBase): string;
+/**
+ * `--strict-pins`: every remote input must be pinned, so the build is reproducible. A remote IMPORT
+ * needs INTEGRITY or a `Sitefile.lock` entry; a BASE image needs `@sha256:` or a lockfile `images`
+ * entry. `lock` is undefined with --no-lockfile (only the Sitefile's own pins count then). Checked in
+ * source order, before anything is fetched; the first unpinned input fails with E_UNPINNED.
+ */
+export declare function checkPins(p: Plan, lock: Lockfile | undefined, baseRef: string | undefined): Pins;
+export interface ExportTarget {
+    /** Overrides the Sitefile's EXPORT format. */
+    readonly format?: ExportFormat;
+    /** Overrides the Sitefile's EXPORT ... BASE (wbn). */
+    readonly baseUrl?: string;
+    /** oci: root directory inside the layer (overrides EXPORT ... AT; default /srv/www). */
+    readonly ociRoot?: string;
+    /** oci: site layer encoding (overrides EXPORT ... COMPRESSION; default gzip). */
+    readonly ociCompression?: OciCompression;
+    /** wbn: `gzip` wraps the bundle in gzip (overrides EXPORT ... COMPRESSION; default none). */
+    readonly wbnCompression?: OciCompression;
+    /** Extra OCI config labels. */
+    readonly imageLabels?: Readonly<Record<string, string>>;
+    /** Add org.opencontainers.image.source/revision from the git checkout (opt-in). */
+    readonly gitLabels?: boolean;
+    /** oci: `name:tag` recorded as org.opencontainers.image.ref.name in index.json. */
+    readonly ociRefName?: string;
+    /** oci: attach a provenance and/or SBOM attestation (`--provenance`, `--sbom`). */
+    readonly attest?: AttestRequest;
+}
+export interface ExportedBuild extends BuildResult {
+    readonly format: ExportFormat;
+    /** Real path written: a directory for `directory`, otherwise the archive file. */
+    readonly outDir: string;
+    /** Archive size in bytes (archive formats only). */
+    readonly bytes?: number;
+    /** `sha256:<hex>` of the archive file (archive formats only). */
+    readonly fileDigest?: string;
+    /** oci: the image's manifest digest (its image ID). */
+    readonly manifestDigest?: string;
+    /** Watch mode: set when the directory export applied only the changes (src/exporter.ts). */
+    readonly incremental?: {
+        readonly written: number;
+        readonly removed: number;
+    };
+}
+/**
+ * Build, then write the exported tree to `outDir`: a directory for the
+ * `directory` format, a single file for zip, tar, tgz and wbn.
+ */
+export declare function buildToDirectory(options: BuildOptions & ExportTarget & {
+    readonly outDir: string;
+    readonly force?: boolean;
+}): Promise<ExportedBuild>;
+/**
+ * The Sitefile's `EXPORT ... COMPRESSION` for an export in `format`: it belongs to the EXPORT's own format,
+ * so a `--format` override to another format does not inherit it (undefined: that format's default).
+ */
+export declare function sitefileCompression(plan: Pick<Plan, 'exportFormat' | 'exportCompression'>, format: ExportFormat): OciCompression | undefined;
+/**
+ * The attestations (`--provenance`, `--sbom`) of an image built from `result`: in-toto statements
+ * whose subject is the image manifest. They never change the image itself.
+ */
+export declare function imageAttestations(result: BuildResult, img: Pick<OciImage, 'manifestDigest' | 'manifestBytes' | 'configBytes' | 'root'>, options: Pick<BuildOptions, 'contextDir' | 'sitefile' | 'label' | 'buildArgs' | 'platform'>, request: AttestRequest): Promise<Referrer[]>;
+/** What fetching a remote IMPORT needs: the network policy and the lockfile rules (and, for builds, the vendor directory). */
+export interface RemoteEnv {
+    readonly policy: FetchPolicy;
+    readonly lock: Lockfile | undefined;
+    readonly label: string;
+    readonly warn: (m: string) => void;
+    readonly frozen: boolean;
+    readonly update: boolean;
+    /** Vendored copies (`sitefile vendor`), preferred over the network. */
+    readonly vendor?: Vendor | undefined;
+    /** Limits for Git trees (file count, total size; default DEFAULT_ARCHIVE_LIMITS). */
+    readonly archiveLimits?: ArchiveLimits;
+    /** Build secrets by id (`--secret`), sent as the headers of IMPORT … SECRET clauses. */
+    readonly secrets?: Secrets | undefined;
+}
+/** `--secret` ids that no IMPORT … SECRET names (likely a typo). */
+export declare function warnUnusedSecrets(p: Plan, secrets: Secrets | undefined, warn: (m: string) => void): void;
+/**
+ * The bytes of a remote IMPORT, checked against its INTEGRITY and the lockfile (and recorded there):
+ * read from the vendor directory when it has the URL, otherwise fetched.
+ */
+export declare function fetchRemoteImport(spec: ImportSpec, url: string, env: RemoteEnv): Promise<{
+    bytes: Uint8Array;
+    finalUrl: string;
+}>;
+/** The canonical bytes `sitefile vendor` stores for a Git selection: a file's bytes, or a tree as a deterministic tar. */
+export declare function gitSelectionBytes(selection: GitSelection): Uint8Array;
+/**
+ * The content of a Git IMPORT, checked against the lockfile (and recorded there). The commit is the
+ * one in the URL, else the locked one (unless --update-lock), else what the ref names now. A vendored
+ * copy of that commit is read instead of the network (a ref with no lockfile entry uses the vendored
+ * commit, as a BASE tag uses the vendored digest).
+ */
+export declare function fetchGitImport(spec: ImportSpec, loc: GitLocation, env: RemoteEnv): Promise<{
+    commit: string;
+    selection: GitSelection;
+}>;
+/** How deep Sitefile imports may nest (an imported Sitefile importing another counts one more level). */
+export declare const MAX_SITEFILE_IMPORT_DEPTH = 8;
+/**
+ * Where a Sitefile lives, for the labels of the Sitefiles it imports: `<prefix><dir>/Sitefile`.
+ * Local Sitefiles have no prefix and `dir` relative to the working directory; a Git checkout has
+ * `git+https://host/repo.git#<commit>:` and the directory inside the repository.
+ */
+export interface LabelScope {
+    readonly prefix: string;
+    readonly dir: string;
+}
+/** The label an imported Sitefile's messages and file origins use. */
+export declare function sitefileLabel(scope: LabelScope): string;
+/** The ARG values an `IMPORT … AS sitefile` passes, checked against the imported Sitefile's ARGs. */
+export declare function importedArgs(spec: ImportSpec, program: Program): Record<string, string>;
+/**
+ * Parse, check and plan an imported Sitefile: no PLUGIN or TOOL, the IMPORT's ARG clauses, and the
+ * stages `refs` (references from the importing Sitefile) must exist.
+ */
+export declare function planImportedSitefile(spec: ImportSpec, source: string, label: string, refs: readonly ImportedStageRef[]): {
+    program: Program;
+    plan: Plan;
+};
+/** A Sitefile imported AS sitefile: loaded, its imports resolved; its stages are built when first needed. */
+export interface ImportedSitefile {
+    /** The import's name as the build's own Sitefile sees it: `theme`, or `theme+inner` for one imported by `theme`. */
+    readonly name: string;
+    readonly label: string;
+    /** Its whole plan (every stage). */
+    readonly plan: Plan;
+    /**
+     * What the import stands for in the provenance and memo keys: the sha256 of its Sitefile (a local
+     * directory) or the digest of the checked-out tree (Git).
+     */
+    readonly digest: string;
+    /** Whether a path of its context is a directory (`why` lists the file a directory COPY placed). */
+    isDirectory(rel: string): boolean;
+    /** Its imports by name (an `AS sitefile` one as its Sitefile, see {@link unitResource}). */
+    readonly resources: ReadonlyMap<string, Resource>;
+    /** The Sitefiles it imports, by import name. */
+    readonly imported: ReadonlyMap<string, ImportedSitefile>;
+    /** With `recordSteps`: like {@link BuildResult.steps}, for the stages built (a prefix of `plan.stages`). */
+    readonly steps?: Tree[][];
+    /** What each of its FINGERPRINTs renamed (old path, new path), by its line. */
+    readonly renames: ReadonlyMap<number, ReadonlyArray<readonly [string, string]>>;
+}
+/**
+ * Where an imported Sitefile is read from by `vendor` and `outdated`, which never build it: a directory of
+ * a local context, or a directory of a Git tree held in memory.
+ */
+export type SitefileSource = {
+    readonly kind: 'local';
+    readonly local: LocalContext;
+    readonly scope: LabelScope;
+    readonly label: string;
+    readonly chain: ReadonlyArray<{
+        readonly id: string;
+        readonly label: string;
+    }>;
+} | {
+    readonly kind: 'tree';
+    readonly tree: Tree;
+    readonly dir: string;
+    readonly scope: LabelScope;
+    readonly label: string;
+    readonly chain: ReadonlyArray<{
+        readonly id: string;
+        readonly label: string;
+    }>;
+};
+/** The source of the build's own Sitefile, for {@link readImportedSitefile}. */
+export declare function rootSitefileSource(options: BuildOptions, label: string, sitefilePath: string): Promise<SitefileSource>;
+/**
+ * Read and plan the Sitefile an `IMPORT … AS sitefile` of `from` names, without building it (for `vendor`
+ * and `outdated`): the same location, cycle, depth and ARG rules as a build. A Git one is fetched with
+ * `fetchGit` (the commit a build would use). Returns its plan and the source its own imports read from.
+ */
+export declare function readImportedSitefile(spec: ImportSpec, from: SitefileSource, refs: readonly ImportedStageRef[], fetchGit: (spec: ImportSpec, loc: GitLocation) => Promise<{
+    commit: string;
+    selection: GitSelection;
+}>): Promise<{
+    plan: Plan;
+    source: SitefileSource;
+}>;
+/** Top-level names a template reads (variables, #each lists, #if conditions). */
+export declare function templateNames(nodes: readonly TemplateNode[], out?: Set<string>): Set<string>;
+/**
+ * The last segment of a TRANSFORM destination when it names each file of a directory source:
+ * `*` (the file's own name) or `*.ext` (its name with the extension replaced). Undefined otherwise.
+ */
+export declare function starName(dest: string): string | undefined;
+/**
+ * Where one file of a directory TRANSFORM goes: `rel` is its path inside the source directory.
+ * `TO /out/*` keeps its relative path, `TO /out/*.ext` replaces its extension, and any other
+ * destination is the directory `<dest>/<relative dir>/` (the plugin names the files).
+ */
+export declare function fileDest(dest: string, rel: string): string;
+type Settled<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: unknown;
+};
+/**
+ * Run `fn(0..n)` at most `limit` at a time, starting them in index order. After a failure no
+ * later index starts, so the lowest failing index is always among the results (and every index
+ * below it has run): callers report that one, whatever order the calls finished in.
+ */
+export declare function runBounded<T>(n: number, limit: number, fn: (i: number) => Promise<T>): Promise<Array<Settled<T> | undefined>>;
+export {};