@johnhenry/sitefile 0.0.0-stage → 0.0.0

package/lib/src/cli/cache.js

@@ -0,0 +1,109 @@
+import path from 'node:path';
+import { CACHE_MAX_ENV, cacheLimitFromEnv, cacheUsage, enforceCacheLimit, formatLimit, parseSize } from '../cache-limit.js';
+import { TransformCache } from '../plugins/cache.js';
+import { resolveStoreHome } from '../store.js';
+import { humanSize, requireArgs, str, table, usage } from './common.js';
+/** Where TRANSFORM results are cached: beside the image store, in `$SITEFILE_HOME/cache/transform`. */
+export function transformCacheDir(env = process.env) {
+    return path.join(resolveStoreHome(env), 'cache', 'transform');
+}
+const info = {
+    name: 'cache info',
+    summary: 'show the TRANSFORM result cache location and size',
+    usage: 'cache info [--json]',
+    description: 'Print where plugin/tool results are cached, and how many entries and bytes it holds.',
+    flags: ['    --json   machine-readable output'],
+    options: { json: { type: 'boolean' } },
+    async run(v, pos) {
+        requireArgs(pos, 0, 0, 'no arguments');
+        const i = await new TransformCache(transformCacheDir()).info();
+        process.stdout.write(v['json'] ? JSON.stringify(i, null, 2) + '\n' : `Cache:   ${i.dir}\nEntries: ${i.entries}\nBlobs:   ${i.blobs}\nSize:    ${humanSize(i.bytes)}\n`);
+        return 0;
+    },
+};
+const prune = {
+    name: 'cache prune',
+    summary: 'delete cached TRANSFORM results',
+    usage: 'cache prune [--older-than <days> | --max-size <size>]',
+    description: 'Delete every cached TRANSFORM result, or only entries not used for the given number of days, and the blobs no\nentry still uses. With --max-size, instead apply the automatic size limit now with that size: least recently\nused evictable data (TRANSFORM results, compiled wasm modules, untagged images and unused blobs) is deleted\nuntil the rest fits. Tagged images are never touched.',
+    flags: ['    --older-than <days>   keep entries used within this many days', '    --max-size <size>     shrink evictable data to this size (e.g. 500M, 2G)'],
+    options: { 'older-than': { type: 'string' }, 'max-size': { type: 'string' } },
+    async run(v, pos) {
+        requireArgs(pos, 0, 0, 'no arguments');
+        const raw = v['older-than'];
+        const max = str(v['max-size']);
+        if (max !== undefined) {
+            if (raw !== undefined)
+                usage('--older-than and --max-size conflict');
+            const n = parseSize(max);
+            if (n === undefined || n === 0)
+                usage('--max-size expects a size greater than 0, such as 500M or 2G');
+            const r = await enforceCacheLimit(resolveStoreHome(), n);
+            process.stdout.write(`Evicted ${r.items} item${r.items === 1 ? '' : 's'}\nTotal reclaimed space: ${humanSize(r.bytes)}\n`);
+            return 0;
+        }
+        let ms = 0;
+        if (typeof raw === 'string') {
+            const days = Number(raw);
+            if (!Number.isFinite(days) || days <= 0)
+                usage('--older-than expects a positive number of days');
+            ms = days * 86_400_000;
+        }
+        const r = await new TransformCache(transformCacheDir()).prune(ms);
+        process.stdout.write(`Deleted ${r.entries} entr${r.entries === 1 ? 'y' : 'ies'} and ${r.blobs} blob${r.blobs === 1 ? '' : 's'}\nTotal reclaimed space: ${humanSize(r.bytes)}\n`);
+        return 0;
+    },
+};
+const du = {
+    name: 'cache du',
+    summary: 'show the size of every cache under $SITEFILE_HOME',
+    usage: 'cache du [--json]',
+    description: 'Print the size of each cache and store under $SITEFILE_HOME, how much of it may be evicted automatically\n(EVICTABLE), and the size limit ($SITEFILE_CACHE_MAX). Alias: cache ls.',
+    flags: ['    --json   machine-readable output (sizes in bytes; limit 0 = unlimited)'],
+    options: { json: { type: 'boolean' } },
+    async run(v, pos) {
+        requireArgs(pos, 0, 0, 'no arguments');
+        const home = resolveStoreHome();
+        const limit = cacheLimitFromEnv(process.env, (m) => process.stderr.write(`warning: ${m}\n`));
+        const caches = await cacheUsage(home);
+        const bytes = caches.reduce((a, c) => a + c.bytes, 0);
+        const evictable = caches.reduce((a, c) => a + c.evictable, 0);
+        if (v['json']) {
+            process.stdout.write(JSON.stringify({ home, limit, caches, bytes, evictable }, null, 2) + '\n');
+            return 0;
+        }
+        const rows = [
+            ['CACHE', 'ITEMS', 'SIZE', 'EVICTABLE', 'PATH'],
+            ...caches.map((c) => [c.name, String(c.items), humanSize(c.bytes), humanSize(c.evictable), c.path]),
+            ['total', '', humanSize(bytes), humanSize(evictable), home],
+        ];
+        process.stdout.write(table(rows));
+        process.stdout.write(`Limit: ${formatLimit(limit)} (${CACHE_MAX_ENV}; evictable data over it is deleted after each build, least recently used first)\n`);
+        return 0;
+    },
+};
+/**
+ * End of `build`/`inspect`: apply $SITEFILE_CACHE_MAX. Never fails: problems are warnings.
+ */
+export async function evictAfterBuild(env = process.env) {
+    const warn = (m) => void process.stderr.write(`warning: ${m}\n`);
+    try {
+        const limit = cacheLimitFromEnv(env, warn);
+        if (limit === 0)
+            return;
+        const r = await enforceCacheLimit(resolveStoreHome(env), limit);
+        if (r.items > 0) {
+            process.stderr.write(`Evicted ${r.items} cache item${r.items === 1 ? '' : 's'} (${humanSize(r.bytes)}) to stay under ${CACHE_MAX_ENV}=${formatLimit(limit)}\n`);
+        }
+    }
+    catch (e) {
+        warn(`cache size limit not applied: ${e.message}`);
+    }
+}
+export const cacheSubcommands = new Map([
+    ['info', info],
+    ['prune', prune],
+    ['du', du],
+    ['ls', du],
+]);
+//# sourceMappingURL=cache.js.map

package/lib/src/cli/common.d.ts

@@ -0,0 +1,29 @@
+import { type ParseArgsConfig } from 'node:util';
+type Options = NonNullable<ParseArgsConfig['options']>;
+export type ParsedValues = Record<string, string | boolean | Array<string | boolean> | undefined>;
+export interface Command {
+    readonly name: string;
+    /** One line for the command list. */
+    readonly summary: string;
+    readonly usage: string;
+    readonly description: string;
+    /** Help lines for the options, already formatted. */
+    readonly flags: readonly string[];
+    readonly options: Options;
+    /** Positional arguments allowed (default true). */
+    readonly run: (values: ParsedValues, positionals: string[]) => Promise<number>;
+}
+export declare function commandHelp(c: Command): string;
+export declare function usageError(message: string): number;
+/** Parse `args` for `command` and run it, mapping SitefileError to the CLI exit codes (1, or 2 for E_USAGE). */
+export declare function runCommand(command: Command, args: readonly string[]): Promise<number>;
+export declare function usage(message: string): never;
+export declare function requireArgs(positionals: string[], min: number, max: number, what: string): void;
+/** Left-aligned columns separated by two spaces, like `docker images`. */
+export declare function table(rows: readonly (readonly string[])[]): string;
+/** 1.2kB, 34.5MB (decimal units, as Docker prints them). */
+export declare function humanSize(bytes: number): string;
+export declare function relativeTime(iso: string, now?: number): string;
+export declare function str(v: ParsedValues[string]): string | undefined;
+export declare function strs(v: ParsedValues[string]): string[];
+export {};

package/lib/src/cli/common.js

@@ -0,0 +1,100 @@
+import { parseArgs } from 'node:util';
+import { SitefileError } from '../errors.js';
+export function commandHelp(c) {
+    return `Usage: sitefile ${c.usage}\n\n${c.description}\n${c.flags.length ? `\nOptions:\n${c.flags.map((f) => `  ${f}`).join('\n')}\n` : ''}`;
+}
+export function usageError(message) {
+    process.stderr.write(`error: ${message}\nRun 'sitefile --help' for usage.\n`);
+    return 2;
+}
+/** Parse `args` for `command` and run it, mapping SitefileError to the CLI exit codes (1, or 2 for E_USAGE). */
+export async function runCommand(command, args) {
+    let parsed;
+    try {
+        parsed = parseArgs({ args: [...args], allowPositionals: true, options: { ...command.options, help: { type: 'boolean', short: 'h' } } });
+    }
+    catch (e) {
+        return usageError(`${command.name}: ${e.message}`);
+    }
+    if (parsed.values.help) {
+        process.stdout.write(commandHelp(command));
+        return 0;
+    }
+    try {
+        return await command.run(parsed.values, parsed.positionals);
+    }
+    catch (e) {
+        if (e instanceof SitefileError) {
+            if (e.code === 'E_USAGE')
+                return usageError(e.detail);
+            process.stderr.write(`error[${e.code}]: ${e.message}\n`);
+            return 1;
+        }
+        throw e;
+    }
+}
+export function usage(message) {
+    throw new SitefileError('E_USAGE', message);
+}
+export function requireArgs(positionals, min, max, what) {
+    if (positionals.length < min)
+        usage(`expected ${what}`);
+    if (positionals.length > max)
+        usage(`unexpected arguments: ${positionals.slice(max).join(' ')}`);
+}
+/** Left-aligned columns separated by two spaces, like `docker images`. */
+export function table(rows) {
+    if (rows.length === 0)
+        return '';
+    const widths = [];
+    for (const r of rows)
+        r.forEach((c, i) => (widths[i] = Math.max(widths[i] ?? 0, c.length)));
+    return rows.map((r) => r.map((c, i) => (i === r.length - 1 ? c : c.padEnd(widths[i] ?? 0))).join('  ').trimEnd()).join('\n') + '\n';
+}
+/** Drop trailing zeros only after a decimal point ("1.50" -> "1.5", "100" stays). */
+function stripDecimalZeros(s) {
+    return s.includes('.') ? s.replace(/\.?0+$/, '') : s;
+}
+/** 1.2kB, 34.5MB (decimal units, as Docker prints them). */
+export function humanSize(bytes) {
+    if (bytes < 1000)
+        return `${bytes}B`;
+    const units = ['kB', 'MB', 'GB', 'TB'];
+    let v = bytes;
+    let i = -1;
+    do {
+        v /= 1000;
+        i++;
+    } while (v >= 1000 && i < units.length - 1);
+    return `${v >= 100 ? v.toFixed(0) : stripDecimalZeros(v.toPrecision(3))}${units[i]}`;
+}
+export function relativeTime(iso, now = Date.now()) {
+    const s = Math.max(0, Math.round((now - Date.parse(iso)) / 1000));
+    if (Number.isNaN(s))
+        return 'unknown';
+    if (s < 5)
+        return 'Less than a second ago';
+    const units = [
+        [31536000, 'year'],
+        [2592000, 'month'],
+        [604800, 'week'],
+        [86400, 'day'],
+        [3600, 'hour'],
+        [60, 'minute'],
+        [1, 'second'],
+    ];
+    for (const [n, name] of units) {
+        if (s >= n) {
+            const k = Math.floor(s / n);
+            return `${k} ${name}${k === 1 ? '' : 's'} ago`;
+        }
+    }
+    return 'Less than a second ago';
+}
+export function str(v) {
+    return typeof v === 'string' ? v : undefined;
+}
+export function strs(v) {
+    return Array.isArray(v) ? v.filter((x) => typeof x === 'string') : typeof v === 'string' ? [v] : [];
+}
+//# sourceMappingURL=common.js.map

package/lib/src/cli/git-context.d.ts

@@ -0,0 +1,18 @@
+import { type GitLocation } from '../resources/git.js';
+import { type ArchiveLimits, type FetchPolicy } from '../resources/types.js';
+/**
+ * `sitefile build https://host/repo.git#ref:dir` (issue #91): a build context fetched from Git.
+ * A context argument with a URL scheme (`https://`, `http://`, `git+https://`, `git+http://`) is a
+ * Git URL. Its tree is fetched like a Git IMPORT (same network policy; symlinks resolved inside the
+ * tree, submodules refused), written to a temporary directory, built from there, and removed.
+ */
+export declare function isGitContext(context: string): boolean;
+/** The location of a Git context argument (`https://…` is read as `git+https://…`). */
+export declare function gitContextLocation(context: string): GitLocation;
+export interface GitContext {
+    readonly dir: string;
+    readonly commit: string;
+    dispose(): Promise<void>;
+}
+/** Fetch the context's tree and write it to a new temporary directory. */
+export declare function materializeGitContext(context: string, policy: FetchPolicy, limits?: ArchiveLimits): Promise<GitContext>;

package/lib/src/cli/git-context.js

@@ -0,0 +1,48 @@
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { SitefileError } from '../errors.js';
+import { fetchGitCommit, parseGitUri, selectGitPath } from '../resources/git.js';
+import { DEFAULT_ARCHIVE_LIMITS } from '../resources/types.js';
+import { Tree, makeFile } from '../tree.js';
+/**
+ * `sitefile build https://host/repo.git#ref:dir` (issue #91): a build context fetched from Git.
+ * A context argument with a URL scheme (`https://`, `http://`, `git+https://`, `git+http://`) is a
+ * Git URL. Its tree is fetched like a Git IMPORT (same network policy; symlinks resolved inside the
+ * tree, submodules refused), written to a temporary directory, built from there, and removed.
+ */
+export function isGitContext(context) {
+    return /^[A-Za-z][A-Za-z0-9+.-]*:\/\//.test(context);
+}
+/** The location of a Git context argument (`https://…` is read as `git+https://…`). */
+export function gitContextLocation(context) {
+    const uri = /^git\+/i.test(context) ? context : `git+${context}`;
+    const loc = parseGitUri(uri);
+    return { ...loc, url: context };
+}
+/** Fetch the context's tree and write it to a new temporary directory. */
+export async function materializeGitContext(context, policy, limits = DEFAULT_ARCHIVE_LIMITS) {
+    const loc = gitContextLocation(context);
+    const objs = await fetchGitCommit(loc.repo, loc.ref, loc.commit, { policy }, limits);
+    const sel = selectGitPath(objs, loc, limits);
+    if (sel.kind !== 'tree')
+        throw new SitefileError('E_TYPE', `build context '${context}' is a file; a Git context must name a directory`);
+    // Same checks as an IMPORT of the tree (NFC, case collisions), before anything is written.
+    const tree = Tree.fromFiles(sel.files.map(([p, f]) => [p, makeFile(f.bytes, context, f.mode)]));
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'sitefile-context-'));
+    const dispose = () => fs.rm(dir, { recursive: true, force: true });
+    try {
+        for (const [p, n] of tree.entries()) {
+            const dest = path.join(dir, ...p.slice(1).split('/'));
+            await fs.mkdir(path.dirname(dest), { recursive: true });
+            await fs.writeFile(dest, n.bytes, { mode: n.mode });
+            await fs.chmod(dest, n.mode);
+        }
+    }
+    catch (e) {
+        await dispose();
+        throw new SitefileError('E_EXPORT', `cannot write the Git context to a temporary directory: ${e.message}`, undefined, { cause: e });
+    }
+    return { dir, commit: objs.commit, dispose };
+}
+//# sourceMappingURL=git-context.js.map

package/lib/src/cli/images.d.ts

@@ -0,0 +1,6 @@
+import { type ImageSummary } from '../store.js';
+import { type Command } from './common.js';
+export declare const imageCommands: ReadonlyMap<string, Command>;
+/** `sitefile image <sub>` → command; `ls`, `rm`, `tag` and `save` map onto the top-level commands. */
+export declare const imageSubcommands: ReadonlyMap<string, Command>;
+export type { ImageSummary };

package/lib/src/cli/images.js

@@ -0,0 +1,285 @@
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { sourceDateEpoch, writeTar } from '../archive-writers.js';
+import { SitefileError } from '../errors.js';
+import { exportDirectory, exportFile } from '../exporter.js';
+import { encodeTree, formatFromExtension, isArchiveFormat } from '../export-formats.js';
+import { EXPORT_FORMATS, parseExportFormat } from '../language/ast.js';
+import { MEDIA, siteLayerIndex } from '../oci.js';
+import { looksLikeImageId, parseLocalRef, refKey } from '../ref.js';
+import { shortId, Store } from '../store.js';
+import { humanSize, relativeTime, requireArgs, str, table, usage } from './common.js';
+function split(key) {
+    const i = key.lastIndexOf(':');
+    return [key.slice(0, i), key.slice(i + 1)];
+}
+/** A path relative to the cwd when it is inside it, else absolute. */
+function shown(p) {
+    const rel = path.relative(process.cwd(), p);
+    return rel === '' ? '.' : rel.startsWith('..') ? p : rel;
+}
+const images = {
+    name: 'images',
+    summary: 'list images in the local store',
+    usage: 'images [--json] [--digests] [-q]',
+    description: 'List the images in the local store (SITEFILE_HOME or ~/.sitefile), newest first.\nImages without a tag show as <none>. Alias: sitefile image ls.',
+    flags: ['--json         machine-readable output (full IDs, sizes in bytes)', '--digests      add the full image ID (sha256:...) column', '-q, --quiet    only print short image IDs'],
+    options: { json: { type: 'boolean' }, digests: { type: 'boolean' }, quiet: { type: 'boolean', short: 'q' } },
+    async run(v, pos) {
+        requireArgs(pos, 0, 0, 'no arguments');
+        const store = await Store.open();
+        const list = await store.list();
+        const rows = list.flatMap((im) => (im.tags.length ? im.tags : [undefined]).map((t) => ({ im, tag: t })));
+        if (v.json) {
+            const out = rows.map(({ im, tag }) => {
+                const [repository, t] = tag ? split(tag) : [null, null];
+                return { repository, tag: t, id: im.id, created: im.created, files: im.files, size: im.size };
+            });
+            process.stdout.write(JSON.stringify(out, null, 2) + '\n');
+            return 0;
+        }
+        if (v.quiet) {
+            const seen = new Set();
+            for (const { im } of rows)
+                if (!seen.has(im.id))
+                    (seen.add(im.id), process.stdout.write(`${shortId(im.id)}\n`));
+            return 0;
+        }
+        const head = ['REPOSITORY', 'TAG', 'IMAGE ID', ...(v.digests ? ['DIGEST'] : []), 'CREATED', 'FILES', 'SIZE'];
+        const body = rows.map(({ im, tag }) => {
+            const [repo, t] = tag ? split(tag) : ['<none>', '<none>'];
+            return [repo, t, shortId(im.id), ...(v.digests ? [im.id] : []), relativeTime(im.created), String(im.files), humanSize(im.size)];
+        });
+        process.stdout.write(table([head, ...body]));
+        return 0;
+    },
+};
+const inspect = {
+    name: 'image inspect',
+    summary: 'show an image manifest',
+    usage: 'image inspect <ref|id> [--json]',
+    description: 'Show an image: its ID, tags, creation time, build metadata (ARG names only) and files.',
+    flags: ['--json   machine-readable output'],
+    options: { json: { type: 'boolean' } },
+    async run(v, pos) {
+        requireArgs(pos, 1, 1, 'an image reference');
+        const store = await Store.open();
+        const id = await store.resolve(pos[0]);
+        const d = await store.details(id);
+        const tree = await store.loadTree(id); // verifies every digest
+        const files = tree.entries().map(([p, n]) => ({ path: p, mode: n.mode.toString(8), size: n.bytes.byteLength, digest: n.digest }));
+        const layer = d.manifest.layers[0];
+        if (v.json) {
+            const out = {
+                id,
+                tags: d.tags,
+                created: d.created,
+                os: d.config.os,
+                architecture: d.config.architecture,
+                root: d.root,
+                size: d.size,
+                labels: d.config.labels,
+                config: d.manifest.config,
+                layers: d.manifest.layers,
+                diffIds: d.config.diffIds,
+                files,
+            };
+            process.stdout.write(JSON.stringify(out, null, 2) + '\n');
+            return 0;
+        }
+        const labels = Object.entries(d.config.labels).map(([k, val]) => `  ${k}=${val}`);
+        const out = [
+            `ID:          ${id}`,
+            `Tags:        ${d.tags.join(', ') || '<none>'}`,
+            `Stored:      ${d.created} (${relativeTime(d.created)})`,
+            `Platform:    ${d.config.os}/${d.config.architecture}`,
+            `Root:        ${d.root}`,
+            `Layer:       ${layer?.digest ?? '-'} (${humanSize(d.layerSize)} ${d.manifest.layers[siteLayerIndex(d.manifest, d.config)]?.mediaType === MEDIA.layerTar ? 'tar' : 'gzip'})`,
+            `Diff ID:     ${d.config.diffIds[0] ?? '-'}`,
+            `Config:      ${d.manifest.config.digest}`,
+            'Labels:',
+            ...labels,
+            `Files:       ${files.length} (${humanSize(d.size)})`,
+            '',
+            ...files.map((f) => `${f.mode}  ${String(f.size).padStart(8)}  ${f.path}`),
+        ];
+        process.stdout.write(out.join('\n') + '\n');
+        return 0;
+    },
+};
+const tag = {
+    name: 'tag',
+    summary: 'add a name:tag to an image',
+    usage: 'tag <src> <dst>',
+    description: 'Create the local reference <dst> (name[:tag]) for the image <src> (reference or ID).\nAn existing <dst> is moved to the new image.',
+    flags: [],
+    options: {},
+    async run(_v, pos) {
+        requireArgs(pos, 2, 2, '<src> and <dst>');
+        const dst = parseLocalRef(pos[1]);
+        const store = await Store.open();
+        const id = await store.resolve(pos[0]);
+        const key = await store.tag(id, dst);
+        process.stdout.write(`${key} -> ${shortId(id)}\n`);
+        return 0;
+    },
+};
+const rmi = {
+    name: 'rmi',
+    summary: 'remove tags / images',
+    usage: 'rmi [-f] <ref|id>...',
+    description: 'Remove the tag <ref>. The image manifest is deleted when no other tag references it (blobs are\nreclaimed by "sitefile image prune"). Removing by image ID untags every tag and needs -f when there is more than one.',
+    flags: ['-f, --force   remove an image by ID even if it has several tags'],
+    options: { force: { type: 'boolean', short: 'f' } },
+    async run(v, pos) {
+        requireArgs(pos, 1, Infinity, 'an image reference');
+        const store = await Store.open();
+        let failed = false;
+        for (const ref of pos) {
+            try {
+                const r = await store.removeImage(ref, !!v.force);
+                for (const t of r.untagged)
+                    process.stdout.write(`Untagged: ${t}\n`);
+                if (r.deleted)
+                    process.stdout.write(`Deleted: ${r.deleted}\n`);
+            }
+            catch (e) {
+                if (!(e instanceof SitefileError))
+                    throw e;
+                if (e.code === 'E_USAGE')
+                    throw e;
+                process.stderr.write(`error[${e.code}]: ${e.message}\n`);
+                failed = true;
+            }
+        }
+        return failed ? 1 : 0;
+    },
+};
+const prune = {
+    name: 'image prune',
+    summary: 'delete unreferenced manifests and blobs',
+    usage: 'image prune',
+    description: 'Delete untagged image manifests and every blob no remaining image uses, then print the space reclaimed.',
+    flags: [],
+    options: {},
+    async run(_v, pos) {
+        requireArgs(pos, 0, 0, 'no arguments');
+        const store = await Store.open();
+        const r = await store.prune();
+        process.stdout.write(`Deleted ${r.manifests} image${r.manifests === 1 ? '' : 's'} and ${r.blobs} blob${r.blobs === 1 ? '' : 's'}\nTotal reclaimed space: ${humanSize(r.bytes)}\n`);
+        return 0;
+    },
+};
+const save = {
+    name: 'save',
+    summary: 'export an image to a directory or archive',
+    usage: 'save <ref|id> -o <out> [--format fmt] [--base-url url] [--force]',
+    description: 'Write an image\'s files to a directory, or to a zip, tar, tar.gz (tgz) or wbn archive, or the image itself as\nan OCI archive (-o x.oci.tar) or OCI layout directory (--format oci). The format is chosen like "build -o":\nfrom --format, else the extension (.zip .tar .tar.gz .tgz .wbn .oci.tar), else a directory.\nArchives are deterministic (set SOURCE_DATE_EPOCH to stamp them). A non-empty destination needs --force.',
+    flags: [
+        '-o, --out <path>     destination (required)',
+        `    --format <fmt>   ${EXPORT_FORMATS.join(' | ')} (alias tar.gz)`,
+        '    --base-url <url> https URL ending in "/" (wbn only; required for wbn)',
+        '    --force          replace a non-empty destination or an existing file',
+    ],
+    options: { out: { type: 'string', short: 'o' }, format: { type: 'string' }, 'base-url': { type: 'string' }, force: { type: 'boolean' } },
+    async run(v, pos) {
+        requireArgs(pos, 1, 1, 'an image reference');
+        const out = str(v.out);
+        if (!out)
+            usage('save requires -o <out>');
+        let format;
+        if (v.format !== undefined) {
+            format = parseExportFormat(str(v.format) ?? '');
+            if (!format)
+                usage(`--format expects one of ${EXPORT_FORMATS.join(', ')} (or tar.gz)`);
+        }
+        format ??= formatFromExtension(out) ?? 'directory';
+        const store = await Store.open();
+        const id = await store.resolve(pos[0]);
+        // An empty scratch directory as the "context": the destination is then always
+        // outside it, so a non-empty directory or an existing file needs --force.
+        const scratch = await fs.mkdtemp(path.join(os.tmpdir(), 'sitefile-save-'));
+        try {
+            const opts = { contextDir: scratch, ...(v.force ? { force: true } : {}) };
+            if (format === 'oci') {
+                // The stored image as-is (same digests): an OCI archive for *.tar, else a layout directory.
+                const input = pos[0];
+                const refName = looksLikeImageId(input) ? undefined : refKey(parseLocalRef(input));
+                const layout = await store.layoutOf(id, refName);
+                if (out.toLowerCase().endsWith('.tar')) {
+                    const w = await exportFile(writeTar(layout, { epoch: sourceDateEpoch() ?? 0 }), out, opts);
+                    process.stdout.write(`Saved ${shortId(id)} to ${shown(w.outFile)} (oci archive, ${w.bytes} bytes)\n`);
+                }
+                else {
+                    const w = await exportDirectory(layout, out, opts);
+                    process.stdout.write(`Saved ${shortId(id)} to ${shown(w.outDir)} (oci layout)\n`);
+                }
+                return 0;
+            }
+            const tree = await store.loadTree(id);
+            if (!isArchiveFormat(format)) {
+                const w = await exportDirectory(tree, out, opts);
+                process.stdout.write(`Saved ${shortId(id)} (${tree.size} files) to ${shown(w.outDir)}\n`);
+            }
+            else {
+                const data = encodeTree(tree, format, { epoch: sourceDateEpoch(), baseUrl: str(v['base-url']) });
+                const w = await exportFile(data, out, opts);
+                process.stdout.write(`Saved ${shortId(id)} (${tree.size} files) to ${shown(w.outFile)} (${format === 'tgz' ? 'tar.gz' : format}, ${w.bytes} bytes)\n`);
+            }
+        }
+        finally {
+            await fs.rm(scratch, { recursive: true, force: true });
+        }
+        return 0;
+    },
+};
+const diff = {
+    name: 'image diff',
+    summary: 'compare two images',
+    usage: 'image diff <ref|id> <ref|id>',
+    description: 'List paths added (A), removed (D) or changed (C) going from the first image to the second.\nExit status is 0 whether or not they differ.',
+    flags: [],
+    options: {},
+    async run(_v, pos) {
+        requireArgs(pos, 2, 2, 'two image references');
+        const store = await Store.open();
+        const [a, b] = await Promise.all(pos.map(async (p) => store.loadTree(await store.resolve(p))));
+        const am = new Map(a?.entries());
+        const bm = new Map(b?.entries());
+        const lines = [];
+        for (const p of [...new Set([...am.keys(), ...bm.keys()])].sort()) {
+            const x = am.get(p);
+            const y = bm.get(p);
+            if (!x)
+                lines.push(`A ${p}`);
+            else if (!y)
+                lines.push(`D ${p}`);
+            else if (x.digest !== y.digest || x.mode !== y.mode)
+                lines.push(`C ${p}`);
+        }
+        process.stdout.write(lines.length ? lines.join('\n') + '\n' : '');
+        return 0;
+    },
+};
+export const imageCommands = new Map([
+    ['images', images],
+    ['tag', tag],
+    ['rmi', rmi],
+    ['save', save],
+    ['image inspect', inspect],
+    ['image prune', prune],
+    ['image diff', diff],
+]);
+/** `sitefile image <sub>` → command; `ls`, `rm`, `tag` and `save` map onto the top-level commands. */
+export const imageSubcommands = new Map([
+    ['ls', images],
+    ['list', images],
+    ['rm', rmi],
+    ['tag', tag],
+    ['save', save],
+    ['inspect', inspect],
+    ['prune', prune],
+    ['diff', diff],
+]);
+//# sourceMappingURL=images.js.map

package/lib/src/cli/index.d.ts

@@ -0,0 +1,10 @@
+export declare const EXTRA_COMMANDS: readonly string[];
+/**
+ * The language server exists only in the Rust implementation (a tooling
+ * exception, docs/RUST.md): the language is the same in both, the server is
+ * an editor tool. Here `sitefile lsp` is a usage error that points there.
+ */
+export declare const LSP_UNAVAILABLE = "'sitefile lsp' (the language server) is provided by the Rust implementation: build it with 'cd rust && cargo build --release' and run 'rust/target/release/sitefile lsp' (see docs/LSP.md)";
+export declare const EXTRA_HELP = "\nImages (local store: $SITEFILE_HOME or ~/.sitefile):\n  sitefile build [context] -t name[:tag]           also store the result as an image (repeatable -t)\n  sitefile images [--json] [--digests] [-q]        list images (alias: image ls)\n  sitefile image inspect <ref> [--json]            show an image manifest\n  sitefile image prune                             delete unreferenced manifests and blobs\n  sitefile image diff <a> <b>                      added/removed/changed paths\n  sitefile tag <src> <dst>                         add a name:tag\n  sitefile rmi [-f] <ref|id>...                    remove tags / images\n  sitefile save <ref> -o out[.zip|.tar|.tar.gz|.wbn]   export an image\n  sitefile push <registry/name[:tag]>              push a (tagged) image to an OCI registry\n  sitefile pull <[registry/]name[:tag][@digest]>   pull an image (a bare name means Docker Hub)\n\nVariants:\n  sitefile bake [targets...] [-f file] [--print]   build several targets (matrix, groups) from\n                                                   sitefile.bake.yaml; --print shows the plan\n\nOffline builds:\n  sitefile vendor [context] [--vendor-dir dir]     download remote imports and the BASE image into\n                                                   vendor/sitefile; builds then read them from there\n\nPins:\n  sitefile outdated [context] [--json]             compare remote imports and the BASE image with\n                                                   their pins (never changes anything)\n\nBuild cache (TRANSFORM results: $SITEFILE_HOME/cache/transform):\n  sitefile cache info [--json]                     location, entries, size\n  sitefile cache prune [--older-than <days>]       delete cached results\n  sitefile cache prune --max-size <size>           shrink evictable data (LRU) to <size>\n  sitefile cache du [--json]                       size of every cache and the store (alias: cache ls)\n  Evictable data over $SITEFILE_CACHE_MAX (default 1GiB, 0 = no limit) is deleted after each build.\n\nServing sites (detached servers are tracked by name):\n  sitefile serve [--name n] [-p [host:]port] [-d] [--spa] <ref|./dir>\n  sitefile serve --watch [-p [host:]port] [ctx]    build in memory, serve, rebuild + live reload\n  sitefile servers [-a] [--json]                   list servers (alias: server ls)\n  sitefile server stop|rm [-f]|restart|logs [-f] <name|id>\n\nEditor support:\n  sitefile lsp [--stdio]                           language server over stdio (Rust build only; docs/LSP.md)\n\nRun 'sitefile <command> --help' for the options of a command.\n";
+export declare function isExtraCommand(name: string | undefined): boolean;
+export declare function runExtraCommand(argv: readonly string[]): Promise<number>;