@gtkx/cli 1.0.0-rc.4 → 1.1.0

package/src/deploy/nfpm/config.ts

@@ -0,0 +1,153 @@
+import type { DeployPayload, DeploySettings, StagedFile } from "../types.js";
+import { resolveDepends } from "../depends.js";
+import { groupForCategories, sectionForCategories } from "../settings/categories.js";
+import { nfpmContents } from "./contents.js";
+import { debDescription, rpmDescription } from "./description.js";
+import { type Entries, optional, when } from "./optional.js";
+
+type NfpmPackager = "deb" | "rpm";
+type NfpmConfig = Entries;
+
+const PREFIX = "/usr";
+const DEFAULT_PRIORITY = "optional";
+const DEFAULT_UMASK = 0o022;
+const VERSION_SCHEMA = "none";
+
+const maintainerFor = (settings: DeploySettings): string => {
+    const { name, email } = settings.developer;
+
+    return email === null ? name : `${name} <${email}>`;
+};
+
+const scriptsFor = (settings: DeploySettings): NfpmConfig | undefined => {
+    const scripts = settings.deploy.scripts;
+
+    if (scripts === undefined) {
+        return undefined;
+    }
+
+    return {
+        ...optional("preinstall", scripts.preInstall),
+        ...optional("postinstall", scripts.postInstall),
+        ...optional("preremove", scripts.preRemove),
+        ...optional("postremove", scripts.postRemove),
+    };
+};
+
+const relationsFor = (settings: DeploySettings, packager: NfpmPackager): NfpmConfig => {
+    const relations = settings.deploy.relations ?? {};
+
+    return {
+        ...optional("recommends", relations.recommends?.[packager]),
+        ...optional("suggests", relations.suggests?.[packager]),
+        ...optional("provides", relations.provides?.[packager]),
+        ...optional("conflicts", relations.conflicts?.[packager]),
+        ...optional("replaces", relations.replaces?.[packager]),
+    };
+};
+
+const debSection = (settings: DeploySettings): NfpmConfig => ({
+    section: settings.deploy.deb?.section ?? sectionForCategories(settings.categories),
+    priority: settings.deploy.deb?.priority ?? DEFAULT_PRIORITY,
+});
+
+const debSignature = (settings: DeploySettings): NfpmConfig => {
+    const signing = settings.deploy.signing?.deb;
+
+    if (signing === undefined) {
+        return {};
+    }
+
+    return {
+        signature: {
+            key_file: signing.keyFile,
+            ...optional("key_id", signing.keyId),
+            ...optional("method", signing.method),
+            ...optional("type", signing.type),
+            ...optional("signer", signing.signer),
+        },
+    };
+};
+
+const rpmSignature = (settings: DeploySettings): NfpmConfig => {
+    const signing = settings.deploy.signing?.rpm;
+
+    if (signing === undefined) {
+        return {};
+    }
+
+    return { signature: { key_file: signing.keyFile, ...optional("key_id", signing.keyId) } };
+};
+
+const debSettings = (settings: DeploySettings): NfpmConfig => {
+    const deb = settings.deploy.deb ?? {};
+    const relations = settings.deploy.relations ?? {};
+
+    return {
+        ...optional("compression", deb.compression),
+        ...optional("fields", deb.fields),
+        ...optional("breaks", relations.breaks?.deb),
+        ...optional("predepends", relations.preDepends?.deb),
+        ...debSignature(settings),
+    };
+};
+
+const rpmSettings = (settings: DeploySettings): NfpmConfig => {
+    const rpm = settings.deploy.rpm ?? {};
+
+    return {
+        group: rpm.group ?? groupForCategories(settings.categories),
+        summary: settings.summary,
+        packager: maintainerFor(settings),
+        ...optional("compression", rpm.compression),
+        ...optional("prefixes", rpm.prefixes),
+        ...rpmSignature(settings),
+    };
+};
+
+const packageNameFor = (settings: DeploySettings, packager: NfpmPackager): string =>
+    settings.deploy[packager]?.packageName ?? settings.binaryName;
+
+const stagedFilesFor = (payload: DeployPayload, packager: NfpmPackager): StagedFile[] => [
+    ...payload.stage,
+    ...payload.overlays[packager],
+];
+
+const packagerSettings = (settings: DeploySettings, packager: NfpmPackager): NfpmConfig =>
+    packager === "rpm" ? rpmSettings(settings) : debSettings(settings);
+
+const releaseFor = (settings: DeploySettings, packager: NfpmPackager): string =>
+    packager === "rpm" ? settings.versions.rpmRelease : settings.versions.debRevision;
+
+const descriptionFor = (settings: DeploySettings, packager: NfpmPackager): string =>
+    packager === "rpm" ? rpmDescription(settings) : debDescription(settings);
+
+const renderNfpmConfig = (payload: DeployPayload, packager: NfpmPackager): NfpmConfig => {
+    const settings = payload.settings;
+    const isRpm = packager === "rpm";
+    const depends = resolveDepends(settings.deploy, settings.libraries, payload.node?.glibcFloor ?? null);
+
+    return {
+        name: packageNameFor(settings, packager),
+        arch: settings.arch[packager],
+        platform: "linux",
+        version: settings.versions.packageVersion,
+        version_schema: VERSION_SCHEMA,
+        release: releaseFor(settings, packager),
+        ...optional("epoch", settings.versions.epoch === null ? undefined : String(settings.versions.epoch)),
+        ...when(!isRpm, debSection(settings)),
+        maintainer: maintainerFor(settings),
+        vendor: settings.developer.name,
+        ...optional("homepage", settings.homepage),
+        license: settings.license,
+        description: descriptionFor(settings, packager),
+        umask: DEFAULT_UMASK,
+        depends: depends[packager],
+        ...relationsFor(settings, packager),
+        ...optional("scripts", scriptsFor(settings)),
+        [packager]: packagerSettings(settings, packager),
+        contents: nfpmContents(PREFIX, stagedFilesFor(payload, packager), isRpm),
+    };
+};
+
+export { type NfpmPackager, packageNameFor, renderNfpmConfig };

package/src/deploy/nfpm/contents.ts

@@ -0,0 +1,69 @@
+import { sortStrings } from "@gtkx/utils";
+import { posix } from "node:path";
+import type { StagedFile } from "../types.js";
+
+type NfpmContent = {
+    src?: string;
+    dst: string;
+    type?: string;
+    file_info?: { mode: number };
+};
+
+const FILESYSTEM_OWNED_PREFIXES = new Set([
+    "/usr",
+    "/usr/bin",
+    "/usr/lib",
+    "/usr/share",
+    "/usr/share/applications",
+    "/usr/share/dbus-1",
+    "/usr/share/dbus-1/services",
+    "/usr/share/doc",
+    "/usr/share/glib-2.0",
+    "/usr/share/glib-2.0/schemas",
+    "/usr/share/icons",
+    "/usr/share/licenses",
+    "/usr/share/metainfo",
+    "/usr/share/mime",
+    "/usr/share/mime/packages",
+]);
+
+const ICON_THEME_PREFIX = "/usr/share/icons/";
+
+const contentFor = (prefix: string, file: StagedFile): NfpmContent => ({
+    src: file.abs,
+    dst: posix.join(prefix, file.rel),
+    file_info: { mode: file.mode },
+});
+
+const isFilesystemOwned = (directory: string): boolean =>
+    FILESYSTEM_OWNED_PREFIXES.has(directory) || directory.startsWith(ICON_THEME_PREFIX);
+
+const parentDirectories = (destination: string): string[] => {
+    const parts = destination.split("/").slice(1, -1);
+
+    return parts.map((_, index) => `/${parts.slice(0, index + 1).join("/")}`);
+};
+
+const ownedDirectories = (contents: NfpmContent[]): string[] => {
+    const directories = new Set(contents.flatMap((entry) => parentDirectories(entry.dst)));
+
+    return sortStrings([...directories].filter((directory) => !isFilesystemOwned(directory)));
+};
+
+const directoryContent = (destination: string): NfpmContent => ({
+    dst: destination,
+    type: "dir",
+    file_info: { mode: 0o755 },
+});
+
+const nfpmContents = (prefix: string, files: StagedFile[], shouldOwnDirectories: boolean): NfpmContent[] => {
+    const contents = files.map((file) => contentFor(prefix, file));
+
+    if (!shouldOwnDirectories) {
+        return contents;
+    }
+
+    return [...ownedDirectories(contents).map((directory) => directoryContent(directory)), ...contents];
+};
+
+export { nfpmContents };

package/src/deploy/nfpm/description.ts

@@ -0,0 +1,11 @@
+import type { DeploySettings } from "../types.js";
+
+const DEBIAN_PARAGRAPH_SEPARATOR = ".";
+
+const debDescription = (settings: DeploySettings): string =>
+    [settings.summary, ...settings.description.flatMap((paragraph, index) =>
+        index === 0 ? [paragraph] : [DEBIAN_PARAGRAPH_SEPARATOR, paragraph])].join("\n");
+
+const rpmDescription = (settings: DeploySettings): string => settings.description.join("\n\n");
+
+export { debDescription, rpmDescription };

package/src/deploy/nfpm/optional.ts

@@ -0,0 +1,8 @@
+type Entries = Record<string, unknown>;
+
+const optional = (key: string, value: unknown): Entries =>
+    value === undefined || value === null ? {} : { [key]: value };
+
+const when = (isIncluded: boolean, entries: Entries): Entries => (isIncluded ? entries : {});
+
+export { type Entries, optional, when };

package/src/deploy/nfpm/pack.ts

@@ -0,0 +1,44 @@
+import { existsSync, mkdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import type { DeployArtifact, DeployPayload } from "../types.js";
+import { runCliTool } from "../../internal/run-cli-tool.js";
+import { resolveNfpm } from "../vendored/nfpm.js";
+import { type NfpmPackager, packageNameFor } from "./config.js";
+
+const artifactNameFor = (payload: DeployPayload, packager: NfpmPackager): string => {
+    const { settings } = payload;
+    const name = packageNameFor(settings, packager);
+    const { packageVersion, debRevision, rpmRelease } = settings.versions;
+
+    if (packager === "deb") {
+        return `${name}_${packageVersion}-${debRevision}_${settings.arch.deb}.deb`;
+    }
+
+    return `${name}-${packageVersion}-${rpmRelease}.${settings.arch.rpm}.rpm`;
+};
+
+const packWithNfpm = async (
+    payload: DeployPayload,
+    packager: NfpmPackager,
+    configPath: string,
+): Promise<DeployArtifact> => {
+    const nfpm = await resolveNfpm();
+    const output = payload.settings.paths.output;
+    mkdirSync(output, { recursive: true });
+    const target = join(output, artifactNameFor(payload, packager));
+
+    runCliTool({
+        tool: nfpm,
+        args: ["package", "--config", configPath, "--packager", packager, "--target", target],
+        target: `the ${packager} package`,
+        shouldStream: true,
+    });
+
+    if (!existsSync(target)) {
+        throw new Error(`nfpm reported success but wrote no ${packager} package at ${target}`);
+    }
+
+    return { path: target, size: statSync(target).size };
+};
+
+export { packWithNfpm };

package/src/deploy/node-runtime/download.ts

@@ -0,0 +1,48 @@
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import type { DigestRequest } from "../download.js";
+import { runCliTool } from "../../internal/run-cli-tool.js";
+import { cachedDigest, cacheDir, downloadFile, publishedDigest } from "../download.js";
+
+const DIST_BASE_URL = "https://nodejs.org/dist";
+const STRIP_COMPONENTS = "2";
+const CHECKSUMS_FILE = "SHASUMS256.txt";
+
+const releaseName = (version: string, arch: string): string => `node-v${version}-linux-${arch}`;
+
+const digestRequest = (version: string, assetName: string, dir: string): DigestRequest => ({
+    url: `${DIST_BASE_URL}/v${version}/${CHECKSUMS_FILE}`,
+    dest: join(dir, `${assetName}.sha256`),
+    assetName,
+    subject: `Node.js ${version}`,
+});
+
+const extractNode = (archive: string, dir: string, version: string, arch: string): void => {
+    runCliTool({
+        tool: "tar",
+        args: ["-xJf", archive, "-C", dir, "--strip-components", STRIP_COMPONENTS,
+            `${releaseName(version, arch)}/bin/node`],
+        target: `Node.js ${version}`,
+    });
+};
+
+const downloadNode = async (version: string, arch: string, destDir: string): Promise<string> => {
+    const assetName = `${releaseName(version, arch)}.tar.xz`;
+    const dir = cacheDir(["node", `${version}-linux-${arch}`]);
+    const request = digestRequest(version, assetName, dir);
+
+    const archive = await downloadFile({
+        url: `${DIST_BASE_URL}/v${version}/${assetName}`,
+        dest: join(dir, assetName),
+        label: `Node.js ${version} for linux-${arch}`,
+        sha256: await cachedDigest(request),
+        freshSha256: () => publishedDigest(request),
+    });
+
+    mkdirSync(destDir, { recursive: true });
+    extractNode(archive, destDir, version, arch);
+
+    return join(destDir, "node");
+};
+
+export { downloadNode };

package/src/deploy/node-runtime/elf.ts

@@ -0,0 +1,145 @@
+import { readFileSync } from "node:fs";
+
+type ElfSection = {
+    name: string;
+    offset: number;
+    size: number;
+};
+
+type ElfInfo = {
+    needed: string[];
+    glibcFloor: string | null;
+};
+
+type DynamicEntry = {
+    tag: number;
+    value: number;
+};
+
+const ELF_MAGIC = "ELF";
+const CLASS_64 = 2;
+const LITTLE_ENDIAN = 1;
+const OFFSET_CLASS = 4;
+const OFFSET_DATA = 5;
+const OFFSET_SECTION_HEADERS = 0x28;
+const OFFSET_SECTION_ENTRY_SIZE = 0x3A;
+const OFFSET_SECTION_COUNT = 0x3C;
+const OFFSET_SECTION_NAME_INDEX = 0x3E;
+const SECTION_NAME = 0;
+const SECTION_OFFSET = 24;
+const SECTION_SIZE = 32;
+const DYNAMIC_ENTRY_SIZE = 16;
+const DT_NULL = 0;
+const DT_NEEDED = 1;
+const DYNAMIC_VALUE_OFFSET = 8;
+const GLIBC_VERSION = /GLIBC_(\d+)\.(\d+)/g;
+const VERSION_RADIX = 1000;
+
+const assertElf64 = (buffer: Buffer, path: string): void => {
+    if (buffer.length < OFFSET_SECTION_NAME_INDEX || buffer.subarray(0, 4).toString("latin1") !== ELF_MAGIC) {
+        throw new Error(`Cannot read ${path}: it is not an ELF binary`);
+    }
+
+    if (buffer.readUInt8(OFFSET_CLASS) !== CLASS_64 || buffer.readUInt8(OFFSET_DATA) !== LITTLE_ENDIAN) {
+        throw new Error(`Cannot read ${path}: only little-endian 64-bit ELF binaries are supported`);
+    }
+};
+
+const readCString = (buffer: Buffer, start: number): string => {
+    const end = buffer.indexOf(0, start);
+
+    return buffer.subarray(start, end === -1 ? buffer.length : end).toString("latin1");
+};
+
+const readSection = (buffer: Buffer, base: number, names: Buffer): ElfSection => ({
+    name: readCString(names, buffer.readUInt32LE(base + SECTION_NAME)),
+    offset: Number(buffer.readBigUInt64LE(base + SECTION_OFFSET)),
+    size: Number(buffer.readBigUInt64LE(base + SECTION_SIZE)),
+});
+
+const readSections = (buffer: Buffer): ElfSection[] => {
+    const headers = Number(buffer.readBigUInt64LE(OFFSET_SECTION_HEADERS));
+    const entrySize = buffer.readUInt16LE(OFFSET_SECTION_ENTRY_SIZE);
+    const count = buffer.readUInt16LE(OFFSET_SECTION_COUNT);
+    const nameIndex = buffer.readUInt16LE(OFFSET_SECTION_NAME_INDEX);
+    const nameBase = headers + nameIndex * entrySize;
+    const nameOffset = Number(buffer.readBigUInt64LE(nameBase + SECTION_OFFSET));
+    const nameSize = Number(buffer.readBigUInt64LE(nameBase + SECTION_SIZE));
+    const names = buffer.subarray(nameOffset, nameOffset + nameSize);
+
+    return Array.from({ length: count }, (_, index) => readSection(buffer, headers + index * entrySize, names));
+};
+
+const sectionFor = (sections: ElfSection[], name: string): ElfSection | undefined =>
+    sections.find((section) => section.name === name);
+
+const readDynamicEntries = (buffer: Buffer, dynamic: ElfSection): DynamicEntry[] => {
+    const entries: DynamicEntry[] = [];
+
+    for (let cursor = 0; cursor + DYNAMIC_ENTRY_SIZE <= dynamic.size; cursor += DYNAMIC_ENTRY_SIZE) {
+        const base = dynamic.offset + cursor;
+        const tag = Number(buffer.readBigUInt64LE(base));
+
+        if (tag === DT_NULL) {
+            break;
+        }
+
+        entries.push({ tag, value: Number(buffer.readBigUInt64LE(base + DYNAMIC_VALUE_OFFSET)) });
+    }
+
+    return entries;
+};
+
+const readNeeded = (buffer: Buffer, dynamic: ElfSection | undefined, strings: Buffer): string[] => {
+    if (dynamic === undefined) {
+        return [];
+    }
+
+    return readDynamicEntries(buffer, dynamic)
+        .filter((entry) => entry.tag === DT_NEEDED)
+        .map((entry) => readCString(strings, entry.value));
+};
+
+const getRank = (version: number[]): number => (version[0] ?? 0) * VERSION_RADIX + (version[1] ?? 0);
+
+const highestVersion = (versions: number[][]): number[] | null => {
+    let highest: number[] | null = null;
+
+    for (const version of versions) {
+        if (highest === null || getRank(version) > getRank(highest)) {
+            highest = version;
+        }
+    }
+
+    return highest;
+};
+
+const formatVersion = (version: number[] | null): string | null =>
+    version === null ? null : `${String(version[0] ?? 0)}.${String(version[1] ?? 0)}`;
+
+const readGlibcFloor = (strings: Buffer): string | null => {
+    const found = strings
+        .toString("latin1")
+        .matchAll(GLIBC_VERSION)
+        .map((match) => [Number(match[1]), Number(match[2])])
+        .toArray();
+
+    return formatVersion(highestVersion(found));
+};
+
+const stringTable = (buffer: Buffer, dynstr: ElfSection | undefined): Buffer =>
+    dynstr === undefined ? Buffer.alloc(0) : buffer.subarray(dynstr.offset, dynstr.offset + dynstr.size);
+
+const readElfInfo = (path: string): ElfInfo => {
+    const buffer = readFileSync(path);
+    assertElf64(buffer, path);
+    const sections = readSections(buffer);
+    const strings = stringTable(buffer, sectionFor(sections, ".dynstr"));
+
+    return {
+        needed: readNeeded(buffer, sectionFor(sections, ".dynamic"), strings),
+        glibcFloor: readGlibcFloor(strings),
+    };
+};
+
+export { type ElfInfo, readElfInfo };

package/src/deploy/node-runtime/guard.ts

@@ -0,0 +1,29 @@
+import type { ElfInfo } from "./elf.js";
+
+const PORTABLE_LIBRARIES = new Set([
+    "ld-linux-aarch64.so.1",
+    "ld-linux-x86-64.so.2",
+    "libc.so.6",
+    "libdl.so.2",
+    "libgcc_s.so.1",
+    "libm.so.6",
+    "libpthread.so.0",
+    "librt.so.1",
+    "libstdc++.so.6",
+]);
+
+const assertPortableNode = (info: ElfInfo, source: string): void => {
+    const foreign = info.needed.filter((library) => !PORTABLE_LIBRARIES.has(library));
+
+    if (foreign.length === 0) {
+        return;
+    }
+
+    throw new Error(
+        `Cannot bundle this Node.js binary: \`deploy.node.source: "${source}"\` picked one linked against ` +
+        `${foreign.join(", ")}, which the target machine will not have. ` +
+        'Use `deploy.node.source: "download"` to fetch an official self-contained build instead.',
+    );
+};
+
+export { assertPortableNode };

package/src/deploy/node-runtime/index.ts

@@ -0,0 +1,80 @@
+import { info, tryResolveExecutable } from "@gtkx/utils";
+import { chmodSync, copyFileSync, mkdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import type { DeploySettings, NodeRuntime } from "../types.js";
+import { runCliTool } from "../../internal/run-cli-tool.js";
+import { downloadNode } from "./download.js";
+import { readElfInfo } from "./elf.js";
+import { assertPortableNode } from "./guard.js";
+
+const BYTES_PER_MIB = 1024 * 1024;
+const EXECUTABLE_MODE = 0o755;
+const NODE_FILENAME = "node";
+
+const sourcePathFor = (settings: DeploySettings): string => {
+    const node = settings.deploy.node ?? {};
+    const source = node.source ?? "download";
+
+    if (source === "host") {
+        return process.execPath;
+    }
+
+    if (node.path === undefined) {
+        throw new Error('Cannot resolve the Node.js runtime: `deploy.node.source: "path"` needs `deploy.node.path`');
+    }
+
+    return resolve(settings.paths.root, node.path);
+};
+
+const didStripBinary = (path: string): boolean => {
+    if (tryResolveExecutable("strip") === undefined) {
+        return false;
+    }
+
+    runCliTool({ tool: "strip", args: ["--strip-unneeded", path], target: "the bundled Node.js" });
+
+    return true;
+};
+
+const megabytes = (path: string): string => (statSync(path).size / BYTES_PER_MIB).toFixed(1);
+
+const stageNode = (settings: DeploySettings, sourcePath: string): string => {
+    mkdirSync(settings.paths.runtime, { recursive: true });
+    const staged = join(settings.paths.runtime, NODE_FILENAME);
+    copyFileSync(sourcePath, staged);
+    chmodSync(staged, EXECUTABLE_MODE);
+
+    return staged;
+};
+
+const stageDownloadedNode = async (settings: DeploySettings, version: string): Promise<string> => {
+    const staged = await downloadNode(version, settings.arch.node, settings.paths.runtime);
+    chmodSync(staged, EXECUTABLE_MODE);
+
+    return staged;
+};
+
+const stageFromSource = async (settings: DeploySettings, version: string, source: string): Promise<string> => {
+    if (source === "download") {
+        return stageDownloadedNode(settings, version);
+    }
+
+    const sourcePath = sourcePathFor(settings);
+    assertPortableNode(readElfInfo(sourcePath), source);
+
+    return stageNode(settings, sourcePath);
+};
+
+const resolveNodeRuntime = async (settings: DeploySettings): Promise<NodeRuntime> => {
+    const node = settings.deploy.node ?? {};
+    const source = node.source ?? "download";
+    const version = node.version ?? process.versions.node;
+    const staged = await stageFromSource(settings, version, source);
+    const isStripped = node.shouldStrip === false ? false : didStripBinary(staged);
+    const elf = readElfInfo(staged);
+    info(`Bundled Node.js v${version} (${megabytes(staged)} MiB, glibc >= ${elf.glibcFloor ?? "unknown"})`);
+
+    return { path: staged, version, glibcFloor: elf.glibcFloor, isStripped };
+};
+
+export { resolveNodeRuntime };

package/src/deploy/payload/copy-tree.ts

@@ -0,0 +1,51 @@
+import { chmodSync, copyFileSync, mkdirSync, statSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, relative } from "node:path";
+import type { StagedFile } from "../types.js";
+import { listFilesRecursive } from "../../internal/list-files.js";
+
+const EXECUTABLE_MODE = 0o755;
+const READABLE_MODE = 0o644;
+const EXECUTABLE_SUFFIXES = [".node", ".so"];
+const MODE_MASK = 0o7777;
+
+const modeFor = (rel: string): number => {
+    const name = rel.split("/").at(-1) ?? rel;
+
+    return EXECUTABLE_SUFFIXES.some((suffix) => name.endsWith(suffix)) ? EXECUTABLE_MODE : READABLE_MODE;
+};
+
+const assertInsideRoot = (root: string, rel: string, abs: string): void => {
+    const escape = relative(root, abs);
+
+    if (escape.length === 0 || escape.startsWith("..") || isAbsolute(escape)) {
+        throw new Error(`Cannot stage "${rel}": it resolves outside the staging directory`);
+    }
+};
+
+const placeFile = (root: string, rel: string, mode: number, write: (target: string) => void): StagedFile => {
+    const abs = join(root, rel);
+    assertInsideRoot(root, rel, abs);
+    mkdirSync(dirname(abs), { recursive: true });
+    write(abs);
+    chmodSync(abs, mode);
+
+    return { rel, abs, mode };
+};
+
+const copyInto = (root: string, rel: string, source: string, mode = modeFor(rel)): StagedFile =>
+    placeFile(root, rel, mode, (target) => {
+        copyFileSync(source, target);
+    });
+
+const writeInto = (root: string, rel: string, contents: string, mode = READABLE_MODE): StagedFile =>
+    placeFile(root, rel, mode, (target) => {
+        writeFileSync(target, contents);
+    });
+
+const sourceMode = (path: string): number => statSync(path).mode & MODE_MASK;
+
+const copyTree = (root: string, relBase: string, sourceDir: string): StagedFile[] =>
+    listFilesRecursive(sourceDir)
+        .map((file) => copyInto(root, join(relBase, file.rel), file.absPath, sourceMode(file.absPath)));
+
+export { copyInto, copyTree, EXECUTABLE_MODE, writeInto };