@johnhenry/sitefile 0.0.0-stage → 0.0.0

package/lib/src/cli/index.js

@@ -0,0 +1,95 @@
+import { runCommand, usageError } from './common.js';
+import { imageCommands, imageSubcommands } from './images.js';
+import { registryCommands } from './registry.js';
+import { serverCommands, serverSubcommands } from './servers.js';
+import { cacheSubcommands } from './cache.js';
+import { vendorCommands } from './vendor.js';
+import { outdatedCommands } from './outdated.js';
+import { bakeCommands } from './bake.js';
+/**
+ * Image-store and site-server commands. They live outside cli.ts' build/validate/inspect
+ * parser: each has its own options and `--help`.
+ */
+const TOP = new Map([...imageCommands, ...serverCommands, ...registryCommands, ...vendorCommands, ...outdatedCommands, ...bakeCommands].filter(([k]) => !k.includes(' ')));
+export const EXTRA_COMMANDS = [...TOP.keys(), 'image', 'server', 'cache', 'lsp'];
+/**
+ * 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 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 const EXTRA_HELP = `
+Images (local store: $SITEFILE_HOME or ~/.sitefile):
+  sitefile build [context] -t name[:tag]           also store the result as an image (repeatable -t)
+  sitefile images [--json] [--digests] [-q]        list images (alias: image ls)
+  sitefile image inspect <ref> [--json]            show an image manifest
+  sitefile image prune                             delete unreferenced manifests and blobs
+  sitefile image diff <a> <b>                      added/removed/changed paths
+  sitefile tag <src> <dst>                         add a name:tag
+  sitefile rmi [-f] <ref|id>...                    remove tags / images
+  sitefile save <ref> -o out[.zip|.tar|.tar.gz|.wbn]   export an image
+  sitefile push <registry/name[:tag]>              push a (tagged) image to an OCI registry
+  sitefile pull <[registry/]name[:tag][@digest]>   pull an image (a bare name means Docker Hub)
+
+Variants:
+  sitefile bake [targets...] [-f file] [--print]   build several targets (matrix, groups) from
+                                                   sitefile.bake.yaml; --print shows the plan
+
+Offline builds:
+  sitefile vendor [context] [--vendor-dir dir]     download remote imports and the BASE image into
+                                                   vendor/sitefile; builds then read them from there
+
+Pins:
+  sitefile outdated [context] [--json]             compare remote imports and the BASE image with
+                                                   their pins (never changes anything)
+
+Build cache (TRANSFORM results: $SITEFILE_HOME/cache/transform):
+  sitefile cache info [--json]                     location, entries, size
+  sitefile cache prune [--older-than <days>]       delete cached results
+  sitefile cache prune --max-size <size>           shrink evictable data (LRU) to <size>
+  sitefile cache du [--json]                       size of every cache and the store (alias: cache ls)
+  Evictable data over $SITEFILE_CACHE_MAX (default 1GiB, 0 = no limit) is deleted after each build.
+
+Serving sites (detached servers are tracked by name):
+  sitefile serve [--name n] [-p [host:]port] [-d] [--spa] <ref|./dir>
+  sitefile serve --watch [-p [host:]port] [ctx]    build in memory, serve, rebuild + live reload
+  sitefile servers [-a] [--json]                   list servers (alias: server ls)
+  sitefile server stop|rm [-f]|restart|logs [-f] <name|id>
+
+Editor support:
+  sitefile lsp [--stdio]                           language server over stdio (Rust build only; docs/LSP.md)
+
+Run 'sitefile <command> --help' for the options of a command.
+`;
+export function isExtraCommand(name) {
+    return name !== undefined && EXTRA_COMMANDS.includes(name);
+}
+const GROUPS = new Map([
+    ['image', { subs: imageSubcommands, usage: 'image <ls|inspect|tag|rm|save|prune|diff>' }],
+    ['server', { subs: serverSubcommands, usage: 'server <ls|stop|rm|logs|restart>' }],
+    ['cache', { subs: cacheSubcommands, usage: 'cache <info|prune|du>' }],
+]);
+export async function runExtraCommand(argv) {
+    const [name, ...rest] = argv;
+    if (name === 'lsp')
+        return usageError(LSP_UNAVAILABLE);
+    const group = name === undefined ? undefined : GROUPS.get(name);
+    if (group) {
+        const [sub, ...args] = rest;
+        const cmd = sub === undefined ? undefined : group.subs.get(sub);
+        if (!cmd) {
+            if (sub === undefined || sub === '--help' || sub === '-h') {
+                const lines = [...new Set(group.subs.values())].map((c) => `  ${c.usage.padEnd(44)} ${c.summary}`);
+                process.stdout.write(`Usage: sitefile ${group.usage} ...\n\n${lines.join('\n')}\n`);
+                return sub === undefined ? 2 : 0;
+            }
+            return usageError(`unknown ${name} command '${sub}'`);
+        }
+        return runCommand(cmd, args);
+    }
+    const cmd = name === undefined ? undefined : TOP.get(name);
+    if (!cmd)
+        return usageError(`unknown command '${name ?? ''}'`);
+    return runCommand(cmd, rest);
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,5 @@
+import { type OutdatedReport } from '../outdated.js';
+import { type Command } from './common.js';
+/** The text report: a table, one line per error, and a summary line. */
+export declare function formatOutdated(r: OutdatedReport): string;
+export declare const outdatedCommands: ReadonlyMap<string, Command>;

package/lib/src/cli/outdated.js

@@ -0,0 +1,94 @@
+import { insecureRegistriesFromEnv } from '../base-image.js';
+import { collectBuildArgs } from '../build-args.js';
+import { outdated } from '../outdated.js';
+import { loadSecrets } from '../secrets.js';
+import { DEFAULT_FETCH_POLICY } from '../resources/types.js';
+import { shortId } from '../store.js';
+import { requireArgs, str, strs, table, usage } from './common.js';
+function positive(raw, flag) {
+    if (raw === undefined)
+        return undefined;
+    const n = Number(raw);
+    if (!Number.isSafeInteger(n) || n <= 0)
+        usage(`${flag} expects a positive integer`);
+    return n;
+}
+/** The order statuses are counted in the summary line. */
+const ORDER = ['changed', 'unpinned', 'error', 'digest-only', 'current'];
+/** The text report: a table, one line per error, and a summary line. */
+export function formatOutdated(r) {
+    if (r.inputs.length === 0)
+        return 'No remote inputs: the Sitefile has no remote IMPORT, no registry FROM image and no BASE image\n';
+    const short = (d) => (d === null ? '-' : shortId(d));
+    const rows = [['KIND', 'NAME', 'SOURCE', 'PINNED', 'BY', 'LATEST', 'STATUS', 'NEWER TAG']];
+    for (const i of r.inputs)
+        rows.push([i.kind, i.name, i.source, short(i.pin), i.pinnedBy ?? '-', short(i.latest), i.status, i.newerTag ?? '-']);
+    let out = table(rows);
+    for (const i of r.inputs)
+        if (i.error)
+            out += `${i.name}: error[${i.error.code}]: ${i.error.message}\n`;
+    const n = r.inputs.length;
+    const counts = ORDER.filter((s) => r.summary[s] > 0).map((s) => `${r.summary[s]} ${s === 'error' && r.summary[s] !== 1 ? 'errors' : s}`);
+    return `${out}${n} remote input${n === 1 ? '' : 's'}: ${counts.join(', ')}\n`;
+}
+const outdatedCommand = {
+    name: 'outdated',
+    summary: 'check whether pinned remote imports and BASE images have changed upstream',
+    usage: 'outdated [context] [options]',
+    description: "Report, for every remote IMPORT and the BASE image, what it is pinned to (INTEGRITY, @sha256: or\nSitefile.lock) and what it resolves to now. Never changes anything: use 'sitefile build --update-lock'\nto accept new content. An https URL is fetched again and its sha256 compared (there is no notion of a\nnewer version of a URL); a BASE tag is resolved again (changed = the tag moved), and for a version-like\ntag (1.2, v1.2.3-alpine) the registry's tag list is searched for a greater tag of the same shape.",
+    flags: [
+        '-f, --file <path>             Sitefile path (default: <context>/Sitefile)',
+        '--json                        machine-readable output',
+        '--build-arg <NAME=value>      set an ARG (repeatable); --build-arg NAME reads $NAME',
+        '--build-arg-file <path>       read ARGs from a .json, .yaml/.yml or .env file (repeatable)',
+        '--secret id=<id>,env=<VAR>    a build secret for IMPORT ... SECRET (or id=<id>,src=<file>; repeatable)',
+        '--no-lockfile                 ignore Sitefile.lock (only INTEGRITY and @sha256: count as pins)',
+        '--allow-http                  permit plain http:// imports',
+        '--allow-private-network       permit loopback/private network addresses',
+        `--max-download-bytes <n>      per-resource size limit (default ${DEFAULT_FETCH_POLICY.maxBytes})`,
+        `--timeout <ms>                per-resource fetch timeout (default ${DEFAULT_FETCH_POLICY.timeoutMs})`,
+        '--base <image>                check this BASE image (overrides EXPORT ... AS oci BASE)',
+        '--insecure-registry <h>       allow plain http to registry host[:port] (repeatable)',
+    ],
+    options: {
+        file: { type: 'string', short: 'f' },
+        json: { type: 'boolean' },
+        'build-arg': { type: 'string', multiple: true },
+        'build-arg-file': { type: 'string', multiple: true },
+        secret: { type: 'string', multiple: true },
+        'no-lockfile': { type: 'boolean' },
+        'allow-http': { type: 'boolean' },
+        'allow-private-network': { type: 'boolean' },
+        'max-download-bytes': { type: 'string' },
+        timeout: { type: 'string' },
+        base: { type: 'string' },
+        'insecure-registry': { type: 'string', multiple: true },
+    },
+    async run(v, pos) {
+        requireArgs(pos, 0, 1, 'a context directory');
+        const maxBytes = positive(str(v['max-download-bytes']), '--max-download-bytes');
+        const timeoutMs = positive(str(v.timeout), '--timeout');
+        const file = str(v.file);
+        const base = str(v.base);
+        const r = await outdated({
+            contextDir: pos[0] ?? '.',
+            ...(file ? { sitefile: file } : {}),
+            buildArgs: await collectBuildArgs(strs(v['build-arg-file']), strs(v['build-arg'])),
+            secrets: await loadSecrets(strs(v.secret)),
+            fetchPolicy: {
+                allowHttp: !!v['allow-http'],
+                allowPrivateNetwork: !!v['allow-private-network'],
+                ...(maxBytes ? { maxBytes } : {}),
+                ...(timeoutMs ? { timeoutMs } : {}),
+            },
+            ...(v['no-lockfile'] ? { lockfile: false } : {}),
+            ...(base !== undefined ? { baseImage: base } : {}),
+            registry: { insecureRegistries: insecureRegistriesFromEnv(strs(v['insecure-registry'])) },
+            onWarning: (m) => process.stderr.write(`warning: ${m}\n`),
+        });
+        process.stdout.write(v.json ? JSON.stringify(r, null, 2) + '\n' : formatOutdated(r));
+        return 0;
+    },
+};
+export const outdatedCommands = new Map([['outdated', outdatedCommand]]);
+//# sourceMappingURL=outdated.js.map

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

@@ -0,0 +1,2 @@
+import { type Command } from './common.js';
+export declare const registryCommands: ReadonlyMap<string, Command>;

package/lib/src/cli/registry.js

@@ -0,0 +1,122 @@
+import { insecureRegistriesFromEnv, makeClient } from '../base-image.js';
+import { SitefileError } from '../errors.js';
+import { parseRef, refKey, withDefaultRegistry, canonicalRef } from '../ref.js';
+import { pullImage, pushImage } from '../registry-ops.js';
+import { shortId, Store } from '../store.js';
+import { requireArgs, str, strs, usage } from './common.js';
+async function readStdin() {
+    const chunks = [];
+    let n = 0;
+    for await (const c of process.stdin) {
+        n += c.length;
+        if (n > 64 * 1024)
+            usage('--password-stdin: input is too long');
+        chunks.push(c);
+    }
+    return Buffer.concat(chunks).toString('utf8').replace(/\r?\n$/, '');
+}
+function positive(raw, flag) {
+    if (raw === undefined)
+        return undefined;
+    const n = Number(raw);
+    if (!Number.isSafeInteger(n) || n <= 0)
+        usage(`${flag} expects a positive integer`);
+    return n;
+}
+const COMMON_FLAGS = [
+    '--insecure-registry <host[:port]>   allow plain http to this registry (repeatable; localhost always may;',
+    '                                    also $SITEFILE_INSECURE_REGISTRIES, comma-separated)',
+    '--username <name>                   registry user (with --password-stdin); otherwise credentials come from',
+    '                                    $SITEFILE_REGISTRY_AUTH or ~/.docker/config.json (auths, credHelpers, credsStore)',
+    '--password-stdin                    read the password from stdin',
+    '--allow-private-network             let redirects/token servers on other hosts resolve to private addresses',
+    '--timeout <ms>                      per-request idle timeout (default 30000)',
+];
+const COMMON_OPTIONS = {
+    'insecure-registry': { type: 'string', multiple: true },
+    username: { type: 'string' },
+    'password-stdin': { type: 'boolean' },
+    'allow-private-network': { type: 'boolean' },
+    timeout: { type: 'string' },
+};
+async function clientOptions(v) {
+    let explicit;
+    const username = str(v.username);
+    if (v['password-stdin']) {
+        if (!username)
+            usage('--password-stdin needs --username');
+        explicit = { username, password: await readStdin() };
+    }
+    else if (username) {
+        usage('--username needs --password-stdin (passwords are not accepted on the command line)');
+    }
+    const timeoutMs = positive(str(v.timeout), '--timeout');
+    const maxBlob = positive(str(v['max-download-bytes']), '--max-download-bytes');
+    return {
+        explicit,
+        options: {
+            insecureRegistries: insecureRegistriesFromEnv(strs(v['insecure-registry'])),
+            allowPrivateNetwork: !!v['allow-private-network'],
+            limits: { ...(timeoutMs ? { timeoutMs } : {}), ...(maxBlob ? { maxBlobBytes: maxBlob } : {}) },
+        },
+    };
+}
+const push = {
+    name: 'push',
+    summary: 'push an image to a registry',
+    usage: 'push <registry/name[:tag]> [options]',
+    description: 'Push the local image of that name to an OCI registry (distribution spec v1.1): blobs the registry lacks\nare uploaded (layers of a BASE image are mounted from its repository when it is on the same registry),\nthen the manifest. Name the image first: sitefile tag blog:1 localhost:5000/blog:1.\nThe registry host is always explicit (there is no Docker Hub default for push: use docker.io/user/name).\nPlain http is allowed for localhost and --insecure-registry hosts only.',
+    flags: COMMON_FLAGS,
+    options: COMMON_OPTIONS,
+    async run(v, pos) {
+        requireArgs(pos, 1, 1, 'an image reference');
+        const input = pos[0];
+        const ref0 = parseRef(input);
+        if (ref0.registry === undefined) {
+            usage(`'${input}' has no registry host; tag the image first, e.g. sitefile tag ${input} localhost:5000/${input}`);
+        }
+        const ref = canonicalRef(ref0);
+        const store = await Store.open();
+        const refs = await store.refs();
+        const id = ref.digest !== undefined && ref.tag === undefined ? ref.digest : refs[refKey({ ...ref, digest: undefined })];
+        if (id === undefined || !(await store.hasImage(id))) {
+            throw new SitefileError('E_NOT_FOUND', `no local image ${refKey({ ...ref, digest: undefined })}; tag one first: sitefile tag <image> ${refKey({ ...ref, digest: undefined })}`);
+        }
+        const { options, explicit } = await clientOptions(v);
+        const client = makeClient(ref.registry, { ...options, explicitCredentials: explicit });
+        process.stdout.write(`The push refers to repository [${ref.registry}/${ref.name}]\n`);
+        const r = await pushImage(store, client, id, ref, { onEvent: (m) => process.stdout.write(`${m}\n`) });
+        process.stdout.write(`${ref.tag ?? 'digest'}: digest: ${r.digest} size: ${r.size}\n`);
+        return 0;
+    },
+};
+const pull = {
+    name: 'pull',
+    summary: 'pull an image from a registry',
+    usage: 'pull <[registry/]name[:tag][@sha256:...]> [options]',
+    description: 'Pull an image into the local store and tag it name:tag as written. A name without a registry host\nmeans Docker Hub (nginx -> docker.io/library/nginx). For a multi-platform image the --platform variant is\nchosen (default linux/amd64). Every blob is sha256-verified while it streams in, and a manifest fetched by\ndigest must hash to it. The result is stored as-is (Docker or OCI manifests); only images built by\nsitefile can be served or saved. Pin with @sha256:... for reproducibility.',
+    flags: ['--platform <os/arch>   variant to choose from an image index (default linux/amd64)', '--max-download-bytes <n>   per-blob size limit (default 2 GiB)', ...COMMON_FLAGS],
+    options: { ...COMMON_OPTIONS, platform: { type: 'string' }, 'max-download-bytes': { type: 'string' } },
+    async run(v, pos) {
+        requireArgs(pos, 1, 1, 'an image reference');
+        const ref = withDefaultRegistry(parseRef(pos[0]));
+        const store = await Store.open();
+        const { options, explicit } = await clientOptions(v);
+        const client = makeClient(ref.registry, { ...options, explicitCredentials: explicit });
+        const platform = str(v.platform);
+        const r = await pullImage(store, client, ref, {
+            platform,
+            enforcePlatform: platform !== undefined,
+            tag: ref.digest === undefined,
+            onEvent: (m) => process.stdout.write(`${m}\n`),
+        });
+        process.stdout.write(`Digest: ${r.rootDigest}\n`);
+        process.stdout.write(`Pulled ${ref.digest === undefined ? refKey(ref) : `${ref.registry}/${ref.name}@${ref.digest}`} (image ${shortId(r.id)})\n`);
+        return 0;
+    },
+};
+export const registryCommands = new Map([
+    ['push', push],
+    ['pull', pull],
+]);
+//# sourceMappingURL=registry.js.map

package/lib/src/cli/serve-worker.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/lib/src/cli/serve-worker.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+// Detached server process spawned by `sitefile serve -d` / `restart`.
+// Usage: node serve-worker.js <server id>. State and logs live in $SITEFILE_HOME/servers.
+import { SitefileError } from '../errors.js';
+import { closeServer, createSiteServer, formatUrl, listen } from '../server.js';
+import { loadServedTree, ServerRegistry } from '../servers.js';
+const stamp = (m) => void process.stdout.write(`${new Date().toISOString()} ${m}\n`);
+async function main() {
+    const id = process.argv[2] ?? '';
+    const reg = await ServerRegistry.open();
+    const state = await reg.read(id);
+    if (!state)
+        throw new SitefileError('E_SERVER', `no state for server '${id}'`);
+    try {
+        const tree = await loadServedTree(reg.store, state.source);
+        const server = createSiteServer(tree, { spa: state.spa, serverId: id, log: stamp });
+        const addr = await listen(server, state.bind.host, state.bind.port);
+        await reg.update(id, { pid: process.pid, host: addr.host, port: addr.port, ready: true, error: undefined });
+        stamp(`serving ${state.image} (${tree.size} files) at ${formatUrl(addr.host, addr.port)}`);
+        const stop = (signal) => () => {
+            stamp(`received ${signal}, shutting down`);
+            void closeServer(server).then(async () => {
+                await reg.update(id, { ready: false }).catch(() => undefined);
+                process.exit(0);
+            });
+            setTimeout(() => process.exit(0), 3000).unref();
+        };
+        process.on('SIGTERM', stop('SIGTERM'));
+        process.on('SIGINT', stop('SIGINT'));
+    }
+    catch (e) {
+        const message = e instanceof SitefileError ? `error[${e.code}]: ${e.message}` : `error: ${e.message}`;
+        process.stderr.write(`${new Date().toISOString()} ${message}\n`);
+        await reg.update(id, { pid: 0, ready: false, error: message }).catch(() => undefined);
+        process.exit(1);
+    }
+}
+main().catch((e) => {
+    process.stderr.write(`${e?.stack ?? String(e)}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=serve-worker.js.map

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

@@ -0,0 +1,15 @@
+import { ServerRegistry, type ServerState } from '../servers.js';
+import { type Command } from './common.js';
+/** `-p` value: `port`, `host:port` or `[v6]:port`. Default bind is 127.0.0.1 with a free port. */
+export declare function parsePublish(spec: string | undefined): {
+    host: string;
+    port: number;
+};
+/** SIGTERM, wait, then SIGKILL. Returns false if the server was not running. */
+export declare function stopServer(reg: ServerRegistry, s: ServerState, graceMs: number): Promise<boolean>;
+/** The last n lines of text, each newline-terminated; a trailing newline is not an extra empty line. */
+export declare function tailLines(text: string, n: number): string;
+/** Top-level: `sitefile serve`, `sitefile servers`. */
+export declare const serverCommands: ReadonlyMap<string, Command>;
+/** `sitefile server <ls|stop|rm|logs|restart>`. */
+export declare const serverSubcommands: ReadonlyMap<string, Command>;