@gtkx/cli 1.6.0 → 2.0.0-beta.10

package/src/deploy/run-deploy.ts

@@ -1,9 +1,11 @@
-import { loadConfig } from "@gtkx/config";
+import { type Config, loadConfig } from "@gtkx/config";
 import { info, warn } from "@gtkx/utils";
 import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join, relative } from "node:path";
 import type {
+    DeployArchName,
     DeployArtifact,
+    DeployConfig,
     DeployManifest,
     DeployPayload,
     DeploySettings,
@@ -22,19 +24,23 @@ import {
     synchronizeCatalogs,
 } from "../i18n/catalogs.js";
 import { extractSourceCatalogTo } from "../i18n/source-messages.js";
+import { prepareBuildOutDir, resolveBuildOutDir } from "../internal/build-output.js";
 import { discoverSourceFiles } from "../internal/source-imports.js";
 import { renderDesktopEntry } from "./freedesktop/desktop-entry.js";
 import { extractMetadataMessages, localizeMetadata } from "./freedesktop/localize.js";
 import { renderMetainfo } from "./freedesktop/metainfo.js";
 import { renderMimePackage } from "./freedesktop/mime-package.js";
 import { validateDesktopEntry, validateMetainfo } from "./freedesktop/validate.js";
-import { resolveNodeRuntime } from "./node-runtime/index.js";
+import { resolveStagedAddon } from "./native-addon.js";
+import { assertPortableRuntimeSource, resolveNodeRuntime } from "./node-runtime/index.js";
 import { collectNotices } from "./notices/collect.js";
 import { type StagedMetadata, stageOverlays, stagePayload } from "./payload/stage.js";
 import { DEFAULT_TARGETS, parseTargetList, targetsFor } from "./registry.js";
+import { archesFor, hostArchName, isHostArch, parseArchList } from "./settings/arch.js";
 import { readBuildManifest } from "./settings/build-manifest.js";
 import { resolveDeploySettings } from "./settings/index.js";
 import { readPackageManifest } from "./settings/package-manifest.js";
+import { prepareDeployOutDir } from "./settings/paths.js";
 import { missingDeployError } from "./settings/starter.js";
 import { finishArgsFor, hasDisplaySocket, runtimeLabelFor } from "./targets/flatpak-manifest.js";
 import { detectPackageManager } from "./targets/flatpak-sources.js";
@@ -58,20 +64,56 @@ import {
 type DeployOptions = {
     entry: string;
     cwd: string;
+    configFile?: string | undefined;
     targets?: string | undefined;
+    arches?: string | undefined;
     outDir?: string | undefined;
     shouldPrintManifests: boolean;
     shouldSkipBuild: boolean;
 };
 
-type PreflightRequest = {
+type LoadedDeployConfig = {
+    config: Config;
+    configFile: string;
+    root: string;
+    deploy: DeployConfig;
+};
+
+type DeployPlan = {
+    loaded: LoadedDeployConfig;
     targets: DeployTarget[];
-    settings: DeploySettings;
+    arches: [DeployArchName, ...DeployArchName[]];
     project: CatalogProject | null;
+};
+
+type PreflightRequest = {
+    plan: DeployPlan;
+    settings: DeploySettings;
     shouldPrintManifests: boolean;
     shouldSkipBuild: boolean;
 };
 
+type BuildApplicationRequest = {
+    options: DeployOptions;
+    plan: DeployPlan;
+    settings: DeploySettings;
+    buildOutDir: string | null;
+};
+
+type BuildPayloadRequest = {
+    options: DeployOptions;
+    plan: DeployPlan;
+    settings: DeploySettings;
+    metadata: StagedMetadata;
+};
+
+type ArchRunRequest = {
+    options: DeployOptions;
+    plan: DeployPlan;
+    arch: DeployArchName;
+    metadata: StagedMetadata;
+};
+
 const BUILD_MODE = "production";
 const BYTES_PER_MIB = 1024 * 1024;
 const WEBKIT_LIBRARY = "WebKit-6.0";
@@ -212,17 +254,28 @@ const sourceModeTools = (targets: DeployTarget[], settings: DeploySettings): Dep
 const isNodeRequired = (targets: DeployTarget[], settings: DeploySettings): boolean =>
     !(settings.deploy.flatpak?.mode === "source" && targets.every((target) => target.name === FLATPAK_TARGET));
 
-const runtimeToolsFor = (targets: DeployTarget[], settings: DeploySettings): DeployTool[] => {
-    if (!isNodeRequired(targets, settings)) {
+const archiveToolsFor = (settings: DeploySettings): DeployTool[] =>
+    (settings.deploy.node?.source ?? "download") === "download" ? [TAR] : [];
+
+const stripToolsFor = (settings: DeploySettings, arches: DeployArchName[]): DeployTool[] => {
+    if (settings.deploy.node?.shouldStrip === false) {
         return [];
     }
 
-    const node = settings.deploy.node ?? {};
-    const archiveTools = (node.source ?? "download") === "download" ? [TAR] : [];
+    return arches.some((arch) => isHostArch(arch)) ? [STRIP] : [];
+};
+
+const runtimeToolsFor = (targets: DeployTarget[], settings: DeploySettings, arches: DeployArchName[]): DeployTool[] => {
+    if (!isNodeRequired(targets, settings)) {
+        return [];
+    }
 
-    return node.shouldStrip === false ? archiveTools : [...archiveTools, STRIP];
+    return [...archiveToolsFor(settings), ...stripToolsFor(settings, arches)];
 };
 
+const crossBuildToolsFor = (arches: DeployArchName[]): DeployTool[] =>
+    arches.every((arch) => isHostArch(arch)) ? [] : [TAR];
+
 const mutableCatalogTools = (project: CatalogProject): DeployTool[] => {
     if (project.catalogs.length === 0) {
         return [MSGGREP, XGETTEXT];
@@ -249,47 +302,107 @@ const catalogTools = (project: CatalogProject | null, shouldSkipBuild: boolean):
     return project.catalogs.length === 0 ? [] : [MSGFMT];
 };
 
-const preflight = ({
-    targets,
-    settings,
-    project,
-    shouldPrintManifests,
-    shouldSkipBuild,
-}: PreflightRequest): void => {
+const preflight = ({ plan, settings, shouldPrintManifests, shouldSkipBuild }: PreflightRequest): void => {
+    const { targets, arches, project } = plan;
+
     const packagerTools = shouldPrintManifests
         ? []
-        : [...runtimeToolsFor(targets, settings), ...targets.flatMap((target) => target.tools)];
+        : [...runtimeToolsFor(targets, settings, arches), ...targets.flatMap((target) => target.tools)];
 
     const required = [
         DESKTOP_FILE_VALIDATE,
         APPSTREAMCLI,
+        ...crossBuildToolsFor(arches),
         ...catalogTools(project, shouldSkipBuild),
         ...sourceModeTools(targets, settings),
     ];
 
     const report = probeTools([...required, ...packagerTools]);
     assertTools(report);
+
+    if (isNodeRequired(targets, settings)) {
+        assertPortableRuntimeSource(settings);
+    }
+
     warnMissingOptional(report);
     warnFlatpakPermissions(targets, settings);
     warnLibraryMinimums(targets, settings);
 };
 
-const resolveTargetNames = (options: DeployOptions, settings: DeploySettings): string[] => {
+const hostOnlyNames = (targets: DeployTarget[]): string[] =>
+    targets.filter((target) => target.isHostOnly).map((target) => target.name);
+
+const assertCrossBuild = (plan: DeployPlan): void => {
+    const foreign = plan.arches.filter((arch) => !isHostArch(arch));
+
+    if (foreign.length === 0) {
+        return;
+    }
+
+    const hostOnly = hostOnlyNames(plan.targets);
+
+    if (hostOnly.length > 0) {
+        throw new Error(
+            `Cannot build ${hostOnly.join(" and ")} for ${foreign.join(" and ")}: those targets package with ` +
+            `tooling that only runs on ${hostArchName()}. Deploy them in a separate run without --arch.`,
+        );
+    }
+
+    if ((plan.loaded.deploy.node?.source ?? "download") !== "download") {
+        throw new Error(
+            'Cannot deploy for another architecture with a `deploy.node.source` other than "download": ' +
+            `a host or path runtime is always ${hostArchName()}.`,
+        );
+    }
+};
+
+const resolveTargetNames = (options: DeployOptions, deploy: DeployConfig): string[] => {
     if (options.targets !== undefined) {
         return parseTargetList(options.targets);
     }
 
-    return settings.deploy.targets ?? DEFAULT_TARGETS;
+    return deploy.targets ?? DEFAULT_TARGETS;
+};
+
+const resolveArchNames = (options: DeployOptions, deploy: DeployConfig): string[] => {
+    if (options.arches !== undefined) {
+        return parseArchList(options.arches);
+    }
+
+    return deploy.architectures ?? [hostArchName()];
 };
 
-const loadSettings = async (options: DeployOptions): Promise<DeploySettings> => {
-    const { config, root } = await loadConfig(options.cwd, { mode: BUILD_MODE });
+const loadDeployConfig = async (options: DeployOptions): Promise<LoadedDeployConfig> => {
+    const { config, configFile, root } = await loadConfig(options.cwd, {
+        mode: BUILD_MODE,
+        configFile: options.configFile,
+    });
 
     if (config.deploy === undefined) {
         throw missingDeployError(config.applicationId, readPackageManifest(root));
     }
 
-    return resolveDeploySettings({ root, config, outDirOverride: options.outDir });
+    return { config, configFile, root, deploy: config.deploy };
+};
+
+const settingsFor = (plan: DeployPlan, options: DeployOptions, arch: DeployArchName): DeploySettings =>
+    resolveDeploySettings({
+        root: plan.loaded.root,
+        config: plan.loaded.config,
+        configFile: plan.loaded.configFile,
+        outDirOverride: options.outDir,
+        arch,
+    });
+
+const planDeploy = async (options: DeployOptions): Promise<DeployPlan> => {
+    const loaded = await loadDeployConfig(options);
+
+    return {
+        loaded,
+        targets: targetsFor(resolveTargetNames(options, loaded.deploy)),
+        arches: archesFor(resolveArchNames(options, loaded.deploy)),
+        project: resolveCatalogProject(loaded.root, loaded.config.applicationId),
+    };
 };
 
 const synchronizeMetadataCatalogs = async (
@@ -318,41 +431,57 @@ const synchronizeMetadataCatalogs = async (
     }
 };
 
-const buildPayload = async (
-    options: DeployOptions,
-    settings: DeploySettings,
-    targets: DeployTarget[],
-    project: CatalogProject | null,
-): Promise<DeployPayload> => {
+const buildApplication = async ({
+    options,
+    plan,
+    settings,
+    buildOutDir,
+}: BuildApplicationRequest): Promise<StagedMetadata> => {
     const templates = renderMetadata(settings);
 
-    if (!options.shouldSkipBuild) {
-        info(`Building ${options.entry}`);
-
-        await buildApp({
-            entry: options.entry,
-            vite: { root: options.cwd },
-        });
+    if (buildOutDir === null) {
+        if (plan.project !== null) {
+            compileCatalogs(plan.project, join(settings.paths.dist, LOCALE_DIRNAME));
+        }
 
-        await synchronizeMetadataCatalogs(settings, templates, project);
-    } else if (project !== null) {
-        compileCatalogs(project, join(settings.paths.dist, LOCALE_DIRNAME));
+        return localizeMetadata(templates, plan.project);
     }
 
-    const metadata = localizeMetadata(templates, project);
-    validateMetadata(settings, metadata, isFlathubSubmission(settings, targets));
-    const buildManifest = readBuildManifest(settings);
+    info(`Building ${options.entry}`);
+    using preparedOutput = prepareBuildOutDir(settings.paths.root, buildOutDir);
+
+    await buildApp({
+        entry: options.entry,
+        configFile: options.configFile,
+        vite: { root: options.cwd, build: { outDir: preparedOutput.path, emptyOutDir: false } },
+    });
+
+    preparedOutput.commit();
+    await synchronizeMetadataCatalogs(settings, templates, plan.project);
+
+    return localizeMetadata(templates, plan.project);
+};
+
+const buildArchPayload = async ({
+    options,
+    plan,
+    settings,
+    metadata,
+}: BuildPayloadRequest): Promise<DeployPayload> => {
+    validateMetadata(settings, metadata, isFlathubSubmission(settings, plan.targets));
+    const buildManifest = readBuildManifest(settings, plan.loaded);
 
     const builtSettings: DeploySettings = {
         ...settings,
         paths: { ...settings.paths, schemaFiles: buildManifest.schemaFiles },
     };
 
-    const node = options.shouldPrintManifests || !isNodeRequired(targets, builtSettings)
+    const node = options.shouldPrintManifests || !isNodeRequired(plan.targets, builtSettings)
         ? null
         : await resolveNodeRuntime(builtSettings);
 
-    const stage = stagePayload({ settings: builtSettings, node, metadata });
+    const addon = await resolveStagedAddon(builtSettings);
+    const stage = stagePayload({ settings: builtSettings, node, addon, metadata });
     info(`Staged ${String(stage.length)} files into ${displayPath(builtSettings, builtSettings.paths.stage)}`);
     const notices = collectNotices({ settings: builtSettings, node, packages: buildManifest.packages });
 
@@ -404,50 +533,76 @@ const packTargets = async (
     return artifacts;
 };
 
-const announce = (settings: DeploySettings, targets: DeployTarget[]): void => {
-    const names = targets.map((target) => target.name).join(", ");
+const announce = (settings: DeploySettings, plan: DeployPlan): void => {
+    const names = plan.targets.map((target) => target.name).join(", ");
     const version = `${settings.versions.packageVersion}-${settings.versions.debRevision}`;
-    info(`Deploying ${settings.name} ${version} as ${settings.binaryName} (${settings.arch.rpm}) to ${names}`);
+    const arches = plan.arches.join(", ");
+    info(`Deploying ${settings.name} ${version} as ${settings.binaryName} (${arches}) to ${names}`);
 };
 
-const runDeploy = async (options: DeployOptions): Promise<void> => {
-    let settings = await loadSettings(options);
-    let project = resolveCatalogProject(settings.paths.root, settings.applicationId);
-    let targets = targetsFor(resolveTargetNames(options, settings));
-    announce(settings, targets);
+const deployArch = async (request: ArchRunRequest): Promise<DeployArtifact[]> => {
+    const { options, plan, arch, metadata } = request;
+    const settings = settingsFor(plan, options, arch);
+    const payload = await buildArchPayload({ options, plan, settings, metadata });
+    const rendered = renderTargetManifests(plan.targets, payload);
 
-    preflight({
-        targets,
-        settings,
-        project,
-        shouldPrintManifests: options.shouldPrintManifests,
-        shouldSkipBuild: options.shouldSkipBuild,
-    });
+    if (options.shouldPrintManifests) {
+        const count = rendered.values().toArray().flat().length;
+        info(`Wrote ${String(count)} manifests for ${arch}, 0 packages built`);
+
+        return [];
+    }
 
-    if (!options.shouldSkipBuild) {
-        await ensureGenerated(options.cwd, {
-            shouldAnnounce: true,
-            mode: BUILD_MODE,
-        });
+    return await packTargets(rendered, payload);
+};
 
-        settings = await loadSettings(options);
-        project = resolveCatalogProject(settings.paths.root, settings.applicationId);
-        targets = targetsFor(resolveTargetNames(options, settings));
+const regenerate = async (options: DeployOptions, plan: DeployPlan): Promise<DeployPlan> => {
+    if (options.shouldSkipBuild) {
+        return plan;
     }
 
-    const payload = await buildPayload(options, settings, targets, project);
-    const rendered = renderTargetManifests(targets, payload);
+    await ensureGenerated(options.cwd, {
+        shouldAnnounce: true,
+        mode: BUILD_MODE,
+        configFile: options.configFile,
+    });
+
+    return await planDeploy(options);
+};
 
+const finish = (options: DeployOptions, settings: DeploySettings, artifacts: DeployArtifact[]): void => {
     if (options.shouldPrintManifests) {
-        const count = rendered.values().toArray().flat().length;
-        info(`Wrote ${String(count)} manifests, 0 packages built`);
-
         return;
     }
 
-    const artifacts = await packTargets(rendered, payload);
     const output = displayPath(settings, settings.paths.output);
     info(`Deploy complete: ${String(artifacts.length)} artifacts in ${output}`);
 };
 
+const runDeploy = async (options: DeployOptions): Promise<void> => {
+    const planned = await planDeploy(options);
+    assertCrossBuild(planned);
+    announce(settingsFor(planned, options, planned.arches[0]), planned);
+
+    preflight({
+        plan: planned,
+        settings: settingsFor(planned, options, planned.arches[0]),
+        shouldPrintManifests: options.shouldPrintManifests,
+        shouldSkipBuild: options.shouldSkipBuild,
+    });
+
+    const plan = await regenerate(options, planned);
+    const settings = settingsFor(plan, options, plan.arches[0]);
+    const buildOutDir = options.shouldSkipBuild ? null : resolveBuildOutDir(settings.paths.root, settings.paths.dist);
+    prepareDeployOutDir(settings.paths.root, settings.paths.outDir);
+    const metadata = await buildApplication({ options, plan, settings, buildOutDir });
+    const artifacts: DeployArtifact[] = [];
+
+    for (const arch of plan.arches) {
+        artifacts.push(...await deployArch({ options, plan, arch, metadata }));
+    }
+
+    finish(options, settings, artifacts);
+};
+
 export { runDeploy };

package/src/deploy/settings/arch.ts

@@ -1,18 +1,50 @@
-import type { DeployArch } from "../types.js";
+import { sortStrings } from "@gtkx/utils";
+import type { DeployArch, DeployArchName } from "../types.js";
 
-const ARCH_TABLE: Record<string, DeployArch> = {
+const EM_X86_64 = 62;
+const EM_AARCH64 = 183;
+
+const ARCH_TABLE: Record<DeployArchName, DeployArch> = {
     arm64: { deb: "arm64", rpm: "aarch64", flatpak: "aarch64", appimage: "aarch64", node: "arm64" },
     x64: { deb: "amd64", rpm: "x86_64", flatpak: "x86_64", appimage: "x86_64", node: "x64" },
 };
 
-const resolveArch = (arch: string = process.arch): DeployArch => {
-    const resolved = ARCH_TABLE[arch];
+const ELF_MACHINE_TABLE: Record<DeployArchName, number> = {
+    arm64: EM_AARCH64,
+    x64: EM_X86_64,
+};
+
+const KNOWN_ARCH_NAMES = sortStrings(Object.keys(ARCH_TABLE)).join(", ");
+
+const isArchName = (name: string): name is DeployArchName => Object.hasOwn(ARCH_TABLE, name);
+
+const assertKnownArch = (name: string): DeployArchName => {
+    if (!isArchName(name)) {
+        throw new Error(`Cannot deploy for ${name}: only ${KNOWN_ARCH_NAMES} are supported`);
+    }
+
+    return name;
+};
+
+const resolveArch = (name: DeployArchName): DeployArch => ARCH_TABLE[name];
+
+const hostArchName = (): DeployArchName => assertKnownArch(process.arch);
+
+const isHostArch = (name: DeployArchName): boolean => name === hostArchName();
+
+const elfMachineFor = (name: DeployArchName): number => ELF_MACHINE_TABLE[name];
+
+const parseArchList = (value: string): string[] => value.split(",").map((name) => name.trim()).filter(Boolean);
+
+const archesFor = (names: string[]): [DeployArchName, ...DeployArchName[]] => {
+    const requested = sortStrings(new Set(names.map((name) => assertKnownArch(name.trim()))));
+    const [first, ...rest] = requested.map((name) => assertKnownArch(name));
 
-    if (resolved === undefined) {
-        throw new Error(`Cannot deploy for ${arch}: only ${Object.keys(ARCH_TABLE).join(" and ")} are supported`);
+    if (first === undefined) {
+        throw new Error(`Cannot deploy without an architecture; choose from ${KNOWN_ARCH_NAMES}`);
     }
 
-    return resolved;
+    return [first, ...rest];
 };
 
-export { resolveArch };
+export { archesFor, elfMachineFor, hostArchName, isHostArch, KNOWN_ARCH_NAMES, parseArchList, resolveArch };

package/src/deploy/settings/build-manifest.ts

@@ -1,12 +1,14 @@
-import { isRecord, sortStrings } from "@gtkx/utils";
+import type { Config } from "@gtkx/config";
+import { isPathInside, isRecord, sortStrings, toPosixPath } from "@gtkx/utils";
 import { existsSync, readFileSync, statSync } from "node:fs";
-import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { isAbsolute, join, relative, resolve } from "node:path";
 import type { DeploySettings } from "../types.js";
 import {
     BUILD_MANIFEST_FILENAME,
     BUILD_MANIFEST_FORMAT_VERSION,
     BUILD_MANIFEST_GENERATOR,
     type BuildManifest,
+    configDigest,
     type RecordedPackage,
 } from "../../internal/build-manifest.js";
 import {
@@ -20,6 +22,11 @@ type ResolvedBuildManifest = {
     schemaFiles: string[];
 };
 
+type ExpectedBuildConfig = {
+    config: Config;
+    configFile: string;
+};
+
 const invalidManifest = (path: string): Error =>
     new Error(`Cannot deploy: ${path} is not a valid GTKX build manifest. Run \`gtkx build\` again.`);
 
@@ -51,6 +58,8 @@ const parseBuildManifest = (value: unknown, path: string): BuildManifest => {
         !isRecord(value) ||
         value.generator !== BUILD_MANIFEST_GENERATOR ||
         value.formatVersion !== BUILD_MANIFEST_FORMAT_VERSION ||
+        typeof value.configFile !== "string" ||
+        typeof value.configDigest !== "string" ||
         !Array.isArray(value.schemas) ||
         !Array.isArray(value.packages)
     ) {
@@ -62,24 +71,14 @@ const parseBuildManifest = (value: unknown, path: string): BuildManifest => {
     return {
         generator: BUILD_MANIFEST_GENERATOR,
         formatVersion: BUILD_MANIFEST_FORMAT_VERSION,
+        configFile: value.configFile,
+        configDigest: value.configDigest,
         schemas: recordedSchemas(value.schemas, path),
         packages: packages.map((entry) => recordedPackage(entry, path)),
     };
 };
 
-const isFile = (path: string): boolean => {
-    try {
-        return statSync(path, { throwIfNoEntry: false })?.isFile() === true;
-    } catch {
-        return false;
-    }
-};
-
-const isInsideProject = (root: string, filePath: string): boolean => {
-    const rel = relative(root, filePath);
-
-    return rel.length > 0 && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
-};
+const isFile = (path: string): boolean => statSync(path, { throwIfNoEntry: false })?.isFile() === true;
 
 const resolveRecordedSchema = (root: string, manifestPath: string, entry: string): string => {
     if (isAbsolute(entry) || !entry.endsWith(SCHEMA_SUFFIX)) {
@@ -88,7 +87,7 @@ const resolveRecordedSchema = (root: string, manifestPath: string, entry: string
 
     const filePath = resolve(root, entry);
 
-    if (!isInsideProject(root, filePath)) {
+    if (!isPathInside(root, filePath)) {
         throw new Error(`Cannot deploy: ${manifestPath} records a GSettings schema outside the project.`);
     }
 
@@ -103,7 +102,20 @@ const resolveRecordedSchema = (root: string, manifestPath: string, entry: string
     return filePath;
 };
 
-const readBuildManifest = (settings: DeploySettings): ResolvedBuildManifest => {
+const assertBuildConfig = (
+    settings: DeploySettings,
+    manifestPath: string,
+    manifest: BuildManifest,
+    expected: ExpectedBuildConfig,
+): void => {
+    const expectedFile = toPosixPath(relative(settings.paths.root, expected.configFile));
+
+    if (manifest.configFile !== expectedFile || manifest.configDigest !== configDigest(expected.config)) {
+        throw new Error(`Cannot deploy: ${manifestPath} was built from a different GTKX configuration.`);
+    }
+};
+
+const readBuildManifest = (settings: DeploySettings, expected: ExpectedBuildConfig): ResolvedBuildManifest => {
     const manifestPath = join(settings.paths.dist, BUILD_MANIFEST_FILENAME);
 
     if (!existsSync(manifestPath)) {
@@ -112,6 +124,7 @@ const readBuildManifest = (settings: DeploySettings): ResolvedBuildManifest => {
 
     const parsed: unknown = JSON.parse(readFileSync(manifestPath, "utf8"));
     const manifest = parseBuildManifest(parsed, manifestPath);
+    assertBuildConfig(settings, manifestPath, manifest, expected);
     const files = manifest.schemas.map((entry) => resolveRecordedSchema(settings.paths.root, manifestPath, entry));
     const unique = sortStrings(new Set(files));
     assertUniqueSchemaBasenames(unique);

package/src/deploy/settings/extra-files.ts

@@ -1,3 +1,5 @@
+import { statSync } from "node:fs";
+import { normalize, resolve } from "node:path";
 import type { DeployConfig, DeployExtraFile } from "../types.js";
 
 type ExtraFiles = NonNullable<DeployConfig["extraFiles"]>;
@@ -5,17 +7,41 @@ type ExtraFileEntry = NonNullable<ExtraFiles[string]>;
 
 const OCTAL_RADIX = 8;
 
+const assertSourceFile = (root: string, file: DeployExtraFile): void => {
+    const source = resolve(root, file.source);
+
+    try {
+        if (statSync(source).isFile()) {
+            return;
+        }
+    } catch {
+        throw new Error(`Cannot install "${file.destination}": its source file "${file.source}" does not exist`);
+    }
+
+    throw new Error(`Cannot install "${file.destination}": its source "${file.source}" is not a file`);
+};
+
 const resolveExtraFile = (destination: string, entry: ExtraFileEntry): DeployExtraFile => {
+    const normalizedDestination = normalize(destination);
+
     if (typeof entry === "string") {
-        return { destination, source: entry, mode: null };
+        return { destination: normalizedDestination, source: entry, mode: null };
     }
 
     const mode = entry.mode === undefined ? null : Number.parseInt(entry.mode, OCTAL_RADIX);
 
-    return { destination, source: entry.source, mode };
+    return { destination: normalizedDestination, source: entry.source, mode };
 };
 
-const resolveExtraFiles = (deploy: DeployConfig): DeployExtraFile[] =>
-    Object.entries(deploy.extraFiles ?? {}).map(([destination, entry]) => resolveExtraFile(destination, entry));
+const resolveExtraFiles = (root: string, deploy: DeployConfig): DeployExtraFile[] => {
+    const files = Object.entries(deploy.extraFiles ?? {})
+        .map(([destination, entry]) => resolveExtraFile(destination, entry));
+
+    for (const file of files) {
+        assertSourceFile(root, file);
+    }
+
+    return files;
+};
 
 export { resolveExtraFiles };